# Milestone 5: Filtering + Local DNS

Goal (PLAN §16 Phase 5): the rule matcher (exact / parent-walk / wildcard); blocklist parsers and the compiled file format; the fetcher and its scheduled update; the RCU snapshot swap; per-group safe-search; blocked-response synthesis; local records; forward zones. Exit: the §3.10 precedence table is validated by tests; local zone answers and conditional forwards work.

Read first: `AGENTS.md` (values), `specs/research/zig-0.16-api-notes.md` (verified stdlib facts — pre-0.16 knowledge is stale and MUST NOT be used), `specs/milestone-1.md`, `specs/milestone-2.md`, `specs/milestone-3.md`, `specs/milestone-4.md` (module conventions, the "As built" notes, and the binding logging policy restated below). The Zig source of truth is `/home/mokhtar/app/zig` at tag `0.16.0`. PLAN §2.2, §3.8–§3.10, §5, §6.2, §6.4, §6.5, §7, §11.2, §12, §18 are the scope authority.

## What already exists (do not respecify, import it)

- `src/dns/*` — pure wire format. Used here: `name.Name`, `name.fromText`, `name.formatText`, `name.eqlIgnoreCase`, `types.Type`, `types.Class`, `types.Rcode`, `types.max_name_len`, `question.Question`, `header.Header`, `edns.OptRecord`, `packet.ResponseBuilder` (`init`, `setRcode`, `addAnswer`, `addOptEcho`, `finish`). Do not write a second name parser and do not add anything to `src/dns/`.
- `src/platform/address.zig` — `NetAddress.parse/format/key/eql`, `Prefix.parse/contains`, `matchLongest`. Group assignment by client IP uses these; do not write a second IP parser.
- `src/config/model.zig` — `Config`, `Group`, `Rule`, `RuleKind`, `RuleAction`, `BlocklistSource`, `GroupSource`, `LocalRecord`, `RecordType`, `ForwardZone`, `Client`, `ClientPrefix`, `Blocking`, `BlockResponse`, `BlocklistUpdate`, `updateIntervalSeconds`.
- `src/config/validate.zig` — `parseResolver(text) ResolverError!Resolver`, `Resolver`, `ResolverScheme`. Its doc comment already names this phase as the importer. `local/forward_zones.zig` imports it; nobody writes a second resolver-URL parser.
- `src/storage/repositories/*` — `listGroups`/`freeGroups`, `listGroupSources`/`freeGroupSources`, `listRules`/`freeRules`, `listBlocklistSources`/`freeBlocklistSources`, `listLocalRecords`, `listForwardZones`, `listClients`, `listClientPrefixes`, and the `count*` functions. Every list returns `std.ArrayList(model.X)` with heap-owned strings and a matching `freeX`. **The repositories gain no new functions in this milestone except the two named in S8.1**, which are additive and owned by S8.
- `src/storage/db.zig` — `Db`, `Stmt`, `Tx`, `Error`. `db.zig` takes no `std.Io` (milestone 4's documented exception); everything else that touches the filesystem takes `io: std.Io`.
- `src/upstream/transport.zig` — `Client` (the `exchangeFn` vtable), `ExchangeError`, `PeerFault`, `LocalResource`, `mapLocal`, `group`, `validateResponse`, `max_message_len`. The forward-zone client implements this interface; it does not invent a second one.
- `build.zig` — `-Dintegration` (hermetic, loopback/tmpdir only, PR-blocking) and `-Dlive` (leaves the machine, manual only) reach test files through `@import("build_options")`. A second test artifact carries the fuzz targets with `dns` as a named module.

## Sessions

```
S1 (parsers + wildcard)   S2 (domain_set + compiler)   S3 (safesearch + response)
S4 (local records + forward_zones)   S6 (fetcher)   S7 (forward_client)      [all parallel, no deps]
             |                    |
             +---------+----------+
                       v
                 S5 (rules + matcher)          [needs S1, S2]
                       v
                 S8 (manager)                  [needs S2, S5, S6]
                       v
                 S9 (integration + fuzz)       [needs everything]
```

Six sessions start together. Every later session is written against **this spec**, not against the previous session's source. The orchestrator — not any session — wires `src/tests.zig` imports and every `build.zig` change. A session that needs a build change reports the exact change in its completion report; the one this milestone needs is stated in S9.3.

## Session verification protocol (read this before starting)

Unchanged from milestone 4, and it still binds:

- `zig test <file>` does not work here: every file imports across `src/` subdirectories or links against `sqlite3`. Each session verifies its own work with `zig fmt --check <its files>` and `zig ast-check <its files>`. `zig ast-check` reports only syntax and AST-level errors; it does **not** type-check, so it cannot prove the code compiles.
- The orchestrator wires the files into `src/tests.zig` and runs `zig build test` (and `zig build test -Dintegration` for S9). That run is the real gate.
- Every session states in its completion report that its tests have not been executed, and lists the exact test names it wrote so the orchestrator can confirm they ran.
- No session edits `build.zig`, `build.zig.zon`, or `src/tests.zig`. No session edits a milestone 1–4 file; a needed change there is reported, not made.

## Design invariants (all sessions)

- **The pure core stays pure.** `filter/parsers.zig`, `parser_hosts.zig`, `parser_domains.zig`, `parser_abp.zig`, `wildcard.zig`, `domain_set.zig`, `compiler.zig`, `rules.zig`, `matcher.zig`, `safesearch.zig`, `response.zig`, `local/records.zig` and `local/forward_zones.zig` take **no `std.Io` value**. They take bytes, structs, an allocator, and `*std.Io.Reader` / `*std.Io.Writer` interfaces — which are not `Io` and carry no backend. Clocks, entropy, sockets and files arrive as parameters or do not arrive at all.
- **`std.Io` lives in exactly three files**: `filter/fetcher.zig`, `filter/manager.zig`, `local/forward_client.zig`. PLAN §5 marks `filter/` "pure" and then lists `fetcher.zig` and `compiler.zig` inside it; the split above keeps that promise where it matters — the compiler is pure over reader/writer interfaces, and only the fetcher and the manager touch the network and the filesystem.
- **Logging policy (binding, repo-wide, milestone 4 "As built")**: a condition that is returned as a typed error logs at `warn` at most. `err` is reserved for failures the code swallows. The zig test runner fails any test that emits `err` logs. In this milestone the only legitimate `err` site is a background refresh task that has nowhere to return its failure — and even that logs at `warn`, because the failure is recorded in `SourceStatus` and surfaced (S8.5). **No `std.log.err` call is written in this milestone.**
- **Every failure mode is counted, not dropped** (AGENTS.md). A skipped regex line, an unsupported ABP modifier, an over-long line, a single-label name, an unparseable name, a failed download and a checksum mismatch each increment a named counter that reaches `SourceStatus` and (for the three columns that exist) `blocklist_sources`.
- **No regex, ever** (PLAN §2.2). Regex lines are recognized, counted, skipped. No engine, no dependency, no "just a small subset".
- **Nothing in this milestone allocates on the query path.** `Snapshot.evaluate` performs no allocation, opens no file, and takes no lock beyond the reader lock its caller already holds. It is callable from a `std.Io` task with a stack buffer and nothing else.
- **Determinism**: a compiled list body is a pure function of the downloaded bytes and the format. See the determinism contract in §Determinism below; S2 and S9 both test it.
- Unit tests live in-file. Tests that touch the filesystem, loopback sockets or real HTTP live in `src/filter/filter_integration_test.zig`, guarded by `if (!build_options.integration) return error.SkipZigTest;`. Tests that leave the machine are guarded by `build_options.live`. Mirrors milestones 1, 3 and 4.

---

## Resolved PLAN ambiguities (read before writing code)

These were decided while writing this spec. They are the ruling for this milestone; the orchestrator carries any of them that change PLAN text back into PLAN.

1. **Blocklist domain entries match exactly; only rules parent-walk.** PLAN §7.1 builds a candidate chain and then consults rules (step 3), blocklist domains (step 4) and blocklist wildcards (step 5). If blocklist domains were also matched against the whole chain, §3.10's separate "blocklist wildcards" level would be unreachable and one `com`-shaped line in a bad list would black-hole the internet. §3.9 ties parent-walk to the **rule** model ("parent-walk (implicit via candidate chain)"). Ruling: exact and wildcard **rules** are evaluated against every candidate in the chain; **blocklist `.list` entries** are matched against the query name only; **blocklist `.wild` entries** are matched against every *proper parent* of the query name (that is what `*.x.y` means). ABP `||x.y^` therefore emits both a `.list` entry `x.y` and a `.wild` entry `x.y`, which together give the "domain and all subdomains" semantics the syntax promises.
2. **`*` matches one or more labels.** PLAN §3.9 gives both `*.doubleclick.net` and `ads.*.example.com`. A one-label-only `*` would make the first pattern miss `a.b.doubleclick.net`, which is not what an operator writing it means. One rule for both positions: each `*` label matches one **or more** labels. Bounded by the 128-label ceiling a 255-byte name implies, so the backtracking match cannot blow up.
3. **`evaluate` takes no qtype.** PLAN §7.1 keys evaluation on `{domain, qtype, group_id}` but no step in §7 or §3.10 reads the qtype. Ruling: the filtering decision is `{domain, group}`; the qtype travels with the query for logging and for response synthesis, not for matching. Adding an unused parameter would be generality nobody asked for (AGENTS.md).
4. **Group assignment by client IP is in scope; auto-materialization is not.** PLAN §7.2 belongs to the filtering engine this phase builds, and the matching half is pure (`clients` exact match → `client_prefixes` longest-prefix → `default`). The half that **writes** — inserting the unseen client row, updating `last_seen`, retention of `hand_edited = 0` rows — needs a clock and a database write on the query path and belongs with the handler pipeline (Phase 7) and retention (Phase 6). `Snapshot.groupForClient` is built here; nothing inserts a row.
5. **A plain UDP/TCP resolver client is in scope.** PLAN Phase 5's exit criterion says conditional forwards *work*, and §6.5 permits plain transports. No such client exists: `transport.Endpoint` knows only `https://` and `tls://`, by design. Ruling: `src/local/forward_client.zig` implements `transport.Client` over plain UDP with TCP fallback, configured from `validate.Resolver` rather than from `transport.Endpoint`, so no milestone-3 file is edited. Wiring it into the query path is Phase 7.
6. **Compressed transfer encoding is out of scope.** `std.http.Client` advertises gzip and deflate by default (verified, Client.zig:831) and `Response.readerDecompressing` would be needed to read them. The fetcher overrides `accept_encoding` to identity, exactly as `doh_client.zig` does. A daily download of a few megabytes does not pay for a decompression buffer and a second failure surface. A source URL that serves a `.gz` **body** (content, not encoding) fails the compile with a high invalid-line count and a visible error, rather than silently compiling to nothing.

## Determinism

For a given input byte stream and format, `compiler.compile` must produce byte-identical `.list` and `.wild` bodies on every run, on both target architectures. Concretely:

- Names are lowercased over ASCII only (`A`–`Z`); a byte ≥ 0x80 makes the candidate invalid.
- A single trailing dot is stripped; the name is stored without it.
- Entries are sorted ascending by `std.mem.order(u8, …)` over the full name and deduplicated.
- Every line ends with a single `\n`, including the last. An empty body is zero bytes.
- The body carries no header, no timestamp, no hostname, no counts. The manager writes the header (S8.3); the checksum covers the two bodies only.
- Sorting is by byte value, not by locale, not by label. Two runs of the same input in different input order (S9 shuffles a fixture) produce the same body.

The snapshot built from those files is deterministic in content but **not** in hash-table layout: the open-addressing seed is per-snapshot randomness (S2.1). `contains` results do not depend on it, and that is the property tests assert.

## Memory budget (PLAN §18: < 100 MB with ~1M blocked domains)

The compiled in-memory structure is an **exact-match** set — a flat arena of length-prefixed lowercase names plus an open-addressed table of `u32` offsets into it. No Bloom filter, no hash-only key set, no probabilistic structure: a false positive in a DNS sinkhole blocks a real domain for a real household and is undebuggable from the outside. Every probe compares full bytes.

Sizing for one 1,000,000-entry source, mean name length 22 bytes:

| Part | Size |
|---|---|
| arena (`1 + len` bytes per name) | ≈ 23 MB |
| index: capacity `2^21` slots at load factor ≤ 0.75, 4 bytes per slot | 8 MiB |
| per-source struct overhead | < 1 KB |
| **total, one 1M-domain source** | **≈ 31 MB** |

A typical household set (three lists, ~150k entries each, heavy overlap) is under 15 MB. Sets are **per source, shared between groups** — a group holds indices into `Snapshot.sources`, so assigning one source to four groups costs four `u32`s, not four copies.

Refresh peak, which is what the budget has to survive:

1. Sources are compiled **one at a time**, each into its own arena, and that arena is freed before the next source starts. Compile working set for a 1M-entry source: 23 MB of candidate bytes plus 4 MB of `u32` offsets ≈ 27 MB.
2. The new snapshot is built only after every compile has finished, so compile arenas and the new snapshot never coexist.
3. Peak is therefore `max(old + compile, old + new)` ≈ 62 MB for a 1M-domain configuration, leaving headroom under the 100 MB target for the servers, the pool and (Phase 6) the cache.

Hard caps, all of which produce a typed error and a counter rather than a slow death: `compiler.max_domains = 2_000_000` per source, `fetcher.max_body_bytes = 64 * 1024 * 1024`, `compiler.max_line_len = 4096`, `rules.max_wildcards_per_group = 4096`.

Lookup cost, against PLAN §18's "blocklist lookup p95 < 1 ms": a 5-label query walks at most 5 candidates; per candidate the matcher does 2 rule-set probes plus one probe per assigned source (`.list` for the full name, `.wild` for parents). With 5 sources that is under 40 Wyhash + memcmp probes on structures that fit in L2 for typical list sizes. No allocation, no lock beyond the caller's reader lock.

---

## Verified 0.16.0 stdlib facts used by this milestone

Read from `/home/mokhtar/app/zig` at tag `0.16.0`. Anything not listed here or in `specs/research/zig-0.16-api-notes.md` must be re-verified against the source before use.

### Locks — they are **not** in `std.Thread`

`lib/std/Thread.zig` declares no `Mutex` and no `RwLock` in 0.16.0. Both live under `std.Io`:

```zig
pub const RwLock = @import("Io/RwLock.zig");                       // Io.zig:48
pub const init: RwLock = .{ ... };                                 // Io/RwLock.zig:15
pub fn lock(rl: *RwLock, io: Io) Io.Cancelable!void;               // Io/RwLock.zig:51
pub fn lockUncancelable(rl: *RwLock, io: Io) void;                 // Io/RwLock.zig:42
pub fn unlock(rl: *RwLock, io: Io) void;                           // Io/RwLock.zig:70
pub fn lockShared(rl: *RwLock, io: Io) Io.Cancelable!void;         // Io/RwLock.zig:115
pub fn lockSharedUncancelable(rl: *RwLock, io: Io) void;           // Io/RwLock.zig:97
pub fn unlockShared(rl: *RwLock, io: Io) void;                     // Io/RwLock.zig:133
pub fn tryLockShared(rl: *RwLock, io: Io) bool;                    // Io/RwLock.zig:75
pub const Mutex = extern struct { ... };                           // Io.zig:1587
```

### Timers

```zig
pub fn sleep(io: Io, duration: Duration, clock: Clock) Cancelable!void;   // Io.zig:2397
pub fn sleep(duration: Clock.Duration, io: Io) Cancelable!void;           // Io.zig:900
pub fn fromSeconds(x: i64) Duration;                                      // Io.zig:988
pub fn fromMilliseconds(x: i64) Duration;                                 // Io.zig:984
pub fn now(clock: Clock, io: Io) Io.Timestamp;                            // Io.zig:778
pub fn toSeconds(t: Timestamp) i64;                                       // Io.zig:943
```

There is no timer wheel and no periodic-callback API. A scheduled refresh is a task that sleeps and loops; cancellation arrives as `error.Canceled` from the sleep (milestone 3 convention).

### `std.Io.Reader` line iteration

```zig
pub fn takeDelimiter(r: *Reader, delimiter: u8) error{ ReadFailed, StreamTooLong }!?[]u8;  // Reader.zig:895
pub fn discardDelimiterInclusive(r: *Reader, delimiter: u8) Error!usize;                   // Reader.zig:1037
pub fn discardRemaining(r: *Reader) ShortError!usize;                                      // Reader.zig:270
```

`takeDelimiter` returns `null` at end of stream, excludes the delimiter, and treats end-of-stream as a delimiter for a final unterminated line. `error.StreamTooLong` means the line did not fit the reader's buffer and **leaves the stream unmodified** (doc comment, Reader.zig:885) — the compiler must then `discardDelimiterInclusive('\n')` to step over that line and count it, or it will spin forever on the same bytes. This is the single most likely infinite loop in this milestone.

### `std.http.Client` — GET download flow

```zig
pub fn request(client: *Client, method, uri, options: RequestOptions) RequestError!Request;
pub fn sendBodiless(r: *Request) Writer.Error!void;                       // Client.zig:912
pub fn receiveHead(r: *Request, redirect_buffer: []u8) ReceiveHeadError!Response;  // Client.zig:1133
pub fn reader(response: *Response, transfer_buffer: []u8) *Reader;        // Client.zig:736
pub fn readerDecompressing(...) *Reader;                                  // Client.zig:752 (NOT used, ambiguity 6)
redirect_behavior: Request.RedirectBehavior = @enumFromInt(3)             // Client.zig:1654
pub const default_accept_encoding = { gzip, deflate, identity }           // Client.zig:831
```

`receiveHead` follows redirects itself and needs the `redirect_buffer` to outlive `Request.uri`; RFC 9110 recommends ≥ 8000 bytes (doc comment, Client.zig:1128). An empty buffer is legal only when `redirect_behavior = .not_allowed`. Blocklist URLs redirect in practice, so the fetcher allows redirects and supplies a real buffer. `Response.reader` returns **compressed** bytes if a compressed encoding was negotiated — which is why the fetcher pins `accept_encoding` to identity.

### Hashing and sorting

```zig
pub fn hash(seed: u64, input: []const u8) u64;              // hash/wyhash.zig:178  → std.hash.Wyhash
pub const Sha256 = Sha2x32(iv256, 256);                     // crypto/sha2.zig:23
pub fn hash(b: []const u8, out: *[32]u8, options) void;     // crypto/sha2.zig:108
pub fn bytesToHex(input: anytype, case: Case) [input.len * 2]u8;   // fmt.zig:1156
pub fn sortUnstableContext(a: usize, b: usize, context: anytype) void;  // mem.zig:648
```

### Filesystem (unchanged from milestone 4, reproduced for the two files that need it)

```zig
pub fn createFileAtomic(dir: Dir, io: Io, sub_path: []const u8, options: CreateFileAtomicOptions)
    CreateFileAtomicError!File.Atomic;                        // Dir.zig:1924
pub fn replace(af: *Atomic, io: Io) ReplaceError!void;        // File/Atomic.zig:77
pub fn deinit(af: *Atomic, io: Io) void;                      // File/Atomic.zig:23
pub fn readFileAlloc(dir, io, sub_path, gpa, limit) ReadFileAllocError![]u8;   // Dir.zig:1326
pub fn createDirPathStatus(dir, io, sub_path, permissions) ...!CreatePathStatus; // Dir.zig:851
pub fn deleteFile(dir, io, sub_path) DeleteFileError!void;    // Dir.zig:1004
pub fn writer(file: File, io: Io, buffer: []u8) Writer;       // File.zig:600, BY VALUE
```

Plain `createDirPath` hardcodes `0o777` (Dir.zig:843) and must not be used; the blocklist directory is created with `createDirPathStatus(io, path, .fromMode(0o700))`.

---

## Session S1: `src/filter/parsers.zig`, `parser_hosts.zig`, `parser_domains.zig`, `parser_abp.zig`, `wildcard.zig`

Pure, and **`std` is the only import in all five files**. No `@import("../dns/...")`, no config, no allocator, no I/O. That constraint is not stylistic: `parsers.zig` is the root of the fuzz module S9.3 adds, and a module root cannot import across its own directory boundary (`error.ImportOutsideModulePath`, milestone 2). Domain **validity** is decided in S2's compiler through `dns.name.fromText`; these files decide **format**.

### S1.1 `parsers.zig` — the shared vocabulary

```zig
pub const hosts = @import("parser_hosts.zig");
pub const domains = @import("parser_domains.zig");
pub const abp = @import("parser_abp.zig");
pub const wildcard = @import("wildcard.zig");

pub const Format = enum { hosts, domains, abp };

pub const Kind = enum {
    /// Nothing on the line, or only a comment.
    ignore,
    /// `text` holds one or more whitespace-separated candidate names.
    domain,
    /// `text` holds one candidate suffix; every proper subdomain of it matches.
    wildcard,
    /// A regex rule. Counted, skipped, never compiled (PLAN §2.2).
    regex,
    /// Syntactically a rule of this format, but one nxdns cannot honour:
    /// an ABP modifier list, an exception rule, element hiding, a scheme anchor.
    unsupported,
};

pub const Line = struct {
    kind: Kind,
    /// Borrowed from the caller's line. Not lowercased, not validated.
    text: []const u8 = "",
    /// `.wildcard` only. ABP `||x^` covers `x` itself as well as its subdomains,
    /// so the compiler emits an additional `.list` entry when this is set.
    covers_apex: bool = false,
};

/// Dispatches to the format's parser. The line must not contain '\n' or '\r';
/// the caller strips them.
pub fn parseLine(format: Format, line: []const u8) Line;

/// Picks a format from the first `sample_lines` lines that are not blank and
/// not comments: an ABP marker (`||`, `@@`, `##`, `$`) anywhere wins `.abp`;
/// otherwise a majority of lines whose first field parses as an IP literal
/// wins `.hosts`; otherwise `.domains`.
pub const sample_lines = 64;
pub fn detectFormat(sample: []const u8) Format;
```

`detectFormat` uses its own minimal IPv4/IPv6-literal recognizer over the first field (digits, dots, colons and hex only) rather than `NetAddress.parse` — importing `platform/` would break the module constraint above, and a sniffing heuristic does not need a correct parser.

### S1.2 `parser_hosts.zig`

```zig
pub fn parseLine(line: []const u8) parsers.Line;
```

1. Truncate at the first `#`. Trim ASCII whitespace. Empty → `.ignore`.
2. A line starting with `/` → `.regex` (a regex smuggled into a hosts list).
3. Split on ASCII whitespace. If the first field looks like an IP literal **and** at least one field follows, the remaining fields are the candidate names → `.domain` with `text` spanning them.
4. If the first field does not look like an IP literal, the whole line is the candidate name(s) → `.domain`. Real "hosts" lists are frequently bare domain lists with a hosts extension.
5. A leading `*.` on any candidate is not stripped here; `parsers.parseLine` is per line, and the compiler splits `text` and re-classifies each name (S2.3). This is the one place a `.domain` line can yield wildcard entries, and it is spelled out in S2.3 rather than duplicated here.

The sink address is not checked against a list of "blocking" IPs: a hosts-format blocklist that maps to `127.0.0.1`, `0.0.0.0` or `::` is the same instruction to nxdns, and a source that maps to a real address is still a source of names the operator asked to block.

### S1.3 `parser_domains.zig`

```zig
pub fn parseLine(line: []const u8) parsers.Line;
```

One candidate per line. `#` and `!` start a comment (both appear in the wild); truncate and trim. A leading `/` → `.regex`. Everything else → `.domain` with the trimmed text. A line containing whitespace after trimming → `.unsupported` (a domains-format list with two fields is a mis-detected hosts file, and guessing is worse than counting).

### S1.4 `parser_abp.zig`

```zig
pub fn parseLine(line: []const u8) parsers.Line;
```

| Input | Result |
|---|---|
| `! comment`, `[Adblock Plus 2.0]`, empty | `.ignore` |
| `\|\|example.com^` | `.wildcard`, `text = "example.com"`, `covers_apex = true` |
| `\|\|example.com^` with a trailing `$…` modifier list | `.unsupported` |
| `@@…` (exception) | `.unsupported` |
| `##…`, `#@#…`, `#?#…` (element hiding) | `.unsupported` |
| `\|http://…`, `\|https://…` (scheme anchor) | `.unsupported` |
| `/regex/` | `.regex` |
| `example.com` (bare) | `.domain` |
| anything containing `*`, `^` or `\|` outside the forms above | `.unsupported` |

`^` is a separator token in ABP and only the trailing `^` (or a trailing `^` before a modifier) is meaningful for a domain rule; anything else carrying `^` is `.unsupported`. Exception rules are `.unsupported` rather than an allow entry: PLAN's allow surface is the `rules` table, and a list that could quietly allow a domain across every group is a policy hole the operator did not open.

### S1.5 `wildcard.zig`

```zig
pub const max_labels = 128;

pub const PatternError = error{
    /// No label is exactly "*".
    NoWildcard,
    /// A label contains '*' but is not exactly "*". Partial-label globbing
    /// (`ad*.example.com`) is out of scope: it is regex by another name, and
    /// PLAN §3.9 defines the wildcard as a label pattern.
    PartialWildcardLabel,
    EmptyLabel,
    LabelTooLong,
    PatternTooLong,
    TooManyLabels,
};

/// Syntax only. A valid pattern has at least one label that is exactly "*",
/// every other label is 1–63 bytes with no '*' inside it, and the whole
/// pattern is at most 253 bytes over at most `max_labels` labels.
pub fn validate(pattern: []const u8) PatternError!void;

/// `domain` is already normalized: lowercase, no trailing dot. `pattern` is
/// lowercase. Each "*" label matches ONE OR MORE labels (resolved ambiguity 2).
/// Allocation-free; the backtracking is bounded by `max_labels` on both sides.
pub fn matches(pattern: []const u8, domain: []const u8) bool;
```

Implementation shape: split both sides into label slices in two fixed `[max_labels][]const u8` stack arrays, then run the classic two-pointer glob match with a single backtrack point (a `*` consumes one label and may extend). No recursion, no allocation. A pattern with more than `max_labels` labels cannot occur because `validate` rejects it and the matcher only holds validated patterns; `matches` asserts the bound.

### S1.6 Tests (in-file)

`parsers.zig`:
- `detectFormat` on a hosts fixture, a domains fixture, an ABP fixture, and a file whose first 64 lines are all comments (→ `.domains`).
- `parseLine` dispatches to the format's parser (one case each).

`parser_hosts.zig`:
- `0.0.0.0 ads.example.com` → `.domain`, `"ads.example.com"`.
- `127.0.0.1 a.example.com b.example.com` → `.domain` whose `text` spans both names.
- `::1 ip6-localhost ip6-loopback` → `.domain` with both names (the compiler drops single-label names, S2.3 — this test asserts the parser does not silently swallow them).
- `0.0.0.0 ads.example.com # tracker` → the comment is gone.
- `# whole line`, ``, `   ` → `.ignore`.
- `/ads\d+/` → `.regex`.
- `example.com` (no IP) → `.domain`.

`parser_domains.zig`: bare name; `! comment`; `# comment`; inline `example.com # x`; `/re/` → `.regex`; `0.0.0.0 example.com` → `.unsupported`.

`parser_abp.zig`: one named test per row of the S1.4 table.

`wildcard.zig`:
- `validate` accepts `*.doubleclick.net` and `ads.*.example.com`; one named test per `PatternError` member: `example.com` → `NoWildcard`, `a*b.com` → `PartialWildcardLabel`, `a..b` → `EmptyLabel`, a 64-byte label → `LabelTooLong`, a 300-byte pattern → `PatternTooLong`, a 200-label pattern → `TooManyLabels`.
- `matches("*.doubleclick.net", "a.doubleclick.net")` true; `("*.doubleclick.net", "a.b.doubleclick.net")` true (ambiguity 2); `("*.doubleclick.net", "doubleclick.net")` false; `("ads.*.example.com", "ads.eu.example.com")` true; `("ads.*.example.com", "ads.eu.west.example.com")` true; `("ads.*.example.com", "ads.example.com")` false; `("*.example.com", "example.com.evil.net")` false.
- A pathological pattern `*.*.*.*.*.*.*.*.example.com` against a 100-label domain terminates (assert it returns, which is the runnable form of "the backtracking is bounded").

### S1.7 Acceptance criteria

- [ ] `zig fmt --check` and `zig ast-check` clean on all five files.
- [ ] `grep -n "@import" src/filter/parsers.zig src/filter/parser_*.zig src/filter/wildcard.zig`
      shows only `std` and sibling files in `src/filter/`.
- [ ] `PatternError` includes `PartialWildcardLabel` and every member is produced by a named test.
- [ ] No allocator, no `std.Io` value, no clock appears in any of the five files.
- [ ] Every bullet in S1.6 exists as a named test.

---

## Session S2: `src/filter/domain_set.zig`, `src/filter/compiler.zig`

Pure: an allocator and reader/writer interfaces, no `Io`. `compiler.zig` may import `../dns/name.zig` (it decides domain validity); `domain_set.zig` imports only `std`.

### S2.1 `domain_set.zig`

```zig
pub const DomainSet = struct {
    /// Length-prefixed lowercase names, back to back: [len: u8][bytes]…
    arena: []const u8,
    /// Open-addressed table of offsets into `arena`; `empty` marks a hole.
    /// Length is always a power of two.
    index: []const u32,
    count: u32,
    seed: u64,

    pub const empty_slot: u32 = std.math.maxInt(u32);
    pub const max_count: u32 = 4_000_000;
    pub const max_arena_bytes: usize = 1 << 31;

    pub const Error = error{ OutOfMemory, TooManyDomains, SetTooLarge, NotSorted, NotLowercase };

    /// Builds from a compiled body: LF-separated, lowercase, sorted ascending,
    /// deduplicated, every line 1–255 bytes. The sortedness is VERIFIED, not
    /// assumed — a hand-edited or truncated file must fail loudly at load
    /// (`error.NotSorted`) rather than produce a set that silently misses
    /// entries. Verification is one comparison per line and costs nothing.
    ///
    /// `seed` randomizes the hash. Query names are attacker-supplied, so a
    /// fixed seed would make probe-chain flooding computable offline; the seed
    /// arrives as a parameter so this file stays free of entropy sources.
    pub fn build(gpa: std.mem.Allocator, body: []const u8, seed: u64) Error!DomainSet;

    /// An empty set that owns nothing. `contains` on it is always false.
    pub const empty: DomainSet;

    pub fn deinit(self: *DomainSet, gpa: std.mem.Allocator) void;

    /// `domain` must be normalized (lowercase, no trailing dot). Allocation-free.
    pub fn contains(self: *const DomainSet, domain: []const u8) bool;

    /// Bytes held, for the memory report in `Snapshot.memoryBytes`.
    pub fn memoryBytes(self: *const DomainSet) usize;
};
```

Rules:

- Capacity is the smallest power of two ≥ `count * 4 / 3`, minimum 16. Linear probing, insertion in file order, no tombstones (the set is immutable after `build`).
- Hash is `std.hash.Wyhash.hash(self.seed, domain)`; the slot is `hash & (index.len - 1)`. A probe compares the full stored bytes with `std.mem.eql` before reporting a hit. **There is no path in which a hash collision produces a match.**
- `build` makes exactly two allocations (arena, index) and frees both on any error.
- A body of length 0 yields `empty`.
- `count > max_count` → `error.TooManyDomains`; body longer than `max_arena_bytes` → `error.SetTooLarge` (the index stores `u32` offsets and must not silently truncate).

Tests (in-file):
- Build from a small sorted body; `contains` true for every member, false for four non-members including a prefix, a suffix, an uppercase spelling and the empty string.
- A body that is not sorted → `error.NotSorted`; a body with an uppercase byte → `error.NotLowercase`; a duplicate line → `error.NotSorted` (equal is not ascending, and a duplicate means the compiler broke its contract).
- Two sets built from the same body with different seeds answer `contains` identically over a 50-name probe list — the property that matters, stated as a test.
- 10,000 generated names round-trip; `memoryBytes` is within 2× of the naive `body.len` bound.
- `build` under `std.testing.checkAllAllocationFailures` leaks nothing.
- `empty.contains("x") == false` and `deinit` on `empty` is a no-op.

### S2.2 `compiler.zig` — signatures

```zig
pub const max_domains: u32 = 2_000_000;
pub const max_line_len: usize = 4096;

pub const Counts = struct {
    domains: u32 = 0,
    wildcards: u32 = 0,
    skipped_regex: u32 = 0,
    skipped_unsupported: u32 = 0,
    /// Not a valid domain name (`dns.name.fromText` rejected it, a non-ASCII
    /// byte, or fewer than two labels).
    invalid: u32 = 0,
    /// Lines longer than `max_line_len`, skipped whole.
    long_lines: u32 = 0,
    /// Duplicates removed by the sort/unique pass.
    duplicates: u32 = 0,
};

pub const Result = struct {
    counts: Counts,
    /// Lowercase hex sha256 over the `.list` body followed by the `.wild` body.
    checksum: [64]u8,
};

pub const Error = error{ OutOfMemory, TooManyDomains, ReadFailed, WriteFailed };

/// Reads `r` to end of stream, writes the two compiled bodies. Nothing else is
/// written — headers belong to the caller (S8.3), so this function is a pure
/// function of (bytes, format) and is tested by comparing two runs.
pub fn compile(
    gpa: std.mem.Allocator,
    r: *std.Io.Reader,
    format: parsers.Format,
    list_w: *std.Io.Writer,
    wild_w: *std.Io.Writer,
) Error!Result;
```

### S2.3 `compile` algorithm

1. Two `std.ArrayList(u8)` arenas (`list_bytes`, `wild_bytes`) and two `std.ArrayList(u32)` offset lists, all from `gpa`. All four are freed before returning, on every path.
2. Loop with `r.takeDelimiter('\n')`:
   - `null` → end.
   - `error.StreamTooLong` → `counts.long_lines += 1`, then `r.discardDelimiterInclusive('\n')` (tolerating `error.EndOfStream` as end of input) and continue. **Not doing this discard is an infinite loop** — `takeDelimiter` leaves the stream unmodified on `StreamTooLong` (verified, Reader.zig:885).
   - Strip a trailing `\r` (CRLF files are common).
3. `parsers.parseLine(format, line)`; `.ignore` continues, `.regex` and `.unsupported` increment their counters and continue.
4. For `.domain`, split `line.text` on ASCII whitespace and process each field; for `.wildcard`, process `line.text` as one field with `covers_apex` remembered.
5. Per candidate field, in order: a. A leading `*.` makes it a wildcard candidate over the remainder; a `*` anywhere else makes it `invalid` (blocklist entries are suffixes, not patterns — patterns belong to the `rules` table). b. Strip one trailing `.`. c. Reject any byte ≥ 0x80 or any ASCII control byte → `invalid`. d. Lowercase ASCII into a `[types.max_name_len]u8` stack buffer. e. `dns.name.fromText` must accept it → else `invalid`. f. Fewer than two labels → `invalid`. This is what keeps `localhost`, `local`, `broadcasthost` and the `ip6-*` names that every hosts list carries from black-holing the loopback names of every client on the LAN. It is the single highest-consequence rule in this file. g. Append to `list_bytes` (domain) or `wild_bytes` (wildcard), recording the offset. A `.wildcard` with `covers_apex` appends to **both**. h. Either list exceeding `max_domains` entries → `error.TooManyDomains`.
6. Sort each offset list with `std.mem.sortUnstableContext` comparing the stored names bytewise, then write unique entries to the matching writer, each followed by `\n`, counting duplicates.
7. Hash both bodies as they are written (`std.crypto.hash.sha2.Sha256` streaming: `update` per emitted line, `final`, `std.fmt.bytesToHex(digest, .lower)`), `.list` first then `.wild`.
8. Return `Result`. `counts.domains` and `counts.wildcards` are the **written, deduplicated** counts — they are what `blocklist_sources.domain_count` and `wildcard_count` store, and what the UI shows.

### S2.4 Tests (in-file, `std.Io.Reader.fixed` / `std.Io.Writer.Allocating`)

- Hosts fixture with sink IPs, comments, a duplicate, `localhost`, an over-long line and a regex line: every counter has the expected value and the body is exactly the expected sorted text.
- Domains fixture and ABP fixture likewise, the ABP one asserting `||x.com^` produces `x.com` in **both** bodies.
- **Determinism**: compile the same fixture twice → identical bodies and identical checksums.
- **Order independence**: compile a shuffled permutation of the same fixture → identical bodies.
- Uppercase input compiles to lowercase output; a trailing-dot input compiles without the dot.
- A candidate with a non-ASCII byte, a single-label candidate, and a `a*b.com` candidate each land in `counts.invalid` and appear in neither body.
- An input of 3,000 lines with a 5,000-byte line in the middle: `long_lines == 1`, the surrounding lines are all present, and the call **terminates** (the `StreamTooLong` regression test).
- An empty input produces two empty bodies and the sha256 of the empty string.
- `compile` under `checkAllAllocationFailures` leaks nothing.

### S2.5 Acceptance criteria

- [ ] `zig fmt --check` and `zig ast-check` clean on both files.
- [ ] Neither file takes a `std.Io` value, opens a file, or reads a clock.
- [ ] `domain_set.zig` imports only `std`.
- [ ] `contains` compares full bytes on every probe; no code path returns a hit from a hash
      comparison alone.
- [ ] The `StreamTooLong` discard is implemented and covered by the 3,000-line test.
- [ ] The two-label minimum is implemented and covered by a `localhost` test.
- [ ] Determinism and order-independence tests pass.

---

## Session S3: `src/filter/safesearch.zig`, `src/filter/response.zig`

Pure. `safesearch.zig` imports `std` and `../dns/name.zig`; `response.zig` imports `std`, `../dns/*` and `../config/model.zig`.

### S3.1 `safesearch.zig`

```zig
pub const Entry = struct { domain: []const u8, target: []const u8 };

/// PLAN §7.4. Sorted by `domain`, so the table is searchable and diffable, and
/// asserted sorted by a comptime block. Every target is a name the operator's
/// upstream can resolve; nxdns never hardcodes an address.
pub const table = [_]Entry{
    .{ .domain = "bing.com",           .target = "strict.bing.com" },
    .{ .domain = "duckduckgo.com",     .target = "safe.duckduckgo.com" },
    .{ .domain = "google.com",         .target = "forcesafesearch.google.com" },
    .{ .domain = "pixabay.com",        .target = "safesearch.pixabay.com" },
    .{ .domain = "www.bing.com",       .target = "strict.bing.com" },
    .{ .domain = "www.duckduckgo.com", .target = "safe.duckduckgo.com" },
    .{ .domain = "www.google.com",     .target = "forcesafesearch.google.com" },
    .{ .domain = "www.youtube.com",    .target = "restrictmoderate.youtube.com" },
    .{ .domain = "youtube.com",        .target = "restrictmoderate.youtube.com" },
    .{ .domain = "m.youtube.com",      .target = "restrictmoderate.youtube.com" },
    .{ .domain = "youtubei.googleapis.com",       .target = "restrictmoderate.youtube.com" },
    .{ .domain = "youtube.googleapis.com",        .target = "restrictmoderate.youtube.com" },
    .{ .domain = "www.youtube-nocookie.com",      .target = "restrictmoderate.youtube.com" },
};

/// Exact match on a normalized name (lowercase, no trailing dot). Google's
/// country domains (`google.de`, …) are NOT enumerated: the list is unbounded,
/// it goes stale, and `forcesafesearch.google.com` is the documented target for
/// every one of them — an operator who needs a country domain adds a rule.
/// State that reasoning in the file.
pub fn lookup(domain: []const u8) ?[]const u8;

/// The rewritten question name for a matched query, as a `dns.name.Name`.
/// Applying it — sending the rewritten question upstream and prefixing the
/// answer with a CNAME from the original name to `target` — is the handler's
/// job (Phase 7). Nothing here builds a response.
pub fn rewrite(domain: []const u8) ?name.Name;
```

The table is asserted sorted and duplicate-free in a `comptime` block, and `lookup` is a binary search. A test walks every entry and asserts `dns.name.fromText` accepts both sides.

### S3.2 `response.zig` — blocked-response synthesis (PLAN §6.2)

```zig
pub const Options = struct {
    mode: model.BlockResponse,   // .zero | .nxdomain
    ttl: u32,                    // blocking.ttl
};

pub const Error = packet.ResponseBuilder.Error;

/// Writes a blocked reply for `q` into `buf` and returns a prefix of it.
///
/// `.zero`: A → 0.0.0.0, AAAA → ::, every other qtype → NOERROR with no answer
///   (NODATA). Synthesizing an address for a qtype that does not carry one is
///   not possible, and NXDOMAIN for, say, an MX query would tell the client the
///   name does not exist while an A query says it does.
/// `.nxdomain`: RCODE = NXDOMAIN, no answer, for every qtype.
///
/// No SOA is placed in the authority section: nxdns is not authoritative for
/// the name and a synthesized SOA would give resolvers a negative-caching TTL
/// nxdns cannot honour. Document that in the file.
///
/// `request_opt` echoes EDNS exactly as `handler.zig` does: when the query
/// carried an OPT record, the reply carries one with the same payload size and
/// the DO bit passed through.
pub fn writeBlocked(
    buf: []u8,
    request: header.Header,
    q: question.Question,
    request_opt: ?edns.OptRecord,
    do_bit: bool,
    options: Options,
) Error![]u8;
```

Only the question's class `IN` is answered with addresses; a non-`IN` class takes the NODATA path.

Tests (in-file): for each of the two modes × {A, AAAA, MX, HTTPS} × {with OPT, without OPT}, parse the produced message back with `packet.parse` and assert the rcode, ancount, arcount, the echoed question, the rdata bytes and the TTL. One test asserts a `buf` too small returns `error.WriteFailed` rather than truncating.

### S3.3 Acceptance criteria

- [ ] `zig fmt --check` and `zig ast-check` clean on both files.
- [ ] The safe-search table is comptime-asserted sorted and duplicate-free.
- [ ] Neither file takes a `std.Io` value or an allocator.
- [ ] Every blocked-response case in S3.2 is a named test that re-parses the output.

---

## Session S4: `src/local/records.zig`, `src/local/forward_zones.zig`

Pure. Both build immutable lookup structures from the model types the repositories already return.

### S4.1 `records.zig`

```zig
pub const Value = union(enum) { a: [4]u8, aaaa: [16]u8, cname: name.Name };

pub const Record = struct {
    /// Normalized owner name: lowercase, no trailing dot.
    owner: []const u8,
    value: Value,
    ttl: u32,
};

pub const Error = error{ OutOfMemory, BadRecordValue, BadRecordName, TooManyRecords };
pub const max_records: usize = 10_000;

pub const Records = struct {
    /// Arena-owned, sorted by (owner, rtype) so lookup is a binary search and
    /// the answer order for one name is stable across restarts.
    items: []const Record,

    pub const empty: Records;

    /// `gpa` owns the result; `deinit` frees it. Values are parsed here, once:
    /// an `a` value through `NetAddress.parse` (must be `.ip4`), `aaaa` (`.ip6`),
    /// a `cname` through `dns.name.fromText`. A bad value is an error, not a
    /// skipped row — `validate.zig` already rejects these, so reaching one here
    /// means the database was edited behind nxdns's back and silence would make
    /// a record vanish with no signal.
    pub fn build(gpa: std.mem.Allocator, rows: []const model.LocalRecord) Error!Records;
    pub fn deinit(self: *Records, gpa: std.mem.Allocator) void;

    /// All records for `domain` whose type matches `qtype`, plus any CNAME
    /// (RFC 1034 §3.6.2: a CNAME answers every qtype). Empty slice = no local
    /// record. Allocation-free.
    pub fn lookup(self: *const Records, domain: []const u8, qtype: types.Type) []const Record;

    /// True when the name has any local record of any type. The handler needs
    /// this to answer NODATA instead of forwarding a name nxdns owns.
    pub fn hasName(self: *const Records, domain: []const u8) bool;
};

/// Writes `records` as answers into a builder the caller has already
/// initialized with the request header and question. Mechanism only.
pub fn writeAnswers(
    b: *packet.ResponseBuilder,
    owner: name.Name,
    records: []const Record,
) packet.ResponseBuilder.Error!void;
```

Local records are group-independent (PLAN §6.4) and are matched **before** filtering. Resolving a CNAME target through the pipeline is Phase 7; `writeAnswers` emits the CNAME record and stops.

### S4.2 `forward_zones.zig`

```zig
pub const Zone = struct {
    /// Normalized: lowercase, no trailing dot.
    zone: []const u8,
    resolver: validate.Resolver,
};

pub const Error = error{ OutOfMemory, BadZone, BadResolver, TooManyZones };
pub const max_zones: usize = 1_000;

pub const Zones = struct {
    /// Arena-owned, sorted by descending label count then by name, so the first
    /// match found by a forward scan is the longest one.
    items: []const Zone,

    pub const empty: Zones;

    pub fn build(gpa: std.mem.Allocator, rows: []const model.ForwardZone) Error!Zones;
    pub fn deinit(self: *Zones, gpa: std.mem.Allocator) void;

    /// Longest-suffix match on LABEL boundaries: `lan.home` matches `nas.lan.home`
    /// and `lan.home`, and does NOT match `notlan.home`. `10.in-addr.arpa`
    /// matches every reverse name under it. Allocation-free.
    pub fn match(self: *const Zones, domain: []const u8) ?*const Zone;
};
```

`build` parses each `resolver` string with `validate.parseResolver` — the function whose doc comment already names this file as its Phase 5 importer. There is no second resolver parser.

### S4.3 Tests (in-file)

`records.zig`:
- Build from A, AAAA and CNAME rows; `lookup("nas.lan", .a)` returns the A record; `.aaaa` returns the AAAA; `.mx` returns nothing; with a CNAME present, every qtype returns the CNAME.
- Two A records for one name both come back, in a stable order across two builds.
- Uppercase and trailing-dot owner names normalize to the same key.
- A bad `a` value (`"::1"`), a bad `aaaa` value, a bad CNAME target and an unparseable owner each produce their typed error.
- `writeAnswers` output re-parses with the expected ancount, types, TTLs and rdata.
- `build` under `checkAllAllocationFailures`.

`forward_zones.zig`:
- `lan.home` matches `nas.lan.home`, `a.b.lan.home` and `lan.home`; does not match `notlan.home`, `home` or `lan.home.evil.net`.
- With both `home` and `lan.home` configured, `nas.lan.home` matches `lan.home` (longest wins).
- `10.in-addr.arpa` matches `5.4.3.10.in-addr.arpa`.
- A bad resolver URL → `error.BadResolver`; a bad zone → `error.BadZone`.
- `build` under `checkAllAllocationFailures`.

### S4.4 Acceptance criteria

- [ ] `zig fmt --check` and `zig ast-check` clean on both files.
- [ ] Neither file takes a `std.Io` value or reads a clock.
- [ ] `forward_zones.zig` calls `validate.parseResolver`; no second resolver parser exists
      (`grep -rn "udp://" src/local/` shows only test text).
- [ ] Suffix matching is on label boundaries, proven by the `notlan.home` test.
- [ ] Every bullet in S4.3 exists as a named test.

---

## Session S5: `src/filter/rules.zig`, `src/filter/matcher.zig`

Pure, and the heart of the milestone. Depends on S1's `wildcard.zig` and S2's `domain_set.zig`.

### S5.1 `rules.zig` — one group's explicit rules

```zig
pub const Error = error{ OutOfMemory, BadPattern, TooManyWildcards } || domain_set.DomainSet.Error;
pub const max_wildcards_per_group: usize = 4096;

pub const RuleSet = struct {
    exact_allow: domain_set.DomainSet,
    exact_block: domain_set.DomainSet,
    /// Arena-owned, normalized, sorted for determinism. Scanned linearly:
    /// these are operator-authored and few, and a linear scan over ≤ 4096
    /// short patterns is far cheaper than any index that would have to be
    /// rebuilt on every swap.
    wildcard_allow: []const []const u8,
    wildcard_block: []const []const u8,

    pub const empty: RuleSet;

    /// `rows` are this group's rules only (already filtered by the caller).
    /// Patterns are normalized (lowercase, trailing dot stripped) and validated:
    /// `.exact` through `dns.name.fromText`, `.wildcard` through
    /// `wildcard.validate`. An invalid pattern is `error.BadPattern` — the
    /// database went through `validate.zig`, so an invalid one here means the
    /// rows were edited underneath nxdns.
    pub fn build(gpa: std.mem.Allocator, rows: []const model.Rule, seed: u64) Error!RuleSet;
    pub fn deinit(self: *RuleSet, gpa: std.mem.Allocator) void;
    pub fn memoryBytes(self: *const RuleSet) usize;
};
```

`build` must be given only one group's rows; splitting `listRules` output by group is the caller's job (S5.3's `Snapshot.build`), because only it holds the group table.

### S5.2 `matcher.zig` — normalization, candidates, decision

```zig
pub const Reason = enum {
    none,
    rule_allow_exact,
    rule_block_exact,
    rule_allow_wildcard,
    rule_block_wildcard,
    blocklist_domain,
    blocklist_wildcard,
};

pub const Decision = struct {
    blocked: bool,
    reason: Reason,
    /// The candidate (or pattern) that decided it; borrowed from the caller's
    /// normalized buffer or from the snapshot. "" when `reason == .none`.
    matched: []const u8,
    /// `.blocklist_*` only: index into `Snapshot.sources`, for the block reason
    /// the query log (Phase 6) and the UI (Phase 8) will show.
    source: ?u32 = null,
};

/// Lowercase ASCII, trailing dot stripped, written into `buf`. Returns a slice
/// of `buf`. The root name normalizes to "".
pub fn normalize(qname: name.Name, buf: *[types.max_name_len]u8) []const u8;

/// Full name, then each parent, ending at the last two-label suffix. The TLD
/// alone is NOT a candidate: a rule or list entry on `com` is a configuration
/// mistake that would take the whole internet with it, and refusing to walk
/// that far costs nothing real.
pub const Candidates = struct {
    rest: []const u8,
    pub fn init(domain: []const u8) Candidates;
    pub fn next(self: *Candidates) ?[]const u8;
};
```

### S5.3 `matcher.zig` — the snapshot

```zig
pub const SourceSets = struct {
    /// Row id, so the manager can map a decision back to `blocklist_sources`.
    id: i64,
    /// Borrowed from the snapshot arena; the source's display name for the UI.
    name: []const u8,
    domains: domain_set.DomainSet,
    wildcards: domain_set.DomainSet,
};

pub const Group = struct {
    id: i64,
    name: []const u8,
    safe_search: bool,
    rules: rules.RuleSet,
    /// Indices into `Snapshot.sources`, ascending, deduplicated.
    sources: []const u32,
};

pub const ClientEntry = struct { key: address.NetAddress.Key, group: u32 };
pub const PrefixEntry = struct { prefix: address.Prefix, group: u32, priority: i32 };

pub const Snapshot = struct {
    arena: std.heap.ArenaAllocator,
    groups: []Group,
    sources: []SourceSets,
    clients: []ClientEntry,
    prefixes: []PrefixEntry,
    /// Index into `groups` of the group named "default". Always valid:
    /// `build` returns `error.MissingDefaultGroup` otherwise.
    default_group: u32,
    /// Monotonic, assigned by the manager. Logged on every swap so an operator
    /// can tell which generation answered a query.
    generation: u64,

    pub const Input = struct {
        groups: []const model.Group,
        group_sources: []const model.GroupSource,
        sources: []const model.BlocklistSource,
        rules: []const model.Rule,
        clients: []const model.Client,
        prefixes: []const model.ClientPrefix,
        /// One entry per `sources[i]`, in the same order: the compiled bodies
        /// already read from disk with their headers stripped. An enabled source
        /// whose bodies are absent is `error.MissingCompiledSource` — a silently
        /// unenforced blocklist is exactly the failure PLAN §1.3 exists to
        /// prevent.
        compiled: []const Compiled,
        seed: u64,
        generation: u64,
    };

    pub const Compiled = struct { list_body: []const u8, wild_body: []const u8 };

    pub const Error = error{
        OutOfMemory, MissingDefaultGroup, UnknownGroup, UnknownSource,
        MissingCompiledSource, BadClientIp, BadClientPrefix,
    } || rules.Error;

    /// Builds an immutable snapshot. Every string is copied into `arena`, so the
    /// caller may free the repository lists immediately afterwards. Disabled
    /// sources are skipped entirely — they cost no memory.
    pub fn build(gpa: std.mem.Allocator, input: Input) Error!Snapshot;
    pub fn deinit(self: *Snapshot) void;

    /// PLAN §3.10 precedence, allow wins at equal specificity:
    ///   1. exact/parent allow rules   2. exact/parent block rules
    ///   3. wildcard allow rules       4. wildcard block rules
    ///   5. blocklist domains          6. blocklist wildcards
    /// `domain` is normalized (`normalize`). No allocation, no lock, no clock.
    pub fn evaluate(self: *const Snapshot, group: u32, domain: []const u8) Decision;

    /// PLAN §7.2 matching half: exact client row, else longest-prefix match
    /// (ties broken by longer prefix then higher `priority`), else the default
    /// group. Auto-materialization is Phase 7 (resolved ambiguity 4).
    pub fn groupForClient(self: *const Snapshot, addr: address.NetAddress) u32;

    pub fn groupIndexById(self: *const Snapshot, id: i64) ?u32;
    pub fn groupIndexByName(self: *const Snapshot, name_text: []const u8) ?u32;
    pub fn safeSearch(self: *const Snapshot, group: u32) bool;
    pub fn memoryBytes(self: *const Snapshot) usize;
};
```

`evaluate` order is the specification, and it is level-by-level over the **whole candidate chain**, not candidate-by-candidate over the levels: level 1 is checked against every candidate before level 2 is checked against any. That is what makes "an allow rule on the parent beats a block rule on the child" true, which is the behaviour operators expect from an allow list.

Levels 5 and 6 iterate the group's sources in ascending index order and return the first hit, so the reported `source` is stable for a given snapshot. Level 5 tests **only the full name** and level 6 tests **only proper parents** (resolved ambiguity 1).

### S5.4 Tests (in-file)

Precedence — one named test per row, each asserting `blocked`, `reason` and `matched`:

| Configuration | Query | Expected |
|---|---|---|
| block rule `ads.example.com`, nothing else | `ads.example.com` | blocked, `rule_block_exact` |
| block rule `example.com` | `ads.example.com` | blocked, `rule_block_exact`, matched `example.com` (parent walk) |
| block rule `example.com`, allow rule `ads.example.com` | `ads.example.com` | allowed, `rule_allow_exact` |
| block rule `ads.example.com`, allow rule `example.com` | `ads.example.com` | allowed (allow level runs first over the whole chain) |
| allow rule `*.example.com`, block rule `ads.example.com` | `ads.example.com` | blocked (exact block, level 2, beats wildcard allow, level 3) |
| allow wildcard `*.example.com`, block wildcard `*.example.com` | `a.example.com` | allowed (tie → allow wins) |
| list entry `tracker.net` | `tracker.net` | blocked, `blocklist_domain` |
| list entry `tracker.net` | `sub.tracker.net` | **allowed** (ambiguity 1) |
| wild entry `tracker.net` | `sub.tracker.net` | blocked, `blocklist_wildcard` |
| wild entry `tracker.net` | `tracker.net` | allowed (a `.wild` entry covers proper subdomains only) |
| allow rule `sub.tracker.net`, wild entry `tracker.net` | `sub.tracker.net` | allowed |
| nothing configured | `example.com` | allowed, `reason == .none` |
| source assigned to group A only | same query in group B | allowed in B, blocked in A |
| disabled source | its entry | allowed (disabled sources are not loaded) |

Also:
- `normalize` lowercases, strips one trailing dot, and returns `""` for the root.
- `Candidates` over `a.b.example.com` yields exactly `a.b.example.com`, `b.example.com`, `example.com` — and not `com`.
- `groupForClient`: exact IPv4 hit; exact IPv6 hit through the canonical key; `/24` prefix hit; overlapping `/16` and `/24` → the `/24` wins; equal-length prefixes → higher priority wins; no match → default group.
- `Snapshot.build` without a `default` group → `error.MissingDefaultGroup`; with a `group_sources` row naming an unknown source → `error.UnknownSource`; with an enabled source whose `compiled` entry is absent → `error.MissingCompiledSource`.
- Two snapshots built from the same input with different seeds produce identical decisions over a 40-query table.
- `Snapshot.build` under `checkAllAllocationFailures` leaks nothing.
- `memoryBytes` on a snapshot with 10,000 synthetic domains stays under the S§Memory-budget bound (`count * (avg_len + 1) * 2 + index`), asserted as an inequality so it is a real regression guard.

### S5.5 Acceptance criteria

- [ ] `zig fmt --check` and `zig ast-check` clean on both files.
- [ ] Neither file takes a `std.Io` value, opens a file, or reads a clock.
- [ ] `evaluate` performs no allocation (no allocator is reachable from its signature).
- [ ] Every row of the S5.4 precedence table exists as a named test.
- [ ] The candidate chain stops before the TLD, proven by a test.
- [ ] `Snapshot.build` copies every string into its arena; a test frees the input lists before
      calling `evaluate`.

---

## Session S6: `src/filter/fetcher.zig`

The first of the three `std.Io` files. Downloads one source; knows nothing about parsing, files or the database.

### S6.1 Signatures

```zig
pub const max_body_bytes: usize = 64 * 1024 * 1024;
pub const redirect_buffer_len: usize = 8192;   // RFC 9110 recommendation (Client.zig:1128)
pub const min_transfer_buf: usize = 16 * 1024;

pub const Error = error{
    BadUrl, ConnectFailed, TlsFailed, SendFailed, ReceiveFailed, HttpStatus,
    BodyTooLarge, Timeout, Canceled, OutOfMemory, SystemResources, Unexpected,
};

pub const Result = struct { bytes_read: u64, status: std.http.Status };

pub const Fetcher = struct {
    http: *std.http.Client,       // caller-owned, shared, pools connections
    transfer_buf: []u8,           // caller-owned, ≥ min_transfer_buf
    redirect_buf: []u8,           // caller-owned, ≥ redirect_buffer_len

    /// GETs `url` and streams the body into `w`. Nothing is buffered whole:
    /// a 64 MB list must not become a 64 MB allocation, and the caller is
    /// writing into a temporary file anyway.
    ///
    /// `budget` bounds the WHOLE exchange. `std.http.Client` has no per-request
    /// deadline (verified), so the caller runs this under `io.concurrent` and
    /// cancels the future — the same pattern `tls_client_integration_test.zig`
    /// established. This function therefore takes no timeout parameter and
    /// simply propagates `error.Canceled`; S8 owns the deadline.
    pub fn fetch(self: *Fetcher, io: std.Io, url: []const u8, w: *std.Io.Writer) Error!Result;
};
```

Rules:

- `std.Uri.parse` failure → `error.BadUrl`. A scheme other than `http`/`https` → `error.BadUrl`.
- `accept_encoding` is overridden to identity (resolved ambiguity 6), matching `doh_client.zig`.
- `redirect_behavior` keeps the stdlib default of 3; `receiveHead(self.redirect_buf)` follows them. `error.TooManyHttpRedirects` maps to `error.HttpStatus`.
- Status other than `.ok` → `error.HttpStatus`. An error return carries no `Result`, so the fetcher stores the numeric status in a `last_status: ?std.http.Status` field, cleared at the start of each `fetch` and set from every response head; the caller reads it after `error.HttpStatus`. `content-type` is **not** checked: blocklists are served as `text/plain`, `application/octet-stream`, `text/html` and worse, and the compiler's invalid-line counters are the honest signal about content.
- The body is copied to `w` in `transfer_buf`-sized chunks with a running total; exceeding `max_body_bytes` → `error.BodyTooLarge` (and the caller discards its temporary file).
- Error mapping reuses `transport.mapLocal` first, then classifies by phase, exactly as `doh_client.zig`'s `mapError` does. Do not invent a second classification vocabulary.

### S6.2 Tests

In-file (no sockets): URL rejection table (`ftp://x`, `x`, `https://`), and a `Fetcher` value constructed against an undefined `std.http.Client` proving the URL check precedes any client use (the `doh_client.zig` pattern).

Everything real belongs to S9: a loopback `std.http.Server` serving a fixture, a redirect chain, a 404, and a body that exceeds a lowered cap.

### S6.3 Acceptance criteria

- [ ] `zig fmt --check` and `zig ast-check` clean.
- [ ] `accept_encoding` is pinned to identity and the reason is commented.
- [ ] The body is streamed; no `allocRemaining`, no whole-body allocation anywhere in the file.
- [ ] No timeout parameter and no sleep: the deadline is the caller's (S8.4).
- [ ] `transport.mapLocal` is used before any phase classification.

---

## Session S7: `src/local/forward_client.zig`

Conditional forwarding's transport (resolved ambiguity 5). Implements `transport.Client` so the Phase 7 handler treats a forward zone exactly like any other exchange.

### S7.1 Signatures

```zig
pub const ForwardClient = struct {
    resolver: validate.Resolver,
    /// Caller-owned scratch for the TCP length-prefixed path.
    frame_buf: []u8,
    read_timeout: std.Io.Clock.Duration,
    stats: Stats = .{},

    pub const Stats = struct {
        queries: u64 = 0,
        udp_truncated: u64 = 0,   // TC=1 → retried over TCP
        failures: u64 = 0,
    };

    pub fn init(resolver: validate.Resolver, frame_buf: []u8, read_timeout: std.Io.Clock.Duration) ForwardClient;
    pub fn client(self: *ForwardClient) transport.Client;

    /// UDP: send, `receiveTimeout`, validate. TC=1 → retry over TCP with the
    /// RFC 1035 §4.2.2 two-byte length prefix. `.tcp` resolvers skip straight
    /// to the TCP path.
    pub fn exchange(self: *ForwardClient, io: std.Io, query: []const u8, response_buf: []u8)
        transport.ExchangeError![]u8;
};
```

Rules:

- Every response passes `transport.validateResponse(query, response)` before it is returned — a forward zone points at LAN infrastructure, which is not a reason to trust its framing.
- UDP uses `Socket.receiveTimeout` (verified implemented on the POSIX Threaded backend, milestone 3). A datagram from an address other than the resolver's is **discarded and counted**, and the receive is retried within the remaining budget.
- TCP has no read timeout in 0.16.0: run the exchange under `io.concurrent` and cancel the loser against a `std.Io.Clock.Duration` sleep, exactly as milestone 3 does. Never set `ConnectOptions.timeout` — the Threaded backend panics (Threaded.zig:12077).
- Failures map through `transport.mapLocal` first, then to the phase's `PeerFault`. Every socket is closed on every path.
- No health tracking and no backoff: `upstream/health.zig` and `pool.zig` model the *upstream* pool, and a forward zone has exactly one designated resolver with no failover partner. Say so in a comment so its absence does not read as an oversight.

### S7.2 Tests

In-file: the `transport.Client` vtable instantiation check (milestone 3's pattern) and the stats struct defaults. Everything with a socket is S9's: a loopback UDP responder answering an A query, a loopback responder setting TC=1 followed by a TCP responder returning the full answer, a silent responder proving the timeout produces `error.Timeout`, and a responder answering with a mismatched ID proving `error.ResponseMismatch`.

### S7.3 Acceptance criteria

- [ ] `zig fmt --check` and `zig ast-check` clean.
- [ ] `ConnectOptions.timeout` appears nowhere.
- [ ] Every response goes through `transport.validateResponse`.
- [ ] A datagram from a foreign source address is counted and discarded, not returned.
- [ ] The file implements `transport.Client` and defines no second client interface.

---

## Session S8: `src/filter/manager.zig`

The `BlocklistManager` of PLAN §4: compiled-file layout, refresh, metadata, snapshot build and the RCU swap. The only file in this milestone that touches both the database and the filesystem.

### S8.1 The two repository additions this session owns

`blocklist_sources` carries counters and a checksum that milestone 4 deliberately excluded from the config model (runtime facts, not configuration). Refresh has to write them, so `sources_repo.zig` gains exactly two functions — additive, no signature of an existing function changes:

```zig
pub const SourceRow = struct {
    id: i64,
    url: []const u8,
    name: []const u8,
    enabled: bool,
    last_updated: ?i64,
    domain_count: i64,
    wildcard_count: i64,
    skipped_regex_count: i64,
    checksum: ?[]const u8,
};

/// Every source with its row id and runtime columns. Strings are heap copies.
/// ORDER BY url (matching `listBlocklistSources`, milestone 4 §S4.2).
pub fn listSourceRows(database: *db.Db, gpa: Allocator) db.Error!std.ArrayList(SourceRow);
pub fn freeSourceRows(gpa: Allocator, items: []const SourceRow) void;

/// Writes the runtime columns for one source after a successful compile.
pub fn updateSourceStats(database: *db.Db, id: i64, stats: SourceStats) db.Error!void;
```

This is the one exception to "no session edits a milestone 1–4 file", and it is scoped to appending two functions and their tests to `sources_repo.zig`. S8 owns that file for this milestone. No schema change and no migration: every column already exists (PLAN §11.2).

### S8.2 Compiled-file layout (PLAN §3.8, §3.13)

```
<data_dir>/blocklists/<source_id>.list
<data_dir>/blocklists/<source_id>.wild
```

Directory created with `createDirPathStatus(io, path, .fromMode(0o700))`; files written 0o600 through `createFileAtomic` + `replace` (milestone 4's verified helper), so a crash mid-write can never leave a half-list that would load as a valid, shorter blocklist. `<source_id>` is the `blocklist_sources` row id, so a renamed URL keeps its files and a deleted source's files are removed by `pruneOrphans` (below).

Header, written by the manager ahead of the body, every line prefixed `# `:

```
# nxdns blocklist
# url <url>
# format <hosts|domains|abp>
# fetched_at <unix seconds>
# domains <n>
# wildcards <n>
# skipped_regex <n>
# skipped_unsupported <n>
# invalid <n>
# sha256 <64 hex chars>
```

The loader strips every leading `#` line and hands the remainder to `DomainSet.build`. The `sha256` covers the `.list` body followed by the `.wild` body — **not** the header, so the checksum is stable across refetches of unchanged content while `fetched_at` moves.

### S8.3 Signatures

```zig
pub const Paths = struct {
    dir: std.Io.Dir,          // <data_dir>
    subdir: []const u8 = "blocklists",
};

pub const SourceStatus = struct {
    id: i64,
    url: []const u8,          // borrowed from the manager's arena
    state: enum { ok, never_fetched, fetch_failed, compile_failed, load_failed },
    last_attempt: i64 = 0,
    last_success: i64 = 0,
    counts: compiler.Counts = .{},
    /// Fixed-size, no allocation on the failure path.
    last_error: [128]u8 = @splat(0),
    last_error_len: u8 = 0,
};

pub const Manager = struct {
    gpa: std.mem.Allocator,
    database: *db.Db,
    paths: Paths,
    fetcher: *fetcher.Fetcher,
    update: model.BlocklistUpdate,
    total_budget: std.Io.Clock.Duration,

    lock: std.Io.RwLock,
    current: ?*matcher.Snapshot,
    generation: u64,
    statuses: []SourceStatus,

    pub const Error = error{ OutOfMemory, ... } || db.Error || matcher.Snapshot.Error;

    pub fn init(gpa, database, paths, fetcher_ptr, update, total_budget) Error!Manager;
    pub fn deinit(self: *Manager, io: std.Io) void;

    /// Reads the database and every compiled file, builds a snapshot and swaps
    /// it in. Called at startup and after any refresh. A source whose compiled
    /// files are missing or whose checksum does not match is marked
    /// `.load_failed` and REFRESHED, not silently skipped.
    pub fn reload(self: *Manager, io: std.Io) Error!void;

    /// Fetch + compile + atomically replace the compiled files for one source,
    /// then update its row. Returns false when the content was unchanged
    /// (checksum equal), in which case only `last_updated` moves.
    pub fn refreshSource(self: *Manager, io: std.Io, row: sources_repo.SourceRow) Error!bool;

    /// Every enabled source, one at a time, then one `reload`. Never stops at
    /// the first failure: a broken source must not hide the rest.
    pub fn refreshAll(self: *Manager, io: std.Io) Error!void;

    /// Long-running task: sleeps `update.interval_hours`, refreshes, repeats.
    /// Returns on `error.Canceled`. Started with `io.concurrent` by Phase 7's
    /// wiring; nothing in this milestone starts it automatically.
    pub fn runScheduler(self: *Manager, io: std.Io) std.Io.Cancelable!void;

    /// Reader side of the RCU swap. The handle holds a shared lock; the caller
    /// MUST release it and MUST NOT retain the snapshot pointer afterwards.
    pub const Handle = struct {
        snapshot: *const matcher.Snapshot,
        manager: *Manager,
        pub fn release(self: Handle, io: std.Io) void;
    };
    pub fn acquire(self: *Manager, io: std.Io) ?Handle;

    /// Copies the status table for the API and `nxdns check`.
    pub fn statusSnapshot(self: *Manager, io: std.Io, out: []SourceStatus) usize;

    /// Deletes `<id>.list`/`<id>.wild` files whose id is not in the database.
    pub fn pruneOrphans(self: *Manager, io: std.Io) Error!void;
};
```

**The swap is an `std.Io.RwLock`, not a lock-free pointer.** PLAN §7.3 says "readers lock-free", and this is a deliberate, documented deviation. Freeing the old snapshot safely without a lock requires epoch-based reclamation or hazard pointers — a class of code that is very hard to get right and impossible to test convincingly, bought for a household resolver whose target is 100 qps. A shared lock held for the microseconds of one `evaluate` costs an uncontended atomic pair; the writer takes the exclusive lock only on a swap, which happens on refresh. The old snapshot is freed **after** `unlock` returns, and the `Handle` API makes "do not retain the pointer" the only shape the caller can write. State this reasoning in the file, and have the orchestrator amend PLAN §7.3.

### S8.4 `refreshSource` order — the order is the specification

1. `now = std.Io.Clock.real.now(io).toSeconds()`; `status.last_attempt = now`.
2. Create `<subdir>/<id>.list.tmp` and `<id>.wild.tmp` through `createFileAtomic` (`.permissions = .fromMode(0o600)`, `.replace = true`).
3. Download into a third temporary file (`<id>.raw.tmp`) rather than memory — `max_body_bytes` is 64 MB and the budget in §Memory has no room for it alongside two snapshots. Run `fetcher.fetch` under `io.concurrent` with a `total_budget` sleep racing it, and cancel the loser (milestone 3's pattern). A fetch failure sets `.fetch_failed` with the error name, logs at `warn`, and returns without touching the live compiled files.
4. Reopen the raw file, sniff the format with `parsers.detectFormat` over the first `parsers.sample_lines` lines, then `compiler.compile` from a `File.Reader` into the two temporary writers. Any compile error sets `.compile_failed` and returns; the live files are still untouched.
5. If `result.checksum` equals the stored `checksum`, `deinit` the atomics (which discards the temporaries), update only `last_updated`, and return `false`. Recompiling identical content into a new file would invalidate the snapshot for nothing.
6. Otherwise write the header, `replace` both atomics, delete the raw temporary, and `updateSourceStats` with the counts, the checksum and `last_updated = now`.
7. `status.state = .ok`, `status.counts = result.counts`, `status.last_success = now`.

Every failure path deletes its temporaries. No path leaves a `.tmp` behind, and no path deletes a good compiled file.

### S8.5 Failure visibility

- Every non-`ok` state records the error name into `SourceStatus.last_error` and logs once at `warn` with the source URL and the state. No `err` level, per the binding logging policy: the condition is recorded and surfaced, not swallowed.
- `refreshAll` returns successfully when at least one source failed; the failures live in `statuses`. It returns an error only when *nothing* could be done (out of memory, the database is unreachable). Phase 8 exposes the statuses at `GET /api/blocklists`; `nxdns check` gains nothing in this milestone.
- `reload` with zero enabled sources is normal (a fresh install), produces a valid empty snapshot, and logs at `info`.

### S8.6 Startup and scheduling policy

`runScheduler` refreshes a source at startup only when it needs it: no compiled file, a checksum mismatch against the file on disk, or `last_updated` older than `interval_hours`. A cold restart of a Pi must not re-download every list, and a boot loop must not turn into a download loop. After the initial pass it sleeps `interval_hours` between full passes. `update.enabled == false` means `runScheduler` returns immediately after the initial load; manual refresh through `refreshAll` still works (Phase 8's `POST /api/blocklists/update`).

### S8.7 Tests

In-file (`:memory:` database, no filesystem): `init`/`deinit`; `acquire` before any `reload` returns `null`; the header writer produces the exact expected text for a known `Counts`; the header stripper returns the body for a header-only file and for a file with no header; `SourceStatus.last_error` truncation at 128 bytes.

Everything with real files, real HTTP and real swaps is S9's.

### S8.8 Acceptance criteria

- [ ] `zig fmt --check` and `zig ast-check` clean on `manager.zig` and `sources_repo.zig`.
- [ ] `sources_repo.zig` gains exactly two public functions plus `SourceRow`/`freeSourceRows`; no
      existing signature changes; the new list has a deterministic `ORDER BY url`.
- [ ] No schema change, no migration step, no new column.
- [ ] Compiled files are written through `createFileAtomic` + `replace` at 0o600, in a 0o700
      directory created with `createDirPathStatus`.
- [ ] A fetch or compile failure leaves the previously compiled files byte-identical (test in S9).
- [ ] The RwLock deviation from PLAN §7.3 is documented in the file with its reasoning.
- [ ] The old snapshot is freed after `unlock`, never while a reader could hold it.
- [ ] `refreshAll` does not stop at the first failing source.
- [ ] `grep -n "std.log.err" src/filter/ src/local/` returns nothing.

---

## Session S9: `src/filter/filter_integration_test.zig`, `tests/fuzz/blocklist_fuzz.zig`

### S9.1 Hermetic integration cases (`-Dintegration`, `std.testing.tmpDir`)

*compile → load → match, through real files*

1. Compile a 5,000-line hosts fixture to real `.list`/`.wild` files, build a snapshot from them, and assert 20 sampled domains match and 20 non-members do not.
2. Recompile the same fixture into a second directory: both files are byte-identical, and so is the checksum.
3. Truncate a `.list` file mid-line and reload → `error.NotSorted` or `MissingCompiledSource`, and **the previous snapshot is still serving** (assert through `acquire`).

*fetcher against a loopback `std.http.Server`*

4. A 200 response with a hosts body → the compiled files exist, `blocklist_sources` counters and checksum are written, and `acquire` sees the domains.
5. A 302 to a second path → followed, same result.
6. A 404 → `.fetch_failed`, the previously compiled files are byte-identical, and the snapshot still blocks what it blocked before.
7. A body larger than a lowered `max_body_bytes` → `error.BodyTooLarge`, no `.tmp` file remains in the blocklist directory (assert by listing it).
8. Refetching identical content → `refreshSource` returns `false`, the compiled files' mtimes are unchanged, and `last_updated` moved.

*swap*

9. Under a snapshot acquired by one task, a concurrent `reload` completes and the holding task still reads a consistent snapshot; after `release` and a re-`acquire`, the new generation is visible.
10. `pruneOrphans` deletes files for a deleted source and leaves live ones alone.

*local records and forward zones, end to end*

11. Build `Records` from a seeded database (through `local_repo.listLocalRecords`), answer an A query for `nas.lan`, and re-parse the reply: one answer, correct rdata, correct TTL.
12. A CNAME local record answers an A query with the CNAME record and nothing else.
13. `ForwardClient` against a loopback UDP responder: an A query for `nas.lan.home` returns the responder's answer, and `Zones.match` selected that resolver.
14. The loopback responder sets TC=1; the client retries over TCP against a loopback TCP responder and returns the full answer, with `stats.udp_truncated == 1`.
15. A silent responder → `error.Timeout` inside the configured budget (assert the elapsed time is below twice the budget).
16. A responder answering with a wrong ID → `error.ResponseMismatch`.

*blocked responses*

17. For each `blocking.response` mode, synthesize a reply for a blocked A and AAAA query and re-parse it: `.zero` gives `0.0.0.0` / `::` with `blocking.ttl`; `.nxdomain` gives NXDOMAIN with no answer.

### S9.2 Fuzz target

`tests/fuzz/blocklist_fuzz.zig`, in the style of `tests/fuzz/dns_fuzz.zig` (milestone 2): a `std.testing.fuzz` test per parser plus one for `wildcard.matches`, each filling a buffer through `Smith.sliceWithHash` and feeding the prefix in. The acceptance property is "does not crash and does not hang": every parser returns a `Line` for any byte string, and `wildcard.matches` terminates for any pattern/domain pair (the pattern is first passed through `validate`, and only accepted patterns reach `matches`, matching how production uses it). Corpus entries: one hosts line, one ABP line, one regex line, one over-long line.

### S9.3 The build change (orchestrator, not this session)

```zig
const parsers_mod = b.createModule(.{
    .root_source_file = b.path("src/filter/parsers.zig"),
    .target = target,
    .optimize = optimize,
});
const blocklist_fuzz_mod = b.createModule(.{
    .root_source_file = b.path("tests/fuzz/blocklist_fuzz.zig"),
    .target = target,
    .optimize = optimize,
});
blocklist_fuzz_mod.addImport("parsers", parsers_mod);
const blocklist_fuzz_tests = b.addTest(.{
    .name = "blocklist-fuzz",
    .use_llvm = if (fuzz) true else null,
    .root_module = blocklist_fuzz_mod,
});
test_step.dependOn(&b.addRunArtifact(blocklist_fuzz_tests).step);
```

This is exactly why S1's five files import nothing outside `src/filter/`: `parsers.zig` is a module root here and in the aggregator, and an import that escaped its directory would fail with `error.ImportOutsideModulePath` (milestone 2). The in-file tests of those five files still run in the aggregator artifact; the fuzz artifact runs only `blocklist_fuzz.zig`'s tests.

### S9.4 Acceptance criteria

- [ ] `zig fmt --check` and `zig ast-check` clean on both files.
- [ ] All 17 hermetic cases exist as named tests and pass under `zig build test -Dintegration`.
- [ ] No hermetic test reaches a non-loopback address or leaves a file outside its `tmpDir`.
- [ ] The fuzz tests pass under plain `zig build test` (corpus replay + empty input).

---

## Module Layout

```
src/filter/parsers.zig                 S1  format vocabulary + dispatch + sniffing (std only)
src/filter/parser_hosts.zig            S1  hosts-file lines (std only)
src/filter/parser_domains.zig          S1  one-domain-per-line lists (std only)
src/filter/parser_abp.zig              S1  ABP subset; modifiers/exceptions unsupported (std only)
src/filter/wildcard.zig                S1  `*`-label pattern validate + match (std only)
src/filter/domain_set.zig              S2  arena + open-addressed exact set
src/filter/compiler.zig                S2  stream -> sorted, deduped .list/.wild bodies + sha256
src/filter/safesearch.zig              S3  per-group safe-search table + rewrite
src/filter/response.zig                S3  blocked-response synthesis (zero | nxdomain)
src/filter/rules.zig                   S5  one group's compiled allow/block rules
src/filter/matcher.zig                 S5  Snapshot, §3.10 precedence, group-for-client
src/filter/fetcher.zig                 S6  std.http.Client GET, streamed, capped
src/filter/manager.zig                 S8  compiled files, refresh, metadata, RCU swap, scheduler
src/filter/filter_integration_test.zig S9  -Dintegration: real files, loopback HTTP/UDP/TCP
src/local/records.zig                  S4  local A/AAAA/CNAME lookup + answer writing
src/local/forward_zones.zig            S4  zone suffix match -> validate.Resolver
src/local/forward_client.zig           S7  plain UDP/TCP resolver, transport.Client
src/storage/repositories/sources_repo.zig  S8  += listSourceRows, updateSourceStats
tests/fuzz/blocklist_fuzz.zig          S9  parser + wildcard fuzz targets
```

## File Ownership

| Files | Owner | Notes |
|---|---|---|
| `src/filter/parsers.zig`, `parser_hosts.zig`, `parser_domains.zig`, `parser_abp.zig`, `wildcard.zig` | S1 | frozen after S1 verifies; `std`-only imports |
| `src/filter/domain_set.zig`, `src/filter/compiler.zig` | S2 | frozen after S2 verifies |
| `src/filter/safesearch.zig`, `src/filter/response.zig` | S3 | |
| `src/local/records.zig`, `src/local/forward_zones.zig` | S4 | |
| `src/filter/rules.zig`, `src/filter/matcher.zig` | S5 | |
| `src/filter/fetcher.zig` | S6 | |
| `src/local/forward_client.zig` | S7 | |
| `src/filter/manager.zig`, `src/storage/repositories/sources_repo.zig` | S8 | the only milestone-4 file any session edits, and only additively (S8.1) |
| `src/filter/filter_integration_test.zig`, `tests/fuzz/blocklist_fuzz.zig` | S9 | |
| `build.zig`, `build.zig.zon`, `src/tests.zig` | orchestrator | no session edits these |
| `PLAN.md` §7.1, §7.3 | orchestrator | amended per resolved ambiguities 1 and 3, and per S8.3 |

No session touches `src/dns/`, `src/server/`, `src/upstream/`, `src/platform/`, `src/config/`, `src/cli.zig` or `src/main.zig`. A needed change there is reported, not made.

## Acceptance Criteria (Milestone 5 Complete)

- [ ] `zig build test` exits 0 with every new file wired into `src/tests.zig`, including the new
      `blocklist-fuzz` artifact.
- [ ] `zig build test -Dintegration` exits 0: milestone 1's loopback TLS echo, milestone 3's
      listener and resolver tests, milestone 4's 21 storage cases, and all 17 filtering cases.
- [ ] `zig build cross` still produces two statically linked executables.
- [ ] The PLAN §3.10 precedence table is proven row by row by the S5.4 tests.
- [ ] Compiling a fixture twice produces byte-identical bodies and checksums; compiling a shuffled
      permutation produces the same bodies.
- [ ] `grep -rn "std.log.err" src/filter/ src/local/` returns nothing.
- [ ] `grep -rln "std.Io," src/filter/ src/local/` names only `fetcher.zig`, `manager.zig`,
      `forward_client.zig` and the S9 test file `filter_integration_test.zig` (reader/writer
      interface parameters do not count; check the match).
- [ ] `grep -rn "regex" src/filter/` shows counting and skipping only — no matching engine.
- [ ] A hosts fixture containing `localhost`, `ip6-localhost` and `broadcasthost` compiles to a body
      containing none of them.
- [ ] A snapshot over a 1,000,000-entry synthetic list reports `memoryBytes()` under 40 MB (S5.4's
      inequality test, scaled) — the runnable form of the PLAN §18 budget.
- [ ] `zig fmt --check` clean repo-wide; GPG-signed lowercase commits.

## Anti-Requirements

- **No handler integration.** `src/server/handler.zig` is not edited. Nothing in this milestone is called from the query path; composing local records → forward zones → filtering → safe-search → cache → upstream is Phase 7. The pieces are built and tested standalone.
- **No CNAME uncloaking.** PLAN §6.3 is explicitly Phase 7 (§16). No chain walking, no depth-8 budget, no re-evaluation of answer-section names anywhere in this milestone.
- **No cache, no rate limiter, no query log, no disk monitor, no retention, no log rotation.** Phase 6. A `Decision` carries a `reason` for the future query log; nothing writes one.
- **No pause/resume.** Phase 7.
- **No web API, no SSE, no `/metrics`, no auth.** Phase 8. `SourceStatus` exists for that phase to read; no handler exists.
- **No regex engine, in any form, for any reason.** PLAN §2.2. Regex lines are counted and skipped.
- **No allow rules sourced from blocklists.** ABP exception rules (`@@`) are counted as unsupported. Allow policy lives in the `rules` table where an operator can see it.
- **No blocklist storage in SQLite.** PLAN Decision A: compiled flat files under `<data_dir>/blocklists/`, metadata columns only in `config.db`.
- **No schema change and no migration step.** Every column this milestone writes already exists.
- **No HTTP compression, no conditional requests (`ETag`/`If-Modified-Since`), no HTTP/2.** Unchanged content is detected by comparing the compiled checksum, which also catches a source that changes its headers without changing its content.
- **No client auto-materialization, no `last_seen` updates.** Phase 7 (resolved ambiguity 4).
- **No snapshot persistence.** The snapshot is rebuilt from the database and the compiled files at startup; caching it on disk would add a fourth thing that can be stale.
- **No lock-free reclamation scheme.** The documented `RwLock` deviation (S8.3) is the design, not a placeholder for a later epoch-based rewrite.
- **No third-party Zig packages.** stdlib plus the two pinned C libraries.

## As built (S1–S4, S6, S7 and orchestrator wiring)

Deviations from the text above, recorded after the first six sessions verified. Where this section and the session text disagree, this section wins.

**S1 parsers + wildcard.** `validate` counts labels before the 253-byte length check, so `TooManyLabels` is reachable. A hosts line with a sink address and no name is `.unsupported`. `||example.com` without `^` is `.wildcard` with `covers_apex = true`. `detectFormat` treats `$` as a marker only on non-comment lines; `||` and `@@` are matched anchored. Element-hiding separators are matched positionally since milestone 16 ruling 5: at offset 0 a selector must follow the separator; past offset 0 a domain-list character must precede it — so a `## Title` banner is not element hiding. `looksLikeIpLiteral` lives in `parsers.zig` and is shared with `parser_hosts.zig`. `wildcard.matches` is total on unvalidated input: the label splitter returns null above `max_labels` and `matches` returns false — no assert, because `parsers.zig` is the S9.3 fuzz root.

**S2 domain_set + compiler.** The line-length cap is enforced both ways: `error.StreamTooLong` is discarded with `discardDelimiterInclusive`, and a returned line over `max_line_len` is skipped; both increment `long_lines`. `DomainSet.build` maps an empty line to `error.NotSorted` and a line over 255 bytes to `error.SetTooLarge`; per line, the lowercase check runs before the order check. `covers_apex` applies only to `.wildcard` lines: `*.x` in a hosts or domains list is a wildcard with no apex entry.

**S3 safesearch + response.** The safe-search table as written above was not sorted; the built table holds the same entry set sorted ascending by `std.mem.order` (`www.youtube-nocookie.com` < `www.youtube.com`; `youtube.com` < `youtube.googleapis.com` < `youtubei.googleapis.com`). `rewrite` uses `catch unreachable` on `name.fromText`, upheld by the every-entry-is-valid test. The mode × qtype × OPT matrix is eight named tests, each looping over OPT presence internally; all sixteen cases are exercised and re-parsed.

**S4 records + forward_zones.** A CNAME is exclusive at a name (RFC 1034 §3.6.2): records sort by (owner, rtype) with rank A, AAAA, CNAME, and a name carrying a CNAME answers with the CNAME run alone. `validate.zig` does not reject a CNAME coexisting with an A, so the mixed case is reachable from a hand-edited database. `qtype == .any` returns the whole record run. The root name is rejected (`BadRecordName` / `BadZone`), as is any byte ≥ 0x80 in an owner, CNAME target or zone. Each table is `items` plus one flat byte block — two surviving allocations, freed by `deinit`.

**S6 fetcher.** `Fetcher.last_status: ?std.http.Status` carries the numeric status past `error.HttpStatus` (see S6.1). `error.WriteFailed` from the output writer maps to `error.Unexpected`; the caller owns the writer and reads the concrete failure there. A `narrowLocal` step folds `transport.mapLocal`'s fd-quota members into `error.SystemResources` and the rest into `error.Unexpected`. A declared `content-length` over `max_body_bytes` returns `error.BodyTooLarge` before the body streams.

**S7 forward_client.** `read_timeout` is `std.Io.Clock.Duration` (S9 constructs it as `.{ .raw = .fromMilliseconds(200), .clock = .awake }`). `Stats` has a fourth field, `foreign_datagrams`. `failures` counts `.peer_fault` and `.local_resource` only — cancellations are shutdown, not failure. The TC bit is read only after `validateResponse` matches the reply. `frame_buf` is split in half between the stream writer and reader; `min_frame_buf = 1024` is asserted in `init`.

**Orchestrator wiring.** All thirteen new files are imported by `src/tests.zig` individually (`wildcard.zig` is unreachable through `parsers.zig` for test collection). The TCP framing helpers (`prefix_len`, `framePrefix`, `parsePrefix`) moved to `upstream/transport.zig` as their single home; `dot_client.zig`, `tcp_server.zig`, `forward_client.zig` and both server integration tests now use the `transport.*` forms, and the canonical framing tests live in `transport.zig`. `zig build test` exits 0 after the move.

**S5 rules + matcher.** `Snapshot.Input` gains `group_ids: []const i64` and `source_ids: []const i64`, parallel to `groups` and `sources` (the model structs carry no row id); length mismatch is an assert. `compiled` is `[]const ?Compiled` — `null` for an enabled source is `error.MissingCompiledSource`; a disabled source needs no entry. On a prefix-length tie the *lower* priority number wins, matching `address.matchLongest` and `pool.zig`. `max_wildcards_per_group` counts both wildcard lists of a group combined, over rows before deduplication. Duplicate rule rows are deduplicated before `DomainSet.build`. Level-6 nesting iterates parents outermost (most specific first), sources innermost. A `group_sources` row naming a disabled source is legal; an unknown URL is `error.UnknownSource`, an unknown group `error.UnknownGroup`. `RuleSet` carries a fifth field, `wildcard_bytes`, backing both pattern lists. The snapshot builds every sub-structure from its own arena, so `Snapshot.deinit` is one `arena.deinit()`. **S8 must fill `group_ids`, `source_ids` and the optional `compiled` entries accordingly.**

**S8 manager + sources_repo.** The compile stage writes plain `<id>.list.tmp` / `<id>.wild.tmp`; `publish` streams header + body into the final files via `createFileAtomic` + `sync` + `replace` at 0o600 — the header carries counts that exist only after the compile, so it cannot go into the same atomic pass. Group row ids come from `groups_repo.groupId(database, name)` (added by the orchestrator; a vanished name is `error.GroupSetChanged`) — the manager does not run raw SQL. A source whose compiled files are missing, unreadable or checksum-mismatched is marked `.load_failed` and excluded from the snapshot; the reload succeeds without it. A present, checksum-clean but malformed body still fails the build and the previous snapshot keeps serving. `updateSourceStats` takes the whole stats struct; the unchanged path re-writes the row and verifies the on-disk bodies hash to the stored checksum before skipping (a corrupt file takes the rewrite path, which repairs it). `SourceStatus.state` is a named `pub const State` with a `no_valid_entries` member: a download that compiles to zero domains and zero wildcards with any nonzero invalid/unsupported/long-line count fails the refresh, leaves the previous files serving, and records `NoValidEntries invalid=N unsupported=N long_lines=N`. A failed refresh seeds its status from the prior entry, so `last_success` and the counts of the still-serving files survive. A second lock, `writer_lock` (plain `std.Io.Mutex`, separate from the RCU lock so readers never wait behind a download), serializes `reload`, `refreshSource`, `refreshAll`, `pruneOrphans` and the startup pass. Format sniffing collects `parsers.sample_lines` countable lines (never a flat byte window). `SourceStatus` is a value type that borrows nothing: `url` is inline `[max_url_len]u8` + `url_len` (`max_url_len = 255`, truncation in the status only; the full url lives on the source row), read via `urlText()`; a copy made under the lock outlives the table it came from. `SourceStatus` also splits the refresh fact from the load fact: `state` records the latest attempt to produce the files, `loaded: bool` records whether they are filtering right now, and a load outcome never overwrites a refresh failure (`State.isRefreshFailure` names the three refresh states) — after `refreshAll`, a source can honestly read `.fetch_failed` with `loaded = true`. Refresh tmp cleanup defers are installed before the calls that create the files, so cancellation and OutOfMemory paths leak no `.tmp`. A reload collects per-source `LoadOutcome`s while it builds the candidate snapshot and applies them to the status table (`applyLoadOutcomes`) inside the same exclusive-lock section as the swap — a reload that fails before publishing leaves both the snapshot and the status table describing the previous generation, and the table and snapshot change atomically for readers. A disabled source is recorded as not loaded; its `state` keeps the record of how it last stood. The reload builds its status table off to the side (`StatusTable`, `buildStatusTable`, `mergeStatuses`) and installs it in the same critical section that swaps the snapshot, so a reload that fails publishes neither. `refreshAll` still syncs the table up front — a refresh pass needs somewhere to record per-source outcomes as it goes. `Manager.Error` adds `Canceled`, `FileSystem`, `GroupSetChanged`. The snapshot seed comes from `io.random` (`std.crypto.random` does not exist in 0.16). The daily interval sleeps on `.clock = .boot`; S7's short timeouts stay on `.awake`. `sources_repo` additions: `SourceRow`, `SourceStats`, `listSourceRows`, `freeSourceRows`, `updateSourceStats` — additive only.

**S9 note from S8:** a loopback `std.http.Server` answering `request.respond(body, .{})` deadlocks a second fetch — the fetcher keeps the connection alive while a one-accept server waits for a new one. Respond with `.{ .keep_alive = false }` or serve a keep-alive loop on the stream.

**S9 integration + fuzz.** Case 3 splits into the two real failure modes: a checksum-mismatched file marks the source `.load_failed` and the reload succeeds without it (generation advances); only a checksum-clean but malformed body fails `reload` and leaves the previous snapshot serving. Case 7 proves the cap from the response head: an explicit `content-length` of 100 MiB returns `error.BodyTooLarge` before any body streams. Case 8 back-dates `last_updated` through `updateSourceStats` and asserts inode and mtime of the compiled file are unchanged. Case 15 asserts `budget/2 <= elapsed < 2*budget` (the POSIX backend wakes ~0.8 ms early on a 200 ms deadline). The fuzz corpus is inline — `tests/fuzz/corpus.zig` imports the `dns` module, which the blocklist-fuzz module does not have. Fuzz targets assert properties, not only absence of crashes: `Line.text` windows the input (pointer containment), `covers_apex` only on `.wildcard`, `detectFormat`'s answer survives `parseLine` over the same bytes, and `matches` is exercised on rejected patterns.

**Final wiring.** `build.zig` gained the `blocklist-fuzz` artifact (module import `parsers` → `src/filter/parsers.zig`, LLVM backend under `-Dfuzz`), hung off `test_step` beside the dns fuzz artifact. Evaluation: `zig build test`, `zig build test -Dintegration` and `zig build cross` all exit 0; both cross executables are statically linked.
