admin: activity history filters become a live-apply toolbar

the five-field form with its apply button is gone. one row holds a search-shaped domain field and a client ip field that debounce into the url with enter flushing at once, result segments and a time menu that commit instantly, and a clear that appears only when a filter is active without reflowing the row. presets freeze both absolute bounds at click time so a bookmark describes the same investigation later, custom ranges apply atomically through set range with inline validation, and echo queues keep in-flight commits from clobbering newer typing or newer picks. live mode renders no toolbar, the availability banner became a footer note, previous rows stay visible during refetch, and every control carries a 44px hit target.

CHANGELOG.md

@@ -4,7 +4,42 @@ 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.11] - 2026-08-24
+## [0.0.14] - 2026-08-28
+
+Schema changes stop costing you your query history. querylog.db is now version-stamped and migrated in place; the server refuses to start rather than ever reset a healthy file, and the release tooling refuses to ship a schema change that is neither migratable nor explicitly disclosed with recovery steps. Three releases (0.0.6, 0.0.9, 0.0.12) each discarded the log on upgrade; this ends that.
+
+### Changed
+
+- **querylog.db is migrated in place.** The file now carries a schema version, and a release that changes the schema ships a migration that runs at startup: one consistent backup (`querylog.db.pre-migrate-<timestamp>`, mode 0600, only the most recent kept), then every step and the version stamp in a single transaction. A failure before the commit rolls back and leaves your file exactly as it was.
+- **The server refuses instead of resetting.** A querylog.db it cannot use — newer than the binary, older than 0.0.12, or mid-migration failure — is left untouched and the server exits with a clear message instead of setting the file aside and starting an empty log. The exit code (2) tells systemd not to restart-loop a deliberate refusal. Corruption is the only case that still sets a file aside automatically.
+- **The release gate now enforces the contract.** A schema change cannot be tagged unless it either ships a working migration (proven in CI against a frozen fixture of the previous schema, with shipped migration files locked byte-for-byte once released) or explicitly declares a break — which requires a version bump the server refuses on, a reset disclosure, and step-by-step restore instructions in this file.
+
+**One hazard to know when downgrading.** The first start under this release restamps querylog.db from the old fingerprint to version 1 (contents untouched). If you later downgrade to 0.0.13 or older, that binary treats the new stamp as a schema mismatch, moves your file aside as `querylog.db.schema-changed-<timestamp>`, and starts an empty log. To recover: return to 0.0.14 or newer, stop the server, move the empty `querylog.db` away and delete its `querylog.db-wal` and `querylog.db-shm` files (leaving them would corrupt the restored file), rename the `.schema-changed-<timestamp>` file back to `querylog.db`, and start.
+
+## [0.0.13] - 2026-08-27
+
+The upstream query budget becomes one honest deadline. A busy network no longer blames a healthy standby for running out of time, and a query burst no longer queues invisibly until everything answers SERVFAIL at once.
+
+### Fixed
+
+- **The per-query upstream budget is now one absolute deadline, spent by everything that blocks.** Waiting for a free slot on a saturated upstream now spends the query's `upstream.total_timeout_ms` budget just like the exchange itself, instead of being invisible to it — under a burst, queries used to wait out their whole budget in the queue and then start attempts they could never finish. An attempt near the end of the budget runs truncated, and when a truncated attempt runs out of time that is evidence about the budget, not the upstream: it no longer counts against that upstream's health or success rate, and the query log no longer names an upstream that was given no fair chance. A field incident produced 279 rows blaming a standby whose health counters read zero for zero; those rows now attribute nothing.
+- **A query no longer blocks behind a saturated upstream while another has capacity.** Admission sweeps the upstreams in priority order and takes the first free slot; priority now means the order among upstreams that can be admitted right now, and a query blocks only when nothing has capacity — on the highest-priority eligible upstream, bounded by the remaining budget.
+- **Conditional forward zones spend `upstream.read_timeout_ms` once per query.** A UDP attempt, a truncated answer and the TCP retry now share the one budget instead of taking a fresh one each, so a slow zone resolver can no longer stretch a single query to several times the configured timeout.
+
+### Added
+
+- **`nxdns_upstream_budget_exhausted_total`.** A pool-wide counter of queries whose budget ran out — in the queue or mid-attempt — before any upstream answered. It carries no per-upstream label on purpose: running out of budget is a fact about the pool.
+- **A configuration with more than 64 enabled upstreams is rejected at validation** with a clear message, instead of tripping an internal limit at startup.
+
+## [0.0.12] - 2026-08-27
+
+Overview stops re-reading the whole query log. One endpoint, one snapshot, pre-aggregated buckets — a 30-day view now costs the same on a month of history as on a day of it. Read the upgrade note first: it resets your query history.
+
+### Changed
+
+- **Upgrading resets your query history.** The query-log schema gains the aggregate tables described below, and `querylog.db` is never migrated: the first start after the upgrade sets the old file aside (kept on disk next to the new one, named with the reason) and begins a fresh log. Settings, groups, blocklists and every other configuration are untouched.
+- **The Overview is served by one endpoint, `GET /api/overview`.** It replaces `GET /api/stats`, `/api/stats/timeseries`, `/api/stats/types`, `/api/stats/routes` and `/api/stats/clients`, which are gone. The five panels now come from a single database snapshot, so they can no longer disagree with each other, and the page shows one loading and one error state instead of five.
+- **Query statistics are pre-aggregated as they are written.** The query log now maintains 30-minute aggregate tables in the same transaction that stores the rows, and the 24-hour, 7-day and 30-day views read those instead of scanning every logged query. The cost of opening the Overview no longer grows with the size of the log: measured at three million rows, the 30-day view went from roughly eight-tenths of a second of scanning to under fifty milliseconds, at the price of about ten percent on each background write batch and ~1.5 MB of disk. The server also keeps the most recent response per period in memory and serves repeat polls from it while nothing has changed — until new queries land, retention prunes, or the period's time window rolls forward — so on a quiet network most of the steady 30-second refreshes do no database work at all.
 
 The Overview charts move to visx and grow up: one hover treatment across all four, honest labels, and maintained d3 math under the app's own rendering.
 

PLAN.md

@@ -85,13 +85,13 @@ Verified: 0.16.0 ships `std.crypto.tls.Client` only. There is no server-side TLS
 Two SQLite files with opposite write profiles, isolated from each other:
 
 - **`config.db`** — small, precious, rarely written: groups, clients, prefixes, upstreams, blocklist source metadata, rules, local records, forward zones, settings, schema version.
-- **`querylog.db`** — high-churn, large, expendable: query log + its own private `domains` dimension table. Client identity stored as **IP text**, not a FK into config — log rows are immutable facts and must not point at mutable config rows. If `querylog.db` is missing or corrupt at startup, rename aside, recreate, keep serving. Log loss is not an outage.
+- **`querylog.db`** — high-churn, large, expendable: query log + its own private `domains` dimension table. Client identity stored as **IP text**, not a FK into config — log rows are immutable facts and must not point at mutable config rows. If `querylog.db` is missing or corrupt at startup, rename aside, recreate, keep serving — corruption only; a healthy file whose schema this build cannot use refuses the startup instead (§3.7).
 - No cross-DB references. Retention/VACUUM churn never touches `config.db`; config backup is a copy of a tiny file.
 
 ### 3.7 Upgrades: Auto-Migration (Decision J)
 
 - `config.db`: numbered, sequential SQL migration steps compiled into the binary. At startup: read schema version row, apply newer steps inside a transaction, continue. Operator upgrade = install binary, restart. Before v0.1 the list holds one step — the baseline of §11.2, edited in place — because nxdns has no installs and a step exists only to reconcile a database somebody already has.
-- `querylog.db`: **no migrations.** On schema mismatch: rename aside, recreate fresh.
+- `querylog.db`: a logical version in `PRAGMA user_version`, migrated **in place** at startup by the same shape of compiled step list, inside one transaction and behind one `querylog.db.pre-migrate-<epoch>` backup (only the newest is kept). A healthy file is never renamed aside: a version this build cannot reach refuses the startup with instructions, and only corruption recreates. A deliberate break is still allowed, but it must be versioned, refused at startup, and disclosed in the changelog — the cut gate enforces that. See `docs/reference/query-log-lifecycle.md`.
 
 ### 3.8 Blocklist Storage (Decision A)
 
@@ -238,7 +238,7 @@ src/
   web/
     server.zig  router.zig  auth.zig  sse.zig  static.zig  metrics.zig  openapi.zig
     handlers/
-      auth.zig  stats.zig  queries.zig  clients.zig  groups.zig  blocklists.zig
+      auth.zig  overview.zig  queries.zig  clients.zig  groups.zig  blocklists.zig
       rules.zig  local.zig  lookup.zig  pause.zig  settings.zig
       upstream_health.zig  certs.zig  health.zig  version.zig
 
@@ -484,6 +484,8 @@ CREATE INDEX idx_query_log_client ON query_log(client_ip);
 CREATE INDEX idx_query_log_domain ON query_log(domain_id);
 ```
 
+The sketch above is the original shape; `src/storage/querylog_schema.zig` is the authority, and the provenance columns milestone 28 added are not repeated here. Beside the raw rows the file carries four projection tables — `bucket_totals`, `bucket_clients`, `bucket_types`, `bucket_routes` — on a 30-minute grain, which is what `GET /api/overview` reads for the 24h, 7d and 30d windows instead of scanning every row. They are maintained by the batch writer and by retention inside the same transaction as the raw rows, so SQLite's transaction is the whole coherence story: no second file, no backfill, no rebuild command. The 1h window is narrower than the grain and takes one raw scan.
+
 ### 11.4 Query Logger
 
 - In-memory buffer, mutex guarded, hard cap `query_log_buffer_max` (default 10000).
@@ -493,7 +495,7 @@ CREATE INDEX idx_query_log_domain ON query_log(domain_id);
 
 ### 11.5 Retention
 
-Periodic delete of rows older than `retention_days`; scheduled checkpoint/VACUUM on `querylog.db` only.
+Periodic delete of rows older than `retention_days`, dropping the projection buckets behind the cutoff and recomputing the straddling one in the same transaction; scheduled checkpoint/VACUUM on `querylog.db` only.
 
 ### 11.6 Disk Discipline (cloudflared lesson)
 
@@ -536,7 +538,7 @@ Scalars in `settings(key, value)`; ordered/structured items in dedicated tables.
 ### 13.1 Endpoints
 
 - `POST /api/auth/login`, `POST /api/auth/logout`
-- `GET /api/stats?period=…`, `GET /api/stats/timeseries?period=…`, `GET /api/stats/types?period=…`, `GET /api/stats/routes?period=…`, `GET /api/stats/clients?period=…`
+- `GET /api/overview?period=…` — every Overview panel in one response over one read transaction
 - `GET /api/queries` (filter + paginate), `GET /api/queries/live` (SSE, per-IP cap)
 - `GET/PUT /api/clients/{id}`
 - `GET/POST/PUT/DELETE /api/groups…`, `/api/blocklists…`, `/api/rules…`, `/api/local-records…`, `/api/forward-zones…`
@@ -664,7 +666,7 @@ The project publishes released binaries and container images from its own Gitea
 6. Disk-fill degrades gracefully; no silent log-flood failure mode.
 7. Web UI + API provide full admin functionality; OpenAPI contract tests green.
 8. `nxdns export` round-trips via `nxdns import`.
-9. Query logging, stats, SSE live stream work; querylog.db corruption self-heals.
+9. Query logging, the overview, SSE live stream work; querylog.db corruption self-heals.
 10. Local DoH + DoT endpoints serve LAN clients.
 11. Schema upgrade = install + restart (migration test proves it).
 12. All suites green in Gitea CI for both targets.
@@ -692,5 +694,5 @@ The project publishes released binaries and container images from its own Gitea
 | G | SQLite vendored amalgamation + own thin wrapper |
 | H | Two DBs: `config.db` (precious) + `querylog.db` (expendable, self-contained, client IP as text) |
 | I | Frontend embedded in binary; dev flag serves from disk; static musl release builds |
-| J | Auto-migration for `config.db` at startup; `querylog.db` recreated on mismatch |
+| J | Auto-migration at startup for both databases; `querylog.db` recreated only when corrupt |
 | — | Safe-search per-group; Prometheus `/metrics` in scope; CI on self-hosted Gitea Actions |

admin/scripts/assert-bundle-size.mjs

@@ -14,7 +14,7 @@ import { readdirSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const BUDGET_BYTES = 800_000;
+const BUDGET_BYTES = 850_000;
 
 const distDir = join(dirname(dirname(fileURLToPath(import.meta.url))), "dist", "assets");
 

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

@@ -1,4 +1,4 @@
-import { cleanup, render, screen, waitFor, within } from "@testing-library/react";
+import { render, screen, waitFor, within } from "@testing-library/react";
 import { QueryClientProvider } from "@tanstack/react-query";
 import { RouterProvider, createMemoryHistory } from "@tanstack/react-router";
 import { AuthProvider } from "@/auth/store";
@@ -313,16 +313,17 @@ test("a row retention has pruned explains the 404 and keeps the way back to the
 	});
 });
 
-/**
+/** The related-actions region of a query detail. */
- * The related-actions region of a query detail. Scoped on purpose: the sidebar
- * carries a Pause of its own, and this is the one that answers "this query was
- * blocked and should not have been".
- */
 function related(): HTMLElement {
 	return screen.getByRole("region", { name: "Related" });
 }
 
-test("a blocked query's Related offers Pause; an allowed one has nothing to pause about", async () => {
+/**
+ * Related is links only. Pause is a resolver-wide control and lives in the
+ * sidebar alone, so a blocked query — the case that used to carry one here —
+ * offers no button of any kind.
+ */
+test("Related carries its four links and no control, blocked query or not", async () => {
 	responses["/api/queries/50"] = detail(50, {
 		policy: { action: "block", reason: "blocklist_domain", matched: "ads.example" },
 		route: { kind: "blocked", upstream: "" },
@@ -330,25 +331,12 @@ test("a blocked query's Related offers Pause; an allowed one has nothing to paus
 	renderDetail(50);
 
 	await screen.findByRole("heading", { name: "example.com" });
-	await waitFor(() => expect(within(related()).getByRole("button", { name: "Pause" })).toBeTruthy());
+	await waitFor(() => expect(within(related()).getByText("Diagnostics around this query")).toBeTruthy());
-
+	expect(within(related()).getAllByRole("link").map((link) => link.textContent)).toEqual([
-	cleanup();
+		"Test this domain against current policy",
-	responses["/api/queries/51"] = detail(51, { policy: { action: "allow", reason: "no_match", matched: "" } });
+		"All activity for this domain",
-	renderDetail(51);
+		"All activity from this client",
-
+		"Diagnostics around this query",
-	await screen.findByRole("heading", { name: "example.com" });
+	]);
-	expect(within(related()).queryByRole("button", { name: "Pause" })).toBeNull();
+	expect(within(related()).queryByRole("button")).toBeNull();
-});
-
-test("the Pause action stays away while protection is unavailable", async () => {
-	responses["/api/health"] = health({ protection: { state: "unavailable", until: null } });
-	responses["/api/queries/52"] = detail(52, {
-		policy: { action: "block", reason: "blocklist_domain", matched: "ads.example" },
-		route: { kind: "blocked", upstream: "" },
-	});
-	renderDetail(52);
-
-	await screen.findByRole("heading", { name: "example.com" });
-	await waitFor(() => expect(screen.getByText("Diagnostics around this query")).toBeTruthy());
-	expect(within(related()).queryByRole("button", { name: "Pause" })).toBeNull();
 });

admin/src/features/activity/ActivityDetailPage.tsx

@@ -73,9 +73,7 @@ export default function ActivityDetailPage() {
 						domain={domain}
 						client={client}
 						ts={time}
-						origin={origin}
+						origin={origin} />
-						blocked={detail.policy.action === "block"}
-					/>
 				}
 			/>
 		</section>

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

@@ -0,0 +1,393 @@
+/**
+ * The filter toolbar on its own: the controls that decide what reaches the URL,
+ * driven through a harness that plays the part the page plays.
+ *
+ * The timezone is fixed because the only invalid bound reachable in jsdom is a
+ * wall-clock time inside a spring-forward gap: jsdom applies the
+ * `datetime-local` value sanitization algorithm, so text that is merely
+ * incomplete never reaches the component at all — the input hands it back as
+ * the empty string, which is a bound the operator cleared.
+ */
+
+import { useCallback, useState } from "react";
+import { afterAll, expect, test, vi } from "vitest";
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import ActivityFilters, { NO_FILTERS, type AppliedFilters } from "./ActivityFilters";
+import { unixToDatetimeLocal } from "./datetime";
+
+vi.stubEnv("TZ", "Europe/Paris");
+afterAll(() => vi.unstubAllEnvs());
+
+/** 02:30 does not exist on this date in Paris; the clock jumps 02:00 to 03:00. */
+const GAP_WALL_TIME = "2026-03-29T02:30:00";
+
+/** The text of the elements an input points at with `aria-describedby`. */
+function describedText(input: HTMLElement): string {
+	const ids = input.getAttribute("aria-describedby");
+	if (ids === null) throw new Error("input has no aria-describedby");
+	return ids
+		.split(/\s+/)
+		.map((id) => {
+			const node = document.getElementById(id);
+			if (node === null) throw new Error(`aria-describedby names missing element ${id}`);
+			return node.textContent ?? "";
+		})
+		.join(" ");
+}
+
+/**
+ * The page's half of the contract: the applied state is held outside the form.
+ *
+ * `deferred` holds the patches back instead of applying them, so a test can
+ * land them in an order the network and the router can genuinely produce —
+ * an early debounce arriving after a later one, over a draft that has moved on.
+ */
+function renderFilters(initial: AppliedFilters = NO_FILTERS, deferred = false) {
+	const patches: Array<Partial<AppliedFilters>> = [];
+	const state: { current: AppliedFilters } = { current: initial };
+	const setter: { current: ((next: AppliedFilters) => void) | null } = { current: null };
+
+	function Harness() {
+		const [applied, setApplied] = useState(initial);
+		state.current = applied;
+		setter.current = setApplied;
+		const onApply = useCallback((patch: Partial<AppliedFilters>) => {
+			patches.push(patch);
+			if (!deferred) setApplied((prev) => ({ ...prev, ...patch }));
+		}, []);
+		const onClear = useCallback(() => {
+			patches.push({});
+			if (!deferred) setApplied(NO_FILTERS);
+		}, []);
+		return <ActivityFilters applied={applied} onApply={onApply} onClear={onClear} />;
+	}
+
+	render(<Harness />);
+	/** The URL moving under the form: a commit landing, or the back button. */
+	function land(next: AppliedFilters) {
+		act(() => setter.current!(next));
+	}
+	return { patches, state, land };
+}
+
+function openTimeMenu() {
+	fireEvent.click(screen.getByRole("button", { name: /^Time: / }));
+}
+
+test("the segments commit to the applied state on the click, with no button in between", () => {
+	const { patches, state } = renderFilters();
+	expect(
+		screen.getAllByRole("radio").map((radio) => radio.closest("label")?.textContent),
+	).toEqual(["Any", "Blocked", "Allowed"]);
+
+	fireEvent.click(screen.getByRole("radio", { name: "Blocked" }));
+	expect(patches).toEqual([{ blocked: true }]);
+	expect(state.current.blocked).toBe(true);
+
+	fireEvent.click(screen.getByRole("radio", { name: "Allowed" }));
+	expect(state.current.blocked).toBe(false);
+
+	fireEvent.click(screen.getByRole("radio", { name: "Any" }));
+	expect(state.current.blocked).toBeUndefined();
+});
+
+test("a time preset writes an absolute second, and the trigger names the preset", () => {
+	const now = 1_800_000_000_000;
+	vi.spyOn(Date, "now").mockReturnValue(now);
+	const { patches } = renderFilters();
+
+	openTimeMenu();
+	expect(screen.getAllByRole("menuitem").map((item) => item.textContent)).toEqual([
+		"Any time",
+		"Past hour",
+		"Past 24 hours",
+		"Past 7 days",
+		"Custom…",
+	]);
+
+	fireEvent.click(screen.getByRole("menuitem", { name: "Past 24 hours" }));
+
+	// Both bounds, concrete: an open upper bound would keep taking in queries
+	// logged after the reader stopped looking, so the same link tomorrow would
+	// name a different day.
+	expect(patches).toEqual([{ since: now / 1000 - 86_400, until: now / 1000 }]);
+	expect(screen.getByRole("button", { name: "Time: Past 24 hours" })).toBeTruthy();
+
+	// A clock that has moved on does not move the label: the URL still holds the
+	// second the click resolved to.
+	vi.spyOn(Date, "now").mockReturnValue(now + 60_000);
+	fireEvent.click(screen.getByRole("radio", { name: "Blocked" }));
+	expect(screen.getByRole("button", { name: "Time: Past 24 hours" })).toBeTruthy();
+
+	vi.restoreAllMocks();
+});
+
+test("bounds nobody picked here read as Custom, and Any time clears both", () => {
+	const { patches } = renderFilters({ ...NO_FILTERS, since: 1_700_000_000, until: 1_700_000_600 });
+	expect(screen.getByRole("button", { name: "Time: Custom" })).toBeTruthy();
+
+	openTimeMenu();
+	fireEvent.click(screen.getByRole("menuitem", { name: "Any time" }));
+
+	expect(patches).toEqual([{ since: undefined, until: undefined }]);
+	expect(screen.getByRole("button", { name: "Time: Any time" })).toBeTruthy();
+});
+
+test("the custom range applies only through Set range, and Enter is Set range", () => {
+	const { patches } = renderFilters();
+	openTimeMenu();
+	fireEvent.click(screen.getByRole("menuitem", { name: "Custom…" }));
+
+	const since = screen.getByLabelText("Since") as HTMLInputElement;
+	fireEvent.change(since, { target: { value: "2026-03-29T04:30:00" } });
+	// Typing a bound is not applying it: the other half may still be half-typed.
+	expect(patches).toEqual([]);
+
+	const applied = { since: Math.floor(new Date("2026-03-29T04:30:00").getTime() / 1000), until: undefined };
+	fireEvent.click(screen.getByRole("button", { name: "Set range" }));
+	expect(patches).toEqual([applied]);
+
+	// Enter inside a bound is that bound's action, not the toolbar's submit: the
+	// outer form flushes the text filters and would apply neither half of this.
+	fireEvent.change(since, { target: { value: "2026-03-29T05:30:00" } });
+	fireEvent.keyDown(since, { key: "Enter" });
+	expect(patches).toHaveLength(2);
+	expect(patches[1]).toEqual({
+		since: Math.floor(new Date("2026-03-29T05:30:00").getTime() / 1000),
+		until: undefined,
+	});
+});
+
+test("a rejected bound marks its own input and describes it", () => {
+	const { patches } = renderFilters();
+	openTimeMenu();
+	fireEvent.click(screen.getByRole("menuitem", { name: "Custom…" }));
+
+	const since = screen.getByLabelText("Since") as HTMLInputElement;
+	const until = screen.getByLabelText("Until") as HTMLInputElement;
+
+	fireEvent.change(since, { target: { value: GAP_WALL_TIME } });
+	fireEvent.click(screen.getByRole("button", { name: "Set range" }));
+
+	expect(since.getAttribute("aria-invalid")).toBe("true");
+	expect(describedText(since)).toContain("daylight saving");
+	// Refused means refused, and only the offending bound carries the mark.
+	expect(patches).toEqual([]);
+	expect(until.getAttribute("aria-invalid")).toBeNull();
+	expect(until.getAttribute("aria-describedby")).toBeNull();
+});
+
+test("an upper bound below the lower one is refused, against the bound that is wrong", () => {
+	const { patches } = renderFilters();
+	openTimeMenu();
+	fireEvent.click(screen.getByRole("menuitem", { name: "Custom…" }));
+
+	const since = screen.getByLabelText("Since") as HTMLInputElement;
+	const until = screen.getByLabelText("Until") as HTMLInputElement;
+	fireEvent.change(since, { target: { value: "2026-05-02T10:00:00" } });
+	fireEvent.change(until, { target: { value: "2026-05-02T09:00:00" } });
+	fireEvent.click(screen.getByRole("button", { name: "Set range" }));
+
+	expect(until.getAttribute("aria-invalid")).toBe("true");
+	expect(describedText(until)).toContain("selects nothing");
+	expect(since.getAttribute("aria-invalid")).toBeNull();
+	expect(patches).toEqual([]);
+
+	// The window is half-open, so two equal bounds are as empty as an inverted
+	// pair and are refused the same way.
+	fireEvent.change(until, { target: { value: "2026-05-02T10:00:00" } });
+	fireEvent.click(screen.getByRole("button", { name: "Set range" }));
+	expect(until.getAttribute("aria-invalid")).toBe("true");
+	expect(patches).toEqual([]);
+
+	fireEvent.change(until, { target: { value: "2026-05-02T11:00:00" } });
+	fireEvent.click(screen.getByRole("button", { name: "Set range" }));
+	expect(until.getAttribute("aria-invalid")).toBeNull();
+	expect(patches).toHaveLength(1);
+});
+
+test("Clear keeps its place while there is nothing to clear, and stays out of the tab order", () => {
+	const { state } = renderFilters();
+	const clear = screen.getByText("Clear");
+	expect(clear.getAttribute("tabindex")).toBe("-1");
+	expect(clear.getAttribute("aria-hidden")).toBe("true");
+
+	fireEvent.click(screen.getByRole("radio", { name: "Blocked" }));
+
+	expect(clear.getAttribute("tabindex")).toBeNull();
+	expect(clear.getAttribute("aria-hidden")).toBeNull();
+
+	fireEvent.click(clear);
+	expect(state.current).toEqual(NO_FILTERS);
+	expect(clear.getAttribute("tabindex")).toBe("-1");
+});
+
+test("Clear empties the text drafts along with the applied filters", () => {
+	vi.useFakeTimers();
+	try {
+		const { state } = renderFilters();
+		const domain = screen.getByLabelText("Filter domains") as HTMLInputElement;
+		fireEvent.change(domain, { target: { value: "ads" } });
+		act(() => vi.advanceTimersByTime(400));
+		expect(state.current.domain).toBe("ads");
+
+		fireEvent.click(screen.getByRole("button", { name: "Clear" }));
+		act(() => vi.advanceTimersByTime(400));
+
+		expect(domain.value).toBe("");
+		expect(state.current).toEqual(NO_FILTERS);
+	} finally {
+		vi.useRealTimers();
+	}
+});
+
+test("the domain field is search-shaped, unspellchecked, and labelled without a visible label", () => {
+	renderFilters();
+	const domain = screen.getByLabelText("Filter domains") as HTMLInputElement;
+	expect(domain.type).toBe("search");
+	expect(domain.getAttribute("spellcheck")).toBe("false");
+	expect(domain.getAttribute("autocomplete")).toBe("off");
+	expect(domain.getAttribute("placeholder")).toBe("Filter domains…");
+	// The magnifier is decoration over the field, never a second thing to read.
+	expect(document.querySelector("svg[aria-hidden='true']")).toBeTruthy();
+});
+
+test("a bound change does not reset the domain draft that is still being typed", () => {
+	const now = 1_800_000_000_000;
+	vi.spyOn(Date, "now").mockReturnValue(now);
+	const { state } = renderFilters();
+
+	const domain = screen.getByLabelText("Filter domains") as HTMLInputElement;
+	fireEvent.change(domain, { target: { value: "ads" } });
+
+	// A preset commits at once, while the typed word is still waiting out its
+	// debounce. The URL moves, but not the part of it this field is derived from.
+	openTimeMenu();
+	fireEvent.click(screen.getByRole("menuitem", { name: "Past hour" }));
+
+	expect(state.current.since).toBe(now / 1000 - 3600);
+	expect(domain.value).toBe("ads");
+
+	vi.restoreAllMocks();
+});
+
+test("a debounced commit landing late does not roll the field back over newer typing", () => {
+	vi.useFakeTimers();
+	try {
+		const { patches, land } = renderFilters(NO_FILTERS, true);
+		const domain = screen.getByLabelText("Filter domains") as HTMLInputElement;
+
+		// Two commits in flight, and the reader is a keystroke ahead of both.
+		fireEvent.change(domain, { target: { value: "ad" } });
+		act(() => vi.advanceTimersByTime(400));
+		fireEvent.change(domain, { target: { value: "ads" } });
+		act(() => vi.advanceTimersByTime(400));
+		expect(patches).toEqual([
+			{ domain: "ad", client: undefined },
+			{ domain: "ads", client: undefined },
+		]);
+		fireEvent.change(domain, { target: { value: "adsx" } });
+
+		// The older one lands first. It is this toolbar's own echo, two keystrokes
+		// stale, and seeding the field from it would delete what was typed since.
+		land({ ...NO_FILTERS, domain: "ad" });
+		expect(domain.value).toBe("adsx");
+
+		land({ ...NO_FILTERS, domain: "ads" });
+		expect(domain.value).toBe("adsx");
+
+		// An address that was never sent from here is someone else's — a pasted
+		// link, or the back button — and that one does move the field.
+		land({ ...NO_FILTERS, domain: "elsewhere" });
+		expect(domain.value).toBe("elsewhere");
+	} finally {
+		vi.useRealTimers();
+	}
+});
+
+test("a window moved from outside re-opens the custom row over the bounds it arrived with", () => {
+	const now = 1_800_000_000_000;
+	vi.spyOn(Date, "now").mockReturnValue(now);
+	const { land } = renderFilters();
+
+	openTimeMenu();
+	fireEvent.click(screen.getByRole("menuitem", { name: "Past hour" }));
+	// A preset supersedes the custom row, so it is shut and the label is the preset.
+	expect(screen.queryByLabelText("Since")).toBeNull();
+	expect(screen.getByRole("button", { name: "Time: Past hour" })).toBeTruthy();
+
+	// The back button, or a pasted link: a range this form did not choose.
+	const since = 1_700_000_000;
+	land({ ...NO_FILTERS, since, until: since + 600 });
+
+	expect(screen.getByRole("button", { name: "Time: Custom" })).toBeTruthy();
+	// The label says Custom, so the fields it names have to be on screen holding
+	// that range — a Custom window with nothing to read is the label lying.
+	// jsdom's value sanitizer spells the milliseconds out, so the seeded text is
+	// the prefix rather than the whole of what the input holds.
+	expect((screen.getByLabelText("Since") as HTMLInputElement).value).toContain(
+		unixToDatetimeLocal(since),
+	);
+	expect((screen.getByLabelText("Until") as HTMLInputElement).value).toContain(
+		unixToDatetimeLocal(since + 600),
+	);
+
+	vi.restoreAllMocks();
+});
+
+test("a window moved from outside clears an error left over from the old one", () => {
+	const { land } = renderFilters();
+	openTimeMenu();
+	fireEvent.click(screen.getByRole("menuitem", { name: "Custom…" }));
+
+	const until = screen.getByLabelText("Until") as HTMLInputElement;
+	fireEvent.change(screen.getByLabelText("Since"), { target: { value: "2026-05-02T10:00:00" } });
+	fireEvent.change(until, { target: { value: "2026-05-02T09:00:00" } });
+	fireEvent.click(screen.getByRole("button", { name: "Set range" }));
+	expect(until.getAttribute("aria-invalid")).toBe("true");
+
+	const since = 1_700_000_000;
+	land({ ...NO_FILTERS, since, until: since + 600 });
+
+	// The bounds the message was about are gone, so the message is too.
+	expect((screen.getByLabelText("Until") as HTMLInputElement).getAttribute("aria-invalid")).toBeNull();
+	expect(screen.queryByRole("alert")).toBeNull();
+});
+
+test("the client field names the exact match it performs", () => {
+	renderFilters();
+	const client = screen.getByLabelText("Client IP (exact match)") as HTMLInputElement;
+	expect(client.getAttribute("placeholder")).toBe("Client IP…");
+});
+
+test("an earlier range commit landing late does not unseat the pick that is current", () => {
+	const first = 1_800_000_000_000;
+	vi.spyOn(Date, "now").mockReturnValue(first);
+	const { patches, land } = renderFilters(NO_FILTERS, true);
+
+	openTimeMenu();
+	fireEvent.click(screen.getByRole("menuitem", { name: "Past hour" }));
+
+	// A second pick before the first has come back through the URL.
+	const second = first + 60_000;
+	vi.spyOn(Date, "now").mockReturnValue(second);
+	openTimeMenu();
+	fireEvent.click(screen.getByRole("menuitem", { name: "Past 24 hours" }));
+
+	expect(patches).toEqual([
+		{ since: first / 1000 - 3600, until: first / 1000 },
+		{ since: second / 1000 - 86_400, until: second / 1000 },
+	]);
+
+	// The older window lands first. It is this toolbar's own echo, so it must not
+	// read as a range someone else chose: doing that would clear the preset and
+	// throw the custom row open over a window the reader has already moved past.
+	land({ ...NO_FILTERS, since: first / 1000 - 3600, until: first / 1000 });
+	expect(screen.queryByLabelText("Since")).toBeNull();
+
+	land({ ...NO_FILTERS, since: second / 1000 - 86_400, until: second / 1000 });
+	expect(screen.getByRole("button", { name: "Time: Past 24 hours" })).toBeTruthy();
+	expect(screen.queryByLabelText("Since")).toBeNull();
+
+	vi.restoreAllMocks();
+});

admin/src/features/activity/ActivityFilters.tsx

@@ -1,73 +1,198 @@
 /**
- * The filter row over the Activity table.
+ * The filter toolbar over the Activity history table.
  *
  * The applied state is the URL, never this form: what the reader sees is what
- * the link they can paste to a housemate will show. So this holds a draft only,
+ * the link they can paste to a housemate will show. So this holds a draft, and
- * and the page remounts it whenever the applied search changes — a back button
+ * every control writes through to the URL — the segments and the time presets
- * or a pasted URL has to move the form with it, and a form that seeded itself
+ * at once, the two text fields after a pause so a five-letter domain is one
- * once would keep showing the previous investigation's filters.
+ * navigation rather than five.
  *
- * In live mode the row stays visible and disabled rather than disappearing: the
+ * A time preset writes both bounds as absolute seconds, resolved once at the
- * filters are retained in the URL and apply again the moment history comes
+ * click. Neither half may be left open: a bookmark has to describe the same
- * back, and hiding them would read as having lost them. The stream itself is
+ * investigation tomorrow, and a window that slid overnight — or one that stayed
- * unfiltered — the server sends every query — so a row that looked usable here
+ * open at the top and swallowed everything logged since — would answer a
+ * different question under the same link.
+ *
+ * A URL can move under this form at any time, and the draft only follows the
+ * part of it that actually moved. A field is re-seeded when its own URL value
+ * changed and the new value is not one this toolbar just wrote: the debounce
+ * means the URL is always a little behind the keyboard, and a landing commit
+ * must not roll the input back over the letters typed since.
+ *
+ * The custom range is the one control that does not live-apply. Two half-typed
+ * timestamps are a normal intermediate state of typing one of them, and a lower
+ * bound at or above an upper bound selects nothing at all, so the pair is
+ * validated and applied together or not at all.
+ *
+ * Live mode does not render this at all — the page mounts it inside the History
+ * panel. The stream is unfiltered, and a row of controls that looked usable
  * would promise filtering that is not happening.
  */
 
-import { useState, type FormEvent } from "react";
+import { useCallback, useEffect, useState, type FormEvent, type KeyboardEvent } from "react";
 import * as stylex from "@stylexjs/stylex";
-import Select from "@/ui/Select";
+import { Button, Menu, MenuItem, MenuTrigger, Popover, Radio, RadioGroup } from "react-aria-components";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
 import { datetimeField, editDatetimeField, resolveDatetimeField, type DatetimeField } from "./datetime";
 import type { ActivitySearch } from "./search";
 
-const STATUS_OPTIONS = [
+/** Long enough that a typed word is one navigation, short enough to feel live. */
-	{ value: "any", label: "All" },
+const DEBOUNCE_MS = 350;
-	{ value: "blocked", label: "Blocked only" },
+
-	{ value: "allowed", label: "Allowed only" },
+const RESULTS = [
-];
+	{ value: "any", label: "Any" },
+	{ value: "blocked", label: "Blocked" },
+	{ value: "allowed", label: "Allowed" },
+] as const;
+
+const PRESETS = [
+	{ label: "Any time", seconds: null },
+	{ label: "Past hour", seconds: 3600 },
+	{ label: "Past 24 hours", seconds: 86_400 },
+	{ label: "Past 7 days", seconds: 604_800 },
+] as const;
+
+const CUSTOM_ITEM = "Custom…";
+
+/** The pointer-target floor `ui/Checkbox` and the dialog Close button already set. */
+const HIT_TARGET = 44;
 
 const styles = stylex.create({
-	/** One column on a phone, two from `sm`, five from `lg`. */
+	toolbar: {
-	grid: {
 		marginTop: "1rem",
-		display: "grid",
+		display: "flex",
-		gap: "0.75rem",
+		flexWrap: "wrap",
-		gridTemplateColumns: {
+		alignItems: "center",
-			default: "repeat(1, minmax(0, 1fr))",
+		gap: "0.5rem",
-			"@media (min-width: 640px)": "repeat(2, minmax(0, 1fr))",
-			"@media (min-width: 1024px)": "repeat(5, minmax(0, 1fr))",
-		},
 	},
-	label: {
+	/** The domain field is the one that grows; everything else keeps its size. */
-		display: "block",
+	searchWrap: {
+		position: "relative",
+		flexGrow: 1,
+		flexShrink: 1,
+		flexBasis: "14rem",
+		display: "flex",
+	},
+	searchIcon: {
+		position: "absolute",
+		insetInlineStart: "0.5rem",
+		top: "50%",
+		transform: "translateY(-50%)",
+		color: colors.textMuted,
+		pointerEvents: "none",
+	},
+	/** Every control in the row is a pointer target before it is anything else. */
+	field: {
+		minHeight: HIT_TARGET,
+	},
+	searchInput: {
+		width: "100%",
+		paddingInlineStart: "1.875rem",
+	},
+	clientInput: {
+		flexGrow: 0,
+		flexShrink: 1,
+		flexBasis: "10rem",
+	},
+	/** A button is text-sized by default; this is the hit area around the text. */
+	hitTarget: {
+		minHeight: HIT_TARGET,
+		minWidth: HIT_TARGET,
+		display: "inline-flex",
+		alignItems: "center",
+		justifyContent: "center",
+	},
+	resultGroup: {
+		display: "flex",
+		gap: "0.25rem",
+	},
+	/** The segment styling of the Overview period picker, item for item. */
+	segment: {
+		cursor: "pointer",
+		borderStyle: "none",
+		borderRadius: "0.25rem",
+		paddingInline: "0.625rem",
+		fontSize: "0.875rem",
+		lineHeight: "1.25rem",
+		minHeight: HIT_TARGET,
+		minWidth: HIT_TARGET,
+		display: "inline-flex",
+		alignItems: "center",
+		justifyContent: "center",
+	},
+	/** A Radio is a `label`, so RAC drives the ring rather than `:focus-visible`. */
+	segmentFocusVisible: {
+		outlineWidth: 2,
+		outlineStyle: "solid",
+		outlineColor: colors.focus,
+		outlineOffset: 2,
+	},
+	/** The pressed fill is heavier than `surfaceHover`, so a hover cannot mimic it. */
+	segmentSelected: {
+		backgroundColor: {
+			default: "oklch(92% 0.004 286.32)",
+			"@media (prefers-color-scheme: dark)": "oklch(37% 0.013 285.805)",
+		},
+		color: colors.text,
+		fontWeight: 500,
+	},
+	segmentIdle: {
+		backgroundColor: { default: "transparent", ":hover": colors.surfaceHover },
+		color: colors.textSecondary,
+	},
+	popover: {
+		borderRadius: "0.25rem",
+		borderWidth: 1,
+		borderStyle: "solid",
+		borderColor: colors.border,
+		backgroundColor: colors.surfaceRaised,
+		color: colors.text,
+		boxShadow: "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)",
+	},
+	menu: {
+		outlineStyle: "none",
+		paddingBlock: "0.25rem",
+	},
+	menuItem: {
+		cursor: "pointer",
+		paddingInline: "0.75rem",
+		fontSize: "0.875rem",
+		lineHeight: "1.25rem",
+		whiteSpace: "nowrap",
+		minHeight: HIT_TARGET,
+		display: "flex",
+		alignItems: "center",
+	},
+	/** Inset because an item flush against the popover edge clips an outset ring. */
+	menuItemFocused: {
+		backgroundColor: colors.primary,
+		color: colors.primaryText,
+		outlineColor: { default: null, ":focus-visible": colors.primaryText },
+	},
+	/**
+	 * 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.
+	 */
+	clearHidden: {
+		visibility: "hidden",
+	},
+	customRow: {
+		marginTop: "0.5rem",
+		display: "flex",
+		flexWrap: "wrap",
+		alignItems: "flex-end",
+		gap: "0.5rem",
+	},
+	customField: {
+		display: "flex",
+		flexDirection: "column",
+		gap: "0.25rem",
 		fontSize: "0.875rem",
 		lineHeight: "1.25rem",
 	},
-	input: {
-		marginTop: "0.25rem",
-		width: "100%",
-		// A disabled native input keeps its value legible but reads as inert,
-		// matching what RAC does to the Select trigger beside it.
-		cursor: { default: null, ":disabled": "not-allowed" },
-		opacity: { default: null, ":disabled": 0.55 },
-	},
-	buttonRow: {
-		display: "flex",
-		alignItems: "flex-end",
-		gap: "0.5rem",
-		gridColumn: {
-			default: null,
-			"@media (min-width: 640px)": "span 2 / span 2",
-			"@media (min-width: 1024px)": "span 5 / span 5",
-		},
-	},
-	toolbarButton: {
-		fontWeight: 500,
-	},
 	error: {
-		marginTop: "0.5rem",
 		fontSize: "0.875rem",
 		lineHeight: "1.25rem",
 		color: colors.dangerText,
@@ -86,6 +211,22 @@ export const NO_FILTERS: AppliedFilters = {
 	until: undefined,
 };
 
+/** The half-open window the API reads: `ts >= since` and `ts < until`. */
+interface Bounds {
+	since: number | undefined;
+	until: number | undefined;
+}
+
+/** The two text filters as the URL spells them, with absent written as empty. */
+interface TextPair {
+	domain: string;
+	client: string;
+}
+
+function sameBounds(a: Bounds, b: Bounds): boolean {
+	return a.since === b.since && a.until === b.until;
+}
+
 function blockedOption(blocked: boolean | undefined): string {
 	if (blocked === undefined) return "any";
 	return blocked ? "blocked" : "allowed";
@@ -96,135 +237,404 @@ function optionBlocked(value: string): boolean | undefined {
 	return value === "allowed" ? false : undefined;
 }
 
-function boundError(label: string, reason: "unparseable" | "nonexistent"): string {
+/** A filter value the URL can carry: trimmed, and empty means absent. */
-	return reason === "unparseable"
+function textFilter(value: string): string | undefined {
-		? `${label} is not a complete date and time.`
+	const trimmed = value.trim();
-		: `${label} names a local time that does not exist — the clock jumps over it for daylight saving.`;
+	return trimmed === "" ? undefined : trimmed;
+}
+
+/** The message plus the bound it belongs to, so that input can point at it. */
+interface BoundError {
+	field: "since" | "until";
+	message: string;
+}
+
+/** The toolbar is rendered once per page, so the message can hold a fixed id. */
+const ERROR_ID = "activity-filter-error";
+
+function boundError(field: "since" | "until", reason: "unparseable" | "nonexistent"): BoundError {
+	const label = field === "since" ? "Since" : "Until";
+	return {
+		field,
+		message:
+			reason === "unparseable"
+				? `${label} is not a complete date and time.`
+				: `${label} names a local time that does not exist — the clock jumps over it for daylight saving.`,
+	};
+}
+
+/** The preset a label is claimed for, kept only while the URL still holds it. */
+interface ChosenPreset extends Bounds {
+	label: string;
+}
+
+/**
+ * What this toolbar knows about the URL, and what it is still waiting to see
+ * come back from it.
+ *
+ * `url` and `bounds` are the last values looked at, so a change can be told
+ * apart field by field. `pendingText` and `pendingBounds` are every commit made
+ * here that the URL has not echoed yet. Both are queues rather than single
+ * slots: two keystrokes either side of the debounce put two text commits in
+ * flight, and two menu picks in quick succession do the same to the range. In
+ * both cases the older echo landing second must not be mistaken for someone
+ * else's edit — that is what would clear the preset out from under the pick
+ * that is actually current.
+ */
+interface Sync {
+	url: TextPair;
+	bounds: Bounds;
+	pendingText: TextPair[];
+	pendingBounds: Bounds[];
 }
 
 interface Props {
 	applied: AppliedFilters;
-	isDisabled: boolean;
+	/** Merges a patch into the applied search. `replace` keeps typing out of history. */
-	onApply: (filters: AppliedFilters) => void;
+	onApply: (patch: Partial<AppliedFilters>, replace?: boolean) => void;
 	onClear: () => void;
 }
 
-export default function ActivityFilters({ applied, isDisabled, onApply, onClear }: Props) {
+export default function ActivityFilters({ applied, onApply, onClear }: Props) {
-	const [domain, setDomain] = useState(applied.domain ?? "");
+	const urlText: TextPair = { domain: applied.domain ?? "", client: applied.client ?? "" };
-	const [client, setClient] = useState(applied.client ?? "");
+	const urlBounds: Bounds = { since: applied.since, until: applied.until };
-	const [blocked, setBlocked] = useState(blockedOption(applied.blocked));
+
+	const [domain, setDomain] = useState(urlText.domain);
+	const [client, setClient] = useState(urlText.client);
+	const [preset, setPreset] = useState<ChosenPreset | null>(null);
+	const [showCustom, setShowCustom] = useState(applied.since !== undefined || applied.until !== undefined);
 	const [since, setSince] = useState<DatetimeField>(() => datetimeField(applied.since));
 	const [until, setUntil] = useState<DatetimeField>(() => datetimeField(applied.until));
-	const [error, setError] = useState<string | null>(null);
+	const [error, setError] = useState<BoundError | null>(null);
+	const [sync, setSync] = useState<Sync>({
+		url: urlText,
+		bounds: urlBounds,
+		pendingText: [],
+		pendingBounds: [],
+	});
 
-	function submit(event: FormEvent) {
+	const textMoved = sync.url.domain !== urlText.domain || sync.url.client !== urlText.client;
+	const boundsMoved = !sameBounds(sync.bounds, urlBounds);
+	if (textMoved || boundsMoved) {
+		let pendingText = sync.pendingText;
+		let pendingBounds = sync.pendingBounds;
+
+		if (textMoved) {
+			// The newest commit the URL matches, and everything before it, has now
+			// been accounted for; an older one landing later is not new news.
+			const echo = pendingText.findLastIndex(
+				(sent) => sent.domain === urlText.domain && sent.client === urlText.client,
+			);
+			if (echo >= 0) {
+				pendingText = pendingText.slice(echo + 1);
+			} else {
+				pendingText = [];
+				if (sync.url.domain !== urlText.domain) setDomain(urlText.domain);
+				if (sync.url.client !== urlText.client) setClient(urlText.client);
+			}
+		}
+
+		if (boundsMoved) {
+			const echo = pendingBounds.findLastIndex((sent) => sameBounds(sent, urlBounds));
+			if (echo >= 0) {
+				pendingBounds = pendingBounds.slice(echo + 1);
+			} else {
+				// Someone else moved the window — the back button, or a pasted link.
+				// Whatever this form was showing about the old one is now wrong: the
+				// preset it was named after, an error against bounds that are gone,
+				// and a custom row that is open or shut for the wrong range.
+				pendingBounds = [];
+				setPreset(null);
+				setError(null);
+				setShowCustom(urlBounds.since !== undefined || urlBounds.until !== undefined);
+				setSince(datetimeField(urlBounds.since));
+				setUntil(datetimeField(urlBounds.until));
+			}
+		}
+
+		setSync({ url: urlText, bounds: urlBounds, pendingText, pendingBounds });
+	}
+
+	const dirty = textFilter(domain) !== applied.domain || textFilter(client) !== applied.client;
+
+	const commitText = useCallback(
+		(replace: boolean) => {
+			const next = { domain: textFilter(domain), client: textFilter(client) };
+			setSync((prev) => ({
+				...prev,
+				pendingText: [...prev.pendingText, { domain: next.domain ?? "", client: next.client ?? "" }],
+			}));
+			onApply(next, replace);
+		},
+		[domain, client, onApply],
+	);
+
+	function commitBounds(bounds: Bounds) {
+		setSync((prev) => ({ ...prev, pendingBounds: [...prev.pendingBounds, bounds] }));
+		onApply(bounds);
+	}
+
+	useEffect(() => {
+		if (!dirty) return;
+		const id = setTimeout(() => commitText(true), DEBOUNCE_MS);
+		return () => clearTimeout(id);
+	}, [dirty, commitText]);
+
+	function flush(event: FormEvent) {
 		event.preventDefault();
+		if (dirty) commitText(true);
+	}
+
+	function selectPreset(label: string) {
+		if (label === CUSTOM_ITEM) {
+			setShowCustom(true);
+			return;
+		}
+		const option = PRESETS.find((candidate) => candidate.label === label);
+		if (option === undefined) return;
+		setShowCustom(false);
+		setError(null);
+		if (option.seconds === null) {
+			setPreset(null);
+			setSince(datetimeField(undefined));
+			setUntil(datetimeField(undefined));
+			commitBounds({ since: undefined, until: undefined });
+			return;
+		}
+		// Both bounds, resolved once, here. An open upper bound would keep taking
+		// in queries logged after the reader stopped looking, so "the past hour"
+		// would name a different hour every time the link was opened.
+		const now = Math.floor(Date.now() / 1000);
+		const bounds: Bounds = { since: now - option.seconds, until: now };
+		setPreset({ label, ...bounds });
+		setSince(datetimeField(bounds.since));
+		setUntil(datetimeField(bounds.until));
+		commitBounds(bounds);
+	}
+
+	function setRange() {
 		const sinceValue = resolveDatetimeField(since);
 		if (!sinceValue.ok) {
-			setError(boundError("Since", sinceValue.reason));
+			setError(boundError("since", sinceValue.reason));
 			return;
 		}
 		const untilValue = resolveDatetimeField(until);
 		if (!untilValue.ok) {
-			setError(boundError("Until", untilValue.reason));
+			setError(boundError("until", untilValue.reason));
+			return;
+		}
+		// The window is half-open — `ts >= since` and `ts < until` — so two equal
+		// bounds are as empty as an inverted pair, and neither is worth applying.
+		if (
+			sinceValue.value !== undefined &&
+			untilValue.value !== undefined &&
+			untilValue.value <= sinceValue.value
+		) {
+			setError({
+				field: "until",
+				message: "Until must be after Since, or the range selects nothing.",
+			});
 			return;
 		}
 		setError(null);
-		onApply({
+		setPreset(null);
-			domain: domain.trim() === "" ? undefined : domain.trim(),
+		commitBounds({ since: sinceValue.value, until: untilValue.value });
-			client: client.trim() === "" ? undefined : client.trim(),
-			blocked: optionBlocked(blocked),
-			since: sinceValue.value,
-			until: untilValue.value,
-		});
 	}
 
 	function clear() {
 		setDomain("");
 		setClient("");
-		setBlocked("any");
+		setPreset(null);
+		setShowCustom(false);
 		setSince(datetimeField(undefined));
 		setUntil(datetimeField(undefined));
 		setError(null);
+		setSync((prev) => ({
+			...prev,
+			pendingText: [],
+			pendingBounds: [...prev.pendingBounds, { since: undefined, until: undefined }],
+		}));
 		onClear();
 	}
 
-	return (
+	const active =
-		<>
+		domain.trim() !== "" ||
-			<form onSubmit={submit} {...stylex.props(styles.grid)}>
+		client.trim() !== "" ||
-				<label {...stylex.props(styles.label)}>
+		applied.blocked !== undefined ||
-					Domain contains
+		applied.since !== undefined ||
-					<input
+		applied.until !== undefined;
-						type="text"
+
-						value={domain}
+	// The label the URL earns on its own, overridden only while a preset click is
-						disabled={isDisabled}
+	// still the whole of what the URL says. Bounds nobody here chose read as
-						onChange={(event) => setDomain(event.target.value)}
+	// "Custom": that is what a pasted link or an edited range is.
-						{...stylex.props(shared.smallInput, styles.input, shared.focusRing)}
+	let timeLabel = "Any time";
-					/>
+	if (applied.since !== undefined || applied.until !== undefined) {
-				</label>
+		timeLabel = preset !== null && sameBounds(preset, urlBounds) ? preset.label : "Custom";
-				<label {...stylex.props(styles.label)}>
+	}
-					Client (exact)
+
-					<input
+	/** True for the one bound the current message is about; nothing else is marked. */
-						type="text"
+	const invalid = (field: BoundError["field"]): true | undefined =>
-						value={client}
+		error !== null && error.field === field ? true : undefined;
-						disabled={isDisabled}
+
-						onChange={(event) => setClient(event.target.value)}
+	function boundInput(field: BoundError["field"]) {
-						{...stylex.props(shared.smallInput, styles.input, shared.focusRing)}
+		const state = field === "since" ? since : until;
-					/>
+		const set = field === "since" ? setSince : setUntil;
-				</label>
+		return (
-				<Select
+			<label {...stylex.props(styles.customField)}>
-					variant="compactField"
+				{field === "since" ? "Since" : "Until"}
-					label="Result"
+				<input
-					value={blocked}
+					type="datetime-local"
-					isDisabled={isDisabled}
+					step={1}
-					onChange={setBlocked}
+					value={state.text}
-					options={STATUS_OPTIONS}
+					aria-invalid={invalid(field)}
+					aria-describedby={invalid(field) && ERROR_ID}
+					onChange={(event) => set(editDatetimeField(state, event.target.value))}
+					onKeyDown={(event: KeyboardEvent<HTMLInputElement>) => {
+						// Enter here means this range, not the toolbar's text filters:
+						// the two bounds only ever apply together, and the outer form's
+						// submit would apply neither of them.
+						if (event.key !== "Enter") return;
+						event.preventDefault();
+						setRange();
+					}}
+					onBlur={() => {
+						const resolved = resolveDatetimeField(state);
+						if (!resolved.ok) setError(boundError(field, resolved.reason));
+						else if (invalid(field)) setError(null);
+					}}
+					{...stylex.props(shared.smallInput, styles.field, shared.focusRing)}
 				/>
-				<label {...stylex.props(styles.label)}>
+				{invalid(field) && (
-					Since
+					<span id={ERROR_ID} role="alert" {...stylex.props(styles.error)}>
-					<input
+						{error?.message}
-						type="datetime-local"
+					</span>
-						step={1}
+				)}
-						value={since.text}
+			</label>
-						disabled={isDisabled}
+		);
-						onChange={(event) => setSince(editDatetimeField(since, event.target.value))}
+	}
-						{...stylex.props(shared.smallInput, styles.input, shared.focusRing)}
+
-					/>
+	return (
-				</label>
+		<form onSubmit={flush}>
-				<label {...stylex.props(styles.label)}>
+			<div {...stylex.props(styles.toolbar)}>
-					Until
+				<div {...stylex.props(styles.searchWrap)}>
-					<input
+					<svg
-						type="datetime-local"
+						aria-hidden="true"
-						step={1}
+						viewBox="0 0 16 16"
-						value={until.text}
+						width="14"
-						disabled={isDisabled}
+						height="14"
-						onChange={(event) => setUntil(editDatetimeField(until, event.target.value))}
+						fill="none"
-						{...stylex.props(shared.smallInput, styles.input, shared.focusRing)}
+						stroke="currentColor"
-					/>
+						strokeWidth="1.5"
-				</label>
+						{...stylex.props(styles.searchIcon)}
-				<div {...stylex.props(styles.buttonRow)}>
-					<button
-						type="submit"
-						disabled={isDisabled}
-						{...stylex.props(shared.button, styles.toolbarButton, shared.focusRing)}
 					>
-						Apply filters
+						<circle cx="7" cy="7" r="4.5" />
-					</button>
+						<path d="M10.5 10.5 14 14" strokeLinecap="round" />
+					</svg>
+					<input
+						type="search"
+						aria-label="Filter domains"
+						placeholder="Filter domains…"
+						spellCheck={false}
+						autoComplete="off"
+						value={domain}
+						onChange={(event) => setDomain(event.target.value)}
+						{...stylex.props(shared.smallInput, styles.field, styles.searchInput, shared.focusRing)}
+					/>
+				</div>
+				{/*
+				 * The client filter matches one address exactly — the server has no
+				 * substring match for it — so the name says so rather than leaving the
+				 * reader to discover it by typing half an address and getting nothing.
+				 */}
+				<input
+					type="text"
+					aria-label="Client IP (exact match)"
+					placeholder="Client IP…"
+					spellCheck={false}
+					autoComplete="off"
+					value={client}
+					onChange={(event) => setClient(event.target.value)}
+					{...stylex.props(shared.smallInput, styles.field, styles.clientInput, shared.focusRing)}
+				/>
+				<RadioGroup
+					aria-label="Result"
+					orientation="horizontal"
+					value={blockedOption(applied.blocked)}
+					onChange={(next) => onApply({ blocked: optionBlocked(next) })}
+					className={() => stylex.props(styles.resultGroup).className ?? ""}
+				>
+					{RESULTS.map((option) => (
+						<Radio
+							key={option.value}
+							value={option.value}
+							className={({ isSelected, isFocusVisible }) =>
+								stylex.props(
+									styles.segment,
+									isSelected ? styles.segmentSelected : styles.segmentIdle,
+									isFocusVisible && styles.segmentFocusVisible,
+								).className ?? ""
+							}
+						>
+							{option.label}
+						</Radio>
+					))}
+				</RadioGroup>
+				<MenuTrigger>
+					<Button
+						className={() =>
+							stylex.props(shared.button, styles.hitTarget, shared.focusRing).className ?? ""
+						}
+					>
+						Time: {timeLabel}
+					</Button>
+					<Popover className={() => stylex.props(styles.popover).className ?? ""}>
+						<Menu {...stylex.props(styles.menu)}>
+							{[...PRESETS.map((option) => option.label), CUSTOM_ITEM].map((label) => (
+								<MenuItem
+									key={label}
+									onAction={() => selectPreset(label)}
+									className={({ isFocused }) =>
+										stylex.props(
+											styles.menuItem,
+											shared.insetFocusRing,
+											isFocused && styles.menuItemFocused,
+										).className ?? ""
+									}
+								>
+									{label}
+								</MenuItem>
+							))}
+						</Menu>
+					</Popover>
+				</MenuTrigger>
+				<button
+					type="button"
+					onClick={clear}
+					tabIndex={active ? undefined : -1}
+					aria-hidden={active ? undefined : true}
+					{...stylex.props(
+						shared.button,
+						styles.hitTarget,
+						shared.focusRing,
+						!active && styles.clearHidden,
+					)}
+				>
+					Clear
+				</button>
+			</div>
+			{showCustom && (
+				<div {...stylex.props(styles.customRow)}>
+					{boundInput("since")}
+					{boundInput("until")}
 					<button
 						type="button"
-						onClick={clear}
+						onClick={setRange}
-						disabled={isDisabled}
+						{...stylex.props(shared.button, styles.hitTarget, shared.focusRing)}
-						{...stylex.props(shared.button, styles.toolbarButton, shared.focusRing)}
 					>
-						Clear
+						Set range
 					</button>
 				</div>
-			</form>
-			{error !== null && (
-				<p role="alert" {...stylex.props(styles.error)}>
-					{error}
-				</p>
 			)}
-		</>
+		</form>
 	);
 }

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 { FakeEventSource } from "./fakeEventSource";
 
 function client(id: number, ip: string, name: string, learnedName: string): Client {
 	return {
@@ -135,6 +136,22 @@ function queryCalls(): string[] {
 		.filter((url) => url === "/api/queries" || url.startsWith("/api/queries?"));
 }
 
+/** The toolbar's search field, which is how a domain filter is entered now. */
+function domainInput(): HTMLInputElement {
+	return screen.getByLabelText("Filter domains") as HTMLInputElement;
+}
+
+/** Enter in a text field: the debounce's escape hatch, and the fast path here. */
+function submitFilters() {
+	fireEvent.submit(domainInput().closest("form")!);
+}
+
+/** The custom range lives behind the Time menu; the two bounds only exist there. */
+function openCustomRange() {
+	fireEvent.click(screen.getByRole("button", { name: /^Time: / }));
+	fireEvent.click(screen.getByRole("menuitem", { name: "Custom…" }));
+}
+
 test("renders the first page with the seven columns filled in", async () => {
 	renderPage();
 	await screen.findByText("first.example");
@@ -162,7 +179,7 @@ test("renders the first page with the seven columns filled in", async () => {
 	expect(screen.getByText(/Showing 2 queries/)).toBeTruthy();
 });
 
-test("resolves each row's client to its display name, keeping the IP as the tooltip", async () => {
+test("resolves each row's client to its display name, reading the IP out with it", 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 });
@@ -182,19 +199,22 @@ test("resolves each row's client to its display name, keeping the IP as the tool
 
 	// A hand-typed name wins outright; the learned name never surfaces for it.
 	const named = await screen.findByText("Kitchen Pi");
-	expect(named.getAttribute("title")).toBe("192.0.2.10");
+	// 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();
 
 	// 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");
-	expect(learned.getAttribute("title")).toBe("192.0.2.11");
+	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 no tooltip standing in.
+	// seen, both fall back to the bare address with nothing standing in for it.
-	expect(screen.getByText("192.0.2.12").getAttribute("title")).toBeNull();
+	expect(screen.getByText("192.0.2.12").textContent).toBe("192.0.2.12");
-	expect(screen.getByText("192.0.2.99").getAttribute("title")).toBeNull();
+	expect(screen.getByText("192.0.2.99").textContent).toBe("192.0.2.99");
 });
 
 test("load more appends the next page and stops at the end of the log", async () => {
@@ -216,8 +236,8 @@ test("applying a filter puts it in the url, refetches, and resets the accumulate
 	fireEvent.click(screen.getByRole("button", { name: "Load more" }));
 	await screen.findByText("older.example");
 
-	fireEvent.change(screen.getByLabelText("Domain contains"), { target: { value: "ads" } });
+	fireEvent.change(domainInput(), { target: { value: "ads" } });
-	fireEvent.click(screen.getByRole("button", { name: "Apply filters" }));
+	submitFilters();
 
 	await screen.findByText(/Showing 1 query /);
 	expect(history.location.search).toContain("domain=ads");
@@ -242,8 +262,8 @@ test("a load-more that resolves after a filter change is discarded", async () =>
 
 	fireEvent.click(screen.getByRole("button", { name: "Load more" }));
 
-	fireEvent.change(screen.getByLabelText("Domain contains"), { target: { value: "ads" } });
+	fireEvent.change(domainInput(), { target: { value: "ads" } });
-	fireEvent.click(screen.getByRole("button", { name: "Apply filters" }));
+	submitFilters();
 	await screen.findByText(/Showing 1 query /);
 
 	releaseLoadMore();
@@ -281,8 +301,8 @@ test("load more is disabled while a filter change shows placeholder data, then u
 	renderPage();
 	await screen.findByText("first.example");
 
-	fireEvent.change(screen.getByLabelText("Domain contains"), { target: { value: "ads" } });
+	fireEvent.change(domainInput(), { target: { value: "ads" } });
-	fireEvent.click(screen.getByRole("button", { name: "Apply filters" }));
+	submitFilters();
 
 	const staleButton = await screen.findByRole("button", { name: "Load more" });
 	expect(staleButton).toHaveProperty("disabled", true);
@@ -416,7 +436,7 @@ test("a ?domain= link seeds the filter form and fetches that domain on arrival",
 	renderPage("/activity?domain=ads");
 
 	await screen.findByText("ads.example");
-	expect(screen.getByLabelText("Domain contains")).toHaveProperty("value", "ads");
+	expect(domainInput()).toHaveProperty("value", "ads");
 	expect(screen.queryByText("first.example")).toBeNull();
 });
 
@@ -441,7 +461,7 @@ test("a rejected search parameter is dropped rather than guessed at", async () =
 	await screen.findByText("first.example");
 	// Nothing survived validation, so the request is the unfiltered one.
 	expect(queryCalls()).toEqual(["/api/queries"]);
-	expect(screen.getByLabelText("Domain contains")).toHaveProperty("value", "");
+	expect(domainInput()).toHaveProperty("value", "");
 });
 
 test("the form draft follows the url back and forward, seconds included", async () => {
@@ -454,25 +474,33 @@ test("the form draft follows the url back and forward, seconds included", async
 	const seeded = 1_700_000_017;
 	const { history } = renderPage(`/activity?mode=history&domain=first&since=${seeded}`);
 
-	const domainInput = await screen.findByLabelText("Domain contains");
+	await screen.findByLabelText("Filter domains");
-	expect(domainInput).toHaveProperty("value", "first");
+	expect(domainInput()).toHaveProperty("value", "first");
+	// A seeded custom range opens its row, so the link's bounds are visible.
 	const sinceInput = screen.getByLabelText("Since") as HTMLInputElement;
 	expect(sinceInput.value).toContain(":37");
 
-	fireEvent.change(domainInput, { target: { value: "second" } });
+	fireEvent.change(domainInput(), { target: { value: "second" } });
-	fireEvent.click(screen.getByRole("button", { name: "Apply filters" }));
+	submitFilters();
 	await waitFor(() => expect(history.location.search).toContain("domain=second"));
 	// The untouched Since bound applied as the exact second it was seeded with.
 	expect(queryCalls()).toContain(`/api/queries?domain=second&since=${seeded}`);
 
+	// A pasted link, then the buttons over it: the draft is derived from the URL,
+	// so whichever way the browser moves it the field has to move with it.
+	act(() => history.push(`/activity?mode=history&domain=third&since=${seeded}`));
+	await waitFor(() => {
+		expect(domainInput()).toHaveProperty("value", "third");
+	});
+
 	act(() => history.back());
 	await waitFor(() => {
-		expect(screen.getByLabelText("Domain contains")).toHaveProperty("value", "first");
+		expect(domainInput()).toHaveProperty("value", "second");
 	});
 
 	act(() => history.forward());
 	await waitFor(() => {
-		expect(screen.getByLabelText("Domain contains")).toHaveProperty("value", "second");
+		expect(domainInput()).toHaveProperty("value", "third");
 	});
 });
 
@@ -508,8 +536,9 @@ test("a wall-clock time the daylight-saving jump skips is refused, not silently
 	const callsBefore = queryCalls().length;
 	const searchBefore = history.location.search;
 
+	openCustomRange();
 	fireEvent.change(screen.getByLabelText("Since"), { target: { value: DST_WALL_TIME } });
-	fireEvent.click(screen.getByRole("button", { name: "Apply filters" }));
+	fireEvent.click(screen.getByRole("button", { name: "Set range" }));
 
 	if (inGap) {
 		expect(screen.getByRole("alert").textContent).toContain("daylight saving");
@@ -544,6 +573,40 @@ test("the policy simulation is reachable from the header, with no rows to click
 	expect(history.location.pathname).toBe("/activity/test");
 });
 
+test("the mode switch is a tab list whose selection is the url, and it keeps the filters", async () => {
+	// Live opens a stream as soon as its panel mounts, so the switch cannot be
+	// exercised without one; the fake stands in for the browser's EventSource.
+	vi.stubGlobal(
+		"EventSource",
+		class {
+			constructor(url: string) {
+				return new FakeEventSource(url) as unknown as EventSource;
+			}
+		},
+	);
+	const { history } = renderPage("/activity?mode=history&domain=ads&blocked=true");
+	await screen.findByText("ads.example");
+
+	const tabs = within(screen.getByRole("tablist", { name: "Activity mode" }));
+	expect(tabs.getAllByRole("tab").map((tab) => tab.textContent)).toEqual(["History", "Live"]);
+	expect(tabs.getByRole("tab", { name: "History", selected: true })).toBeTruthy();
+	expect(tabs.getByRole("tab", { name: "Live", selected: false })).toBeTruthy();
+
+	fireEvent.click(tabs.getByRole("tab", { name: "Live" }));
+
+	await waitFor(() => expect(history.location.search).toContain("mode=live"));
+	// The investigation survives the switch: both filters are still in the URL.
+	expect(history.location.search).toContain("domain=ads");
+	expect(history.location.search).toContain("blocked=true");
+	expect(
+		within(screen.getByRole("tablist", { name: "Activity mode" })).getByRole("tab", {
+			name: "Live",
+			selected: true,
+		}),
+	).toBeTruthy();
+	expect(await screen.findByText(/the History filters apply to history only/)).toBeTruthy();
+});
+
 test("Clear empties the url as well as the form", async () => {
 	const { history } = renderPage("/activity?mode=history&domain=ads&blocked=true");
 	await screen.findByText("ads.example");
@@ -553,5 +616,130 @@ test("Clear empties the url as well as the form", async () => {
 		expect(history.location.search).not.toContain("domain");
 	});
 	expect(history.location.search).not.toContain("blocked");
-	expect(screen.getByLabelText("Domain contains")).toHaveProperty("value", "");
+	expect(domainInput()).toHaveProperty("value", "");
+});
+
+test("the domain field debounces into the url, and Enter flushes it at once", async () => {
+	vi.useFakeTimers({ shouldAdvanceTime: true });
+	try {
+		const { history } = renderPage();
+		await screen.findByText("first.example");
+
+		fireEvent.change(domainInput(), { target: { value: "a" } });
+		fireEvent.change(domainInput(), { target: { value: "ad" } });
+		fireEvent.change(domainInput(), { target: { value: "ads" } });
+		// Mid-word the URL has not moved: three keystrokes are one investigation,
+		// not three, and each one would otherwise be a request and a history entry.
+		expect(history.location.search).not.toContain("domain");
+
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(400);
+		});
+		expect(history.location.search).toContain("domain=ads");
+		// Replaced, not pushed: Back leaves the page, it does not retype the word.
+		expect(history.length).toBe(1);
+
+		fireEvent.change(domainInput(), { target: { value: "first" } });
+		submitFilters();
+		await waitFor(() => expect(history.location.search).toContain("domain=first"));
+	} finally {
+		vi.useRealTimers();
+	}
+});
+
+test("the field being typed in keeps the focus when the debounce commits", async () => {
+	vi.useFakeTimers({ shouldAdvanceTime: true });
+	try {
+		const { history } = renderPage();
+		await screen.findByText("first.example");
+
+		const input = domainInput();
+		input.focus();
+		fireEvent.change(input, { target: { value: "ads" } });
+
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(400);
+		});
+		await waitFor(() => expect(history.location.search).toContain("domain=ads"));
+
+		// The same node, still focused, still holding the caret: a toolbar that
+		// remounted on the URL it just wrote would drop the next keystroke.
+		expect(domainInput()).toBe(input);
+		expect(document.activeElement).toBe(input);
+	} finally {
+		vi.useRealTimers();
+	}
+});
+
+test("a result segment commits on the click, with no wait and no button", async () => {
+	const { history } = renderPage("/activity?domain=ads");
+	await screen.findByText("ads.example");
+
+	fireEvent.click(screen.getByRole("radio", { name: "Blocked" }));
+
+	await waitFor(() => expect(history.location.search).toContain("blocked=true"));
+	expect(history.location.search).toContain("domain=ads");
+});
+
+test("a time preset writes the second it resolved to, not a rolling window", async () => {
+	const now = 1_700_000_000_000;
+	vi.spyOn(Date, "now").mockReturnValue(now);
+	stubFetch((url) => {
+		if (url === "/api/clients") return json({ clients: CLIENTS });
+		return json({ queries: [], next_before: null, coverage: COMPLETE } satisfies QueriesPage);
+	});
+	const { history } = renderPage();
+	await screen.findByText("No queries logged yet.");
+
+	fireEvent.click(screen.getByRole("button", { name: "Time: Any time" }));
+	fireEvent.click(screen.getByRole("menuitem", { name: "Past hour" }));
+
+	// Both bounds are concrete, so the link names a closed hour rather than one
+	// that keeps growing at the top as the log does.
+	const since = now / 1000 - 3600;
+	const until = now / 1000;
+	await waitFor(() => expect(history.location.search).toContain(`since=${since}`));
+	expect(history.location.search).toContain(`until=${until}`);
+	expect(screen.getByRole("button", { name: "Time: Past hour" })).toBeTruthy();
+	expect(queryCalls()).toContain(`/api/queries?since=${since}&until=${until}`);
+
+	vi.restoreAllMocks();
+});
+
+test("Live shows no toolbar at all", async () => {
+	vi.stubGlobal(
+		"EventSource",
+		class {
+			constructor(url: string) {
+				return new FakeEventSource(url) as unknown as EventSource;
+			}
+		},
+	);
+	renderPage("/activity?mode=live&domain=ads");
+	await screen.findByText(/the History filters apply to history only/);
+
+	// The stream is unfiltered, so a control here would promise filtering that is
+	// not happening; the filters are still in the URL, waiting for History.
+	expect(screen.queryByLabelText("Filter domains")).toBeNull();
+	expect(screen.queryByRole("radio", { name: "Blocked" })).toBeNull();
+	expect(screen.queryByRole("button", { name: /^Time: / })).toBeNull();
+});
+
+test("the coverage watermark reads under the results, never over 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, "kept.example")],
+			next_before: null,
+			coverage: { complete: false, available_since: 1_700_000_000 },
+		} satisfies QueriesPage);
+	});
+	renderPage();
+	await screen.findByText("kept.example");
+
+	const watermark = screen.getByText(/Query history is available from/);
+	const count = screen.getByText(/Showing 1 query/);
+	// After the count in document order, which is what "footer" means here.
+	expect(count.compareDocumentPosition(watermark) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
 });

admin/src/features/activity/ActivityPage.tsx

@@ -8,8 +8,10 @@
  * recipient should be looking at.
  */
 
+import { useCallback } from "react";
 import { Link, useNavigate, useSearch } from "@tanstack/react-router";
 import * as stylex from "@stylexjs/stylex";
+import { Tab, TabList, TabPanel, Tabs } from "react-aria-components";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
 import ActivityFilters, { NO_FILTERS, type AppliedFilters } from "./ActivityFilters";
@@ -53,6 +55,13 @@ const styles = stylex.create({
 		fontWeight: 500,
 		cursor: "pointer",
 	},
+	/** A Tab is a `div` with a roving tabindex, so RAC drives the ring, not `:focus-visible`. */
+	modeFocusVisible: {
+		outlineWidth: 2,
+		outlineStyle: "solid",
+		outlineColor: colors.focus,
+		outlineOffset: 2,
+	},
 	modeIdle: {
 		backgroundColor: { default: "transparent", ":hover": colors.surfaceHover },
 		color: { default: colors.textSecondary, ":hover": colors.text },
@@ -76,13 +85,33 @@ const styles = stylex.create({
 		lineHeight: "1.25rem",
 		color: colors.textMuted,
 	},
+	panel: {
+		outlineStyle: "none",
+	},
+	/**
+	 * A panel with nothing tabbable in it — an empty or loading history — is given
+	 * a tabindex by RAC so the reader can still reach its content, so it has to be
+	 * able to show that it holds the focus.
+	 */
+	panelFocusVisible: {
+		outlineWidth: 2,
+		outlineStyle: "solid",
+		outlineColor: colors.focus,
+		outlineOffset: 2,
+	},
+	/** Explicit, so RAC's default `react-aria-Tabs` class does not land instead. */
+	tabsRoot: {
+		display: "block",
+	},
 });
 
+function panelClass({ isFocusVisible }: { isFocusVisible: boolean }): string {
+	return stylex.props(styles.panel, isFocusVisible && styles.panelFocusVisible).className ?? "";
+}
+
 export default function ActivityPage() {
 	const search = useSearch({ from: "/shell/activity" });
 	const navigate = useNavigate({ from: "/activity" });
-	const live = search.mode === "live";
-
 	// The functional form, not a replacement object: the filters are retained
 	// across a mode switch on purpose, and spelling out a new search here would
 	// drop every one of them on the way to Live and back.
@@ -91,62 +120,75 @@ export default function ActivityPage() {
 		void navigate({ search: (prev) => ({ ...prev, mode }) });
 	}
 
-	function apply(filters: AppliedFilters) {
+	// A patch, merged into whatever the URL already says: a segment click must not
-		void navigate({ search: { mode: search.mode, ...filters } });
+	// spell out the four filters it is not about. `replace` is the debounced text
-	}
+	// commits, so the back button steps between investigations, not keystrokes.
+	const apply = useCallback(
+		(patch: Partial<AppliedFilters>, replace = false) => {
+			void navigate({ search: (prev) => ({ ...prev, ...patch }), replace });
+		},
+		[navigate],
+	);
+
+	const clear = useCallback(() => {
+		void navigate({ search: (prev) => ({ mode: prev.mode, ...NO_FILTERS }) });
+	}, [navigate]);
 
 	return (
 		<section>
-			<div {...stylex.props(styles.header)}>
+			{/*
-				<h1 {...stylex.props(styles.heading)}>Activity</h1>
+			 * The selected tab is the URL's `mode` and nothing else. RAC would hold
-				<div role="group" aria-label="Activity mode" {...stylex.props(styles.switch)}>
+			 * the selection itself, but a second copy of it would fight the back
-					{MODES.map((option) => {
+			 * button, so the search parameter stays the only state there is.
-						const selected = option.mode === search.mode;
+			 */}
-						return (
+			<Tabs
-							<button
+				selectedKey={search.mode}
+				onSelectionChange={(key) => selectMode(key as ActivityMode)}
+				className={() => stylex.props(styles.tabsRoot).className ?? ""}
+			>
+				<div {...stylex.props(styles.header)}>
+					<h1 {...stylex.props(styles.heading)}>Activity</h1>
+					<TabList
+						aria-label="Activity mode"
+						className={() => stylex.props(styles.switch).className ?? ""}
+					>
+						{MODES.map((option) => (
+							<Tab
 								key={option.mode}
-								type="button"
+								id={option.mode}
-								aria-pressed={selected}
+								className={({ isSelected, isFocusVisible }) =>
-								onClick={() => selectMode(option.mode)}
+									stylex.props(
-								{...stylex.props(
+										styles.modeButton,
-									styles.modeButton,
+										isSelected ? styles.modeSelected : styles.modeIdle,
-									selected ? styles.modeSelected : styles.modeIdle,
+										isFocusVisible && styles.modeFocusVisible,
-									shared.focusRing,
+									).className ?? ""
-								)}
+								}
 							>
 								{option.label}
-							</button>
+							</Tab>
-						);
+						))}
-					})}
+					</TabList>
+					<Link to="/activity/test" {...stylex.props(styles.simulationLink, shared.focusRing)}>
+						Current policy simulation
+					</Link>
 				</div>
-				<Link to="/activity/test" {...stylex.props(styles.simulationLink, shared.focusRing)}>
-					Current policy simulation
-				</Link>
-			</div>
 
-			{/*
+				{/*
-			 * Remounted whenever the applied search changes, which is what makes
+				 * The toolbar belongs to History alone. It is not remounted on a search
-			 * the back button work: the draft is derived state, and the browser
+				 * change: it resyncs its draft from the URL instead, because a remount
-			 * moving the URL under it has to move the form with it.
+				 * mid-debounce would take the focus out of the input being typed in.
-			 */}
+				 */}
-			<ActivityFilters
+				<TabPanel id="history" className={panelClass}>
-				key={`${search.domain ?? ""}|${search.client ?? ""}|${String(search.blocked)}|${String(search.since)}|${String(search.until)}`}
+					<ActivityFilters applied={search} onApply={apply} onClear={clear} />
-				applied={search}
+					<HistoryActivity search={search} />
-				isDisabled={live}
+				</TabPanel>
-				onApply={apply}
+				<TabPanel id="live" className={panelClass}>
-				onClear={() => apply(NO_FILTERS)}
-			/>
-
-			{live ? (
-				<>
 					<p {...stylex.props(styles.liveNote)}>
-						The stream carries every query the server answers; these filters apply to history only.
+						The stream carries every query the server answers; the History filters apply to history only.
 					</p>
 					<LiveActivity origin={search} />
-				</>
+				</TabPanel>
-			) : (
+			</Tabs>
-				<HistoryActivity search={search} />
-			)}
 		</section>
 	);
 }

admin/src/features/activity/HistoryActivity.tsx

@@ -56,7 +56,8 @@ const styles = stylex.create({
 		lineHeight: "1.25rem",
 		color: colors.textMuted,
 	},
-	refetching: {
+	/** The gap a line standing on its own needs from the block above it. */
+	spacedTop: {
 		marginTop: "0.75rem",
 	},
 	moreButton: {
@@ -81,7 +82,9 @@ export default function HistoryActivity({ search }: { search: ActivitySearch })
 
 	const pages = base.data?.pages ?? [];
 	const rows: QueryRow[] = pages.flatMap((page) => page.queries);
-	const coverage = pages[0]?.coverage;
+	// Only from the settled response. Placeholder pages belong to the previous
+	// filter, and a watermark is a claim about the window being displayed.
+	const coverage = base.isPlaceholderData ? undefined : pages[0]?.coverage;
 	const filterActive = Object.keys(filter).length > 0;
 	// `base.hasNextPage` reads the query state, which is empty while placeholder
 	// data stands in for a filter change; derive the cursor from what is on
@@ -112,16 +115,27 @@ export default function HistoryActivity({ search }: { search: ActivitySearch })
 
 	return (
 		<>
+			{/*
+			 * A quiet line, never a skeleton: the rows on screen stay put while a
+			 * filter change is in flight, so a keystroke must not blank the table
+			 * it is narrowing.
+			 */}
 			{base.isFetching && (
-				<p {...stylex.props(styles.note, styles.refetching)} role="status">
+				<p {...stylex.props(styles.note, styles.spacedTop)} role="status">
-					Loading…
+					Updating…
 				</p>
 			)}
-			{coverage !== undefined && <CoverageNotice coverage={coverage} />}
 			{rows.length === 0 ? (
-				<p {...stylex.props(styles.empty)}>
+				<>
-					{filterActive ? "No queries match the current filters." : "No queries logged yet."}
+					<p {...stylex.props(styles.empty)}>
-				</p>
+						{filterActive ? "No queries match the current filters." : "No queries logged yet."}
+					</p>
+					{coverage !== undefined && (
+						<div {...stylex.props(styles.spacedTop)}>
+							<CoverageNotice coverage={coverage} variant="note" />
+						</div>
+					)}
+				</>
 			) : (
 				<>
 					<div {...stylex.props(styles.tableWrap)}>
@@ -158,6 +172,7 @@ export default function HistoryActivity({ search }: { search: ActivitySearch })
 							Showing {rows.length} {rows.length === 1 ? "query" : "queries"}
 							{hasMore ? "" : " — end of log"}
 						</p>
+						{coverage !== undefined && <CoverageNotice coverage={coverage} variant="note" />}
 						{hasMore && (
 							<button
 								type="button"

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

@@ -57,7 +57,17 @@ function json(payload: unknown): Response {
 	return new Response(JSON.stringify(payload), { status: 200, headers: { "content-type": "application/json" } });
 }
 
-function stubFetch(handler: (url: string) => Response | Promise<Response> = () => json({})) {
+/**
+ * The empty history page. Live mode asks for no query pages, but switching back
+ * to History does, and a page-shaped response is the only honest answer there.
+ */
+const EMPTY_PAGE = { queries: [], next_before: null, coverage: { complete: true, available_since: 0 } };
+
+function defaultHandler(url: string): Response {
+	return json(url === "/api/queries" || url.startsWith("/api/queries?") ? EMPTY_PAGE : {});
+}
+
+function stubFetch(handler: (url: string) => Response | Promise<Response> = defaultHandler) {
 	fetchMock = vi.fn((input: RequestInfo | URL) => {
 		const url = String(input);
 		if (url === "/api/version") return Promise.resolve(json(VERSION));
@@ -168,7 +178,7 @@ test("streams rows, flags blocked ones, and freezes the display", async () => {
 	expect(screen.getByText("later.example")).toBeTruthy();
 });
 
-test("resolves each row's client to its display name, keeping the IP as the tooltip", async () => {
+test("resolves each row's client to its display name, reading the IP out with it", async () => {
 	await openLive();
 	act(() => {
 		sources[0]!.emit("query", frame(1000, "named.example", { request: { client: "192.0.2.10" } }));
@@ -178,11 +188,14 @@ test("resolves each row's client to its display name, keeping the IP as the tool
 	});
 
 	const named = await screen.findByText("Kitchen Pi");
-	expect(named.getAttribute("title")).toBe("192.0.2.10");
+	// 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");
-	expect(learned.getAttribute("title")).toBe("192.0.2.11");
+	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();
@@ -256,7 +269,40 @@ test("a recovered row links to its stored detail; a streamed one opens in place
 	expect(screen.getByRole("button", { name: "streamed.example" })).toBeTruthy();
 });
 
-test("a streamed row opens its own provenance, from the keyboard as well as the pointer", async () => {
+/** The open detail. Named by its heading, so the query proves the name is visible. */
+function detailDialog(): HTMLElement {
+	return screen.getByRole("dialog", { name: "Streamed query" });
+}
+
+/** React Aria's ModalOverlay, two levels out from the dialog it wraps. */
+function backdrop(): HTMLElement {
+	return detailDialog().parentElement!.parentElement!;
+}
+
+/**
+ * Activate a control the way a keyboard does. jsdom runs no default action for
+ * Enter on a button, so the click a browser would then dispatch is issued here;
+ * `detail: 0` is what marks it as keyboard-driven rather than pointer-driven,
+ * and is the flag React Aria itself reads.
+ */
+function pressWithKeyboard(control: HTMLElement) {
+	act(() => control.focus());
+	fireEvent.keyDown(control, { key: "Enter" });
+	fireEvent.click(control, { detail: 0 });
+	fireEvent.keyUp(control, { key: "Enter" });
+}
+
+/** Activate a control the way a mouse does, through the full pointer sequence. */
+function pressWithMouse(control: HTMLElement) {
+	fireEvent.pointerDown(control, { pointerType: "mouse", button: 0 });
+	fireEvent.pointerUp(control, { pointerType: "mouse", button: 0 });
+	fireEvent.click(control, { detail: 1 });
+}
+
+test.each([
+	["the pointer", pressWithMouse],
+	["the keyboard", pressWithKeyboard],
+])("a streamed row opens its provenance in a named dialog, from %s", async (_label, press) => {
 	await openLive();
 	act(() =>
 		sources[0]!.emit(
@@ -273,69 +319,108 @@ test("a streamed row opens its own provenance, from the keyboard as well as the
 	// only way to lose that is to opt out of it, which nothing here may do.
 	expect(trigger.tagName).toBe("BUTTON");
 	expect(trigger.getAttribute("tabindex")).toBeNull();
-	act(() => trigger.focus());
+	// The row opens a dialog, so it says so; what it no longer claims is to
-	expect(document.activeElement).toBe(trigger);
+	// expand a region that stays in the page.
+	expect(trigger.getAttribute("aria-haspopup")).toBe("dialog");
+	expect(trigger.getAttribute("aria-expanded")).toBeNull();
+	expect(trigger.getAttribute("aria-controls")).toBeNull();
 
-	fireEvent.click(trigger);
+	press(trigger);
-	const heading = screen.getByRole("heading", { level: 1, name: "streamed.example" });
-	expect(heading).toBeTruthy();
-	const panel = heading.closest("div")!.parentElement!;
-	expect(within(panel).getByText("Blocked locally")).toBeTruthy();
-	expect(panel.textContent).toContain("the query log may not have written it yet");
 
-	fireEvent.click(screen.getByRole("button", { name: "Close" }));
+	const dialog = detailDialog();
-	expect(screen.queryByRole("heading", { level: 1, name: "streamed.example" })).toBeNull();
+	expect(within(dialog).getByRole("heading", { level: 1, name: "streamed.example" })).toBeTruthy();
+	expect(within(dialog).getByText("Blocked locally")).toBeTruthy();
+	expect(dialog.textContent).toContain("the query log may not have written it yet");
+	// React Aria may defer the move by a frame, depending on the modality it read
+	// from the activation, so the wait is the assertion rather than a workaround.
+	await waitFor(() => expect(dialog.contains(document.activeElement)).toBe(true));
+	expect(within(dialog).getByRole("button", { name: "Close" })).toBeTruthy();
 });
 
-test("the detail takes focus when a row opens it and hands it back when it closes", async () => {
+test("tabbing forward and backward stays inside the open dialog", async () => {
 	await openLive();
 	act(() => sources[0]!.emit("query", frame(1000, "streamed.example")));
+	fireEvent.click(screen.getByRole("button", { name: "streamed.example" }));
 
-	const trigger = screen.getByRole("button", { name: "streamed.example" });
+	const dialog = detailDialog();
-	expect(trigger.getAttribute("aria-expanded")).toBe("false");
+	await waitFor(() => expect(dialog.contains(document.activeElement)).toBe(true));
-	expect(trigger.getAttribute("aria-controls")).toBeNull();
+	// The related links land asynchronously; tabbing before them would walk a
+	// shorter dialog than the reader ever sees.
+	await waitFor(() => expect(within(dialog).getAllByRole("link").length).toBeGreaterThan(1));
 
-	// A native button activates on Enter and Space; jsdom does not synthesize
+	const visited = new Set<Element>();
-	// the click those keys fire, so the click is the activation.
+	for (const shiftKey of [false, false, false, false, false, false, true, true, true, true]) {
-	act(() => trigger.focus());
+		fireEvent.keyDown(document.activeElement!, { key: "Tab", shiftKey });
-	fireEvent.click(trigger);
+		fireEvent.keyUp(document.activeElement!, { key: "Tab", shiftKey });
-
+		expect(dialog.contains(document.activeElement)).toBe(true);
-	const panel = screen.getByRole("group", { name: "Streamed query" });
+		visited.add(document.activeElement!);
-	expect(trigger.getAttribute("aria-expanded")).toBe("true");
+	}
-	expect(trigger.getAttribute("aria-controls")).toBe(panel.id);
+	// Containment that never moved focus would satisfy the check above without
-	// The panel is inserted above the table, behind the trigger in tab order, so
+	// trapping anything, so the walk has to have actually walked.
-	// the only thing that keeps a forward tab inside it is focus moving in.
+	expect(visited.size).toBeGreaterThan(1);
-	expect(panel.compareDocumentPosition(trigger) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
-	expect(document.activeElement).toBe(panel);
-	expect(panel.contains(screen.getByRole("button", { name: "Close" }))).toBe(true);
-
-	fireEvent.click(screen.getByRole("button", { name: "Close" }));
-	expect(screen.queryByRole("group", { name: "Streamed query" })).toBeNull();
-	expect(document.activeElement).toBe(trigger);
-	expect(trigger.getAttribute("aria-expanded")).toBe("false");
-	expect(trigger.getAttribute("aria-controls")).toBeNull();
 });
 
-test("opening a second row moves the expanded state and the focus with it", async () => {
+test.each([
+	["the Close button", () => fireEvent.click(within(detailDialog()).getByRole("button", { name: "Close" }))],
+	["Escape", () => fireEvent.keyDown(detailDialog(), { key: "Escape" })],
+	[
+		"a click on the backdrop",
+		() => {
+			const overlay = backdrop();
+			fireEvent.pointerDown(overlay, { pointerType: "mouse", button: 0 });
+			fireEvent.pointerUp(overlay, { pointerType: "mouse", button: 0 });
+			fireEvent.click(overlay, { detail: 1 });
+		},
+	],
+])("%s closes the dialog and returns focus to the row that opened it", async (_label, dismiss) => {
 	await openLive();
-	act(() => {
+	act(() => sources[0]!.emit("query", frame(1000, "streamed.example")));
-		sources[0]!.emit("query", frame(1000, "first.example"));
+	const trigger = screen.getByRole("button", { name: "streamed.example" });
-		sources[0]!.emit("query", frame(1001, "second.example"));
+	act(() => trigger.focus());
-	});
+	fireEvent.click(trigger);
+	expect(detailDialog()).toBeTruthy();
 
-	const first = screen.getByRole("button", { name: "first.example" });
+	dismiss();
-	const second = screen.getByRole("button", { name: "second.example" });
-	fireEvent.click(first);
-	fireEvent.click(second);
 
-	const panel = screen.getByRole("group", { name: "Streamed query" });
+	await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull());
-	expect(within(panel).getByRole("heading", { level: 1, name: "second.example" })).toBeTruthy();
+	expect(document.activeElement).toBe(screen.getByRole("button", { name: "streamed.example" }));
-	expect(document.activeElement).toBe(panel);
+});
-	expect(first.getAttribute("aria-expanded")).toBe("false");
+
-	expect(second.getAttribute("aria-expanded")).toBe("true");
+test("the stream runs on behind the open dialog, and its rows land in the table on close", async () => {
+	await openLive();
+	act(() => sources[0]!.emit("query", frame(1000, "streamed.example")));
+	fireEvent.click(screen.getByRole("button", { name: "streamed.example" }));
+
+	const snapshot = detailDialog().textContent;
+	act(() => sources[0]!.emit("query", frame(1001, "arrived-while-open.example")));
+
+	// The connection is untouched: no close, no second EventSource.
+	expect(sources).toHaveLength(1);
+	expect(sources[0]!.closed).toBe(false);
+	// And the snapshot is a snapshot: nothing that arrives rewrites it.
+	expect(detailDialog().textContent).toBe(snapshot);
+
+	fireEvent.click(within(detailDialog()).getByRole("button", { name: "Close" }));
+	await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull());
+	expect(screen.getByRole("button", { name: "arrived-while-open.example" })).toBeTruthy();
+	expect(screen.getByRole("button", { name: "streamed.example" })).toBeTruthy();
+});
+
+test("the rows and toolbar behind the dialog are out of reach while it is open", async () => {
+	await openLive();
+	act(() => sources[0]!.emit("query", frame(1000, "streamed.example")));
+	fireEvent.click(screen.getByRole("button", { name: "streamed.example" }));
+
+	// React Aria hides everything outside the modal from assistive technology
+	// and from the pointer alike, so the row and the toolbar are unreachable by
+	// role: nothing behind the dialog can be operated while it is open.
+	expect(screen.queryByRole("button", { name: "streamed.example" })).toBeNull();
+	expect(screen.queryByRole("button", { name: "Freeze" })).toBeNull();
+	expect(screen.getByRole("button", { name: "Close" })).toBeTruthy();
 
 	fireEvent.click(screen.getByRole("button", { name: "Close" }));
-	expect(document.activeElement).toBe(second);
+	await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull());
+	expect(screen.getByRole("button", { name: "Freeze" })).toBeTruthy();
 });
 
 /**
@@ -359,23 +444,57 @@ function renderLiveWithCapacity(capacity: number) {
 	);
 }
 
-test("an open streamed detail survives the row being evicted from the ring buffer", () => {
+/** Push one ringful of filler through a 5-row ring, evicting whatever was there. */
-	renderLiveWithCapacity(5);
+function evictWithFiller() {
-	act(() => sources[0]!.emit("open"));
-	act(() => sources[0]!.emit("query", frame(1000, "evicted.example")));
-	fireEvent.click(screen.getByRole("button", { name: "evicted.example" }));
-	expect(screen.getByRole("heading", { level: 1, name: "evicted.example" })).toBeTruthy();
-
-	// One ringful more: the ring keeps the newest 5, so the selected row is gone
-	// from the table. The detail is a snapshot, not a lookup into the ring.
 	act(() => {
 		for (let index = 0; index < 5; index += 1) {
 			sources[0]!.emit("query", frame(2000 + index, `filler${index}.example`));
 		}
 	});
+}
+
+test("an open dialog's snapshot survives its row being evicted from the ring buffer", async () => {
+	renderLiveWithCapacity(5);
+	act(() => sources[0]!.emit("open"));
+	act(() => sources[0]!.emit("query", frame(1000, "evicted.example")));
+	fireEvent.click(screen.getByRole("button", { name: "evicted.example" }));
+	const snapshot = detailDialog().textContent;
+	expect(within(detailDialog()).getByRole("heading", { level: 1, name: "evicted.example" })).toBeTruthy();
+
+	// One ringful more: the ring keeps the newest 5, so the selected row is gone.
+	// The dialog holds the frame itself, not a lookup into the ring, so it neither
+	// blanks out nor closes.
+	evictWithFiller();
+	expect(detailDialog().textContent).toBe(snapshot);
+
+	fireEvent.click(within(detailDialog()).getByRole("button", { name: "Close" }));
+	await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull());
 	expect(screen.getAllByRole("row")).toHaveLength(6);
 	expect(screen.queryByRole("button", { name: "evicted.example" })).toBeNull();
-	expect(screen.getByRole("heading", { level: 1, name: "evicted.example" })).toBeTruthy();
+});
+
+test("closing after the source row is evicted anchors focus in the results region", async () => {
+	renderLiveWithCapacity(5);
+	act(() => sources[0]!.emit("open"));
+	act(() => sources[0]!.emit("query", frame(1000, "evicted.example")));
+	const trigger = screen.getByRole("button", { name: "evicted.example" });
+	act(() => trigger.focus());
+	fireEvent.click(trigger);
+
+	evictWithFiller();
+	expect(trigger.isConnected).toBe(false);
+
+	fireEvent.click(within(detailDialog()).getByRole("button", { name: "Close" }));
+	await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull());
+
+	// Never the body, never whichever row happens to sit where the old one did,
+	// and never the Freeze button: a stable anchor in the region the reader was
+	// reading. React Aria's own deferred restore runs after this and, finding
+	// focus already placed, leaves it alone.
+	const region = screen.getByRole("region", { name: "Live queries" });
+	expect(document.activeElement).toBe(region);
+	await act(() => new Promise((resolve) => requestAnimationFrame(() => resolve(undefined))));
+	expect(document.activeElement).toBe(region);
 });
 
 test("the route renders the live ring at its production capacity", async () => {
@@ -391,34 +510,29 @@ test("an open streamed detail survives Freeze and Resume", async () => {
 	await openLive();
 	act(() => sources[0]!.emit("query", frame(1000, "held.example")));
 	fireEvent.click(screen.getByRole("button", { name: "held.example" }));
+	const snapshot = detailDialog().textContent;
 
-	fireEvent.click(screen.getByRole("button", { name: "Freeze" }));
+	// Freeze is behind the dialog, so it is reached the way the code reaches it
-	expect(screen.getByRole("heading", { level: 1, name: "held.example" })).toBeTruthy();
+	// rather than by role, which the modal deliberately hides.
-	fireEvent.click(screen.getByRole("button", { name: "Resume" }));
+	const freeze = () => screen.getByText("Freeze") as HTMLButtonElement;
-	expect(screen.getByRole("heading", { level: 1, name: "held.example" })).toBeTruthy();
+	act(() => freeze().click());
+	expect(detailDialog().textContent).toBe(snapshot);
+	act(() => (screen.getByText("Resume") as HTMLButtonElement).click());
+	expect(detailDialog().textContent).toBe(snapshot);
 });
 
-test("the filter row stays visible, keeps its values, and is out of the tab order", async () => {
+test("live renders no filter toolbar, not even a disabled one", async () => {
 	await openLive("/activity?mode=live&domain=ads&client=192.0.2.10&blocked=true");
 
-	const domain = screen.getByLabelText("Domain contains") as HTMLInputElement;
+	// The stream is unfiltered — the server sends every query — so a row of
-	expect(domain.value).toBe("ads");
+	// controls here would promise filtering that is not happening. The filters
-	expect(domain.disabled).toBe(true);
+	// are not lost: they are in the URL, and History applies them on the way back.
-	expect((screen.getByLabelText("Client (exact)") as HTMLInputElement).disabled).toBe(true);
+	expect(screen.queryByLabelText("Filter domains")).toBeNull();
-	expect((screen.getByLabelText("Since") as HTMLInputElement).disabled).toBe(true);
+	expect(screen.queryByLabelText("Client IP (exact match)")).toBeNull();
-	expect((screen.getByLabelText("Until") as HTMLInputElement).disabled).toBe(true);
+	expect(screen.queryByRole("radio", { name: "Blocked" })).toBeNull();
-
+	expect(screen.queryByRole("button", { name: /^Time: / })).toBeNull();
-	const form = domain.closest("form")!;
+	expect(screen.queryByText("Clear")).toBeNull();
-	const controls = [...form.querySelectorAll("input, button, select, textarea, a[href], [tabindex]")];
+	expect(screen.getByText(/the History filters apply to history only/)).toBeTruthy();
-	expect(controls.length).toBeGreaterThan(0);
-	for (const control of controls) {
-		// A disabled form control is skipped by the browser's tab order, and RAC
-		// pins its own trigger out of it as well. Nothing in the row may
-		// reintroduce itself with a reachable tabindex.
-		expect(control.hasAttribute("disabled")).toBe(true);
-		const tabindex = control.getAttribute("tabindex");
-		expect(tabindex === null || tabindex === "-1").toBe(true);
-	}
 });
 
 test("live mode asks for no query pages, whatever filters the url retained", async () => {
@@ -431,31 +545,30 @@ test("live mode asks for no query pages, whatever filters the url retained", asy
 test("leaving live closes the stream, and coming back opens exactly one fresh one", async () => {
 	await openLive("/activity?mode=live&domain=ads");
 
-	fireEvent.click(screen.getByRole("button", { name: "History" }));
+	fireEvent.click(screen.getByRole("tab", { name: "History" }));
-	await screen.findByRole("button", { name: "Apply filters" });
+	await screen.findByLabelText("Filter domains");
 	expect(sources).toHaveLength(1);
 	expect(sources[0]!.closed).toBe(true);
 	// The filters came along, which is the point of switching rather than
 	// navigating: the reader keeps the question they were asking.
-	expect((screen.getByLabelText("Domain contains") as HTMLInputElement).value).toBe("ads");
+	expect((screen.getByLabelText("Filter domains") as HTMLInputElement).value).toBe("ads");
-	expect((screen.getByLabelText("Domain contains") as HTMLInputElement).disabled).toBe(false);
 
-	fireEvent.click(screen.getByRole("button", { name: "Live" }));
+	fireEvent.click(screen.getByRole("tab", { name: "Live" }));
 	await screen.findByRole("button", { name: "Freeze" });
 	expect(sources).toHaveLength(2);
 	expect(sources[1]!.closed).toBe(false);
 });
 
-/**
+/** The related-actions region of a query detail. */
- * The related-actions region of a query detail. Scoped on purpose: the sidebar
- * carries a Pause of its own, and this is the one that answers "this query was
- * blocked and should not have been".
- */
 function related(): HTMLElement {
 	return screen.getByRole("region", { name: "Related" });
 }
 
-test("a streamed blocked row carries the same Pause action as the persisted detail", async () => {
+/**
+ * The streamed detail carries the same Related as the persisted one: four links
+ * and no control. Pause is resolver-wide and lives in the sidebar alone.
+ */
+test("a streamed blocked row's Related carries links only", async () => {
 	await openLive();
 	act(() =>
 		sources[0]!.emit(
@@ -468,14 +581,7 @@ test("a streamed blocked row carries the same Pause action as the persisted deta
 	);
 	fireEvent.click(screen.getByRole("button", { name: "streamed.example" }));
 
-	await waitFor(() => expect(within(related()).getByRole("button", { name: "Pause" })).toBeTruthy());
+	await waitFor(() => expect(within(related()).getByText("Diagnostics around this query")).toBeTruthy());
-});
+	expect(within(related()).getAllByRole("link")).toHaveLength(4);
-
+	expect(within(related()).queryByRole("button")).toBeNull();
-test("a streamed row that was allowed offers nothing to pause", async () => {
-	await openLive();
-	act(() => sources[0]!.emit("query", frame(1001, "allowed.example", { policy: { action: "allow" } })));
-	fireEvent.click(screen.getByRole("button", { name: "allowed.example" }));
-
-	await screen.findByRole("heading", { level: 1, name: "allowed.example" });
-	expect(within(related()).queryByRole("button", { name: "Pause" })).toBeNull();
 });

admin/src/features/activity/LiveActivity.tsx

@@ -1,6 +1,6 @@
 /**
- * Activity in live mode: the SSE stream, its bounded ring buffer, and the
+ * Activity in live mode: the SSE stream, its bounded ring buffer, and the modal
- * in-place detail a streamed row opens.
+ * detail a streamed row opens.
  *
  * This subtree is mounted only while the URL says `mode=live`, which is what
  * closes the EventSource on the way back to history: the connection is a
@@ -17,6 +17,7 @@ import { Link } from "@tanstack/react-router";
 import * as stylex from "@stylexjs/stylex";
 import { useClientNames } from "@/features/clients/clientNames";
 import { summarizeEvent } from "@/features/provenance/querySummary";
+import Dialog from "@/ui/Dialog";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
 import { ActivityCells, ActivityTableHead, activityDomainLink } from "./cells";
@@ -88,6 +89,7 @@ const styles = stylex.create({
 		lineHeight: "1.25rem",
 	},
 	dismiss: {
+		cursor: { default: "pointer", ":disabled": "not-allowed" },
 		borderStyle: "none",
 		backgroundColor: "transparent",
 		padding: 0,
@@ -161,29 +163,6 @@ const styles = stylex.create({
 		textDecorationLine: "underline",
 		textDecorationStyle: "dotted",
 	},
-	detailPanel: {
-		marginTop: "1rem",
-		borderRadius: "0.25rem",
-		borderWidth: 1,
-		borderStyle: "solid",
-		borderColor: colors.borderStrong,
-		backgroundColor: colors.surface,
-		padding: "1rem",
-	},
-	detailBar: {
-		display: "flex",
-		alignItems: "baseline",
-		justifyContent: "space-between",
-		gap: "0.75rem",
-	},
-	detailLabel: {
-		fontSize: "0.75rem",
-		lineHeight: "1rem",
-		fontWeight: 600,
-		letterSpacing: "0.05em",
-		textTransform: "uppercase",
-		color: colors.textMuted,
-	},
 	footnote: {
 		marginTop: "0.75rem",
 		fontSize: "0.875rem",
@@ -192,10 +171,6 @@ const styles = stylex.create({
 	},
 });
 
-/** One panel at a time, so the trigger that opened it can name it in `aria-controls`. */
-const DETAIL_PANEL_ID = "live-query-detail";
-const DETAIL_LABEL_ID = "live-query-detail-label";
-
 const PILL_LABELS: Record<StreamStatus, string> = {
 	connecting: "Connecting…",
 	open: "Live",
@@ -225,40 +200,15 @@ function StatusPill({ status }: { status: StreamStatus }) {
  *
  * The buffer is a 500-row ring that a gap merge also rewrites: a reference by
  * key would go stale under the reader while they were still reading it, and the
- * panel would blank out for no reason they could see. The snapshot is the whole
+ * dialog would blank out or swap under their eyes for no reason they could see.
- * fact — a streamed frame carries its own provenance — so it survives eviction,
+ * The snapshot is the whole fact — a streamed frame carries its own provenance
- * a merge and a Freeze/Resume, and closes only when the reader closes it or
+ * — so it survives eviction, a merge and a Freeze/Resume, and closes only when
- * leaves live mode.
+ * the reader closes it or leaves live mode. The stream behind it never stops.
  */
 function LiveDetail({ row, origin, onClose }: { row: StreamedRow; origin: ActivitySearch; onClose: () => void }) {
 	const summary = summarizeEvent(row.event);
-	const panel = useRef<HTMLDivElement>(null);
-
-	// The panel opens above the table, behind the trigger in tab order, so a
-	// forward tab from the row would walk past it. Focus moves in on open —
-	// keyed on the row, so choosing a second row moves it again — and the
-	// closer puts it back on the trigger.
-	useEffect(() => {
-		panel.current?.focus();
-	}, [row.key]);
-
 	return (
-		<div
+		<Dialog title="Streamed query" size="detail" isOpen onClose={onClose}>
-			ref={panel}
-			id={DETAIL_PANEL_ID}
-			tabIndex={-1}
-			role="group"
-			aria-labelledby={DETAIL_LABEL_ID}
-			{...stylex.props(styles.detailPanel)}
-		>
-			<div {...stylex.props(styles.detailBar)}>
-				<span id={DETAIL_LABEL_ID} {...stylex.props(styles.detailLabel)}>
-					Streamed query
-				</span>
-				<button type="button" onClick={onClose} {...stylex.props(shared.button, shared.focusRing)}>
-					Close
-				</button>
-			</div>
 			<ProvenanceDetail
 				provenance={row.event}
 				persistedId={null}
@@ -268,11 +218,10 @@ function LiveDetail({ row, origin, onClose }: { row: StreamedRow; origin: Activi
 						client={summary.client_ip}
 						ts={summary.ts}
 						origin={origin}
-						blocked={row.event.policy.action === "block"}
 					/>
 				}
 			/>
-		</div>
+		</Dialog>
 	);
 }
 
@@ -292,21 +241,36 @@ export default function LiveActivity({
 	const clientNames = useClientNames();
 	const [selected, setSelected] = useState<StreamedRow | null>(null);
 	const trigger = useRef<HTMLButtonElement | null>(null);
+	const results = useRef<HTMLDivElement>(null);
+	const restoring = useRef(false);
+
+	/**
+	 * Where focus lands when the dialog closes.
+	 *
+	 * React Aria restores focus itself, but in a `requestAnimationFrame` and
+	 * only while focus is still on the body — and its target is the row button,
+	 * which the ring may have evicted while the reader was reading. So this runs
+	 * in the effect that follows the focus scope's teardown and puts focus on a
+	 * connected element first: the row if it is still there, the results region
+	 * if it is not. React Aria's deferred pass then finds focus already placed
+	 * and does nothing, so the two never fight over it. If a navigation unmounts
+	 * this component the effect never runs, which is the right answer — there is
+	 * no longer a table to return to.
+	 */
+	useEffect(() => {
+		if (selected !== null || !restoring.current) return;
+		restoring.current = false;
+		const from = trigger.current;
+		trigger.current = null;
+		(from?.isConnected === true ? from : results.current)?.focus();
+	}, [selected]);
 
 	function open(row: StreamedRow, from: HTMLButtonElement) {
 		trigger.current = from;
+		restoring.current = true;
 		setSelected(row);
 	}
 
-	// The row that opened the panel takes focus back, unless the ring has
-	// already evicted it: a detached button cannot be focused, and the browser
-	// falls back to the document, which is the best available answer.
-	function close() {
-		setSelected(null);
-		trigger.current?.focus();
-		trigger.current = null;
-	}
-
 	return (
 		<>
 			<div {...stylex.props(styles.toolbar)}>
@@ -362,71 +326,81 @@ export default function LiveActivity({
 				</div>
 			)}
 
-			{selected !== null && <LiveDetail row={selected} origin={origin} onClose={close} />}
+			{/*
+			 * The region is the anchor focus falls back to when the row that
+			 * opened the dialog is gone, so it is rendered unconditionally: an
+			 * anchor that disappears with the last row is no anchor at all.
+			 */}
+			<div
+				ref={results}
+				tabIndex={-1}
+				role="region"
+				aria-label="Live queries"
+				{...stylex.props(shared.focusRing)}
+			>
+				{live.rows.length === 0 ? (
+					live.status !== "capped" && (
+						<p {...stylex.props(styles.empty)}>
+							{live.status === "open" ? "Waiting for queries…" : "No queries received yet."}
+						</p>
+					)
+				) : (
+					<>
+						<div {...stylex.props(styles.tableWrap)}>
+							<table {...stylex.props(styles.table)}>
+								<ActivityTableHead />
+								<tbody>
+									{live.rows.map((row) => {
+										const summary = summaryOf(row);
+										return (
+											<tr
+												key={row.key}
+												{...stylex.props(styles.row, summary.blocked && styles.rowBlocked)}
+											>
+												<ActivityCells
+													row={summary}
+													clientNames={clientNames}
+													renderDomain={(_id, children) =>
+														row.kind === "streamed" ? (
+															<button
+																type="button"
+																aria-haspopup="dialog"
+																onClick={(event) => open(row, event.currentTarget)}
+																{...stylex.props(
+																	styles.domainButton,
+																	activityDomainLink,
+																	shared.focusRing,
+																)}
+															>
+																{children}
+															</button>
+														) : (
+															<Link
+																to="/activity/queries/$id"
+																params={{ id: String(row.row.id) }}
+																search={origin}
+																{...stylex.props(activityDomainLink, shared.focusRing)}
+															>
+																{children}
+															</Link>
+														)
+													}
+												/>
+											</tr>
+										);
+									})}
+								</tbody>
+							</table>
+						</div>
+						<p {...stylex.props(styles.footnote)}>
+							Showing {live.rows.length} {live.rows.length === 1 ? "query" : "queries"} (newest first,
+							last {capacity} kept).
+						</p>
+					</>
+				)}
+			</div>
 
-			{live.rows.length === 0 ? (
+			{selected !== null && <LiveDetail row={selected} origin={origin} onClose={() => setSelected(null)} />}
-				live.status !== "capped" && (
-					<p {...stylex.props(styles.empty)}>
-						{live.status === "open" ? "Waiting for queries…" : "No queries received yet."}
-					</p>
-				)
-			) : (
-				<>
-					<div {...stylex.props(styles.tableWrap)}>
-						<table {...stylex.props(styles.table)}>
-							<ActivityTableHead />
-							<tbody>
-								{live.rows.map((row) => {
-									const summary = summaryOf(row);
-									return (
-										<tr
-											key={row.key}
-											{...stylex.props(styles.row, summary.blocked && styles.rowBlocked)}
-										>
-											<ActivityCells
-												row={summary}
-												clientNames={clientNames}
-												renderDomain={(_id, children) =>
-													row.kind === "streamed" ? (
-														<button
-															type="button"
-															aria-expanded={selected?.key === row.key}
-															aria-controls={
-																selected?.key === row.key ? DETAIL_PANEL_ID : undefined
-															}
-															onClick={(event) => open(row, event.currentTarget)}
-															{...stylex.props(
-																styles.domainButton,
-																activityDomainLink,
-																shared.focusRing,
-															)}
-														>
-															{children}
-														</button>
-													) : (
-														<Link
-															to="/activity/queries/$id"
-															params={{ id: String(row.row.id) }}
-															search={origin}
-															{...stylex.props(activityDomainLink, shared.focusRing)}
-														>
-															{children}
-														</Link>
-													)
-												}
-											/>
-										</tr>
-									);
-								})}
-							</tbody>
-						</table>
-					</div>
-					<p {...stylex.props(styles.footnote)}>
-						Showing {live.rows.length} {live.rows.length === 1 ? "query" : "queries"} (newest first, last{" "}
-						{capacity} kept).
-					</p>
-				</>
-			)}
 		</>
 	);
 }

admin/src/features/activity/RelatedActions.tsx

@@ -11,7 +11,6 @@
 
 import { Link } from "@tanstack/react-router";
 import * as stylex from "@stylexjs/stylex";
-import PauseControl from "@/features/pause/PauseControl";
 import { styles as shared } from "@/ui/styles";
 import { provenanceRelatedLink } from "./ProvenanceDetail";
 import { diagnosticsBounds, relatedBounds } from "./relatedLinks";
@@ -24,15 +23,9 @@ interface Props {
 	ts: number;
 	/** The Activity search the reader came from; its bounds win over the defaults. */
 	origin: Pick<ActivitySearch, "since" | "until">;
-	/**
-	 * This query was blocked. Pausing is a valid answer to a block the reader
-	 * disagrees with, and to nothing else here — so the control appears for a
-	 * block and not beside an allowed query it could not have caused.
-	 */
-	blocked: boolean;
 }
 
-export default function RelatedActions({ domain, client, ts, origin, blocked }: Props) {
+export default function RelatedActions({ domain, client, ts, origin }: Props) {
 	const bounds = relatedBounds(ts, origin);
 	const window = diagnosticsBounds(ts);
 	return (
@@ -61,7 +54,6 @@ export default function RelatedActions({ domain, client, ts, origin, blocked }:
 			>
 				Diagnostics around this query
 			</Link>
-			{blocked && <PauseControl />}
 		</>
 	);
 }

admin/src/features/clients/ClientEditDialog.tsx

@@ -18,16 +18,10 @@ interface Props {
 }
 
 const styles = stylex.create({
-	heading: {
-		fontSize: "1.125rem",
-		lineHeight: "1.75rem",
-		fontWeight: 600,
-	},
 	form: {
 		display: "flex",
 		flexDirection: "column",
 		gap: "1rem",
-		marginTop: "1rem",
 	},
 	fieldLabel: {
 		display: "block",
@@ -67,8 +61,7 @@ export default function ClientEditDialog({ client, groups, onClose }: Props) {
 	const readOnly = useReadOnlyConfig();
 
 	return (
-		<Dialog label={`Edit client ${client.ip}`} isOpen onClose={onClose}>
+		<Dialog title={`Edit client ${client.ip}`} isOpen onClose={onClose}>
-			<h2 {...stylex.props(styles.heading)}>Edit {client.ip}</h2>
 			<form
 				{...stylex.props(styles.form)}
 				onSubmit={(event) => {

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

@@ -1,6 +1,20 @@
 import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
 import { ClientName, type ClientNames } from "./clientNames";
-import { BASE, MANAGED_FILE, NEVER, renderClientsPage, setConfigStatus } from "./testFixtures";
+import { BASE, CLIENTS, MANAGED_FILE, NEVER, renderClientsPage, setConfigStatus } from "./testFixtures";
+
+/** The text of the elements an input points at with `aria-describedby`. */
+function describedText(input: HTMLElement): string {
+	const ids = input.getAttribute("aria-describedby");
+	if (ids === null) throw new Error("input has no aria-describedby");
+	return ids
+		.split(/\s+/)
+		.map((id) => {
+			const node = document.getElementById(id);
+			if (node === null) throw new Error(`aria-describedby names missing element ${id}`);
+			return node.textContent ?? "";
+		})
+		.join(" ");
+}
 
 function clientRow(ip: string): HTMLElement {
 	const row = screen.getByText(ip).closest("tr");
@@ -73,6 +87,39 @@ test("the address links to the client's detail page", async () => {
 	expect(link.getAttribute("href")).toBe("/clients/1");
 });
 
+test("delete asks first, naming the row, and the confirmation carries out the delete", async () => {
+	const { fetchMock } = await renderClientsPage({ ...BASE, "DELETE /api/clients/2": {} });
+
+	fireEvent.click(within(clientRow("192.168.1.11")).getByRole("button", { name: "Delete" }));
+
+	const dialog = await screen.findByRole("alertdialog", { name: "Delete client" });
+	// The operator has to be able to tell from the dialog alone which row this is.
+	expect(within(dialog).getByText(/kids-tablet\.lan \(192\.168\.1\.11\)/)).toBeTruthy();
+	expect(within(dialog).getByText(/re-materialize on their next DNS query/)).toBeTruthy();
+	// Asking is not deleting.
+	expect(fetchMock.mock.calls.filter(([, init]) => init?.method === "DELETE")).toEqual([]);
+
+	fireEvent.click(within(dialog).getByRole("button", { name: "Delete" }));
+	await waitFor(() =>
+		expect(
+			fetchMock.mock.calls.filter(([input, init]) => init?.method === "DELETE" && String(input).endsWith("/2")),
+		).toHaveLength(1),
+	);
+	await waitFor(() => expect(screen.queryByRole("alertdialog")).toBeNull());
+});
+
+test("cancelling the confirmation keeps the client", async () => {
+	const { fetchMock } = await renderClientsPage({ ...BASE, "DELETE /api/clients/2": {} });
+
+	fireEvent.click(within(clientRow("192.168.1.11")).getByRole("button", { name: "Delete" }));
+	const dialog = await screen.findByRole("alertdialog", { name: "Delete client" });
+	fireEvent.click(within(dialog).getByRole("button", { name: "Cancel" }));
+
+	await waitFor(() => expect(screen.queryByRole("alertdialog")).toBeNull());
+	expect(screen.getByText("192.168.1.11")).toBeTruthy();
+	expect(fetchMock.mock.calls.filter(([, init]) => init?.method === "DELETE")).toEqual([]);
+});
+
 test("shows the DNS-activity empty state when there are no clients", async () => {
 	await renderClientsPage({ ...BASE, "GET /api/clients": { clients: [] } });
 
@@ -140,9 +187,15 @@ test("an unknown group id filters to nothing and offers a way out", async () =>
 	expect(router.state.location.search).toEqual({});
 });
 
+// Both statuses lock the declared delete, but only file authority proves the
+// file declares the row; the anchors keep the two sentences apart.
+const DECLARED_NOTE = /^This client is declared in the configuration file/;
+const UNKNOWN_NOTE = /^nxdns cannot say whether this client is declared/;
 test("file mode drops every edit affordance and keeps the observed delete live (R2-4)", async () => {
 	await renderClientsPage({ ...BASE, "GET /api/config/status": MANAGED_FILE });
-	await screen.findAllByLabelText(/Managed by \/etc\/nxdns\/config\.zon/);
+	// The settled sentence, not the tag: "Locked" is already on screen while
+	// authority is pending, so waiting on it would not wait for this status.
+	await screen.findAllByText(/^Managed by \/etc\/nxdns\/config\.zon/);
 
 	expect(screen.queryAllByRole("button", { name: "Edit" })).toEqual([]);
 
@@ -150,6 +203,34 @@ test("file mode drops every edit affordance and keeps the observed delete live (
 	const observed = clientRow("192.168.1.11");
 	expect((within(declared).getByRole("button", { name: "Delete" }) as HTMLButtonElement).disabled).toBe(true);
 	expect((within(observed).getByRole("button", { name: "Delete" }) as HTMLButtonElement).disabled).toBe(false);
+
+	// Why the locked Delete will not answer, in visible text and exactly once:
+	// per row it would repeat down the whole page, and on the button it was a
+	// title that a keyboard and a touch screen never reached.
+	expect(screen.getAllByText(DECLARED_NOTE, { selector: "p" })).toHaveLength(1);
+	expect(within(declared).queryByText(DECLARED_NOTE, { selector: "p" })).toBeNull();
+	// The description stays on the button itself too, for a reader on that control.
+	const locked = within(declared).getByRole("button", { name: "Delete" });
+	expect(document.getElementById(locked.getAttribute("aria-describedby") ?? "")?.textContent).toMatch(DECLARED_NOTE);
+});
+
+test("an all-observed page still says why Edit is gone, with no delete note to carry it", async () => {
+	// Every row observed, so no Delete is locked. The edit lock is still real, and
+	// "Locked" appearing with nothing to explain it is the failure this guards.
+	const observedOnly = { clients: [CLIENTS.clients[1]] };
+	await renderClientsPage({
+		...BASE,
+		"GET /api/clients": observedOnly,
+		"GET /api/config/status": MANAGED_FILE,
+	});
+	// The settled sentence is both the anchor and the assertion: it is the whole
+	// explanation for the missing Edit action.
+	await screen.findAllByText(/^Managed by \/etc\/nxdns\/config\.zon/);
+	expect(await screen.findAllByText("Locked")).not.toHaveLength(0);
+
+	// The delete sentence belongs only to a row that has one.
+	expect(screen.queryByText(DECLARED_NOTE)).toBeNull();
+	expect((screen.getByRole("button", { name: "Delete" }) as HTMLButtonElement).disabled).toBe(false);
 });
 
 test("file mode renders network assignments with no mutation control at all (R2-4)", async () => {
@@ -170,7 +251,7 @@ test("file mode renders network assignments with no mutation control at all (R2-
 
 test("a failed config status exposes no configuration mutation, and still deletes an observed client (R3-4)", async () => {
 	await renderClientsPage({ ...BASE, "GET /api/config/status": undefined });
-	await screen.findAllByLabelText(/Configuration status unavailable/);
+	await screen.findAllByText(/^Configuration status unavailable/);
 
 	expect(screen.queryAllByRole("button", { name: "Edit" })).toEqual([]);
 	expect(screen.queryByRole("button", { name: "Save assignments" })).toBeNull();
@@ -186,10 +267,6 @@ test("a failed config status exposes no configuration mutation, and still delete
 // confirmation is already open. `undefined` is the failed status: the fetch stub
 // answers 404 for a key it does not hold.
 //
-// Both statuses lock the declared delete, but only file authority proves the
-// file declares the row; the anchors keep the two sentences apart.
-const DECLARED_NOTE = /^This client is declared in the configuration file/;
-const UNKNOWN_NOTE = /^nxdns cannot say whether this client is declared/;
 describe.each([
 	["file authority", MANAGED_FILE, DECLARED_NOTE, UNKNOWN_NOTE],
 	["a failed status", undefined, UNKNOWN_NOTE, DECLARED_NOTE],
@@ -212,13 +289,13 @@ describe.each([
 		expect(within(dialog).queryByRole("button", { name: "Save" })).toBeNull();
 		expect((within(dialog).getByLabelText("Name") as HTMLInputElement).value).toBe("laptop");
 		expect(within(dialog).getByText(/can no longer be saved/)).toBeTruthy();
-		expect(within(dialog).getByLabelText(/^Locked\./)).toBeTruthy();
+		expect(within(dialog).getByText("Locked")).toBeTruthy();
 
 		fireEvent.click(within(dialog).getByRole("button", { name: "Cancel" }));
 		await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull());
 	});
 
-	test("locks an open declared-client delete confirmation and leaves cancel working", async () => {
+	test("locks an open declared-client delete confirmation in place and leaves cancel working", async () => {
 		const map = { ...BASE };
 		const { queryClient, fetchMock } = await renderClientsPage(map);
 		// The Edit affordance appearing is the proof authority resolved to
@@ -227,23 +304,68 @@ describe.each([
 
 		const declared = clientRow("192.168.1.10");
 		fireEvent.click(within(declared).getByRole("button", { name: "Delete" }));
-		expect(within(clientRow("192.168.1.10")).getByRole("button", { name: "Confirm delete" })).toBeTruthy();
+		const dialog = await screen.findByRole("alertdialog", { name: "Delete client" });
 
 		await setConfigStatus(map, queryClient, status);
 
-		const confirming = clientRow("192.168.1.10");
+		// The dialog stays put. Closing it would throw focus at the Delete button
-		expect(within(confirming).queryByRole("button", { name: "Confirm delete" })).toBeNull();
+		// the same turn disabled, and the reason would survive only as a title
-		expect(within(confirming).getByText(lockNote)).toBeTruthy();
+		// attribute; here the reason is the dialog's own message.
-		expect(within(confirming).queryByText(otherNote)).toBeNull();
+		await waitFor(() => expect(within(dialog).queryByRole("button", { name: "Delete" })).toBeNull());
-		expect(within(confirming).getByLabelText(/^Locked\./)).toBeTruthy();
+		expect(within(dialog).getByText(lockNote)).toBeTruthy();
+		expect(within(dialog).queryByText(otherNote)).toBeNull();
+		expect(within(dialog).getByText("Locked")).toBeTruthy();
 
-		fireEvent.click(within(confirming).getByRole("button", { name: "Cancel" }));
+		fireEvent.click(within(dialog).getByRole("button", { name: "Cancel" }));
-		await waitFor(() =>
+		await waitFor(() => expect(screen.queryByRole("alertdialog")).toBeNull());
-			expect(within(clientRow("192.168.1.10")).getByRole("button", { name: "Delete" })).toBeTruthy(),
-		);
 		expect(fetchMock.mock.calls.filter(([, init]) => init?.method === "DELETE")).toEqual([]);
 	});
 
+	test("a cancelled confirmation stays closed when authority comes back", async () => {
+		const map = { ...BASE };
+		const { queryClient } = await renderClientsPage(map);
+		await unlockedEdit(0);
+
+		fireEvent.click(within(clientRow("192.168.1.10")).getByRole("button", { name: "Delete" }));
+		const dialog = await screen.findByRole("alertdialog", { name: "Delete client" });
+		fireEvent.click(within(dialog).getByRole("button", { name: "Cancel" }));
+		await waitFor(() => expect(screen.queryByRole("alertdialog")).toBeNull());
+
+		// A poll that fails and then recovers must not raise a destructive
+		// question the operator already answered.
+		await setConfigStatus(map, queryClient, status);
+		await setConfigStatus(map, queryClient, BASE["GET /api/config/status"]);
+
+		await waitFor(() => expect(screen.getAllByRole("button", { name: "Edit" }).length).toBeGreaterThan(0));
+		expect(screen.queryByRole("alertdialog")).toBeNull();
+	});
+
+	test("the confirm action comes back when authority does, without a second prompt", async () => {
+		const map = { ...BASE, "DELETE /api/clients/1": {} };
+		const { queryClient, fetchMock } = await renderClientsPage(map);
+		await unlockedEdit(0);
+
+		fireEvent.click(within(clientRow("192.168.1.10")).getByRole("button", { name: "Delete" }));
+		const dialog = await screen.findByRole("alertdialog", { name: "Delete client" });
+
+		await setConfigStatus(map, queryClient, status);
+		await waitFor(() => expect(within(dialog).queryByRole("button", { name: "Delete" })).toBeNull());
+
+		await setConfigStatus(map, queryClient, BASE["GET /api/config/status"]);
+
+		// The question was never withdrawn, so the answer returns to the same
+		// dialog rather than asking the operator to start again.
+		const confirm = await within(dialog).findByRole("button", { name: "Delete" });
+		fireEvent.click(confirm);
+		await waitFor(() =>
+			expect(
+				fetchMock.mock.calls.filter(
+					([input, init]) => init?.method === "DELETE" && String(input).endsWith("/1"),
+				),
+			).toHaveLength(1),
+		);
+	});
+
 	test("keeps an open observed-client delete confirmation live (R3-4)", async () => {
 		const map = { ...BASE, "DELETE /api/clients/2": {} };
 		const { queryClient, fetchMock } = await renderClientsPage(map);
@@ -253,10 +375,11 @@ describe.each([
 
 		const observed = clientRow("192.168.1.11");
 		fireEvent.click(within(observed).getByRole("button", { name: "Delete" }));
+		const dialog = await screen.findByRole("alertdialog", { name: "Delete client" });
 
 		await setConfigStatus(map, queryClient, status);
 
-		fireEvent.click(within(clientRow("192.168.1.11")).getByRole("button", { name: "Confirm delete" }));
+		fireEvent.click(within(dialog).getByRole("button", { name: "Delete" }));
 		await waitFor(() =>
 			expect(
 				fetchMock.mock.calls.filter(
@@ -271,7 +394,7 @@ test("a pending config status holds the same line as a failed one (R3-4)", async
 	// The status request never settles, so authority stays pending for the whole
 	// test: nothing configuration owns may be offered on that guess.
 	await renderClientsPage({ ...BASE, "GET /api/config/status": NEVER });
-	await screen.findAllByLabelText(/Checking which configuration source/);
+	await screen.findAllByText(/^Checking which configuration source/);
 
 	expect(screen.queryAllByRole("button", { name: "Edit" })).toEqual([]);
 	expect(screen.queryByRole("button", { name: "Save assignments" })).toBeNull();
@@ -280,3 +403,66 @@ test("a pending config status holds the same line as a failed one (R3-4)", async
 	const observed = clientRow("192.168.1.11");
 	expect((within(observed).getByRole("button", { name: "Delete" }) as HTMLButtonElement).disabled).toBe(false);
 });
+
+test("a save-time problem marks the input it is about and describes it", async () => {
+	await renderClientsPage();
+
+	const range = (await screen.findByLabelText("Range 1")) as HTMLInputElement;
+	fireEvent.change(range, { target: { value: "" } });
+	fireEvent.click(screen.getByRole("button", { name: "Save assignments" }));
+
+	expect(range.getAttribute("aria-invalid")).toBe("true");
+	expect(describedText(range)).toBe("Row 1: prefix is required.");
+
+	// Only the offending input is marked; the priority beside it is untouched.
+	const priority = screen.getByLabelText("Priority for range 1");
+	expect(priority.getAttribute("aria-invalid")).toBeNull();
+	expect(priority.getAttribute("aria-describedby")).toBeNull();
+
+	fireEvent.change(range, { target: { value: "10.0.0.0/8" } });
+	fireEvent.change(screen.getByLabelText("Priority for range 1"), { target: { value: "abc" } });
+	fireEvent.click(screen.getByRole("button", { name: "Save assignments" }));
+
+	expect(range.getAttribute("aria-invalid")).toBeNull();
+	expect(describedText(screen.getByLabelText("Priority for range 1"))).toBe(
+		"Row 1: priority must be a whole number.",
+	);
+});
+
+test("removing a row drops the message rather than moving it to another input", async () => {
+	await renderClientsPage();
+
+	// Row 1 is the offending one, so removing it is what would slide the stale
+	// index onto row 2 — an input that validated cleanly.
+	const range = (await screen.findByLabelText("Range 1")) as HTMLInputElement;
+	fireEvent.change(range, { target: { value: "" } });
+	fireEvent.click(screen.getByRole("button", { name: "Add range" }));
+	fireEvent.change(screen.getByLabelText("Range 2"), { target: { value: "10.0.0.0/8" } });
+	fireEvent.click(screen.getByRole("button", { name: "Save assignments" }));
+
+	expect(range.getAttribute("aria-invalid")).toBe("true");
+	expect(describedText(range)).toBe("Row 1: prefix is required.");
+
+	const section = assignmentsSection();
+	fireEvent.click(within(section).getAllByRole("button", { name: "Remove" })[0] as HTMLButtonElement);
+
+	const survivor = screen.getByLabelText("Range 1") as HTMLInputElement;
+	expect(survivor.value).toBe("10.0.0.0/8");
+	expect(survivor.getAttribute("aria-invalid")).toBeNull();
+	expect(survivor.getAttribute("aria-describedby")).toBeNull();
+	expect(within(section).queryByRole("alert")).toBeNull();
+	expect(screen.queryByLabelText("Range 2")).toBeNull();
+});
+
+test("editing a row clears the message it was about", async () => {
+	await renderClientsPage();
+
+	const range = (await screen.findByLabelText("Range 1")) as HTMLInputElement;
+	fireEvent.change(range, { target: { value: "" } });
+	fireEvent.click(screen.getByRole("button", { name: "Save assignments" }));
+	expect(range.getAttribute("aria-invalid")).toBe("true");
+
+	fireEvent.change(range, { target: { value: "10.0.0.0/8" } });
+	expect(range.getAttribute("aria-invalid")).toBeNull();
+	expect(within(assignmentsSection()).queryByRole("alert")).toBeNull();
+});

admin/src/features/clients/ClientsPage.tsx

@@ -9,7 +9,8 @@ import ClientEditDialog from "./ClientEditDialog";
 import NetworkAssignments from "./NetworkAssignments";
 import { ClientDisplayName } from "./clientIdentity";
 import InlineError from "@/lib/InlineError";
-import ConfigLockIndicator from "@/features/configuration/ConfigLockIndicator";
+import ConfirmDialog from "@/ui/ConfirmDialog";
+import ConfigLockIndicator, { lockReason } from "@/features/configuration/ConfigLockIndicator";
 import { useAuthority, useReadOnlyConfig, type Authority } from "@/features/configuration/authority";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
@@ -24,6 +25,9 @@ import { colors } from "@/ui/tokens.stylex";
  * alone cannot say which operator surface set the row — so the sentence names
  * the doubt rather than asserting a declaration, the way `provenanceOf` does.
  */
+/** The one note every locked Delete on this page describes itself with. */
+const DELETE_LOCK_NOTE_ID = "clients-delete-locked-note";
+
 function declaredDeleteNote(authority: Authority): string {
 	if (authority.state === "resolved") {
 		return "This client is declared in the configuration file; remove it there and restart.";
@@ -31,6 +35,16 @@ function declaredDeleteNote(authority: Authority): string {
 	return "nxdns cannot say whether this client is declared in the configuration file until it reports its configuration status, so deleting it stays locked.";
 }
 
+/**
+ * How the confirmation names the row. The address is always there and always
+ * unique, so it carries the sentence; a name the operator recognizes leads when
+ * the row has one.
+ */
+function clientLabel(client: Client): string {
+	const name = client.name !== "" ? client.name : client.learned_name;
+	return name === "" ? client.ip : `${name} (${client.ip})`;
+}
+
 const styles = stylex.create({
 	heading: {
 		fontSize: "1.5rem",
@@ -41,6 +55,15 @@ const styles = stylex.create({
 		marginTop: "1rem",
 		color: colors.textMuted,
 	},
+	lockNote: {
+		marginTop: "1rem",
+		display: "flex",
+		flexDirection: "column",
+		gap: "0.25rem",
+		fontSize: "0.875rem",
+		lineHeight: "1.25rem",
+		color: colors.textMuted,
+	},
 	filterBar: {
 		marginTop: "1rem",
 		display: "flex",
@@ -79,23 +102,11 @@ const styles = stylex.create({
 		color: colors.primaryOnSurface,
 		textDecorationLine: "none",
 	},
-	confirmGroup: {
-		display: "inline-flex",
-		flexWrap: "wrap",
-		alignItems: "center",
-		justifyContent: "flex-end",
-		gap: "0.5rem",
-	},
 	actionGroup: {
 		display: "inline-flex",
 		alignItems: "center",
 		gap: "0.5rem",
 	},
-	note: {
-		fontSize: "0.75rem",
-		lineHeight: "1rem",
-		color: colors.textMuted,
-	},
 	dangerText: {
 		color: colors.danger,
 	},
@@ -112,7 +123,7 @@ export default function ClientsPage() {
 	const queryClient = useQueryClient();
 	const deleteMutation = useMutation(clientDeleteMutation(queryClient));
 	const [editing, setEditing] = useState<Client | null>(null);
-	const [confirmingId, setConfirmingId] = useState<number | null>(null);
+	const [pendingDelete, setPendingDelete] = useState<Client | null>(null);
 	const readOnly = useReadOnlyConfig();
 	const authority = useAuthority();
 
@@ -122,6 +133,17 @@ export default function ClientsPage() {
 	const filterGroup: Group | undefined = group === undefined ? undefined : groups.find((row) => row.id === group);
 	const rows = group === undefined ? clients : clients.filter((client) => client.group_id === group);
 
+	// Authority is polled, so it can turn while the confirmation is open. The
+	// dialog reads it on every render rather than trusting the state that opened
+	// it, and withdraws the answer that would now fail instead of withdrawing the
+	// question: the operator is told why, and only they close the dialog.
+	const deleteLocked = pendingDelete !== null && readOnly && pendingDelete.hand_edited;
+
+	// The reason a locked Delete will not answer, printed once above the table.
+	// Per row it would repeat down the whole page; on the button it was a `title`
+	// that a keyboard and a touch screen never reached.
+	const deletesLocked = readOnly && rows.some((client) => client.hand_edited);
+
 	return (
 		<section>
 			<h1 {...stylex.props(styles.heading)}>Clients</h1>
@@ -137,6 +159,15 @@ export default function ClientsPage() {
 					</Link>
 				</div>
 			)}
+			{/* The whole explanation for this page's locks, printed once. Per row it
+			    would repeat down the table; on the controls it was a `title` that a
+			    keyboard and a touch screen never reached. */}
+			{readOnly && (
+				<div {...stylex.props(styles.lockNote)}>
+					<p>{lockReason(authority)}.</p>
+					{deletesLocked && <p id={DELETE_LOCK_NOTE_ID}>{declaredDeleteNote(authority)}</p>}
+				</div>
+			)}
 			{clients.length === 0 ? (
 				<p {...stylex.props(styles.empty)}>
 					No clients yet. Rows appear automatically as devices on the network make DNS queries — there is
@@ -178,77 +209,37 @@ export default function ClientsPage() {
 									<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.right)}>
-										{confirmingId === client.id ? (
+										<span {...stylex.props(styles.actionGroup)}>
-											<span {...stylex.props(styles.confirmGroup)}>
+											{/* Naming a client writes configuration, so the affordance is
-												{/* Authority is polled, so it can turn while a confirmation
+											    absent — not disabled — wherever the write cannot land. */}
-												    sits open. The confirm path reads it on every render
+											{readOnly ? (
-												    rather than trusting the state that opened it. */}
+												<ConfigLockIndicator compact />
-												<span {...stylex.props(styles.note)}>
+											) : (
-													{readOnly && client.hand_edited
-														? declaredDeleteNote(authority)
-														: "Deleted clients re-materialize on their next DNS query."}
-												</span>
-												{readOnly && client.hand_edited ? (
-													<ConfigLockIndicator />
-												) : (
-													<button
-														type="button"
-														onClick={() => {
-															setConfirmingId(null);
-															deleteMutation.mutate(client.id);
-														}}
-														{...stylex.props(
-															shared.smallButton,
-															styles.dangerText,
-															shared.focusRing,
-														)}
-													>
-														Confirm delete
-													</button>
-												)}
 												<button
 													type="button"
-													onClick={() => setConfirmingId(null)}
+													onClick={() => setEditing(client)}
 													{...stylex.props(shared.smallButton, shared.focusRing)}
 												>
-													Cancel
+													Edit
 												</button>
-											</span>
+											)}
-										) : (
+											<button
-											<span {...stylex.props(styles.actionGroup)}>
+												type="button"
-												{/* Naming a client writes configuration, so the affordance is
+												onClick={() => setPendingDelete(client)}
-												    absent — not disabled — wherever the write cannot land. */}
+												disabled={readOnly && client.hand_edited}
-												{readOnly ? (
+												aria-describedby={
-													<ConfigLockIndicator />
+													readOnly && client.hand_edited ? DELETE_LOCK_NOTE_ID : undefined
-												) : (
+												}
-													<button
+												{...stylex.props(
-														type="button"
+													shared.smallButton,
-														onClick={() => setEditing(client)}
+													styles.dangerText,
-														{...stylex.props(shared.smallButton, shared.focusRing)}
+													styles.dimWhenDisabled,
-													>
+													shared.focusRing,
-														Edit
-													</button>
 												)}
-												<button
+											>
-													type="button"
+												Delete
-													onClick={() => setConfirmingId(client.id)}
+											</button>
-													disabled={readOnly && client.hand_edited}
+										</span>
-													title={
-														readOnly && client.hand_edited
-															? declaredDeleteNote(authority)
-															: undefined
-													}
-													{...stylex.props(
-														shared.smallButton,
-														styles.dangerText,
-														styles.dimWhenDisabled,
-														shared.focusRing,
-													)}
-												>
-													Delete
-												</button>
-											</span>
-										)}
 									</td>
 								</tr>
 							))}
@@ -256,6 +247,24 @@ export default function ClientsPage() {
 					</table>
 				</div>
 			)}
+			<ConfirmDialog
+				isOpen={pendingDelete !== null}
+				title="Delete client"
+				message={
+					pendingDelete === null
+						? ""
+						: deleteLocked
+							? declaredDeleteNote(authority)
+							: `Delete ${clientLabel(pendingDelete)}? Deleted clients re-materialize on their next DNS query.`
+				}
+				confirmLabel="Delete"
+				lock={deleteLocked ? <ConfigLockIndicator /> : undefined}
+				onConfirm={() => {
+					if (pendingDelete !== null) deleteMutation.mutate(pendingDelete.id);
+					setPendingDelete(null);
+				}}
+				onCancel={() => setPendingDelete(null)}
+			/>
 			<InlineError error={deleteMutation.error} />
 			{editing !== null && <ClientEditDialog client={editing} groups={groups} onClose={() => setEditing(null)} />}
 			<NetworkAssignments prefixes={prefixes} groups={groups} />

admin/src/features/clients/NetworkAssignments.tsx

@@ -4,7 +4,15 @@ import * as stylex from "@stylexjs/stylex";
 import { clientPrefixesPutMutation } from "@/lib/queries";
 import type { ClientPrefix, Group } from "@/lib/types";
 import { defaultGroupId } from "@/lib/defaultGroup";
-import { firstProblem, initPrefixEditor, isDirty, prefixEditorReducer, toInputs } from "./prefixEditor";
+import {
+	firstProblem,
+	initPrefixEditor,
+	isDirty,
+	prefixEditorReducer,
+	toInputs,
+	type PrefixEditorAction,
+	type PrefixProblem,
+} from "./prefixEditor";
 import InlineError from "@/lib/InlineError";
 import AuthorityGate from "@/features/configuration/AuthorityGate";
 import Select from "@/ui/Select";
@@ -16,6 +24,9 @@ interface Props {
 	groups: Group[];
 }
 
+/** The editor is rendered once per page, so the message can hold a fixed id. */
+const VALIDATION_ID = "network-assignments-validation";
+
 const styles = stylex.create({
 	section: {
 		marginTop: "2.5rem",
@@ -65,6 +76,7 @@ const styles = stylex.create({
 		width: "5rem",
 	},
 	removeButton: {
+		cursor: { default: "pointer", ":disabled": "not-allowed" },
 		borderRadius: "0.25rem",
 		borderWidth: 1,
 		borderStyle: "solid",
@@ -161,12 +173,24 @@ function AssignmentsTable({ prefixes }: { prefixes: ClientPrefix[] }) {
 function AssignmentsEditor({ prefixes, groups }: Props) {
 	const queryClient = useQueryClient();
 	const mutation = useMutation(clientPrefixesPutMutation(queryClient));
-	const [state, dispatch] = useReducer(prefixEditorReducer, prefixes, initPrefixEditor);
+	const [state, apply] = useReducer(prefixEditorReducer, prefixes, initPrefixEditor);
-	const [validation, setValidation] = useState<string | null>(null);
+	const [validation, setValidation] = useState<PrefixProblem | null>(null);
 	const dirty = isDirty(state);
 	const fallbackGroupId = defaultGroupId(groups);
 	const groupOptions = groups.map((group) => ({ value: String(group.id), label: group.name }));
 
+	// A problem names a row by position, and every action here can move, add or
+	// delete a position. The message describes the rows Save read, so it dies
+	// with them rather than drifting onto whatever row inherits the index.
+	const dispatch = (action: PrefixEditorAction) => {
+		setValidation(null);
+		apply(action);
+	};
+
+	/** True for the one input the current message is about; nothing else is marked. */
+	const invalid = (index: number, field: PrefixProblem["field"]): true | undefined =>
+		validation !== null && validation.index === index && validation.field === field ? true : undefined;
+
 	const save = () => {
 		const problem = firstProblem(state.rows);
 		setValidation(problem);
@@ -187,6 +211,8 @@ function AssignmentsEditor({ prefixes, groups }: Props) {
 							<input
 								type="text"
 								aria-label={`Range ${index + 1}`}
+								aria-invalid={invalid(index, "prefix")}
+								aria-describedby={invalid(index, "prefix") && VALIDATION_ID}
 								placeholder="192.168.1.0/24"
 								value={row.prefix}
 								onChange={(event) =>
@@ -207,6 +233,8 @@ function AssignmentsEditor({ prefixes, groups }: Props) {
 								type="text"
 								inputMode="numeric"
 								aria-label={`Priority for range ${index + 1}`}
+								aria-invalid={invalid(index, "priority")}
+								aria-describedby={invalid(index, "priority") && VALIDATION_ID}
 								placeholder="100"
 								value={row.priority}
 								onChange={(event) =>
@@ -226,8 +254,8 @@ function AssignmentsEditor({ prefixes, groups }: Props) {
 				</ul>
 			)}
 			{validation !== null && (
-				<p role="alert" {...stylex.props(styles.validation)}>
+				<p id={VALIDATION_ID} role="alert" {...stylex.props(styles.validation)}>
-					{validation}
+					{validation.message}
 				</p>
 			)}
 			<InlineError error={mutation.error} />
@@ -250,10 +278,7 @@ function AssignmentsEditor({ prefixes, groups }: Props) {
 				{dirty && (
 					<button
 						type="button"
-						onClick={() => {
+						onClick={() => dispatch({ type: "reset", prefixes })}
-							setValidation(null);
-							dispatch({ type: "reset", prefixes });
-						}}
 						{...stylex.props(shared.button, shared.focusRing)}
 					>
 						Discard changes

admin/src/features/clients/clientNames.tsx

@@ -16,6 +16,14 @@ import * as stylex from "@stylexjs/stylex";
 import { clientsQuery } from "@/lib/queries";
 import type { Client } from "@/lib/types";
 import { styles as shared } from "@/ui/styles";
+import { colors } from "@/ui/tokens.stylex";
+
+const styles = stylex.create({
+	/** Secondary to the name it qualifies, and never the only thing in the cell. */
+	address: {
+		color: colors.textMuted,
+	},
+});
 
 export type ClientNames = ReadonlyMap<string, Pick<Client, "name" | "learned_name">>;
 
@@ -53,11 +61,13 @@ export function clientLabel(ip: string, names: ClientNames): { text: string; lea
 export function ClientName({ ip, names }: { ip: string; names: ClientNames }) {
 	const label = clientLabel(ip, names);
 	if (label === null) return <span {...stylex.props(shared.mono)}>{ip}</span>;
-	// The name replaces the address on screen, so the address stays reachable
+	// The name replaces the address, so the address follows it as real text that
-	// as the tooltip rather than disappearing from the row entirely.
+	// anyone can read and copy. A `title` carried it before, which reaches
+	// neither a keyboard nor a touch screen.
 	return (
-		<span title={ip} {...stylex.props(label.learned && shared.learnedName)}>
+		<span {...stylex.props(label.learned && shared.learnedName)}>
 			{label.text}
+			<span {...stylex.props(styles.address)}> ({ip})</span>
 		</span>
 	);
 }

admin/src/features/clients/prefixEditor.test.ts

@@ -76,11 +76,15 @@ test("toInputs trims prefixes, parses priorities and omits empty ones", () => {
 
 test("firstProblem flags empty prefixes and non-integer priorities", () => {
 	expect(firstProblem([{ prefix: "10.0.0.0/8", group_id: 1, priority: "" }])).toBeNull();
-	expect(firstProblem([{ prefix: "  ", group_id: 1, priority: "" }])).toBe("Row 1: prefix is required.");
+	expect(firstProblem([{ prefix: "  ", group_id: 1, priority: "" }])).toEqual({
+		index: 0,
+		field: "prefix",
+		message: "Row 1: prefix is required.",
+	});
 	expect(
 		firstProblem([
 			{ prefix: "10.0.0.0/8", group_id: 1, priority: "100" },
 			{ prefix: "10.1.0.0/16", group_id: 1, priority: "abc" },
 		]),
-	).toBe("Row 2: priority must be a whole number.");
+	).toEqual({ index: 1, field: "priority", message: "Row 2: priority must be a whole number." });
 });

admin/src/features/clients/prefixEditor.ts

@@ -55,11 +55,20 @@ export function isDirty(state: PrefixEditorState): boolean {
 	});
 }
 
-export function firstProblem(rows: PrefixRow[]): string | null {
+/** Which input the message is about, so the editor can point that input at it. */
-	for (const [i, row] of rows.entries()) {
+export interface PrefixProblem {
-		if (row.prefix.trim() === "") return `Row ${i + 1}: prefix is required.`;
+	index: number;
+	field: "prefix" | "priority";
+	message: string;
+}
+
+export function firstProblem(rows: PrefixRow[]): PrefixProblem | null {
+	for (const [index, row] of rows.entries()) {
+		if (row.prefix.trim() === "")
+			return { index, field: "prefix", message: `Row ${index + 1}: prefix is required.` };
 		const priority = row.priority.trim();
-		if (priority !== "" && !/^\d+$/.test(priority)) return `Row ${i + 1}: priority must be a whole number.`;
+		if (priority !== "" && !/^\d+$/.test(priority))
+			return { index, field: "priority", message: `Row ${index + 1}: priority must be a whole number.` };
 	}
 	return null;
 }

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

@@ -61,17 +61,20 @@ test("the lock is silent when the database owns the configuration", async () =>
 test("under file authority the lock names the file, in words a reader hears", async () => {
 	renderIndicator(MANAGED_FILE);
 
+	// The reason is visible text beside the tag, not a title and not a label: a
+	// tooltip reaches neither a keyboard nor a touch screen, and screen-reader-only
+	// text is the same failure pointed the other way.
 	const lock = await screen.findByText("Locked");
 	await waitFor(() =>
-		expect(lock.getAttribute("aria-label")).toBe(
+		expect(screen.getByText(`Managed by ${CONFIG_PATH}; edit the file and restart nxdns`)).toBeTruthy(),
-			`Locked. Managed by ${CONFIG_PATH}; edit the file and restart nxdns.`,
-		),
 	);
+	expect(lock.getAttribute("title")).toBeNull();
+	expect(lock.getAttribute("aria-label")).toBeNull();
 });
 
 test("an unanswered status still locks, and says that is why", async () => {
 	renderIndicator("failed");
 
-	const lock = await screen.findByText("Locked");
+	await screen.findByText("Locked");
-	await waitFor(() => expect(lock.getAttribute("aria-label")).toContain("Configuration status unavailable"));
+	await waitFor(() => expect(screen.getByText(/^Configuration status unavailable/)).toBeTruthy());
 });

admin/src/features/configuration/ConfigLockIndicator.tsx

@@ -1,8 +1,20 @@
 import * as stylex from "@stylexjs/stylex";
 import { colors } from "@/ui/tokens.stylex";
-import { useAuthority } from "./authority";
+import { useAuthority, type Authority } from "./authority";
 
 const styles = stylex.create({
+	row: {
+		display: "inline-flex",
+		alignItems: "baseline",
+		flexWrap: "wrap",
+		gap: "0.375rem",
+	},
+	/** The sentence is secondary to the word, and wraps rather than stretching a row. */
+	reason: {
+		fontSize: "0.75rem",
+		lineHeight: "1rem",
+		color: colors.textMuted,
+	},
 	tag: {
 		marginLeft: "0.5rem",
 		borderWidth: 1,
@@ -26,20 +38,34 @@ const styles = stylex.create({
  * The word is real text, not colour or an icon, so a screen reader announces
  * the reason the control will not answer.
  */
-export default function ConfigLockIndicator() {
+/**
+ * Why a configuration control will not answer. Exported because a page that
+ * shows the compact tag has to print this sentence itself, once, somewhere the
+ * tag can point at.
+ */
+export function lockReason(authority: Authority): string {
+	if (authority.state === "pending") return "Checking which configuration source this server obeys";
+	if (authority.state === "failed") return "Configuration status unavailable, so edits are held back";
+	return `Managed by ${authority.status.path ?? "the configuration file"}; edit the file and restart nxdns`;
+}
+
+export default function ConfigLockIndicator({ compact = false }: { compact?: boolean }) {
 	const authority = useAuthority();
 	if (authority.state === "resolved" && authority.status.authority === "database") return null;
 
-	const reason =
+	const reason = lockReason(authority);
-		authority.state === "pending"
-			? "Checking which configuration source this server obeys"
-			: authority.state === "failed"
-				? "Configuration status unavailable, so edits are held back"
-				: `Managed by ${authority.status.path ?? "the configuration file"}; edit the file and restart nxdns`;
 
+	// A compact caller has no room for the sentence and must print it once
+	// nearby instead: the Clients table would otherwise repeat it down every row.
+	if (compact) return <span {...stylex.props(styles.tag)}>Locked</span>;
+
+	// Everywhere else the reason is visible text rather than a `title` or an
+	// `aria-label`. A tooltip reaches neither a keyboard nor a touch screen, and
+	// screen-reader-only text is the same failure pointed the other way.
 	return (
-		<span title={reason} aria-label={`Locked. ${reason}.`} {...stylex.props(styles.tag)}>
+		<span {...stylex.props(styles.row)}>
-			Locked
+			<span {...stylex.props(styles.tag)}>Locked</span>
+			<span {...stylex.props(styles.reason)}>{reason}</span>
 		</span>
 	);
 }

admin/src/features/configuration/GroupSourcesEditor.tsx

@@ -3,7 +3,8 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import * as stylex from "@stylexjs/stylex";
 import { groupSourcesPutMutation, groupSourcesQuery } from "@/lib/queries";
 import type { Blocklist } from "@/lib/types";
-import { sameSet, toggleSource } from "./sourceSet";
+import { sameSet } from "./sourceSet";
+import Checkbox, { CheckboxGroup } from "@/ui/Checkbox";
 import InlineError from "@/lib/InlineError";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
@@ -28,13 +29,6 @@ const styles = stylex.create({
 		flexDirection: "column",
 		gap: "0.25rem",
 	},
-	checkboxLabel: {
-		display: "inline-flex",
-		alignItems: "center",
-		gap: "0.5rem",
-		fontSize: "0.875rem",
-		lineHeight: "1.25rem",
-	},
 	buttonRow: {
 		marginTop: "0.75rem",
 		display: "flex",
@@ -66,21 +60,22 @@ export default function GroupSourcesEditor({ groupId, blocklists }: Props) {
 
 	return (
 		<div {...stylex.props(styles.root)}>
-			<ul {...stylex.props(styles.list)}>
+			{/* The section's own "Assigned sources" heading is the visible label; a
-				{blocklists.map((blocklist) => (
+			    Label here would put the same words on screen twice. Ids cross the
-					<li key={blocklist.id}>
+			    React Aria boundary as strings, the same convention as Select. */}
-						<label {...stylex.props(styles.checkboxLabel)}>
+			<CheckboxGroup
-							<input
+				aria-label="Assigned sources"
-								type="checkbox"
+				value={current.map(String)}
-								checked={current.includes(blocklist.id)}
+				onChange={(values) => setSelected(values.map(Number).sort((a, b) => a - b))}
-								onChange={() => setSelected(toggleSource(current, blocklist.id))}
+			>
-								{...stylex.props(shared.focusRing)}
+				<ul {...stylex.props(styles.list)}>
-							/>
+					{blocklists.map((blocklist) => (
-							{blocklist.name}
+						<li key={blocklist.id}>
-						</label>
+							<Checkbox value={String(blocklist.id)}>{blocklist.name}</Checkbox>
-					</li>
+						</li>
-				))}
+					))}
-			</ul>
+				</ul>
+			</CheckboxGroup>
 			<InlineError error={mutation.error} />
 			<div {...stylex.props(styles.buttonRow)}>
 				<button

admin/src/features/configuration/ProtectionGroups.tsx

@@ -21,6 +21,7 @@ import type { Blocklist, ConfigStatus, Group, Rule, RuleAction, RuleKind } from
 import ConfirmDialog from "@/ui/ConfirmDialog";
 import DefinitionList from "@/ui/DefinitionList";
 import Select from "@/ui/Select";
+import Switch from "@/ui/Switch";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
 import AuthorityGate from "./AuthorityGate";
@@ -68,13 +69,6 @@ const styles = stylex.create({
 		alignItems: "center",
 		gap: "0.75rem",
 	},
-	checkboxLabel: {
-		display: "inline-flex",
-		alignItems: "center",
-		gap: "0.5rem",
-		fontSize: "0.875rem",
-		lineHeight: "1.25rem",
-	},
 	spacer: {
 		marginLeft: "auto",
 	},
@@ -355,21 +349,15 @@ function GroupDetailEditable({ group }: { group: Group }) {
 			)}
 
 			<div {...stylex.props(styles.controlRow)}>
-				<label {...stylex.props(styles.checkboxLabel)}>
+				<Switch
-					<input
+					isSelected={group.safe_search}
-						type="checkbox"
+					isDisabled={update.isPending}
-						checked={group.safe_search}
+					onChange={(safeSearch) =>
-						disabled={update.isPending}
+						update.mutate({ id: group.id, input: { name: group.name, safe_search: safeSearch } })
-						{...stylex.props(shared.focusRing)}
+					}
-						onChange={(event) =>
+				>
-							update.mutate({
-								id: group.id,
-								input: { name: group.name, safe_search: event.target.checked },
-							})
-						}
-					/>
 					Safe search
-				</label>
+				</Switch>
 				<span {...stylex.props(styles.spacer)}>
 					{!renaming && (
 						<button

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

@@ -46,7 +46,7 @@ test("another group can be renamed and deleted, and carries its safe-search stat
 	await screen.findByRole("heading", { name: "kids", level: 2 });
 
 	expect((screen.getByRole("button", { name: "Rename group" }) as HTMLButtonElement).disabled).toBe(false);
-	expect((screen.getByRole("checkbox", { name: "Safe search" }) as HTMLInputElement).checked).toBe(true);
+	expect((screen.getByRole("switch", { name: "Safe search" }) as HTMLInputElement).checked).toBe(true);
 
 	fireEvent.click(screen.getByRole("button", { name: "Delete group" }));
 	const dialog = await screen.findByRole("alertdialog");
@@ -60,7 +60,7 @@ test("toggling safe search resends the whole group row", async () => {
 	await openProtection(2);
 	await screen.findByRole("heading", { name: "kids", level: 2 });
 
-	fireEvent.click(screen.getByRole("checkbox", { name: "Safe search" }));
+	fireEvent.click(screen.getByRole("switch", { name: "Safe search" }));
 
 	await waitFor(() => expect(writes("PUT")).toHaveLength(1));
 	expect(writes("PUT")[0]).toMatchObject({
@@ -89,6 +89,31 @@ test("the source assignment saves the full set via PUT", async () => {
 	});
 });
 
+test("the source checkboxes form one named group, and each carries its own state", async () => {
+	await openProtection(2);
+	await screen.findByRole("heading", { name: "kids", level: 2 });
+
+	// The section heading names the group; the boxes belong to it rather than
+	// sitting loose beside the group's other checkboxes.
+	const group = await screen.findByRole("group", { name: "Assigned sources" });
+	const ads = within(group).getByRole("checkbox", { name: "Ads" }) as HTMLInputElement;
+	expect(ads.checked).toBe(false);
+	// Safe search is the group's own field, not one of its sources, and it is a
+	// switch rather than a checkbox because it applies the moment it moves.
+	expect(within(group).queryByRole("switch")).toBeNull();
+	expect(screen.getByRole("switch", { name: "Safe search" })).toBeTruthy();
+
+	fireEvent.click(ads);
+	await waitFor(() => expect(ads.checked).toBe(true));
+
+	// Discard returns the group to the server's set rather than clearing it.
+	fireEvent.click(screen.getByRole("button", { name: "Discard" }));
+	await waitFor(() =>
+		expect((within(group).getByRole("checkbox", { name: "Ads" }) as HTMLInputElement).checked).toBe(false),
+	);
+	expect(writes("PUT")).toEqual([]);
+});
+
 test("only the selected group's rules are listed", async () => {
 	await openProtection(2);
 	await screen.findByRole("heading", { name: "kids", level: 2 });
@@ -212,11 +237,33 @@ test("the Sources tab lists the catalogue with both skipped columns and their no
 	expect(
 		screen.getByText(/Skipped unsupported lines are syntax nxdns cannot translate into a DNS decision/),
 	).toBeTruthy();
-	expect((screen.getByLabelText("Ads enabled") as HTMLInputElement).checked).toBe(true);
+	// Switches, not checkboxes: the row applies the moment it moves, and the role
-	expect((screen.getByLabelText("Trackers enabled") as HTMLInputElement).checked).toBe(false);
+	// is what tells a screen reader so.
+	expect((screen.getByRole("switch", { name: "Ads enabled" }) as HTMLInputElement).checked).toBe(true);
+	expect((screen.getByRole("switch", { name: "Trackers enabled" }) as HTMLInputElement).checked).toBe(false);
 	expect(screen.getByRole("heading", { name: "Add source" })).toBeTruthy();
 });
 
+test("a source switch resends the whole row immediately, with no Save step", async () => {
+	calls = stubApi(DATABASE);
+	await renderPage("/configuration/protection?tab=sources", "Protection");
+
+	fireEvent.click(await screen.findByRole("switch", { name: "Trackers enabled" }));
+
+	// No Save button stands between the switch and the write: one click, one PUT.
+	await waitFor(() => expect(writes("PUT")).toHaveLength(1));
+	expect(writes("PUT")[0]).toMatchObject({
+		url: "/api/blocklists/2",
+		// The whole row goes back, not a patch of the one field that moved.
+		body: {
+			url: "https://example.com/trackers.txt",
+			name: "Trackers",
+			enabled: true,
+			is_suggested: true,
+		},
+	});
+});
+
 test("Update now says it started, and says nothing once it succeeds", async () => {
 	let release: ((response: Response) => void) | null = null;
 	calls = stubApi(DATABASE, {

admin/src/features/configuration/ProtectionSources.tsx

@@ -14,6 +14,7 @@ import type { Blocklist, BlocklistInput } from "@/lib/types";
 import ConfirmDialog from "@/ui/ConfirmDialog";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
+import Switch from "@/ui/Switch";
 import AuthorityGate from "./AuthorityGate";
 import BlocklistForm from "./BlocklistForm";
 import FileModeNote from "./FileModeNote";
@@ -249,13 +250,11 @@ function SourcesEditor({ blocklists }: { blocklists: Blocklist[] }) {
 										</span>
 									</td>
 									<td {...stylex.props(shared.td)}>
-										<input
+										<Switch
-											type="checkbox"
 											aria-label={`${b.name} enabled`}
-											checked={b.enabled}
+											isSelected={b.enabled}
-											disabled={toggle.isPending}
+											isDisabled={toggle.isPending}
 											onChange={() => toggleEnabled(b)}
-											{...stylex.props(shared.focusRing)}
 										/>
 									</td>
 									<td {...stylex.props(shared.td, shared.tabularNums)}>{b.domain_count}</td>

admin/src/features/configuration/SettingsForm.tsx

@@ -13,6 +13,9 @@ import { styles as config } from "./styles";
 
 const DARK = "@media (prefers-color-scheme: dark)";
 
+/** The form is rendered once per page, so the message can hold a fixed id. */
+const MISMATCH_ID = "web.password_mismatch";
+
 const styles = stylex.create({
 	form: {
 		marginTop: "1rem",
@@ -100,6 +103,7 @@ const styles = stylex.create({
 		gap: "0.75rem",
 	},
 	save: {
+		cursor: { default: "pointer", ":disabled": "not-allowed" },
 		borderStyle: "none",
 		borderRadius: "0.25rem",
 		paddingInline: "1rem",
@@ -174,12 +178,15 @@ function FieldRow({
 	}
 	if (def.kind === "number") {
 		const numeric = value as number;
+		// An empty or unparseable number reads back as NaN. The form already refuses
+		// to submit on it; this is what says so to a screen reader.
 		return (
 			<div {...stylex.props(styles.field)}>
 				<FieldLabel id={id} text={def.key} restart={restart} />
 				<input
 					id={id}
 					type="number"
+					aria-invalid={Number.isNaN(numeric) || undefined}
 					value={Number.isNaN(numeric) ? "" : numeric}
 					onChange={(e) => onChange(e.target.valueAsNumber)}
 					{...stylex.props(styles.fieldInput, shared.focusRing)}
@@ -285,6 +292,8 @@ export default function SettingsForm({ envelope }: { envelope: SettingsEnvelope
 											id="web.password"
 											type="password"
 											autoComplete="new-password"
+											aria-invalid={passwordsMismatch || undefined}
+											aria-describedby={passwordsMismatch ? MISMATCH_ID : undefined}
 											value={password}
 											onChange={(e) => setPassword(e.target.value)}
 											{...stylex.props(styles.fieldInput, shared.focusRing)}
@@ -298,6 +307,8 @@ export default function SettingsForm({ envelope }: { envelope: SettingsEnvelope
 											id="web.password_confirm"
 											type="password"
 											autoComplete="new-password"
+											aria-invalid={passwordsMismatch || undefined}
+											aria-describedby={passwordsMismatch ? MISMATCH_ID : undefined}
 											value={confirm}
 											onChange={(e) => setConfirm(e.target.value)}
 											{...stylex.props(styles.fieldInput, shared.focusRing)}
@@ -310,7 +321,7 @@ export default function SettingsForm({ envelope }: { envelope: SettingsEnvelope
 										</p>
 									)}
 									{passwordsMismatch && (
-										<p {...stylex.props(styles.spanRow, styles.mismatchNotice)}>
+										<p id={MISMATCH_ID} {...stylex.props(styles.spanRow, styles.mismatchNotice)}>
 											Passwords do not match.
 										</p>
 									)}

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

@@ -176,12 +176,52 @@ test("enum and boolean fields diff as their own types", async () => {
 	expect(putBodies[0]).toEqual({ logging: { level: "debug", hide_domains: true } });
 });
 
+/** The text of the elements an input points at with `aria-describedby`. */
+function describedText(input: HTMLElement): string {
+	const ids = input.getAttribute("aria-describedby");
+	if (ids === null) throw new Error("input has no aria-describedby");
+	return ids
+		.split(/\s+/)
+		.map((id) => {
+			const node = document.getElementById(id);
+			if (node === null) throw new Error(`aria-describedby names missing element ${id}`);
+			return node.textContent ?? "";
+		})
+		.join(" ");
+}
+
 test("clearing a number field disables Save instead of sending NaN", async () => {
 	await openSystem();
 
 	const cache = screen.getByRole("group", { name: "Cache" });
-	fireEvent.change(within(cache).getByLabelText("size"), { target: { value: "" } });
+	const size = within(cache).getByLabelText("size");
+	fireEvent.change(size, { target: { value: "" } });
 	expect(saveButton().disabled).toBe(true);
+	// The refusal is on the field itself, not only on the Save button.
+	expect(size.getAttribute("aria-invalid")).toBe("true");
+
+	fireEvent.change(size, { target: { value: "512" } });
+	expect(size.getAttribute("aria-invalid")).toBeNull();
+});
+
+test("the mismatch message is attached to both password inputs", async () => {
+	await openSystem();
+
+	const web = screen.getByRole("group", { name: "Web" });
+	const passwordInput = within(web).getByLabelText("password");
+	const confirmInput = within(web).getByLabelText("confirm password");
+
+	fireEvent.change(passwordInput, { target: { value: "hunter2" } });
+	for (const input of [passwordInput, confirmInput]) {
+		expect(input.getAttribute("aria-invalid")).toBe("true");
+		expect(describedText(input)).toBe("Passwords do not match.");
+	}
+
+	fireEvent.change(confirmInput, { target: { value: "hunter2" } });
+	for (const input of [passwordInput, confirmInput]) {
+		expect(input.getAttribute("aria-invalid")).toBeNull();
+		expect(input.getAttribute("aria-describedby")).toBeNull();
+	}
 });
 
 test("password flow: note shown, confirm required, PUT sends web.password, no restart notice", async () => {

admin/src/features/configuration/UpstreamsTab.tsx

@@ -7,6 +7,7 @@ import type { Upstream, UpstreamInput } from "@/lib/types";
 import ConfirmDialog from "@/ui/ConfirmDialog";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
+import Switch from "@/ui/Switch";
 import AuthorityGate from "./AuthorityGate";
 import FileModeNote from "./FileModeNote";
 import QueryPanel from "./QueryPanel";
@@ -165,13 +166,11 @@ function UpstreamsEditor({ upstreams }: { upstreams: Upstream[] }) {
 									</td>
 									<td {...stylex.props(shared.td, shared.tabularNums)}>{u.priority}</td>
 									<td {...stylex.props(shared.td)}>
-										<input
+										<Switch
-											type="checkbox"
 											aria-label={`${u.url} enabled`}
-											checked={u.enabled}
+											isSelected={u.enabled}
-											disabled={toggle.isPending}
+											isDisabled={toggle.isPending}
 											onChange={() => toggleEnabled(u)}
-											{...stylex.props(shared.focusRing)}
 										/>
 									</td>
 									<td {...stylex.props(shared.td)}>{u.tls_name === "" ? "—" : u.tls_name}</td>

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

@@ -24,7 +24,7 @@ afterEach(() => {
 function mutationControls(): Element[] {
 	return [
 		...contentArea().querySelectorAll(
-			'input, textarea, select, [role="combobox"], [role="checkbox"], [contenteditable]',
+			'input, textarea, select, [role="combobox"], [role="checkbox"], [role="switch"], [contenteditable]',
 		),
 	];
 }
@@ -99,14 +99,17 @@ test("a failed status is announced by the shell on a page that is not configurat
 	stubApi(DATABASE, {
 		responses: {
 			"GET /api/config/status": new Response(JSON.stringify({ error: "gone" }), { status: 404 }),
-			"GET /api/stats?period=24h": {
+			"GET /api/overview?period=24h": {
 				period: "24h",
 				since: 0,
 				until: 86400,
-				queries: 0,
+				bucket_seconds: 1800,
-				blocked: 0,
+				totals: { queries: 0, blocked: 0, clients: 0, avg_response_time_us: null },
-				clients: 0,
+				buckets: [],
-				avg_response_time_us: null,
+				clients: [],
+				other: [],
+				types: [],
+				routes: [],
 				coverage: { complete: true, available_since: 0 },
 			},
 		},

admin/src/features/configuration/sourceSet.test.ts

@@ -1,18 +1,4 @@
-import { sameSet, toggleSource } from "./sourceSet";
+import { sameSet } from "./sourceSet";
-
-test("toggleSource adds a missing id keeping ascending order", () => {
-	expect(toggleSource([1, 3], 2)).toEqual([1, 2, 3]);
-	expect(toggleSource([], 5)).toEqual([5]);
-});
-
-test("toggleSource removes a present id", () => {
-	expect(toggleSource([1, 2, 3], 2)).toEqual([1, 3]);
-	expect(toggleSource([5], 5)).toEqual([]);
-});
-
-test("toggleSource twice is a no-op set-wise", () => {
-	expect(toggleSource(toggleSource([1, 2], 3), 3)).toEqual([1, 2]);
-});
 
 test("sameSet compares regardless of order", () => {
 	expect(sameSet([1, 2, 3], [3, 1, 2])).toBe(true);

admin/src/features/configuration/sourceSet.ts

@@ -1,8 +1,3 @@
-export function toggleSource(ids: number[], id: number): number[] {
-	if (ids.includes(id)) return ids.filter((existing) => existing !== id);
-	return [...ids, id].sort((a, b) => a - b);
-}
-
 export function sameSet(a: number[], b: number[]): boolean {
 	if (a.length !== b.length) return false;
 	const sortedA = [...a].sort((x, y) => x - y);

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

@@ -2,23 +2,14 @@ import { fireEvent, render as renderBare, screen, within } from "@testing-librar
 import { QueryClientProvider } from "@tanstack/react-query";
 import { createQueryClient } from "@/lib/queryClient";
 import { formatTime } from "@/lib/format";
-import type { StatsClients } from "@/lib/types";
+import ClientChart, { type ClientChartData } from "./ClientChart";
-import ClientChart from "./ClientChart";
 import { OTHER_KEY, clientKey, seriesColor } from "./seriesColors";
 
 const SINCE = 1_700_000_000;
 const BUCKET = 1800;
 
-function clients(named: { client: string; buckets: number[] }[], other: number[]): StatsClients {
+function clients(named: { client: string; buckets: number[] }[], other: number[]): ClientChartData {
-	return {
+	return { since: SINCE, bucket_seconds: BUCKET, clients: named, other };
-		period: "24h",
-		since: SINCE,
-		until: SINCE + other.length * BUCKET,
-		bucket_seconds: BUCKET,
-		coverage: { complete: true, available_since: SINCE },
-		clients: named,
-		other,
-	};
 }
 
 const TWO_BUCKETS = clients(
@@ -34,15 +25,15 @@ const TWO_BUCKETS = clients(
  * client is registered in these fixtures, which is what leaves the addresses on
  * screen as the labels.
  */
-function render(data: StatsClients) {
+function render(data: ClientChartData) {
 	const client = createQueryClient();
-	const tree = (next: StatsClients) => (
+	const tree = (next: ClientChartData) => (
 		<QueryClientProvider client={client}>
 			<ClientChart data={next} />
 		</QueryClientProvider>
 	);
 	const result = renderBare(tree(data));
-	return { ...result, rerender: (next: StatsClients) => result.rerender(tree(next)) };
+	return { ...result, rerender: (next: ClientChartData) => result.rerender(tree(next)) };
 }
 
 beforeEach(() => {

admin/src/features/overview/ClientChart.tsx

@@ -13,7 +13,7 @@ import * as stylex from "@stylexjs/stylex";
 import { Group } from "@visx/group";
 import { BarStack } from "@visx/shape";
 import { formatTime } from "@/lib/format";
-import type { StatsClients } from "@/lib/types";
+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";
@@ -69,8 +69,6 @@ const styles = stylex.create({
 interface Series {
 	key: string;
 	label: string;
-	/** Kept beside the label so a renamed client is still identifiable by address. */
-	address: string | null;
 	color: string;
 	buckets: number[];
 }
@@ -82,28 +80,35 @@ interface Series {
  * and a table column all saying zero. The named clients stay at zero, because a
  * client that went quiet is something the reader wants to see.
  */
-function seriesOf(data: StatsClients, names: ClientNames): Series[] {
+function seriesOf(data: ClientChartData, names: ClientNames): Series[] {
 	const named = data.clients.map((client) => ({
 		key: clientKey(client.client),
 		// The name if the client is registered under one, the address otherwise —
 		// the same precedence and the same lookup the query tables use. The colour
 		// keys on the address regardless, so naming a client never repaints it.
 		label: clientLabel(client.client, names)?.text ?? client.client,
-		address: client.client,
 		color: seriesColor(clientKey(client.client)),
 		buckets: client.buckets,
 	}));
 	if (data.other.every((count) => count === 0)) return named;
-	return [
+	return [...named, { key: OTHER_KEY, label: "Other", color: seriesColor(OTHER_KEY), buckets: data.other }];
-		...named,
+}
-		{ key: OTHER_KEY, label: "Other", address: null, color: seriesColor(OTHER_KEY), buckets: data.other },
+
-	];
+/**
+ * The slice of the Overview body this chart draws. Declared here rather than
+ * taken whole, so what the chart reads is stated where it is read.
+ */
+export interface ClientChartData {
+	since: number;
+	bucket_seconds: number;
+	clients: OverviewClientSeries[];
+	other: number[];
 }
 
 /** One column: the timestamp plus one entry per series, keyed by the series key. */
 type Column = { ts: number } & Record<string, number>;
 
-export default function ClientChart({ data }: { data: StatsClients }) {
+export default function ClientChart({ data }: { data: ClientChartData }) {
 	const [containerRef, width] = useMeasuredWidth();
 	// 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.
@@ -208,7 +213,7 @@ export default function ClientChart({ data }: { data: StatsClients }) {
 			)}
 			<ul {...stylex.props(styles.legend)}>
 				{series.map((one) => (
-					<li key={one.key} title={one.address ?? undefined} {...stylex.props(styles.legendItem)}>
+					<li key={one.key} {...stylex.props(styles.legendItem)}>
 						<span aria-hidden="true" {...stylex.props(styles.swatch, styles.swatchColor(one.color))} />
 						{one.label}
 					</li>

admin/src/features/overview/OverviewFrame.tsx

@@ -0,0 +1,148 @@
+/**
+ * The part of Overview that does not wait for anything: the heading, the period
+ * picker, and the pulsing body the page shows while the window is in flight.
+ *
+ * It lives apart from `OverviewPage` so the route's pending component can render
+ * the identical surface while the page chunk loads. Importing the page itself
+ * would pull the charts into the main bundle, and a second hand-written copy of
+ * the frame would drift. Nothing here imports a chart.
+ */
+
+import * as stylex from "@stylexjs/stylex";
+import { useNavigate, useSearch } from "@tanstack/react-router";
+import { Radio, RadioGroup } from "react-aria-components";
+import type { Period } from "@/lib/types";
+import { styles as shared } from "@/ui/styles";
+import { colors } from "@/ui/tokens.stylex";
+import { DEFAULT_PERIOD, PERIODS } from "./period";
+
+const styles = stylex.create({
+	page: {
+		display: "flex",
+		flexDirection: "column",
+		gap: "1rem",
+	},
+	headingRow: {
+		display: "flex",
+		flexWrap: "wrap",
+		alignItems: "center",
+		justifyContent: "space-between",
+		gap: "0.75rem",
+	},
+	heading: {
+		fontSize: "1.5rem",
+		lineHeight: "2rem",
+		fontWeight: 600,
+	},
+	periodGroup: {
+		display: "flex",
+		gap: "0.25rem",
+	},
+	period: {
+		cursor: "pointer",
+		borderStyle: "none",
+		borderRadius: "0.25rem",
+		paddingInline: "0.625rem",
+		paddingBlock: "0.25rem",
+		fontSize: "0.875rem",
+		lineHeight: "1.25rem",
+	},
+	/** A Radio is a `label`, so RAC drives the ring rather than `:focus-visible`. */
+	periodFocusVisible: {
+		outlineWidth: 2,
+		outlineStyle: "solid",
+		outlineColor: colors.focus,
+		outlineOffset: 2,
+	},
+	/** The pressed fill is heavier than `surfaceHover`, so a hover cannot mimic it. */
+	periodSelected: {
+		backgroundColor: {
+			default: "oklch(92% 0.004 286.32)",
+			"@media (prefers-color-scheme: dark)": "oklch(37% 0.013 285.805)",
+		},
+		color: colors.text,
+		fontWeight: 500,
+	},
+	periodIdle: {
+		backgroundColor: { default: "transparent", ":hover": colors.surfaceHover },
+		color: colors.textSecondary,
+	},
+	loading: {
+		fontSize: "0.875rem",
+		lineHeight: "1.25rem",
+		color: colors.textMuted,
+	},
+});
+
+export function PeriodPicker({ period, onChange }: { period: Period; onChange: (period: Period) => void }) {
+	return (
+		<RadioGroup
+			aria-label="Period"
+			orientation="horizontal"
+			value={period}
+			onChange={(next) => onChange(next as Period)}
+			className={() => stylex.props(styles.periodGroup).className ?? ""}
+		>
+			{PERIODS.map((option) => (
+				<Radio
+					key={option}
+					value={option}
+					className={({ isSelected, isFocusVisible }) =>
+						stylex.props(
+							styles.period,
+							isSelected ? styles.periodSelected : styles.periodIdle,
+							isFocusVisible && styles.periodFocusVisible,
+						).className ?? ""
+					}
+				>
+					{option}
+				</Radio>
+			))}
+		</RadioGroup>
+	);
+}
+
+export function OverviewLoading() {
+	return (
+		<p role="status" {...stylex.props(styles.loading, shared.pulse)}>
+			Loading…
+		</p>
+	);
+}
+
+export function OverviewFrame({
+	period,
+	onChange,
+	children,
+}: {
+	period: Period;
+	onChange: (period: Period) => void;
+	children: React.ReactNode;
+}) {
+	return (
+		<div {...stylex.props(styles.page)}>
+			<div {...stylex.props(styles.headingRow)}>
+				<h1 {...stylex.props(styles.heading)}>Overview</h1>
+				<PeriodPicker period={period} onChange={onChange} />
+			</div>
+			{children}
+		</div>
+	);
+}
+
+/**
+ * The route's pending surface. The picker stays live because it only writes the
+ * search parameter, which the route already re-reads on its own.
+ */
+export function OverviewPending() {
+	const period = useSearch({ from: "/shell/overview" }).period ?? DEFAULT_PERIOD;
+	const navigate = useNavigate({ from: "/overview" });
+	return (
+		<OverviewFrame
+			period={period}
+			onChange={(next) => void navigate({ search: (prev) => ({ ...prev, period: next }) })}
+		>
+			<OverviewLoading />
+		</OverviewFrame>
+	);
+}

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

@@ -16,64 +16,32 @@ import { createQueryClient } from "@/lib/queryClient";
 import { createAppRouter } from "@/routes";
 import { clientKey, qtypeKey, seriesColor } from "./seriesColors";
 import { health } from "@/lib/healthFixture";
-import type { Health, StatsClients, StatsRoutes, StatsTimeseries, StatsTotals, StatsTypes } from "@/lib/types";
+import type { Health, Overview } from "@/lib/types";
 
 const SINCE = Date.UTC(2026, 0, 1, 0, 0) / 1000;
 const UNTIL = Date.UTC(2026, 0, 2, 0, 0) / 1000;
 const COVERAGE = { complete: true, available_since: SINCE };
 
-const TOTALS: StatsTotals = {
+const OVERVIEW: Overview = {
-	period: "24h",
-	since: SINCE,
-	until: UNTIL,
-	queries: 1000,
-	blocked: 250,
-	clients: 7,
-	avg_response_time_us: 2345,
-	coverage: COVERAGE,
-};
-
-const SERIES: StatsTimeseries = {
 	period: "24h",
 	since: SINCE,
 	until: UNTIL,
 	bucket_seconds: 1800,
+	totals: { queries: 1000, blocked: 250, clients: 7, avg_response_time_us: 2345 },
 	buckets: [
 		{ ts: SINCE, queries: 60, blocked: 20, cached: 10 },
 		{ ts: SINCE + 1800, queries: 40, blocked: 0, cached: 0 },
 	],
-	coverage: COVERAGE,
-};
-
-const CLIENTS: StatsClients = {
-	period: "24h",
-	since: SINCE,
-	until: UNTIL,
-	bucket_seconds: 1800,
 	clients: [
 		{ client: "192.0.2.30", buckets: [40, 20] },
 		{ client: "192.0.2.31", buckets: [20, 20] },
 	],
 	other: [0, 0],
-	coverage: COVERAGE,
-};
-
-const TYPES: StatsTypes = {
-	period: "24h",
-	since: SINCE,
-	until: UNTIL,
 	types: [
 		{ qtype: 1, count: 600 },
 		{ qtype: 28, count: 300 },
 		{ qtype: null, count: 100 },
 	],
-	coverage: COVERAGE,
-};
-
-const ROUTES: StatsRoutes = {
-	period: "24h",
-	since: SINCE,
-	until: UNTIL,
 	routes: [
 		{ route: "upstream", source: "https://dns.example/dns-query", count: 500 },
 		{ route: "blocked", source: null, count: 250 },
@@ -83,22 +51,27 @@ const ROUTES: StatsRoutes = {
 	coverage: COVERAGE,
 };
 
-/** The same shapes an hour wide, so a period change is observable in every panel. */
+/** The same shape an hour wide and empty, so a period change is observable. */
-const HOUR = {
+const HOUR: Overview = {
-	totals: { ...TOTALS, period: "1h", since: UNTIL - 3600, queries: 12, blocked: 3, clients: 2 } as StatsTotals,
+	...OVERVIEW,
-	timeseries: { ...SERIES, period: "1h", since: UNTIL - 3600, bucket_seconds: 60, buckets: [] } as StatsTimeseries,
+	period: "1h",
-	clients: { ...CLIENTS, period: "1h", since: UNTIL - 3600, clients: [], other: [] } as StatsClients,
+	since: UNTIL - 3600,
-	types: { ...TYPES, period: "1h", since: UNTIL - 3600, types: [] } as StatsTypes,
+	bucket_seconds: 60,
-	routes: { ...ROUTES, period: "1h", since: UNTIL - 3600, routes: [] } as StatsRoutes,
+	totals: { queries: 12, blocked: 3, clients: 2, avg_response_time_us: 2345 },
+	buckets: [],
+	clients: [],
+	other: [],
+	types: [],
+	routes: [],
 };
 
 let healthBody: Health;
-let failing: Set<string>;
+let failing: boolean;
 /** The registered clients, as `/api/clients` answers them. */
 let registered: { ip: string; name: string; learned_name: string }[];
 let coverageComplete: boolean;
-/** Paths held in flight, so a test can look at the page while one is pending. */
+/** Held in flight, so a test can look at the page while the request is pending. */
-let delayed: Map<string, Promise<void>>;
+let delayed: Promise<void> | null;
 
 function json(payload: unknown, status = 200): Response {
 	return new Response(JSON.stringify(payload), { status, headers: { "content-type": "application/json" } });
@@ -110,27 +83,18 @@ function withCoverage<T extends { coverage: typeof COVERAGE }>(body: T): T {
 
 beforeEach(() => {
 	healthBody = health();
-	failing = new Set();
+	failing = false;
 	registered = [];
 	coverageComplete = true;
-	delayed = new Map();
+	delayed = null;
 	vi.stubGlobal(
 		"fetch",
 		vi.fn(async (input: RequestInfo | URL) => {
 			const url = String(input);
-			const hour = url.includes("period=1h");
+			if (url.startsWith("/api/overview")) {
-			for (const [path, body] of [
+				if (failing) return json({ error: "endpoint unavailable" }, 400);
-				["/api/stats/timeseries", hour ? HOUR.timeseries : SERIES],
+				if (delayed !== null) await delayed;
-				["/api/stats/clients", hour ? HOUR.clients : CLIENTS],
+				return json(withCoverage(url.includes("period=1h") ? HOUR : OVERVIEW));
-				["/api/stats/types", hour ? HOUR.types : TYPES],
-				["/api/stats/routes", hour ? HOUR.routes : ROUTES],
-				["/api/stats", hour ? HOUR.totals : TOTALS],
-			] as const) {
-				if (!url.startsWith(path)) continue;
-				if (failing.has(path)) return json({ error: "endpoint unavailable" }, 400);
-				const held = delayed.get(path);
-				if (held !== undefined) await held;
-				return json(withCoverage(body));
 			}
 			if (url === "/api/clients") {
 				return json({
@@ -215,25 +179,27 @@ test("the page builds a donut slice's colour from the entry's identity", async (
 	expect(swatch.getAttribute("style")).toContain(seriesColor(qtypeKey(1)));
 });
 
-test("a slow endpoint does not hold the page back: the panels that answered render beside it", async () => {
+test("a request in flight leaves the heading and the picker usable behind one loading surface", async () => {
-	// Through the real route, which is the point: the loader starts the five
+	// Through the real route, which is the point: the loader starts the request
-	// requests and awaits none of them. If it awaited, the router would hold the
+	// and awaits it nowhere. If it awaited, the router would hold the whole page —
-	// whole page until the slowest answered and this would time out on the tiles.
+	// heading and period picker included — until the response landed.
 	let release = () => {};
-	delayed.set("/api/stats/routes", new Promise<void>((resolve) => (release = resolve)));
+	delayed = new Promise<void>((resolve) => (release = resolve));
 
 	renderApp();
 
-	// The tiles and both charts are readable while the routes request is still
+	await screen.findByRole("heading", { name: "Overview", level: 1 });
-	// in flight, and the panel waiting on it says so for itself.
+	expect(screen.getByRole("radio", { name: "1h" })).toBeTruthy();
-	await screen.findByText("1,000");
+	// One loading state for the whole page, not one per panel.
-	expect(within(panel("Queries over time")).getAllByText("Blocked").length).toBeGreaterThan(0);
+	const loading = await screen.findByText("Loading…");
-	expect(within(panel("Client activity over time")).getAllByText("192.0.2.30")).toHaveLength(2);
+	expect(loading.getAttribute("role")).toBe("status");
-	expect(within(panel("Query types")).getAllByText("A")).toHaveLength(2);
+	expect(screen.getAllByText("Loading…")).toHaveLength(1);
-	expect(within(panel("Upstream servers")).getByRole("status").textContent).toBe("Loading…");
+	expect(screen.queryByRole("heading", { name: "Query types" })).toBeNull();
 
 	release();
-	await waitFor(() => expect(within(panel("Upstream servers")).queryByRole("status")).toBeNull());
+	delayed = null;
+	await screen.findByText("1,000");
+	expect(screen.queryByText("Loading…")).toBeNull();
 });
 
 test("a registered client is named in the chart, an unregistered one keeps its address", async () => {
@@ -248,6 +214,16 @@ test("a registered client is named in the chart, an unregistered one keeps its a
 	await waitFor(() => expect(within(chart).getAllByText("kitchen-pi")).toHaveLength(2));
 	expect(within(chart).queryByText("192.0.2.30")).toBeNull();
 	expect(within(chart).getAllByText("192.0.2.31")).toHaveLength(2);
+
+	// Nor on hover: a pointer-only tooltip would say what the design just chose
+	// not to, and only to a reader holding a mouse.
+	const legendItem = within(chart)
+		.getAllByText("kitchen-pi")
+		.map((node) => node.closest("li"))
+		.find((node) => node !== null);
+	expect(legendItem).toBeTruthy();
+	expect(legendItem?.getAttribute("title")).toBeNull();
+	expect(within(chart).getByRole("list").querySelectorAll("[title]")).toHaveLength(0);
 });
 
 test("a client named only by reverse DNS is named by it too", async () => {
@@ -369,14 +345,23 @@ test("an empty window says so in every panel instead of drawing nothing", async
 test("a deep link opens on the period it names", async () => {
 	renderApp("/overview?period=1h");
 	await screen.findByText("12");
-	expect(screen.getByRole("button", { name: "1h" }).getAttribute("aria-pressed")).toBe("true");
+	// One radio group named Period, holding the four periods and exactly one
-	expect(screen.getByRole("button", { name: "24h" }).getAttribute("aria-pressed")).toBe("false");
+	// selection: the segmented picker is a single choice, not four toggles.
+	const picker = within(screen.getByRole("radiogroup", { name: "Period" }));
+	expect(picker.getAllByRole("radio").map((radio) => radio.getAttribute("value"))).toEqual([
+		"1h",
+		"24h",
+		"7d",
+		"30d",
+	]);
+	expect(picker.getByRole("radio", { name: "1h", checked: true })).toBeTruthy();
+	expect(picker.getByRole("radio", { name: "24h", checked: false })).toBeTruthy();
 });
 
 test("a period the API does not have falls back to the default without carrying it in the url", async () => {
 	const router = renderApp("/overview?period=90d");
 	await screen.findByText("1,000");
-	expect(screen.getByRole("button", { name: "24h" }).getAttribute("aria-pressed")).toBe("true");
+	expect(screen.getByRole("radio", { name: "24h", checked: true })).toBeTruthy();
 	expect(router.state.location.search).toEqual({});
 });
 
@@ -384,7 +369,7 @@ test("the picker rescopes every panel and writes the period into the url", async
 	const router = renderApp();
 	await screen.findByText("1,000");
 
-	fireEvent.click(screen.getByRole("button", { name: "1h" }));
+	fireEvent.click(screen.getByRole("radio", { name: "1h" }));
 
 	await screen.findByText("12");
 	await waitFor(() => expect(router.state.location.search).toEqual({ period: "1h" }));
@@ -392,17 +377,24 @@ test("the picker rescopes every panel and writes the period into the url", async
 	expect(screen.queryByText("1,000")).toBeNull();
 });
 
-test("one failing panel keeps its own error and leaves the rest of the page standing", async () => {
+test("a failed request is one error for the whole page, stated once and retryable", async () => {
-	failing.add("/api/stats/routes");
+	failing = true;
 	renderApp();
-	await screen.findByText("1,000");
 
-	await waitFor(() => expect(within(panel("Upstream servers")).getByText("endpoint unavailable")).toBeTruthy());
+	await screen.findByText("endpoint unavailable");
-	expect(within(panel("Upstream servers")).getByRole("button", { name: "Retry" })).toBeTruthy();
+	// One statement of the failure, not one per panel: there is a single request
-	// A failed donut never blanks the charts.
+	// behind every panel, so a second copy would only repeat this sentence.
-	expect(screen.getByRole("img", { name: /queries over time/i })).toBeTruthy();
+	expect(screen.getAllByText("endpoint unavailable")).toHaveLength(1);
-	expect(screen.getByRole("img", { name: /client activity over time/i })).toBeTruthy();
+	expect(screen.getAllByRole("button", { name: "Retry" })).toHaveLength(1);
+	// The heading and the picker survive it, so the reader can rescope or retry.
+	expect(screen.getByRole("heading", { name: "Overview", level: 1 })).toBeTruthy();
+	expect(screen.getByRole("radio", { name: "1h" })).toBeTruthy();
 	expect(screen.queryByText("Something went wrong")).toBeNull();
+
+	failing = false;
+	fireEvent.click(screen.getByRole("button", { name: "Retry" }));
+	await screen.findByText("1,000");
+	expect(screen.getByRole("img", { name: /queries over time/i })).toBeTruthy();
 });
 
 test("an incomplete window states its watermark once for the whole page", async () => {

admin/src/features/overview/OverviewPage.tsx

@@ -8,9 +8,9 @@
  * The period is URL state, so a view is a link: `/overview?period=1h` opens
  * exactly what the sender was reading.
  *
- * Every panel reads the same window (`overviewWindow.ts`) and renders on its
+ * One request feeds every panel (`overviewWindow.ts`), so the page has one
- * own. A donut whose request failed shows its own error while the charts keep
+ * loading state and one error state rather than six: there is no longer a
- * their data, and no two panels ever describe different spans.
+ * partial answer to render, and nothing left for a panel to disagree about.
  */
 
 import * as stylex from "@stylexjs/stylex";
@@ -18,16 +18,16 @@ import { useNavigate, useSearch } from "@tanstack/react-router";
 import CoverageNotice from "@/lib/CoverageNotice";
 import InlineError from "@/lib/InlineError";
 import { qtypeName } from "@/features/provenance/qtype";
-import type { Period, StatsRoutes, StatsTypes } from "@/lib/types";
+import type { Overview, OverviewRouteRow, OverviewTypeRow } from "@/lib/types";
-import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
 import ClientChart from "./ClientChart";
 import Donut from "./Donut";
 import StatTiles from "./StatTiles";
 import TimeseriesChart from "./TimeseriesChart";
 import type { DonutSlice } from "./Donut";
+import { OverviewFrame, OverviewLoading } from "./OverviewFrame";
 import { useOverviewWindow, type Panel } from "./overviewWindow";
-import { DEFAULT_PERIOD, PERIODS } from "./period";
+import { DEFAULT_PERIOD } from "./period";
 import { qtypeKey, routeKey, seriesColor } from "./seriesColors";
 
 /**
@@ -48,48 +48,6 @@ const ROUTE_LABELS = {
 } as const;
 
 const styles = stylex.create({
-	page: {
-		display: "flex",
-		flexDirection: "column",
-		gap: "1rem",
-	},
-	headingRow: {
-		display: "flex",
-		flexWrap: "wrap",
-		alignItems: "center",
-		justifyContent: "space-between",
-		gap: "0.75rem",
-	},
-	heading: {
-		fontSize: "1.5rem",
-		lineHeight: "2rem",
-		fontWeight: 600,
-	},
-	periodGroup: {
-		display: "flex",
-		gap: "0.25rem",
-	},
-	period: {
-		borderStyle: "none",
-		borderRadius: "0.25rem",
-		paddingInline: "0.625rem",
-		paddingBlock: "0.25rem",
-		fontSize: "0.875rem",
-		lineHeight: "1.25rem",
-	},
-	/** The pressed fill is heavier than `surfaceHover`, so a hover cannot mimic it. */
-	periodSelected: {
-		backgroundColor: {
-			default: "oklch(92% 0.004 286.32)",
-			"@media (prefers-color-scheme: dark)": "oklch(37% 0.013 285.805)",
-		},
-		color: colors.text,
-		fontWeight: 500,
-	},
-	periodIdle: {
-		backgroundColor: { default: "transparent", ":hover": colors.surfaceHover },
-		color: colors.textSecondary,
-	},
 	panel: {
 		borderRadius: "0.25rem",
 		borderWidth: 1,
@@ -110,54 +68,20 @@ const styles = stylex.create({
 		gap: "1rem",
 		gridTemplateColumns: { default: "minmax(0, 1fr)", [TWO_COLUMN]: "repeat(2, minmax(0, 1fr))" },
 	},
-	loading: {
-		fontSize: "0.875rem",
-		lineHeight: "1.25rem",
-		color: colors.textMuted,
-	},
 });
 
-function PeriodPicker({ period, onChange }: { period: Period; onChange: (period: Period) => void }) {
-	return (
-		<div role="group" aria-label="Period" {...stylex.props(styles.periodGroup)}>
-			{PERIODS.map((option) => (
-				<button
-					key={option}
-					type="button"
-					aria-pressed={option === period}
-					onClick={() => onChange(option)}
-					{...stylex.props(
-						styles.period,
-						option === period ? styles.periodSelected : styles.periodIdle,
-						shared.focusRing,
-					)}
-				>
-					{option}
-				</button>
-			))}
-		</div>
-	);
-}
-
 /**
- * One panel's three states. Loading and error are the panel's own: a failure
+ * The page's three states. The heading and the period picker stay put through
- * here never reaches past this box, which is what keeps a failed donut from
+ * all three, so the reader can rescope or retry without waiting for anything.
- * blanking the charts beside it.
  */
-function PanelBody<T>({ panel, children }: { panel: Panel<T>; children: (data: T) => React.ReactNode }) {
+function PageBody({ panel, children }: { panel: Panel<Overview>; children: (data: Overview) => React.ReactNode }) {
 	if (panel.status === "error") return <InlineError error={panel.error} onRetry={panel.retry} />;
-	if (panel.status === "loading") {
+	if (panel.status === "loading") return <OverviewLoading />;
-		return (
-			<p role="status" {...stylex.props(styles.loading, shared.pulse)}>
-				Loading…
-			</p>
-		);
-	}
 	return <>{children(panel.data)}</>;
 }
 
-function typeSlices(data: StatsTypes): DonutSlice[] {
+function typeSlices(types: OverviewTypeRow[]): DonutSlice[] {
-	return data.types.map((row) => ({
+	return types.map((row) => ({
 		key: qtypeKey(row.qtype),
 		label: row.qtype === null ? "Unknown" : qtypeName(row.qtype),
 		value: row.count,
@@ -171,8 +95,8 @@ function typeSlices(data: StatsTypes): DonutSlice[] {
  * appear under two kinds and two rows can both be "Unknown". The four
  * source-less kinds are their own label and need no qualifier.
  */
-function routeSlices(data: StatsRoutes): DonutSlice[] {
+function routeSlices(routes: OverviewRouteRow[]): DonutSlice[] {
-	return data.routes.map((row) => {
+	return routes.map((row) => {
 		const named = row.route === "upstream" || row.route === "forward_zone";
 		return {
 			key: routeKey(row.route, row.source),
@@ -190,59 +114,54 @@ export default function OverviewPage() {
 	const overview = useOverviewWindow(period);
 
 	return (
-		<div {...stylex.props(styles.page)}>
+		<OverviewFrame
-			<div {...stylex.props(styles.headingRow)}>
+			period={period}
-				<h1 {...stylex.props(styles.heading)}>Overview</h1>
+			onChange={(next) => void navigate({ search: (prev) => ({ ...prev, period: next }) })}
-				<PeriodPicker
+		>
-					period={period}
+			<PageBody panel={overview}>
-					onChange={(next) => void navigate({ search: (prev) => ({ ...prev, period: next }) })}
+				{(data) => (
-				/>
+					<>
-			</div>
+						<StatTiles stats={{ since: data.since, until: data.until, ...data.totals }} />
 
-			<PanelBody panel={overview.totals}>{(totals) => <StatTiles stats={totals} />}</PanelBody>
+						{/* One notice for the page: every panel came out of this one
+						    response, so a second copy would only repeat this sentence. */}
+						<CoverageNotice coverage={data.coverage} />
 
-			{/* One notice for the page: every panel is judged against the same window,
+						<section aria-labelledby="overview-queries" {...stylex.props(styles.panel)}>
-			    so a second copy would only repeat this sentence. */}
+							<h2 id="overview-queries" {...stylex.props(styles.panelHeading)}>
-			{overview.coverage !== null && <CoverageNotice coverage={overview.coverage} />}
+								Queries over time
+							</h2>
+							<TimeseriesChart data={data} />
+						</section>
 
-			<section aria-labelledby="overview-queries" {...stylex.props(styles.panel)}>
+						<section aria-labelledby="overview-clients" {...stylex.props(styles.panel)}>
-				<h2 id="overview-queries" {...stylex.props(styles.panelHeading)}>
+							<h2 id="overview-clients" {...stylex.props(styles.panelHeading)}>
-					Queries over time
+								Client activity over time
-				</h2>
+							</h2>
-				<PanelBody panel={overview.timeseries}>{(data) => <TimeseriesChart data={data} />}</PanelBody>
+							<ClientChart data={data} />
-			</section>
+						</section>
 
-			<section aria-labelledby="overview-clients" {...stylex.props(styles.panel)}>
+						<div {...stylex.props(styles.donutRow)}>
-				<h2 id="overview-clients" {...stylex.props(styles.panelHeading)}>
+							<section aria-labelledby="overview-types" {...stylex.props(styles.panel)}>
-					Client activity over time
+								<h2 id="overview-types" {...stylex.props(styles.panelHeading)}>
-				</h2>
+									Query types
-				<PanelBody panel={overview.clients}>{(data) => <ClientChart data={data} />}</PanelBody>
+								</h2>
-			</section>
+								<Donut slices={typeSlices(data.types)} caption="Queries by DNS type" unit="Queries" />
-
+							</section>
-			<div {...stylex.props(styles.donutRow)}>
+							<section aria-labelledby="overview-routes" {...stylex.props(styles.panel)}>
-				<section aria-labelledby="overview-types" {...stylex.props(styles.panel)}>
+								<h2 id="overview-routes" {...stylex.props(styles.panelHeading)}>
-					<h2 id="overview-types" {...stylex.props(styles.panelHeading)}>
+									Upstream servers
-						Query types
+								</h2>
-					</h2>
+								<Donut
-					<PanelBody panel={overview.types}>
+									slices={routeSlices(data.routes)}
-						{(data) => <Donut slices={typeSlices(data)} caption="Queries by DNS type" unit="Queries" />}
+									caption="Queries by how they were answered"
-					</PanelBody>
+									unit="Queries"
-				</section>
+								/>
-				<section aria-labelledby="overview-routes" {...stylex.props(styles.panel)}>
+							</section>
-					<h2 id="overview-routes" {...stylex.props(styles.panelHeading)}>
+						</div>
-						Upstream servers
+					</>
-					</h2>
+				)}
-					<PanelBody panel={overview.routes}>
+			</PageBody>
-						{(data) => (
+		</OverviewFrame>
-							<Donut
-								slices={routeSlices(data)}
-								caption="Queries by how they were answered"
-								unit="Queries"
-							/>
-						)}
-					</PanelBody>
-				</section>
-			</div>
-		</div>
 	);
 }

admin/src/features/overview/StatTiles.tsx

@@ -5,7 +5,7 @@
  * typographic, so the eye ranks the figures rather than the panels, and a tile
  * never implies a state it is not reporting.
  *
- * The Activity links carry the bounds the **stats response** returned, not
+ * The Activity links carry the bounds the **overview response** returned, not
  * bounds computed here — a client-computed window would send the reader to a
  * slightly different span than the one they were just reading.
  */
@@ -13,7 +13,7 @@
 import * as stylex from "@stylexjs/stylex";
 import { Link } from "@tanstack/react-router";
 import { formatMicros } from "@/lib/format";
-import type { StatsTotals } from "@/lib/types";
+import type { OverviewTotals } from "@/lib/types";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
 
@@ -101,7 +101,13 @@ function Tile({
 	);
 }
 
-export default function StatTiles({ stats }: { stats: StatsTotals }) {
+/** The window's totals with the bounds they were measured over. */
+export interface StatTilesData extends OverviewTotals {
+	since: number;
+	until: number;
+}
+
+export default function StatTiles({ stats }: { stats: StatTilesData }) {
 	const window = {
 		mode: "history" as const,
 		since: stats.since,

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

@@ -1,24 +1,17 @@
 import { fireEvent, render, screen, within } from "@testing-library/react";
 import * as stylex from "@stylexjs/stylex";
 import { formatTime } from "@/lib/format";
-import type { Bucket, StatsTimeseries } from "@/lib/types";
+import type { Bucket } from "@/lib/types";
 import { styles as shared } from "@/ui/styles";
-import TimeseriesChart from "./TimeseriesChart";
+import TimeseriesChart, { type TimeseriesData } from "./TimeseriesChart";
 
 const SINCE = 1_700_000_000;
 
-function timeseries(buckets: Bucket[]): StatsTimeseries {
+function timeseries(buckets: Bucket[]): TimeseriesData {
-	return {
+	return { since: SINCE, bucket_seconds: 1800, buckets };
-		period: "24h",
-		since: SINCE,
-		until: SINCE + buckets.length * 1800,
-		bucket_seconds: 1800,
-		coverage: { complete: true, available_since: SINCE },
-		buckets,
-	};
 }
 
-function counting(bucketCount: number): StatsTimeseries {
+function counting(bucketCount: number): TimeseriesData {
 	return timeseries(
 		Array.from({ length: bucketCount }, (_, i) => ({
 			ts: SINCE + i * 1800,

admin/src/features/overview/TimeseriesChart.tsx

@@ -2,7 +2,7 @@ import * as stylex from "@stylexjs/stylex";
 import { Group } from "@visx/group";
 import { BarStack } from "@visx/shape";
 import { formatTime } from "@/lib/format";
-import type { Bucket, StatsTimeseries } from "@/lib/types";
+import type { Bucket } from "@/lib/types";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
 import {
@@ -103,7 +103,17 @@ function tooltipOf(column: Column): TooltipContent {
 	};
 }
 
-export default function TimeseriesChart({ data }: { data: StatsTimeseries }) {
+/**
+ * The slice of the Overview body this chart draws. Declared here rather than
+ * taken whole, so what the chart reads is stated where it is read.
+ */
+export interface TimeseriesData {
+	since: number;
+	bucket_seconds: number;
+	buckets: Bucket[];
+}
+
+export default function TimeseriesChart({ data }: { data: TimeseriesData }) {
 	const [containerRef, width] = useMeasuredWidth();
 	// 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.

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

@@ -1,74 +1,41 @@
 /**
- * Window coherence across the five Overview requests, migrated from the
+ * The hook over the single `/api/overview` request.
- * two-request `activityWindow` this replaces. Every behaviour that hook pinned
+ *
- * is pinned here — the identity, the one retry per mismatch episode, the
+ * The five-endpoint build reconciled five window identities here — the retry per
- * terminal error, the discarded previous-period pair and the stale completion
+ * mismatch episode, the terminal "different window" error, the orphaned stale
- * that must not speak — now over five endpoints and with the watermark in the
+ * completion. One request cannot disagree with itself, so those behaviours have
- * identity, plus the per-panel isolation the layout added.
+ * no subject left and are gone rather than ported. What survived the collapse is
+ * pinned below: the three states, and the one rule a single request still does
+ * not settle — that a `keepPreviousData` body from the period the reader left
+ * must never render under the new period's label.
  */
 
 import { render, screen, waitFor } from "@testing-library/react";
 import { QueryClientProvider } from "@tanstack/react-query";
 import { createQueryClient } from "@/lib/queryClient";
-import type { Coverage, Period } from "@/lib/types";
+import type { Period } from "@/lib/types";
-import {
+import { useOverviewWindow } from "./overviewWindow";
-	newerWindow,
-	sameWindow,
-	useOverviewWindow,
-	windowIdOf,
-	OVERVIEW_ENDPOINTS,
-	type OverviewEndpoint,
-} from "./overviewWindow";
 
 const SINCE = Date.UTC(2026, 0, 1, 0, 0) / 1000;
 const UNTIL = Date.UTC(2026, 0, 2, 0, 0) / 1000;
-const COVERAGE: Coverage = { complete: true, available_since: SINCE };
 
-/** Where each endpoint's body currently ends, and what watermark it admits. */
+let failing: boolean;
-interface Bounds {
+let calls: number;
-	until: number;
-	availableSince: number;
-}
 
-const PATHS: Record<OverviewEndpoint, string> = {
+function body(period: Period): unknown {
-	totals: "/api/stats?period=",
+	return {
-	timeseries: "/api/stats/timeseries?period=",
+		period,
-	clients: "/api/stats/clients?period=",
+		since: SINCE,
-	types: "/api/stats/types?period=",
+		until: UNTIL,
-	routes: "/api/stats/routes?period=",
+		bucket_seconds: 1800,
-};
+		totals: { queries: 10, blocked: 2, clients: 1, avg_response_time_us: 1000 },
-
+		buckets: [],
-let bounds: Record<OverviewEndpoint, Bounds>;
+		clients: [],
-let failing: Set<OverviewEndpoint>;
+		other: [],
-let calls: Record<OverviewEndpoint, number>;
+		types: [],
-/** Endpoints that answer for the page's window from their second call onward. */
+		routes: [],
-let catchUp: Set<OverviewEndpoint>;
+		coverage: { complete: true, available_since: SINCE },
-/** Held to keep one answer in flight while the test moves the page on. */
+	};
-let hold: { promise: Promise<void>; release: () => void } | null;
-
-function endpointOf(url: string): OverviewEndpoint | null {
-	// Longest prefix first: `/api/stats?` and `/api/stats/…` share a stem.
-	for (const endpoint of ["timeseries", "clients", "types", "routes", "totals"] as const) {
-		if (url.startsWith(PATHS[endpoint])) return endpoint;
-	}
-	return null;
-}
-
-function body(endpoint: OverviewEndpoint, period: Period): unknown {
-	const { until, availableSince } = bounds[endpoint];
-	const shared = { period, since: SINCE, until, coverage: { ...COVERAGE, available_since: availableSince } };
-	switch (endpoint) {
-		case "totals":
-			return { ...shared, queries: 10, blocked: 2, clients: 1, avg_response_time_us: 1000 };
-		case "timeseries":
-			return { ...shared, bucket_seconds: 3600, buckets: [] };
-		case "clients":
-			return { ...shared, bucket_seconds: 3600, clients: [], other: [] };
-		case "types":
-			return { ...shared, types: [] };
-		case "routes":
-			return { ...shared, routes: [] };
-	}
 }
 
 function json(payload: unknown, status = 200): Response {
@@ -76,55 +43,36 @@ function json(payload: unknown, status = 200): Response {
 }
 
 beforeEach(() => {
-	bounds = {
+	failing = false;
-		totals: { until: UNTIL, availableSince: SINCE },
+	calls = 0;
-		timeseries: { until: UNTIL, availableSince: SINCE },
-		clients: { until: UNTIL, availableSince: SINCE },
-		types: { until: UNTIL, availableSince: SINCE },
-		routes: { until: UNTIL, availableSince: SINCE },
-	};
-	failing = new Set();
-	catchUp = new Set();
-	hold = null;
-	calls = { totals: 0, timeseries: 0, clients: 0, types: 0, routes: 0 };
 	vi.stubGlobal(
 		"fetch",
 		vi.fn(async (input: RequestInfo | URL) => {
 			const url = String(input);
-			const endpoint = endpointOf(url);
+			if (!url.startsWith("/api/overview")) return json({ error: "not stubbed" }, 404);
-			if (endpoint === null) return json({ error: "not stubbed" }, 404);
+			calls += 1;
-			calls[endpoint] += 1;
+			if (failing) return json({ error: "endpoint unavailable" }, 400);
-			if (failing.has(endpoint)) return json({ error: "endpoint unavailable" }, 400);
-			if (catchUp.has(endpoint) && calls[endpoint] >= 2)
-				bounds[endpoint] = { until: UNTIL, availableSince: SINCE };
 			const period = (new URLSearchParams(url.split("?")[1]).get("period") ?? "24h") as Period;
-			// Built before the wait, so a held answer carries what its own request
+			return json(body(period));
-			// would have returned rather than what the page has moved on to.
-			const payload = json(body(endpoint, period));
-			if (hold !== null && endpoint === "routes" && calls.routes === 2) await hold.promise;
-			return payload;
 		}),
 	);
 });
 
 afterEach(() => vi.unstubAllGlobals());
 
+/** The last retry the hook handed out, so a test can spend it. */
+let lastRetry: () => void;
+
 function Probe({ period }: { period: Period }) {
-	const overview = useOverviewWindow(period);
+	const panel = useOverviewWindow(period);
-	return (
+	if (panel.status === "error") lastRetry = panel.retry;
-		<ul>
+	const detail =
-			{OVERVIEW_ENDPOINTS.map((endpoint) => {
+		panel.status === "ready"
-				const panel = overview[endpoint];
+			? `${panel.data.period}@${panel.data.until}`
-				const detail =
+			: panel.status === "error"
-					panel.status === "ready"
+				? (panel.error as Error).message
-						? `${panel.data.period}@${panel.data.until}/${panel.data.coverage.available_since}`
+				: "";
-						: panel.status === "error"
+	return <p>{`${panel.status}:${detail}`}</p>;
-							? (panel.error as Error).message
-							: "";
-				return <li key={endpoint}>{`${endpoint}:${panel.status}:${detail}`}</li>;
-			})}
-		</ul>
-	);
 }
 
 function renderProbe(period: Period = "24h") {
@@ -144,149 +92,36 @@ function renderProbe(period: Period = "24h") {
 	};
 }
 
-function line(endpoint: OverviewEndpoint): string {
+function line(): string {
-	const item = screen.getAllByRole("listitem").find((element) => element.textContent?.startsWith(`${endpoint}:`));
+	return screen.getByRole("paragraph").textContent ?? "";
-	if (item === undefined) throw new Error(`no probe line for ${endpoint}`);
-	return item.textContent ?? "";
 }
 
-test("the window identity is the period, both bounds and the watermark together", () => {
+test("the page is loading until the body for the selected period arrives", async () => {
-	const base = { period: "24h" as const, since: SINCE, until: UNTIL, availableSince: SINCE };
-	expect(sameWindow(base, { ...base })).toBe(true);
-	expect(sameWindow(base, { ...base, period: "1h" })).toBe(false);
-	expect(sameWindow(base, { ...base, since: SINCE - 1 })).toBe(false);
-	expect(sameWindow(base, { ...base, until: UNTIL + 1 })).toBe(false);
-	// The bounds agree and the answers still describe different windows: a prune
-	// between the two requests moved what the same span can be answered for.
-	expect(sameWindow(base, { ...base, availableSince: SINCE + 60 })).toBe(false);
-});
-
-test("the newer until wins, and for equal bounds the later watermark does", () => {
-	const base = { period: "24h" as const, since: SINCE, until: UNTIL, availableSince: SINCE };
-	expect(newerWindow(base, { ...base, until: UNTIL + 60 }).until).toBe(UNTIL + 60);
-	expect(newerWindow({ ...base, until: UNTIL + 60 }, base).until).toBe(UNTIL + 60);
-	expect(newerWindow(base, { ...base, availableSince: SINCE + 60 }).availableSince).toBe(SINCE + 60);
-	// A newer watermark does not outrank an older window's later bound.
-	expect(newerWindow({ ...base, until: UNTIL + 60 }, { ...base, availableSince: SINCE + 60 }).until).toBe(UNTIL + 60);
-});
-
-test("windowIdOf reads the four fields off any of the five bodies", () => {
-	expect(windowIdOf({ period: "7d", since: 1, until: 2, coverage: { complete: false, available_since: 3 } })).toEqual(
-		{
-			period: "7d",
-			since: 1,
-			until: 2,
-			availableSince: 3,
-		},
-	);
-});
-
-test("five responses for one window render as five ready panels", async () => {
 	renderProbe();
-	await waitFor(() => expect(line("totals")).toContain("ready"));
+	expect(line()).toBe("loading:");
-	for (const endpoint of OVERVIEW_ENDPOINTS) {
+	await waitFor(() => expect(line()).toBe(`ready:24h@${UNTIL}`));
-		expect(line(endpoint)).toBe(`${endpoint}:ready:24h@${UNTIL}/${SINCE}`);
-	}
 });
 
-test("one endpoint behind a bucket boundary is refetched once and then agrees", async () => {
+test("a failed request is one error for the whole page, with a retry that refetches", async () => {
-	// Behind on its first answer, caught up by the time the hook asks again.
+	failing = true;
-	bounds.routes = { until: UNTIL - 3600, availableSince: SINCE };
-	catchUp.add("routes");
 	renderProbe();
 
-	await waitFor(() => expect(line("routes")).toContain("ready"));
+	await waitFor(() => expect(line()).toBe("error:endpoint unavailable"));
-	expect(calls.routes).toBe(2);
+	const spent = calls;
-	expect(calls.totals).toBe(1);
-});
 
-test("a laggard that stays behind fails its own panel and leaves the rest rendering", async () => {
+	failing = false;
-	bounds.types = { until: UNTIL - 3600, availableSince: SINCE };
+	lastRetry();
-	renderProbe();
+	await waitFor(() => expect(line()).toBe(`ready:24h@${UNTIL}`));
-
+	expect(calls).toBeGreaterThan(spent);
-	await waitFor(() => expect(line("types")).toContain("error"));
-	expect(line("types")).toContain("different window");
-	// One retry, not a loop.
-	expect(calls.types).toBe(2);
-	for (const endpoint of ["totals", "timeseries", "clients", "routes"] as const) {
-		expect(line(endpoint)).toContain("ready");
-	}
-});
-
-test("a failed request degrades its own panel; the charts keep the window", async () => {
-	failing.add("routes");
-	renderProbe();
-
-	await waitFor(() => expect(line("routes")).toContain("error"));
-	expect(line("routes")).toContain("endpoint unavailable");
-	expect(line("timeseries")).toContain("ready");
-	expect(line("totals")).toContain("ready");
-});
-
-test("a watermark that advanced mid-page is a mismatch, not a mixed window", async () => {
-	// Same bounds, later watermark: retention pruned between the two responses.
-	bounds.clients = { until: UNTIL, availableSince: SINCE + 600 };
-	renderProbe();
-
-	await waitFor(() => expect(line("clients")).toContain(`/${SINCE + 600}`));
-	// The page adopts the later watermark, so the four older answers are the
-	// laggards and each gets its one retry rather than rendering beside it.
-	await waitFor(() => expect(calls.totals).toBe(2));
-	expect(line("clients")).toContain("ready");
 });
 
 test("a retained previous-period body never renders under the new period's label", async () => {
 	const { rerenderWith } = renderProbe("24h");
-	await waitFor(() => expect(line("totals")).toBe(`totals:ready:24h@${UNTIL}/${SINCE}`));
+	await waitFor(() => expect(line()).toBe(`ready:24h@${UNTIL}`));
 
 	rerenderWith("1h");
-	// Whatever `keepPreviousData` is holding, no panel may claim it answers 1h.
+	// `keepPreviousData` is holding the 24h body. It is a complete answer and
-	await waitFor(() => expect(line("totals")).toBe(`totals:ready:1h@${UNTIL}/${SINCE}`));
+	// still the wrong one to draw under "1h", so the page waits.
-	for (const endpoint of OVERVIEW_ENDPOINTS) expect(line(endpoint)).toContain("1h@");
+	expect(line()).toBe("loading:");
-});
+	await waitFor(() => expect(line()).toBe(`ready:1h@${UNTIL}`));
-
-test("a period change buys the new window its own retry", async () => {
-	bounds.routes = { until: UNTIL - 3600, availableSince: SINCE };
-	const { rerenderWith } = renderProbe("24h");
-	await waitFor(() => expect(line("routes")).toContain("error"));
-	const spent = calls.routes;
-
-	rerenderWith("1h");
-	// The mismatch persists under the new period, and the episode key changed
-	// with it: the retry the abandoned period spent is not the new one's.
-	await waitFor(() => expect(calls.routes).toBeGreaterThan(spent));
-	await waitFor(() => expect(line("routes")).toContain("error"));
-});
-
-test("a retry in flight when the period changes cannot spend the window's retry later", async () => {
-	// The stale completion the tokens exist to orphan: routes lags under 24h, the
-	// hook issues its one retry, and the reader picks 1h before that retry lands.
-	bounds.routes = { until: UNTIL - 3600, availableSince: SINCE };
-	let release = () => {};
-	hold = { promise: new Promise<void>((resolve) => (release = resolve)), release: () => release() };
-
-	const { rerenderWith } = renderProbe("24h");
-	await waitFor(() => expect(calls.routes).toBe(2));
-
-	bounds.routes = { until: UNTIL, availableSince: SINCE };
-	rerenderWith("1h");
-	await waitFor(() => expect(line("routes")).toContain("1h@"));
-
-	// The abandoned retry lands now, under a period it was never asked for.
-	hold.release();
-	hold = null;
-	await waitFor(() => expect(line("routes")).toContain("ready"));
-
-	// Back to the window it was issued for, still lagging. The stale completion
-	// must not have marked this episode spent: the panel gets a real retry before
-	// it is allowed to reach the terminal error.
-	bounds.routes = { until: UNTIL - 3600, availableSince: SINCE };
-	rerenderWith("24h");
-
-	// The cached lagging body is there to render immediately, and the panel must
-	// not state the terminal error off it: that error means "retried and still
-	// behind", and this visit has not retried anything yet. An abandoned
-	// completion recording the episode as spent is what would produce it here.
-	expect(line("routes")).toContain("loading");
-	await waitFor(() => expect(line("routes")).toContain("different window"));
 });

admin/src/features/overview/overviewWindow.ts

@@ -1,249 +1,34 @@
 /**
- * One period, five requests, one window.
+ * One period, one request, one window.
  *
- * Totals, the timeline, the per-client series and the two breakdowns are
+ * The five per-panel endpoints this replaces could each answer for a different
- * separate calls, so a refresh that straddles a bucket boundary — or a retention
+ * span, so the page had to reconcile five window identities, retry the laggards
- * pass that advances the watermark mid-page — can answer them for different
+ * and fail the ones that stayed behind. `GET /api/overview` answers every panel
- * windows. Rendering them side by side anyway would put a headline count above
+ * out of a single read transaction: the totals, both timelines and both
- * charts of a different span, a mixed page that looks exactly like a real one.
+ * breakdowns describe the same span and the same database state by construction,
+ * and none of that reconciliation has anything left to reconcile.
  *
- * This is **window** coherence, not data-snapshot coherence: matching bounds
+ * What remains is the one rule a single request does not settle by itself.
- * cannot prove a common database state, and live inserts between requests may
+ * `keepPreviousData` holds the body of the period the reader just left — a
- * still shift counts slightly between panels. What it does guarantee is that no
+ * complete, self-consistent answer, and still the wrong one to draw under the
- * two panels ever describe different spans.
+ * new label — so a body is a member of this window only while its own `period`
- *
+ * is the selected one. Until then the page is loading.
- * Rendering is per panel. A panel whose request is still in flight shows its own
- * loading state and a panel whose request failed shows its own error, while the
- * panels that match the window keep rendering — a failed donut never blanks the
- * charts.
  */
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback } from "react";
-import { keepPreviousData, useQuery, type UseQueryResult } from "@tanstack/react-query";
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
-import { statsClientsQuery, statsQuery, statsRoutesQuery, statsTypesQuery, timeseriesQuery } from "@/lib/queries";
+import { overviewQuery } from "@/lib/queries";
-import type {
+import type { Overview, Period } from "@/lib/types";
-	Coverage,
-	Period,
-	StatsClients,
-	StatsRoutes,
-	StatsTimeseries,
-	StatsTotals,
-	StatsTypes,
-} from "@/lib/types";
-
-export const OVERVIEW_ENDPOINTS = ["totals", "timeseries", "clients", "types", "routes"] as const;
-export type OverviewEndpoint = (typeof OVERVIEW_ENDPOINTS)[number];
-
-interface EndpointBodies {
-	totals: StatsTotals;
-	timeseries: StatsTimeseries;
-	clients: StatsClients;
-	types: StatsTypes;
-	routes: StatsRoutes;
-}
-
-/**
- * What makes two responses the same window. `available_since` joins the bounds
- * because retention advancing between requests changes what the same `[since,
- * until)` can answer for, and mixing a pre-prune answer with a post-prune one is
- * the failure the bounds alone would not catch.
- */
-export interface WindowId {
-	period: Period;
-	since: number;
-	until: number;
-	availableSince: number;
-}
-
-/** The four fields every window-bounded stats body carries. */
-interface Bounded {
-	period: Period;
-	since: number;
-	until: number;
-	coverage: Coverage;
-}
-
-export function windowIdOf(body: Bounded): WindowId {
-	return {
-		period: body.period,
-		since: body.since,
-		until: body.until,
-		availableSince: body.coverage.available_since,
-	};
-}
-
-export function sameWindow(a: WindowId, b: WindowId): boolean {
-	return a.period === b.period && a.since === b.since && a.until === b.until && a.availableSince === b.availableSince;
-}
-
-/**
- * Which of two candidate windows the page adopts: the one that reaches further
- * forward in time, and for identical bounds the one that admits the later
- * watermark. Both rules pick the answer a laggard has to catch up to.
- */
-export function newerWindow(a: WindowId, b: WindowId): WindowId {
-	if (b.until !== a.until) return b.until > a.until ? b : a;
-	return b.availableSince > a.availableSince ? b : a;
-}
-
-function keyOf(id: WindowId): string {
-	return `${id.period}|${id.since}|${id.until}|${id.availableSince}`;
-}
 
 export type Panel<T> =
 	{ status: "loading" } | { status: "error"; error: unknown; retry: () => void } | { status: "ready"; data: T };
 
-export interface OverviewWindow {
+export function useOverviewWindow(period: Period): Panel<Overview> {
-	/** Null until one response for the selected period has arrived. */
+	const query = useQuery({ ...overviewQuery(period), placeholderData: keepPreviousData });
-	window: WindowId | null;
+	const { refetch } = query;
-	/** The adopted window's watermark, for the page's single coverage notice. */
+	const retry = useCallback(() => void refetch(), [refetch]);
-	coverage: Coverage | null;
+
-	totals: Panel<StatsTotals>;
+	if (query.isError) return { status: "error", error: query.error, retry };
-	timeseries: Panel<StatsTimeseries>;
+	if (query.data !== undefined && query.data.period === period) return { status: "ready", data: query.data };
-	clients: Panel<StatsClients>;
+	return { status: "loading" };
-	types: Panel<StatsTypes>;
-	routes: Panel<StatsRoutes>;
-}
-
-/**
- * A laggard that stayed behind after its one retry. Not an `ApiError`: nothing
- * failed, the endpoint simply never caught up, and `InlineError` renders the
- * message verbatim.
- */
-export const MISMATCH = new Error("This panel is for a different window than the rest of the page. Try again.");
-
-export function useOverviewWindow(period: Period): OverviewWindow {
-	const queries: { [K in OverviewEndpoint]: UseQueryResult<EndpointBodies[K]> } = {
-		totals: useQuery({ ...statsQuery(period), placeholderData: keepPreviousData }),
-		timeseries: useQuery({ ...timeseriesQuery(period), placeholderData: keepPreviousData }),
-		clients: useQuery({ ...statsClientsQuery(period), placeholderData: keepPreviousData }),
-		types: useQuery({ ...statsTypesQuery(period), placeholderData: keepPreviousData }),
-		routes: useQuery({ ...statsRoutesQuery(period), placeholderData: keepPreviousData }),
-	};
-
-	// A `keepPreviousData` placeholder for the period just left is a complete,
-	// self-consistent body — and still the wrong one to show under the new label,
-	// so it is neither a candidate for the window nor a member of it.
-	const answers = new Map<OverviewEndpoint, WindowId>();
-	for (const endpoint of OVERVIEW_ENDPOINTS) {
-		const data = queries[endpoint].data;
-		if (data !== undefined && data.period === period) answers.set(endpoint, windowIdOf(data));
-	}
-
-	let window: WindowId | null = null;
-	for (const id of answers.values()) window = window === null ? id : newerWindow(window, id);
-
-	// The effect below runs on what the responses say, not on how many times they
-	// arrived: a poll that returns byte-identical data must not restart the retry
-	// bookkeeping. The refetchers ride a ref for the same reason — TanStack hands
-	// back a fresh function identity on some renders, and depending on it would
-	// re-enter the effect with nothing changed.
-	const answersKey = OVERVIEW_ENDPOINTS.map((endpoint) => {
-		const id = answers.get(endpoint);
-		return id === undefined ? "" : keyOf(id);
-	}).join("~");
-	const latest = useRef({ answers, refetch: queries });
-	latest.current = { answers, refetch: queries };
-
-	// Which mismatch episode each endpoint has already spent its retry on, keyed
-	// by endpoint and window identity so a new window buys a new attempt.
-	const retriedFor = useRef(new Map<OverviewEndpoint, string>());
-	// Which retry each endpoint is waiting on. Per endpoint, because one shared
-	// counter would let a second endpoint's retry silence the first's completion;
-	// bumped on every retry issued, so a completion from a window or a period the
-	// page has left can neither clear an error the current one reached nor spend
-	// the current window's one retry.
-	const tokens = useRef(new Map<OverviewEndpoint, number>());
-	// State, not a ref: a retry that returns byte-identical data changes nothing
-	// else a render could see, and the panel still has to reach its error.
-	const [landedFor, setLandedFor] = useState(new Map<OverviewEndpoint, string>());
-
-	// Leaving a period ends every episode it opened. A retry issued for the old
-	// period can still be in flight, and without this its completion would land
-	// under the new one holding a token the map still honours: it would record an
-	// episode as spent, so a return to that window would reach the terminal error
-	// without the retry that error is supposed to follow. Bumping the tokens
-	// orphans those answers, and the cleared maps let the new window start clean.
-	const [lastPeriod, setLastPeriod] = useState(period);
-	if (lastPeriod !== period) {
-		setLastPeriod(period);
-		for (const endpoint of OVERVIEW_ENDPOINTS) {
-			tokens.current.set(endpoint, (tokens.current.get(endpoint) ?? 0) + 1);
-		}
-		retriedFor.current.clear();
-		setLandedFor(new Map());
-	}
-
-	const windowKey = window === null ? null : keyOf(window);
-
-	useEffect(() => {
-		if (windowKey === null) return;
-		for (const [endpoint, identity] of latest.current.answers) {
-			if (keyOf(identity) === windowKey) {
-				retriedFor.current.delete(endpoint);
-				continue;
-			}
-			const episode = `${endpoint}|${windowKey}`;
-			if (retriedFor.current.get(endpoint) === episode) continue;
-			retriedFor.current.set(endpoint, episode);
-			const token = (tokens.current.get(endpoint) ?? 0) + 1;
-			tokens.current.set(endpoint, token);
-			const landed = () => {
-				if (tokens.current.get(endpoint) !== token) return;
-				setLandedFor((previous) => new Map(previous).set(endpoint, episode));
-			};
-			void latest.current.refetch[endpoint].refetch().then(landed, landed);
-		}
-	}, [answersKey, windowKey]);
-
-	const retry = useCallback((endpoint: OverviewEndpoint) => {
-		retriedFor.current.delete(endpoint);
-		tokens.current.set(endpoint, (tokens.current.get(endpoint) ?? 0) + 1);
-		setLandedFor((previous) => {
-			const next = new Map(previous);
-			next.delete(endpoint);
-			return next;
-		});
-		void latest.current.refetch[endpoint].refetch();
-	}, []);
-
-	function panelOf<K extends OverviewEndpoint>(endpoint: K): Panel<EndpointBodies[K]> {
-		const query = queries[endpoint];
-		const onRetry = () => retry(endpoint);
-		if (query.isError) return { status: "error", error: query.error, retry: onRetry };
-		const data = query.data;
-		if (
-			data !== undefined &&
-			windowKey !== null &&
-			data.period === period &&
-			keyOf(windowIdOf(data)) === windowKey
-		) {
-			return { status: "ready", data };
-		}
-		if (windowKey !== null && landedFor.get(endpoint) === `${endpoint}|${windowKey}`) {
-			return { status: "error", error: MISMATCH, retry: onRetry };
-		}
-		return { status: "loading" };
-	}
-
-	const panels = {
-		totals: panelOf("totals"),
-		timeseries: panelOf("timeseries"),
-		clients: panelOf("clients"),
-		types: panelOf("types"),
-		routes: panelOf("routes"),
-	};
-
-	// The notice describes the window, so any member of it can supply the
-	// watermark: whichever panel arrived says the same thing about coverage.
-	let coverage: Coverage | null = null;
-	for (const endpoint of OVERVIEW_ENDPOINTS) {
-		const panel = panels[endpoint];
-		if (panel.status === "ready") {
-			coverage = panel.data.coverage;
-			break;
-		}
-	}
-
-	return { window, coverage, ...panels };
 }

admin/src/features/pause/PauseControl.test.tsx

@@ -91,11 +91,14 @@ test("unpaused: duration menu pauses with the picked duration_seconds", async ()
 
 	fireEvent.click(trigger);
 	expect(trigger.getAttribute("aria-expanded")).toBe("true");
-	for (const label of ["60 seconds", "5 minutes", "30 minutes", "Indefinitely"]) {
+	expect(screen.getAllByRole("menuitem").map((item) => item.textContent)).toEqual([
-		expect(screen.getByRole("button", { name: label })).toBeTruthy();
+		"60 seconds",
-	}
+		"5 minutes",
+		"30 minutes",
+		"Indefinitely",
+	]);
 
-	fireEvent.click(screen.getByRole("button", { name: "5 minutes" }));
+	fireEvent.click(screen.getByRole("menuitem", { name: "5 minutes" }));
 	await waitFor(() => expect(postBodies).toEqual([{ paused: true, duration_seconds: 300 }]));
 
 	await screen.findByRole("button", { name: "Resume" });
@@ -105,7 +108,7 @@ test("indefinite pause sends no duration_seconds", async () => {
 	renderControl();
 
 	fireEvent.click(await findPauseTrigger());
-	fireEvent.click(screen.getByRole("button", { name: "Indefinitely" }));
+	fireEvent.click(screen.getByRole("menuitem", { name: "Indefinitely" }));
 	await waitFor(() => expect(postBodies).toEqual([{ paused: true }]));
 
 	await screen.findByRole("button", { name: "Resume" });
@@ -151,11 +154,15 @@ test("an active resolver states nothing: the button already says Pause", async (
 test("escape closes the duration menu", async () => {
 	renderControl();
 
-	const trigger = await findPauseTrigger();
+	fireEvent.click(await findPauseTrigger());
-	fireEvent.click(trigger);
+	expect(screen.getByRole("menuitem", { name: "Indefinitely" })).toBeTruthy();
-	expect(screen.getByRole("button", { name: "Indefinitely" })).toBeTruthy();
+
-	fireEvent.keyDown(trigger, { key: "Escape" });
+	// Opening the menu moves focus into it, so Escape is pressed where the reader
-	expect(screen.queryByRole("button", { name: "Indefinitely" })).toBeNull();
+	// is, not on the trigger they left.
+	fireEvent.keyDown(screen.getByRole("menu"), { key: "Escape" });
+
+	await waitFor(() => expect(screen.queryByRole("menuitem", { name: "Indefinitely" })).toBeNull());
+	expect(screen.getByRole("button", { name: "Pause" }).getAttribute("aria-expanded")).toBe("false");
 });
 
 test("failed pause with 429 shows a ticking retry countdown", async () => {
@@ -168,7 +175,7 @@ test("failed pause with 429 shows a ticking retry countdown", async () => {
 	renderControl();
 
 	fireEvent.click(await findPauseTrigger());
-	fireEvent.click(screen.getByRole("button", { name: "5 minutes" }));
+	fireEvent.click(screen.getByRole("menuitem", { name: "5 minutes" }));
 
 	const alert = await screen.findByRole("alert");
 	expect(alert.textContent).toBe("Rate limited. Try again in 30s.");
@@ -187,7 +194,7 @@ test("failed pause with 503 shows the degraded message", async () => {
 	renderControl();
 
 	fireEvent.click(await findPauseTrigger());
-	fireEvent.click(screen.getByRole("button", { name: "60 seconds" }));
+	fireEvent.click(screen.getByRole("menuitem", { name: "60 seconds" }));
 
 	const alert = await screen.findByRole("alert");
 	expect(alert.textContent).toBe("The server is starting or degraded. Try again shortly.");
@@ -202,12 +209,12 @@ test("a successful pause clears the previous mutation error", async () => {
 	renderControl();
 
 	fireEvent.click(await findPauseTrigger());
-	fireEvent.click(screen.getByRole("button", { name: "5 minutes" }));
+	fireEvent.click(screen.getByRole("menuitem", { name: "5 minutes" }));
 	await screen.findByRole("alert");
 
 	postFailure = null;
 	fireEvent.click(screen.getByRole("button", { name: "Pause" }));
-	fireEvent.click(screen.getByRole("button", { name: "5 minutes" }));
+	fireEvent.click(screen.getByRole("menuitem", { name: "5 minutes" }));
 
 	await screen.findByRole("button", { name: "Resume" });
 	expect(screen.queryByRole("alert")).toBeNull();
@@ -240,7 +247,7 @@ test("a menu left open when the control withdraws does not come back open", asyn
 	vi.useFakeTimers({ shouldAdvanceTime: true });
 	renderControl();
 	fireEvent.click(await findPauseTrigger());
-	expect(screen.getByRole("button", { name: "Indefinitely" })).toBeTruthy();
+	expect(screen.getByRole("menuitem", { name: "Indefinitely" })).toBeTruthy();
 
 	protection = { state: "unavailable", until: null };
 	await vi.advanceTimersByTimeAsync(11_000);
@@ -253,7 +260,7 @@ test("a menu left open when the control withdraws does not come back open", asyn
 	// reader opened, and nobody opened this one.
 	const trigger = await vi.waitFor(() => screen.getByRole("button", { name: "Pause" }));
 	expect(trigger.getAttribute("aria-expanded")).toBe("false");
-	expect(screen.queryByRole("button", { name: "Indefinitely" })).toBeNull();
+	expect(screen.queryByRole("menuitem", { name: "Indefinitely" })).toBeNull();
 	vi.useRealTimers();
 });
 
@@ -261,7 +268,7 @@ test("a menu open when someone else pauses does not reopen when that pause ends"
 	vi.useFakeTimers({ shouldAdvanceTime: true });
 	renderControl();
 	fireEvent.click(await findPauseTrigger());
-	expect(screen.getByRole("button", { name: "Indefinitely" })).toBeTruthy();
+	expect(screen.getByRole("menuitem", { name: "Indefinitely" })).toBeTruthy();
 
 	// Filtering is paused from somewhere else, and this browser learns it from
 	// the poll. The Resume rendering has no menu.
@@ -274,7 +281,7 @@ test("a menu open when someone else pauses does not reopen when that pause ends"
 
 	const trigger = await vi.waitFor(() => screen.getByRole("button", { name: "Pause" }));
 	expect(trigger.getAttribute("aria-expanded")).toBe("false");
-	expect(screen.queryByRole("button", { name: "Indefinitely" })).toBeNull();
+	expect(screen.queryByRole("menuitem", { name: "Indefinitely" })).toBeNull();
 	vi.useRealTimers();
 });
 

admin/src/features/pause/PauseControl.tsx

@@ -1,8 +1,7 @@
 /**
- * The Pause/Resume control, in the two places a pause is a valid answer to what
+ * The Pause/Resume control, at the foot of the sidebar. A pause stops filtering
- * the reader is looking at: the foot of the sidebar, where it belongs to the
+ * for the whole resolver, so it belongs to the shell rather than to any page,
- * resolver rather than to any page, and beside the detail of a query that was
+ * and it has no second placement.
- * blocked.
  *
  * It reads `Health.protection` rather than `/api/pause` so it cannot contradict
  * the Diagnostics health strip, and it renders nothing at all while protection
@@ -20,9 +19,10 @@
  * line: the button says Pause, which is the whole message.
  */
 
-import { useEffect, useState } from "react";
+import { useEffect } from "react";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import * as stylex from "@stylexjs/stylex";
+import { Button, Menu, MenuItem, MenuTrigger, Popover } from "react-aria-components";
 import { formatClock } from "@/lib/format";
 import { pauseMutation } from "@/lib/queries";
 import InlineError from "@/lib/InlineError";
@@ -48,6 +48,8 @@ const styles = stylex.create({
 			":disabled": "oklch(70.5% 0.015 286.067)",
 			"@media (prefers-color-scheme: dark)": { default: null, ":disabled": "oklch(44.2% 0.017 285.786)" },
 		},
+		/** The sidebar foot is the only placement, and there Log out sets the width. */
+		width: "100%",
 	},
 	row: {
 		display: "flex",
@@ -61,43 +63,44 @@ const styles = stylex.create({
 		lineHeight: "1rem",
 		color: colors.textSecondary,
 	},
-	anchor: {
+	/** `--trigger-width` is RAC's: the menu is as wide as the button that opened it. */
-		position: "relative",
+	popover: {
-	},
+		width: "var(--trigger-width)",
-	menu: {
-		position: "absolute",
-		left: 0,
-		top: "100%",
-		zIndex: 10,
-		marginTop: "0.25rem",
-		display: "flex",
-		width: "9rem",
-		flexDirection: "column",
 		borderRadius: "0.25rem",
 		borderWidth: 1,
 		borderStyle: "solid",
 		borderColor: colors.border,
 		backgroundColor: colors.surfaceRaised,
-		paddingBlock: "0.25rem",
+		color: colors.text,
 		boxShadow: "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)",
 	},
+	menu: {
+		outlineStyle: "none",
+		paddingBlock: "0.25rem",
+	},
 	menuItem: {
-		borderStyle: "none",
+		cursor: "pointer",
-		backgroundColor: { default: "transparent", ":hover": colors.surfaceHover },
-		color: "inherit",
 		paddingInline: "0.75rem",
 		paddingBlock: "0.375rem",
-		textAlign: "left",
 		fontSize: "0.875rem",
 		lineHeight: "1.25rem",
 	},
+	/**
+	 * RAC focuses the item's own node, so the shared ring applies; it is inset
+	 * because an item flush against the popover edge clips an outset one, and
+	 * recoloured because the focus token is the blue this row just painted.
+	 */
+	menuItemFocused: {
+		backgroundColor: colors.primary,
+		color: colors.primaryText,
+		outlineColor: { default: null, ":focus-visible": colors.primaryText },
+	},
 });
 
 export default function PauseControl() {
 	const queryClient = useQueryClient();
 	const protection = useProtection();
 	const mutation = useMutation(pauseMutation(queryClient));
-	const [menuOpen, setMenuOpen] = useState(false);
 	const paused = protection.state === "paused";
 	const { reset } = mutation;
 	useEffect(() => reset(), [paused, reset]);
@@ -108,15 +111,6 @@ export default function PauseControl() {
 	// the wrong action, which is the contradiction this control exists to end.
 	const actionable = protection.state === "active" || protection.state === "paused";
 
-	// Leaving `active` unmounts the menu but not the state that opened it, and
-	// the menu belongs to the active rendering alone — a pause someone else
-	// started, seen through the poll, takes it away exactly as a withdrawal does.
-	// Closing on the way out rather than on the way back means the trigger can
-	// only ever come back shut, however long it was gone.
-	useEffect(() => {
-		if (protection.state !== "active") setMenuOpen(false);
-	}, [protection.state]);
-
 	if (!actionable) return null;
 
 	if (paused) {
@@ -140,41 +134,40 @@ export default function PauseControl() {
 	}
 
 	return (
-		<div
+		<div {...stylex.props(styles.row)}>
-			{...stylex.props(styles.anchor)}
+			<MenuTrigger>
-			onKeyDown={(e) => {
+				<Button
-				if (e.key === "Escape") setMenuOpen(false);
+					isDisabled={mutation.isPending}
-			}}
+					className={() => stylex.props(shared.button, styles.trigger, shared.focusRing).className ?? ""}
-		>
+				>
-			<button
+					Pause
-				type="button"
+				</Button>
-				aria-expanded={menuOpen}
+				<Popover className={() => stylex.props(styles.popover).className ?? ""}>
-				aria-controls="pause-menu"
+					<Menu {...stylex.props(styles.menu)}>
-				onClick={() => setMenuOpen((open) => !open)}
+						{DURATIONS.map(({ label, seconds }) => (
-				disabled={mutation.isPending}
+							<MenuItem
-				{...stylex.props(shared.button, styles.trigger, shared.focusRing)}
+								key={label}
-			>
+								onAction={() =>
-				Pause
+									mutation.mutate(
-			</button>
+										seconds === null
-			{menuOpen && (
+											? { paused: true }
-				<div id="pause-menu" {...stylex.props(styles.menu)}>
+											: { paused: true, duration_seconds: seconds },
-					{DURATIONS.map(({ label, seconds }) => (
+									)
-						<button
+								}
-							key={label}
+								className={({ isFocused }) =>
-							type="button"
+									stylex.props(
-							onClick={() => {
+										styles.menuItem,
-								setMenuOpen(false);
+										shared.insetFocusRing,
-								mutation.mutate(
+										isFocused && styles.menuItemFocused,
-									seconds === null ? { paused: true } : { paused: true, duration_seconds: seconds },
+									).className ?? ""
-								);
+								}
-							}}
+							>
-							{...stylex.props(styles.menuItem, shared.insetFocusRing)}
+								{label}
-						>
+							</MenuItem>
-							{label}
+						))}
-						</button>
+					</Menu>
-					))}
+				</Popover>
-				</div>
+			</MenuTrigger>
-			)}
 			<InlineError error={mutation.error} />
 		</div>
 	);

admin/src/lib/CoverageNotice.tsx

@@ -17,6 +17,12 @@ const styles = stylex.create({
 		lineHeight: "1.25rem",
 		color: colors.textSecondary,
 	},
+	/** The same sentence with no box, for a results footer that already has one. */
+	note: {
+		fontSize: "0.875rem",
+		lineHeight: "1.25rem",
+		color: colors.textMuted,
+	},
 });
 
 /**
@@ -27,11 +33,21 @@ const styles = stylex.create({
  * watermark and nothing more: the same incompleteness covers a log retention
  * has pruned and one that simply has not been running long enough, and the
  * response does not say which.
+ *
+ * `note` is the same sentence without the panel, for a place that already sits
+ * under the data it qualifies — a results footer states the reach of the count
+ * beside it, where a full-width banner would announce a limit as news.
  */
-export default function CoverageNotice({ coverage }: { coverage: Coverage }) {
+export default function CoverageNotice({
+	coverage,
+	variant = "banner",
+}: {
+	coverage: Coverage;
+	variant?: "banner" | "note";
+}) {
 	if (coverage.complete) return null;
 	return (
-		<p role="status" {...stylex.props(styles.notice)}>
+		<p role="status" {...stylex.props(variant === "note" ? styles.note : styles.notice)}>
 			Query history is available from {formatTime(coverage.available_since)}.
 		</p>
 	);

admin/src/lib/InlineError.tsx

@@ -12,6 +12,7 @@ const styles = stylex.create({
 		color: colors.danger,
 	},
 	retry: {
+		cursor: { default: "pointer", ":disabled": "not-allowed" },
 		borderStyle: "none",
 		backgroundColor: "transparent",
 		padding: 0,

admin/src/lib/api.test.ts

@@ -1,4 +1,4 @@
-import { ApiError, deleteGroup, getQueries, getStats, listGroups, login, putGroupSources } from "@/lib/api";
+import { ApiError, deleteGroup, getOverview, getQueries, listGroups, login, putGroupSources } from "@/lib/api";
 
 function jsonResponse(payload: unknown, status = 200, headers: Record<string, string> = {}): Response {
 	return new Response(JSON.stringify(payload), {
@@ -50,7 +50,7 @@ test("falls back to a status message on a non-JSON error body", async () => {
 
 test("parses Retry-After on 429", async () => {
 	fetchMock.mockResolvedValue(jsonResponse({ error: "rate limited" }, 429, { "Retry-After": "17" }));
-	const failure = await getStats("1h").catch((e: unknown) => e);
+	const failure = await getOverview("1h").catch((e: unknown) => e);
 	expect(failure).toBeInstanceOf(ApiError);
 	expect((failure as ApiError).status).toBe(429);
 	expect((failure as ApiError).retryAfter).toBe(17);
@@ -58,7 +58,7 @@ test("parses Retry-After on 429", async () => {
 
 test("ignores a malformed Retry-After header", async () => {
 	fetchMock.mockResolvedValue(jsonResponse({ error: "rate limited" }, 429, { "Retry-After": "soon" }));
-	const failure = await getStats().catch((e: unknown) => e);
+	const failure = await getOverview().catch((e: unknown) => e);
 	expect((failure as ApiError).retryAfter).toBeUndefined();
 });
 

admin/src/lib/api.ts

@@ -23,6 +23,7 @@ import type {
 	LoginResponse,
 	LogoutResponse,
 	LookupResult,
+	Overview,
 	PausePost,
 	PauseState,
 	Period,
@@ -35,11 +36,6 @@ import type {
 	SettingsEnvelope,
 	SettingsPatch,
 	SourceStatus,
-	StatsClients,
-	StatsRoutes,
-	StatsTimeseries,
-	StatsTotals,
-	StatsTypes,
 	Upstream,
 	UpstreamEcho,
 	UpstreamInput,
@@ -112,7 +108,7 @@ export const login = (body: LoginRequest): Promise<LoginResponse> =>
 	request("/api/auth/login", { method: "POST", body });
 export const logout = (): Promise<LogoutResponse> => request("/api/auth/logout", { method: "POST", body: {} });
 
-// Query log + stats
+// Query log + overview
 
 export const getQueries = (filter: QueriesFilter = {}): Promise<QueriesPage> =>
 	request(`/api/queries${qs({ ...filter })}`);
@@ -123,13 +119,8 @@ export const getQueryDetail = (id: number): Promise<QueryDetail> => request(`/ap
 /** `EventSource` URL for the live stream; not a fetch route. */
 export const liveQueriesUrl = "/api/queries/live";
 
-export const getStats = (period?: Period): Promise<StatsTotals> => request(`/api/stats${qs({ period })}`);
+/** Every Overview panel for one window, from one read transaction. */
-export const getStatsTimeseries = (period?: Period): Promise<StatsTimeseries> =>
+export const getOverview = (period?: Period): Promise<Overview> => request(`/api/overview${qs({ period })}`);
-	request(`/api/stats/timeseries${qs({ period })}`);
-export const getStatsTypes = (period?: Period): Promise<StatsTypes> => request(`/api/stats/types${qs({ period })}`);
-export const getStatsRoutes = (period?: Period): Promise<StatsRoutes> => request(`/api/stats/routes${qs({ period })}`);
-export const getStatsClients = (period?: Period): Promise<StatsClients> =>
-	request(`/api/stats/clients${qs({ period })}`);
 
 export const getLookup = (domain: string, groupId?: number): Promise<LookupResult> =>
 	request(`/api/lookup${qs({ domain, group_id: groupId })}`);

admin/src/lib/contractSamples.gen.ts

@@ -29,6 +29,7 @@ import type {
 	LoginResponse,
 	LogoutResponse,
 	LookupResult,
+	Overview,
 	PauseState,
 	QueriesPage,
 	QueryDetail,
@@ -36,11 +37,6 @@ import type {
 	RuleEcho,
 	SettingsEnvelope,
 	SourceStatus,
-	StatsClients,
-	StatsRoutes,
-	StatsTimeseries,
-	StatsTotals,
-	StatsTypes,
 	Upstream,
 	UpstreamEcho,
 	Version,
@@ -588,39 +584,6 @@ export const sample_get_query_detail: QueryDetail = {
 	},
 };
 
-export const sample_get_stats: StatsTotals = {
-	avg_response_time_us: null,
-	blocked: 0,
-	clients: 0,
-	coverage: {
-		available_since: 0,
-		complete: true,
-	},
-	period: "1h",
-	queries: 0,
-	since: 0,
-	until: 0,
-};
-
-export const sample_get_stats_timeseries: StatsTimeseries = {
-	bucket_seconds: 0,
-	buckets: [
-		{
-			blocked: 0,
-			cached: 0,
-			queries: 0,
-			ts: 0,
-		},
-	],
-	coverage: {
-		available_since: 0,
-		complete: true,
-	},
-	period: "1h",
-	since: 0,
-	until: 0,
-};
-
 export const sample_get_pause: PauseState = {
 	paused: false,
 	until: null,
@@ -837,31 +800,35 @@ export const sample_error_not_found: ErrorEnvelope = {
 	error: "not found",
 };
 
-export const sample_get_stats_types: StatsTypes = {
+export const sample_get_overview: Overview = {
-	coverage: {
+	bucket_seconds: 0,
-		available_since: 0,
+	buckets: [
-		complete: true,
-	},
-	period: "1h",
-	since: 0,
-	types: [
 		{
-			count: 0,
+			blocked: 0,
-			qtype: 0,
+			cached: 0,
+			queries: 0,
+			ts: 0,
 		},
+	],
+	clients: [
 		{
-			count: 0,
+			buckets: [0],
-			qtype: null,
+			client: "192.0.2.30",
+		},
+		{
+			buckets: [0],
+			client: "192.0.2.31",
+		},
+		{
+			buckets: [0],
+			client: "192.0.2.32",
 		},
 	],
-	until: 0,
-};
-
-export const sample_get_stats_routes: StatsRoutes = {
 	coverage: {
 		available_since: 0,
 		complete: true,
 	},
+	other: [0],
 	period: "1h",
 	routes: [
 		{
@@ -906,32 +873,22 @@ export const sample_get_stats_routes: StatsRoutes = {
 		},
 	],
 	since: 0,
-	until: 0,
+	totals: {
-};
+		avg_response_time_us: 0,
-
+		blocked: 0,
-export const sample_get_stats_clients: StatsClients = {
+		clients: 0,
-	bucket_seconds: 0,
+		queries: 0,
-	clients: [
+	},
+	types: [
 		{
-			buckets: [0],
+			count: 0,
-			client: "192.0.2.30",
+			qtype: 0,
 		},
 		{
-			buckets: [0],
+			count: 0,
-			client: "192.0.2.31",
+			qtype: null,
-		},
-		{
-			buckets: [0],
-			client: "192.0.2.32",
 		},
 	],
-	coverage: {
-		available_since: 0,
-		complete: true,
-	},
-	other: [0],
-	period: "1h",
-	since: 0,
 	until: 0,
 };
 

admin/src/lib/queries.ts

@@ -21,11 +21,7 @@ import type {
 export const queryKeys = {
 	health: ["health"] as const,
 	version: ["version"] as const,
-	stats: (period: Period) => ["stats", period] as const,
+	overview: (period: Period) => ["overview", period] as const,
-	timeseries: (period: Period) => ["stats", "timeseries", period] as const,
-	statsTypes: (period: Period) => ["stats", "types", period] as const,
-	statsRoutes: (period: Period) => ["stats", "routes", period] as const,
-	statsClients: (period: Period) => ["stats", "clients", period] as const,
 	queriesInfinite: (filter: QueriesFilter) => ["queries", "infinite", filter] as const,
 	queryDetail: (id: number) => ["queries", "detail", id] as const,
 	diagnosticsInfinite: (filter: DiagnosticsFilter) => ["diagnostics", "infinite", filter] as const,
@@ -54,34 +50,10 @@ export const healthQuery = () =>
 export const versionQuery = () =>
 	queryOptions({ queryKey: queryKeys.version, queryFn: api.getVersion, staleTime: Infinity });
 
-export const statsQuery = (period: Period = "24h") =>
+export const overviewQuery = (period: Period = "24h") =>
-	queryOptions({ queryKey: queryKeys.stats(period), queryFn: () => api.getStats(period), refetchInterval: 30_000 });
-
-export const timeseriesQuery = (period: Period = "24h") =>
 	queryOptions({
-		queryKey: queryKeys.timeseries(period),
+		queryKey: queryKeys.overview(period),
-		queryFn: () => api.getStatsTimeseries(period),
+		queryFn: () => api.getOverview(period),
-		refetchInterval: 30_000,
-	});
-
-export const statsTypesQuery = (period: Period = "24h") =>
-	queryOptions({
-		queryKey: queryKeys.statsTypes(period),
-		queryFn: () => api.getStatsTypes(period),
-		refetchInterval: 30_000,
-	});
-
-export const statsRoutesQuery = (period: Period = "24h") =>
-	queryOptions({
-		queryKey: queryKeys.statsRoutes(period),
-		queryFn: () => api.getStatsRoutes(period),
-		refetchInterval: 30_000,
-	});
-
-export const statsClientsQuery = (period: Period = "24h") =>
-	queryOptions({
-		queryKey: queryKeys.statsClients(period),
-		queryFn: () => api.getStatsClients(period),
 		refetchInterval: 30_000,
 	});
 

admin/src/lib/types.ts

@@ -291,15 +291,13 @@ export interface DiagnosticsFilter {
 	before?: number;
 }
 
-export interface StatsTotals {
+/** The window's four headline numbers. */
-	period: Period;
+export interface OverviewTotals {
-	since: number;
-	until: number;
 	queries: number;
 	blocked: number;
+	/** Distinct clients seen in the window, not a sum of per-bucket counts. */
 	clients: number;
 	avg_response_time_us: number | null;
-	coverage: Coverage;
 }
 
 export interface Bucket {
@@ -309,67 +307,53 @@ export interface Bucket {
 	cached: number;
 }
 
-export interface StatsTimeseries {
-	period: Period;
-	since: number;
-	until: number;
-	bucket_seconds: number;
-	buckets: Bucket[];
-	coverage: Coverage;
-}
-
 /**
  * One DNS type's share of the window. `qtype` is the numeric code as logged:
  * naming it is the admin's job (`features/provenance/qtype.ts`), and a row whose
  * type was never recorded keeps its own `null` group rather than disappearing.
  */
-export interface StatsTypeRow {
+export interface OverviewTypeRow {
 	qtype: number | null;
 	count: number;
 }
 
-export interface StatsTypes {
-	period: Period;
-	since: number;
-	until: number;
-	types: StatsTypeRow[];
-	coverage: Coverage;
-}
-
 /**
  * How the window's queries were answered. `source` names the answering upstream
  * on `upstream` rows and the zone on `forward_zone` rows; every other route kind
  * carries null, as does a row whose identity was not recorded.
  */
-export interface StatsRouteRow {
+export interface OverviewRouteRow {
 	route: RouteKind;
 	source: string | null;
 	count: number;
 }
 
-export interface StatsRoutes {
+/** One client's per-bucket counts, aligned to `Overview.buckets`. */
-	period: Period;
+export interface OverviewClientSeries {
-	since: number;
-	until: number;
-	routes: StatsRouteRow[];
-	coverage: Coverage;
-}
-
-/** One client's per-bucket counts, aligned to `StatsTimeseries`'s buckets. */
-export interface StatsClientSeries {
 	client: string;
 	buckets: number[];
 }
 
-export interface StatsClients {
+/**
+ * Everything the Overview page draws, for one window, from one request. The
+ * server answers all six panels out of a single read transaction, so the
+ * headline totals, the two timelines and the two breakdowns are guaranteed to
+ * describe the same span *and* the same database state — a coherence the five
+ * endpoints this replaces could not offer.
+ */
+export interface Overview {
 	period: Period;
 	since: number;
 	until: number;
 	bucket_seconds: number;
+	totals: OverviewTotals;
+	buckets: Bucket[];
 	/** The eight busiest clients in the window, ranked by total count. */
-	clients: StatsClientSeries[];
+	clients: OverviewClientSeries[];
 	/** Everything outside the top eight. Always present and always bucket-count-sized. */
 	other: number[];
+	types: OverviewTypeRow[];
+	routes: OverviewRouteRow[];
 	coverage: Coverage;
 }
 

admin/src/routes.tsx

@@ -32,18 +32,15 @@ import {
 	groupsQuery,
 	healthQuery,
 	localRecordsQuery,
+	overviewQuery,
 	queriesInfiniteQuery,
 	queryDetailQuery,
 	rulesQuery,
 	settingsQuery,
-	statsClientsQuery,
-	statsQuery,
-	statsRoutesQuery,
-	statsTypesQuery,
-	timeseriesQuery,
 	upstreamsQuery,
 } from "@/lib/queries";
 import { DEFAULT_PERIOD, parsePeriod } from "@/features/overview/period";
+import { OverviewPending } from "@/features/overview/OverviewFrame";
 import {
 	validateGroupId,
 	validateProtectionSearch,
@@ -168,26 +165,28 @@ const overviewRoute = createRoute({
 	}),
 	loaderDeps: ({ search }): { period: Period } => ({ period: search.period ?? DEFAULT_PERIOD }),
 	/**
-	 * Started here, awaited nowhere. Every panel reads these with `useQuery` and
+	 * Started here, awaited nowhere. The page reads these with `useQuery` and owns
-	 * owns its own loading and error surface, so awaiting would trade that whole
+	 * its own loading and error surface, so awaiting would trade that contract for
-	 * contract for one blocking navigation: the page would sit on the slowest of
+	 * one blocking navigation: nothing at all until the request answered, rather
-	 * five requests and then appear complete, instead of the four that answered
+	 * than the heading and the period picker while it is in flight. The rejections
-	 * rendering beside the one still in flight. The rejections are caught only to
+	 * are caught only to keep them from going unhandled; the page states them.
-	 * keep them from going unhandled; the panels state them.
 	 */
 	loader: ({ context, deps }) => {
 		const start = (promise: Promise<unknown>) => void promise.catch(() => {});
 		start(context.queryClient.ensureQueryData(healthQuery()));
-		start(context.queryClient.ensureQueryData(statsQuery(deps.period)));
+		start(context.queryClient.ensureQueryData(overviewQuery(deps.period)));
-		start(context.queryClient.ensureQueryData(timeseriesQuery(deps.period)));
-		start(context.queryClient.ensureQueryData(statsClientsQuery(deps.period)));
 		// The registered names the client chart labels its series with. Started here
 		// so the lookup is not a second round trip after the page chunk lands.
 		start(context.queryClient.ensureQueryData(clientsQuery()));
-		start(context.queryClient.ensureQueryData(statsTypesQuery(deps.period)));
-		start(context.queryClient.ensureQueryData(statsRoutesQuery(deps.period)));
 	},
 	component: lazyRouteComponent(() => import("@/features/overview/OverviewPage")),
+	/**
+	 * The page's own loading surface, rendered while its chunk is still in flight.
+	 * The default pending component would put a second, differently-placed
+	 * "Loading…" before it, which reads as a stutter rather than one wait.
+	 * `OverviewFrame` is a separate module so this import leaves the charts lazy.
+	 */
+	pendingComponent: OverviewPending,
 });
 
 /**

admin/src/shell/AppShell.test.tsx

@@ -19,44 +19,16 @@ const RECONCILED_AT = 1754899200;
 const DATABASE: ConfigStatus = { authority: "database", path: null, reconciled_at: null, restart_pending: false };
 
 const RESPONSES: Record<string, unknown> = {
-	"/api/stats?period=24h": {
+	"/api/overview?period=24h": {
-		period: "24h",
-		since: 0,
-		until: 86400,
-		queries: 0,
-		blocked: 0,
-		clients: 0,
-		avg_response_time_us: null,
-		coverage: { complete: true, available_since: 0 },
-	},
-	"/api/stats/timeseries?period=24h": {
 		period: "24h",
 		since: 0,
 		until: 86400,
 		bucket_seconds: 1800,
+		totals: { queries: 0, blocked: 0, clients: 0, avg_response_time_us: null },
 		buckets: [],
-		coverage: { complete: true, available_since: 0 },
-	},
-	"/api/stats/clients?period=24h": {
-		period: "24h",
-		since: 0,
-		until: 86400,
-		bucket_seconds: 1800,
 		clients: [],
 		other: [],
-		coverage: { complete: true, available_since: 0 },
-	},
-	"/api/stats/types?period=24h": {
-		period: "24h",
-		since: 0,
-		until: 86400,
 		types: [],
-		coverage: { complete: true, available_since: 0 },
-	},
-	"/api/stats/routes?period=24h": {
-		period: "24h",
-		since: 0,
-		until: 86400,
 		routes: [],
 		coverage: { complete: true, available_since: 0 },
 	},
@@ -242,12 +214,45 @@ test("mount probe reveals the logout button and a failed logout surfaces inline"
 
 	renderShell();
 
-	fireEvent.click(await screen.findByRole("button", { name: "Log out" }));
+	// Both renderings are mounted; the viewport paints the sidebar one on WIDE
+	// and the header one below it.
+	await waitFor(() => expect(screen.getAllByRole("button", { name: "Log out" })).toHaveLength(2));
+	const aside = document.querySelector("aside") as HTMLElement;
+	fireEvent.click(within(aside).getByRole("button", { name: "Log out" }));
 
-	await screen.findByText("Rate limited. Try again in 7s.");
+	await within(aside).findByText("Rate limited. Try again in 7s.");
 	expect(screen.getByRole("heading", { name: "Overview" })).toBeTruthy();
 });
 
+test("Log out sits in the sidebar on wide, and only in the header below it", async () => {
+	stubFetch((url) =>
+		url === "/api/auth/login"
+			? new Response(JSON.stringify({ error: "password required" }), {
+					status: 401,
+					headers: { "content-type": "application/json" },
+				})
+			: null,
+	);
+	renderShell();
+	await screen.findByRole("heading", { name: "Overview" });
+
+	const aside = document.querySelector("aside") as HTMLElement;
+	const header = document.querySelector("header") as HTMLElement;
+	await waitFor(() => expect(within(aside).getByRole("button", { name: "Log out" })).toBeTruthy());
+	expect(within(header).getByRole("button", { name: "Log out" })).toBeTruthy();
+	// The header is the narrow rendering now: the Menu button is its only nav.
+	expect(within(header).getByRole("button", { name: "Menu" })).toBeTruthy();
+
+	// In the sidebar the control precedes the version label rather than crowding it.
+	const version = within(aside).getByText(/^nxdns v/);
+	const logout = within(aside).getByRole("button", { name: "Log out" });
+	expect(logout.compareDocumentPosition(version) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+	// The drawer keeps no third copy: the header already carries the narrow one.
+	fireEvent.click(within(header).getByRole("button", { name: "Menu" }));
+	const drawer = document.getElementById("mobile-nav") as HTMLElement;
+	expect(within(drawer).queryByRole("button", { name: "Log out" })).toBeNull();
+});
+
 test("the header carries no protection display at all any more", async () => {
 	renderShell();
 	await screen.findByRole("heading", { name: "Overview" });
@@ -285,6 +290,40 @@ test("the mobile drawer carries the same control, not a header one it lost", asy
 	expect(pause.compareDocumentPosition(version) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
 });
 
+test("the Menu button is a disclosure trigger, and it names the panel it opens", async () => {
+	renderShell();
+	await screen.findByRole("heading", { name: "Overview" });
+	const menu = screen.getByRole("button", { name: "Menu" });
+
+	// The trigger states the drawer's state, and points at the drawer itself.
+	expect(menu.getAttribute("aria-expanded")).toBe("false");
+	expect(menu.getAttribute("aria-controls")).toBe("mobile-nav");
+	const drawer = document.getElementById("mobile-nav") as HTMLElement;
+	expect(drawer.getAttribute("hidden")).not.toBeNull();
+
+	fireEvent.click(menu);
+	expect(menu.getAttribute("aria-expanded")).toBe("true");
+	expect(drawer.getAttribute("hidden")).toBeNull();
+	expect(within(drawer).getByRole("navigation", { name: "Main" })).toBeTruthy();
+
+	fireEvent.click(menu);
+	expect(menu.getAttribute("aria-expanded")).toBe("false");
+	expect(drawer.getAttribute("hidden")).not.toBeNull();
+});
+
+test("following a drawer link closes the drawer behind it", async () => {
+	renderShell();
+	await screen.findByRole("heading", { name: "Overview" });
+	const menu = screen.getByRole("button", { name: "Menu" });
+	fireEvent.click(menu);
+
+	const drawer = document.getElementById("mobile-nav") as HTMLElement;
+	fireEvent.click(within(drawer).getByRole("link", { name: "Clients" }));
+
+	await waitFor(() => expect(menu.getAttribute("aria-expanded")).toBe("false"));
+	expect(drawer.getAttribute("hidden")).not.toBeNull();
+});
+
 test("a paused resolver says so in both renderings, not only on Diagnostics", async () => {
 	// The trace a pause leaves on every page. With the header indicator and the
 	// Overview status row both gone, a reader who is not on Diagnostics has only

admin/src/shell/AppShell.tsx

@@ -2,6 +2,7 @@ import { useId, useState } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { Link, Outlet, useNavigate } from "@tanstack/react-router";
 import * as stylex from "@stylexjs/stylex";
+import { Button, Disclosure, DisclosurePanel } from "react-aria-components";
 import { useAuth } from "@/auth/store";
 import InlineError from "@/lib/InlineError";
 import { healthQuery, versionQuery } from "@/lib/queries";
@@ -110,6 +111,17 @@ const styles = stylex.create({
 		alignItems: "center",
 		gap: "0.5rem",
 	},
+	/**
+	 * In a 14rem column the button and its error stack, so the button spans the
+	 * sidebar and matches the Pause trigger below it.
+	 */
+	sidebarLogout: {
+		flexDirection: "column",
+		alignItems: "stretch",
+		gap: "0.25rem",
+		paddingInline: "1rem",
+		paddingTop: "0.75rem",
+	},
 	shell: {
 		minHeight: "100dvh",
 		height: { default: null, [WIDE]: "100dvh" },
@@ -147,8 +159,9 @@ const styles = stylex.create({
 		minWidth: { default: null, [WIDE]: 0 },
 		flexDirection: "column",
 	},
+	/** Narrow only: on WIDE the sidebar carries everything this row held. */
 	header: {
-		display: "flex",
+		display: { default: "flex", [WIDE]: "none" },
 		alignItems: "center",
 		gap: "0.75rem",
 		borderBottomWidth: 1,
@@ -284,13 +297,13 @@ function VersionFooter() {
 	);
 }
 
-function LogoutButton() {
+function LogoutButton({ style }: { style?: stylex.StyleXStyles }) {
 	const { authRequired, logout } = useAuth();
 	const navigate = useNavigate();
 	const [error, setError] = useState<unknown>(null);
 	if (authRequired !== true) return null;
 	return (
-		<div {...stylex.props(styles.logoutRow)}>
+		<div {...stylex.props(styles.logoutRow, style)}>
 			<button
 				type="button"
 				onClick={() => {
@@ -318,37 +331,49 @@ export default function AppShell() {
 				<nav aria-label="Main" {...stylex.props(styles.sidebarNav)}>
 					<NavLinks />
 				</nav>
+				<LogoutButton style={styles.sidebarLogout} />
 				<SidebarFooter />
 			</aside>
-			<div {...stylex.props(styles.column)}>
+			{/* The column itself is the disclosure: the trigger sits in the header
+			    and the panel opens below the notices, so any wrapper around only
+			    the two would have to cut across the column's own flex children. */}
+			<Disclosure
+				isExpanded={drawerOpen}
+				onExpandedChange={setDrawerOpen}
+				{...stylex.props(styles.column)}
+			>
 				<header {...stylex.props(styles.header)}>
-					<button
+					<Button
-						type="button"
+						slot="trigger"
-						aria-expanded={drawerOpen}
+						className={() =>
-						aria-controls="mobile-nav"
+							stylex.props(shared.button, styles.narrowOnly, shared.focusRing).className ?? ""
-						onClick={() => setDrawerOpen((open) => !open)}
+						}
-						{...stylex.props(shared.button, styles.narrowOnly, shared.focusRing)}
 					>
 						Menu
-					</button>
+					</Button>
 					<span {...stylex.props(styles.narrowBrand)}>nxdns</span>
 					<div {...stylex.props(styles.headerRight)}>
 						<LogoutButton />
 					</div>
 				</header>
 				<ConfigStatusNotices />
-				{drawerOpen && (
+				<DisclosurePanel id="mobile-nav" {...stylex.props(styles.drawer)}>
-					<div id="mobile-nav" {...stylex.props(styles.drawer)}>
+					{/* React Aria only hides a collapsed panel; the shell drops it
-						<nav aria-label="Main" {...stylex.props(styles.drawerNav)}>
+					    instead, so a closed drawer keeps no second health poll and
-							<NavLinks onNavigate={() => setDrawerOpen(false)} />
+					    no second Pause control alive behind the header. */}
-						</nav>
+					{drawerOpen && (
-						<SidebarFooter />
+						<>
-					</div>
+							<nav aria-label="Main" {...stylex.props(styles.drawerNav)}>
-				)}
+								<NavLinks onNavigate={() => setDrawerOpen(false)} />
+							</nav>
+							<SidebarFooter />
+						</>
+					)}
+				</DisclosurePanel>
 				<main id="main-content" data-scroll-restoration-id="main" {...stylex.props(styles.main)}>
 					<Outlet />
 				</main>
-			</div>
+			</Disclosure>
 		</div>
 	);
 }

admin/src/ui/Checkbox.test.tsx

@@ -0,0 +1,92 @@
+import { act, fireEvent, render, screen, within } from "@testing-library/react";
+import Checkbox, { CheckboxGroup } from "./Checkbox";
+
+/**
+ * The drawn box, which is the label's one child that does not hold the hidden
+ * input. StyleX compiles to class names and jsdom loads no stylesheet, so the
+ * class list is the only place the composed ring is observable.
+ */
+function indicator(input: HTMLElement): HTMLElement {
+	const label = input.closest("label") as HTMLElement;
+	const spans = [...label.querySelectorAll("span")];
+	const box = spans.find((span) => !span.contains(input));
+	if (box === undefined) throw new Error("the checkbox drew no indicator");
+	return box;
+}
+
+test("a standalone checkbox reports its state and reads its label as its name", () => {
+	const onChange = vi.fn();
+	render(
+		<Checkbox isSelected onChange={onChange}>
+			Safe search
+		</Checkbox>,
+	);
+
+	const box = screen.getByRole("checkbox", { name: "Safe search" }) as HTMLInputElement;
+	expect(box.checked).toBe(true);
+
+	fireEvent.click(box);
+	// The caller owns the state, so the box reports the value it would move to
+	// rather than moving there itself.
+	expect(onChange).toHaveBeenCalledWith(false);
+});
+
+test("a disabled checkbox keeps its state on screen but takes no input", () => {
+	render(
+		<Checkbox isSelected isDisabled onChange={vi.fn()}>
+			Safe search
+		</Checkbox>,
+	);
+
+	const box = screen.getByRole("checkbox", { name: "Safe search" }) as HTMLInputElement;
+	expect(box.checked).toBe(true);
+	// The disabled input is the whole guard: a browser fires no click on one, and
+	// it is out of the tab order. Clicking it here would prove nothing either way,
+	// because `fireEvent` dispatches straight at the node and skips that check.
+	expect(box.disabled).toBe(true);
+});
+
+test("keyboard focus composes the ring onto the drawn box", () => {
+	render(
+		<Checkbox isSelected={false} onChange={vi.fn()}>
+			Ads
+		</Checkbox>,
+	);
+
+	const input = screen.getByRole("checkbox", { name: "Ads" });
+	const box = indicator(input);
+	const idle = box.className.split(" ");
+	expect(input.closest("label")?.getAttribute("data-focus-visible")).toBeNull();
+
+	// React Aria only calls focus visible after the modality is keyboard, which
+	// is why a bare focus() is not enough to raise the ring.
+	act(() => {
+		fireEvent.keyDown(document.body, { key: "Tab" });
+		input.focus();
+	});
+
+	expect(input.closest("label")?.getAttribute("data-focus-visible")).toBe("true");
+	const ringed = box.className.split(" ");
+	// The box gained classes it did not have: the ring is composed onto it, not
+	// merely reported by React Aria on the root.
+	expect(ringed.length).toBeGreaterThan(idle.length);
+	expect(idle.every((name) => ringed.includes(name))).toBe(true);
+});
+
+test("inside a group the group owns the selection, and the group carries the name", () => {
+	const onChange = vi.fn();
+	render(
+		<CheckboxGroup aria-label="Assigned sources" value={["1"]} onChange={onChange}>
+			<Checkbox value="1">Ads</Checkbox>
+			<Checkbox value="2">Trackers</Checkbox>
+		</CheckboxGroup>,
+	);
+
+	const group = screen.getByRole("group", { name: "Assigned sources" });
+	expect((within(group).getByRole("checkbox", { name: "Ads" }) as HTMLInputElement).checked).toBe(true);
+	expect((within(group).getByRole("checkbox", { name: "Trackers" }) as HTMLInputElement).checked).toBe(false);
+
+	// The group reports the whole set, not the box that moved.
+	fireEvent.click(within(group).getByRole("checkbox", { name: "Trackers" }));
+	expect(onChange).toHaveBeenCalledWith(["1", "2"]);
+});

admin/src/ui/Checkbox.tsx

@@ -0,0 +1,138 @@
+/**
+ * The checkbox, wrapping React Aria's.
+ *
+ * React Aria hides the real input and leaves the mark to the call site, so the
+ * box below is what the reader sees. It is drawn to the native control's size
+ * so a row that held a native checkbox keeps its height and its baseline.
+ *
+ * One component covers both uses: pass `value` for a box inside a
+ * `CheckboxGroup`, which owns the selection, or `isSelected`/`onChange` for a
+ * standalone box that owns its own.
+ */
+
+import type { ReactNode } from "react";
+import * as stylex from "@stylexjs/stylex";
+import { Checkbox as AriaCheckbox } from "react-aria-components";
+import { colors } from "./tokens.stylex";
+
+/**
+ * Re-exported rather than wrapped: the group adds no styling of its own, and
+ * routing it through here keeps React Aria's checkbox parts to one import site,
+ * the same rule `Select` follows.
+ */
+export { CheckboxGroup } from "react-aria-components";
+
+interface Common {
+	/** The visible label, which is also the accessible name. */
+	children: ReactNode;
+	/** Visible but inert; React Aria also drops it from the tab order. */
+	isDisabled?: boolean;
+}
+
+/** Inside a `CheckboxGroup`, which holds the selection for every box in it. */
+interface Grouped extends Common {
+	value: string;
+	isSelected?: never;
+	onChange?: never;
+}
+
+/** On its own, where the caller holds the state and is told to move it. */
+interface Standalone extends Common {
+	value?: never;
+	isSelected: boolean;
+	onChange: (isSelected: boolean) => void;
+}
+
+/**
+ * The two modes are exclusive: a grouped box that also carried `isSelected`
+ * would have two sources of truth, and a standalone one without `onChange`
+ * could never move. The union is what makes both unrepresentable.
+ */
+type Props = Grouped | Standalone;
+
+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.
+	 */
+	label: {
+		minHeight: 44,
+		minWidth: 44,
+		display: "inline-flex",
+		alignItems: "center",
+		gap: "0.5rem",
+		fontSize: "0.875rem",
+		lineHeight: "1.25rem",
+	},
+	box: {
+		flexShrink: 0,
+		boxSizing: "border-box",
+		width: "0.875rem",
+		height: "0.875rem",
+		display: "inline-flex",
+		alignItems: "center",
+		justifyContent: "center",
+		borderRadius: "0.1875rem",
+		borderWidth: 1,
+		borderStyle: "solid",
+		borderColor: colors.borderStrong,
+		backgroundColor: colors.surfaceRaised,
+	},
+	boxSelected: {
+		borderColor: colors.primary,
+		backgroundColor: colors.primary,
+		color: colors.primaryText,
+	},
+	/**
+	 * The shared ring keys off `:focus-visible`, which lands on the hidden input
+	 * rather than on this box, so the ring follows the state React Aria reports.
+	 */
+	boxFocused: {
+		outlineWidth: 2,
+		outlineStyle: "solid",
+		outlineColor: colors.focus,
+		outlineOffset: 2,
+	},
+	/** The box dims, not the words: the label still has to be readable. */
+	boxDisabled: {
+		opacity: 0.5,
+	},
+});
+
+/** `currentColor` so the mark follows the selected box's foreground token. */
+function CheckMark() {
+	return (
+		<svg aria-hidden="true" viewBox="0 0 12 12" width="10" height="10" fill="none">
+			<path
+				d="M2.5 6.5 5 9l4.5-5.5"
+				stroke="currentColor"
+				strokeWidth="2"
+				strokeLinecap="round"
+				strokeLinejoin="round"
+			/>
+		</svg>
+	);
+}
+
+export default function Checkbox({ children, ...state }: Props) {
+	return (
+		<AriaCheckbox {...state} className={() => stylex.props(styles.label).className ?? ""}>
+			{(renderProps) => (
+				<>
+					<span
+						{...stylex.props(
+							styles.box,
+							renderProps.isSelected && styles.boxSelected,
+							renderProps.isFocusVisible && styles.boxFocused,
+							renderProps.isDisabled && styles.boxDisabled,
+						)}
+					>
+						{renderProps.isSelected && <CheckMark />}
+					</span>
+					{children}
+				</>
+			)}
+		</AriaCheckbox>
+	);
+}

admin/src/ui/ConfirmDialog.tsx

@@ -8,6 +8,7 @@
  * and a stray outside click is not one. Escape still cancels.
  */
 
+import type { ReactNode } from "react";
 import * as stylex from "@stylexjs/stylex";
 import { Dialog as AriaDialog, Heading, Modal, ModalOverlay } from "react-aria-components";
 import { colors } from "./tokens.stylex";
@@ -19,6 +20,14 @@ interface Props {
 	/** The full sentence the operator reads before confirming; names the entity. */
 	message: string;
 	confirmLabel: string;
+	/**
+	 * Stands in for the confirm action when the write can no longer land, the way
+	 * an open edit dialog drops its Save. Closing the dialog instead would throw
+	 * focus at a control that is now disabled and say nothing about why, so the
+	 * question stays on screen and only the answer that would fail is withdrawn.
+	 * Cancel is always live.
+	 */
+	lock?: ReactNode;
 	onConfirm: () => void;
 	onCancel: () => void;
 }
@@ -67,6 +76,7 @@ const styles = stylex.create({
 		marginTop: "1.5rem",
 	},
 	dangerButton: {
+		cursor: { default: "pointer", ":disabled": "not-allowed" },
 		borderRadius: "0.25rem",
 		borderStyle: "none",
 		backgroundColor: colors.danger,
@@ -79,7 +89,7 @@ const styles = stylex.create({
 	},
 });
 
-export default function ConfirmDialog({ isOpen, title, message, confirmLabel, onConfirm, onCancel }: Props) {
+export default function ConfirmDialog({ isOpen, title, message, confirmLabel, lock, onConfirm, onCancel }: Props) {
 	return (
 		<ModalOverlay
 			isOpen={isOpen}
@@ -98,13 +108,17 @@ export default function ConfirmDialog({ isOpen, title, message, confirmLabel, on
 						<button type="button" onClick={onCancel} {...stylex.props(shared.button, shared.focusRing)}>
 							Cancel
 						</button>
-						<button
+						{lock === undefined ? (
-							type="button"
+							<button
-							onClick={onConfirm}
+								type="button"
-							{...stylex.props(styles.dangerButton, shared.focusRing)}
+								onClick={onConfirm}
-						>
+								{...stylex.props(styles.dangerButton, shared.focusRing)}
-							{confirmLabel}
+							>
-						</button>
+								{confirmLabel}
+							</button>
+						) : (
+							lock
+						)}
 					</div>
 				</AriaDialog>
 			</Modal>

admin/src/ui/Dialog.tsx

@@ -4,18 +4,25 @@
  * React Aria owns the focus trap, the Escape handler and the `aria-modal`
  * wiring that the hand-rolled overlay only approximated. State is controlled by
  * the caller because the trigger is a table row button, not a `DialogTrigger`.
+ *
+ * The title is both the visible heading and the accessible name: `Heading
+ * slot="title"` is what React Aria points `aria-labelledby` at, so a caller
+ * cannot name the dialog one thing and show another.
  */
 
 import type { ReactNode } from "react";
 import * as stylex from "@stylexjs/stylex";
-import { Dialog as AriaDialog, Modal, ModalOverlay } from "react-aria-components";
+import { Dialog as AriaDialog, Heading, Modal, ModalOverlay } from "react-aria-components";
 import { colors } from "./tokens.stylex";
+import { styles as shared } from "./styles";
 
 interface Props {
-	/** The dialog's accessible name. */
+	/** The dialog's heading, and with it the dialog's accessible name. */
-	label: string;
+	title: string;
 	isOpen: boolean;
 	onClose: () => void;
+	/** `detail` is the wider panel a record needs; `form` fits a column of fields. */
+	size?: "form" | "detail";
 	children: ReactNode;
 }
 
@@ -30,25 +37,74 @@ const styles = stylex.create({
 		padding: "1rem",
 		backgroundColor: "rgba(0, 0, 0, 0.4)",
 	},
+	/**
+	 * A column so the header stays put and the body scrolls under it. The height
+	 * cap is what keeps a long record inside the viewport instead of running off
+	 * the bottom of a short one.
+	 */
 	panel: {
 		width: "100%",
-		maxWidth: "28rem",
+		maxHeight: "85vh",
+		display: "flex",
+		flexDirection: "column",
 		borderRadius: "0.5rem",
 		borderWidth: 1,
 		borderStyle: "solid",
 		borderColor: colors.border,
 		backgroundColor: colors.surfaceRaised,
 		color: colors.text,
-		padding: "1.5rem",
 		boxShadow: "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)",
 	},
-	/** The panel already draws the boundary; the dialog's own ring would double it. */
+	panelForm: {
+		maxWidth: "28rem",
+	},
+	panelDetail: {
+		maxWidth: "52rem",
+	},
+	/**
+	 * The panel already draws the boundary; the dialog's own ring would double
+	 * it. `minHeight: 0` is what lets the body shrink far enough to scroll.
+	 */
 	body: {
 		outlineStyle: "none",
+		display: "flex",
+		flexDirection: "column",
+		minHeight: 0,
+	},
+	header: {
+		flexShrink: 0,
+		display: "flex",
+		alignItems: "center",
+		justifyContent: "space-between",
+		gap: "1rem",
+		borderBottomWidth: 1,
+		borderBottomStyle: "solid",
+		borderBottomColor: colors.border,
+		paddingInline: "1.5rem",
+		paddingBlock: "0.75rem",
+	},
+	title: {
+		fontSize: "1.125rem",
+		lineHeight: "1.75rem",
+		fontWeight: 600,
+	},
+	/** 44px on both axes: the pointer-target floor, which the word alone misses. */
+	close: {
+		minWidth: 44,
+		minHeight: 44,
+		display: "inline-flex",
+		alignItems: "center",
+		justifyContent: "center",
+	},
+	content: {
+		minHeight: 0,
+		overflowY: "auto",
+		paddingInline: "1.5rem",
+		paddingBlock: "1.5rem",
 	},
 });
 
-export default function Dialog({ label, isOpen, onClose, children }: Props) {
+export default function Dialog({ title, isOpen, onClose, size = "form", children }: Props) {
 	return (
 		<ModalOverlay
 			isOpen={isOpen}
@@ -58,9 +114,26 @@ export default function Dialog({ label, isOpen, onClose, children }: Props) {
 			isDismissable
 			className={() => stylex.props(styles.overlay).className ?? ""}
 		>
-			<Modal className={() => stylex.props(styles.panel).className ?? ""}>
+			<Modal
-				<AriaDialog aria-label={label} {...stylex.props(styles.body)}>
+				className={() =>
-					{children}
+					stylex.props(styles.panel, size === "detail" ? styles.panelDetail : styles.panelForm).className ??
+					""
+				}
+			>
+				<AriaDialog {...stylex.props(styles.body)}>
+					<div {...stylex.props(styles.header)}>
+						<Heading slot="title" level={2} {...stylex.props(styles.title)}>
+							{title}
+						</Heading>
+						<button
+							type="button"
+							onClick={onClose}
+							{...stylex.props(shared.button, styles.close, shared.focusRing)}
+						>
+							Close
+						</button>
+					</div>
+					<div {...stylex.props(styles.content)}>{children}</div>
 				</AriaDialog>
 			</Modal>
 		</ModalOverlay>

admin/src/ui/Switch.test.tsx

@@ -0,0 +1,91 @@
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import Switch from "./Switch";
+
+/**
+ * The drawn track, which is the label's one span that does not hold the hidden
+ * input. StyleX compiles to class names and jsdom loads no stylesheet, so the
+ * class list is the only place the composed state is observable.
+ */
+function track(input: HTMLElement): HTMLElement {
+	const label = input.closest("label") as HTMLElement;
+	const spans = [...label.querySelectorAll("span")];
+	const drawn = spans.find((span) => !span.contains(input));
+	if (drawn === undefined) throw new Error("the switch drew no track");
+	return drawn;
+}
+
+test("a switch reports the switch role, not a checkbox one", () => {
+	const onChange = vi.fn();
+	render(
+		<Switch isSelected onChange={onChange}>
+			Safe search
+		</Switch>,
+	);
+
+	// The role is the whole point: it tells a screen reader the setting moves now
+	// rather than on some later Save.
+	const control = screen.getByRole("switch", { name: "Safe search" }) as HTMLInputElement;
+	expect(control.checked).toBe(true);
+	expect(screen.queryByRole("checkbox")).toBeNull();
+
+	fireEvent.click(control);
+	// The caller owns the state, so the switch reports the value it would move to.
+	expect(onChange).toHaveBeenCalledWith(false);
+});
+
+test("a bare switch takes its name from aria-label", () => {
+	render(<Switch aria-label="udp://1.1.1.1:53 enabled" isSelected={false} onChange={vi.fn()} />);
+
+	const control = screen.getByRole("switch", { name: "udp://1.1.1.1:53 enabled" }) as HTMLInputElement;
+	expect(control.checked).toBe(false);
+});
+
+test("a disabled switch keeps its state on screen but takes no input", () => {
+	render(
+		<Switch isSelected isDisabled onChange={vi.fn()}>
+			Safe search
+		</Switch>,
+	);
+
+	const control = screen.getByRole("switch", { name: "Safe search" }) as HTMLInputElement;
+	expect(control.checked).toBe(true);
+	// The disabled input is the whole guard: a browser fires no click on one, and
+	// it is out of the tab order. Clicking it here would prove nothing either way,
+	// because `fireEvent` dispatches straight at the node and skips that check.
+	expect(control.disabled).toBe(true);
+});
+
+test("the track is drawn from the selected state, not left to the browser", () => {
+	const { rerender } = render(<Switch aria-label="Safe search" isSelected={false} onChange={vi.fn()} />);
+
+	const control = screen.getByRole("switch");
+	const off = track(control).className.split(" ");
+
+	rerender(<Switch aria-label="Safe search" isSelected onChange={vi.fn()} />);
+	const on = track(control).className.split(" ");
+
+	// The two states compose to different class sets, so the thumb and the fill
+	// actually move rather than the input alone changing.
+	expect(on).not.toEqual(off);
+});
+
+test("keyboard focus composes the ring onto the drawn track", () => {
+	render(<Switch aria-label="Safe search" isSelected={false} onChange={vi.fn()} />);
+
+	const control = screen.getByRole("switch");
+	const drawn = track(control);
+	const idle = drawn.className.split(" ");
+	expect(control.closest("label")?.getAttribute("data-focus-visible")).toBeNull();
+
+	// React Aria only calls focus visible after the modality is keyboard, which
+	// is why a bare focus() is not enough to raise the ring.
+	act(() => {
+		fireEvent.keyDown(document.body, { key: "Tab" });
+		control.focus();
+	});
+
+	expect(control.closest("label")?.getAttribute("data-focus-visible")).toBe("true");
+	const ringed = drawn.className.split(" ");
+	expect(ringed.length).toBeGreaterThan(idle.length);
+	expect(idle.every((name) => ringed.includes(name))).toBe(true);
+});

admin/src/ui/Switch.tsx

@@ -0,0 +1,121 @@
+/**
+ * The on/off switch, wrapping React Aria's.
+ *
+ * A switch, not a checkbox: every call site flips a setting that takes effect
+ * the moment it moves, with no Save between. A checkbox states what a form will
+ * submit, which is a promise these controls do not make.
+ *
+ * React Aria hides the real input and leaves the track to the call site, so the
+ * track and thumb below are what the reader sees. The caller always holds the
+ * state — none of these controls owns the value it shows, because the server's
+ * answer is the value.
+ */
+
+import type { ReactNode } from "react";
+import * as stylex from "@stylexjs/stylex";
+import { Switch as AriaSwitch } from "react-aria-components";
+import { colors } from "./tokens.stylex";
+
+interface Common {
+	isSelected: boolean;
+	onChange: (isSelected: boolean) => void;
+	/** Visible but inert; React Aria also drops it from the tab order. */
+	isDisabled?: boolean;
+}
+
+/** With visible words beside the track, which name it. */
+interface Labelled extends Common {
+	children: ReactNode;
+	"aria-label"?: never;
+}
+
+/** Bare, in a table cell whose column heading cannot name a single row. */
+interface Named extends Common {
+	children?: never;
+	"aria-label": string;
+}
+
+/**
+ * A switch has to be named, and exactly one of the two ways: visible words that
+ * `aria-label` would then override and hide from the reader who can see them,
+ * or no words and a label only the screen reader gets.
+ */
+type Props = Labelled | Named;
+
+const styles = stylex.create({
+	/**
+	 * The whole label is the hit area, so it carries the 44px pointer-target
+	 * floor on both axes, the same floor `Checkbox` and the dialog's Close
+	 * button already set. The track itself is far under it.
+	 */
+	label: {
+		minWidth: 44,
+		minHeight: 44,
+		display: "inline-flex",
+		alignItems: "center",
+		gap: "0.5rem",
+		fontSize: "0.875rem",
+		lineHeight: "1.25rem",
+	},
+	/** Bare switches sit in a table cell, where the row sets the rhythm. */
+	track: {
+		flexShrink: 0,
+		boxSizing: "border-box",
+		width: 28,
+		height: 16,
+		display: "inline-flex",
+		alignItems: "center",
+		justifyContent: "flex-start",
+		borderRadius: 8,
+		padding: 2,
+		backgroundColor: colors.borderStrong,
+	},
+	/**
+	 * The thumb moves by the box's own alignment rather than by a transform, so
+	 * there is no transition to withhold from a reader who asked for less motion.
+	 */
+	trackSelected: {
+		justifyContent: "flex-end",
+		backgroundColor: colors.primary,
+	},
+	/** As on `Checkbox`: the ring follows the state React Aria reports, because
+	 *  `:focus-visible` lands on the hidden input rather than on this track. */
+	trackFocused: {
+		outlineWidth: 2,
+		outlineStyle: "solid",
+		outlineColor: colors.focus,
+		outlineOffset: 2,
+	},
+	/** The track dims, not the words: the label still has to be readable. */
+	trackDisabled: {
+		opacity: 0.5,
+	},
+	thumb: {
+		width: 12,
+		height: 12,
+		borderRadius: 6,
+		backgroundColor: colors.surfaceRaised,
+	},
+});
+
+export default function Switch({ children, ...state }: Props) {
+	return (
+		<AriaSwitch {...state} className={() => stylex.props(styles.label).className ?? ""}>
+			{(renderProps) => (
+				<>
+					<span
+						{...stylex.props(
+							styles.track,
+							renderProps.isSelected && styles.trackSelected,
+							renderProps.isFocusVisible && styles.trackFocused,
+							renderProps.isDisabled && styles.trackDisabled,
+						)}
+					>
+						<span {...stylex.props(styles.thumb)} />
+					</span>
+					{children}
+				</>
+			)}
+		</AriaSwitch>
+	);
+}

admin/src/ui/styles.ts

@@ -60,6 +60,7 @@ export const styles = stylex.create({
 	},
 
 	button: {
+		cursor: { default: "pointer", [DISABLED]: "not-allowed" },
 		borderRadius: "0.25rem",
 		borderWidth: 1,
 		borderStyle: "solid",
@@ -70,6 +71,7 @@ export const styles = stylex.create({
 		lineHeight: "1.25rem",
 	},
 	smallButton: {
+		cursor: { default: "pointer", [DISABLED]: "not-allowed" },
 		borderRadius: "0.25rem",
 		borderWidth: 1,
 		borderStyle: "solid",
@@ -80,6 +82,7 @@ export const styles = stylex.create({
 		lineHeight: "1.25rem",
 	},
 	largeButton: {
+		cursor: { default: "pointer", [DISABLED]: "not-allowed" },
 		borderRadius: "0.25rem",
 		borderWidth: 1,
 		borderStyle: "solid",
@@ -90,6 +93,7 @@ export const styles = stylex.create({
 	},
 
 	primaryButton: {
+		cursor: { default: "pointer", [DISABLED]: "not-allowed" },
 		borderRadius: "0.25rem",
 		borderStyle: "none",
 		backgroundColor: colors.primary,
@@ -102,6 +106,7 @@ export const styles = stylex.create({
 		opacity: { default: 1, [DISABLED]: 0.5 },
 	},
 	largePrimaryButton: {
+		cursor: { default: "pointer", [DISABLED]: "not-allowed" },
 		borderRadius: "0.25rem",
 		borderStyle: "none",
 		backgroundColor: colors.primary,
@@ -113,6 +118,7 @@ export const styles = stylex.create({
 	},
 
 	rowButton: {
+		cursor: { default: "pointer", [DISABLED]: "not-allowed" },
 		borderRadius: "0.25rem",
 		borderStyle: "none",
 		backgroundColor: "transparent",
@@ -123,6 +129,7 @@ export const styles = stylex.create({
 		color: colors.primaryOnSurface,
 	},
 	linkButton: {
+		cursor: { default: "pointer", [DISABLED]: "not-allowed" },
 		borderStyle: "none",
 		backgroundColor: "transparent",
 		padding: 0,
@@ -132,6 +139,7 @@ export const styles = stylex.create({
 		color: colors.primaryOnSurface,
 	},
 	dangerLinkButton: {
+		cursor: { default: "pointer", [DISABLED]: "not-allowed" },
 		borderStyle: "none",
 		backgroundColor: "transparent",
 		padding: 0,
@@ -142,6 +150,7 @@ export const styles = stylex.create({
 		opacity: { default: 1, [DISABLED]: 0.5 },
 	},
 	retryButton: {
+		cursor: { default: "pointer", [DISABLED]: "not-allowed" },
 		marginTop: "0.75rem",
 		borderRadius: "0.25rem",
 		borderWidth: 1,

build.zig.zon

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

docs/README.md

@@ -37,6 +37,7 @@ Descriptions of what is there. No procedures, no advice.
 - [reference/api.md](reference/api.md) — every REST route, authentication and the event stream.
 - [reference/cli.md](reference/cli.md) — the six subcommands, every flag, every exit code.
 - [reference/files-and-directories.md](reference/files-and-directories.md) — the data directory layout and file modes.
+- [reference/query-log-lifecycle.md](reference/query-log-lifecycle.md) — how `querylog.db` is versioned, migrated, backed up and, rarely, recreated.
 - [reference/performance.md](reference/performance.md) — the targets and the measured numbers.
 
 ## Explanation

docs/explanation/architecture.md

@@ -27,7 +27,7 @@ Directories:
 | `src/cache/` | `dns_cache.zig`: bounded in-memory TTL cache of whole response messages, keyed by the question. The clock arrives as a parameter. |
 | `src/upstream/` | Upstream resolution: shared vocabulary and the `Client` interface (`transport.zig`), DoH client (RFC 8484), DoT client (RFC 7858), per-endpoint health and backoff (`health.zig`), and `pool.zig` — priority-ordered failover that is itself a `transport.Client`, so the handler sees one interface. |
 | `src/server/` | The serving side: UDP/TCP/DoH/DoT listeners, `handler.zig` (the whole query pipeline), `cert_store.zig` (refcounted TLS cert holder), `rate_limiter.zig`, `pause.zig`, `clients.zig` (client auto-materialisation), `local_tables.zig` (published local-answer tables), `query_sink.zig` (log and SSE fanout), `shutdown.zig` (SIGINT/SIGTERM into one `std.Io.Event`). |
-| `src/storage/` | SQLite ownership: `db.zig` is the only file that calls SQLite, `config_schema.zig` + `migrations.zig` for `config.db`, `querylog_schema.zig` (open-or-recreate), async query `logger.zig`, `retention.zig`, `disk_monitor.zig`, and one repository per table under `repositories/`. |
+| `src/storage/` | SQLite ownership: `db.zig` is the only file that calls SQLite, `config_schema.zig` + `migrations.zig` for `config.db`, `querylog_schema.zig` + `querylog_versions.zig` + `querylog_migrations.zig` for `querylog.db`, async query `logger.zig`, `retention.zig`, `disk_monitor.zig`, and one repository per table under `repositories/`. |
 | `src/config/` | The one configuration model (`model.zig`), the pure validator (`validate.zig`), `import.zig`/`export.zig` (ZON to and from `config.db`, byte-stable round trip), `loader.zig` (read/parse/validate a named file, with the shared fault mapping), `reconcile.zig` (converge the database onto a parsed config by row identity). |
 | `src/web/` | The admin HTTP layer: `server.zig` (listener), `router.zig`/`routes.zig`, one file per resource under `handlers/`, `auth.zig` (sessions), `sse.zig` (live query fanout), `static.zig` (embedded SPA), `metrics.zig` (Prometheus), `openapi.zig` (served contract), `api_limiter.zig`, `http_util.zig`. |
 | `src/platform/` | OS and TLS edges: IP address values, the `std.log` sink (`logging.zig`), `statfs.zig` (free-space query via libc), client TLS over `std.crypto.tls` (`tls_client.zig`), server TLS over vendored Mbed TLS (`tls_server.zig`). |
@@ -115,7 +115,7 @@ Two databases with opposite contracts, in one data directory (see [reference/fil
 
 Which of the file and the database is *authoritative* is chosen by the invocation, not by state: bare `nxdns run` serves the database, and `nxdns run --config FILE` makes the file authoritative and reconciles the database onto it at every start. `reconcile.zig` is that convergence, matching rows by identity and writing only differences, so runtime state — blocklist checksums, compiled snapshots, client history — survives. Why it works that way is [configuration-model.md](configuration-model.md).
 
-**`querylog.db` is expendable.** It is never migrated. Its schema carries a fingerprint derived from the DDL text, and at open, a missing, corrupt, non-database, `quick_check`-failing or fingerprint-mismatched file is moved aside and recreated empty — the old file is kept under a new name rather than deleted, so an operator can still look at it. Retention deletes old rows daily and periodically rewrites the file to reclaim space.
+**`querylog.db` is the expendable one, but its history is not thrown away.** It carries a logical version in `PRAGMA user_version`, and an older supported version is migrated in place at open: one transaction, behind one `querylog.db.pre-migrate-<epoch>` backup, of which only the newest is kept. Only real damage recreates the file — missing, corrupt, not a database, or failing `quick_check` — and then the old file is kept under a new name rather than deleted, so an operator can still look at it. A healthy file this build cannot read is neither migrated nor moved aside: the startup refuses and says why, because losing months of history to a rollback is worse than a server that will not start. Retention deletes old rows daily and periodically rewrites the file to reclaim space. The whole contract is [reference/query-log-lifecycle.md](../reference/query-log-lifecycle.md).
 
 The split exists so that the churn of the second database can never endanger the first. Query logs are high-volume, disposable, and the thing most likely to be corrupted by a power cut on an SD card; configuration is small, irreplaceable, and the thing an operator would have to reconstruct by hand. Giving them one file would force the careful contract onto the noisy data or the loose contract onto the valuable data.
 

docs/how-to/set-up-admin-authentication.md

@@ -62,7 +62,7 @@ Which of steps 4 and 5 applies to your server depends on its authority. Under `n
 Login is `POST /api/auth/login` with a JSON body. Without a session, the API answers 401:
 
 ```sh
-curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8451/api/stats
+curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8451/api/overview
 ```
 
 ```
@@ -92,7 +92,7 @@ The cookie is named `nxdns_session` and carries `HttpOnly; SameSite=Lax; Path=/`
 
 ```sh
 curl -sS -b /tmp/nxdns-lab/cookies.txt -o /dev/null -w '%{http_code}\n' \
-  http://127.0.0.1:8451/api/stats
+  http://127.0.0.1:8451/api/overview
 ```
 
 ```
@@ -125,13 +125,13 @@ Sessions live in memory only. A restart logs everyone out. Thirty-two concurrent
 ```sh
 curl -sS -b /tmp/nxdns-lab/cookies.txt -c /tmp/nxdns-lab/cookies.txt \
   -X POST http://127.0.0.1:8451/api/auth/logout
-curl -sS -b /tmp/nxdns-lab/cookies.txt -o /dev/null -w 'stats: %{http_code}\n' \
+curl -sS -b /tmp/nxdns-lab/cookies.txt -o /dev/null -w 'overview: %{http_code}\n' \
-  http://127.0.0.1:8451/api/stats
+  http://127.0.0.1:8451/api/overview
 ```
 
 ```
 {"authenticated":false}
-stats: 401
+overview: 401
 ```
 
 Logging out with a stale cookie, or with none, answers the same way. The point of logging out is to end up logged out, and that is where such a request already is.
@@ -154,7 +154,7 @@ Changing the password ends every session, including the one that made the change
 
 ```sh
 curl -sS -b /tmp/nxdns-lab/c2.txt -o /dev/null -w 'old session: %{http_code}\n' \
-  http://127.0.0.1:8451/api/stats
+  http://127.0.0.1:8451/api/overview
 curl -sS -X POST http://127.0.0.1:8451/api/auth/login \
   -H 'content-type: application/json' -d '{"password":"lab-password"}' \
   -w ' (old password)\n'
@@ -217,14 +217,14 @@ curl -sS -X POST http://127.0.0.1:8451/api/auth/login \
 curl -sS -c /tmp/nxdns-lab/c5.txt -X POST http://127.0.0.1:8451/api/auth/login \
   -H 'content-type: application/json' -d '{"password":"offline-password"}' \
   -w ' (new password, http %{http_code})\n'
-curl -sS -b /tmp/nxdns-lab/c5.txt -o /dev/null -w 'stats: %{http_code}\n' \
+curl -sS -b /tmp/nxdns-lab/c5.txt -o /dev/null -w 'overview: %{http_code}\n' \
-  http://127.0.0.1:8451/api/stats
+  http://127.0.0.1:8451/api/overview
 ```
 
 ```
 {"error":"invalid password"} (old password, http 401)
 {"authenticated":true,"auth_required":true} (new password, http 200)
-stats: 200
+overview: 200
 ```
 
 The next export shows the new hash and a null `password` again:
@@ -245,7 +245,7 @@ See [back up and restore](back-up-and-restore.md) for when `import` does need `-
 Authentication is off. Every route is open, and a login attempt succeeds without minting anything — there is nothing to log in to, and a session that authorises nothing would be a lie for the browser to store:
 
 ```sh
-curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8453/api/stats
+curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8453/api/overview
 curl -sS -X POST http://127.0.0.1:8453/api/auth/login \
   -H 'content-type: application/json' -d '{"password":"anything"}'
 ```

docs/how-to/troubleshoot.md

@@ -267,11 +267,11 @@ cat /etc/resolv.conf
 curl -s http://127.0.0.1:8080/metrics | grep nxdns_upstream_
 ```
 
-`nxdns_upstream_in_flight` against `nxdns_upstream_slots` is how much of an upstream's concurrency is in use right now, and `nxdns_upstream_queued_total` counts exchanges that had to wait for a slot (with `nxdns_upstream_queued_seconds_total` for how long they waited in total). Both queue counters are approximate — they are sampled when a query is admitted, not measured as a queue length. A `queued_total` climbing with each burst means queries are waiting on the upstream rather than failing at it, and a query that waits past `upstream.total_timeout_ms` is canceled in the queue and answered SERVFAIL.
+`nxdns_upstream_in_flight` against `nxdns_upstream_slots` is how much of an upstream's concurrency is in use right now, and `nxdns_upstream_queued_total` counts exchanges that had to wait for a slot (with `nxdns_upstream_queued_seconds_total` for how long they waited in total). Both queue counters are approximate — they are sampled when a query is admitted, not measured as a queue length. A `queued_total` climbing with each burst means queries are waiting on the upstream rather than failing at it, and a query that waits past `upstream.total_timeout_ms` is given up on in the queue and answered SERVFAIL. `nxdns_upstream_budget_exhausted_total` counts those give-ups pool-wide — queries whose own budget ran out, in the queue or mid-attempt, before any upstream answered. It carries no `url` label on purpose: running out of budget is a fact about the pool, so the exhausted attempt is never charged to an upstream's health and is never attributed in the query log, although the row can still name the last endpoint whose success or recorded failure preceded it.
 
 `nxdns_upstream_reuse_recoveries_total` is the other half of the picture: it counts DoT connections that went stale between exchanges and were redialed. A few are normal — a resolver is free to close an idle connection. One per query means the connection is never being reused, and every query is paying a full TLS handshake.
 
-**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 is not: failover is strict priority, not load spreading — a query waits for a slot on the first available upstream and only reaches the next one when that upstream fails or is in backoff, so a second entry adds no concurrent capacity to the first. The per-upstream slot count is compiled, not configured, so there is no knob to widen one upstream either.
+**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.
 
 ## The disk is filling up
 
@@ -339,3 +339,37 @@ nxdns run failed: SchemaTooNew
 ```
 
 **Fix.** There is no downgrade. Import the export you took before upgrading into a fresh data directory with the older binary; see [Upgrade nxdns](upgrade.md).
+
+## The server refuses to start over querylog.db
+
+**Symptom.** The process stops at startup naming the query log, and the error is one of four names:
+
+```
+error(querylog_schema): refusing to open querylog database '/var/lib/nxdns/querylog.db': it is stamped 7, and this build supports schema versions 1 to 1 (SchemaTooNew). The file is left exactly as it is; see docs/how-to/troubleshoot.md, "The server refuses to start over querylog.db"
+nxdns run failed: SchemaTooNew
+```
+
+This is a refusal, not damage. nxdns will not replace a healthy query log to get itself started, so the file is left exactly as it was — schema, rows, coverage watermark and version stamp all unchanged — and the startup fails instead. All four exit 2, the code that means an operator has to act, because none of them resolves on a retry — the shipped systemd unit's `RestartPreventExitStatus=2 64` stops the unit on the first refusal instead of restart-looping it. `systemctl status nxdns` shows the refusal. `nxdns check` does not grade the query log at all, so it will not reproduce any of these.
+
+[The query-log lifecycle](../reference/query-log-lifecycle.md) is the full contract behind this page.
+
+**Fixes by name.**
+
+- `SchemaTooNew` — the file was stamped by a newer nxdns than the one you are running, which normally means a binary was rolled back. Put the newer release back and start it: the file is exactly as that release left it. If you mean to stay on the older release, that release cannot read this file, so restore the `querylog.db.pre-migrate-<unix-seconds>` copy the upgrade left beside it — stop the server, move `querylog.db` and its `querylog.db-wal` and `querylog.db-shm` out of the way, rename the backup to `querylog.db`, and start. Starting empty is also an option: with the server stopped, move `querylog.db` and both sidecars aside and the next start creates a fresh log.
+- `SchemaUnsupported` — the stamp is not a version this build can reach. Either the file predates 0.0.12, or it came from somewhere else, or a release since deliberately broke the schema; the changelog section for the release you are running says so when it is the third case. There is no migration path, by contract. Keep the file if the history matters — copy it somewhere and read it with the `sqlite3` shell — and if starting with an empty log is acceptable, stop the server, move `querylog.db`, `querylog.db-wal` and `querylog.db-shm` out of the data directory by hand, and start again.
+- `MigrationBackupFailed` — a migration was due and the pre-migration backup could not be written, so nothing was migrated. The line above names the destination and the reason, which is almost always a full or read-only data directory. Free space or fix the permissions and start again.
+- `MigrationFailed` — read the log line above it, because two different states wear this one name.
+
+**Which `MigrationFailed` you have.** The distinction is in the line the migration logged, and it decides whether you do anything at all:
+
+- Before the commit: `querylog migration 1 -> 2 failed before commit (...); the database is unchanged`. Nothing was applied. The file still carries its old version and every row, and this run's backup was deleted because the original is intact. Restarting will attempt the same migration and fail the same way, so this needs the underlying cause — the log line names it — or a report.
+- After the commit: `querylog migration 1 -> 2 COMMITTED and the database IS at version 2, but the connection could not be restored: ...; the backup '...' is kept and the next start will open the migrated file normally`. The migration DID complete. Only that one startup is refused, the pre-migration backup is kept, and the next start opens the migrated file on the ordinary current-version path. Start the server again.
+
+In neither case does the server start with an empty log on its own. Recreating a query log automatically is reserved for real corruption; see [why a query log is moved aside](../reference/files-and-directories.md#why-a-query-log-is-moved-aside).
+
+> Not reproduced against a running service: the four refusals are covered by the
+> test suite rather than by a hand-driven install, and the released chain has no
+> migration step in it yet, so no upgrade produces a `pre-migrate` backup today.
+> The messages above are the ones `src/storage/querylog_schema.zig` and
+> `src/storage/querylog_migrations.zig` emit, with a data directory path and
+> example version numbers filled in.

docs/how-to/upgrade.md

@@ -263,7 +263,7 @@ nxdns run failed: SchemaTooNew
 > hand and `nxdns run` was pointed at it. The two lines above are that run's
 > output.
 
-That run exits 1. Recovering means importing the export you took in step 1 into a fresh data directory with the older binary.
+That run exits 2, and the shipped unit stops rather than restart-loops it. Recovering means importing the export you took in step 1 into a fresh data directory with the older binary.
 
 ### Rolling back from file mode
 

docs/reference/api.md

@@ -109,11 +109,7 @@ Auth `open` means no session is required; `session` means a valid session cookie
 | GET | `/api/queries` | session | counted | read | Query log rows for the Activity page |
 | GET | `/api/queries/{id}` | session | counted | read | One query, fully explained |
 | GET | `/api/queries/live` | session | exempt | read | Live query stream (server-sent events) |
-| GET | `/api/stats` | session | counted | read | Totals for a period |
+| GET | `/api/overview` | session | counted | read | Everything the Overview page draws, for one period |
-| GET | `/api/stats/timeseries` | session | counted | read | Bucketed counts for a period |
-| GET | `/api/stats/types` | session | counted | read | Query-type breakdown for a period |
-| GET | `/api/stats/routes` | session | counted | read | How the period's queries were answered |
-| GET | `/api/stats/clients` | session | counted | read | Per-client bucketed counts for a period |
 | GET | `/api/lookup` | session | counted | read | Explain a domain |
 | GET | `/api/diagnostics` | session | counted | read | Operational event log |
 | DELETE | `/api/diagnostics` | session | counted | runtime action | Purge every resolved event |
@@ -221,6 +217,6 @@ A non-empty `rewrites.cname_target` on a query detail means the decision landed
 
 ### Coverage
 
-Every window-bounded read — `GET /api/queries` and the five `GET /api/stats*` endpoints — answers with a `coverage` object: `available_since` is the oldest instant the query log is still complete for, and `complete` is true only when the window the request asked about starts at or after it. Retention deletes rows and advances the watermark in one transaction, so a client can tell an empty window from a pruned one instead of charting the gap as zero. A request with no lower bound at all asks about the whole of history, and is never complete.
+Every window-bounded read — `GET /api/queries` and `GET /api/overview` — answers with a `coverage` object: `available_since` is the oldest instant the query log is still complete for, and `complete` is true only when the window the request asked about starts at or after it. Retention deletes rows and advances the watermark in one transaction, so a client can tell an empty window from a pruned one instead of charting the gap as zero. A request with no lower bound at all asks about the whole of history, and is never complete.
 
-Each of these responses reads its rows and its watermark inside one SQLite read transaction, so retention cannot prune between the two and hand back pre-prune rows tagged with a post-prune `available_since`. Coherence stops there: two separate requests are two separate reads, and queries logged between them can move the counts.
+Each of these responses reads its rows and its watermark inside one SQLite read transaction, so retention cannot prune between the two and hand back pre-prune rows tagged with a post-prune `available_since`. `GET /api/overview` puts every Overview panel inside that one transaction, so its totals and its four breakdowns describe one database state. Coherence stops there: two separate requests are two separate reads, and queries logged between them can move the counts.

docs/reference/cli.md

@@ -214,7 +214,7 @@ Prints the usage text to stdout and exits 0. `nxdns --help` and `nxdns -h` do th
 | --- | --- |
 | 0 | Success. |
 | 1 | Runtime failure — I/O, database, out of memory. A partial diagnostic report caused by an allocation failure is a runtime failure, not a verdict on the configuration. |
-| 2 | A configuration problem the operator can fix, or a `check` that found one. |
+| 2 | A configuration problem the operator can fix, a `check` that found one, or a deliberate refusal to run that no retry will clear. |
 | 64 | Usage error — unknown command or flag, a flag without its value, a missing or extra argument. |
 
 Code 2 means the same thing from every subcommand. `src/config/faults.zig` holds the one list of errors that mean "the configuration the operator supplied is wrong", and `run`, `check` and `import` all ask it, so a rejected file exits 2 whichever command read it. The list is every error the validator raises, plus `ParseZon`, `ConfigTooLarge`, `NoUsableUpstreams`, `BadCertificate` and `ManagedConfigUnreadable`. In practice that covers a file with a syntax error, one larger than 4 MiB, one with no `default` group (`MissingDefaultGroup`), one with no enabled upstream (`NoUpstreams`), a bad bind address, a bad rate limit, an unusable certificate, `password` and `password_hash` set together, and a `--config` path that is absent or unreadable.
@@ -237,6 +237,8 @@ load one with `nxdns import <file>`, or make a file the source of truth with `nx
 
 `import` exits 2 for those faults and for `DestructiveImport`. That last one is deliberately not a configuration fault — it reports what applying the file would delete, rather than anything wrong with its content — and `import` decides it for itself; the answer to it is `--allow-delete`, not an edit.
 
+`run` also exits 2 on the four query-log schema refusals — `SchemaTooNew`, `SchemaUnsupported`, `MigrationFailed` and `MigrationBackupFailed` — which are in the same list. They are not a verdict on a file the operator wrote, but they share the property exit 2 exists to signal: the server is refusing on purpose, an operator has to act, and a restart will only repeat the refusal. Exit 1 would put them under the unit's `Restart=on-failure` and loop them. See [the server refuses to start over querylog.db](../how-to/troubleshoot.md#the-server-refuses-to-start-over-querylogdb).
+
 `OutOfMemory` is exit 1 even when problems were recorded, because the report is then incomplete. Every other error is 1.
 
 Where an exit code sends you next: [troubleshoot](../how-to/troubleshoot.md).

docs/reference/configuration.md

@@ -37,12 +37,14 @@ Timeouts for talking to upstream resolvers.
 | Key | Type | Default | Unit | Validation | Consumed by |
 |---|---|---|---|---|---|
 | `upstream.attempt_timeout_ms` | u32 | 2500 | ms | 100–120000, and not above `total_timeout_ms` | deadline on one attempt against one upstream inside the pool's failover loop (`src/upstream/pool.zig`), the whole attempt including the connect |
-| `upstream.read_timeout_ms` | u32 | 3000 | ms | 100–120000 | read deadline on conditional-forward-zone exchanges (`src/local/forward_client.zig`) |
+| `upstream.read_timeout_ms` | u32 | 3000 | ms | 100–120000 | budget for a whole conditional-forward-zone exchange (`src/local/forward_client.zig`): the UDP attempt, a TC=1 fallback and the TCP retry together |
 | `upstream.total_timeout_ms` | u32 | 5000 | ms | 100–120000 | per-query budget of the upstream pool (`src/upstream/pool.zig`): every failover attempt together, not one of them; also the `nxdns check` probe deadline |
 
 The two pool budgets nest. `attempt_timeout_ms` bounds one try against one upstream; when it expires the pool records the failure and moves to the next candidate. `total_timeout_ms` bounds the whole loop, so a query against five unreachable upstreams costs the total budget once, not five attempt budgets in a row. When the total expires the in-flight attempt is canceled and the query fails with a timeout.
 
-`read_timeout_ms` is unrelated to both. It bounds a different subsystem — the conditional-forward-zone client — so no cross-check relates it to the pool's budgets, and it is free to sit above either of them.
+Budget semantics. The deadline is an instant, computed once when the query enters the pool, and every blocking step spends against it — waiting for a free slot on an upstream as much as the exchange itself. An attempt therefore runs against `min(now + attempt_timeout_ms, deadline)`, which near the end of the budget is *truncated*: shorter than the configured attempt. Attribution follows from that. A truncated attempt that expires is evidence about the budget, not about the upstream, so it leaves that upstream's health and success rate untouched and the query log's `upstream` field unchanged — the row may still name the endpoint of the preceding attributable attempt, and is null only when there was none — and it increments the pool-wide `nxdns_upstream_budget_exhausted_total` metric. An attempt that expires on its full budget, or that fails outright (a refused connection, a bad answer, the peer's own timeout), is evidence about the upstream: it is recorded against that upstream's health and names it in the query log. Either way the client is answered SERVFAIL. Forward-zone queries are not affected — they have one configured resolver, so a timeout there always names it.
+
+`read_timeout_ms` is unrelated to both pool budgets. It bounds a different subsystem — the conditional-forward-zone client — so no cross-check relates it to the pool's budgets, and it is free to sit above either of them. Within that subsystem it is one budget for the whole exchange: a query that goes out over UDP, comes back truncated and is retried over TCP has the two legs and the fallback share `read_timeout_ms`, never one each.
 
 ### dns
 
@@ -318,7 +320,7 @@ Zones resolved by a specific resolver instead of the configured upstreams, for L
 | `zone` | string | required | a valid domain name; unique |
 | `resolver` | string | required | `udp://IP:port` or `tcp://IP:port`; the host must be an IP literal and the port is mandatory |
 
-The resolver host must be an IP literal because resolving the resolver's own name would be a bootstrap problem. Matching is longest suffix (`src/local/forward_zones.zig`); the exchange is UDP then TCP (`src/local/forward_client.zig`) with `upstream.read_timeout_ms` as the read deadline.
+The resolver host must be an IP literal because resolving the resolver's own name would be a bootstrap problem. Matching is longest suffix (`src/local/forward_zones.zig`); the exchange is UDP then TCP (`src/local/forward_client.zig`), with `upstream.read_timeout_ms` bounding the whole exchange rather than each leg.
 
 Reverse zones are declared the same way, and one is the prerequisite for [learned client names](#learned-names):
 

docs/reference/files-and-directories.md

@@ -16,10 +16,12 @@ Default `/var/lib/nxdns`, overridable with `--data-dir DIR`. `nxdns run` and `nx
 | --- | --- | --- |
 | `config.db` | The configuration database, including `web.password_hash`. The source of truth in database mode; in file mode it is the runtime substrate the file is reconciled onto (see [the configuration file](#the-configuration-file)). | 0600 |
 | `config.db-wal`, `config.db-shm` | SQLite write-ahead log and shared-memory index for `config.db`. Created by `run`, `import` and `export` when WAL is enabled, inheriting the main file's permissions. `check` creates neither. | 0600 |
-| `querylog.db` | The query log: every domain every client asked for. Expendable — if it is missing or unusable it is recreated empty. | 0600 |
+| `querylog.db` | The query log: every domain every client asked for. Missing or damaged, it is recreated empty; an older schema is migrated in place, and a schema this build cannot use refuses the startup. See [the query-log lifecycle](query-log-lifecycle.md). | 0600 |
 | `querylog.db-wal`, `querylog.db-shm` | WAL sidecars for `querylog.db`. | 0600 |
-| `querylog.db.<reason>-<unix-seconds>` | A `querylog.db` this build could not use, moved aside before an empty one was created in its place. Kept, never overwritten. `<reason>` is one of `corrupt`, `not-a-database`, `quick-check-failed` or `schema-changed`; see [why a query log is moved aside](#why-a-query-log-is-moved-aside). | Whatever the renamed file had — no chmod reaches it |
+| `querylog.db.<reason>-<unix-seconds>` | A damaged `querylog.db`, moved aside before an empty one was created in its place. Kept, never overwritten. `<reason>` is one of `corrupt`, `not-a-database` or `quick-check-failed`; see [why a query log is moved aside](#why-a-query-log-is-moved-aside). | Whatever the renamed file had — no chmod reaches it |
 | `querylog.db.<reason>-<unix-seconds>-<n>` | The same, when the plain name is taken — `<n>` counts from 1 and rises until the name is free. Two recreates within one second is the case it exists for. | The same |
+| `querylog.db.pre-migrate-<unix-seconds>` | A complete copy of `querylog.db` taken immediately before a schema migration. Exactly one survives: a successful migration deletes every other one, and a later successful start retries that cleanup. Written by `VACUUM INTO`, so it holds the committed database including anything still only in the write-ahead log, and it needs no sidecars of its own. | 0600 |
+| `querylog.db.pre-migrate-<unix-seconds>-<n>` | The same, when the plain name is taken — `<n>` counts from 2. | The same |
 | `blocklists/` | Compiled blocklist snapshots, one subdirectory of the data directory. | 0700 |
 | `blocklists/<id>.list` | Exact domains for blocklist source `<id>`, one per line, behind a header. | 0600 |
 | `blocklists/<id>.wild` | Wildcard entries for the same source. | 0600 |
@@ -52,14 +54,15 @@ The temporaries of a source that still exists are cleaned by the refresh that ow
 
 ### Why a query log is moved aside
 
-A `querylog.db` is moved aside when it is missing nothing but usability, and the name it is given says which of the four cases it hit:
+A `querylog.db` is moved aside only when it is genuinely damaged, and the name it is given says which of the three cases it hit:
 
 | `<reason>` | What happened |
 | --- | --- |
 | `corrupt` | SQLite reported the file as damaged. |
 | `not-a-database` | The file is not a SQLite database at all. |
 | `quick-check-failed` | `PRAGMA quick_check` did not answer `ok`. |
-| `schema-changed` | Nothing is wrong with the file. Its `user_version` fingerprint does not match this build's schema, so this build cannot read it. Upgrades that touch the query-log schema produce this one, and the file they set aside is a healthy database. |
+
+There is no fourth case. A healthy file carrying a schema version this build cannot use is neither migrated nor renamed: the startup refuses and the file stays where it is, which is [the query-log lifecycle](query-log-lifecycle.md). You can still find a `querylog.db.schema-changed-<unix-seconds>` in a data directory, because 0.0.13 and older produced one on any schema change — and still do, if you downgrade to one of them. This build never writes that name.
 
 Only the main file is renamed — its `-wal` and `-shm` are deleted, because a stale WAL would be replayed into the fresh database. A missing `querylog.db` is created without any aside file. The rename happens inside `querylog_schema.open`, before the 0600 chmod, and that chmod names `querylog.db` and its two sidecars only — so an aside file keeps the mode the file had at rename time, which for a `querylog.db` nxdns itself created is 0600 and for one an operator put there is whatever they left it at. Nothing prunes the aside files; they accumulate until an operator removes them, and each one holds the same browsing history the live query log holds.
 
@@ -67,6 +70,10 @@ Only the main file is renamed — its `-wal` and `-shm` are deleted, because a s
 
 The 0600 modes are not cosmetic. `config.db` holds the argon2id password hash and `querylog.db` holds the browsing history of every client on the LAN, so both are as sensitive as each other, and a WAL file holds the same rows as the database it belongs to. SQLite creates the main database at `0644 & ~umask`; nxdns chmods it to 0600 before enabling WAL, so the sidecars inherit 0600 rather than being created world-readable.
 
+A `pre-migrate` backup holds that same browsing history, so it is chmodded 0600 the way the live file is: SQLite's `VACUUM INTO` creates it at `0644 & ~umask` and nxdns restricts it immediately afterwards. A backup it cannot restrict is a failed backup — the partial file is deleted and the startup refuses with `MigrationBackupFailed`, rather than leaving a world-readable copy behind.
+
+The aside files are the exception: they get no chmod at all, and an aside keeps whatever mode it had at rename time. For a `querylog.db` nxdns itself created that is 0600; for one an operator put there it is whatever they left it at.
+
 ## The configuration file
 
 There is no default path. `--config FILE` names the file, and without that flag no file is read at all — a `config.zon` sitting in `/etc/nxdns` that no invocation names is inert. `/etc/nxdns/config.zon` is a convention the packaging follows, not a location nxdns probes.

docs/reference/query-log-lifecycle.md

@@ -0,0 +1,70 @@
+# The query log's lifecycle
+
+What happens to `querylog.db` when nxdns opens it: how the file is versioned, when it is migrated, when the server refuses to start over it, and the one case in which it is still replaced. Source of truth: `src/storage/querylog_versions.zig` (the version metadata), `src/storage/querylog_schema.zig` (the open path) and `src/storage/querylog_migrations.zig` (the migration runner).
+
+The rule this page exists to state: **a healthy `querylog.db` is never replaced and never moved aside.** A schema this build cannot use refuses the startup instead. Your query history is not the server's to discard.
+
+## The version stamp
+
+Every `querylog.db` carries a logical schema version in SQLite's `PRAGMA user_version`. It is a small counter — 1 in this release — and not a hash of anything. A file created by this build is stamped as it is created.
+
+Two other values matter, both in `querylog_versions.zig`:
+
+| Constant | Today | What it means |
+| --- | --- | --- |
+| `current_version` | 1 | The version this build creates and reads. |
+| `minimum_supported_version` | 1 | The oldest stamped version this build can migrate up to `current_version`. |
+| `legacy_fingerprint` | 1975011655 | The `user_version` the 0.0.12 and 0.0.13 binaries wrote: a CRC32 of their schema text, under the older policy where a mismatch meant "replace the file". |
+
+`legacy_fingerprint` is frozen forever. Those two releases stamped a hash rather than a version, so this build recognises that one literal number as "version 1" and restamps the file as 1 on the first open. The restamp runs in its own transaction; if it fails, the old stamp and every row stay exactly as they were and the startup refuses.
+
+## What an open does
+
+nxdns opens `querylog.db` once at startup, before it serves anything, and no second process shares a data directory. On a file that is readable and passes `PRAGMA quick_check`, the stamp decides:
+
+| Stamp | What happens |
+| --- | --- |
+| `current_version` | Opens. Nothing is migrated. |
+| `legacy_fingerprint` | Read as version 1: restamped to 1, then treated as version 1 by the rows above and below. |
+| Between `minimum_supported_version` and `current_version` | Migrated in place, then opens. |
+| Above `current_version`, up to 1000000 | REFUSE: `SchemaTooNew`. |
+| Anything else — 0, a negative, another fingerprint, a version below the minimum | REFUSE: `SchemaUnsupported`. |
+
+A refusal changes nothing. The schema, the rows, the coverage watermark and the stamp are all left as they are, no file is set aside, no new file is created, and `nxdns run` exits. The log line names the path, the stamp it found, the range this build supports and [the troubleshooting section](../how-to/troubleshoot.md#the-server-refuses-to-start-over-querylogdb).
+
+## Migrating in place
+
+A migration is one backup and one transaction.
+
+1. **Back up.** `VACUUM INTO` writes a complete copy — including anything still only in the write-ahead log — to `querylog.db.pre-migrate-<unix-seconds>` beside the database. If that name is taken, `-2`, `-3` and so on are tried. A backup that cannot be written is `MigrationBackupFailed`, and the partial copy is deleted; an older backup beside it survives.
+2. **Migrate.** `BEGIN IMMEDIATE`, re-read the stamp under the lock, run every step, run `PRAGMA foreign_key_check`, stamp the new version, `COMMIT`. One transaction covers the whole chain, so the file is either at the old version or at the new one and never in between.
+3. **Clean up.** Every other `querylog.db.pre-migrate-*` beside the file is deleted. **One backup is kept**: the one this migration just took. A later successful start retries that cleanup if it failed.
+
+If a step fails before the commit, the transaction rolls back, this run's backup is deleted, and the startup refuses with `MigrationFailed`. The database keeps the version and the rows it had.
+
+If the commit succeeds and something after it fails, the log says so plainly — the migration DID complete and the file IS at the new version. The backup is kept, the startup still refuses with `MigrationFailed`, and the next start opens the migrated file normally.
+
+## Corruption is the only automatic recreate
+
+Four conditions still create a fresh, empty `querylog.db`: the file is missing, SQLite reports it as corrupt, it is not a SQLite database at all, or `PRAGMA quick_check` does not answer `ok`. Except for the missing case, the unusable file is renamed to `querylog.db.<reason>-<unix-seconds>` and kept. See [why a query log is moved aside](files-and-directories.md#why-a-query-log-is-moved-aside).
+
+Every other failure — a lock held elsewhere, a permission problem, a full disk, a version this build cannot reach — propagates and leaves the file alone.
+
+## Downgrading
+
+**Downgrading to 0.0.13 or older resets your query log.** Those binaries predate this contract: they compare `user_version` against a hash of their own schema text, find this build's version stamp instead, and treat that as a mismatch — so they rename `querylog.db` to `querylog.db.schema-changed-<unix-seconds>` and start an empty log. Nothing is destroyed, but the live log is empty until you put the aside file back, and the restamp that provoked it takes no backup of its own.
+
+To recover, go back to a migration-aware release, stop the server, then, in the data directory:
+
+1. Move the empty `querylog.db` the old binary created out of the way.
+2. Delete its `querylog.db-wal` and `querylog.db-shm`. This is not optional: replaying the empty file's write-ahead log into the restored history would corrupt it.
+3. Rename `querylog.db.schema-changed-<unix-seconds>` back to `querylog.db`.
+4. Start the server.
+
+Downgrading between two migration-aware releases is safe in the sense that matters: a build that finds a stamp above its own `current_version` refuses to start with `SchemaTooNew` and touches nothing. Go forward again, or restore the `pre-migrate` backup the upgrade left.
+
+## Breaking the schema on purpose
+
+A release may still break the query-log schema outright rather than migrate it. That is allowed, and it is never silent. Such a release raises `current_version`, sets `minimum_supported_version` to the same value, and ships no migration step — so files from before the break classify as below the minimum and `open` refuses them with `SchemaUnsupported` rather than replacing them. The release notes carry the phrase `resets your query history` and a `Restoring your query history` section, and the cut gate refuses to build the release without both.
+
+So the contract is: a break is always versioned, always refused at startup with the file intact, and always disclosed in the changelog.

specs/milestone-36.md

@@ -0,0 +1,417 @@
+# Milestone 36: Overview performance — combined endpoint, projections, cache
+
+Replace the five per-panel stats endpoints with one `GET /api/overview` served
+from materialized projections in `querylog.db` plus an in-memory response
+cache, so Overview cost stops growing with query-log size.
+
+## Motivation (measured)
+
+Today each Overview load runs five separate scans of every raw row in the
+window, serialized on `WebState.querylog_lock`, re-polled every 30 s. Measured
+x86 ReleaseSafe (bench at scratchpad `statsbench2/`, production-like skew;
+Pi ≈ 3–3.5× slower):
+
+| Rows | 30d, five scans (today) | 30d, one combined scan | 30d, projections |
+|-----:|------------------------:|-----------------------:|-----------------:|
+| 1M   | ~2.2 s                  | 264 ms                 | 41 ms            |
+| 3M   | ~6.6 s                  | 793 ms                 | 38 ms            |
+| 5M   | ~11.8 s                 | 1,346 ms               | 40 ms            |
+
+Projection maintenance costs +10% per 100-row insert batch, and ~1.5 MB of
+disk in the bench — a size bounded by retained buckets × distinct
+client/type/route keys, independent of raw query volume. Production is on a ~100k rows/day growth
+curve (≈3M rows at 30-day retention), so the projection path is the design
+target, not a contingency. Both computations were cross-checked for identical
+output in the bench.
+
+Design ruling (owner + Codex consultation, 2026-08-27): stay on SQLite;
+projections live in the same file as the raw rows and are updated in the same
+transaction, so SQLite's transaction is the coherence mechanism — no second
+file, no epoch protocol. The DDL change re-fingerprints `querylog.db`; the
+existing rename-aside path handles old files (one-time history reset,
+disclosed in the changelog). No backfill migration.
+
+## Sessions
+
+Four sessions. A first. B and C after A, in parallel (disjoint files). D after B.
+
+- A: storage — projection schema, writer maintenance, retention, new read path.
+  A does NOT delete the five existing aggregate functions — `stats.zig` still
+  calls them until B lands, and A must leave `zig build test` green.
+- B: web — `/api/overview` handler, response cache, removal of the five old
+  endpoints, OpenAPI/contract regeneration.
+- C: admin — one overview query, types, component/data plumbing, tests.
+- D: storage cleanup — delete the five now-unreferenced aggregate functions.
+
+---
+
+## Session A: storage
+
+### A.1 Schema (src/storage/querylog_schema.zig)
+
+Append four projection tables to `ddl`. Grain: 30-minute buckets, `bucket` =
+floor-to-grid of the row timestamp: `@divFloor(timestamp, 1800) * 1800` in Zig
+and the equivalent floor semantics in any SQL (SQLite integer `/` truncates
+toward zero, which differs on negative timestamps — use floor everywhere, as
+`window()` does). 1800 divides every serving
+width ≥ 30 min (1800, 3600, 21600), which is what makes one grain serve the
+24h, 7d and 30d windows exactly. The 1h window (60 s buckets) is NOT served
+from projections (A.4).
+
+```sql
+CREATE TABLE bucket_totals (
+    bucket INTEGER PRIMARY KEY,
+    queries INTEGER NOT NULL,
+    blocked INTEGER NOT NULL,
+    cached INTEGER NOT NULL,
+    rt_sum INTEGER NOT NULL,     -- sum(response_time_us) over timed rows
+    rt_count INTEGER NOT NULL    -- count(response_time_us)
+) WITHOUT ROWID;
+
+CREATE TABLE bucket_clients (
+    bucket INTEGER NOT NULL,
+    client_ip TEXT NOT NULL,
+    queries INTEGER NOT NULL,
+    PRIMARY KEY (bucket, client_ip)
+) WITHOUT ROWID;
+
+CREATE TABLE bucket_types (
+    bucket INTEGER NOT NULL,
+    qtype INTEGER NOT NULL,      -- -1 encodes a NULL qtype, losslessly
+    count INTEGER NOT NULL,
+    PRIMARY KEY (bucket, qtype)
+) WITHOUT ROWID;
+
+CREATE TABLE bucket_routes (
+    bucket INTEGER NOT NULL,
+    route_kind TEXT NOT NULL,
+    source_present INTEGER NOT NULL,  -- 0: source NULL; 1: source = source_text
+    source_text TEXT NOT NULL,        -- '' when source_present = 0
+    count INTEGER NOT NULL,
+    PRIMARY KEY (bucket, route_kind, source_present, source_text),
+    CHECK (source_present IN (0, 1)),
+    CHECK (source_present = 1 OR source_text = '')
+) WITHOUT ROWID;
+```
+
+Column semantics match the existing aggregates exactly: `blocked` counts
+`blocked <> 0`; `cached` counts `cache_hit = 1`; routes' `source` is the
+existing CASE (`upstream` rows → `upstream`, `forward_zone` rows →
+`forward_zone`, else NULL). The fingerprint moves automatically; do not touch
+the fingerprint machinery.
+
+### A.2 Writer maintenance (src/storage/repositories/queries_repo.zig)
+
+`BatchWriter.writeBatch` updates all four projections inside the same
+transaction that inserts the raw rows:
+
+- Aggregate the batch in Zig first, producing per-key deltas; then one UPSERT
+  per touched key:
+  `INSERT ... ON CONFLICT(...) DO UPDATE SET queries = queries + excluded.queries, ...`.
+  The aggregation must accept any slice length — `writeBatch`'s API does not
+  enforce the logger's 100-row batching, so no fixed-size arrays sized to it.
+  `BatchWriter` currently owns no allocator: `init` gains one, owned for the
+  writer's life, used only for the per-batch delta maps; scratch is freed (or
+  a retained map cleared) at the end of every `writeBatch`, and
+  `error.OutOfMemory` fails the batch before the transaction opens — no
+  hidden global allocator, no implicit size cap, no quadratic rescanning.
+- No per-row SQL, no triggers.
+- Failure contract: any failed projection statement rolls the whole
+  transaction back — raw rows and projections together — resets every
+  projection statement, and leaves the writer usable for the next batch
+  (`resetAll` discipline as for the raw statements today). Fault-injection
+  acceptance: a batch whose projection update fails leaves the database
+  unchanged, and the next batch succeeds.
+- The bench measured this at 0.39 ms vs 0.34 ms per batch — acceptance is
+  correctness, not speed.
+
+### A.3 Retention (src/storage/repositories/queries_repo.zig, prune path)
+
+In the same transaction as `pruneOlderThan(cutoff)`'s raw delete:
+
+1. Delete projection rows with `bucket < floor(cutoff / 1800) * 1800` from all
+   four tables.
+2. If `cutoff` is not on a bucket boundary, recompute the straddling bucket
+   (`floor(cutoff/1800)*1800`) from the remaining raw rows and replace its
+   projection rows in all four tables. Never approximate.
+
+Failure atomicity: a failure during the projection delete or the
+straddling-bucket replacement rolls back the raw delete, the watermark
+advance and every projection change together — one transaction, tested by
+fault injection.
+
+Implementation note (Session A, recorded post-build): the bucket_totals
+recompute carries `HAVING count(*) > 0` — a bare SQL aggregate always yields
+one row, and an emptied straddling bucket must disappear, not persist as
+zeros.
+
+### A.4 Read path (src/storage/repositories/queries_repo.zig)
+
+One function producing the whole Overview payload for a window, from one
+already-open read transaction (the caller owns transaction + lock, as today):
+
+```zig
+pub const Overview = struct {
+    totals: StatsTotals,
+    buckets: []const Bucket,          // bucket_count entries, zero-filled
+    clients: ClientsBreakdown,        // top-8 + other, as today
+    types: []const TypeCount,         // sorted as stats_types_sql sorts
+    routes: []const RouteCount,       // sorted as stats_routes_sql sorts
+};
+
+pub fn overview(
+    database: *db.Db,
+    arena: Allocator,
+    since: i64,
+    bucket_seconds: u32,
+    bucket_count: u32,
+) db.Error!Overview
+```
+
+Storage owns these scalars — no import of any web module. `until` is derived
+as `since + bucket_seconds * bucket_count` with the same overflow checks as
+`timeseries`. Preconditions, checked before path selection and tested:
+`bucket_seconds != 0` and `bucket_count != 0` (else `error.Misuse`, matching
+the existing clients contract); on the projection path
+(`bucket_seconds >= 1800`) additionally `since` a multiple of 1800 and
+`bucket_seconds % 1800 == 0`, else `error.Misuse`. The handler's `window()`
+guarantees all of them.
+
+Two implementations behind one entry point, chosen by `bucket_seconds`:
+
+- `bucket_seconds >= 1800` (24h, 7d, 30d): read the four projection tables
+  over `[since, until)`, aggregating 30-min rows up to the serving width in
+  Zig. `distinct_clients` comes from grouping `bucket_clients` by `client_ip`
+  over the window — never from summing per-bucket counts.
+  `avg_response_time_us` = `sum(rt_sum) / sum(rt_count)`, null when
+  `rt_count` sums to 0. Top-8 clients ranked by window total desc, ties by
+  `client_ip` asc (BINARY), residual summed into `other` — identical cut
+  semantics to `statsClients`.
+- `bucket_seconds < 1800` (1h): one single pass over the raw rows in the
+  window (one SELECT of the needed columns, stepped once), aggregating
+  everything in Zig. Memory bound: O(distinct clients + distinct qtypes +
+  distinct routes) in the window — explicitly permitted; this is a household
+  LAN and the same bound the arena-returning aggregates already carry. This
+  replaces today's five scans and the clients rank+bucket double scan. Same
+  output contracts.
+
+Sort orders and tie-breaks must reproduce the existing SQL orderings exactly
+(types: count desc, null last within tie, qtype asc; routes: count desc,
+route_kind asc, null source last, source asc) — the goldens' byte-stability
+argument carries over. Note: `RouteKind`'s enum declaration order is not
+alphabetical; "route_kind asc" means the stored text's byte order, so any Zig
+comparator orders by `@tagName` bytes, never by enum ordinal (Session A's
+accumulator already does; mutation-tested).
+
+### A.5 Acceptance criteria
+
+- [ ] `zig build test` green.
+- [ ] Property test: after an arbitrary interleaving of batches and prunes
+      (including a prune cutoff off the bucket grid), every projection table
+      equals a from-scratch recomputation from `query_log`.
+- [ ] Equivalence test: `overview()` output (both paths) equals a test-only
+      oracle over the same window on the same data — including empty windows,
+      NULL qtype, NULL source on an `upstream` row, ties in ranking, and a
+      window whose last bucket is in progress. The oracle is a copy of the
+      five existing SQL aggregates living in the test file, so it survives
+      Session D's deletion of the production functions.
+- [ ] Fingerprint test updated (table/index count assertions in
+      querylog_schema tests).
+
+---
+
+## Session B: web
+
+### B.1 Endpoint (src/web/handlers/overview.zig, replacing stats.zig's five)
+
+`GET /api/overview?period=1h|24h|30d|7d` (same grammar, default 24h, same 400
+text). One read transaction under `WebState.querylog_lock` covering the
+aggregate and `coverage.read` — one snapshot, no cross-panel skew. Response:
+
+```json
+{
+  "period": "24h", "since": ..., "until": ..., "bucket_seconds": 1800,
+  "totals": { "queries": n, "blocked": n, "clients": n, "avg_response_time_us": n|null },
+  "buckets": [ { "ts": ..., "queries": n, "blocked": n, "cached": n }, ... ],
+  "clients": [ { "client": "ip", "buckets": [n, ...] }, ... ],
+  "other": [n, ...],
+  "types": [ { "qtype": n|null, "count": n }, ... ],
+  "routes": [ { "route": "...", "source": "..."|null, "count": n }, ... ],
+  "coverage": { ... }
+}
+```
+
+Field shapes and semantics are exactly today's five bodies merged; `Period`,
+`window()`, `max_buckets` move to (or stay importable from) the new handler.
+503 when the query log is unavailable; 500 logging unchanged. Route metadata
+identical to the removed endpoints: same authentication (`.session`), same
+rate-limit class (`.counted`), same authority policy (`.read`).
+
+Remove `GET /api/stats`, `/api/stats/timeseries`, `/api/stats/types`,
+`/api/stats/routes`, `/api/stats/clients` and their routes.
+
+Contract surface (B owns all of it): add the new path and schema to the
+OpenAPI document, remove the five old operations and their schemas, update
+every drift guard that lists them, add a contract sample for
+`/api/overview`, and regenerate `admin/src/lib/contractSamples.gen.ts`
+(reserved for B — Session C must not touch it). Update the API listings in
+`docs/` and `PLAN.md` that name the five endpoints or the querylog layout.
+
+### B.2 Response cache (src/web/server.zig WebState + overview.zig)
+
+Per-period cached response body, invalidated by data change or window roll.
+Key: `(period, window.until, data_version)` where `data_version` is `PRAGMA
+data_version` on the web task's connection (it changes when any other
+connection — logger, retention — commits).
+
+The entire cache decision happens under `querylog_lock`; nothing touches the
+shared connection or the slots outside it. Exact sequence per request:
+
+1. Acquire `querylog_lock` — ONCE. `server.QuerylogRead.open` acquires this
+   lock itself, so the overview handler must not call it after step 1: B
+   refactors the scope into a lock-owning wrapper plus a
+   locked-caller variant (for example `QuerylogRead.openLocked`, documented
+   as requiring the lock), and the overview path uses the locked-caller
+   variant for step 4. A literal "lock, then QuerylogRead.open" deadlocks.
+2. Sample `PRAGMA data_version` (inside the lock — the shared connection may
+   otherwise have a foreign transaction open, and the slots need the mutual
+   exclusion anyway).
+3. Hit (`slot.period == period and slot.until == window.until and
+   slot.data_version == sampled`): copy the stored bytes into the request
+   arena, release the lock, respond. The copy is what makes a concurrent
+   rebuild's free-and-replace safe.
+4. Miss: open the read transaction, build the body, commit. Publish to the
+   slot ONLY after a successful commit, keyed by the version sampled in
+   step 2 (a commit landing during the build bumps `data_version`, so the
+   next request rebuilds — stale-under-new-key is impossible). A failed
+   commit or build publishes nothing and responds 500 as today.
+5. Copy to the request arena, release the lock, write the socket. The lock
+   never spans a socket write (existing discipline).
+
+Because the check happens only under the lock, `querylog_lock` is the
+single-flight: a second request for the same key waits and then hits.
+
+Storage: one slot per period (4 slots) in `WebState`; body bytes allocated
+from `WebState.gpa`, replaced on rebuild (free old, install new), freed in
+`deinit`. No capacity limit beyond the allocator — a body is bounded by the
+fixed bucket counts plus the household client/type/route cardinality.
+
+No adaptive polling and no combined-endpoint staging: with projections + this
+cache a rebuild is ~40 ms x86 / ~0.13 s Pi, so the admin's existing 30 s
+cadence is fine.
+
+### B.3 Acceptance criteria
+
+- [ ] `zig build test` green; handler tests ported from stats.zig (period
+      grammar, window math, one-snapshot behavior) plus: cache hit returns
+      byte-identical body; a logger commit (data_version bump) invalidates;
+      a window roll invalidates; a retention prune committed through another
+      connection invalidates (both the aggregates and the cached
+      `coverage.available_since` are replaced); a failed read-transaction
+      commit neither installs nor replaces a cache entry.
+- [ ] `curl /api/overview?period=30d` on a seeded scratch instance returns all
+      panels consistent (breakdowns sum to totals on a quiet database).
+- [ ] The five old routes return 404.
+
+---
+
+## Session C: admin
+
+### C.1 Data layer
+
+- `admin/src/lib/types.ts`: one `Overview` type mirroring B.1; remove the five
+  per-panel response types.
+- `admin/src/lib/api.ts`: `getOverview(period)`; remove the five getters.
+- `admin/src/lib/queries.ts`: `overviewQuery(period)` with
+  `refetchInterval: 30_000` and key `["overview", period]`; remove the five
+  stats query factories and their keys.
+
+### C.2 Overview page
+
+`admin/src/features/overview/overviewWindow.ts` and the chart components
+consume the single query: one `useQuery` where five ran in parallel. Loading,
+error and coverage handling collapse to one page-level surface (one spinner
+state, one error state for the whole Overview); the per-panel shells,
+layout, copy, chart dimensions and accessibility attributes stay exactly as
+they are. Chart components (TimeseriesChart, ClientChart, Donut) keep their
+props — adapt the mapping layer, not the charts. C must not touch
+`contractSamples.gen.ts` (B owns its regeneration).
+
+### C.3 Acceptance criteria
+
+- [ ] `npm test` green in admin/ (mock the one endpoint; port the five-query
+      tests).
+- [ ] `npm run typecheck` green — the build alone does not run tsc. B and C
+      are file-disjoint but type-coupled through `contractSamples.gen.ts`:
+      C's typecheck/test/build gates run (or re-run) AFTER B has regenerated
+      that file. Implementation may proceed in parallel; the green gate is
+      sequenced.
+- [ ] `npm run build` green; bundle-size assertion still passes.
+- [ ] Manual: scratch instance renders all Overview panels from the new
+      endpoint on all four periods.
+
+---
+
+## Session D: storage cleanup
+
+After B is merged and green: delete `statsTotals`, `timeseries`, `statsTypes`,
+`statsRoutes`, `statsClients` and their SQL constants from
+`queries_repo.zig` — nothing references them once `stats.zig` is gone. The
+test-only oracle from A.5 stays. Acceptance: `zig build test` green, no dead
+stats SQL remains in production code.
+
+---
+
+## Module layout
+
+- `src/web/handlers/overview.zig` — new; replaces `src/web/handlers/stats.zig`
+  (deleted by B).
+- `src/storage/querylog_schema.zig` — projection DDL appended.
+- `src/storage/repositories/queries_repo.zig` — writer maintenance, retention
+  integration, `overview()` read path (A); five old aggregates deleted (D).
+- Admin files per C.1/C.2.
+
+## File ownership
+
+- A: `src/storage/*` (old aggregates left in place), plus the mechanical
+  allocator-plumbing at every `BatchWriter.init` call site outside storage
+  (`src/web/handlers/*`, `src/web/web_integration_test.zig`, any test using
+  the writer) — A runs before B, so this is sequential, not shared,
+  ownership; A's gate is the full `zig build test`.
+- B: `src/web/*`, plus: `src/app.zig` (cache cleanup at the composition
+  root), `src/tests.zig` (handler import swap), the OpenAPI document and its
+  drift guards, contract samples including
+  `admin/src/lib/contractSamples.gen.ts`, `docs/**` API listings, `PLAN.md`
+  stale sections, and the Overview/API sections of `specs/ui-redesign.md`
+  (which still mandates the five endpoints and must be amended, not obeyed).
+- C: `admin/*` EXCEPT `admin/src/lib/contractSamples.gen.ts`.
+- D: `src/storage/repositories/queries_repo.zig` (sequential, after B).
+- Orchestrator: `CHANGELOG.md` (hand-written, per release process).
+B and C run in parallel; the one shared-tree exception above is reserved to B.
+
+## Acceptance criteria (milestone complete)
+
+- [ ] `zig build test` and `zig build test -Dintegration` green (the
+      integration suite carries the live route walk, contract-sample
+      comparison, concurrent querylog reads and OpenAPI guards); admin
+      `npm test`/`typecheck`/`build` green.
+- [ ] Scratch-instance smoke: seeded data + live digs; Overview correct on all
+      periods; old endpoints gone.
+- [ ] Changelog discloses: schema change resets query history (rename-aside),
+      five endpoints replaced by `/api/overview`.
+- [ ] Release gate (`zig build cut` fingerprint check) satisfied.
+
+## Anti-requirements
+
+- No second database file, no epoch/validity protocol, no ATTACH.
+- No backfill migration, no rebuild command, no catch-up cursor — projections
+  are born with the file and maintained transactionally; that is the whole
+  coherence story.
+- No connection pool, no adaptive polling, no DuckDB.
+- No new indexes on `query_log`, no triggers, no per-row projection SQL.
+- Do not change the 1h/24h/7d/30d period grammar, bucket widths or counts.
+- No HTTP-level caching of any kind: no ETag, no `Cache-Control`, no
+  stale-while-revalidate, no background refresh, and never cache a 500/503
+  body. The cache is exactly the in-process design of B.2.
+- No visual redesign, no chart-prop changes, no cache configuration knobs,
+  no cache metrics. This milestone changes data acquisition and storage only.

specs/milestone-37.md

@@ -0,0 +1,337 @@
+# Milestone 37: Upstream failover budget — deadline ownership and honest attribution
+
+Make the pool's failover loop own one deadline (admission included), revive the
+standby under primary saturation, and stop blaming endpoints for budget
+exhaustion.
+
+## The defect (field-verified on the Pi, 0.0.11)
+
+With defaults attempt=2500 ms / total=5000 ms and two upstreams:
+
+1. `Pool.exchangeLoopLen` (pool.zig:277) never computes remaining time. The
+   semaphore wait consumes the total budget invisibly: under a traffic burst
+   the primary's slots saturate, a new request queues behind them while the
+   standby sits idle with free slots, and the outer `raceWithin(total)` cancels
+   whatever finally runs. 155 requests died at the 5 s cap; 706 of 717
+   SERVFAILs came from one bursty client. On an idle pool a fast standby works
+   today — the queue is the killer, not the timer arithmetic alone.
+2. The reporting contradicts itself. `selected` is written before the attempt
+   runs (pool.zig:348), so the query log blamed the standby on 279 rows;
+   cancelled attempts are excluded from health (pool.zig:363), so its counters
+   read 0/0. Nothing records "the request exhausted its own budget."
+
+Design reviewed and converged with Codex (thread of 2026-08-27). Defaults do
+not change.
+
+## Sessions
+
+Three, strictly sequential: A (transport vocabulary) → B (pool) → C
+(handler, forward client, surfaces).
+
+---
+
+## Session A: transport vocabulary
+
+### A.1 `error.BudgetExhausted` and a fourth group (src/upstream/transport.zig)
+
+- Add `BudgetExhausted` to `ExchangeError`.
+- Add `.budget_exhausted` to `Group`; `group()` maps the new error to it. The
+  switch stays exhaustive with no `else` — every switch over `Group` breaks at
+  compile time until it handles the new group, which is the point. The
+  production switches are `pool.zig` (:353), `handler.zig` (:677, :735) and
+  `forward_client.zig` (:124). Session A owns a mechanical placeholder arm at
+  each (pool and forward_client: propagate the error without recording
+  health; handler: `=> ctx.servFail()`), plus any test switches the compiler
+  flags, so A's `zig build test` passes. B and C then own the real behavior
+  at their sites. (health.zig has no `group` call; the doh/dot occurrences
+  are tests, not switches.)
+
+### A.2 Timer-origin race (src/upstream/transport.zig)
+
+`raceWithin` collapses "the expiry task won" and "the raced operation itself
+returned error.Timeout" into one `error.Timeout`. Add:
+
+```zig
+pub const RaceOutcome = enum { completed, expired };
+
+pub fn raceUntilTagged(
+    io: std.Io,
+    expiry_at: std.Io.Clock.Timestamp,
+    outcome: *RaceOutcome,
+    comptime f: anytype,
+    args: anytype,
+) ExchangeError!RacedPayload(f)
+```
+
+The expiry parameter is an ABSOLUTE timestamp, not a duration: a duration
+computed from `deadline.toDurationFromNow()` and then slept re-anchors at
+"now", drifting past the total deadline and misclassifying a nominally full
+attempt. The pool computes `expiry_at = min(now + attempt, total_deadline)`
+and passes the timestamp. On the expiry side the function sets `outcome.* =
+.expired` and returns `error.Timeout`; on completion it sets `.completed` and
+returns the raced result (which may itself be `error.Timeout` from the leaf —
+that is a completed peer timeout, not an expiry). `raceWithin` keeps its
+public API and behavior but delegates to the same internal harness (compute
+the absolute deadline, discard the outcome) — one `Select` harness in the
+file, not two copies.
+
+### A.3 Acceptance
+
+- [ ] `zig build test` green.
+- [ ] Unit tests: tagged race distinguishes leaf `error.Timeout` (completed)
+      from expiry (`expired`); the untagged wrapper is unchanged behavior.
+
+---
+
+## Session B: the pool (src/upstream/pool.zig)
+
+### B.1 One deadline owns the loop
+
+- `Pool.exchange` establishes `deadline = std.Io.Timeout{ .duration =
+  self.timeouts.total }.toDeadline(io)` (`.awake` clock, as the loop uses
+  today) and passes it down. The equal-deadline outer `raceWithin` at
+  pool.zig:267 is REMOVED — the loop owns the deadline; two timers aimed at
+  the same instant race each other and let the outer cancellation bypass the
+  loop's classification. No replacement watchdog (the outer race never bounded
+  uncancelable health writes anyway; a later-firing watchdog is scope creep).
+- Every blocking step consumes the deadline:
+  - Admission: through the ownership-safe protocol of B.2 — never a bare
+    `Semaphore.wait` raced against an expiry. Racing the wait with
+    `Select.cancelDiscard` can leak a permit: the wait may have decremented
+    the count in the same instant the expiry wins, and the discarded success
+    never reaches the caller's release-defer. If no time remains before
+    admission, return `error.BudgetExhausted` without waiting.
+  - Attempt: raced via `raceUntilTagged` against
+    `expiry_at = min(now + timeouts.attempt, total_deadline)`.
+- `total < attempt` is already rejected by validate.zig; `total == attempt`
+  (and any admission overhead) simply yields truncated attempts, handled by
+  B.3.
+
+### B.2 Admission without head-of-line blocking
+
+Zig 0.16's `Semaphore` has neither try-acquire nor a timed wait, so the pool
+gains a local admission helper mirroring the standard semaphore's own
+mutex/decrement/condition protocol (never by patching `../zig`, never by
+spinning):
+
+- `tryAcquire()` — take a permit if one is immediately available, else fail
+  without blocking.
+- `acquireUntil(deadline)` — timed acquisition; returns Acquired (holding a
+  permit), Expired (holding none), or `error.Canceled` (holding none).
+  `std.Io.Condition` has no timed wait in 0.16, so this is a NEW pool-local
+  primitive, specified exactly: state lives under one mutex (permit count +
+  waiter bookkeeping); the wait itself may race `Condition.wait` against a
+  sleep via `Select`, because a permit is only ever taken under the mutex
+  AFTER the race resolves — a discarded wake is a lost notification, not a
+  lost permit. To keep that lost notification from stranding another waiter,
+  an exiting waiter that may have absorbed a signal (expiry or cancellation
+  path) re-signals the condition before returning. Permit conservation is by
+  construction: the decrement and the "did I win" decision happen under the
+  same mutex. Every take is non-blocking (the mutex's `tryLock`): a lock
+  miss reads as "no permit now", and `acquireUntil` re-enters the
+  absolute-deadline race on each miss, so contention on the admission mutex
+  never carries a call past its deadline (review round 2026-08-27). Tests:
+  an expiry/acquisition tie leaves the permit count exact; a cancelled
+  waiter holds nothing and a peer waiter still wakes; a contended admission
+  mutex does not carry `acquireUntil` past its deadline.
+
+Loop semantics — priority means ordering among immediately admissible
+candidates:
+
+1. Pass one, first sweep in priority order: `tryAcquire` on each available
+   entry; the first immediate success is attempted. A saturated entry is
+   skipped while another eligible entry has capacity.
+2. If the attempted entry fails (peer fault), the sweep continues from the
+   next entry, still by `tryAcquire`; previously skipped saturated entries
+   are re-tried by `tryAcquire` on each subsequent sweep step (a slot may
+   have freed).
+3. Only when no eligible entry has an immediate permit does the loop block:
+   `acquireUntil(remaining deadline)` on the highest-priority eligible
+   entry. Expired → `error.BudgetExhausted`. The no-head-of-line guarantee
+   is deliberately scoped to capacity observed during the sweep: once
+   blocked, a lower-priority slot freeing does not wake this waiter
+   (any-entry wakeups need multi-wait machinery this milestone does not
+   buy). Record this bound in the admission helper's doc comment.
+4. Pass two (backoff probing) keeps today's in-order probing but admits
+   through the same helper bounded by the remaining deadline — it
+   deliberately retains blocking, one entry at a time, because probing a
+   backed-off entry is already a last resort.
+5. The post-admission health recheck survives the refactor: after acquiring
+   a permit by either path in pass one, re-read health against a fresh
+   `now`; an entry that entered backoff while this task waited is released
+   (permit returned) and the sweep resumes. The existing regression test
+   for this recheck is retained.
+6. Before any attempt starts — immediate admission included — the loop
+   re-reads the clock; a deadline already passed returns
+   `error.BudgetExhausted` with the permit returned and no endpoint named,
+   so an instantly-completing leaf can never manufacture evidence after
+   exhaustion (review round 2026-08-27). Test: an exchange whose deadline
+   is already gone starts no attempt.
+7. The compiled pool bound (`Pool.max_entries`, 64) is enforced at config
+   validation: more than 64 ENABLED upstreams is `TooManyUpstreams` at path
+   `upstreams`, so a valid config can never trip the pool assert (review
+   round 2026-08-27). Tests: 64 enabled passes, 65 fails, 65 listed with
+   64 disabled passes.
+8. Queue accounting keeps its meaning: `queued_total` and
+   `queued_seconds_total` count only the blocking `acquireUntil` path,
+   recorded whether it ends in acquisition, expiry or cancellation; a
+   `tryAcquire` — hit or miss — never counts as queued. Acceptance test
+   retained.
+
+### B.3 Classification (uses A.2's tagged race)
+
+| Attempt outcome | Budget it ran with | Health | `selected` | Loop action |
+| --- | --- | --- | --- | --- |
+| success | any | success | this endpoint | return answer |
+| expiry (`expired`) | full `attempt` | failure | this endpoint | continue failover |
+| expiry (`expired`) | truncated | untouched | unchanged | return `error.BudgetExhausted` |
+| completed peer fault (incl. leaf Timeout) | any, even truncated | failure | this endpoint | continue failover |
+| local_resource | — | untouched | unchanged | return err (as today) |
+| cancellation | — | untouched | unchanged | return `error.Canceled` |
+| wait exhausts deadline | — | untouched | unchanged (null if nothing ran) | return `error.BudgetExhausted` |
+| completed attempt returns `error.BudgetExhausted` (a leaf may emit it once it exists) | any | untouched | unchanged | return it; counter increments once at the outer pool |
+
+A truncated expiry is a censored observation: the pool did not grant the
+configured observation interval, so it is evidence about the pool's budget,
+never about the peer. No minimum-attempt floor exists.
+
+### B.4 `selected` = last attributable endpoint
+
+Assign `selected.*` only in the success row and the two health-recording
+failure rows above — after the attempt completes, not before it starts. This
+attribution rule is POOL-SPECIFIC: leaf clients (DoH, DoT, ForwardClient,
+test fakes) keep their write-before-attempt behavior — they have one
+endpoint and record no health, so "the endpoint I tried" is honest there.
+The `Client.exchange` doc comment in transport.zig is amended to state both
+contracts: implementations may write before each attempt; `Pool` documents
+its stricter last-attributable rule on `Pool.exchange` itself. The pool-level
+tests at pool.zig:748-771 (selected-before-attempt) and :910 invert into the
+new contract's tests; leaf-client tests are untouched.
+
+### B.5 The counter
+
+`Pool` gains one pool-level counter, `budget_exhausted_total` (atomic u64,
+incremented once per exchange that returns `error.BudgetExhausted`, never per
+endpoint). `Pool.snapshot` returns per-entry rows and cannot carry a
+pool-wide number without duplicating it — so the counter is exposed through a
+separate getter, `Pool.budgetExhaustedTotal()`, and B owns the mechanical
+plumbing at every existing snapshot call site its change touches so B's own
+gate passes before C. No per-stage split (queue vs attempt) —
+fixed-cardinality stage labels are deferred until an operator needs them.
+
+### B.6 Acceptance (the decisive regressions first)
+
+- [ ] Fast standby at shipped defaults: entry 0 stalls its full attempt
+      budget, entry 1 answers instantly, attempt = total/2 → entry 1 answers.
+- [ ] Saturated primary, free standby: entry 0's slots all held by stalled
+      exchanges, entry 1 free and fast → entry 1 answers well inside the
+      deadline. This is the Pi reproduction; it must FAIL against the current
+      code and pass after B.2.
+- [ ] Truncated expiry mutates no health, returns BudgetExhausted, leaves
+      `selected` at the last attributable endpoint.
+- [ ] Truncated attempt failing with ConnectionRefused mutates health and
+      updates `selected`.
+- [ ] Queue-only exhaustion → BudgetExhausted with `selected == null`.
+- [ ] All-backoff pass two runs under the same deadline.
+- [ ] External cancellation returns Canceled, counts no budget, mutates
+      nothing.
+- [ ] `budget_exhausted_total` increments once per exhausted exchange.
+- [ ] Existing invariants hold: cancelled waiter returns its permit; two
+      stalling upstreams cost ≤ total, not one budget each.
+
+---
+
+## Session C: handler, forward client, surfaces
+
+### C.1 Handler (src/server/handler.zig)
+
+Both `transport.group` switches (:677, :735) gain `.budget_exhausted =>
+ctx.servFail()` — SERVFAIL on the wire, same as peer faults; no rcode fits
+better. No per-query warn log (spam); the counter is the record.
+
+### C.2 Forward client (src/local/forward_client.zig)
+
+One outer budget for the whole exchange: wrap UDP attempt → truncation
+fallback → TCP in a single tagged race against `read_timeout` (the UDP
+receive's internal deadline and the TCP `raceWithin` at :217 collapse into
+the one outer bound — remove the fresh TCP budget). Every timeout here
+concerns the single configured resolver, so expiry stays `error.Timeout`
+(peer evidence), never BudgetExhausted — the budget/peer distinction is pool
+policy. Test: truncated-UDP-then-stalled-TCP completes or expires within one
+`read_timeout`, not two. Update the doc comment on `read_timeout_ms` in the
+config (validate.zig:360 note and the settings description) to say it bounds
+the whole forward-zone exchange. The key is NOT renamed (anti-requirement).
+
+### C.3 Surfaces
+
+- Metrics: `nxdns_upstream_budget_exhausted_total` (pool-wide) wherever
+  `nxdns_upstream_*` counters render, read via `Pool.budgetExhaustedTotal()`.
+- `/api/health` is NOT changed (decision, not omission): the counter is an
+  operator metric, it never changes health status, and adding it to the API
+  would drag openapi.yaml, admin types, fixtures, contract samples and the
+  admin gates into a milestone that owes them nothing. Metrics only.
+- docs: `docs/reference/configuration.md` — every statement describing
+  `read_timeout_ms` as a per-read or per-attempt bound is rewritten to the
+  whole-exchange contract; the upstream timeouts section gains one paragraph
+  on budget semantics (deadline, truncation, attribution). The stale contract
+  text in `src/config/model.zig` (the setting's doc comment) and the note at
+  `src/config/validate.zig:360` are updated to match.
+
+### C.4 Acceptance
+
+- [ ] `zig build test` and `zig build test -Dintegration` green.
+- [ ] Metrics test covers the new counter's rendering.
+- [ ] Forward-client single-budget test per C.2.
+
+---
+
+## File ownership
+
+- A: `src/upstream/transport.zig`, plus mechanical placeholder arms at the
+  broken `Group` switches (`src/upstream/pool.zig`, `src/server/handler.zig`,
+  `src/local/forward_client.zig`, test switches the compiler flags) —
+  sequential ownership, A runs alone; C takes forward_client.zig and
+  handler.zig over later in sequence.
+- B: `src/upstream/pool.zig` (+ the `Client.exchange` doc contract in
+  transport.zig and snapshot-caller plumbing for the new getter — B runs
+  alone after A).
+- C: `src/server/handler.zig`, `src/local/forward_client.zig`, the metrics
+  rendering files, `src/config/model.zig` + `src/config/validate.zig` doc
+  text, `docs/reference/configuration.md`.
+- Orchestrator: CHANGELOG.md.
+
+## Acceptance criteria (milestone complete)
+
+- [ ] All session criteria; both suites green; `zig fmt --check` clean.
+- [x] The saturated-primary regression demonstrably fails on pre-milestone
+      code and passes after. Evidence (orchestrator-run mutation check,
+      2026-08-27): with the pass-one `tryAcquire` sweep disabled in
+      `Pool.admit` — restoring pre-fix head-of-line blocking — the test
+      "a saturated primary defers to a standby that has capacity" fails with
+      `error.BudgetExhausted` out of the blocking admission path, and four
+      queue-accounting/attribution tests fail with it (5 failed, seed
+      0x91ce5df5). Sweep restored: 30/30 steps, 1892/2067 passed, 0 failed.
+- [ ] Changelog: failover now works under primary saturation; SERVFAILs from
+      budget exhaustion are counted, not blamed on an upstream; for
+      upstream-pool queries the query-log `upstream` field now names only
+      endpoints whose outcome was recorded (may be null) — forward-zone
+      queries keep naming their single configured resolver as before.
+
+## Anti-requirements
+
+- No default timeout changes.
+- No parallel/racing fan-out to multiple upstreams. Priority failover stays,
+  with priority defined as ordering among immediately admissible candidates
+  (B.2) — a saturated higher-priority entry defers to an admissible
+  lower-priority one; it does not outrank an idle standby by blocking on it.
+- No `/api/health` or admin changes; the counter surfaces in metrics only.
+- No patching of the vendored/system Zig stdlib; the admission helper is
+  pool-local.
+- No rename of `upstream.read_timeout_ms` (doc fix only).
+- No minimum-attempt floor constant.
+- No per-stage split of the budget counter; no per-query budget log lines.
+- No watchdog replacing the removed outer race.
+- No fake upstream identity (e.g. "budget") in the query log; no new
+  query-log column.
+- No changes to backoff policy, slot counts, or health scoring beyond the
+  attribution rules above.

specs/milestone-38.md

@@ -0,0 +1,192 @@
+# Milestone 38: querylog schema migrations
+
+Stop the recurring query-history loss: schema changes migrate querylog.db in place; the automatic reset survives only for real corruption; explicit breaks stay possible but must be versioned, refused by `open`, and ship recovery instructions.
+
+Owner rulings (2026-08-28): baseline is the 0.0.12/0.0.13 schema — nothing older is migratable; breaking changes remain allowed but must be explicit with clear changelog instructions; keep only the most recent pre-migration backup.
+
+## Sessions
+
+A (storage framework) first. B (cut gate) needs A's modules. C (docs) after A (documents A's behavior; shares no files with B). The orchestrator writes the changelog.
+
+---
+
+## Session A: migration framework in storage
+
+### A.1 Version metadata module (pure, no SQLite)
+
+New file `src/storage/querylog_versions.zig` — importable by `tools/cut.zig` without linking SQLite. ONLY comptime data:
+
+- `pub const current_version: i32 = 1;`
+- `pub const minimum_supported_version: i32 = 1;` — files stamped below this refuse. An EXPLICIT BREAK in a future release is expressed here: bump `current_version`, set `minimum_supported_version = current_version`, ship no step. The chain then cannot reach the new version from below the minimum and `open` refuses the old file — a break is always versioned, always refused at runtime, never silent.
+- `pub const legacy_fingerprint: i32 = 1975011655;` — the literal `user_version` stamp the 0.0.12/0.0.13 binaries wrote (CRC32 of their DDL text). FROZEN literal, derived from nothing; comment cites v0.0.12.
+- `pub const version_floor_guard: i32 = 1_000_000;`
+- Comptime asserts: `minimum_supported_version >= 1`; `minimum_supported_version <= current_version`; `current_version <= version_floor_guard`; `legacy_fingerprint` outside `[0, version_floor_guard]`; `step_sql.len == current_version - minimum_supported_version`.
+- `pub const step_sql: []const [:0]const u8 = &.{};` — step i migrates version `minimum_supported_version + i` to `+ i + 1`; each entry is `@embedFile("migrations/v<from>.sql")`. EMPTY this milestone.
+- **Steps are SQL-only. There are no migration hooks.** A rebuild that m36-style projections would need is expressible as plain SQL (the recompute statements are SQL); a future change that truly cannot be SQL must amend this design explicitly in its own spec. This keeps every shipped migration byte-comparable (B.2 Gate 2) with no mutable code path.
+- Shipped step files `src/storage/migrations/v<from>.sql` and fixtures (B.1) are immutable once released; the cut gate byte-compares them against the previous tag.
+
+### A.2 Runner module and the rebuild rule
+
+New file `src/storage/querylog_migrations.zig` (SQLite side): the runner and the equivalence oracle.
+
+- `pub fn migrateSteps(database: *db.Db, sql: []const [:0]const u8, from: i32, target: i32) (db.Error || error{TransactionViolation})!void` — runs the steps and the final `PRAGMA user_version = target` stamp inside the caller's already-open transaction. SLICING CONTRACT: `sql` is exactly the `[from, target)` suffix — `sql[0]` migrates `from -> from + 1`; asserted: `sql.len == @intCast(target - from)`. Production callers slice `step_sql[from - minimum_supported_version ..]`. While steps execute, the runner installs SQLite's authorizer (`sqlite3_set_authorizer`; expose a scoped install/clear pair on the db wrapper) denying `SQLITE_TRANSACTION` — a step cannot BEGIN/COMMIT/ROLLBACK at all, which is the only reliable guard (a step containing `COMMIT; BEGIN IMMEDIATE;` would pass a post-step autocommit check while breaking atomicity; that exact bypass is a required negative test, and the test must also assert the authorizer is cleared after the rejection: the rollback succeeds and the SAME connection can then execute transaction statements normally — a leaked authorizer would block cleanup and strand the connection inside the migration transaction). The authorizer is cleared on every exit path. Belt: the post-step `sqlite3_get_autocommit(db) == 0` check stays. `migrateSteps`'s error set is `(db.Error || error{TransactionViolation})`; `runMigration` maps `TransactionViolation` to `error.MigrationFailed`. The no-transaction-statements rule is also in the step-authoring doc comment.
+- `pub fn runMigration(io: std.Io, dir: std.Io.Dir, path: [:0]const u8, database: *db.Db, sql: []const [:0]const u8, from: i32, target: i32) Error!void` — the full orchestration seam: backup (A.4 step 1), transaction + `migrateSteps` + commit (step 2), failure handling (step 3), retention (step 4). `open` calls it with production metadata; synthetic tests call it directly with test chains, so the REAL backup/collision/retention/error paths are what the tests prove.
+- **Rebuild rule** (doc comment on `step_sql`): a step that changes a table's shape must produce a table whose stored CREATE text is byte-identical to the fresh DDL's. The RUNNER brackets every migration with: `PRAGMA foreign_keys = OFF` and `PRAGMA legacy_alter_table = ON` BEFORE `BEGIN IMMEDIATE` (with `foreign_keys` on — which `db.applyPragmas` enables — a rename of a referenced parent rewrites child tables' FK text to `<t>_old`, corrupting them the moment the old table drops; `legacy_alter_table` alone does not prevent that), and restores both pragmas on EVERY exit path, success or failure (they are connection-global and non-transactional). Before COMMIT the runner runs `PRAGMA foreign_key_check` and fails the migration on any row. Step sequence: `ALTER TABLE <t> RENAME TO <t>_old`, `CREATE TABLE <t> ...` pasted VERBATIM from the target `querylog_schema.ddl`, `INSERT INTO <t> SELECT ...` mapping, `DROP TABLE <t>_old`, recreate EVERY dependent object of `<t>` verbatim from the target DDL — indexes AND triggers (both dropped with `<t>_old`). Views are NOT dropped by the rename or the drop (with `legacy_alter_table` on they keep naming `<t>`), so a step DROPs each view over `<t>` FIRST and recreates it verbatim LAST — recreating without the drop fails with "view already exists". `ALTER TABLE ... ADD/RENAME COLUMN` on a kept table is forbidden — SQLite rewrites stored CREATE text under it and the oracle's text layer would rightly fail.
+
+### A.3 The open path (rework `querylog_schema.open`)
+
+`open` owns the file exclusively: nxdns opens querylog.db once at startup before serving, and no other process shares a data dir (existing deployment contract; restate in `open`'s doc comment — the backup-then-lock sequence relies on it).
+
+The version-handling half of `open` is factored as `openVersioned(io, dir, path, handle, plan) Error!void` where `handle: *?db.Db` is an optional SLOT: `openVersioned` closes and nulls it on every error path, so the caller's `errdefer` no-ops and single-close is structural rather than a convention (as built 2026-08-28; the post-commit test asserts `handle == null`). `plan: Plan = .{ .minimum: i32, .current: i32, .legacy_fingerprint: i32, .step_sql: []const [:0]const u8 }`. Production `open` passes the constant plan from `querylog_versions`; tests inject synthetic plans, which is what makes classification, migration, the post-commit mapping, and the sole-close ownership all testable through the REAL open path even while the production chain is empty. Classification itself stays a pure function of `(stamped, plan)`.
+
+Classify a healthy existing file: read `PRAGMA user_version` as `stamped`, map to a logical version FIRST, mutate NOTHING during classification:
+
+| condition | logical version | action |
+| --- | --- | --- |
+| `stamped == legacy_fingerprint` | 1 | classify version 1 by the rows below; if it lands on "current" or "supported older", first restamp to 1 (one transaction, A.5 error mapping), then proceed |
+| `stamped == current_version` | stamped | open as today |
+| `minimum_supported_version <= v < current_version` | v | migrate via `runMigration` |
+| `current_version < v <= version_floor_guard` | v | REFUSE: `error.SchemaTooNew` |
+| anything else (0, negatives, other fingerprints, below minimum) | — | REFUSE: `error.SchemaUnsupported` |
+
+The order matters: after a future explicit break raises the minimum above 1, a legacy-fingerprint file maps to version 1, classifies as below-minimum, and refuses WITHOUT the restamp — an unsupported file is never modified.
+
+REFUSE: the canonical file stays in place, logically untouched (schema, rows, watermark, stamp unchanged — WAL/SHM sidecar bytes may change from the probe; not a violation), nothing set aside, no new file, `open` errors, the server does not start. The log line names the path, the stamped value, the supported range, and `docs/how-to/troubleshoot.md` ("The server refuses to start over querylog.db").
+
+Recreate lanes `missing`, `not_a_database`, `corrupt`, `quick_check_failed` unchanged. `RecreateReason.fingerprint_mismatch` and the `schema-changed` aside tag are DELETED.
+
+Fresh files: after executing `ddl`, stamp `PRAGMA user_version = current_version` (the stamp is already a separate statement; the DDL text does not change this milestone, so `querylog_schema.fingerprint` does not move).
+
+Backup retention has two passes with different authority. A migration's step 4 KNOWS the newest backup — this run's exact filename — and deletes every other `querylog.db.pre-migrate-*`; it is the primary mechanism. A plain successful open at current version runs a CONSERVATIVE retry for cleanups that once failed: parse `<epoch>` and the optional `-N` collision suffix from each name, delete only files whose epoch is STRICTLY below the maximum, keep every file tied at the maximum epoch, and never delete a name that does not parse. This pass EXPLICITLY assumes forward-moving wall clock between migrations (record the assumption in its doc comment): under a clock rollback an older high-epoch name could outrank a genuinely newer backup, which is why the authoritative exact-name pass in step 4 is the primary mechanism and this pass is only the retry for its failures.
+
+### A.4 Running a migration (`runMigration`)
+
+1. **Backup.** `VACUUM INTO` on the live connection (no open transaction) to `querylog.db.pre-migrate-<epoch>` in the database's directory. Destination must not pre-exist: on collision retry `-<epoch>-2`, `-3`, … The path enters the statement through an SQL string-literal quoting helper (double every `'`), never raw interpolation. On failure: delete the partial destination just created (only that file; an older valid backup survives), REFUSE with `error.MigrationBackupFailed`.
+2. **One transaction.** `BEGIN IMMEDIATE`; re-read `user_version` under the lock. If it no longer equals `from`: ROLLBACK, delete this run's backup, REFUSE with `error.MigrationFailed` (exclusive ownership makes this outside interference). Otherwise `migrateSteps(db, sql, from, target)` — every step and the stamp in this one transaction — then COMMIT once.
+3. **On PRE-COMMIT failure:** ROLLBACK, delete this run's backup, REFUSE with `error.MigrationFailed`, log the failing step index. Canonical file keeps its logical state. Never fall through to recreate.
+3b. **On POST-COMMIT failure** (pragma restore or anything after a successful COMMIT): the file IS at `target` and that is said plainly in the log; the backup is KEPT (never deleted on this path). `runMigration` does NOT close the borrowed connection — it returns the distinct internal error `error.MigrationCommittedButUnclean`, and `querylog_schema.open`, which owns the handle and already has the sole error-path close, performs that one close and surfaces `error.MigrationFailed` to its caller. The next start takes the current-version lane cleanly. No post-commit path may claim the file unchanged or delete the backup.
+4. **On success:** best-effort delete of every OTHER `querylog.db.pre-migrate-*` (keep this run's). Deletion errors warn and do not fail startup; A.3's every-open retention retries later. Log one line naming `from -> target` and the kept backup.
+
+### A.5 Legacy restamp error mapping
+
+The fingerprint→1 restamp is this milestone's only real mutation of operator data. It runs in one transaction; any failure (statement or commit) maps to `error.MigrationFailed`, rolls back, and leaves the legacy stamp and every row intact — REFUSE semantics, never recreate. Session A adds a test-only fault-injection seam to the db wrapper (`src/storage/db.zig`, following its existing `ReadTx.commit` injection style): one SQL-substring-matched one-shot seam on `Db.exec` covers statement and commit alike (both restamp statements pass through `Db.exec`), and the same seam drives the post-commit pragma-restore failure. Refusal paths log at `err`, which the test runner treats as failure, so `querylog_migrations.expected_failures` (begin/end/capturing, modelled on `db.read_tx_faults`) captures EXPECTED refusal logs per test; an unexpected refusal elsewhere still fails its test (as built 2026-08-28). Acceptance tests: the restamp forced to fail at (a) the statement and (b) the commit each leave `user_version == legacy_fingerprint` and the rows readable by a subsequent successful open.
+
+### A.6 Schema equivalence oracle
+
+`pub fn schemaEquivalent(gpa: std.mem.Allocator, a: *db.Db, b: *db.Db) (db.Error || std.mem.Allocator.Error)!bool` in `querylog_migrations.zig`. Two layers, both must agree:
+
+1. **Textual, exact:** for every non-`sqlite_` object in `sqlite_schema` (tables, indexes, views, triggers), compare `(type, name, tbl_name, sql)` with `sql` compared byte-for-byte. No normalization: the A.2 rebuild rule guarantees a migrated table carries the verbatim fresh CREATE text, and a fresh file trivially does. This layer sees CHECK constraints, foreign keys, WITHOUT ROWID, partial-index predicates, trigger/view bodies.
+2. **Structural belt:** per table, `PRAGMA table_xinfo` rows and `pragma_table_list` `wr`/`strict` flags; per table, `PRAGMA foreign_key_list`; per index, `PRAGMA index_xinfo` plus `index_list` `unique`/`origin`/`partial` flags.
+
+Sort object and row lists before comparison. Negative tests: dropped `CHECK (rcode BETWEEN 0 AND 4095)`; dropped `REFERENCES domains(id)`; dropped `WITHOUT ROWID`; added column; and a table rebuilt via `ALTER TABLE ... RENAME` WITHOUT the verbatim-text rule compares UNEQUAL (proves the text layer catches SQLite's rename rewrite).
+
+### A.7 Acceptance criteria
+
+- [ ] Fresh file stamps `user_version = 1`, opens as current.
+- [ ] A file stamped `1975011655` opens, restamps to 1, keeps every row; second open takes the current lane.
+- [ ] `SchemaTooNew` and `SchemaUnsupported` refuse: schema dump, row count, watermark, stamp unchanged after refusal; no aside, no new file. One byte-hash variant on a checkpointed, sidecar-free fixture.
+- [ ] Legacy-below-minimum ordering: with a test-local metadata view where minimum > 1 (drive the classification helper directly with injected constants — classification must be a pure function of `(stamped, minimum, current)` for exactly this reason), a legacy-fingerprint stamp classifies as REFUSE and no restamp happens.
+- [ ] A.5 restamp-failure test.
+- [ ] Synthetic chain through `runMigration` (1→3, two SQL steps, the second using the full A.2 rebuild sequence on a real table): backup exists, is a valid db, contains pre-migration rows; `user_version` lands on 3; rows survived; the rebuilt table's CREATE text equals the injected target text.
+- [ ] Referenced-parent rebuild: a synthetic step rebuilds `domains` (referenced by `query_log`); after the migration, `query_log`'s stored FK text still says `REFERENCES domains(id)` (not `domains_old`), `PRAGMA foreign_key_check` is empty, and both pragmas read their defaults (`foreign_keys` per `applyPragmas`, `legacy_alter_table` off) after success AND after a forced failure.
+- [ ] Mid-chain failure (step 2's SQL errors): canonical file logically unchanged (still version 1, rows intact), this run's backup deleted, an older backup preserved, `error.MigrationFailed`.
+- [ ] `legacy_alter_table` pragma is OFF after both success and failure paths.
+- [ ] Post-commit failure branch, driven through `openVersioned` with an injected synthetic plan (not by calling `runMigration` directly): force the pragma restore to fail after a successful COMMIT (fault seam) and assert: the file is at the target version with the migrated schema, the backup remains, the connection is closed exactly once (by the open path), that startup refuses with `error.MigrationFailed`, and the NEXT `openVersioned` under the same plan succeeds through the current-version lane.
+- [ ] Backup retention: two successful synthetic migrations leave exactly one `pre-migrate-*`, the newer (step-4 authority, exact name). A directory seeded with an older epoch, a newest epoch, and a `-2` suffix tied at the newest epoch has a plain successful open delete only the older epoch — both max-epoch ties survive; an unparseable `pre-migrate-*` name survives untouched.
+- [ ] Backup consistency: a row committed but not checkpointed (WAL-only) is present in the backup.
+- [ ] `PRAGMA user_version` transactionality: set inside a transaction, ROLLBACK, original value observed.
+- [ ] Oracle: fresh==fresh true; every A.6 negative test false; a `runMigration`-migrated file vs a fresh file at the target schema true.
+- [ ] Grep scoped to `src/` and `tools/`: the `fingerprint_mismatch` identifier and the `schema-changed` aside-tag string are gone from active code (docs, specs, and changelog legitimately keep the words — the downgrade recovery text names the aside). Both suites green.
+
+---
+
+## Session B: cut gate inversion + fixture proof
+
+### B.1 Fixtures
+
+- `src/storage/testdata/querylog-v1-schema.sql` — the version-1 DDL frozen verbatim (today's `querylog_schema.ddl` text; the stamp is NOT part of it — the loader applies `PRAGMA user_version = 1`).
+- `src/storage/testdata/querylog-v1-data.sql` — representative COHERENT content: query_log rows covering every `route_kind` and the NULL variants (qtype, cache_hit, response_time_us, upstream, forward_zone), matching `domains` rows, a non-default `available_since`, and `bucket_*` projection rows consistent with the raw rows. A fixture-validity test loads it and runs the projection-coherence oracle BEFORE any migration, so an incoherent fixture fails on its own.
+- Immutable once shipped (header comment). From here on, every supported logical version in `[minimum_supported_version, current_version]` has a fixture pair — the current version's pair is the next migration's starting fixture, and an explicit break ships the new baseline pair.
+
+The **fixture proof tests** (appended to `querylog_migrations.zig` by Session B, sequenced after A):
+
+1. For EVERY starting version in `[minimum_supported_version, current_version)`: load that version's fixture pair, stamp it, run the real production chain, assert `schemaEquivalent` against a fresh-`ddl` db, every row survived, `available_since` preserved, projection coherence holds. Empty today; load-bearing without edits the day the chain grows.
+2. The CURRENT version's fixture pair, stamped `current_version`, opens on the current lane, is `schemaEquivalent` to a fresh-`ddl` db, and passes projection coherence — the pair whose existence Gate 2 requires is thereby proven coherent, since the `[minimum, current)` loop never exercises it.
+3. The legacy-stamp variant: a v1-fixture file stamped `1975011655` — while `minimum_supported_version == 1` it opens, restamps, and passes the same assertions as (2); the test is written against the classification helper's injected constants so that when a future break raises the minimum above 1, its companion assertion (legacy stamp + minimum > 1 REFUSES with `error.SchemaUnsupported`, file untouched) is already in the suite.
+
+### B.2 The gate in tools/cut.zig
+
+`cut` imports `querylog_versions` (pure, no SQLite — the link contract is why A.1 is separate). Two INDEPENDENT gates replace the disclose-a-reset gate. Let `prev_version` be the previous tag's `current_version` (parse `git show <tag>:src/storage/querylog_versions.zig` with the existing simple-extraction style; a tag predating the module means 1).
+
+**Gate 1 — schema text.** Fingerprint the previous tag's DDL text vs the tree's. If changed, require ONE of:
+- **Migration lane:** `current_version > prev_version` AND `prev_version >= minimum_supported_version` (the previous release's files are actually reachable — an explicit break can never wear this lane) AND the chain covers `[prev_version, current_version)` (with contiguous per-step files, that is `step_sql.len == current_version - minimum_supported_version` plus the fixture/file checks of Gate 2).
+- **Explicit-break lane:** `current_version > prev_version` AND `minimum_supported_version == current_version` AND the changelog section contains BOTH "resets your query history" AND a `### Restoring your query history` heading with a non-empty body.
+- Neither: FAIL.
+
+**Gate 2 — migration metadata.** Runs INDEPENDENTLY of Gate 1 (catches data-only migrations and prefix edits when the DDL is unchanged):
+- Every `src/storage/migrations/v<from>.sql` present at the previous tag: byte-identical in the tree; missing: FAIL.
+- Every `src/storage/testdata/querylog-v*-{schema,data}.sql` present at the previous tag: byte-identical; missing: FAIL.
+- A fixture pair exists for every version in `[minimum_supported_version, current_version]`: else FAIL.
+- `current_version < prev_version`: FAIL (never regresses).
+- `current_version > prev_version` with neither a new step file nor a break (`minimum == current`): FAIL.
+- `current_version > prev_version` via new step(s) — REGARDLESS of whether the DDL fingerprint moved (data-only migrations included): the changelog section must contain "migrates your query log in place"; else FAIL.
+- Let `prev_minimum` be the previous tag's `minimum_supported_version` (module absent at tag: 1). `minimum_supported_version < prev_minimum`: FAIL. `minimum_supported_version > prev_minimum` is ONLY acceptable as the full explicit break — `minimum == current` AND `current_version > prev_version` AND the break-lane changelog requirements — REGARDLESS of the DDL fingerprint; any other raise: FAIL (a release must never silently drop supported schemas).
+- The tree's `legacy_fingerprint` is not the literal `1975011655`: FAIL (the legacy anchor is frozen forever; editing it strands unupgraded 0.0.12/0.0.13 files).
+
+### B.3 Acceptance criteria
+
+- [ ] Gate unit tests (pure functions over injected inputs, house style): unchanged schema + unchanged metadata passes; migration lane passes; explicit-break lane passes; changed schema with neither FAILS; break metadata (`minimum == current`) presented with the migration phrase FAILS Gate 1's migration lane; version bump with short chain FAILS; edited shipped step FAILS despite a version append; edited fixture FAILS; deleted step file FAILS; missing target-version fixture pair FAILS; version regression FAILS; version bump with no step and no break FAILS; data-only step (unchanged DDL) without the migration phrase FAILS; minimum regression FAILS; minimum raised without the full break FAILS (unchanged DDL variant included); edited `legacy_fingerprint` FAILS; previous tag without `querylog_versions.zig` maps to `prev_version == 1` and `prev_minimum == 1`.
+- [ ] Fixture-validity test and fixture proof loop pass in the plain suite.
+- [ ] `zig build cut` compiles; both suites green.
+
+---
+
+## Session C: docs (after A)
+
+- `docs/how-to/troubleshoot.md`: new section "The server refuses to start over querylog.db" — `SchemaTooNew` (downgraded binary: return to the newer release, or restore the matching `pre-migrate` backup), `SchemaUnsupported` (file predates 0.0.12 or is foreign: not migratable; how to set it aside by hand if starting empty is acceptable), `MigrationFailed`/`MigrationBackupFailed` (the server never starts empty on its own; before the migration committed the file is untouched, and in the rare committed-but-unclean case the log says the migration DID complete, the backup is kept, and the next start simply proceeds).
+- `docs/reference/` page on the query-log lifecycle: version stamp, in-place migration, one kept backup, the honest downgrade contract (downgrading to 0.0.13 or older RESETS the log — those binaries predate this contract; migration-aware binaries refuse cleanly), corruption as the only automatic recreate, the explicit-break contract (versioned, refused at startup, changelog carries restore instructions).
+- Update the documents that still state the old contract: `PLAN.md`, `docs/explanation/architecture.md`, `specs/release-cut.md` — surgical edits to the stale sentences only.
+
+Acceptance: prose accurate against A/B behavior, unwrapped lines, both suites still green.
+
+---
+
+## Module Layout
+
+- `src/storage/querylog_versions.zig` — NEW: pure version/step metadata (cut-importable, no hooks by design).
+- `src/storage/querylog_migrations.zig` — NEW: `migrateSteps`, `runMigration`, `schemaEquivalent`, fixture proof tests.
+- `src/storage/migrations/` — one immutable SQL file per shipped step. NOT created this milestone (empty chain; git carries no empty directory) — the first real step creates it.
+- `src/storage/querylog_schema.zig` — open-path rework, stamp change, lane deletions, every-open retention.
+- `src/storage/testdata/querylog-v1-schema.sql`, `querylog-v1-data.sql` — NEW frozen fixtures.
+- `src/storage/querylog_fixtures.zig` — NEW (Session B, as built): fixture loading and the survival oracle — full-content comparison against a pristine copy, each value encoded type-tag + byte-length + bytes so the comparison is injective (review round 2026-08-28).
+- `tools/cut.zig` — two-gate rework.
+- Session C's doc files.
+
+## File Ownership
+
+A: both new storage modules, `migrations/` dir, `querylog_schema.zig`, callers touched by lane deletion. B (after A): `tools/cut.zig`, `testdata/`, appends tests to `querylog_migrations.zig`, and makes the projection-coherence checker in `queries_repo.zig` `pub` (export-only edit — the checker is currently private to that file, which no session otherwise owns; B's fixture tests need it). C (after A): docs, `PLAN.md`, `specs/release-cut.md`. Orchestrator: CHANGELOG.md, spec sync.
+
+A also owns the fault-injection seam addition in `src/storage/db.zig` (A.5).
+
+## Changelog requirement (orchestrator)
+
+This milestone's own changelog entry must disclose the one hazard neither gate can see: opening querylog.db under this release restamps it from the legacy fingerprint to version 1, so a LATER downgrade to 0.0.13 or older treats the numeric stamp as a fingerprint mismatch, renames the file to a `.schema-changed-<epoch>` aside, and starts an empty log. The restamp itself creates NO backup, so the accurate recovery is: return to a migration-aware release; stop the server; move the empty downgrade-created `querylog.db` out of the way AND delete its `querylog.db-wal`/`querylog.db-shm` sidecars (replaying the empty file's sidecars into the restored history would corrupt it — the recreate code documents this); move the downgrade-created `.schema-changed-<epoch>` aside back to `querylog.db`; start. The entry states the hazard and exactly that procedure.
+
+## Acceptance Criteria (Milestone Complete)
+
+- [ ] No code path recreates or sets aside a healthy querylog.db (grep proves the lane gone).
+- [ ] A 0.0.13-created file (v1 schema + `1975011655` stamp) opens under the new binary with every row intact.
+- [ ] Refusals and pre-commit migration failures leave the file logically untouched; a post-commit `MigrationFailed` leaves it successfully migrated to `target` (backup kept) and only refuses that one startup; the restamp is this milestone's only real mutation and its failure refuses without loss.
+- [ ] The cut gate refuses: a schema change with neither lane, any edit to shipped steps or fixtures, a data-only migration without disclosure, and an explicit break without versioning + restore instructions.
+- [ ] Both suites green, fmt clean.
+
+## Anti-Requirements
+
+- NO migration steps for pre-0.0.12 schemas (refusal with instructions is the contract).
+- NO real chain step this milestone; synthetic chains live in tests only.
+- NO migration hooks — steps are SQL files, period; a future need amends the design in its own spec.
+- NO generic column-intersection salvage.
+- NO `ALTER TABLE ADD/RENAME COLUMN` on kept tables in future steps (rebuild rule; recorded in doc comments, machine-enforced only via the oracle's exact-text layer).
+- NO admin UI/API surface for migrations; startup log lines are the interface.
+- NO config knob for backup retention.
+- NO change to config.db handling.

specs/release-cut.md

@@ -57,7 +57,9 @@ Pure functions unit-tested: semver validation (accept/reject table incl. leading
 
 ## Addendum: the schema gate (post-0.0.9)
 
-0.0.9 changed the `query_log` DDL and its announcement said nothing about it. `querylog.db` is never migrated: the server stamps `PRAGMA user_version` with a CRC32 of the DDL text, and on a mismatch it renames the file aside and creates an empty one, so the first start after such a release destroys the operator's query history. Nothing in the cut noticed, because nothing in the cut had ever read the schema.
+> Superseded by milestone 38. The addendum below records the gate as it was first built, when `querylog.db` was never migrated. The server now versions and migrates that file in place (`docs/reference/query-log-lifecycle.md`), and the single disclose-a-reset check described here was replaced by the two independent gates of `specs/milestone-38.md` §B.2.
+
+0.0.9 changed the `query_log` DDL and its announcement said nothing about it. At the time `querylog.db` was never migrated: the server stamped `PRAGMA user_version` with a CRC32 of the DDL text, and on a mismatch it renamed the file aside and created an empty one, so the first start after such a release destroyed the operator's query history. Nothing in the cut noticed, because nothing in the cut had ever read the schema.
 
 `schema-gate` is a read-only preflight check beside the others. It compares releases, not commits:
 

specs/ui-redesign.md

@@ -54,14 +54,14 @@ One question, answered over a period the reader chooses: what did the resolver d
 
 Top to bottom, edge to edge:
 
-1. **Four stat tiles**, neutral chrome throughout — no coloured accents; emphasis is typographic. Queries, Blocked (count and rate), Clients, Average response. Each tile carries the way into the rows behind its number: Queries and Blocked open Activity for exactly the bounds the stats response returned, Clients opens the clients page, and Average response has nothing to open.
+1. **Four stat tiles**, neutral chrome throughout — no coloured accents; emphasis is typographic. Queries, Blocked (count and rate), Clients, Average response. Each tile carries the way into the rows behind its number: Queries and Blocked open Activity for exactly the bounds the overview response returned, Clients opens the clients page, and Average response has nothing to open.
 2. **Queries over time** — the existing query-volume timeline, split blocked/cached/other, full width.
 3. **Client activity over time** — one stacked series per named client plus "other", on the same bucket alignment as the timeline so the two charts share an x-axis. A client registered under a name is labelled by it, with the same precedence the query tables apply and the address kept as the title; colour keys on the address, so naming a client never repaints its series.
 4. **Query types** and **Upstream servers** — two donuts, side by side above 1280px and stacked below, with the ring and its legend centred in the panel while stacked and left-anchored once they are a pair. Types are labelled by the admin's own `qtypeName()`; routes by route-kind labels and by the answering resolver or zone. Each donut's SVG is decoration (`aria-hidden`, `focusable="false"`); a visible legend and a visually hidden table are the accessible surface. An empty window says "No queries in this period." rather than drawing nothing.
 
 Colours key on semantic identity — the qtype value, the client string, the `(route, source)` pair — so a rank change between two polls never repaints an entry. Charts stay lightweight SVG; no charting dependency.
 
-**Window coherence, five requests.** Totals, timeseries, clients, types and routes are separate calls, and the page holds one window identified by `(period, since, until, coverage.available_since)` — the watermark joins the identity because retention advancing mid-page changes what the same span can answer for. A response is a member only if all four fields match. Rendering is per panel: a member renders, a panel still in flight shows its own loading state, a panel whose request failed shows its own error and Retry, and the members keep rendering throughout — a failed donut never blanks the charts. A response behind the window is refetched once per endpoint-keyed episode and, if it stays behind, that panel alone shows an error. This is window coherence, not data-snapshot coherence: live inserts between requests may shift counts slightly between panels, and that is accepted. One coverage notice for the page, from the window's watermark.
+**One request, one snapshot (superseded 2026-08-27 by milestone 36; the paragraph below replaces the original five-request window-coherence design).** The page makes one call, `GET /api/overview?period=…`, whose body carries totals, timeseries, clients, types, routes and coverage from a single read transaction — data-snapshot coherence, so the panels cannot disagree and no reconciliation layer exists. Loading and error are page-level: one loading surface, one error with Retry for the whole Overview. The per-panel shells, layout, copy and accessibility surfaces are unchanged. One coverage notice for the page, from the response's watermark. A `keepPreviousData` body whose own `period` is not the selected one keeps the page in loading.
 
 **The shell.** The header carries no protection display at all. The Pause/Resume control sits at the foot of the sidebar, above the version label, in both the desktop rail and the mobile drawer; it is the only global runtime action, and it belongs to the resolver rather than to any page. It still appears beside the detail of a query that was blocked. The control states a pause with itself — "Paused until 14:05", or "Paused" when the pause has no end — because "Resume" names an action without naming the state it would end, and with the indicator and the status rows both gone the sidebar is the only place a page other than Diagnostics can carry that fact. An active resolver gets no line; the button says Pause, which is the whole message. The line and the health strip read one `protection` condition through one clock format, so they cannot disagree. The Diagnostics navigation item carries a badge: the open-episode count, or a neutral "!" when the rollup is degraded with nothing open and when the latest health poll failed — an unknown must never read as healthy. It is hidden only when health data exists, the latest poll succeeded, and the rollup is ok with nothing open.
 
@@ -168,7 +168,7 @@ No response payloads, answer RR sets, EDNS data or packet bytes are stored. The
 
 Privacy transforms apply to every new domain-bearing field, not only `domain`: with `hide_domains` on, matched names, CNAME targets and safe-search targets hide consistently.
 
-A one-row `querylog_meta (created_at INTEGER NOT NULL)` table lets the stats and query APIs return a conservative `available_since`, which distinguishes "zero queries" from "history does not exist".
+A one-row `querylog_meta (created_at INTEGER NOT NULL)` table lets the overview and query APIs return a conservative `available_since`, which distinguishes "zero queries" from "history does not exist".
 
 ### Historical query detail
 
@@ -208,9 +208,9 @@ Database mode uses the same information architecture with real edit actions, plu
 
 `GET /api/queries` keeps keyset pagination and its filters; rows gain `rcode`, `route_kind`, `policy_action` and the short policy reason the table needs, and the body gains `coverage: {complete, available_since}`. `GET /api/queries/{id}` returns nested `request` / `policy` / `route` / `response` provenance. `GET /api/queries/live` sends the same object without `id`.
 
-`GET /api/stats` and `/api/stats/timeseries` add `complete` and `available_since`.
+**Superseded by milestone 36 (2026-08-27).** This section originally specified five per-panel endpoints — `GET /api/stats`, `/api/stats/timeseries`, `/api/stats/types`, `/api/stats/routes` and `/api/stats/clients`. Five requests could promise a shared window but never a shared snapshot, and each one scanned every raw row in it. They are replaced by a single `GET /api/overview?period=1h|24h|7d|30d`, which returns `{period, since, until, bucket_seconds, totals:{queries, blocked, clients, avg_response_time_us}, buckets:[{ts, queries, blocked, cached}], clients:[{client, buckets}], other, types:[{qtype, count}], routes:[{route, source, count}], coverage:{complete, available_since}}` — every field with the semantics the five bodies gave it, over one deferred SQLite read transaction, so the breakdowns and the coverage watermark describe one database state. The 24h, 7d and 30d windows are served from 30-minute projection tables maintained transactionally beside the raw rows; the 1h window takes one raw scan. Per-period response caching keyed on `(window.until, PRAGMA data_version)` lives in the web layer.
 
-**Three period aggregations (added 2026-08-22)** to feed the new Overview panels, all taking the same `period` parameter and reporting over the same aligned window, and all reading their rows and their coverage watermark inside one deferred SQLite read transaction. `GET /api/stats/types` → `{period, since, until, coverage, types:[{qtype, count}]}`, the numeric type only — naming types stays the admin's job, and a second table in the server would drift out of agreement with it — with the rows that recorded no type kept as their own `null` group. `GET /api/stats/routes` → `{period, since, until, coverage, routes:[{route, source, count}]}`, grouping `upstream` rows by the answering resolver and `forward_zone` rows by the zone, with blocked, cache, local and rejected carrying no source. `GET /api/stats/clients` → `{period, since, until, bucket_seconds, coverage, clients:[{client, buckets}], other}`, bucketed exactly as `/api/stats/timeseries`, the eight busiest clients named and everything else summed into `other`, which is always present and always bucket-count-sized. No new writers and no new state: all three are pure reads over the query log's provenance columns.
+The panel semantics the five endpoints defined all carry over unchanged: types are the numeric type only — naming types stays the admin's job, and a second table in the server would drift out of agreement with it — with the rows that recorded no type kept as their own `null` group; routes group `upstream` rows by the answering resolver and `forward_zone` rows by the zone, with blocked, cache, local and rejected carrying no source; clients name the eight busiest and sum everything else into `other`, which is always present and always bucket-count-sized.
 
 Existing mutation endpoints stay specific. Diagnostics introduces no generic "perform remediation" endpoint; it invokes the existing blocklist-refresh and certificate-reload operations.
 

src/app.zig

@@ -58,6 +58,7 @@ const model = @import("config/model.zig");
 const pause = @import("server/pause.zig");
 const queries_repo = @import("storage/repositories/queries_repo.zig");
 const query_sink = @import("server/query_sink.zig");
+const querylog_migrations = @import("storage/querylog_migrations.zig");
 const querylog_schema = @import("storage/querylog_schema.zig");
 const rate_limiter = @import("server/rate_limiter.zig");
 const reconcile = @import("config/reconcile.zig");
@@ -817,6 +818,9 @@ fn serve(r: cli.Runner, args: cli.RunArgs) !u8 {
     // Same argument as the live hash: a settings PUT may have installed an
     // owned generation, and this runs after `group.cancel`.
     defer web_state.proxies.deinit(gpa);
+    // The Overview response cache owns its bodies from `gpa`. Same argument
+    // again: no web task can still be reading a slot once the group is cancelled.
+    defer web_state.overview_cache.deinit(gpa);
     if (cfg.web.enabled) web_state = .{
         .gpa = gpa,
         .web = cfg.web,
@@ -1313,9 +1317,9 @@ test "the recreated detail names the aside and the new coverage start" {
     var buf: [events.Store.max_detail_len]u8 = undefined;
 
     try std.testing.expectEqualStrings(
-        "previous file kept as 'querylog.db.schema-changed-1700000000'; " ++
+        "previous file kept as 'querylog.db.quick-check-failed-1700000000'; " ++
             "query history is available from 1700000001",
-        recreatedDetail(&buf, "querylog.db.schema-changed-1700000000", 1700000001),
+        recreatedDetail(&buf, "querylog.db.quick-check-failed-1700000000", 1700000001),
     );
 
     // A fresh file that will not answer is a separate failure; the line still
@@ -1434,7 +1438,7 @@ const m29_ddl: [:0]const u8 =
     \\VALUES (1, unixepoch(), unixepoch() + 1);
 ;
 
-test "an m29 query log is set aside and recreated without the upstream-history tables" {
+test "an m29 query log refuses the startup and is left exactly as it is" {
     var threaded: std.Io.Threaded = .init(testing.allocator, .{});
     defer threaded.deinit();
     const io = threaded.io();
@@ -1445,10 +1449,6 @@ test "an m29 query log is set aside and recreated without the upstream-history t
     var path_buf: [256]u8 = undefined;
     const path = try std.fmt.bufPrintZ(&path_buf, ".zig-cache/tmp/{s}/querylog.db", .{tmp.sub_path});
 
-    var fx: events_fixture.Fixture = .{};
-    try fx.init(io, 1000);
-    defer fx.deinit();
-
     // The fixture is only worth anything while it is still a *different*
     // schema from this build's, and one that carries the deleted tables.
     try testing.expect(!std.mem.eql(u8, m29_ddl, querylog_schema.ddl));
@@ -1458,9 +1458,8 @@ test "an m29 query log is set aside and recreated without the upstream-history t
     // edit to the literal cannot satisfy by changing what it is compared to.
     try testing.expectEqual(m29_fingerprint, @as(i32, @bitCast(std.hash.Crc32.hash(m29_ddl))));
 
-    // A healthy m29 file, stamped with the fingerprint m29's own DDL produced
+    // A healthy m29 file, stamped with the fingerprint m29's own DDL produced.
-    // and backdated so its coverage promise is visibly the older one.
+    {
-    const m29_coverage = blk: {
         var m29 = try db.Db.open(path, .{ .mode = .read_write_create });
         defer m29.close();
         try db.applyPragmas(&m29, .{});
@@ -1478,43 +1477,47 @@ test "an m29 query log is set aside and recreated without the upstream-history t
             "PRAGMA user_version = {d};",
             .{m29_fingerprint},
         ));
-        break :blk try m29.queryInt("SELECT available_since FROM querylog_meta");
-    };
-    try testing.expectEqual(m29_available_since, m29_coverage);
-
-    var opened = try querylog_schema.open(io, std.Io.Dir.cwd(), path);
-    defer opened.database.close();
-
-    // Set aside under the name that says the file was healthy and this build
-    // moved, and still on disk for an operator who wants it.
-    try testing.expectEqual(querylog_schema.RecreateReason.fingerprint_mismatch, opened.recreated.?);
-    try testing.expect(std.mem.indexOf(u8, opened.aside(), ".schema-changed-") != null);
-    try tmp.dir.access(io, std.fs.path.basename(opened.aside()), .{});
-
-    // The two tables are gone from the file this process will write to.
-    for ([_][]const u8{ "upstream_targets", "upstream_minute", "idx_upstream_minute_ts" }) |name| {
-        var stmt = try opened.database.prepare("SELECT count(*) FROM sqlite_schema WHERE name = ?1");
-        defer stmt.deinit();
-        try stmt.bindText(1, name);
-        try testing.expect(try stmt.step());
-        try testing.expectEqual(@as(i64, 0), stmt.columnInt(0));
     }
 
-    // Coverage restarts: the new file does not inherit the replaced one's
+    // m29 predates the version stamp entirely: its `user_version` is a CRC of a
-    // promise about what it can answer. Strictly newer, not merely not-older —
+    // schema no migration chain starts from, so the only honest answer is to
-    // a recreation that copied the watermark across would pass the weaker test.
+    // refuse and say so. The pre-0.0.12 contract — set it aside and start empty
-    const coverage = try queries_repo.availableSince(&opened.database);
+    // — is gone.
-    try testing.expect(coverage > m29_coverage);
+    querylog_migrations.expected_failures.begin();
+    defer querylog_migrations.expected_failures.end();
+    try testing.expectError(
+        error.SchemaUnsupported,
+        querylog_schema.open(io, std.Io.Dir.cwd(), path),
+    );
 
-    reportQuerylogRecreated(&fx.store, io, 2000, &opened, &opened.database);
+    // Nothing was renamed, nothing was created, and the file still answers for
-    try testing.expectEqualStrings("query_log.recreated", try fx.text("SELECT code FROM operational_events"));
+    // itself: the operator can downgrade and keep the history.
-    try testing.expectEqualStrings(
+    var entries: usize = 0;
-        "fingerprint_mismatch",
+    var it = tmp.dir.iterate();
-        try fx.text("SELECT subject_key FROM operational_events"),
+    while (try it.next(io)) |entry| {
+        try testing.expect(std.mem.startsWith(u8, entry.name, "querylog.db"));
+        try testing.expect(std.mem.indexOfScalar(u8, entry.name[10..], '.') == null);
+        entries += 1;
+    }
+    try testing.expect(entries >= 1);
+
+    var reopened = try db.Db.open(path, .{ .mode = .read_write_existing });
+    defer reopened.close();
+    try testing.expectEqual(
+        @as(i64, m29_fingerprint),
+        try reopened.queryInt("PRAGMA user_version"),
+    );
+    try testing.expectEqual(
+        m29_available_since,
+        try reopened.queryInt("SELECT available_since FROM querylog_meta"),
+    );
+    try testing.expectEqual(
+        @as(i64, 1),
+        try reopened.queryInt("SELECT count(*) FROM upstream_targets"),
     );
 }
 
-test "a fingerprint recreate files a resolved event naming the real aside and watermark" {
+test "a recreate files a resolved event naming the real aside and watermark" {
     var threaded: std.Io.Threaded = .init(testing.allocator, .{});
     defer threaded.deinit();
     const io = threaded.io();
@@ -1536,27 +1539,17 @@ test "a fingerprint recreate files a resolved event naming the real aside and wa
     created.database.close();
     try testing.expectEqual(@as(i64, 0), try fx.count("SELECT count(*) FROM operational_events"));
 
-    // A healthy file this build's DDL no longer matches, which is what an
+    // Real damage: corruption is the only thing that recreates now.
-    // upgrade that edits the schema produces.
+    try tmp.dir.writeFile(io, .{ .sub_path = "querylog.db", .data = "not a database at all" });
-    {
-        var stamped = try db.Db.open(path, .{ .mode = .read_write_existing });
-        defer stamped.close();
-        var sql_buf: [64]u8 = undefined;
-        try stamped.exec(try std.fmt.bufPrintZ(
-            &sql_buf,
-            "PRAGMA user_version = {d};",
-            .{querylog_schema.fingerprint +% 1},
-        ));
-    }
 
     var recreated = try querylog_schema.open(io, std.Io.Dir.cwd(), path);
     defer recreated.database.close();
-    try testing.expectEqual(querylog_schema.RecreateReason.fingerprint_mismatch, recreated.recreated.?);
+    try testing.expectEqual(querylog_schema.RecreateReason.not_a_database, recreated.recreated.?);
 
     reportQuerylogRecreated(&fx.store, io, 2000, &recreated, &recreated.database);
 
     try testing.expectEqualStrings("query_log.recreated", try fx.text("SELECT code FROM operational_events"));
-    try testing.expectEqualStrings("fingerprint_mismatch", try fx.text("SELECT subject_key FROM operational_events"));
+    try testing.expectEqualStrings("not_a_database", try fx.text("SELECT subject_key FROM operational_events"));
     try testing.expectEqualStrings("warning", try fx.text("SELECT severity FROM operational_events"));
     // One-shot: already over when it is filed, so it never becomes an open
     // episode `/api/health` counts.
@@ -1609,18 +1602,17 @@ test "a recreate under a long data directory keeps the watermark and a usable na
 
     {
         var created = try querylog_schema.open(io, std.Io.Dir.cwd(), path);
-        defer created.database.close();
+        created.database.close();
-        var sql_buf: [64]u8 = undefined;
+    }
-        try created.database.exec(try std.fmt.bufPrintZ(
+    {
-            &sql_buf,
+        var deep_dir = try tmp.dir.openDir(io, nested, .{});
-            "PRAGMA user_version = {d};",
+        defer deep_dir.close(io);
-            .{querylog_schema.fingerprint +% 1},
+        try deep_dir.writeFile(io, .{ .sub_path = "querylog.db", .data = "not a database at all" });
-        ));
     }
 
     var recreated = try querylog_schema.open(io, std.Io.Dir.cwd(), path);
     defer recreated.database.close();
-    try testing.expectEqual(querylog_schema.RecreateReason.fingerprint_mismatch, recreated.recreated.?);
+    try testing.expectEqual(querylog_schema.RecreateReason.not_a_database, recreated.recreated.?);
     const line_overhead = "previous file kept as ''; query history is available from ".len;
     try testing.expect(recreated.aside().len + line_overhead > events.Store.max_detail_len);
 
@@ -1679,6 +1671,13 @@ test "run maps a rejected configuration to exit 2 and everything else to exit 1"
     try std.testing.expectEqual(cli.exit_check, failureExitCode(error.ParseZon));
     try std.testing.expectEqual(cli.exit_check, failureExitCode(error.NoUsableUpstreams));
     try std.testing.expectEqual(cli.exit_check, failureExitCode(error.BadCertificate));
+    // The query-log schema refusals: `run` is the only command that reaches
+    // them, and exit 1 would put a deliberate refusal under the unit's
+    // `Restart=on-failure`.
+    try std.testing.expectEqual(cli.exit_check, failureExitCode(error.SchemaTooNew));
+    try std.testing.expectEqual(cli.exit_check, failureExitCode(error.SchemaUnsupported));
+    try std.testing.expectEqual(cli.exit_check, failureExitCode(error.MigrationFailed));
+    try std.testing.expectEqual(cli.exit_check, failureExitCode(error.MigrationBackupFailed));
     try std.testing.expectEqual(cli.exit_runtime, failureExitCode(error.AccessDenied));
     try std.testing.expectEqual(cli.exit_runtime, failureExitCode(error.OutOfMemory));
 }

src/cli.zig

@@ -1012,7 +1012,7 @@ fn probeUpstreams(r: Runner, cfg: model.Config) !usize {
             .priority = server.priority,
             .enabled = true,
             .health = .init,
-            .sem = .{ .permits = slots.len },
+            .admission = .{ .permits = slots.len },
             .reuse_recoveries = &recoveries,
         }};
         var single: pool.Pool = .init(&entries, .{}, timeouts, seed);

src/config/faults.zig

@@ -13,7 +13,7 @@ const validate = @import("validate.zig");
 
 /// `ValidateError` enters as a whole set rather than variant by variant, so a
 /// variant added to the validator cannot silently fall through to exit 1. The
-/// five extras are the configuration faults raised outside the validator: the
+/// first five extras are the configuration faults raised outside the validator: the
 /// ZON reader (`ParseZon`), the file size limit (`ConfigTooLarge`), the managed
 /// file the operator named and this process cannot open
 /// (`ManagedConfigUnreadable`, milestone-20 ruling 2), the composition root's
@@ -26,6 +26,16 @@ const validate = @import("validate.zig");
 /// missing file anywhere else stays a runtime failure. `config/loader.zig` owns
 /// the conversion and the closed set of open errors that qualify.
 ///
+/// The four querylog schema refusals are here for the exit code, not because a
+/// `.zon` file is wrong: `SchemaTooNew` and `SchemaUnsupported` are a deliberate
+/// refusal to touch a `querylog.db` this binary does not understand, and
+/// `MigrationFailed` and `MigrationBackupFailed` are a deliberate refusal to run
+/// on a database whose migration or pre-migration backup did not complete. All
+/// four need an operator, and none of them will resolve on a retry — exit 1 puts
+/// them under systemd's `Restart=on-failure` and restart-loops a server that is
+/// refusing on purpose. The unit's `RestartPreventExitStatus=2 64` is what exit
+/// 2 buys them.
+///
 /// Not here on purpose: `error.DestructiveImport`, which reports what an import
 /// would do to the database rather than the content of a file, and is the one
 /// config-shaped exit 2 `cli` decides for itself.
@@ -35,6 +45,10 @@ const ConfigFault = validate.ValidateError || error{
     ManagedConfigUnreadable,
     NoUsableUpstreams,
     BadCertificate,
+    SchemaTooNew,
+    SchemaUnsupported,
+    MigrationFailed,
+    MigrationBackupFailed,
 };
 
 const faults: []const anyerror = blk: {
@@ -119,6 +133,16 @@ test "the seed-file errors that used to exit 1 from run are configuration faults
     try testing.expect(isConfigFault(error.NoUpstreams));
 }
 
+test "the querylog schema refusals exit 2 so systemd does not restart-loop them" {
+    try testing.expect(isConfigFault(error.SchemaTooNew));
+    try testing.expect(isConfigFault(error.SchemaUnsupported));
+    try testing.expect(isConfigFault(error.MigrationFailed));
+    try testing.expect(isConfigFault(error.MigrationBackupFailed));
+    // The refusals are a closed set. A neighbouring schema error is a corrupt
+    // database, not a refusal, and stays a runtime failure.
+    try testing.expect(!isConfigFault(error.SchemaCorrupt));
+}
+
 test "a runtime failure is not a configuration fault" {
     try testing.expect(!isConfigFault(error.OutOfMemory));
     try testing.expect(!isConfigFault(error.AccessDenied));

src/config/model.zig

@@ -57,9 +57,11 @@ pub const Config = struct {
 pub const Upstream = struct {
     /// Bounds one attempt against one upstream inside the pool's failover loop.
     attempt_timeout_ms: u32 = 2500,
-    /// The forward-zone client's read deadline, and nothing else. It bounds a
+    /// The forward-zone client's whole-exchange budget, and nothing else: one
-    /// different subsystem from the two above (`src/local/forward_client.zig`),
+    /// bound covers the UDP attempt, a TC=1 fallback and the TCP retry
-    /// so no cross-check relates it to them.
+    /// together, not each of them. It bounds a different subsystem from the two
+    /// above (`src/local/forward_client.zig`), so no cross-check relates it to
+    /// them.
     read_timeout_ms: u32 = 3000,
     /// The whole-exchange budget: every failover attempt together, not one of
     /// them. The pool races the entire loop against it.

src/config/validate.zig

@@ -52,6 +52,7 @@ const limits = @import("limits.zig");
 const logger = @import("../storage/logger.zig");
 const regex = @import("../filter/regex.zig");
 const safe_url = @import("../safe_url.zig");
+const pool = @import("../upstream/pool.zig");
 const transport = @import("../upstream/transport.zig");
 
 const Config = model.Config;
@@ -69,6 +70,7 @@ const Prefix = address.Prefix;
 /// like every other resource failure.
 pub const ValidateError = error{
     NoUpstreams,
+    TooManyUpstreams,
     BadUpstreamUrl,
     UpstreamHostNotIpLiteral,
     DuplicateUpstreamUrl,
@@ -357,8 +359,9 @@ fn checkScalars(cfg: Config, diags: *Diagnostics) error{OutOfMemory}!void {
     // The only cross-check that relates two knobs of one subsystem: the pool
     // races one attempt against `attempt` and the whole failover loop against
     // `total`, so an attempt budget above the total one can never be reached.
-    // `read_timeout_ms` belongs to the forward-zone client and is deliberately
+    // `read_timeout_ms` bounds the forward-zone client's whole exchange —
-    // unrelated to both.
+    // UDP attempt, TC=1 fallback and TCP retry under one budget — and is
+    // deliberately unrelated to both.
     if (up.attempt_timeout_ms > up.total_timeout_ms) {
         try diags.add(
             error.BadTimeout,
@@ -823,6 +826,21 @@ fn checkCollections(cfg: Config, diags: *Diagnostics, scratch: Allocator) error{
             .{},
         );
     }
+    // Each enabled upstream becomes one pool entry, and the failover loop
+    // tracks the entries it has spent in a fixed bitset of `Pool.max_entries`
+    // bits. Without this check a config past that bound reaches an assert and
+    // panics at startup, which is the wrong way to tell an operator that a
+    // number is too large. Disabled upstreams are not counted: they never
+    // become entries.
+    if (enabled_upstreams > pool.Pool.max_entries) {
+        try diags.add(
+            error.TooManyUpstreams,
+            "upstreams",
+            .{},
+            "{d} upstreams are enabled; nxdns is built for at most {d}",
+            .{ enabled_upstreams, pool.Pool.max_entries },
+        );
+    }
 
     var client_ips: IndexSet = .empty;
     for (cfg.clients, 0..) |client, i| {
@@ -1323,6 +1341,52 @@ test "error.NoUpstreams when nothing is enabled" {
     try expectProblem(cfg, error.NoUpstreams, "upstreams");
 }
 
+/// `count` distinct enabled upstreams. Generated rather than written out
+/// because the bound this exercises is 64, and a hand-written list that long
+/// would say less than the loop does.
+fn ManyUpstreams(comptime count: usize) type {
+    return struct {
+        const list: [count]model.UpstreamServer = blk: {
+            var built: [count]model.UpstreamServer = undefined;
+            for (&built, 0..) |*server, i| {
+                server.* = .{ .url = std.fmt.comptimePrint("https://u{d}.example/dns-query", .{i}) };
+            }
+            break :blk built;
+        };
+    };
+}
+
+fn manyUpstreams(comptime count: usize) []const model.UpstreamServer {
+    return &ManyUpstreams(count).list;
+}
+
+test "as many enabled upstreams as the pool holds validates cleanly" {
+    var cfg = baseConfig();
+    cfg.upstreams = manyUpstreams(pool.Pool.max_entries);
+    try expectClean(cfg);
+}
+
+test "error.TooManyUpstreams one enabled upstream past the pool's bound" {
+    // The pool asserts this bound, so without the check here a valid-looking
+    // config panics at startup instead of being reported.
+    var cfg = baseConfig();
+    cfg.upstreams = manyUpstreams(pool.Pool.max_entries + 1);
+    try expectProblem(cfg, error.TooManyUpstreams, "upstreams");
+}
+
+test "upstreams past the pool's bound are fine while they are disabled" {
+    // Only enabled upstreams become pool entries, so a long list with a small
+    // enabled subset is not near the bound at all.
+    var cfg = baseConfig();
+    cfg.upstreams = comptime blk: {
+        var list = manyUpstreams(pool.Pool.max_entries + 1)[0 .. pool.Pool.max_entries + 1].*;
+        for (list[1..]) |*server| server.enabled = false;
+        const frozen = list;
+        break :blk &frozen;
+    };
+    try expectClean(cfg);
+}
+
 test "error.BadUpstreamUrl on an unsupported scheme" {
     var cfg = baseConfig();
     cfg.upstreams = &.{.{ .url = "ftp://dns.example/" }};

src/local/forward_client.zig

@@ -109,6 +109,11 @@ pub const ForwardClient = struct {
 
     /// `.udp` resolvers send one datagram and fall back to TCP when the answer
     /// comes back with TC=1. `.tcp` resolvers skip straight to the TCP path.
+    ///
+    /// `read_timeout` bounds the WHOLE exchange, truncation fallback included:
+    /// the instant is computed once here and every blocking step inside runs
+    /// against it, so a truncated UDP answer followed by a stalled TCP retry
+    /// costs one budget rather than two.
     pub fn exchange(
         self: *ForwardClient,
         io: std.Io,
@@ -120,10 +125,22 @@ pub const ForwardClient = struct {
         if (response_buf.len == 0) return error.BufferTooSmall;
 
         self.stats.queries += 1;
-        return self.route(io, query, response_buf) catch |err| {
+        const expiry_at: std.Io.Clock.Timestamp = .fromNow(io, self.read_timeout);
+        // The outcome is deliberately discarded. A forward zone has exactly one
+        // configured resolver, so an expiry here is still that resolver failing
+        // to answer in time: `error.Timeout` is peer evidence, and the
+        // budget/peer distinction is upstream-pool policy.
+        var outcome: transport.RaceOutcome = .completed;
+        return transport.raceUntilTagged(io, expiry_at, &outcome, route, .{
+            self,
+            io,
+            query,
+            response_buf,
+            expiry_at,
+        }) catch |err| {
             switch (transport.group(err)) {
                 .peer_fault, .local_resource => self.stats.failures += 1,
-                .cancellation => {},
+                .cancellation, .budget_exhausted => {},
             }
             return err;
         };
@@ -134,11 +151,12 @@ pub const ForwardClient = struct {
         io: std.Io,
         query: []const u8,
         response_buf: []u8,
+        expiry_at: std.Io.Clock.Timestamp,
     ) transport.ExchangeError![]u8 {
         if (self.resolver.scheme == .udp) {
-            if (try self.exchangeUdp(io, query, response_buf)) |reply| return reply;
+            if (try self.exchangeUdp(io, query, response_buf, expiry_at)) |reply| return reply;
         }
-        return self.exchangeTcp(io, query, response_buf);
+        return self.tcpOnce(io, query, response_buf);
     }
 
     /// `null` means the resolver set TC=1 and the caller must retry over TCP.
@@ -151,6 +169,7 @@ pub const ForwardClient = struct {
         io: std.Io,
         query: []const u8,
         response_buf: []u8,
+        expiry_at: std.Io.Clock.Timestamp,
     ) transport.ExchangeError!?[]u8 {
         const dest = self.destination();
         const local = wildcardFor(dest);
@@ -166,9 +185,10 @@ pub const ForwardClient = struct {
             return transport.mapPhase(err, error.SendFailed);
         };
 
-        // A deadline, not a duration: a discarded foreign datagram restarts the
+        // The exchange-wide instant, not a fresh duration: a discarded foreign
-        // receive, and a duration would hand each retry the full budget again.
+        // datagram restarts the receive, and a duration would hand each retry
-        const deadline = (std.Io.Timeout{ .duration = self.read_timeout }).toDeadline(io);
+        // the full budget again.
+        const deadline: std.Io.Timeout = .{ .deadline = expiry_at };
 
         while (true) {
             const msg = socket.receiveTimeout(io, response_buf, deadline) catch |err| switch (err) {
@@ -205,18 +225,11 @@ pub const ForwardClient = struct {
         }
     }
 
-    /// The read budget bounds the whole TCP exchange through
+    /// Unbounded on its own: `exchange` runs it inside the exchange-wide race,
-    /// `transport.raceWithin`. `ConnectOptions.timeout` is never set: the
+    /// which is what cancels a stalled connect or read. It takes no budget of
-    /// Threaded backend panics on it (Threaded.zig:12076).
+    /// its own, so a truncation fallback does not start a second one.
-    fn exchangeTcp(
+    /// `ConnectOptions.timeout` is never set: the Threaded backend panics on it
-        self: *ForwardClient,
+    /// (Threaded.zig:12076).
-        io: std.Io,
-        query: []const u8,
-        response_buf: []u8,
-    ) transport.ExchangeError![]u8 {
-        return transport.raceWithin(io, self.read_timeout, tcpOnce, .{ self, io, query, response_buf });
-    }
-
     fn tcpOnce(
         self: *ForwardClient,
         io: std.Io,
@@ -307,6 +320,11 @@ fn receiveFailure(stream_reader: *const net.Stream.Reader, err: anyerror) transp
 }
 
 const testing = std.testing;
+const build_options = @import("build_options");
+const name_mod = @import("../dns/name.zig");
+const packet = @import("../dns/packet.zig");
+const question = @import("../dns/question.zig");
+const types = @import("../dns/types.zig");
 
 fn testBuf() [min_frame_buf]u8 {
     return undefined;
@@ -467,3 +485,113 @@ test "a stashed stream error is preferred over the collapsed one" {
         receiveFailure(&stream_reader, error.EndOfStream),
     );
 }
+
+const one_budget_ms = 400;
+/// Late enough in the budget that a second, fresh budget for the TCP leg would
+/// be unmistakable in the elapsed time.
+const truncate_after_ms = 300;
+
+/// Answers the first datagram late in the budget with TC=1, which sends the
+/// client to TCP — where a listener that never accepts leaves it stalled.
+fn truncatingThenStallingResolver(io: std.Io, socket: *const net.Socket) void {
+    var buf: [2048]u8 = undefined;
+    const msg = socket.receive(io, &buf) catch return;
+    const request = packet.parse(msg.data) catch return;
+
+    (std.Io.Clock.Duration{
+        .raw = .fromMilliseconds(truncate_after_ms),
+        .clock = .awake,
+    }).sleep(io) catch return;
+
+    // The question has to be echoed: `transport.validateResponse` runs before
+    // the client reads the TC bit, so a bare header would come back as
+    // `BadResponse` and never reach the TCP fallback this case is about.
+    const q = packet.firstQuestion(request) orelse return;
+    var reply_buf: [512]u8 = undefined;
+    var b = packet.ResponseBuilder.init(&reply_buf, request.header, q) catch return;
+    const reply = b.finish();
+
+    var parsed = dns_header.parse(reply) catch return;
+    parsed.flags.tc = true;
+    dns_header.encode(parsed, reply[0..types.header_len]);
+    socket.send(io, &msg.from, reply) catch return;
+}
+
+fn testQuery(io: std.Io, buf: []u8) ![]const u8 {
+    var id_bytes: [2]u8 = undefined;
+    io.random(&id_bytes);
+    dns_header.encode(.{
+        .id = std.mem.readInt(u16, &id_bytes, .big),
+        .flags = .{
+            .rcode = .no_error,
+            .z = 0,
+            .ra = false,
+            .rd = true,
+            .tc = false,
+            .aa = false,
+            .opcode = .query,
+            .qr = false,
+        },
+        .qdcount = 1,
+        .ancount = 0,
+        .nscount = 0,
+        .arcount = 0,
+    }, buf[0..types.header_len]);
+
+    var w: std.Io.Writer = .fixed(buf[types.header_len..]);
+    try question.encode(.{
+        .name = try name_mod.fromText("nas.lan"),
+        .qtype = .a,
+        .qclass = .in,
+    }, &w);
+    return buf[0 .. types.header_len + w.buffered().len];
+}
+
+test "one budget covers the udp leg, the TC=1 fallback and the tcp leg" {
+    if (!build_options.integration) return error.SkipZigTest;
+
+    var threaded: std.Io.Threaded = .init(testing.allocator, .{});
+    defer threaded.deinit();
+    const io = threaded.io();
+
+    const bind_address: net.IpAddress = try .parse("127.0.0.1", 0);
+    const socket = try bind_address.bind(io, .{ .mode = .dgram });
+    defer socket.close(io);
+    const port = socket.address.ip4.port;
+
+    // Bound but never accepted: the connect completes out of the kernel's
+    // backlog and the read then waits forever, which is the stall a second
+    // budget would be spent on.
+    const tcp_address: net.IpAddress = try .parse("127.0.0.1", port);
+    var tcp_listener = try tcp_address.listen(io, .{ .reuse_address = true });
+    defer tcp_listener.deinit(io);
+
+    var group: std.Io.Group = .init;
+    defer group.cancel(io);
+    try group.concurrent(io, truncatingThenStallingResolver, .{ io, &socket });
+
+    var url_buf: [64]u8 = undefined;
+    const url = try std.fmt.bufPrint(&url_buf, "udp://127.0.0.1:{d}", .{port});
+
+    var frame_buf: [min_frame_buf]u8 = undefined;
+    var fc: ForwardClient = .init(
+        try validate.parseResolver(url),
+        &frame_buf,
+        .{ .raw = .fromMilliseconds(one_budget_ms), .clock = .awake },
+    );
+
+    var query_buf: [types.header_len + types.max_name_len + 4]u8 = undefined;
+    const query = try testQuery(io, &query_buf);
+    var response_buf: [2048]u8 = undefined;
+
+    const started = std.Io.Clock.awake.now(io);
+    try testing.expectError(error.Timeout, fc.exchange(io, query, &response_buf));
+    const elapsed = started.durationTo(std.Io.Clock.awake.now(io)).nanoseconds;
+
+    // Two budgets would spend 300 ms on the UDP leg and then a fresh 400 ms on
+    // the stalled TCP leg. The bound sits between one budget and that sum, so
+    // the double-budget shape cannot pass.
+    try testing.expect(elapsed < @as(i96, one_budget_ms + truncate_after_ms / 2) * std.time.ns_per_ms);
+    try testing.expectEqual(@as(u64, 1), fc.stats.udp_truncated);
+    try testing.expectEqual(@as(u64, 1), fc.stats.failures);
+}

src/server/handler.zig

@@ -676,7 +676,10 @@ const Context = struct {
         const answer = client.exchange(ctx.io, ctx.query, ctx.response_buf) catch |err| {
             return switch (transport.group(err)) {
                 .cancellation => .drop,
-                .peer_fault, .local_resource => ctx.servFail(),
+                // A budget that ran out is SERVFAIL like any other failure: no
+                // rcode says "I gave up in time". It is not logged per query —
+                // `nxdns_upstream_budget_exhausted_total` is the record.
+                .peer_fault, .local_resource, .budget_exhausted => ctx.servFail(),
             };
         };
 
@@ -737,7 +740,13 @@ const Context = struct {
                 // the client is about to lose the socket anyway; the listener's
                 // own counters record the abandoned datagram.
                 .cancellation => return .drop,
-                .peer_fault, .local_resource => return ctx.servFail(),
+                // A budget that ran out is SERVFAIL like any other failure: no
+                // rcode says "I gave up in time". It is not logged per query —
+                // `nxdns_upstream_budget_exhausted_total` is the record — and
+                // the pool leaves `selected` unchanged, so the row still names
+                // the last attributable endpoint if there was one, and names
+                // none only when no attributable attempt happened.
+                .peer_fault, .local_resource, .budget_exhausted => return ctx.servFail(),
             };
         };
         bump(&ctx.handler.stats.queries);

src/server/resolver_integration_test.zig

@@ -176,7 +176,7 @@ const EntryStorage = struct {
             .priority = priority,
             .enabled = true,
             .health = .init,
-            .sem = .{ .permits = self.slots.len },
+            .admission = .{ .permits = self.slots.len },
             .reuse_recoveries = &self.recoveries,
         };
     }

src/storage/db.zig

@@ -54,9 +54,24 @@ pub const c = struct {
     pub extern fn sqlite3_column_count(stmt: *c.Stmt) c_int;
     pub extern fn sqlite3_column_type(stmt: *c.Stmt, col: c_int) c_int;
     pub extern fn sqlite3_column_int64(stmt: *c.Stmt, col: c_int) i64;
+    pub extern fn sqlite3_column_double(stmt: *c.Stmt, col: c_int) f64;
     pub extern fn sqlite3_column_text(stmt: *c.Stmt, col: c_int) ?[*]const u8;
     pub extern fn sqlite3_column_bytes(stmt: *c.Stmt, col: c_int) c_int;
+    pub extern fn sqlite3_set_authorizer(db: *Sqlite3, xAuth: ?*const AuthCallback, user_data: ?*anyopaque) c_int;
+    pub extern fn sqlite3_get_autocommit(db: *Sqlite3) c_int;
     pub extern fn sqlite3_last_insert_rowid(db: *Sqlite3) i64;
+
+    /// `int (*)(void*, int, const char*, const char*, const char*, const char*)`.
+    /// The four name arguments are NULL for actions that do not use them, which
+    /// `SQLITE_TRANSACTION` is except for its operation name.
+    pub const AuthCallback = fn (
+        user_data: ?*anyopaque,
+        action: c_int,
+        arg1: ?[*:0]const u8,
+        arg2: ?[*:0]const u8,
+        database: ?[*:0]const u8,
+        trigger_or_view: ?[*:0]const u8,
+    ) callconv(.c) c_int;
     pub extern fn sqlite3_changes(db: *Sqlite3) c_int;
     pub extern fn sqlite3_total_changes(db: *Sqlite3) c_int;
 };
@@ -105,6 +120,20 @@ pub const open_flag = struct {
     pub const exrescode: c_int = 0x2000000;
 };
 
+/// The authorizer verdicts and the one action code nxdns denies, from the
+/// vendored `sqlite3.h` (3.53.4). `SQLITE_DENY` fails the *prepare* with
+/// `SQLITE_AUTH`, which is what makes it a real guard: the statement never
+/// runs at all.
+pub const auth = struct {
+    pub const deny: c_int = 1;
+    pub const transaction: c_int = 22;
+    /// `SAVEPOINT`, `RELEASE` and `ROLLBACK TO` report under this code, not
+    /// under `transaction`. A savepoint at the outermost level opens a real
+    /// transaction and `RELEASE` commits it, so a step using one splits the
+    /// migration exactly as a bare `COMMIT` would.
+    pub const savepoint: c_int = 32;
+};
+
 /// Column type codes returned by `sqlite3_column_type`.
 pub const column_type = struct {
     pub const integer: c_int = 1;
@@ -367,6 +396,7 @@ pub const Db = struct {
     /// message is read back through `sqlite3_errmsg`, so there is no
     /// `sqlite3_free` obligation.
     pub fn exec(self: *Db, sql: [:0]const u8) Error!void {
+        if (execFaultTripped(sql)) return error.Internal;
         return check(c.sqlite3_exec(self.handle, sql.ptr, null, null, null));
     }
 
@@ -424,6 +454,38 @@ pub const Db = struct {
         return value;
     }
 
+    /// False while a transaction is open on this connection. The migration
+    /// runner's belt check: a step that somehow ended the runner's transaction
+    /// must not be allowed to look like a success.
+    pub fn inTransaction(self: *Db) bool {
+        return c.sqlite3_get_autocommit(self.handle) == 0;
+    }
+
+    /// Denies every transaction statement — `BEGIN`, `COMMIT`, `ROLLBACK`,
+    /// `SAVEPOINT`, `RELEASE` — until `clearAuthorizer` runs.
+    ///
+    /// `guard` must outlive the installed window: SQLite keeps the pointer.
+    /// Install and clear are a scoped pair; the migration runner clears on
+    /// every exit path, because a leaked authorizer would go on denying the
+    /// ROLLBACK that cleans up after the very statement it rejected.
+    pub fn denyTransactions(self: *Db, guard: *TransactionGuard) Error!void {
+        guard.* = .{};
+        return check(c.sqlite3_set_authorizer(self.handle, transactionAuthorizer, guard));
+    }
+
+    /// Never fails in a way the caller can act on: passing a null callback only
+    /// clears state SQLite already holds. A failure is logged and swallowed so
+    /// this stays usable in `defer`.
+    pub fn clearAuthorizer(self: *Db) void {
+        const rc = c.sqlite3_set_authorizer(self.handle, null, null);
+        if (rc != result.ok) {
+            log.err("sqlite3_set_authorizer(null) returned {s} (code {d})", .{
+                std.mem.span(c.sqlite3_errstr(rc)),
+                rc,
+            });
+        }
+    }
+
     pub fn lastInsertRowid(self: *Db) i64 {
         return c.sqlite3_last_insert_rowid(self.handle);
     }
@@ -442,6 +504,34 @@ pub const Db = struct {
     }
 };
 
+/// Records whether the authorizer installed by `Db.denyTransactions` actually
+/// rejected anything. The rejection reaches the caller as `error.Auth`, which
+/// is indistinguishable from any other authorization failure; this flag is what
+/// lets the migration runner name the real cause.
+pub const TransactionGuard = struct {
+    denied: bool = false,
+};
+
+fn transactionAuthorizer(
+    user_data: ?*anyopaque,
+    action: c_int,
+    arg1: ?[*:0]const u8,
+    arg2: ?[*:0]const u8,
+    database: ?[*:0]const u8,
+    trigger_or_view: ?[*:0]const u8,
+) callconv(.c) c_int {
+    _ = arg2;
+    _ = database;
+    _ = trigger_or_view;
+    if (action != auth.transaction and action != auth.savepoint) return result.ok;
+    const guard: *TransactionGuard = @ptrCast(@alignCast(user_data.?));
+    guard.denied = true;
+    log.warn("migration step attempted a transaction statement: {s}", .{
+        if (arg1) |op| std.mem.span(op) else "(unnamed)",
+    });
+    return auth.deny;
+}
+
 fn openHandle(filename: [:0]const u8, flags: c_int) Error!*c.Sqlite3 {
     var handle: ?*c.Sqlite3 = null;
     const rc = c.sqlite3_open_v2(filename.ptr, &handle, flags, null);
@@ -963,6 +1053,45 @@ pub const read_tx_faults = if (builtin.is_test) struct {
     }
 } else struct {};
 
+/// Fails one chosen `Db.exec` so a test can drive a failure SQLite itself will
+/// not produce on demand. Test builds only, same shape as `read_tx_seam`.
+///
+/// The migration paths this exists for — the legacy restamp and the
+/// post-commit pragma restore — run statements that always succeed against a
+/// healthy file, and their recovery behaviour is the whole point of the
+/// milestone. Matching on the SQL text rather than counting calls keeps a test
+/// naming the statement it means.
+const exec_seam = if (builtin.is_test) struct {
+    var fail_matching: ?[]const u8 = null;
+} else struct {};
+
+fn execFaultTripped(sql: []const u8) bool {
+    if (!builtin.is_test) return false;
+    const needle = exec_seam.fail_matching orelse return false;
+    if (std.mem.indexOf(u8, sql, needle) == null) return false;
+    exec_seam.fail_matching = null;
+    return true;
+}
+
+/// The seam's controls, for tests in this file and in the storage layer.
+pub const exec_faults = if (builtin.is_test) struct {
+    /// Arms the next `Db.exec` whose SQL contains `needle` to fail with
+    /// `error.Internal` before the statement reaches SQLite. One shot: it
+    /// disarms itself when it trips. Pair it with `defer disarm()` so a test
+    /// that never trips the fault cannot leak it into the next one.
+    pub fn failNextMatching(needle: []const u8) void {
+        exec_seam.fail_matching = needle;
+    }
+
+    pub fn disarm() void {
+        exec_seam.fail_matching = null;
+    }
+
+    pub fn armed() bool {
+        return exec_seam.fail_matching != null;
+    }
+} else struct {};
+
 const testing = std.testing;
 
 fn openMemory() Error!Db {
@@ -1479,3 +1608,57 @@ test "a duplicate insert into a UNIQUE column returns error.Constraint" {
     try stmt.bindText(1, "only");
     try testing.expectError(error.Constraint, stmt.step());
 }
+
+test "the transaction authorizer denies transaction statements and clears cleanly" {
+    var db = try openMemory();
+    defer db.close();
+    try db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY);");
+
+    try db.exec("BEGIN IMMEDIATE;");
+    try testing.expect(db.inTransaction());
+
+    var guard: TransactionGuard = .{};
+    try db.denyTransactions(&guard);
+    // Ordinary work still runs: only the transaction statements are refused.
+    try db.exec("INSERT INTO t (id) VALUES (1);");
+    try testing.expect(!guard.denied);
+    try testing.expectError(error.Auth, db.exec("COMMIT;"));
+    try testing.expect(guard.denied);
+    // The deny happens at prepare, so the transaction is still open.
+    try testing.expect(db.inTransaction());
+
+    // SAVEPOINT and its RELEASE report under a different action code, and they
+    // are the same bypass: at the outermost level they are a transaction under
+    // another name, and inside one they can still discard the migration's work.
+    guard.denied = false;
+    try testing.expectError(error.Auth, db.exec("SAVEPOINT half_a_migration;"));
+    try testing.expect(guard.denied);
+    guard.denied = false;
+    try testing.expectError(error.Auth, db.exec("RELEASE half_a_migration;"));
+    try testing.expect(guard.denied);
+    try testing.expect(db.inTransaction());
+
+    db.clearAuthorizer();
+    // The same connection is usable again — a leaked authorizer would strand it
+    // inside the transaction by denying this too.
+    try db.exec("ROLLBACK;");
+    try testing.expect(!db.inTransaction());
+    try testing.expectEqual(@as(i64, 0), try db.queryInt("SELECT count(*) FROM t"));
+}
+
+test "the exec fault seam fires once, on the statement it names" {
+    var db = try openMemory();
+    defer db.close();
+    try db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY);");
+
+    exec_faults.failNextMatching("COMMIT");
+    defer exec_faults.disarm();
+
+    try db.exec("BEGIN IMMEDIATE;");
+    try db.exec("INSERT INTO t (id) VALUES (1);");
+    try testing.expectError(error.Internal, db.exec("COMMIT;"));
+    try testing.expect(!exec_faults.armed());
+    // Disarmed: the retry is a real COMMIT.
+    try db.exec("COMMIT;");
+    try testing.expectEqual(@as(i64, 1), try db.queryInt("SELECT count(*) FROM t"));
+}

src/storage/logger.zig

@@ -30,6 +30,7 @@
 //! `writer_failed`, so the loss is visible rather than silent.
 
 const std = @import("std");
+const Allocator = std.mem.Allocator;
 const builtin = @import("builtin");
 
 const db = @import("db.zig");
@@ -555,13 +556,17 @@ pub const Logger = struct {
     /// group it cancels for exactly that reason.
     ///
     /// `monitor` is the §11.6 gate. Null disables gating.
+    ///
+    /// `gpa` belongs to the `BatchWriter` for that writer's whole life; it
+    /// allocates the projection deltas of one batch and nothing else.
     pub fn runWriter(
         self: *Logger,
         io: std.Io,
+        gpa: Allocator,
         database: *db.Db,
         monitor: ?*disk_monitor.Monitor,
     ) std.Io.Cancelable!void {
-        var writer = queries_repo.BatchWriter.init(database) catch |err| {
+        var writer = queries_repo.BatchWriter.init(gpa, database) catch |err| {
             scope.warn("query logger: preparing the batch statements failed: {s}", .{@errorName(err)});
             // Without a writer there is no consumer, so leaving the queue open
             // would silently swallow every later entry.
@@ -1134,7 +1139,7 @@ test "an entry with every provenance field set survives the queue, toRow, insert
 
     var database = try openLog();
     defer database.close();
-    var writer = try queries_repo.BatchWriter.init(&database);
+    var writer = try queries_repo.BatchWriter.init(testing.allocator, &database);
     defer writer.deinit();
 
     var buf: [4]Entry = undefined;
@@ -1466,6 +1471,7 @@ test "shutdown writes the batch the writer holds and the rest of the queue" {
     var future = try io.concurrent(Logger.runWriter, .{
         &logger,
         io,
+        testing.allocator,
         &database,
         @as(?*disk_monitor.Monitor, null),
     });
@@ -1502,7 +1508,7 @@ test "entries that arrive inside one window reach the database in one batch" {
 
     var database = try openLog();
     defer database.close();
-    var writer = try queries_repo.BatchWriter.init(&database);
+    var writer = try queries_repo.BatchWriter.init(testing.allocator, &database);
     defer writer.deinit();
 
     var buf: [16]Entry = undefined;
@@ -1559,6 +1565,7 @@ test "the writer holds an entry for the length of the flush interval" {
     var future = try io.concurrent(Logger.runWriter, .{
         &logger,
         io,
+        testing.allocator,
         &database,
         @as(?*disk_monitor.Monitor, null),
     });
@@ -1611,6 +1618,7 @@ test "a full batch flushes without waiting for the interval" {
     var future = try io.concurrent(Logger.runWriter, .{
         &logger,
         io,
+        testing.allocator,
         &database,
         @as(?*disk_monitor.Monitor, null),
     });
@@ -1658,6 +1666,7 @@ test "the writer's next cycle uses the interval set since its last one" {
     var future = try io.concurrent(Logger.runWriter, .{
         &logger,
         io,
+        testing.allocator,
         &database,
         @as(?*disk_monitor.Monitor, null),
     });
@@ -1700,7 +1709,7 @@ test "a gated flush holds the batch until the disk recovers" {
 
     var database = try openLog();
     defer database.close();
-    var writer = try queries_repo.BatchWriter.init(&database);
+    var writer = try queries_repo.BatchWriter.init(testing.allocator, &database);
     defer writer.deinit();
 
     var buf: [4]Entry = undefined;
@@ -1754,7 +1763,7 @@ test "a failing batch is dropped whole and the writer stays usable" {
         \\BEGIN SELECT RAISE(ABORT, 'refused'); END;
     );
 
-    var writer = try queries_repo.BatchWriter.init(&database);
+    var writer = try queries_repo.BatchWriter.init(testing.allocator, &database);
     defer writer.deinit();
 
     var buf: [4]Entry = undefined;
@@ -1789,7 +1798,7 @@ test "a writer that cannot prepare closes the queue and counts every entry" {
 
     for (0..3) |i| logger.log(io, sampleEntry(@intCast(i), "early.example"));
 
-    try logger.runWriter(io, &database, null);
+    try logger.runWriter(io, testing.allocator, &database, null);
 
     try testing.expect(logger.writer_failed.load(.acquire));
     try testing.expectEqual(@as(u64, 3), logger.queries_dropped.load(.monotonic));
@@ -1842,6 +1851,7 @@ test "the gating episode opens on the gate, turns losing on a drop, and clears o
     var future = try io.concurrent(Logger.runWriter, .{
         &logger,
         io,
+        testing.allocator,
         &database,
         @as(?*disk_monitor.Monitor, &monitor),
     });
@@ -2023,6 +2033,7 @@ test "a canceled writer counts the batch it was holding" {
     var future = try io.concurrent(Logger.runWriter, .{
         &logger,
         io,
+        testing.allocator,
         &database,
         @as(?*disk_monitor.Monitor, &monitor),
     });
@@ -2072,6 +2083,7 @@ test "a disk-gated writer drops what it holds at shutdown instead of hanging" {
     var future = try io.concurrent(Logger.runWriter, .{
         &logger,
         io,
+        testing.allocator,
         &database,
         @as(?*disk_monitor.Monitor, &monitor),
     });
@@ -2121,7 +2133,7 @@ test "an empty batch touches neither the database nor the counters" {
 
     var database = try openLog();
     defer database.close();
-    var writer = try queries_repo.BatchWriter.init(&database);
+    var writer = try queries_repo.BatchWriter.init(testing.allocator, &database);
     defer writer.deinit();
 
     var buf: [4]Entry = undefined;
@@ -2155,7 +2167,7 @@ test "a dropped batch opens an error episode the next good batch closes" {
     try fx.init(io, 1000);
     defer fx.deinit();
 
-    var writer = try queries_repo.BatchWriter.init(&database);
+    var writer = try queries_repo.BatchWriter.init(testing.allocator, &database);
     defer writer.deinit();
 
     var buf: [4]Entry = undefined;
@@ -2198,7 +2210,7 @@ test "a writer that cannot prepare leaves an episode no recovery path claims" {
     var logger: Logger = .init(.{}, &buf);
     logger.diagnostics = &fx.store;
 
-    try logger.runWriter(io, &database, null);
+    try logger.runWriter(io, testing.allocator, &database, null);
 
     try testing.expectEqualStrings("writer", try fx.text(
         "SELECT subject_key FROM operational_events WHERE resolved_at IS NULL",
@@ -2209,7 +2221,7 @@ test "a writer that cannot prepare leaves an episode no recovery path claims" {
 
     // The writer returned, so nothing can ever close this. A second run finds
     // the queue closed and adds no second episode.
-    try logger.runWriter(io, &database, null);
+    try logger.runWriter(io, testing.allocator, &database, null);
     try testing.expectEqual(
         @as(i64, 1),
         try fx.count("SELECT count(*) FROM operational_events WHERE resolved_at IS NULL"),

src/storage/logger_controller.zig

@@ -248,6 +248,7 @@ pub const Controller = struct {
         owned.writer = try io.concurrent(logger.Logger.runWriter, .{
             generation.logger,
             io,
+            opts.gpa,
             &owned.database,
             opts.monitor,
         });
@@ -434,7 +435,7 @@ pub const Controller = struct {
         errdefer generation.deinit(self.gpa);
         const owned = &generation.owned.?;
 
-        owned.writer = try io.concurrent(runParkedWriter, .{ generation, io, self.monitor });
+        owned.writer = try io.concurrent(runParkedWriter, .{ generation, io, self.gpa, self.monitor });
 
         // The statements are prepared before anything is published, so a
         // failure here is a refused settings change rather than a writer that
@@ -565,11 +566,12 @@ fn drain(generation: *Generation, io: std.Io) void {
 fn runParkedWriter(
     generation: *Generation,
     io: std.Io,
+    gpa: Allocator,
     monitor: ?*disk_monitor.Monitor,
 ) std.Io.Cancelable!void {
     const owned = &generation.owned.?;
 
-    var writer = queries_repo.BatchWriter.init(&owned.database) catch |err| {
+    var writer = queries_repo.BatchWriter.init(gpa, &owned.database) catch |err| {
         owned.prepare_error = err;
         owned.ready.set(io);
         return;

src/storage/phase6_integration_test.zig

@@ -27,6 +27,7 @@ const disk_monitor = @import("disk_monitor.zig");
 const logger = @import("logger.zig");
 const queries_repo = @import("repositories/queries_repo.zig");
 const querylog_schema = @import("querylog_schema.zig");
+const querylog_versions = @import("querylog_versions.zig");
 const retention = @import("retention.zig");
 
 const testing = std.testing;
@@ -144,7 +145,7 @@ fn awaitCount(counter: *const std.atomic.Value(u64), target: u64, limit: usize)
 }
 
 fn writeRows(database: *db.Db, timestamps: []const i64, domain: []const u8) !void {
-    var writer = try queries_repo.BatchWriter.init(database);
+    var writer = try queries_repo.BatchWriter.init(testing.allocator, database);
     defer writer.deinit();
 
     var rows: [16]queries_repo.Row = undefined;
@@ -208,6 +209,7 @@ test "S8 case 1: the logger writes a real querylog.db end to end" {
     var future = try io.concurrent(logger.Logger.runWriter, .{
         &query_log,
         io,
+        testing.allocator,
         log_db.database(),
         @as(?*disk_monitor.Monitor, null),
     });
@@ -232,7 +234,7 @@ test "S8 case 1: the logger writes a real querylog.db end to end" {
     try testing.expectEqual(@as(i64, 250), try queries_repo.countRows(log_db.database()));
     try testing.expectEqual(@as(i64, 10), try queries_repo.countDomains(log_db.database()));
     try testing.expectEqual(
-        @as(i64, querylog_schema.fingerprint),
+        @as(i64, querylog_versions.current_version),
         try log_db.database().queryInt("PRAGMA user_version"),
     );
 }
@@ -256,6 +258,7 @@ test "S8 case 2: a single entry reaches the file once the flush interval passes"
     var future = try io.concurrent(logger.Logger.runWriter, .{
         &query_log,
         io,
+        testing.allocator,
         log_db.database(),
         @as(?*disk_monitor.Monitor, null),
     });
@@ -311,6 +314,7 @@ test "S8 case 3: a full queue drops the oldest entries and the newest survive" {
     var future = try io.concurrent(logger.Logger.runWriter, .{
         &query_log,
         io,
+        testing.allocator,
         log_db.database(),
         @as(?*disk_monitor.Monitor, &monitor),
     });
@@ -359,6 +363,7 @@ test "S8 case 4: the privacy transforms reach the stored rows" {
     var future = try io.concurrent(logger.Logger.runWriter, .{
         &query_log,
         io,
+        testing.allocator,
         log_db.database(),
         @as(?*disk_monitor.Monitor, null),
     });
@@ -459,6 +464,7 @@ test "S8 case 6: a critical disk gates the flushes and recovery releases them" {
     var future = try io.concurrent(logger.Logger.runWriter, .{
         &query_log,
         io,
+        testing.allocator,
         log_db.database(),
         @as(?*disk_monitor.Monitor, &monitor),
     });

src/storage/querylog_fixtures.zig

@@ -0,0 +1,535 @@
+//! The shipped `querylog.db` fixtures, and the proof that every supported
+//! schema version reaches the current one with the operator's rows intact.
+//!
+//! A file of its own, not a section of `querylog_migrations.zig`, because of the
+//! link contract that split `querylog_versions.zig` out in the first place. The
+//! assertions here need `repositories/queries_repo.zig`'s projection-coherence
+//! oracle, and that file reaches across `src/` for the config and filter types;
+//! importing it from `querylog_migrations.zig` would pull all of it into the
+//! module `tools/cut.zig` builds `querylog_schema.zig` as, where those paths lie
+//! outside the module root and do not compile.
+//!
+//! The fixtures themselves — `testdata/querylog-v<N>-{schema,data}.sql` — are
+//! immutable once released. Every version in `[minimum_supported_version,
+//! current_version]` has a pair: the current version's pair is the next
+//! migration's starting point, and an explicit break ships the new baseline.
+
+const std = @import("std");
+
+const db = @import("db.zig");
+const migrations = @import("querylog_migrations.zig");
+const queries_repo = @import("repositories/queries_repo.zig");
+const querylog_schema = @import("querylog_schema.zig");
+const versions = @import("querylog_versions.zig");
+
+const testing = std.testing;
+
+/// A temporary directory and the `querylog.db` path inside it. Deliberately not
+/// `querylog_migrations.zig`'s test harness: that one builds synthetic schemas,
+/// while everything here starts from the shipped fixture files.
+const Harness = struct {
+    threaded: std.Io.Threaded,
+    tmp: std.testing.TmpDir,
+    buf: [256]u8 = undefined,
+
+    fn init() Harness {
+        return .{
+            .threaded = .init(testing.allocator, .{}),
+            .tmp = testing.tmpDir(.{ .iterate = true }),
+        };
+    }
+
+    fn deinit(self: *Harness) void {
+        self.tmp.cleanup();
+        self.threaded.deinit();
+    }
+
+    fn io(self: *Harness) std.Io {
+        return self.threaded.io();
+    }
+
+    fn path(self: *Harness) [:0]const u8 {
+        return std.fmt.bufPrintZ(&self.buf, ".zig-cache/tmp/{s}/querylog.db", .{self.tmp.sub_path}) catch
+            unreachable;
+    }
+
+    fn openLive(self: *Harness) !db.Db {
+        var database = try db.Db.open(self.path(), .{ .mode = .read_write_existing });
+        errdefer database.close();
+        try db.applyPragmas(&database, .{});
+        return database;
+    }
+};
+
+/// One shipped schema version's frozen pair. Both halves are immutable once
+/// released — the release cut byte-compares them against the previous tag — and
+/// every version in `[minimum_supported_version, current_version]` must have a
+/// pair, which the cut gate also enforces.
+const Fixture = struct {
+    version: i32,
+    schema: [:0]const u8,
+    data: [:0]const u8,
+};
+
+const fixtures = [_]Fixture{
+    .{
+        .version = 1,
+        .schema = @embedFile("testdata/querylog-v1-schema.sql"),
+        .data = @embedFile("testdata/querylog-v1-data.sql"),
+    },
+};
+
+fn fixtureFor(version: i32) ?Fixture {
+    for (fixtures) |fixture| {
+        if (fixture.version == version) return fixture;
+    }
+    return null;
+}
+
+/// Writes a fixture pair to `path` and stamps it. `stamp` is a parameter rather
+/// than `fixture.version` because the legacy-fingerprint file is the same
+/// version-1 bytes under a different stamp.
+fn writeFixture(path: [:0]const u8, fixture: Fixture, stamp: i32) !void {
+    var database = try db.Db.open(path, .{ .mode = .read_write_create });
+    defer database.close();
+    try db.applyPragmas(&database, .{});
+    try database.exec(fixture.schema);
+    try database.exec(fixture.data);
+
+    var buf: [64]u8 = undefined;
+    const sql = std.fmt.bufPrintZ(&buf, "PRAGMA user_version = {d};", .{stamp}) catch unreachable;
+    try database.exec(sql);
+}
+
+/// A second path in the harness's directory, for the reference databases the
+/// assertions below compare against.
+fn sidePath(h: *Harness, buf: []u8, name: []const u8) [:0]const u8 {
+    return std.fmt.bufPrintZ(buf, ".zig-cache/tmp/{s}/{s}", .{ h.tmp.sub_path, name }) catch unreachable;
+}
+
+/// A database holding nothing but the current `ddl`, which is what a file
+/// created by this build is.
+fn openFreshCurrent(h: *Harness, buf: []u8) !db.Db {
+    var database = try db.Db.open(sidePath(h, buf, "fresh.db"), .{ .mode = .read_write_create });
+    errdefer database.close();
+    try db.applyPragmas(&database, .{});
+    try database.exec(querylog_schema.ddl);
+    return database;
+}
+
+/// An untouched load of `fixture`, to compare a migrated or opened file against
+/// rather than restating the fixture's contents in the assertions.
+fn openPristine(h: *Harness, buf: []u8, fixture: Fixture) !db.Db {
+    const path = sidePath(h, buf, "pristine.db");
+    try writeFixture(path, fixture, fixture.version);
+    var database = try db.Db.open(path, .{ .mode = .read_write_existing });
+    errdefer database.close();
+    try db.applyPragmas(&database, .{});
+    return database;
+}
+
+/// Every row of every table, as one canonical text. Exact equality is only the
+/// right question for a file no migration has reshaped; a migrated file is
+/// checked by the counts and the watermark instead.
+fn dumpContent(gpa: std.mem.Allocator, database: *db.Db, out: *std.ArrayList(u8)) !void {
+    var tables: std.ArrayList([]u8) = .empty;
+    defer freeOwned(gpa, &tables);
+    {
+        var stmt = try database.prepare(
+            \\SELECT name FROM sqlite_schema
+            \\WHERE type = 'table' AND name NOT LIKE 'sqlite\_%' ESCAPE '\'
+            \\ORDER BY name
+        );
+        defer stmt.deinit();
+        // Copied out before the per-table statements step: a borrowed
+        // `columnText` would not survive them.
+        while (try stmt.step()) try tables.append(gpa, try stmt.columnTextAlloc(gpa, 0));
+    }
+
+    // The lines are sorted here rather than by the query: the four `bucket_*`
+    // tables are WITHOUT ROWID, so `ORDER BY rowid` is not available to all of
+    // them and no single column list is.
+    var lines: std.ArrayList([]u8) = .empty;
+    defer freeOwned(gpa, &lines);
+
+    for (tables.items) |table| {
+        var sql_buf: [256]u8 = undefined;
+        const sql = std.fmt.bufPrint(&sql_buf, "SELECT * FROM \"{s}\"", .{table}) catch unreachable;
+        var stmt = try database.prepare(sql);
+        defer stmt.deinit();
+        while (try stmt.step()) {
+            var line: std.ArrayList(u8) = .empty;
+            errdefer line.deinit(gpa);
+            try line.print(gpa, "R|{s}", .{table});
+            var col: c_int = 0;
+            const columns: c_int = db.c.sqlite3_column_count(stmt.handle);
+            while (col < columns) : (col += 1) {
+                try line.print(gpa, "|{s}", .{stmt.columnTextOrNull(col) orelse "<null>"});
+            }
+            try lines.append(gpa, try line.toOwnedSlice(gpa));
+        }
+    }
+
+    std.mem.sortUnstable([]u8, lines.items, {}, struct {
+        fn lessThan(_: void, a: []u8, b: []u8) bool {
+            return std.mem.lessThan(u8, a, b);
+        }
+    }.lessThan);
+    for (lines.items) |line| {
+        try out.appendSlice(gpa, line);
+        try out.append(gpa, '\n');
+    }
+}
+
+/// One value, encoded so that no two different values can produce the same
+/// bytes: a type tag, the byte length, then the bytes themselves.
+///
+/// Nothing here is a sentinel and nothing is escaped, which is the point. A
+/// serialization that wrote NULL as `<null>` cannot tell a NULL apart from the
+/// six-character string of the same name, and one that separated values with
+/// `|` cannot tell `a|b` in one column from `a` and `b` in two — so a migration
+/// that turned a NULL `upstream` into text, or shifted a value from one column
+/// into its neighbour, would compare EQUAL to the original. The length prefix
+/// makes the stream uniquely decodable, so equal encodings mean equal rows.
+///
+/// A float travels as its bit pattern rather than as printed digits: the
+/// question here is whether the value survived, not whether it rounds the same.
+fn writeValue(gpa: std.mem.Allocator, stmt: *db.Stmt, col: c_int, out: *std.ArrayList(u8)) !void {
+    switch (db.c.sqlite3_column_type(stmt.handle, col)) {
+        db.column_type.null_value => try out.print(gpa, "n0:", .{}),
+        db.column_type.integer => {
+            var buf: [24]u8 = undefined;
+            const text = std.fmt.bufPrint(&buf, "{d}", .{stmt.columnInt(col)}) catch unreachable;
+            try out.print(gpa, "i{d}:{s}", .{ text.len, text });
+        },
+        db.column_type.float => {
+            const bits: u64 = @bitCast(db.c.sqlite3_column_double(stmt.handle, col));
+            var buf: [24]u8 = undefined;
+            const text = std.fmt.bufPrint(&buf, "{d}", .{bits}) catch unreachable;
+            try out.print(gpa, "f{d}:{s}", .{ text.len, text });
+        },
+        db.column_type.blob => {
+            // `columnText` on a blob hands back the same bytes SQLite stores,
+            // which is what this compares; it is not read as text.
+            const bytes = stmt.columnText(col);
+            try out.print(gpa, "b{d}:{s}", .{ bytes.len, bytes });
+        },
+        else => {
+            const bytes = stmt.columnText(col);
+            try out.print(gpa, "t{d}:{s}", .{ bytes.len, bytes });
+        },
+    }
+}
+
+/// One query's rows, in the order the query returns them, tagged with `label` so
+/// that a difference names the relation it came from. The column count is part
+/// of each row for the same reason the lengths are part of each value.
+fn dumpQuery(
+    gpa: std.mem.Allocator,
+    database: *db.Db,
+    label: []const u8,
+    sql: [:0]const u8,
+    out: *std.ArrayList(u8),
+) !void {
+    var stmt = try database.prepare(sql);
+    defer stmt.deinit();
+    while (try stmt.step()) {
+        const columns: c_int = db.c.sqlite3_column_count(stmt.handle);
+        try out.print(gpa, "{s}:{d}:", .{ label, columns });
+        var col: c_int = 0;
+        while (col < columns) : (col += 1) {
+            try writeValue(gpa, &stmt, col, out);
+        }
+        try out.append(gpa, '\n');
+    }
+}
+
+/// The operator's data as the application means it, in an order a migration
+/// cannot permute.
+///
+/// `q.*` rather than a column list on purpose: a migration that adds a column
+/// must show that column here, and a hand-written list would quietly stop
+/// covering the table the day it grows. `d.domain` rides along so that the text
+/// a row names is compared, not only the id it happens to hold.
+const logical_relations = [_]struct { label: []const u8, sql: [:0]const u8 }{
+    .{
+        .label = "query_log",
+        .sql =
+        \\SELECT q.*, d.domain FROM query_log q
+        \\JOIN domains d ON d.id = q.domain_id
+        \\ORDER BY q.id
+        ,
+    },
+    .{ .label = "domains", .sql = "SELECT * FROM domains ORDER BY id" },
+    .{ .label = "querylog_meta", .sql = "SELECT * FROM querylog_meta ORDER BY id" },
+};
+
+fn dumpLogical(gpa: std.mem.Allocator, database: *db.Db, out: *std.ArrayList(u8)) !void {
+    for (logical_relations) |relation| {
+        try dumpQuery(gpa, database, relation.label, relation.sql, out);
+    }
+}
+
+fn freeOwned(gpa: std.mem.Allocator, list: *std.ArrayList([]u8)) void {
+    for (list.items) |item| gpa.free(item);
+    list.deinit(gpa);
+}
+
+fn expectSameContent(a: *db.Db, b: *db.Db) !void {
+    var text_a: std.ArrayList(u8) = .empty;
+    defer text_a.deinit(testing.allocator);
+    var text_b: std.ArrayList(u8) = .empty;
+    defer text_b.deinit(testing.allocator);
+    try dumpContent(testing.allocator, a, &text_a);
+    try dumpContent(testing.allocator, b, &text_b);
+    try testing.expectEqualStrings(text_a.items, text_b.items);
+}
+
+fn rowCount(database: *db.Db, table: []const u8) !i64 {
+    var buf: [128]u8 = undefined;
+    return database.queryInt(std.fmt.bufPrint(&buf, "SELECT count(*) FROM \"{s}\"", .{table}) catch unreachable);
+}
+
+/// What must hold after a fixture has come through `openVersioned`, whatever
+/// path it took: every row the operator had is still there with the same
+/// CONTENT, and the projections still agree with the raw rows.
+///
+/// Counting rows and checking one watermark is what this used to do, and a
+/// migration that shifted a timestamp, dropped a `qtype` or crossed two rows'
+/// `client_ip` values passed it. The comparison is therefore the full logical
+/// content of the three operator tables, `available_since` included as one
+/// column of `querylog_meta` among the rest. The counts stay because a count
+/// difference is the failure worth naming plainly.
+///
+/// The relations are named rather than derived because they are the ones holding
+/// operator data; the `bucket_*` projections are derived from them, which
+/// `expectProjectionsMatchRecompute` is the right check for. A future migration
+/// that renames a table amends this alongside the step that does it. So does one
+/// that renumbers `id` values: this asserts they survive, which every rebuild
+/// written to the A.2 rule does.
+fn expectFixtureSurvived(opened: *db.Db, pristine: *db.Db) !void {
+    for ([_][]const u8{ "query_log", "domains", "querylog_meta" }) |table| {
+        try testing.expectEqual(try rowCount(pristine, table), try rowCount(opened, table));
+    }
+
+    var opened_text: std.ArrayList(u8) = .empty;
+    defer opened_text.deinit(testing.allocator);
+    var pristine_text: std.ArrayList(u8) = .empty;
+    defer pristine_text.deinit(testing.allocator);
+    try dumpLogical(testing.allocator, opened, &opened_text);
+    try dumpLogical(testing.allocator, pristine, &pristine_text);
+    try testing.expectEqualStrings(pristine_text.items, opened_text.items);
+
+    try queries_repo.expectProjectionsMatchRecompute(opened);
+}
+
+test "the survival comparison tells a NULL apart from text that looks like one" {
+    // The mutation a count-and-watermark check misses entirely, and a
+    // sentinel-string serialization misses just as completely: one column of one
+    // row stops being NULL and becomes the very text the sentinel used. Every
+    // count, the watermark and the projections all still agree.
+    const fixture = fixtureFor(1) orelse return error.MissingFixture;
+
+    var h: Harness = .init();
+    defer h.deinit();
+    try writeFixture(h.path(), fixture, fixture.version);
+
+    var side: [256]u8 = undefined;
+    var pristine = try openPristine(&h, &side, fixture);
+    defer pristine.close();
+
+    var corrupted = try h.openLive();
+    defer corrupted.close();
+    try testing.expectEqual(@as(i64, 0), corrupted.changes());
+    try corrupted.exec(
+        \\UPDATE query_log SET upstream = '<null>'
+        \\WHERE id = (SELECT min(id) FROM query_log WHERE upstream IS NULL)
+    );
+    // The fixture has to actually carry a NULL `upstream` for this to be a test
+    // of anything.
+    try testing.expectEqual(@as(i64, 1), corrupted.changes());
+
+    // Everything the old check looked at still agrees, which is why it passed.
+    for ([_][]const u8{ "query_log", "domains", "querylog_meta" }) |table| {
+        try testing.expectEqual(try rowCount(&pristine, table), try rowCount(&corrupted, table));
+    }
+    try testing.expectEqual(
+        try pristine.queryInt("SELECT available_since FROM querylog_meta WHERE id = 1"),
+        try corrupted.queryInt("SELECT available_since FROM querylog_meta WHERE id = 1"),
+    );
+    try queries_repo.expectProjectionsMatchRecompute(&corrupted);
+
+    // The dumps are compared here rather than through `expectFixtureSurvived`
+    // so that a PASSING run stays silent: `expectEqualStrings` prints the whole
+    // diff before it returns its error, and this is the comparison that function
+    // makes.
+    var corrupted_text: std.ArrayList(u8) = .empty;
+    defer corrupted_text.deinit(testing.allocator);
+    var pristine_text: std.ArrayList(u8) = .empty;
+    defer pristine_text.deinit(testing.allocator);
+    try dumpLogical(testing.allocator, &corrupted, &corrupted_text);
+    try dumpLogical(testing.allocator, &pristine, &pristine_text);
+    try testing.expect(!std.mem.eql(u8, corrupted_text.items, pristine_text.items));
+}
+
+test "every supported version ships a fixture pair" {
+    // The cut gate enforces this against a release; the suite enforces it
+    // against a commit, so a version bump that forgot its fixtures fails here
+    // long before anyone reaches for `zig build cut`.
+    var version = versions.minimum_supported_version;
+    while (version <= versions.current_version) : (version += 1) {
+        try testing.expect(fixtureFor(version) != null);
+    }
+}
+
+test "each shipped fixture pair is coherent before any migration touches it" {
+    for (fixtures) |fixture| {
+        var h: Harness = .init();
+        defer h.deinit();
+        try writeFixture(h.path(), fixture, fixture.version);
+
+        var database = try h.openLive();
+        defer database.close();
+        try testing.expectEqual(
+            @as(i64, fixture.version),
+            try database.queryInt("PRAGMA user_version"),
+        );
+        // An incoherent fixture has to fail as a fixture, not later as a
+        // migration that appears to have corrupted the projections.
+        try queries_repo.expectProjectionsMatchRecompute(&database);
+        try testing.expectEqual(@as(i64, 0), try database.queryInt("SELECT count(*) FROM pragma_foreign_key_check"));
+    }
+}
+
+test "every fixture below the current version migrates to it through the shipped chain" {
+    // Empty while the chain is: `minimum_supported_version == current_version`
+    // today. It is written as the loop so that the day a step ships, the
+    // fixture it starts from is proved through the REAL production plan with no
+    // edit to this test.
+    var version = versions.minimum_supported_version;
+    while (version < versions.current_version) : (version += 1) {
+        const fixture = fixtureFor(version) orelse return error.MissingFixture;
+
+        var h: Harness = .init();
+        defer h.deinit();
+        try writeFixture(h.path(), fixture, version);
+
+        var side: [256]u8 = undefined;
+        var pristine = try openPristine(&h, &side, fixture);
+        defer pristine.close();
+
+        var result = try querylog_schema.open(h.io(), std.Io.Dir.cwd(), h.path());
+        defer result.database.close();
+        try testing.expectEqual(@as(?querylog_schema.RecreateReason, null), result.recreated);
+        try testing.expectEqual(
+            @as(i64, versions.current_version),
+            try result.database.queryInt("PRAGMA user_version"),
+        );
+
+        var fresh_buf: [256]u8 = undefined;
+        var fresh = try openFreshCurrent(&h, &fresh_buf);
+        defer fresh.close();
+        try testing.expect(try migrations.schemaEquivalent(testing.allocator, &result.database, &fresh));
+        try expectFixtureSurvived(&result.database, &pristine);
+    }
+}
+
+test "the current version's fixture pair opens on the current lane unchanged" {
+    // The loop above never reaches this pair, and Gate 2 of the cut requires it
+    // to exist. This is what proves it is a real, coherent file rather than one
+    // shipped to satisfy a gate.
+    const fixture = fixtureFor(versions.current_version) orelse return error.MissingFixture;
+
+    var h: Harness = .init();
+    defer h.deinit();
+    try writeFixture(h.path(), fixture, versions.current_version);
+
+    var side: [256]u8 = undefined;
+    var pristine = try openPristine(&h, &side, fixture);
+    defer pristine.close();
+
+    var result = try querylog_schema.open(h.io(), std.Io.Dir.cwd(), h.path());
+    defer result.database.close();
+    try testing.expectEqual(@as(?querylog_schema.RecreateReason, null), result.recreated);
+    try testing.expectEqual(
+        @as(i64, versions.current_version),
+        try result.database.queryInt("PRAGMA user_version"),
+    );
+
+    var fresh_buf: [256]u8 = undefined;
+    var fresh = try openFreshCurrent(&h, &fresh_buf);
+    defer fresh.close();
+    try testing.expect(try migrations.schemaEquivalent(testing.allocator, &result.database, &fresh));
+    try expectFixtureSurvived(&result.database, &pristine);
+    // No migration ran, so nothing reshaped anything: byte-for-byte the rows
+    // that were loaded.
+    try expectSameContent(&result.database, &pristine);
+}
+
+test "a fixture carrying the 0.0.12 fingerprint restamps, and refuses once the minimum rises" {
+    const fixture = fixtureFor(1) orelse return error.MissingFixture;
+
+    // Version 1 is the legacy fingerprint's logical version, so the pair only
+    // has anything to say while 1 is still supported.
+    if (versions.minimum_supported_version <= 1 and versions.current_version >= 1) {
+        var h: Harness = .init();
+        defer h.deinit();
+        try writeFixture(h.path(), fixture, versions.legacy_fingerprint);
+
+        var side: [256]u8 = undefined;
+        var pristine = try openPristine(&h, &side, fixture);
+        defer pristine.close();
+
+        var result = try querylog_schema.open(h.io(), std.Io.Dir.cwd(), h.path());
+        defer result.database.close();
+        try testing.expectEqual(@as(?querylog_schema.RecreateReason, null), result.recreated);
+        try testing.expectEqual(
+            @as(i64, versions.current_version),
+            try result.database.queryInt("PRAGMA user_version"),
+        );
+
+        var fresh_buf: [256]u8 = undefined;
+        var fresh = try openFreshCurrent(&h, &fresh_buf);
+        defer fresh.close();
+        try testing.expect(try migrations.schemaEquivalent(testing.allocator, &result.database, &fresh));
+        try expectFixtureSurvived(&result.database, &pristine);
+    }
+
+    // The companion, already in the suite for the day a break raises the
+    // minimum above 1: the same bytes under the same stamp are then a file this
+    // build cannot reach, and it is refused without being touched.
+    var h: Harness = .init();
+    defer h.deinit();
+    try writeFixture(h.path(), fixture, versions.legacy_fingerprint);
+
+    const after_break: querylog_schema.Plan = .{
+        .minimum = 2,
+        .current = 2,
+        .legacy_fingerprint = versions.legacy_fingerprint,
+        .step_sql = &.{},
+    };
+    try testing.expect(querylog_schema.classify(versions.legacy_fingerprint, after_break).action ==
+        .refuse_unsupported);
+    try testing.expect(!querylog_schema.classify(versions.legacy_fingerprint, after_break).restamp);
+
+    var handle: ?db.Db = try h.openLive();
+    defer if (handle) |*open_db| open_db.close();
+
+    migrations.expected_failures.begin();
+    defer migrations.expected_failures.end();
+    try testing.expectError(
+        error.SchemaUnsupported,
+        querylog_schema.openVersioned(h.io(), std.Io.Dir.cwd(), h.path(), &handle, after_break),
+    );
+
+    var check = try h.openLive();
+    defer check.close();
+    try testing.expectEqual(
+        @as(i64, versions.legacy_fingerprint),
+        try check.queryInt("PRAGMA user_version"),
+    );
+    var pristine_buf: [256]u8 = undefined;
+    var pristine = try openPristine(&h, &pristine_buf, fixture);
+    defer pristine.close();
+    try expectSameContent(&check, &pristine);
+}

src/storage/querylog_schema.zig

@@ -1,14 +1,15 @@
-//! The `querylog.db` schema and its open-or-recreate policy.
+//! The `querylog.db` schema and its open policy.
 //!
-//! `querylog.db` is never migrated (PLAN §3.7). It holds expendable log rows,
+//! `querylog.db` carries a logical schema version in `PRAGMA user_version`
-//! so a schema change replaces the file instead of upgrading it. The
+//! (`querylog_versions.zig`), and a file stamped below the current version is
-//! replacement trigger is a fingerprint derived from the DDL text itself, so
+//! MIGRATED in place. A healthy file is never replaced and never set aside: a
-//! editing the schema below automatically invalidates every existing file — the
+//! version this build cannot reach refuses the startup with instructions
-//! policy cannot drift out of sync with the SQL.
+//! instead, because the operator's query history is not this program's to
+//! discard.
 //!
 //! **Recreating is destructive, so the predicate is a positive whitelist.** Only
-//! a missing file, `error.Corrupt`, `error.NotADb`, a failed `PRAGMA
+//! a missing file, `error.Corrupt`, `error.NotADb` and a failed `PRAGMA
-//! quick_check` and a fingerprint mismatch recreate. Every other error
+//! quick_check` recreate — genuine corruption, nothing else. Every other error
 //! propagates and the file on disk is not touched. `error.Busy` / `error.Locked`
 //! mean another process holds the write lock — waiting is right, deleting is
 //! catastrophic. `error.OutOfMemory` is this process's problem. `error.CantOpen`
@@ -19,13 +20,25 @@
 const std = @import("std");
 
 const db = @import("db.zig");
+const migrations = @import("querylog_migrations.zig");
+const versions = @import("querylog_versions.zig");
 
 const log = std.log.scoped(.querylog_schema);
 
+/// See `querylog_migrations.fail`: `err`, unless a test has said it is causing
+/// this refusal on purpose.
+fn fail(comptime fmt: []const u8, args: anytype) void {
+    if (migrations.expected_failures.capturing()) {
+        log.warn(fmt, args);
+    } else {
+        log.err(fmt, args);
+    }
+}
+
 /// PLAN §11.3, plus the coverage watermark of milestone 28. Multi-statement
 /// text — it goes through `db.Db.exec`, never through `prepare`.
 ///
-/// The trailing INSERT seeds `querylog_meta`, which is part of the schema
+/// The INSERT seeds `querylog_meta`, which is part of the schema
 /// rather than a later step: a `query_log` with no watermark beside it cannot
 /// answer whether an empty result means "no queries" or "no history", and every
 /// database this program reads from is created by executing this string.
@@ -36,6 +49,13 @@ const log = std.log.scoped(.querylog_schema);
 /// logged in the same second the file was created is not evidence that the
 /// second is completely covered, and the watermark's whole job is to be
 /// conservative. From there it only ever advances, in `queries_repo.pruneOlderThan`.
+///
+/// The four `bucket_*` tables are the Overview projections (milestone 36), on a
+/// 30-minute grain that divides every serving width the API offers. They carry
+/// no history of their own: they are born with the file and maintained in the
+/// same transaction as every insert and every prune, so SQLite's transaction is
+/// the only coherence mechanism there is. There is no backfill path — a file
+/// whose projections could disagree with its rows cannot exist.
 pub const ddl: [:0]const u8 =
     \\CREATE TABLE domains (
     \\    id INTEGER PRIMARY KEY,
@@ -78,6 +98,40 @@ pub const ddl: [:0]const u8 =
     \\);
     \\INSERT INTO querylog_meta (id, created_at, available_since)
     \\VALUES (1, unixepoch(), unixepoch() + 1);
+    \\
+    \\CREATE TABLE bucket_totals (
+    \\    bucket INTEGER PRIMARY KEY,
+    \\    queries INTEGER NOT NULL,
+    \\    blocked INTEGER NOT NULL,
+    \\    cached INTEGER NOT NULL,
+    \\    rt_sum INTEGER NOT NULL,     -- sum(response_time_us) over timed rows
+    \\    rt_count INTEGER NOT NULL    -- count(response_time_us)
+    \\) WITHOUT ROWID;
+    \\
+    \\CREATE TABLE bucket_clients (
+    \\    bucket INTEGER NOT NULL,
+    \\    client_ip TEXT NOT NULL,
+    \\    queries INTEGER NOT NULL,
+    \\    PRIMARY KEY (bucket, client_ip)
+    \\) WITHOUT ROWID;
+    \\
+    \\CREATE TABLE bucket_types (
+    \\    bucket INTEGER NOT NULL,
+    \\    qtype INTEGER NOT NULL,      -- -1 encodes a NULL qtype, losslessly
+    \\    count INTEGER NOT NULL,
+    \\    PRIMARY KEY (bucket, qtype)
+    \\) WITHOUT ROWID;
+    \\
+    \\CREATE TABLE bucket_routes (
+    \\    bucket INTEGER NOT NULL,
+    \\    route_kind TEXT NOT NULL,
+    \\    source_present INTEGER NOT NULL,  -- 0: source NULL; 1: source = source_text
+    \\    source_text TEXT NOT NULL,        -- '' when source_present = 0
+    \\    count INTEGER NOT NULL,
+    \\    PRIMARY KEY (bucket, route_kind, source_present, source_text),
+    \\    CHECK (source_present IN (0, 1)),
+    \\    CHECK (source_present = 1 OR source_text = '')
+    \\) WITHOUT ROWID;
 ;
 
 /// The fingerprint of an arbitrary DDL text. `tools/cut.zig` calls this at
@@ -98,14 +152,21 @@ pub const fingerprint: i32 = blk: {
     break :blk fingerprintOf(ddl);
 };
 
-const set_user_version = std.fmt.comptimePrint("PRAGMA user_version = {d};", .{fingerprint});
+/// What a fresh file is stamped with. The logical version, not the fingerprint:
+/// from this release on, `user_version` is a version number.
+const set_user_version = std.fmt.comptimePrint(
+    "PRAGMA user_version = {d};",
+    .{versions.current_version},
+);
 
 /// Long enough for any path this program will be handed, plus the aside suffix.
 /// A longer path is `error.NameTooLong`, which is what the filesystem calls
 /// would have returned anyway.
 const path_buf_len = 4096 + 64;
 
-pub const RecreateReason = enum { missing, corrupt, not_a_database, quick_check_failed, fingerprint_mismatch };
+/// Corruption, and nothing else. A healthy file with a version this build does
+/// not handle refuses the startup; it is never recreated and never set aside.
+pub const RecreateReason = enum { missing, corrupt, not_a_database, quick_check_failed };
 
 pub const OpenResult = struct {
     database: db.Db,
@@ -125,10 +186,75 @@ pub const OpenResult = struct {
     }
 };
 
-pub const Error = db.Error || error{AsideNameCollision} ||
+pub const Error = db.Error || error{
-    std.Io.Dir.RenamePreserveError || std.Io.Dir.DeleteFileError || std.Io.Dir.AccessError;
+    AsideNameCollision,
+    /// The file's version is above this build's. A downgrade, almost always.
+    SchemaTooNew,
+    /// The file's version is one this build cannot migrate from: older than
+    /// `minimum_supported_version`, or not a stamp nxdns ever wrote.
+    SchemaUnsupported,
+    MigrationFailed,
+    MigrationBackupFailed,
+    NameTooLong,
+} || std.Io.Dir.RenamePreserveError || std.Io.Dir.DeleteFileError || std.Io.Dir.AccessError;
 
-/// Opens `path`, recreating it if and only if it is genuinely unusable.
+/// The version metadata `openVersioned` works against. Production passes
+/// `production_plan`; tests inject synthetic chains, which is what makes
+/// migration, the post-commit branch and the ownership of the handle testable
+/// through the real open path while the shipped chain is still empty.
+pub const Plan = struct {
+    minimum: i32,
+    current: i32,
+    legacy_fingerprint: i32,
+    step_sql: []const [:0]const u8,
+};
+
+pub const production_plan: Plan = .{
+    .minimum = versions.minimum_supported_version,
+    .current = versions.current_version,
+    .legacy_fingerprint = versions.legacy_fingerprint,
+    .step_sql = versions.step_sql,
+};
+
+/// What a stamped `user_version` means. A pure function of the stamp and the
+/// plan's three numbers — no file, no clock, no mutation.
+pub const Action = enum { open_current, migrate, refuse_too_new, refuse_unsupported };
+
+pub const Classification = struct {
+    /// The stamp mapped onto the version line. Equal to the stamp except for
+    /// the legacy fingerprint, which IS version 1.
+    logical: i32,
+    action: Action,
+    /// The legacy fingerprint must be replaced by its logical number before the
+    /// file is used — but only on a lane that accepts the file. An unsupported
+    /// file is never modified.
+    restamp: bool,
+};
+
+/// The classification table. The order is load-bearing: the legacy fingerprint
+/// becomes version 1 FIRST, and only then is version 1 judged against the
+/// plan's range. After a future explicit break raises the minimum above 1, a
+/// legacy-stamped file therefore classifies as below-minimum and refuses
+/// without ever being restamped.
+pub fn classify(stamped: i32, plan: Plan) Classification {
+    const legacy = stamped == plan.legacy_fingerprint;
+    const logical: i32 = if (legacy) 1 else stamped;
+
+    const action: Action = if (logical == plan.current)
+        .open_current
+    else if (logical >= plan.minimum and logical < plan.current)
+        .migrate
+    else if (logical > plan.current and logical <= versions.version_floor_guard)
+        .refuse_too_new
+    else
+        .refuse_unsupported;
+
+    const accepted = action == .open_current or action == .migrate;
+    return .{ .logical = logical, .action = action, .restamp = legacy and accepted };
+}
+
+/// Opens `path`, recreating it if and only if it is genuinely unusable, and
+/// migrating it if and only if it carries an older supported version.
 ///
 /// `path` is resolved twice by two different mechanisms: `dir`-relative for the
 /// filesystem calls, and process-cwd-relative by SQLite's VFS, which knows
@@ -139,7 +265,7 @@ pub fn open(io: std.Io, dir: std.Io.Dir, path: [:0]const u8) Error!OpenResult {
     var handle: ?db.Db = null;
     errdefer if (handle) |*h| h.close();
 
-    const reason: ?RecreateReason = probe: {
+    const cause: RecreateReason = probe: {
         dir.access(io, path, .{}) catch |e| switch (e) {
             error.FileNotFound => break :probe .missing,
             else => |other| return other,
@@ -156,15 +282,10 @@ pub fn open(io: std.Io, dir: std.Io.Dir, path: [:0]const u8) Error!OpenResult {
             break :probe recreatable(e) orelse return e;
         if (!healthy) break :probe .quick_check_failed;
 
-        const stamped = opened.queryInt("PRAGMA user_version") catch |e|
+        try openVersioned(io, dir, path, &handle, production_plan);
-            break :probe recreatable(e) orelse return e;
+        return .{ .database = handle.?, .recreated = null };
-        if (stamped != fingerprint) break :probe .fingerprint_mismatch;
-
-        break :probe null;
     };
 
-    const cause = reason orelse return .{ .database = handle.?, .recreated = null };
-
     // Close first, so SQLite checkpoints and drops `-wal`/`-shm` where it can.
     if (handle) |*h| h.close();
     handle = null;
@@ -199,6 +320,131 @@ pub fn open(io: std.Io, dir: std.Io.Dir, path: [:0]const u8) Error!OpenResult {
     return result;
 }
 
+/// The version half of `open`, against an injectable `plan`.
+///
+/// `handle` is the slot holding the healthy, pragma-applied connection to
+/// `path`. On success the connection stays in it, at `plan.current`. On every
+/// failure this function closes the connection and sets the slot to null, so
+/// the caller's own error-path close cannot double-close it — including the
+/// committed-but-unclean path, which is the one place the handle must be
+/// dropped even though the file on disk is fine.
+///
+/// **nxdns owns `path` exclusively.** It opens `querylog.db` once at startup,
+/// before it serves anything, and no second process shares a data directory —
+/// the standing deployment contract. The backup-then-lock sequence in
+/// `querylog_migrations.runMigration` relies on it: between the `VACUUM INTO`
+/// and the `BEGIN IMMEDIATE` there is no lock, and the re-read of
+/// `user_version` under the lock is what turns a violation of that contract
+/// into a refusal instead of a corrupted migration.
+pub fn openVersioned(
+    io: std.Io,
+    dir: std.Io.Dir,
+    path: [:0]const u8,
+    handle: *?db.Db,
+    plan: Plan,
+) Error!void {
+    const database = &(handle.*.?);
+    errdefer closeSlot(handle);
+
+    const stamped64 = try database.queryInt("PRAGMA user_version");
+    const stamped = std.math.cast(i32, stamped64) orelse {
+        // `user_version` is a signed 32-bit field, so this cannot come from
+        // SQLite. Refusing is the same answer any other foreign stamp gets.
+        refusalLog(path, stamped64, plan, "SchemaUnsupported");
+        return error.SchemaUnsupported;
+    };
+
+    const verdict = classify(stamped, plan);
+    switch (verdict.action) {
+        .refuse_too_new => {
+            refusalLog(path, stamped64, plan, "SchemaTooNew");
+            return error.SchemaTooNew;
+        },
+        .refuse_unsupported => {
+            refusalLog(path, stamped64, plan, "SchemaUnsupported");
+            return error.SchemaUnsupported;
+        },
+        .open_current, .migrate => {},
+    }
+
+    if (verdict.restamp) try restampLegacy(database, path, verdict.logical);
+
+    switch (verdict.action) {
+        .migrate => {
+            const first = @as(usize, @intCast(verdict.logical - plan.minimum));
+            migrations.runMigration(
+                io,
+                dir,
+                path,
+                database,
+                plan.step_sql[first..],
+                verdict.logical,
+                plan.current,
+            ) catch |e| switch (e) {
+                // Two different states of the FILE — migrated and kept with its
+                // backup, or logically untouched — and one shared state of the
+                // CONNECTION: its pragmas are not what `applyPragmas`
+                // guarantees, so it must not serve. Closing it here is the
+                // single close either path gets. After a commit the next start
+                // opens the migrated file on the current-version lane; after a
+                // failure it retries the migration from the top.
+                error.MigrationCommittedButUnclean, error.MigrationFailedUnclean => {
+                    closeSlot(handle);
+                    return error.MigrationFailed;
+                },
+                error.MigrationBackupFailed => return error.MigrationBackupFailed,
+                error.MigrationFailed, error.NameTooLong => return error.MigrationFailed,
+                else => |other| return other,
+            };
+        },
+        .open_current => migrations.pruneBackupsConservative(io, dir, path),
+        else => unreachable,
+    }
+}
+
+/// Replaces the 0.0.12/0.0.13 fingerprint stamp with the logical version it
+/// stands for. This is the milestone's only real mutation of operator data, so
+/// it runs in its own transaction and any failure leaves the legacy stamp and
+/// every row exactly as they were — a refusal, never a recreate.
+fn restampLegacy(database: *db.Db, path: []const u8, logical: i32) Error!void {
+    var stamp_buf: [64]u8 = undefined;
+    const stamp = std.fmt.bufPrintZ(&stamp_buf, "PRAGMA user_version = {d};", .{logical}) catch
+        unreachable; // an i32 and a fixed prefix cannot overrun 64 bytes
+
+    restamp: {
+        var tx = db.Tx.begin(database) catch break :restamp;
+        database.exec(stamp) catch {
+            tx.rollback();
+            break :restamp;
+        };
+        tx.commit() catch {
+            tx.rollback();
+            break :restamp;
+        };
+        log.info("querylog database '{s}' carried the 0.0.12 schema fingerprint; " ++
+            "restamped as schema version {d}", .{ path, logical });
+        return;
+    }
+
+    var buf: [256]u8 = undefined;
+    fail("cannot restamp querylog database '{s}' as schema version {d}: {s}; " ++
+        "the file is unchanged", .{ path, logical, database.lastError(&buf) });
+    return error.MigrationFailed;
+}
+
+fn closeSlot(handle: *?db.Db) void {
+    if (handle.*) |*h| h.close();
+    handle.* = null;
+}
+
+fn refusalLog(path: []const u8, stamped: i64, plan: Plan, name: []const u8) void {
+    fail("refusing to open querylog database '{s}': it is stamped {d}, and this build " ++
+        "supports schema versions {d} to {d} ({s}). The file is left exactly as it is; " ++
+        "see docs/how-to/troubleshoot.md, \"The server refuses to start over querylog.db\"", .{
+        path, stamped, plan.minimum, plan.current, name,
+    });
+}
+
 /// An additional connection to a `querylog.db` that `open` has already
 /// established, with the pragmas every connection to the file needs.
 ///
@@ -244,16 +490,15 @@ fn quickCheck(database: *db.Db) db.Error!bool {
 /// What the aside file's name calls the reason it was set aside.
 ///
 /// The name is the only account of the reason an operator gets: the log line
-/// naming it scrolls away, the file stays for months. `fingerprint_mismatch` is
+/// naming it scrolls away, the file stays for months. Every tag here names real
-/// a database with nothing wrong with it — this build's DDL moved — so calling
+/// damage, which is the whole set of reasons left — a healthy file whose
-/// its file "corrupt" invites the operator to delete evidence of a healthy file.
+/// version this build cannot handle refuses the startup and is not renamed.
 fn asideTag(reason: RecreateReason) []const u8 {
     return switch (reason) {
         .missing => unreachable, // there is no file to rename
         .corrupt => "corrupt",
         .not_a_database => "not-a-database",
         .quick_check_failed => "quick-check-failed",
-        .fingerprint_mismatch => "schema-changed",
     };
 }
 
@@ -324,13 +569,23 @@ test "ddl creates the query-log tables and every index" {
     try database.exec(ddl);
 
     try testing.expectEqual(
-        @as(i64, 3),
+        @as(i64, 7),
         try database.queryInt("SELECT count(*) FROM sqlite_schema WHERE type='table'"),
     );
+    // The three explicit indexes plus `domains.domain`'s autoindex, and
+    // nothing else: the four projection tables are WITHOUT ROWID, so each
+    // one's PRIMARY KEY *is* its storage rather than a second b-tree to keep
+    // in step on every insert.
+    try testing.expectEqual(
+        @as(i64, 4),
+        try database.queryInt("SELECT count(*) FROM sqlite_schema WHERE type='index'"),
+    );
     const objects = [_][]const u8{
         "domains",              "query_log",
         "idx_query_log_ts",     "idx_query_log_client",
         "idx_query_log_domain", "querylog_meta",
+        "bucket_totals",        "bucket_clients",
+        "bucket_types",         "bucket_routes",
     };
     for (objects) |name| {
         var stmt = try database.prepare("SELECT count(*) FROM sqlite_schema WHERE name = ?1");
@@ -404,11 +659,14 @@ test "querylog_meta is seeded with one row the schema will not let a second join
     try testing.expectEqual(@as(i64, 1), try database.queryInt("SELECT count(*) FROM querylog_meta"));
 }
 
-test "the user_version statement stamps the fingerprint" {
+test "the user_version statement stamps the current schema version" {
     var database = try db.Db.open(":memory:", .{ .mode = .memory });
     defer database.close();
     try database.exec(set_user_version);
-    try testing.expectEqual(@as(i64, fingerprint), try database.queryInt("PRAGMA user_version"));
+    try testing.expectEqual(
+        @as(i64, versions.current_version),
+        try database.queryInt("PRAGMA user_version"),
+    );
 }
 
 // The behaviour these two cases describe — a resource error leaves the file on
@@ -437,7 +695,6 @@ test "the aside name says why, and a healthy file is never called corrupt" {
     try testing.expectEqualStrings("corrupt", asideTag(.corrupt));
     try testing.expectEqualStrings("not-a-database", asideTag(.not_a_database));
     try testing.expectEqualStrings("quick-check-failed", asideTag(.quick_check_failed));
-    try testing.expectEqualStrings("schema-changed", asideTag(.fingerprint_mismatch));
 }
 
 test "recreatable selects exactly two of db.Error's members" {
@@ -481,7 +738,7 @@ test "a recreate returns the aside name by value and a fresh create returns none
     try tmp.dir.access(io, kept, .{});
 }
 
-test "a recreate resets coverage to the new file and keeps the old one aside" {
+test "a corrupt file is recreated, coverage restarts, and the old one is kept aside" {
     var threaded: std.Io.Threaded = .init(testing.allocator, .{});
     defer threaded.deinit();
     const io = threaded.io();
@@ -498,21 +755,14 @@ test "a recreate resets coverage to the new file and keeps the old one aside" {
     try created.database.exec("INSERT INTO domains (domain) VALUES ('old.example');");
     created.database.close();
 
-    // A healthy file this build's DDL no longer matches — the case milestone
+    // Real damage, which is now the only thing that recreates.
-    // 28's own schema edit produces on every upgrade.
+    try tmp.dir.writeFile(io, .{ .sub_path = "querylog.db", .data = "not a database at all" });
-    {
-        var stamped = try db.Db.open(path, .{ .mode = .read_write_existing });
-        defer stamped.close();
-        var sql_buf: [64]u8 = undefined;
-        try stamped.exec(try std.fmt.bufPrintZ(&sql_buf, "PRAGMA user_version = {d};", .{fingerprint +% 1}));
-    }
 
     var recreated = try open(io, std.Io.Dir.cwd(), path);
     defer recreated.database.close();
 
-    try testing.expectEqual(RecreateReason.fingerprint_mismatch, recreated.recreated.?);
+    try testing.expectEqual(RecreateReason.not_a_database, recreated.recreated.?);
-    // The name says the file was healthy and this build moved, not that it rotted.
+    try testing.expect(std.mem.indexOf(u8, recreated.aside(), ".not-a-database-") != null);
-    try testing.expect(std.mem.indexOf(u8, recreated.aside(), ".schema-changed-") != null);
     try tmp.dir.access(io, std.fs.path.basename(recreated.aside()), .{});
 
     // Exactly one meta row, and coverage starts at the recreate rather than
@@ -551,3 +801,486 @@ test "a clean reopen reports no recreate and no aside" {
     try testing.expectEqual(@as(?RecreateReason, null), second.recreated);
     try testing.expectEqualStrings("", second.aside());
 }
+
+test "classification is a pure function of the stamp and the plan's three numbers" {
+    const plan: Plan = .{
+        .minimum = 1,
+        .current = 3,
+        .legacy_fingerprint = versions.legacy_fingerprint,
+        .step_sql = &.{},
+    };
+
+    try testing.expectEqual(Action.open_current, classify(3, plan).action);
+    try testing.expectEqual(Action.migrate, classify(1, plan).action);
+    try testing.expectEqual(Action.migrate, classify(2, plan).action);
+    try testing.expectEqual(Action.refuse_too_new, classify(4, plan).action);
+    try testing.expectEqual(Action.refuse_too_new, classify(versions.version_floor_guard, plan).action);
+    // Above the floor guard is not a version this project ever wrote.
+    try testing.expectEqual(
+        Action.refuse_unsupported,
+        classify(versions.version_floor_guard + 1, plan).action,
+    );
+    for ([_]i32{ 0, -1, -1_000_000, 603440875 }) |foreign| {
+        try testing.expectEqual(Action.refuse_unsupported, classify(foreign, plan).action);
+        try testing.expect(!classify(foreign, plan).restamp);
+    }
+
+    // The legacy fingerprint IS version 1, and being version 1 is what decides
+    // its lane.
+    const legacy = classify(versions.legacy_fingerprint, plan);
+    try testing.expectEqual(@as(i32, 1), legacy.logical);
+    try testing.expectEqual(Action.migrate, legacy.action);
+    try testing.expect(legacy.restamp);
+}
+
+test "a legacy stamp below a raised minimum refuses without a restamp" {
+    // What a future explicit break looks like from this side: the minimum has
+    // moved past 1, so the 0.0.12 file is no longer reachable. The ORDER is the
+    // point — mapping to 1 first and judging second is what stops the restamp
+    // from mutating a file this build will refuse anyway.
+    const after_break: Plan = .{
+        .minimum = 3,
+        .current = 3,
+        .legacy_fingerprint = versions.legacy_fingerprint,
+        .step_sql = &.{},
+    };
+
+    const legacy = classify(versions.legacy_fingerprint, after_break);
+    try testing.expectEqual(@as(i32, 1), legacy.logical);
+    try testing.expectEqual(Action.refuse_unsupported, legacy.action);
+    try testing.expect(!legacy.restamp);
+
+    // And versions 1 and 2, which the break dropped, refuse the same way.
+    try testing.expectEqual(Action.refuse_unsupported, classify(1, after_break).action);
+    try testing.expectEqual(Action.refuse_unsupported, classify(2, after_break).action);
+    try testing.expectEqual(Action.open_current, classify(3, after_break).action);
+}
+
+test "the production plan classifies a fresh stamp as current" {
+    try testing.expectEqual(
+        Action.open_current,
+        classify(versions.current_version, production_plan).action,
+    );
+    try testing.expect(classify(versions.legacy_fingerprint, production_plan).restamp);
+}
+
+/// The five lines every file-backed test below opens with.
+const Fixture = struct {
+    threaded: std.Io.Threaded,
+    tmp: std.testing.TmpDir,
+    buf: [256]u8 = undefined,
+
+    fn init() Fixture {
+        return .{
+            .threaded = .init(testing.allocator, .{}),
+            .tmp = testing.tmpDir(.{ .iterate = true }),
+        };
+    }
+
+    fn deinit(self: *Fixture) void {
+        self.tmp.cleanup();
+        self.threaded.deinit();
+    }
+
+    fn io(self: *Fixture) std.Io {
+        return self.threaded.io();
+    }
+
+    fn path(self: *Fixture) [:0]const u8 {
+        return std.fmt.bufPrintZ(&self.buf, ".zig-cache/tmp/{s}/querylog.db", .{self.tmp.sub_path}) catch
+            unreachable;
+    }
+
+    fn stamp(self: *Fixture, value: i32) !void {
+        var database = try db.Db.open(self.path(), .{ .mode = .read_write_existing });
+        defer database.close();
+        var sql: [64]u8 = undefined;
+        try database.exec(try std.fmt.bufPrintZ(&sql, "PRAGMA user_version = {d};", .{value}));
+    }
+
+    fn liveHandle(self: *Fixture) !?db.Db {
+        var database = try db.Db.open(self.path(), .{ .mode = .read_write_existing });
+        errdefer database.close();
+        try db.applyPragmas(&database, .{});
+        return database;
+    }
+
+    fn countMatching(self: *Fixture, prefix: []const u8) !usize {
+        var found: usize = 0;
+        var it = self.tmp.dir.iterate();
+        while (try it.next(self.io())) |entry| {
+            if (std.mem.startsWith(u8, entry.name, prefix)) found += 1;
+        }
+        return found;
+    }
+
+    fn expectModeOfOnlyMatch(self: *Fixture, prefix: []const u8, expected: std.posix.mode_t) !void {
+        var it = self.tmp.dir.iterate();
+        while (try it.next(self.io())) |entry| {
+            if (!std.mem.startsWith(u8, entry.name, prefix)) continue;
+            const stat = try self.tmp.dir.statFile(self.io(), entry.name, .{});
+            const mode = stat.permissions.toMode() & 0o777;
+            if (mode != expected) {
+                std.debug.print("mode of '{s}' is {o}, expected {o}\n", .{ entry.name, mode, expected });
+                return error.TestUnexpectedResult;
+            }
+            return;
+        }
+        std.debug.print("no file starting with '{s}'\n", .{prefix});
+        return error.TestUnexpectedResult;
+    }
+};
+
+test "a fresh file is stamped with the current schema version" {
+    var f: Fixture = .init();
+    defer f.deinit();
+
+    var created = try open(f.io(), std.Io.Dir.cwd(), f.path());
+    defer created.database.close();
+    try testing.expectEqual(RecreateReason.missing, created.recreated.?);
+    try testing.expectEqual(
+        @as(i64, versions.current_version),
+        try created.database.queryInt("PRAGMA user_version"),
+    );
+}
+
+test "a 0.0.13 file is restamped as version 1 and keeps every row" {
+    var f: Fixture = .init();
+    defer f.deinit();
+
+    {
+        var created = try open(f.io(), std.Io.Dir.cwd(), f.path());
+        defer created.database.close();
+        try created.database.exec("INSERT INTO domains (domain) VALUES ('kept.example');");
+    }
+    // Exactly what 0.0.12 and 0.0.13 wrote: the CRC of their DDL, which is this
+    // build's DDL unchanged.
+    try f.stamp(versions.legacy_fingerprint);
+    try testing.expectEqual(versions.legacy_fingerprint, fingerprint);
+
+    {
+        var upgraded = try open(f.io(), std.Io.Dir.cwd(), f.path());
+        defer upgraded.database.close();
+        try testing.expectEqual(@as(?RecreateReason, null), upgraded.recreated);
+        try testing.expectEqual(@as(i64, 1), try upgraded.database.queryInt("PRAGMA user_version"));
+        try testing.expectEqual(
+            @as(i64, 1),
+            try upgraded.database.queryInt("SELECT count(*) FROM domains WHERE domain = 'kept.example'"),
+        );
+    }
+
+    // Nothing was set aside on the way, and the second start is an ordinary
+    // current-version open.
+    try testing.expectEqual(@as(usize, 0), try f.countMatching("querylog.db.schema"));
+    var again = try open(f.io(), std.Io.Dir.cwd(), f.path());
+    defer again.database.close();
+    try testing.expectEqual(@as(?RecreateReason, null), again.recreated);
+    try testing.expectEqual(@as(i64, 1), try again.database.queryInt("PRAGMA user_version"));
+}
+
+test "a version this build cannot handle refuses and leaves the file alone" {
+    var f: Fixture = .init();
+    defer f.deinit();
+
+    {
+        var created = try open(f.io(), std.Io.Dir.cwd(), f.path());
+        defer created.database.close();
+        try created.database.exec("INSERT INTO domains (domain) VALUES ('kept.example');");
+    }
+    const watermark = blk: {
+        var probe = try db.Db.open(f.path(), .{ .mode = .read_write_existing });
+        defer probe.close();
+        break :blk try probe.queryInt("SELECT available_since FROM querylog_meta");
+    };
+
+    migrations.expected_failures.begin();
+    defer migrations.expected_failures.end();
+
+    const lanes = [_]struct { stamp: i32, expected: anyerror }{
+        .{ .stamp = versions.current_version + 1, .expected = error.SchemaTooNew },
+        .{ .stamp = versions.version_floor_guard, .expected = error.SchemaTooNew },
+        .{ .stamp = 0, .expected = error.SchemaUnsupported },
+        .{ .stamp = -3, .expected = error.SchemaUnsupported },
+        .{ .stamp = 603440875, .expected = error.SchemaUnsupported },
+    };
+
+    for (lanes) |lane| {
+        try f.stamp(lane.stamp);
+        try testing.expectError(lane.expected, open(f.io(), std.Io.Dir.cwd(), f.path()));
+
+        // Schema, rows, watermark and stamp all as they were, and nothing new
+        // beside the file.
+        var probe = try db.Db.open(f.path(), .{ .mode = .read_write_existing });
+        defer probe.close();
+        try testing.expectEqual(@as(i64, lane.stamp), try probe.queryInt("PRAGMA user_version"));
+        try testing.expectEqual(
+            @as(i64, 1),
+            try probe.queryInt("SELECT count(*) FROM domains WHERE domain = 'kept.example'"),
+        );
+        try testing.expectEqual(
+            watermark,
+            try probe.queryInt("SELECT available_since FROM querylog_meta"),
+        );
+        try testing.expectEqual(@as(usize, 0), try f.countMatching("querylog.db."));
+    }
+}
+
+test "a restamp that fails at the statement or at the commit refuses without loss" {
+    for ([_][]const u8{ "PRAGMA user_version = 1;", "COMMIT;" }) |failing| {
+        var f: Fixture = .init();
+        defer f.deinit();
+
+        {
+            var created = try open(f.io(), std.Io.Dir.cwd(), f.path());
+            defer created.database.close();
+            try created.database.exec("INSERT INTO domains (domain) VALUES ('kept.example');");
+        }
+        try f.stamp(versions.legacy_fingerprint);
+
+        migrations.expected_failures.begin();
+        defer migrations.expected_failures.end();
+        db.exec_faults.failNextMatching(failing);
+        defer db.exec_faults.disarm();
+
+        try testing.expectError(
+            error.MigrationFailed,
+            open(f.io(), std.Io.Dir.cwd(), f.path()),
+        );
+        try testing.expect(!db.exec_faults.armed());
+
+        // The legacy stamp and every row are exactly as they were: this is a
+        // refusal, and a refusal never costs the operator anything.
+        {
+            var probe = try db.Db.open(f.path(), .{ .mode = .read_write_existing });
+            defer probe.close();
+            try testing.expectEqual(
+                @as(i64, versions.legacy_fingerprint),
+                try probe.queryInt("PRAGMA user_version"),
+            );
+        }
+
+        // And the next start, with nothing injected, does the restamp properly.
+        var recovered = try open(f.io(), std.Io.Dir.cwd(), f.path());
+        defer recovered.database.close();
+        try testing.expectEqual(@as(i64, 1), try recovered.database.queryInt("PRAGMA user_version"));
+        try testing.expectEqual(
+            @as(i64, 1),
+            try recovered.database.queryInt("SELECT count(*) FROM domains WHERE domain = 'kept.example'"),
+        );
+    }
+}
+
+/// A one-step chain from the real current version to one above it. Nothing in
+/// the shipped chain can exercise migration while `step_sql` is empty, so the
+/// open path's migration lanes are driven through this instead.
+const synthetic_plan: Plan = .{
+    .minimum = versions.current_version,
+    .current = versions.current_version + 1,
+    .legacy_fingerprint = versions.legacy_fingerprint,
+    .step_sql = &.{"CREATE TABLE migration_marker (id INTEGER PRIMARY KEY);"},
+};
+
+test "a post-commit failure keeps the migration, keeps the backup, and refuses once" {
+    var f: Fixture = .init();
+    defer f.deinit();
+
+    {
+        var created = try open(f.io(), std.Io.Dir.cwd(), f.path());
+        defer created.database.close();
+        try created.database.exec("INSERT INTO domains (domain) VALUES ('kept.example');");
+    }
+
+    {
+        var handle = try f.liveHandle();
+        errdefer if (handle) |*h| h.close();
+
+        migrations.expected_failures.begin();
+        defer migrations.expected_failures.end();
+        // The first statement of the pragma restore, which runs only after a
+        // successful COMMIT.
+        db.exec_faults.failNextMatching("legacy_alter_table = OFF");
+        defer db.exec_faults.disarm();
+
+        try testing.expectError(
+            error.MigrationFailed,
+            openVersioned(f.io(), std.Io.Dir.cwd(), f.path(), &handle, synthetic_plan),
+        );
+        // Closed exactly once, by the open path: the slot it was handed is
+        // empty, so no caller can close it again.
+        try testing.expect(handle == null);
+    }
+
+    // The file IS migrated. The log said so, and this is what it meant.
+    {
+        var probe = try db.Db.open(f.path(), .{ .mode = .read_write_existing });
+        defer probe.close();
+        try testing.expectEqual(
+            @as(i64, synthetic_plan.current),
+            try probe.queryInt("PRAGMA user_version"),
+        );
+        try testing.expectEqual(
+            @as(i64, 1),
+            try probe.queryInt("SELECT count(*) FROM sqlite_schema WHERE name = 'migration_marker'"),
+        );
+        try testing.expectEqual(
+            @as(i64, 1),
+            try probe.queryInt("SELECT count(*) FROM domains WHERE domain = 'kept.example'"),
+        );
+    }
+    try testing.expectEqual(@as(usize, 1), try f.countMatching("querylog.db.pre-migrate-"));
+    // The backup is the whole query history at the moment of the migration, so
+    // it carries the live file's mode and not SQLite's `0644 & ~umask`.
+    try f.expectModeOfOnlyMatch("querylog.db.pre-migrate-", 0o600);
+
+    // The next start is ordinary: the current-version lane, no second
+    // migration, and the one backup still there for the operator.
+    var handle = try f.liveHandle();
+    defer if (handle) |*h| h.close();
+    try openVersioned(f.io(), std.Io.Dir.cwd(), f.path(), &handle, synthetic_plan);
+    try testing.expect(handle != null);
+    try testing.expectEqual(
+        @as(i64, synthetic_plan.current),
+        try handle.?.queryInt("PRAGMA user_version"),
+    );
+    try testing.expectEqual(@as(usize, 1), try f.countMatching("querylog.db.pre-migrate-"));
+}
+
+/// The same shape as `synthetic_plan`, with a step SQLite refuses to prepare. It
+/// drives the pre-commit failure path without any fault seam, leaving the seam
+/// free for the pragma restore.
+const failing_plan: Plan = .{
+    .minimum = versions.current_version,
+    .current = versions.current_version + 1,
+    .legacy_fingerprint = versions.legacy_fingerprint,
+    .step_sql = &.{"CREATE TABLE migration_marker (id INTEGER PRIMARY KEY) NOT A STATEMENT;"},
+};
+
+test "a pre-commit failure whose pragma restore also fails closes the connection" {
+    var f: Fixture = .init();
+    defer f.deinit();
+
+    {
+        var created = try open(f.io(), std.Io.Dir.cwd(), f.path());
+        defer created.database.close();
+        try created.database.exec("INSERT INTO domains (domain) VALUES ('kept.example');");
+    }
+
+    // The runner's own answer first: a failed restore is a DIFFERENT error from
+    // a failed migration, because the two leave the connection in different
+    // states even though they leave the file in the same one.
+    {
+        var handle = try f.liveHandle();
+        defer if (handle) |*h| h.close();
+
+        migrations.expected_failures.begin();
+        defer migrations.expected_failures.end();
+        db.exec_faults.failNextMatching("legacy_alter_table = OFF");
+        defer db.exec_faults.disarm();
+
+        try testing.expectError(error.MigrationFailedUnclean, migrations.runMigration(
+            f.io(),
+            std.Io.Dir.cwd(),
+            f.path(),
+            &handle.?,
+            failing_plan.step_sql,
+            failing_plan.minimum,
+            failing_plan.current,
+        ));
+        try testing.expect(!db.exec_faults.armed());
+    }
+
+    // And the open path's answer: the handle is closed, exactly as it is after a
+    // post-commit restore failure. A connection that may still hold
+    // `foreign_keys = OFF` never reaches the server.
+    {
+        var handle = try f.liveHandle();
+        errdefer if (handle) |*h| h.close();
+
+        migrations.expected_failures.begin();
+        defer migrations.expected_failures.end();
+        db.exec_faults.failNextMatching("legacy_alter_table = OFF");
+        defer db.exec_faults.disarm();
+
+        try testing.expectError(
+            error.MigrationFailed,
+            openVersioned(f.io(), std.Io.Dir.cwd(), f.path(), &handle, failing_plan),
+        );
+        try testing.expect(handle == null);
+    }
+
+    // The contrast that makes the rule visible, back at the runner, where the
+    // connection survives to be inspected: the same failing step with the
+    // restore working is a plain `MigrationFailed`, and that error promises the
+    // pragmas `applyPragmas` guarantees.
+    {
+        var handle = try f.liveHandle();
+        defer if (handle) |*h| h.close();
+
+        migrations.expected_failures.begin();
+        defer migrations.expected_failures.end();
+        try testing.expectError(error.MigrationFailed, migrations.runMigration(
+            f.io(),
+            std.Io.Dir.cwd(),
+            f.path(),
+            &handle.?,
+            failing_plan.step_sql,
+            failing_plan.minimum,
+            failing_plan.current,
+        ));
+        try testing.expectEqual(@as(i64, 1), try handle.?.queryInt("PRAGMA foreign_keys"));
+        try testing.expectEqual(@as(i64, 0), try handle.?.queryInt("PRAGMA legacy_alter_table"));
+    }
+
+    // No path committed anything, and every run deleted its own backup.
+    var probe = try db.Db.open(f.path(), .{ .mode = .read_write_existing });
+    defer probe.close();
+    try testing.expectEqual(
+        @as(i64, failing_plan.minimum),
+        try probe.queryInt("PRAGMA user_version"),
+    );
+    try testing.expectEqual(
+        @as(i64, 1),
+        try probe.queryInt("SELECT count(*) FROM domains WHERE domain = 'kept.example'"),
+    );
+    try testing.expectEqual(@as(usize, 0), try f.countMatching("querylog.db.pre-migrate-"));
+}
+
+test "a plain open retries a retention cleanup that once failed" {
+    var f: Fixture = .init();
+    defer f.deinit();
+
+    {
+        var created = try open(f.io(), std.Io.Dir.cwd(), f.path());
+        created.database.close();
+    }
+
+    // What a migration whose step-4 cleanup failed leaves behind: an older
+    // epoch, the newest epoch, and a same-second collision name tied with it.
+    const seeded = [_][]const u8{
+        "querylog.db.pre-migrate-1600000000",
+        "querylog.db.pre-migrate-1700000000",
+        "querylog.db.pre-migrate-1700000000-2",
+        "querylog.db.pre-migrate-handwritten",
+    };
+    for (seeded) |name| {
+        try f.tmp.dir.writeFile(f.io(), .{ .sub_path = name, .data = "x" });
+    }
+
+    var opened = try open(f.io(), std.Io.Dir.cwd(), f.path());
+    defer opened.database.close();
+    try testing.expectEqual(@as(?RecreateReason, null), opened.recreated);
+
+    // Only the strictly older epoch goes: both files tied at the newest epoch
+    // survive, because this pass cannot tell which of them a migration made,
+    // and a name it did not write is never its to delete.
+    try testing.expect(!try exists(&f, seeded[0]));
+    for (seeded[1..]) |name| try testing.expect(try exists(&f, name));
+}
+
+fn exists(f: *Fixture, name: []const u8) !bool {
+    f.tmp.dir.access(f.io(), name, .{}) catch |e| switch (e) {
+        error.FileNotFound => return false,
+        else => return e,
+    };
+    return true;
+}

src/storage/querylog_versions.zig

@@ -0,0 +1,89 @@
+//! The `querylog.db` schema version chain: comptime metadata and nothing else.
+//!
+//! Separate from `querylog_migrations.zig` so `tools/cut.zig` can import it
+//! without linking SQLite. Nothing in this file may reach for `db.zig`, for a
+//! C symbol, or for an allocator — the release gate reads these constants at
+//! build time, and a dependency here would drag the whole storage layer into
+//! the cut tool.
+//!
+//! **There are no migration hooks.** A step is a SQL file, period. Every
+//! shipped step is therefore byte-comparable against the previous tag, which is
+//! what lets the cut gate prove a released migration was never edited. A future
+//! change that genuinely cannot be expressed in SQL must amend this design in
+//! its own spec rather than adding a code path here.
+
+const std = @import("std");
+
+/// The version a file created by this build carries in `PRAGMA user_version`.
+pub const current_version: i32 = 1;
+
+/// The oldest stamped version this build can reach `current_version` from.
+/// A file stamped below this refuses to open.
+///
+/// An EXPLICIT BREAK in a future release is expressed here and only here: bump
+/// `current_version`, set `minimum_supported_version = current_version`, and
+/// ship no step. The chain then cannot reach the new version from below the
+/// minimum, so `open` refuses the old file by the ordinary rules. A break is
+/// always versioned, always refused at runtime, and never silent.
+pub const minimum_supported_version: i32 = 1;
+
+/// The literal `user_version` the 0.0.12 and 0.0.13 binaries stamped: the CRC32
+/// of their DDL text, under the pre-migration policy where a stamp mismatch
+/// meant "replace the file".
+///
+/// FROZEN. It is derived from nothing at build time on purpose — recomputing it
+/// from today's DDL would silently stop recognising the files it exists to
+/// recognise the moment the schema moves. Editing it strands every 0.0.12 and
+/// 0.0.13 file that has not yet been opened by a migration-aware build, which
+/// is why the cut gate fails on any change to this line.
+pub const legacy_fingerprint: i32 = 1975011655;
+
+/// Logical versions live far below any plausible CRC32 stamp. A value above
+/// this is not a version this project ever wrote, so it classifies as
+/// unsupported rather than as a from-the-future schema.
+pub const version_floor_guard: i32 = 1_000_000;
+
+/// One entry per shipped step: `step_sql[i]` migrates version
+/// `minimum_supported_version + i` to `minimum_supported_version + i + 1`.
+/// Each entry is `@embedFile("migrations/v<from>.sql")`, and each such file is
+/// immutable once released.
+///
+/// **Step-authoring rules** (the runner enforces the first, the equivalence
+/// oracle catches violations of the rest):
+///
+/// - A step contains no transaction statement. No `BEGIN`, no `COMMIT`, no
+///   `ROLLBACK`, no `SAVEPOINT`: the runner wraps the whole chain in one
+///   transaction and installs an authorizer that denies them outright.
+/// - A step that changes a table's shape must REBUILD it, so that the CREATE
+///   text SQLite stores ends up byte-identical to the fresh DDL's:
+///   `DROP` every view over `<t>` first; `ALTER TABLE <t> RENAME TO <t>_old`;
+///   `CREATE TABLE <t> ...` pasted verbatim from `querylog_schema.ddl`;
+///   `INSERT INTO <t> SELECT ... FROM <t>_old`; `DROP TABLE <t>_old`; recreate
+///   every index and trigger of `<t>` verbatim; recreate the dropped views
+///   verbatim last.
+/// - `ALTER TABLE ... ADD COLUMN` and `ALTER TABLE ... RENAME COLUMN` on a kept
+///   table are forbidden. SQLite rewrites the stored CREATE text under them,
+///   and the oracle's exact-text layer would rightly call the result unequal.
+pub const step_sql: []const [:0]const u8 = &.{};
+
+comptime {
+    std.debug.assert(minimum_supported_version >= 1);
+    std.debug.assert(minimum_supported_version <= current_version);
+    std.debug.assert(current_version <= version_floor_guard);
+    std.debug.assert(legacy_fingerprint < 0 or legacy_fingerprint > version_floor_guard);
+    std.debug.assert(step_sql.len == @as(usize, @intCast(current_version - minimum_supported_version)));
+}
+
+test "the chain covers exactly the supported range" {
+    try std.testing.expectEqual(
+        @as(usize, @intCast(current_version - minimum_supported_version)),
+        step_sql.len,
+    );
+}
+
+test "the legacy anchor is the literal 0.0.12 stamp" {
+    // Not `fingerprintOf(ddl)`. The number is a historical fact about released
+    // binaries, so a test that recomputed it would move with the schema and
+    // prove nothing.
+    try std.testing.expectEqual(@as(i32, 1975011655), legacy_fingerprint);
+}

src/storage/retention.zig

@@ -251,7 +251,7 @@ fn openLog() !db.Db {
 }
 
 fn writeRows(database: *db.Db, timestamps: []const i64) !void {
-    var writer = try queries_repo.BatchWriter.init(database);
+    var writer = try queries_repo.BatchWriter.init(testing.allocator, database);
     defer writer.deinit();
     var rows: [8]queries_repo.Row = undefined;
     for (timestamps, rows[0..timestamps.len]) |timestamp, *row| {

src/storage/storage_integration_test.zig

@@ -28,7 +28,9 @@ const model = @import("../config/model.zig");
 const validate = @import("../config/validate.zig");
 const db = @import("db.zig");
 const migrations = @import("migrations.zig");
+const querylog_migrations = @import("querylog_migrations.zig");
 const querylog_schema = @import("querylog_schema.zig");
+const querylog_versions = @import("querylog_versions.zig");
 
 const testing = std.testing;
 
@@ -354,7 +356,7 @@ test "S7 case 1: querylog open on a fresh directory creates the schema" {
 
     try testing.expectEqual(querylog_schema.RecreateReason.missing, result.recreated.?);
     try testing.expectEqual(
-        @as(i64, querylog_schema.fingerprint),
+        @as(i64, querylog_versions.current_version),
         try result.database.queryInt("PRAGMA user_version"),
     );
     try testing.expectEqual(
@@ -387,7 +389,7 @@ test "S7 case 2: reopening a healthy querylog recreates nothing" {
     try testing.expectEqual(@as(usize, 0), asides.items.items.len);
 }
 
-test "S7 case 3: a wrong user_version recreates and keeps the old file aside" {
+test "S7 case 3: a version this build cannot handle refuses and touches nothing" {
     if (!build_options.integration) return error.SkipZigTest;
 
     var f: Fixture = .init();
@@ -396,29 +398,42 @@ test "S7 case 3: a wrong user_version recreates and keeps the old file aside" {
 
     var buf: [path_buf_len]u8 = undefined;
     const path = try f.pathZ(&buf, "querylog.db");
-    try stampUserVersion(path, querylog_schema.fingerprint +% 1);
 
-    const original = try f.read("querylog.db");
+    querylog_migrations.expected_failures.begin();
-    defer testing.allocator.free(original);
+    defer querylog_migrations.expected_failures.end();
 
-    var result = try querylog_schema.open(io, std.Io.Dir.cwd(), path);
+    // Both refusal lanes, against a checkpointed file with no sidecars beside
-    defer result.database.close();
+    // it: a stamp above this build's version (a downgrade) and a stamp that is
-    try testing.expectEqual(
+    // not a version at all (a pre-0.0.12 fingerprint, or a foreign file).
-        querylog_schema.RecreateReason.fingerprint_mismatch,
+    const refusals = [_]struct { stamp: i32, expected: anyerror }{
-        result.recreated.?,
+        .{ .stamp = querylog_versions.current_version + 1, .expected = error.SchemaTooNew },
-    );
+        .{ .stamp = 0, .expected = error.SchemaUnsupported },
+        .{ .stamp = -7, .expected = error.SchemaUnsupported },
+        .{ .stamp = 603440875, .expected = error.SchemaUnsupported },
+    };
 
-    var asides = try collectAsides(&f);
+    for (refusals) |lane| {
-    defer asides.deinit();
+        try stampUserVersion(path, lane.stamp);
-    try testing.expectEqual(@as(usize, 1), asides.items.items.len);
+        try testing.expect(!try f.exists("querylog.db-wal"));
 
-    // The file was healthy: this build's schema moved, the database did not rot.
+        const original = try f.read("querylog.db");
-    // An operator who reads "corrupt" here deletes a file that was never broken.
+        defer testing.allocator.free(original);
-    try testing.expect(std.mem.startsWith(u8, asides.items.items[0], "querylog.db.schema-changed-"));
 
-    const kept = try f.read(asides.items.items[0]);
+        try testing.expectError(
-    defer testing.allocator.free(kept);
+            lane.expected,
-    try testing.expectEqualSlices(u8, original, kept);
+            querylog_schema.open(io, std.Io.Dir.cwd(), path),
+        );
+
+        // Byte-identical, not merely "still readable": nothing was rewritten,
+        // no aside was made, and no fresh database was created beside it.
+        const after = try f.read("querylog.db");
+        defer testing.allocator.free(after);
+        try testing.expectEqualSlices(u8, original, after);
+
+        var asides = try collectAsides(&f);
+        defer asides.deinit();
+        try testing.expectEqual(@as(usize, 0), asides.items.items.len);
+    }
 }
 
 test "S7 case 4: a garbage file recreates and the garbage is preserved" {
@@ -468,11 +483,11 @@ test "S7 case 5: two recreates in the same second produce two distinct aside fil
 
     var round: usize = 0;
     while (round < 2) : (round += 1) {
-        try stampUserVersion(path, querylog_schema.fingerprint +% 1);
+        try f.write("querylog.db", "not a database at all");
         var result = try querylog_schema.open(io, std.Io.Dir.cwd(), path);
         defer result.database.close();
         try testing.expectEqual(
-            querylog_schema.RecreateReason.fingerprint_mismatch,
+            querylog_schema.RecreateReason.not_a_database,
             result.recreated.?,
         );
     }
@@ -492,7 +507,7 @@ test "S7 case 6: a stale write-ahead log is removed before the fresh database is
 
     var buf: [path_buf_len]u8 = undefined;
     const path = try f.pathZ(&buf, "querylog.db");
-    try stampUserVersion(path, querylog_schema.fingerprint +% 1);
+    try f.write("querylog.db", "not a database at all");
 
     // Existence alone proves nothing: the fresh database turns WAL on again and
     // writes its own `-wal`. The marker is what distinguishes the stale file
@@ -503,7 +518,7 @@ test "S7 case 6: a stale write-ahead log is removed before the fresh database is
     var result = try querylog_schema.open(io, std.Io.Dir.cwd(), path);
     defer result.database.close();
     try testing.expectEqual(
-        querylog_schema.RecreateReason.fingerprint_mismatch,
+        querylog_schema.RecreateReason.not_a_database,
         result.recreated.?,
     );
 
@@ -591,7 +606,7 @@ test "S7 case 23: a locked querylog propagates Busy and is never destroyed" {
     defer reopened.database.close();
     try testing.expectEqual(@as(?querylog_schema.RecreateReason, null), reopened.recreated);
     try testing.expectEqual(
-        @as(i64, querylog_schema.fingerprint),
+        @as(i64, querylog_versions.current_version),
         try reopened.database.queryInt("PRAGMA user_version"),
     );
 

src/storage/testdata/querylog-v1-data.sql

@@ -0,0 +1,88 @@
+-- FROZEN FIXTURE. Representative content for a querylog.db at schema version 1,
+-- loaded on top of `querylog-v1-schema.sql`.
+--
+-- IMMUTABLE once released, for the same reason as its schema half: the release
+-- gate byte-compares it against the previous tag. A future schema version ships
+-- a NEW pair rather than editing this one.
+--
+-- The rows are chosen to be hard on a migration rather than realistic: every
+-- `route_kind`, the NULL variants of `qtype`, `cache_hit`, `response_time_us`,
+-- `upstream` and `forward_zone`, a non-IN qclass with a non-zero rcode, the
+-- group and source id/name pairs, `cname_target`/`safe_search_target`, an
+-- `available_since` that has been advanced away from its DDL default, and
+-- timestamps that straddle two 30-minute projection buckets.
+--
+-- The `bucket_*` rows below are the recomputation of the raw rows, transcribed
+-- from the same SQL `queries_repo`'s coherence oracle recomputes with. A
+-- fixture-validity test runs that oracle over this file BEFORE any migration,
+-- so an incoherent transcription fails on its own rather than as a migration
+-- bug.
+
+UPDATE querylog_meta SET created_at = 1699998000, available_since = 1699998600 WHERE id = 1;
+
+INSERT INTO domains (id, domain) VALUES
+    (1, 'ads.example'),
+    (2, 'news.example'),
+    (3, 'chat.example'),
+    (4, 'printer.lan'),
+    (5, 'nas.lan'),
+    (6, 'cdn.example');
+
+INSERT INTO query_log (
+    id, timestamp, domain_id, client_ip, qtype, blocked, response_time_us,
+    cache_hit, upstream, qclass, rcode, group_id, group_name, policy_action,
+    policy_reason, matched, source_id, source_name, cname_target,
+    safe_search_target, route_kind, forward_zone
+) VALUES
+    (1, 1699999260, 1, '10.0.0.1', 1, 1, NULL, 0, NULL, 1, 0, 7, 'kids',
+     'block', 'blocklist_domain', 'ads.example', 3, 'stevenblack', NULL, NULL,
+     'blocked', NULL),
+    (2, 1699999320, 2, '10.0.0.1', 28, 0, 1500, 0, '9.9.9.9:853', 1, 0, NULL,
+     NULL, 'allow', 'no_match', NULL, NULL, NULL, NULL, NULL, 'upstream', NULL),
+    (3, 1699999380, 2, '10.0.0.2', 1, 0, 90, 1, NULL, 1, 0, NULL, NULL,
+     'allow', 'no_match', NULL, NULL, NULL, NULL, NULL, 'cache', NULL),
+    (4, 1699999440, 3, '10.0.0.2', NULL, 0, NULL, NULL, NULL, 3, 4, NULL, NULL,
+     'not_evaluated', 'non_in_class', NULL, NULL, NULL, NULL, NULL, 'rejected',
+     NULL),
+    (5, 1699999500, 4, '10.0.0.3', 1, 0, 200, 0, NULL, 1, 0, NULL, NULL,
+     'not_evaluated', 'local_record', NULL, NULL, NULL, NULL, NULL, 'local',
+     NULL),
+    (6, 1700000700, 5, '10.0.0.3', 15, 0, 3400, 0, NULL, 1, 0, NULL, NULL,
+     'not_evaluated', 'forward_zone', NULL, NULL, NULL, NULL, NULL,
+     'forward_zone', 'lan.example'),
+    (7, 1700001060, 1, '10.0.0.1', 1, 1, NULL, 0, NULL, 1, 0, 7, 'kids',
+     'block', 'blocklist_wildcard', '*.ads.example', 3, 'stevenblack', NULL,
+     NULL, 'blocked', NULL),
+    (8, 1700001120, 6, '10.0.0.4', 65, 0, 2500, 1, '1.1.1.1:853', 1, 0, NULL,
+     NULL, 'allow', 'no_match', NULL, NULL, NULL, 'edge.cdn.example',
+     'forcesafesearch.example', 'upstream', NULL);
+
+INSERT INTO bucket_totals (bucket, queries, blocked, cached, rt_sum, rt_count) VALUES
+    (1699999200, 6, 1, 1, 5190, 4),
+    (1700001000, 2, 1, 1, 2500, 1);
+
+INSERT INTO bucket_clients (bucket, client_ip, queries) VALUES
+    (1699999200, '10.0.0.1', 2),
+    (1699999200, '10.0.0.2', 2),
+    (1699999200, '10.0.0.3', 2),
+    (1700001000, '10.0.0.1', 1),
+    (1700001000, '10.0.0.4', 1);
+
+-- qtype -1 is the lossless encoding of the NULL qtype on row 4.
+INSERT INTO bucket_types (bucket, qtype, count) VALUES
+    (1699999200, -1, 1),
+    (1699999200, 1, 3),
+    (1699999200, 15, 1),
+    (1699999200, 28, 1),
+    (1700001000, 1, 1),
+    (1700001000, 65, 1);
+
+INSERT INTO bucket_routes (bucket, route_kind, source_present, source_text, count) VALUES
+    (1699999200, 'blocked', 0, '', 1),
+    (1699999200, 'cache', 0, '', 1),
+    (1699999200, 'forward_zone', 1, 'lan.example', 1),
+    (1699999200, 'local', 0, '', 1),
+    (1699999200, 'rejected', 0, '', 1),
+    (1699999200, 'upstream', 1, '9.9.9.9:853', 1),
+    (1700001000, 'blocked', 0, '', 1),
+    (1700001000, 'upstream', 1, '1.1.1.1:853', 1);

src/storage/testdata/querylog-v1-schema.sql

@@ -0,0 +1,88 @@
+-- FROZEN FIXTURE. querylog.db schema version 1: byte-for-byte the `ddl` text of
+-- `src/storage/querylog_schema.zig`, which is the schema the 0.0.12 and 0.0.13
+-- binaries created and the one version 1 names.
+--
+-- IMMUTABLE once released. The release gate byte-compares this file against the
+-- previous tag and fails the cut on any edit, because it is the starting point
+-- every future migration is proved against: editing it would prove a migration
+-- against a file no operator ever had. A new schema version ships a NEW pair.
+--
+-- The `PRAGMA user_version` stamp is deliberately NOT part of this file. The
+-- loader applies it, which is what lets one fixture serve both the version-1
+-- stamp and the 0.0.12/0.0.13 legacy fingerprint.
+
+CREATE TABLE domains (
+    id INTEGER PRIMARY KEY,
+    domain TEXT NOT NULL UNIQUE
+);
+
+CREATE TABLE query_log (
+    id INTEGER PRIMARY KEY,
+    timestamp INTEGER NOT NULL,
+    domain_id INTEGER NOT NULL REFERENCES domains(id),
+    client_ip TEXT NOT NULL,            -- text, not a FK: log rows are immutable facts
+    qtype INTEGER,
+    blocked INTEGER NOT NULL,
+    response_time_us INTEGER,
+    cache_hit INTEGER,
+    upstream TEXT,
+    qclass INTEGER NOT NULL,
+    rcode INTEGER NOT NULL,
+    group_id INTEGER,                   -- text/id pairs, not FKs: a renamed
+    group_name TEXT,                    -- group must not rewrite history
+    policy_action TEXT NOT NULL,
+    policy_reason TEXT NOT NULL,
+    matched TEXT,
+    source_id INTEGER,
+    source_name TEXT,
+    cname_target TEXT,
+    safe_search_target TEXT,
+    route_kind TEXT NOT NULL,
+    forward_zone TEXT,
+    CHECK (rcode BETWEEN 0 AND 4095)    -- twelve bits (RFC 6891 6.1.3)
+);
+CREATE INDEX idx_query_log_ts ON query_log(timestamp);
+CREATE INDEX idx_query_log_client ON query_log(client_ip);
+CREATE INDEX idx_query_log_domain ON query_log(domain_id);
+
+CREATE TABLE querylog_meta (
+    id INTEGER PRIMARY KEY CHECK (id = 1),   -- one row, enforced by the schema
+    created_at INTEGER NOT NULL,
+    available_since INTEGER NOT NULL
+);
+INSERT INTO querylog_meta (id, created_at, available_since)
+VALUES (1, unixepoch(), unixepoch() + 1);
+
+CREATE TABLE bucket_totals (
+    bucket INTEGER PRIMARY KEY,
+    queries INTEGER NOT NULL,
+    blocked INTEGER NOT NULL,
+    cached INTEGER NOT NULL,
+    rt_sum INTEGER NOT NULL,     -- sum(response_time_us) over timed rows
+    rt_count INTEGER NOT NULL    -- count(response_time_us)
+) WITHOUT ROWID;
+
+CREATE TABLE bucket_clients (
+    bucket INTEGER NOT NULL,
+    client_ip TEXT NOT NULL,
+    queries INTEGER NOT NULL,
+    PRIMARY KEY (bucket, client_ip)
+) WITHOUT ROWID;
+
+CREATE TABLE bucket_types (
+    bucket INTEGER NOT NULL,
+    qtype INTEGER NOT NULL,      -- -1 encodes a NULL qtype, losslessly
+    count INTEGER NOT NULL,
+    PRIMARY KEY (bucket, qtype)
+) WITHOUT ROWID;
+
+CREATE TABLE bucket_routes (
+    bucket INTEGER NOT NULL,
+    route_kind TEXT NOT NULL,
+    source_present INTEGER NOT NULL,  -- 0: source NULL; 1: source = source_text
+    source_text TEXT NOT NULL,        -- '' when source_present = 0
+    count INTEGER NOT NULL,
+    PRIMARY KEY (bucket, route_kind, source_present, source_text),
+    CHECK (source_present IN (0, 1)),
+    CHECK (source_present = 1 OR source_text = '')
+) WITHOUT ROWID;

src/tests.zig

@@ -40,7 +40,10 @@ comptime {
     _ = @import("config/faults.zig");
     _ = @import("storage/config_schema.zig");
     _ = @import("storage/migrations.zig");
+    _ = @import("storage/querylog_migrations.zig");
     _ = @import("storage/querylog_schema.zig");
+    _ = @import("storage/querylog_versions.zig");
+    _ = @import("storage/querylog_fixtures.zig");
     _ = @import("storage/provenance.zig");
     _ = @import("storage/repositories/context.zig");
     _ = @import("storage/repositories/crud.zig");
@@ -106,7 +109,7 @@ comptime {
     _ = @import("web/server_integration_test.zig");
     _ = @import("server/local_tables.zig");
     _ = @import("web/metrics.zig");
-    _ = @import("web/handlers/stats.zig");
+    _ = @import("web/handlers/overview.zig");
     _ = @import("web/handlers/queries.zig");
     _ = @import("web/handlers/diagnostics.zig");
     _ = @import("web/handlers/lookup.zig");

src/upstream/dot_client_integration_test.zig

@@ -458,7 +458,7 @@ test "a session the upstream closed is recovered by one redial and counted, not
         .priority = 10,
         .enabled = true,
         .health = .init,
-        .sem = .{ .permits = slots.len },
+        .admission = .{ .permits = slots.len },
         .reuse_recoveries = &fixture.recoveries,
     }};
     var pool: pool_mod.Pool = .init(&entries, .{