half broken

AGENTS.md

@@ -98,9 +98,16 @@ Break these and you break the design, not just the test.
 - **The Go heap does not account for goroutine stacks, runtime metadata, or the
   bbolt mmap.** `memory.reserve` exists to cover them; the cache snapshot and
   query log are mmapped and live outside the heap entirely.
-- **Unknown config keys are silently ignored** (a known open decision —
-  `yaml` `KnownFields(true)` would reject them). If a config key seems to have no
-  effect, check the spelling against the struct tags before anything else.
+- **Unknown config keys are silently ignored** (a settled decision, pinned by
+  `TestLoadIgnoresUnknownKeys` in `internal/config`: `yaml`
+  `KnownFields(true)` was considered and rejected as a behaviour change for
+  anyone carrying extra keys). If a config key seems to have no effect, check
+  the spelling against the struct tags before anything else. The leniency
+  covers unknown keys only — a known key with a bad *type* is still a startup
+  failure.
+- **`dns.EDNS0_NSID.Nsid` is hex on the wire.** A human-readable value there
+  builds a message that will not pack, so the client gets SERVFAIL. See the
+  test-hygiene traps below.
 
 ## Working rules
 
@@ -144,13 +151,19 @@ partial result described as done is not.
   of the published ones" is a real property and cannot flake.
 - Spin up `dns.Server` fakes on `127.0.0.1:0`: `net.Listen`/`net.ListenPacket` to
   find the port, `ActivateAndServe` in a goroutine, stop in `t.Cleanup`.
-- A `dns.Msg` carrying a character-string over 255 bytes **does not pack** in
-  miekg/dns v1.1.73: `TXT.len()` reports such a string as zero length and
-  `EDNS0_NSID.len()` is likewise wrong, so `Pack` fails with "dns: overflow
-  packing opt". On a fake upstream's write path that failure is silent and
-  presents as a client timeout or a SERVFAIL several layers away. Build a
-  multi-kilobyte answer out of many strings under 255 bytes, and assert the
-  fake's write error before blaming the client.
+- A `dns.Msg` carrying a `TXT` string over 255 bytes **does not pack** in
+  miekg/dns v1.1.73 — the error is `dns: string exceeded 255 bytes in txt`, and
+  255 is the exact boundary. On a fake upstream's write path that failure is
+  silent and presents as a client timeout or a SERVFAIL several layers away.
+  Build a multi-kilobyte answer out of many strings under 255 bytes, and assert
+  the fake's write error before blaming the client.
+- **`dns.EDNS0_NSID.Nsid` is a hex string, not the bytes on the wire.** The
+  library hex-decodes it in `pack` and hex-encodes it in `unpack`, so a plain
+  value such as `"fancy-dns"` fails with `dns: overflow packing opt` and a
+  long NSID packs fine (unlike `TXT`). This bit the engine: an unencoded
+  literal made every query from an NSID-using client SERVFAIL. Always
+  hex-encode on the way in; `TestPinnedEDNS0NSIDIsHex` in
+  `internal/engine/pins_test.go` pins the contract.
 - `internal/app/integration_test.go` already builds a fully wired app. Reuse its
   harness rather than rebuilding one.
 - `tsc -b` replays **cached diagnostics** from `node_modules/.tmp/*.tsbuildinfo`.