# Milestone 25: client names learned over reverse DNS

Goal: the clients table names devices by itself. The tracker already materialises every querying address into a `clients` row (PLAN §7.2, `src/server/clients.zig`), but `name` stays NULL until the operator types one — which defeats the point of auto-materialisation on a LAN whose router already knows every DHCP hostname. This milestone asks the router: for each unnamed client, nxdns builds the address's reverse name, matches it against the operator's conditional forward zones (PLAN §6.5), sends one PTR query to the zone's resolver, and stores the answer as a *learned* name — runtime state beside `last_seen`, never configuration. The dashboard shows it; a hand-typed name always wins; a reverse name no forward zone covers is never sent anywhere.

Design written 2026-08-14 against HEAD `c428bc2`, revised after a Codex review of the first draft (all 19 findings accepted; the review's fingerprints are called out inline where a first-draft claim was wrong).

## Implementation contract (read first)

- Read `AGENTS.md`, then this spec whole, before session work starts.
- **The v1 baseline is editable and there is no migration step** (milestone-24 ruling 1 stands unchanged). The two new columns are lines edited into `config_schema.ddl_v1` plus the identical lines in PLAN §11.2, kept byte-identical. A `ddl_v2` or a second `Step` is wrong and must be reverted. A development database stamped version 1 before the edit fails its first `SELECT` naming the columns; delete the scratch database.
- The new `src/local/reverse_name.zig` is pure: bytes in, bytes out, no `std.Io`, no clock, no sockets. (The blanket claim "src/local/ is pure" from the first draft was false — `forward_client.zig` does socket I/O by design; the purity requirement here binds the *new* module and the lookup-table modules it sits beside.) Everything that touches the network or the database lives in `src/server/`.
- After the API shape change, regenerate `web/src/lib/contractSamples.gen.ts` with the AGENTS.md command (never a hand edit) and update `web/src/lib/types.ts` to match, in the same session.
- Verify stdlib claims against `../zig` at tag 0.16.0. `specs/research/` holds verified notes. One verified here: randomness is on the `Io` interface — `io.random(buffer)` (`std/Io.zig:2468`); `std.crypto.random` does not exist in 0.16.0.
- No `std.log.err` in new code. PTR answers are untrusted bytes: never let one reach a log line, a metric label, or the UI without passing `acceptHostname` (ruling 4).

## Rulings (binding)

### 1. When: the tracker's flush pass resolves, bounded, serial, last

Resolution is a step appended to the tracker's existing flush pass (`Tracker.flushOnce`, `src/server/clients.zig:164`), not a new loop and not a query-path hook. Reasons: the pass already runs every `flush_interval_s` (60 s) on a dedicated task with a dedicated `config.db` connection (app.zig:523-524,
:754), it already respects the disk-monitor gate, and a name can only be
learned for a row that exists — which the flush itself just wrote. A DNS query must never wait on naming, and with this placement it structurally cannot.

**Order within one pass is fixed: drain-and-write, then prune (when due), then resolve.** One `now_s` is read at the top of the pass and used by all three steps. Resolving before pruning could spend PTR queries on rows the same pass deletes; the fixed order makes that impossible, and a test proves a row past the prune cutoff on a due pass causes no exchange.

Per pass, the resolver:

- selects at most `max_per_pass = 16` candidate rows (ruling 3 defines a candidate), ordered by `name_attempt_after` ascending then ip;
- resolves them **serially** — in-flight is exactly 1. At 16 per 60 s pass the LAN resolver sees at most ~0.27 queries/second from naming.

**Naming has its own read timeout**, `ptr_read_timeout` = 2 s on the `.awake` clock, a `pub const` on the resolver — it does *not* inherit the handler's `forward_read_timeout`, which the operator may have set as high as the upstream budget. **The budget bounds the whole attempt, not one transport leg**: `ForwardClient` hands its duration to the UDP receive and then again to the TCP fallback, so a resolver that answers UDP late with TC=1 and then stalls TCP would spend up to 2× the budget per attempt — 64 s per pass, not
32. The default `exchangeFn` therefore wraps the entire `ForwardClient` exchange in `transport.raceWithin(io, ptr_read_timeout, ...)` (the same mechanism `exchangeTcp` itself uses, forward_client.zig:195), so UDP, fallback and all share one deadline. The worst case is 16 × 2 s = 32 s of naming per pass, and that number is a bound, not an estimate. That is acceptable because the drain already ran first: a slow pass delays the *next* pass's start (the run loop sleeps after `flushOnce` returns), and one extra interval against a 512-slot pending table on a household LAN drops nothing. The acceptance test for this: with a stub client that times out on every exchange, the pass still drains its pending batch before any exchange is attempted, and attempts stop at `max_per_pass`.

Retry cadence is split by outcome (first draft used one 24 h cadence for everything, which left a freshly-declared zone, a recovered router, or a fixed resolver unnamed for a day while forward-zone changes publish live):

- **definitive** outcomes (`answered`, `nxdomain`): next attempt after `refresh_after_s = 86_400` — the daily refresh that tracks DHCP renames;
- **non-definitive** outcomes (`no_zone`, `failed`, `invalid`): next attempt after `retry_after_s = 3_600` — an operator who declares the missing zone or fixes the resolver sees names within the hour, and a dead resolver costs at most 16 timeouts per hour, not per minute.

Both constants are `pub const` on the resolver; no config knob (household scale, AGENTS.md: no generality nobody asked for).

### 2. Where: only through a declared forward zone, never the pool

The reverse name (`10.1.168.192.in-addr.arpa`, or the 32-nibble `ip6.arpa` form) is matched against the live forward-zones table — the same `forward_zones.Zones.match` the query path uses, bracketed by `LocalTables.acquire`/`release` (`src/server/local_tables.zig:48`), so naming always sees the generation the operator last published.

**The zone's `resolver` is copied by value under the shared lock, and the handle is released before any socket work.** `match` returns a pointer into the current table generation, and `swap` frees the old generation as soon as it holds the exclusive lock — a handle held across a PTR exchange, or a released handle whose `*const Zone` is still dereferenced, is a use-after-free against a config reload. `validate.Resolver` is a plain value; the copy is the whole fix. A regression test must place the `swap` **inside the hazard window** — after the handle release, before the copied resolver is used. A test that swaps before `runPass` evaluates its arguments exercises nothing (the first implementation's test had exactly this defect: the stub's exchange performed the swap, but the resolver had already been copied into the call's arguments, so the test passed regardless of what production retained). The required shape: two candidates in one pass, two generations whose zones cover both but carry **different resolver ports**; the stub `exchangeFn` performs the swap during the *first* attempt (freeing the old generation under `testing.allocator`) and records each attempt's resolver. Assertions: the first attempt's resolver still reads the old generation's port after the swap (the copy, not freed memory), and the second attempt's resolver reads the *new* generation's port (each attempt re-acquires; no table pointer or handle is cached across attempts). With a production `runPass` that retains `*const Zone` or the handle across the release, the first assertion reads freed memory and the second reads the stale generation — either fails.

- Match found: one PTR query to that zone's resolver through `forward_client.ForwardClient`, built per attempt as `Context.viaForwardZone` builds one (handler.zig:411), with `ptr_read_timeout` (ruling 1).
- No match: **no query is sent to anyone** — not the pool, not any resolver. The attempt counts under `no_zone` and retries per ruling 1.

Scope of the promise, stated precisely (the first draft's "never to a public resolver" claimed more than the code enforces): what this milestone guarantees is that a reverse name reaches **only the resolver of a zone the operator declared**, and never the upstream pool. `parseResolver` (validate.zig:274) accepts any IP literal, so an operator who declares `168.192.in-addr.arpa → udp://8.8.8.8:53` has pointed their private reverse space at a public resolver — that is their declaration, and nxdns does not second-guess it, any more than it second-guesses the same zone for forward queries. Likewise nxdns cannot stop a declared LAN resolver forwarding onward. The docs (ruling 11) say this in one sentence.

The DNS cache is not consulted and not written: one PTR per client per day is not worth a cache entry, and bypassing the cache keeps the resolver a plain consumer of the exchange seam.

### 3. Precedence: the operator's name always wins; NXDOMAIN clears

Schema (ruling 5) keeps learned names in their own column, so precedence is a display rule, not a write conflict — `name` is never written by this feature and `learned_name` is never written by the operator.

A **candidate** row satisfies both of:

- `name IS NULL OR name = ''` — a row whose displayed name would come from learning. `hand_edited` does not appear in the predicate (the first draft had it; display precedence never consults it, so candidacy must not either): a hand-edited row the operator grouped but did not name still benefits, and a named row is skipped whatever its flag — its learned name would never be shown.
- `name_attempt_after <= now_s` (ruling 6 gives the exact SQL).

Outcomes of an attempt, written through one repo call (ruling 6), each setting `name_attempt_after` per ruling 1's cadence:

- **Answer with a valid PTR target**: store it in `learned_name` (lowercased, no trailing dot), overwriting whatever learned name was there — the router is the authority on its own zone, and a changed answer is a renamed device, not a conflict. A test covers the overwrite: two attempts, two different valid targets, second wins.
- **NXDOMAIN, or NOERROR with no matching PTR record** (NODATA): clear `learned_name` to NULL. The router affirmatively says the address has no name; keeping a stale one would show a device under its previous owner's hostname after a lease change.
- **Everything else** — transport error, any RCODE other than NOERROR and NXDOMAIN (REFUSED, FORMERR, SERVFAIL, unknown values), malformed reply, invalid hostname (ruling 4): keep the stored `learned_name` as it stands, count under `failed` (or `invalid`). An outage must not strip names from the whole dashboard.

  **"RCODE" here is the full 12-bit value**: the header's 4 bits extended by the OPT record's upper 8 bits when the response carries one (`packet.findOptRecord` locates it; `dns/edns.zig` decodes it). A response whose header says NOERROR under a nonzero extended RCODE is a failure, not an answer and not NODATA — classifying on the header nibble alone would store or clear a name on what the resolver called an error. An OPT record that fails to parse makes the whole reply malformed (`failed`, keep). The first implementation had exactly this bug; the regression test is a NOERROR header + OPT with a nonzero extended RCODE, asserting `failed` counts and the stored name survives — it must fail with the classification reverted to header-only.

**Staleness bound, stated honestly:** an address reassigned to a new device immediately after a successful lookup shows the previous device's hostname for up to `refresh_after_s` (24 h) — the next refresh then overwrites or clears it. That bound is accepted: it matches the prune cadence's granularity, and tightening it means more PTR traffic for a cosmetic lag. The docs state the bound.

`upsertSeen`, `updateClient`, `pruneStale` and the reconcile engine are untouched: a pruned row takes its learned name with it, a re-materialised device is re-learned within a pass, and `updateClient` writing a name removes the row from candidacy (the name predicate) without touching `learned_name`.

### 4. PTR answers are untrusted input: `acceptHostname` gates everything

The answer bytes come from whatever box the operator pointed a zone at, and they land in a UI. Validation has three layers, all required:

1. **Transport**: `transport.validateResponse` (ID and question echo — that is *all* it checks; the first draft leaned on it for more).
2. **Record selection**: walk `packet.answers`; the accepted record is the **first** whose `rtype` is `.ptr`, whose class is `.in`, and whose owner name equals the queried reverse name case-insensitively (`name.eqlIgnoreCase`, name.zig:185). Records failing any of these are skipped, not errors; an answer section with no accepted record under RCODE NOERROR is NODATA (ruling 3 clears). Extra accepted records after the first are ignored.
3. **Hostname shape**: the PTR target decodes via `record.rdataCname` (record.zig:101 handles PTR) and formats via `name.formatText`; the text is accepted only if every byte is in `[a-z0-9._-]` after ASCII-lowercasing `A-Z`, labels are 1–63 bytes, the whole name is ≤ 253 bytes, no label starts or ends with `-`, and there is no empty label (which also rejects a trailing dot — `formatText` emits none, so one appearing is malformed). Underscore is included because real DHCP hostnames carry it; nothing else is. A failing target counts under `invalid` and keeps the stored name.

`acceptHostname` is a pure function in `src/local/reverse_name.zig`, tested against: the empty string, a 254-byte name, a 64-byte label, `a b`, `a\x00b`, `héllo`, `-x`, `x-.y`, `a..b`, `.a`, `a.` (trailing dot), and accepting `nas-1.lan`, `my_printer.home`, `x`.

### 5. Schema: two runtime columns, not a reuse of `name`

`clients` gains, in `config_schema.ddl_v1` directly after `name`:

```sql
    learned_name TEXT,
    name_attempt_after INTEGER NOT NULL DEFAULT 0,
```

with the identical lines in PLAN §11.2. `name_attempt_after` is the epoch second before which the resolver will not attempt this row again; 0 (the default, and every pre-existing row) means "eligible now". Storing the *next* attempt rather than the *last* one keeps the candidate predicate a plain comparison (no addition that could overflow on a corrupt value, no special case for "never attempted") and lets one column carry ruling 1's two cadences.

Reusing `name` with a provenance marker was rejected: `name` feeds `listClients`, which feeds `nxdns export`, and a learned name in an export would turn runtime state into configuration — it would churn export diffs as leases move, and under file authority the next reconcile would fight it. With separate columns:

- **Export/import untouched.** `listClients` selects `name` only (clients_repo.zig:33-38); no code change, and a test proves an export before and after a learned name lands is byte-identical.
- **Reconcile untouched.** The engine never touches runtime columns; the learned columns ride the row exactly as `last_seen` does. Promotion (declaring an observed address) keeps them; deletion of a declared row drops them with the row, correctly.
- **File-authority mode needs no write rule.** Naming is a runtime write like `upsertSeen`, permitted in both authority modes for the same reason. In file mode the operator's *declared* name wins through the ordinary precedence (a non-empty `name` removes the row from candidacy after the reconcile writes it), and the learned name stays display-only runtime state.

The baseline test in `src/storage/migrations.zig` ("a fresh database reaches the baseline...") gains `columnExists` probes for both columns.

### 6. Repo surface: two calls, owned by the resolver

`src/storage/repositories/clients_repo.zig`, in the runtime section beside `upsertSeen` / `pruneStale`:

- `resolveCandidates(database, out, now_s)` — fills a caller-supplied fixed-capacity buffer (capacity `max_per_pass`, each slot `logger.max_client_len` bytes — the bound every address text in this program is sized by) and returns the filled slice or count. **No allocation**: the candidate set is small by construction and the resolver runs on the tracker's task, which owns no allocator today. The WHERE clause, exactly:

  ```sql
  (name IS NULL OR name = '') AND name_attempt_after <= ?1
  ORDER BY name_attempt_after, ip LIMIT 16
  ```

  Tests cover: `now_s` smaller than any cadence constant still selects never-attempted rows (`DEFAULT 0`); the boundary `name_attempt_after = now_s` selects; `now_s + 1` does not; an extreme stored value (`i64` max) never selects and never traps.
- `noteNameOutcome(database, ip, outcome)` where the outcome carries `attempt_after: i64` and one of: store `text`, clear, keep. One UPDATE: always sets `name_attempt_after`; sets `learned_name` to the text on store, to NULL on clear, leaves it alone on keep. **A row deleted between selection and this call makes the UPDATE touch zero rows; that is a no-op by design, not an error and not a counter** — the device left, and nothing was learned about nothing.

`ClientRow` gains `learned_name: []const u8` (NULL reads as `""`, like `name`); `readClientRow` and both SELECTs carry it. `name_attempt_after` is **not** exposed on `ClientRow` or the API — it is scheduling state with no operator meaning, and keeping it out keeps the contract surface one field. `listClients` (export) is not widened — that is the point of ruling 5.

### 7. The resolver module: `src/server/client_names.zig`

New file. A `Resolver` struct owning:

- `stats: Stats` with the six **outcome** counters `attempted`, `answered`, `nxdomain`, `no_zone`, `invalid`, `failed`, plus two counters *outside* the outcome sum: `read_failures` (the candidate SELECT failed; the pass skips naming) and `write_failures` (`noteNameOutcome` failed; the outcome was still counted). Guarded by the tracker's mutex pattern, with a `snapshotStats`. Invariant, asserted in a test: `attempted` equals `answered + nxdomain + no_zone + invalid + failed`. Database failures log at most one `warn` per pass each for reads and writes, tracker-style (clients.zig:181-186); network failures are the counters' job and log nothing new (the `forward_client` module's existing `debug`-level diagnostics are exempt from this milestone's no-log rule — they predate it, are debug-level, and suppressing them per-caller would fork the client).
- an **exchange seam**: production code cannot inject into `ForwardClient` (it is a concrete struct the resolver constructs), so the seam sits above it — a field `exchangeFn: *const fn (io, validate.Resolver, query, response_buf) transport.ExchangeError![]u8` defaulting to a function that builds a stack `ForwardClient` with `ptr_read_timeout` and calls `exchange`. Tests replace the pointer; the production default is itself covered by one test against a loopback UDP socket if one already exists in the suite's patterns, otherwise by the live smoke. The no-zone test runs the **production** pass code with a counting stub and asserts the count stays 0.
- a `runPass(io, database, tables, now_s)`: select candidates (ruling 6), and for each — build the reverse name (pure, ruling 8), acquire/match/**copy resolver**/release (ruling 2), build the PTR query: header with a random id filled from `io.random` (`std/Io.zig:2468` — *not* `std.crypto.random`, which 0.16.0 does not have), RD set, one question, qtype `.ptr`, qclass `.in`, encoded with `dns/header` + `dns/question.encode`; exchange through the seam, classify per rulings 3–4, write per ruling 6. The id is test-visible through the seam (the stub sees the query bytes), so no determinism hook is needed beyond the seam itself.

Wiring: `Tracker.flushOnce` gains an optional `*client_names.Resolver` parameter, invoked **after** the drain/write and prune steps (ruling 1's order); `app.zig` constructs the Resolver beside the tracker (holding the `*LocalTables` pointer) and passes it through `Tracker.run`'s arguments (app.zig:754). The resolver runs on the tracker's task against `tracker_db` — the dedicated-connection rule (clients.zig:127-131) is satisfied because it is the *same* task, serial with the flush. A gated pass (disk critical) skips naming too: naming writes.

### 8. The pure part: `src/local/reverse_name.zig`

New file, pure (no Io, no clock). Two functions plus their tests:

- `reverseName(addr: address.NetAddress, buf: *[max_reverse_len]u8) []const u8` — `d.c.b.a.in-addr.arpa` for v4, the 32-nibble lowercase `ip6.arpa` form for v6. `max_reverse_len` is a comptime bound (v6 form: 32 nibbles · 2 + 8 for `ip6.arpa` = 72; compute, don't hand-wave). An IPv4-mapped v6 address was already canonicalised to `ip4` by `NetAddress` (clients.zig test at :305 proves the tracker's addresses are canonical) — assert, don't re-handle.
- `acceptHostname(text: []const u8) bool` — ruling 4's gate, with ruling 4's test table.

`src/platform/address.zig` types are plain values; importing them into `local/` keeps the module pure. Register the file in `src/tests.zig` the way its siblings are registered.

### 9. Failure visibility: one metrics group

The resolver must be reachable from `metrics.collect`, which reads `server.WebState` — so `src/web/server.zig`'s `WebState` gains an optional `client_names: ?*client_names.Resolver` collaborator, populated by `app.zig` beside `tracker` (the first draft wired the sample and forgot the state; S2 owns `src/web/server.zig` for this field). `src/web/metrics.zig`: `Sample` gains `client_names: ?client_names.Resolver.Stats`, collected beside the tracker's (metrics.zig:191-193) and rendered as `counterGroup(w, "nxdns_client_names_", ...)` beside `nxdns_clients_` (metrics.zig:333-334). `counterGroup` renders every struct field, so all eight counters (six outcomes + `read_failures` + `write_failures`) surface without per-field code. The render test pins one line (e.g. `nxdns_client_names_no_zone_total`).

### 10. API and UI: learned is visible and visibly different

- `GET /api/clients` rows carry `learned_name` (`src/web/openapi.yaml` `required` + `properties` for the client schema; contract samples regenerated; `web/src/lib/types.ts` client row type gains `learned_name: string`). `name_attempt_after` stays internal (ruling 6).
- `web/src/features/clients/ClientsPage.tsx`: the name cell shows `name` when non-empty; otherwise `learned_name` in the page's existing muted text style with a visually-distinct treatment that marks it as learned (exact affordance is the implementer's, but: no new colour system, reuse the muted style the page already has, and the distinction must survive a screen reader — an `aria-label` or visible suffix, not colour alone). An empty both shows what it shows today.
- `ClientEditDialog.tsx` may pre-fill its name field with `learned_name` when `name` is empty — adopting the learned name as a typed name is the natural gesture — but saving still goes through the ordinary PUT and sets `hand_edited` server-side as today. This applies in database-authority mode only; in file mode client edits answer 403 as they do today, and the file-mode story is ruling 5's (declared name wins via candidacy).
- Mocks in `ClientsPage.test.tsx` gain the field with distinct values; rendering tests assert: a named row shows `name` and not `learned_name`; an unnamed row shows `learned_name` with the learned affordance.

### 11. Docs

- `docs/reference/configuration.md`, clients section: a paragraph stating the learned-name mechanism; that it requires a conditional forward zone covering the LAN's reverse space (with the `168.192.in-addr.arpa` example); that hand-typed names win; that learned names never appear in exports; that a rename or lease change can display stale for up to a day (ruling 3's bound). The cadence must be described as it is, not rounded up: each pass attempts **at most 16 due rows**, and a row is due per ruling 1's two cadences — "every unnamed device, once a minute" overstates both coverage and rate and must not appear; and one sentence that PTR queries go to the declared zone's resolver, wherever the operator pointed it (ruling 2's scope).
- The how-to/tutorial page that documents conditional forward zones gains the reverse-zone example if it lacks one (locate it; do not guess its path).
- PLAN §7.2 gains one sentence: materialised clients are named by PTR through the declared forward zones; learned names are runtime state.
- `docs/reference/api.md` only if it enumerates client row fields (check).

## Sessions

Three, strictly sequential: S1 → S2 → S3. S2 needs S1's columns and repo calls; S2 owns the contract regeneration (the API shape changes when S1 widens `ClientRow`, but the sample regen runs the integration suite, which S2's wiring changes — one regen at the end of S2 avoids regenerating twice). S3 reads the fields S2's regenerated types carry.

### Session S1: pure module, schema, repo

Owns: `src/local/reverse_name.zig` (new), `src/tests.zig` (registration), `src/storage/config_schema.zig`, `src/storage/migrations.zig` (test), `src/storage/repositories/clients_repo.zig`, `PLAN.md` (§11.2 lines only).

- S1.1 ruling 8: `reverse_name.zig` with exhaustive tests (v4, v6, bounds; `acceptHostname` accept/reject table from ruling 4).
- S1.2 ruling 5: the two DDL lines in both copies, baseline column probes.
- S1.3 ruling 6: repo calls, `ClientRow` widening, tests — including: the candidate SQL's boundary and extreme-value cases; the ordering; NULL round-trips as `""`; export is byte-stable across a `noteNameOutcome`; `updateClient` leaves `learned_name` alone; the zero-row UPDATE no-op.

Acceptance (S1):
- [ ] `zig build test` passes; baseline test proves both columns exist.
- [ ] `reverseName` output for `192.168.1.10` is
      `10.1.168.192.in-addr.arpa` and for `fd00::1` is the full 32-nibble
      lowercase form; both are matched by a `forward_zones.Zones` built over
      `168.192.in-addr.arpa` / a covering `ip6.arpa` zone in a test that ties
      the two modules together.
- [ ] `acceptHostname` passes ruling 4's full accept/reject table, including
      `a..b`, `.a` and the trailing-dot case.
- [ ] An export taken before and after `noteNameOutcome` on an observed row is
      byte-identical.

### Session S2: resolver, wiring, metrics, API contract (needs S1)

Owns: `src/server/client_names.zig` (new), `src/tests.zig` (registration), `src/server/clients.zig`, `src/app.zig`, `src/web/server.zig` (the `client_names` field), `src/web/metrics.zig`, `src/web/openapi.yaml`, `web/src/lib/types.ts`, `web/src/lib/contractSamples.gen.ts` (regenerated), `web/src/features/clients/ClientsPage.test.tsx` (mock fields only).

- S2.1 ruling 7: the Resolver, the exchange seam, `flushOnce` hook (ruling 1 order), app and WebState wiring.
- S2.2 rulings 1–4: classification tests against a stub exchange. Tests must cover: answered stores and lowercases; a second answered overwrites; NXDOMAIN clears; NODATA clears; REFUSED and an unknown RCODE keep and count `failed`; timeout keeps; invalid hostname keeps and counts `invalid`; a record with wrong type, class, or owner name is skipped; no-zone sends nothing (the stub's call count is the assertion) and counts; `name_attempt_after` lands at `now + refresh_after_s` for definitive and `now + retry_after_s` for non-definitive outcomes; the candidate cap holds; a named row is never attempted; a gated pass attempts nothing; drain precedes any exchange when every exchange times out (ruling 1); a row past the prune cutoff on a due pass causes no exchange (ruling 1); the two-generation swap test per ruling 2's exact shape (swap inside the hazard window, both assertions); a NOERROR header under a nonzero OPT extended RCODE counts `failed` and keeps the stored name (ruling 3); the default `exchangeFn` bounds UDP plus the TCP fallback under one `ptr_read_timeout` deadline (ruling 1) — a loopback resolver that answers UDP with TC=1 late in the budget and then stalls TCP must fail the attempt within one budget, not two (assert elapsed with margin; inject a shortened budget locally if the default seam needs one).
- S2.3 ruling 9: WebState field, metrics sample, render pin.
- S2.4 ruling 10's API half: openapi.yaml, regen samples, types.ts, mock fields.

Acceptance (S2):
- [ ] `zig build test` and `zig build test -Dintegration` pass; the
      regenerated samples carry `learned_name` in the client row sample and
      do not carry `name_attempt_after`.
- [ ] `cd web && npm run typecheck && npm test` pass with the widened types.
- [ ] The stats-sum invariant test passes (`attempted` = sum of the five
      outcomes; `read_failures`/`write_failures` outside it).
- [ ] The no-zone test proves zero exchanges for an uncovered reverse name
      through the production pass code.
- [ ] The concurrent-swap regression test passes (ruling 2).

### Session S3: UI and docs (needs S2)

Owns: `web/src/features/clients/ClientsPage.tsx`, `web/src/features/clients/ClientEditDialog.tsx`, `web/src/features/clients/ClientsPage.test.tsx` (rendering assertions), `docs/reference/configuration.md`, `docs/reference/api.md` (if applicable), the conditional-forwarding doc page, `PLAN.md` (§7.2 sentence only).

- S3.1 ruling 10's UI half.
- S3.2 ruling 11.

Acceptance (S3):
- [ ] `cd web && npm run typecheck && npm test && npm run lint && npm run
      build` pass; rendering tests cover named-wins and learned-affordance.
- [ ] The docs name the reverse-zone prerequisite with a concrete
      `in-addr.arpa` example, the one-day staleness bound, and the
      resolver-is-the-operator's-choice sentence.

### Orchestrator

Verify each session's acceptance before starting the next. After S3, the full gate set (`zig build test`, `zig build test -Dintegration`, `test-aarch64` if qemu is present, `cd web && npm test`, `npm run assert-bundled`), then a live smoke per the verify-against-the-real-network rule: a scratch server with a forward zone `168.192.in-addr.arpa → udp://<router>:53` (or a local stub resolver serving PTR), one real query from a LAN client, then wait one flush interval and confirm the learned name in `GET /api/clients`, in the UI, and in `nxdns_client_names_answered_total`. Then delete the zone and confirm the next attempt counts `no_zone` with no upstream traffic (tcpdump or the pool counters — pool queries must not move); with the hourly non-definitive cadence, age `name_attempt_after` by SQL in the scratch database rather than waiting. In database mode, hand-edit the name and confirm it wins and the row stops being attempted. In file mode, confirm a file-declared name wins after reconcile and the learned name remains display-only. Record deviations in `## Recorded (implementation)`.

## Module layout

New files: `src/local/reverse_name.zig`, `src/server/client_names.zig`. Deleted surface: none.

## File ownership

| File | Session |
| --- | --- |
| `src/local/reverse_name.zig` (new) | S1 |
| `src/storage/config_schema.zig`, `src/storage/migrations.zig` (test) | S1 |
| `src/storage/repositories/clients_repo.zig` | S1 |
| `PLAN.md` | S1 (§11.2 lines), then S3 (§7.2 sentence) — sequential, never concurrent |
| `src/tests.zig` | S1, then S2 — sequential |
| `src/server/client_names.zig` (new) | S2 |
| `src/server/clients.zig`, `src/app.zig`, `src/web/server.zig`, `src/web/metrics.zig` | S2 |
| `src/web/openapi.yaml`, `web/src/lib/types.ts`, `web/src/lib/contractSamples.gen.ts` | S2 |
| `web/src/features/clients/ClientsPage.test.tsx` | S2 (mock fields), then S3 (assertions) — sequential |
| `web/src/features/clients/ClientsPage.tsx`, `ClientEditDialog.tsx` | S3 |
| `docs/reference/configuration.md`, `docs/reference/api.md`, forwarding doc page | S3 |

## Acceptance (milestone complete)

- [ ] All session acceptance boxes.
- [ ] `config_schema.ddl_v1` and PLAN §11.2 byte-identical, both carrying the
      two lines; `migrations.steps` still one step, `target_version` still 1.
- [ ] The live smoke: a real client's hostname appears without any operator
      edit; removing the zone stops queries entirely (`no_zone` moves, pool
      counters do not).
- [ ] `nxdns export` output is byte-identical before and after names are
      learned.
- [ ] Database mode: hand-editing a name wins over the learned name
      immediately and permanently (the row leaves candidacy). File mode: a
      file-declared name wins after reconcile; the learned name is
      display-only runtime state.
- [ ] `src/web/openapi.yaml` reviewed by hand against the changed client row
      shape, reviewer says so in `## Recorded` (no automated guard covers
      schema-to-response agreement — milestone-24 finding, still true).

## Anti-requirements

- No migration step, no `ddl_v2`, no runtime schema probing.
- No PTR query to the upstream pool, and none for a reverse name no declared forward zone covers — under any fallback, ever. (The declared resolver itself is the operator's choice; ruling 2 scopes the promise.)
- No reuse of `clients.name` for learned names, and no learned data in `nxdns export` / `import` ZON or in reconcile semantics.
- No mDNS, NetBIOS, DHCP-lease-file parsing, or any second naming source. PTR through declared zones is the mechanism; a router that serves no reverse zone yields `no_zone` counts and an unnamed row, visibly.
- No per-query or query-path resolution: naming rides the flush pass only.
- No config knobs for cadence, caps, or timeouts; constants per ruling 1.
- No DNS-cache participation for PTR probes.
- No unbounded anything: candidates per pass, in-flight, per-attempt timeout, name length, and retry cadence are all bounded above by rulings 1 and 4.
- No storing or displaying a PTR target that fails `acceptHostname` — not even truncated or escaped.
- No new per-attempt log lines from this milestone's code; counters and the metrics group are the surface. `forward_client.zig`'s existing debug diagnostics stand as they are.
- No allocation on the naming path: candidate storage is fixed-capacity (ruling 6).

## Recorded (implementation)

- `src/server/phase7_integration_test.zig` sits outside the ownership table but gained a mechanical `, null` argument at every `flushOnce`/`run` call site, following the new `names: ?*client_names.Resolver` parameter.
- Review: one external round found four defects (extended RCODE ignored the OPT upper bits; `exchangeWithin` did not bound the UDP+TCP pair under one deadline; the swap test asserted nothing observable; a docs cadence sentence). All four were fixed; the re-review of `src/server/client_names.zig` returned no findings.
- Every fix shipped with a test the author watched fail with the fix reverted. For the swap test the hazard was injected (a pass-level resolver cache that skips re-acquisition) and the second-port assertion failed; the one-deadline test's bound is `budget + late/2` (550 ms) because the unbounded path takes ~700 ms and a 2×-budget bound would pass it.
- `src/web/openapi.yaml` was reviewed by hand against `ClientRow` (clients_repo.zig:312): the nine required fields match one-to-one and `name_attempt_after` is absent from the response, as intended.
- Live smoke (scratch server, file mode, zone `127.in-addr.arpa` at a local stub PTR resolver): one real query materialised the client; the flush pass learned `smoke-host.lan` with no operator edit, visible in `GET /api/clients` and `nxdns_client_names_answered_total`. Removing the zone and re-arming `name_attempt_after` produced `no_zone` with zero packets to the stub and no pool movement. The learned name survived a restart's reconcile. A file-declared `name` won in the API after reconcile with the learned name still present as display-only state, and the named row left candidacy (`attempted` stayed 0 over a full flush interval). The database-mode hand-edit path runs the same candidacy SQL (`name IS NULL OR name = ''`) and is covered by the repo unit tests rather than a second live run. The UI half is covered by the ClientsPage rendering tests, not a live browser check.
- The first smoke attempt polled a stale pre-milestone binary out of `zig-out/bin` — `zig build test` does not refresh the install step. Rebuild before any live check.

## Addendum: names in the query tables (post-0.0.3)

Operator request after running 0.0.3: the live page showed bare addresses while the Clients page had names. Frontend-only follow-up, no API change: `admin/src/features/clients/clientNames.tsx` owns `useClientNames()` (the same `["clients"]` query the Clients page uses, polled every 30 s so mid-stream unknown addresses fold in) and `<ClientName>`, which applies the ruling-10 precedence — hand-typed `name`, else `learned_name` muted with the "learned" tag, else the bare address — with the address kept as the tooltip when a name replaces it. Both query tables render it through the shared `QueryCells`, so the query log page got the same treatment as the live page. The learned-name styles moved from `ClientsPage.tsx` into `ui/styles.ts`. Three new tests (name wins, learned tag, bare fallback for unknown and unnamed addresses) were watched failing before the change.