For the technical audience

Decisions ADR-1001 to ADR-1050

Every architecture decision record (ADR) behind WrenDNS: what we knew, what we chose, and what it costs. This page is built from the specification on every change, so it's always the current record.

ADR-1001 The infrastructure poller as built: named credentials in files, rows (not varbinds) from the worker, a bind-free socket, and the rules for ARP, ports, VLANs and LLDPAccepted 2026-11-18T25.6 (DSC-004, DSC-014; ADR-908) builds the poller on the merged client (T25.4, T25.5) and the sandboxed workers (ADR-933, ADR-934, ADR-988).

Context

T25.6 (DSC-004, DSC-014; ADR-908) builds the poller on the merged client (T25.4, T25.5) and the sandboxed workers (ADR-933, ADR-934, ADR-988). ADR-908 fixes the pacing, the caps and the table list; building it left several details open, and one fact contradicted the design: the worker's seccomp filter refuses bind, and Agent::new bound its socket, so no SNMP request could leave a hardened worker.

Decision

  1. Configuration. [[discovery.snmp_credential]] (name, role infrastructure or host, version v2c or v3, community_file, user, auth_protocol, auth_password_file, priv_protocol, priv_password_file) and [[discovery.snmp_agent]] (name, address, port 161, credential, interval_secs 60..86,400 default 300, max_repetitions 5..25 default 10, tables default all four). Both lists are part of the shared discovery kind: admin-only, audited, "set by file" when the file sets them. Secrets are files only (T25.8 adds *_ref and SecretField): an inline community or password is an unknown key, so the load fails. A file outside [node] secret_file_dirs is a configuration warning, and a refusal when it is read (creds::read_file confines it), so a node never fails to start over a path. An agent's name is a label and never an IP address (the CLI and the API take a name only, ADR-969); an agent takes an infrastructure credential, a host credential is refused; at most 32 of each. Protocol names and their refusal reasons come from wrendns-snmp (wrendns-config depends on it: a path dependency already linked into the binary, so no new external crate).
  2. Jobs and rows. The main process queues snmp_probe and snmp_poll jobs for the SNMP worker; a job carries the destination (checked by the main process: RFC 1918, not this host's own address) and the credential as hex in the frame, which is overwritten after it is written and after the worker decodes it. The worker answers with rows frames (400 rows each, well inside the 1 MiB frame) and then the result (capability record, one statistic per walk, request and timeout counts); no raw varbind crosses the boundary. The main process takes at most 60,000 rows per job. The supervisor numbers every job itself, gives an SNMP job 150 s (five times the job timeout; the worker ends a poll at 100 s), and drops a queued request whose caller gave up, so a worker that was down doesn't run a backlog. The import worker refuses both ops as unknown without reading the request.
  3. The socket. wrendns_net::worker::connected_udp_socket makes a UDP socket with socket(2) and connect(2) alone (the kernel picks the port and drops datagrams from any other source), and Agent::with_socket takes it. wrendns-snmp stays free of unsafe; the one unsafe block is in wrendns-net's sys.rs with its // SAFETY: comments. dsc_002_worker_privileges_are_dropped now also proves a client socket works after the filter.
  4. Tables. Each table group is split into parts with alternatives (arp: ipNetToPhysicalTable, else ipNetToMediaTable; interfaces: ifTable and ifXTable; addresses: ipAddressTable, else ipAddrTable; forwarding: dot1qTpFdbTable, else dot1dTpFdbTable; ports: dot1dBasePortIfIndex; vlans: dot1qVlanCurrentTable, probed only when the forwarding table is the Q-BRIDGE one; neighbours: lldpRemTable; local_ports: lldpLocPortTable). The probe is one GETNEXT on the first column of each alternative until one answers; the choice is the capability record. A poll walks the columns it needs (not whole tables, which would read ten columns to use two); the 5,000-row and 30 s caps apply to each column walk. At least 50 ms separates every two requests of a poll, between walks too. Three timeouts in a row end the poll, and a poll that does not finish merges nothing (its bindings age out). A table that did not answer is skipped until the next Test; there is no automatic re-probe, only the first poll after a start.
  5. What the rows mean. ARP: only states reachable, stale, delay and probe (and type not invalid) are bindings; IPv6 entries are counted and left out; an entry becomes a class 3 binding (Source::SnmpArp) only inside a listed [[discovery.subnet]] (the same filter as the neighbour table: no subnet, no ARP), and never for an address that names no host or a group MAC. The agent's own addresses join with their interface's MAC and the agent's name. Forwarding: only learned entries, never the agent's own MAC; the VLAN is dot1qVlanFdbId's inverse, and unknown without that table (never the FDB ID); a bridge port names its interface through dot1dBasePortIfIndex and is labelled by ifName, else ifDescr, else "port N". Uplink: a port with more than 8 learned MACs, or whose LLDP neighbour is a listed agent (by chassis MAC of its interfaces, learned from earlier polls, or by name) or a UniFi device (T25.10 fills the MAC set), gives no location; where a port has no dot1dBasePortIfIndex entry its number is taken as its ifIndex to find the neighbour. LLDP: a neighbour whose chassis ID is a MAC address becomes an entry with its sysName and "<agent> <port>"; a neighbour with another chassis ID subtype is counted and left out; at most 4 per port; a new sighting from an agent replaces that agent's earlier place. The local port of a neighbour is found by matching lldpLocPortId or lldpLocPortDesc to an interface name, else taken as an ifIndex. A location (port, vlan, lldp) is the last one reported and ages with the entry (seven days of no sighting); an entry that has a location shows the SNMP source.
  6. Expiry and order. An agent's ARP binding is dropped after twice the slowest agent's interval (at least 15 minutes). Agents are polled one at a time (the worker takes one job), the first polls staggered by 5 s; uplinks that depend on another agent's MACs converge after one round.
  7. Observability. wrendns_discovery_agent_up, _polls_total, _poll_failures_total, _last_success_timestamp_seconds, _poll_duration_seconds, _table_rows and _table_answered; the status API lists each agent; the health reason discovery_agent_failing (degraded, never severe) after three failed polls in a row; a state change is logged once.

Alternatives rejected

a [[discovery.snmp_agent]] that carries its credential inline (ADR-908 wants named credentials with roles, so a LAN device never gets the gateway's); sending varbinds to the main process (the parser would run in the process that must not crash, and the frames would be larger); allowing bind in the worker's filter (it exists so a worker can't share the DNS port); walking whole tables (five times the rows for the ARP table); assuming the FDB ID is the VLAN ID (it is not on some vendors' switches); a UniFi-specific uplink test now (T25.10 owns the UniFi device list).

Consequences

the first poll after a start probes every table, so an agent that gains a table needs a Test; an uplink that depends on a listed agent's MACs is placed correctly from the second round; a mixed-version cluster can't read a [discovery] that carries agents on an older node (deny_unknown_fields), which the first-write gate (ADR-928) does not yet know: upgrade every node first. The image delta is not measured here (no external dependency was added; the image job measures it).

Test plan

dsc_004_arp_physical_then_media_fallback, dsc_004_bridge_ports_per_vlan, dsc_004_uplink_ports_give_no_location, dsc_004_lldp_neighbors, dsc_004_capabilities_probed_not_assumed, dsc_004_pacing_limits, dsc_004_parsers_survive_hostile_rows, the config rules (dsc_004_credential_rules, dsc_004_agent_address_and_name_rules), the worker end to end against a fake agent (dsc_004_worker_polls_a_gateway_shaped_agent, dsc_007_credentials_travel_over_stdin_only, dsc_007_import_worker_gets_no_credentials), and the real worker against net-snmp in a throwaway container.

Requirements DSC-004 DSC-014

Builds on ADR-908 ADR-928 ADR-933 ADR-934 ADR-969 ADR-988

Referenced by ADR-1002

ADR-1002 POST /api/v1/discovery/snmp/test: a name only, a dry run, a minute between tests, run where the poller runsAccepted 2026-11-18AGTT25.6 asks for Test: admin, ops:discovery_test for agents, body {agent} only, dryRun lists the OIDs, Idempotency-Key, a 60 s cooldown, audited as discovery.snmp_test.

Context

T25.6 asks for Test: admin, ops:discovery_test for agents, body {agent} only, dryRun lists the OIDs, Idempotency-Key, a 60 s cooldown, audited as discovery.snmp_test. It leaves the answer, the cooldown's home and the cluster behaviour open.

Decision

  1. The body is {"agent": "<name>"} and nothing else (deny_unknown_fields); a value that parses as an IP or socket address is a 400 before anything else, so the endpoint can't be a destination chosen at request time (ADR-907, ADR-908). ?dryRun=true (the query, like the other dry runs) answers with the OIDs a test would query (each part's alternatives with the probe root and the columns a poll walks, and sysObjectID), sends no packet, starts no cooldown and isn't audited.
  2. A real test queues an snmp_probe ahead of the polls, waits for the worker (90 s at most) and answers 200 with the capability record (security level, v3 engine ID, sysObjectID, and for each part the MIB table that answered or none). A test that fails to reach the agent is a 200 with ok: false and the reason (no packet detail, no address, no secret); the earlier capability record stays. A worker that isn't running is 503.
  3. The cooldown is 60 s per agent, kept on the designated node in memory, started when a test starts (a failed test counts) and kept across a reconfigure for an agent that is still there; inside it the answer is 429 with Retry-After. A dry run never waits.
  4. The scope ops:discovery_test is an operator-style scope that implies the admin role (like cluster:admin): a token can't hold it unless its owner is an admin, and the route needs admin. Agents give a reason (AGT-005). Audit: discovery.snmp_test, target the agent's name, detail ok, level, error, node.
  5. It runs on the designated node. A replica with no [discovery] node forwards to the primary (Write::SnmpTest, audited there as "<user> via <entry node>"); a node that isn't designated, or has the inventory off, answers 409 discovery_not_here naming the designated node. The MCP tool test_snmp_agent is T25.13's.

Alternatives rejected

an address in the body (a destination chosen at request time); a cooldown in the shared database (a test is rare and the designated node is one place; a failover resets it, which only allows one extra test); an operator role (the endpoint sends packets to a device, like the router checks, which are admin-only); a long-running 202 with polling (a probe takes seconds, and the page waits for it).

Consequences

the capability record shown on the page is the one the poller uses; pressing Test is the only way to learn a table that came back (ADR-1001 item 4); a Test during a long poll waits for that poll to end (at most 150 s, the handler gives up at 90 s with the reason).

Test plan

dsc_004_snmp_test_over_http (roles, scope, reason, name only, dry run, replay, audit, 404, 429), dsc_004_snmp_test_dry_run_and_cooldown (the runtime with a worker stand-in), dsc_004_snmp_test_round_trips (the cluster channel), the Playwright dsc_004 add an agent and test it and dsc_004 operator sees agents read-only.

Amendment (review fixes of T25.6, still Proposed): (1) A test or poll that gets a USM Report, a decode error or no engine back (a wrong v3 credential, an unknown user) is a failure of the whole probe, not a table that doesn't answer: ok: false, and the old capability record is kept. (2) A Test forwarded from a replica waits 105 s (10 s to reach the primary, 90 s for the worker, 5 s to answer), not 10 s. (3) The cooldown starts only after the worker check, so a 503 doesn't cost the agent its minute. (4) A walk keeps at most 4 MiB, a poll 16 MiB (stop byte_cap), and an octet string is cut to 255 bytes as it arrives (ADR-908, bounded memory). (5) No two datagrams to one agent leave less than 50 ms apart, engine discovery and time-window resends included (paced inside Agent). (6) An SNMP credential's *_file fields follow the credential path rules when set through the API (in secret_file_dirs, not another credential's file); they are checked in plan_settings for the discovery kind, not through API_PATHS, which lists the entry kinds. (7) wrendns snmp walk stays in-process (it is run by the owner at a terminal and sends the same read-only PDUs, bound to the same caps); moving it into wrendns discovery-worker is not done and is not planned: a CLI the owner runs holds the credential file itself.

Requirements AGT-005

Builds on ADR-1001 ADR-907 ADR-908

ADR-1003 The extra UniFi and Home Assistant reads: their settings, what the poll shares, and what history isAccepted 2026-11-18ADR-912 (Accepted) fixes what T25.10 reads and where it runs.

Context

ADR-912 (Accepted) fixes what T25.10 reads and where it runs. It leaves the shape of the settings, the hand-over between the router poll and the inventory thread, the treatment of history, and how far Home Assistant's templates reach to the implementation. The task also closes the Open item of T25.1: nothing fed sources::ha_observations.

Decision

  1. Settings. [discovery.unifi_reads] is a table of three booleans (client_fields, all_users, devices), each off by default. unifi_all_users_within_hours is 1 to 8,760, default 720. home_assistant_all_devices is a boolean, default true (it applies only while discovery is on). The three keys are always serialized and are fields of the discovery settings kind (admin-only, no agent, set-by-file per key). They ship in the release that introduces [discovery], so no new members gate (DISCOVERY_SINCE) is added.
  2. What the poll shares. routers.rs stores, per UniFi router it read, the session it used (base URL, site, the key or cookie, in Zeroizing memory, Debug redacted) and, only while client_fields is on, the raw stat/sta and rest/user answers (moved, not copied). For Home Assistant it stores the token and the devices and trackers it read. This happens only while the inventory runs on this node (Keep), through Board::share(). Every extra request and every parse runs on the wrendns-inventory thread's runtime as tasks of that runtime; routers.rs names none of the extra paths (dsc_009_reads_off_main_runtime). A router whose credential is a stored secret is read on the primary only (ADR-903), so the extra reads need the designated node to be the primary or the credential to be a file.
  3. Pace. The extra reads for a router start after each of its polls and at least 120 s apart; a read that is still running is never started twice. A read that a console refuses (HTTP 401 or 403) or that fails is reported once per change (log line, and DiscoveryStatus.reads, shown on the Network inventory page); the other reads of that router carry on.
  4. History. stat/alluser rows are source history (class 5): the address is last_ip, last_seen is the time, a row outside the window is dropped, and the name has its own kind (history, rank 8, below an import's) so a history name never claims a router's source bit. A history row never raises new_device (UniFi remembering a client is not a new device). History ages out when its window passes since last_seen, with its names; with all_users off it is dropped at once, because nothing refreshes it.
  5. Places. A switch port's mac_table gives a client its place (<switch name> port <n>, and the VLAN) unless the port is an uplink or holds more than 8 MACs; static rows are not evidence; a MAC on two ports takes the port with the smaller table; the observation's time is now - age. client_fields gives a wired client its port from sw_mac and sw_port, a wireless one its access point from ap_mac (named from the devices read when it ran, otherwise the MAC), the VLAN, the network name and the first time seen (rest/user knows it too). Neither carries an address.
  6. Home Assistant. The poll's own devices and trackers now feed ha_observations (once per poll; the addresses are claims, ADR-923, and age out after three polls). The second template lists devices that have a MAC and no entity, found through areas() and labels() because Home Assistant's templates cannot list the registry. A device in no area and with no label is therefore not listed. This limit is checked against a real Home Assistant (deploy/ha-test). Reading the registry through the websocket API would remove it and is left Open (a second protocol and a second credential use).

Alternatives rejected

reading the three UniFi endpoints inside routers.rs (ADR-912); a second login for the inventory thread (a second session on a console that limits them, and the credential read twice); serializing the new keys only when set (the settings kinds fill a missing key with null, which a boolean refuses); keeping the raw answers always (up to 16 MiB held per router for a feature that is off); a history row that creates new_device (every old phone would alert on the first read).

Consequences

the router poll holds a session for the inventory while discovery runs; the raw client answers are held only with client_fields. The Network inventory page gains the three switches, the window, Home Assistant's switch and the reads table; DiscoveryStatus gains reads.

Test plan

dsc_009_alluser_history_never_current, dsc_009_device_mac_table_locations, dsc_009_refused_read_reported_once, dsc_009_never_in_router_leases_or_device_dns, dsc_009_ha_entityless_inventory_only, dsc_009_reads_off_main_runtime, and the others in discovery/reads_tests.rs; deploy/routers-e2e.sh (fake consoles, a refusing one); deploy/ha-test/e2e.sh step 8 (a real Home Assistant); the Playwright tests dsc_009 unifi read toggles and dsc_009 refused read shows on the inventory page.

Builds on ADR-903 ADR-912 ADR-923

ADR-1004 The CMDB's model: configuration items from source records, reconciled by ordered rules, with a definitive source per attribute and a MACD lifecycleAccepted 2026-11-19, owner request; revised 2026-11-18 after review for ADR-998AGTCLUthe owner asked (2026-11-18, fork #21) for a CMDB: one configuration item per real thing on the network, built from every source that reports on it, with the owner declaring which source is definitive for each attribute and with changes going through move, add, change, delete (MACD).

Notes

Owner amendment (2026-11-19, AskUserQuestion), display and default: the CMDB is the source of the names and details the product SHOWS about a device: the map and its drawers, Clients, the query log, Explain, the Policy panel and the agent read tools show the CI's reconciled name and attributes, each with its deciding source on hover. DNS answers, device DNS names, client matching, identify, filtering and group membership still never read a CMDB value (question 6 stands; DSC-901's containment test keeps covering them). [cmdb] enabled becomes on by default (still a validation error at privacy level 2 and above, and never on a resolver pod); while the CMDB is not running yet, is still learning, or its designated node is away, the UI falls back to today's name sources with a visible note, never a blank. On by default must fit the hard idle RSS gate (spec/00 §5): T31.2's measured cost at the caps decides whether the default caps need lowering for small nodes.

Owner decisions (2026-11-19, asked one by one through AskUserQuestion): the design's recommendation was taken for questions 1 to 13, 15 and 16 (all six CI types with node, service and upstream read-only; manual first, then ADR-910's order; wired port, VLAN and network moves only, delete after 14 days with at least 3 days seen; operators approve detected changes and unprotected plans, admins the rest, agents never, one approver; done only records; a manual CMDB name never names a device in DNS; like discovery for privacy; MACD 365 days (cap 10,000) and value history 90 days (cap 20,000); authored data replicates and a backup carries it only with a passphrase; fall back with a badge when the definitive source is silent, hold per rule; the unconfirmed alert after 24 h; hostname plus network proposes only; the [[group_link]] keeps its direction and the CMDB mirrors it read-only; Kubernetes CIs only when the feature is on; the CMDB runs on the node [discovery] designates). Question 14 departs from the recommendation: the Pi-hole importer is not a CMDB source (no pihole_import source kind; imported Pi-hole clients reach the CMDB only through the configuration they become, as the config source).

Context

the owner asked (2026-11-18, fork #21) for a CMDB: one configuration item per real thing on the network, built from every source that reports on it, with the owner declaring which source is definitive for each attribute and with changes going through move, add, change, delete (MACD). M25's inventory (ADR-910) is keyed by MAC and keeps one merged entry per MAC; it drops what each source said and cannot say which source is right. ADR-994 makes a filter profile a group. T24.30 resolves a device's effective policy. T25.18 (UniFi sync, ADR-998 and ADR-999, Proposed) gives each linked group a direction. Full design: docs/design/cmdb.md.

Decision

  1. Scope and containment. The CMDB is read-only towards devices and gateways (no SNMP SET, no write to UniFi, OPNsense or Home Assistant, no probe: ADR-907). Its data never reaches DNS answers, client matching, Neighbors, identify, filtering, or device names in DNS (ADR-910's containment extended; DSC-012's address opt-in stays inventory-only). A MACD marked done changes nothing outside the CMDB. It runs on its own thread, off the query path, with failures contained (CLU-004). Gateway writes need their own ADR.
  2. CI types (closed set, new ones need an ADR): device, interface, network, node, service, upstream. A MAC identifies an interface (interface.mac is its key; a new MAC is a new interface CI), not a device: every MAC-keyed record makes a nic interface CI inside a device CI, one MAC one device until a serial, a stable device key or a person says otherwise. A switch or AP port is an interface CI of kind port, keyed by (device CI, normalised port id) with a per-source normaliser and an alias table, never by MAC (docs/design/cmdb.md, Port identity); an unaliased port is its own CI marked unmapped_port, not a conflict. Relations are typed edges with their own source and times: has_interface, on_network, attached_to (a nic to a port), member_of (a policy group; a set whose sources are config and unifi:<router>; read, never written), runs_on, uses_upstream. A CI id is a random 128-bit ci_<id>, never reused and never derived from a MAC; a merge leaves the losing id as an alias that redirects for 90 days. The registry row also holds first_seen, a CI-level last_seen and days_seen (ADR-1005 §3).
  3. Source records keep what a source said, as it said it: source (kind and instance, such as unifi:<router>, snmp:<agent>, import:<id>, neighbor, lease, mdns, pihole_import, queries, k8s, config, cluster, manual), source_key, ci_type, up to 24 attributes (values cut to 255 B, control characters stripped, DSC-015), first_seen, last_seen, last_changed, state (present, or absent after two missed complete batches as in ADR-924) and the link (auto:<rule>, manual, none). A record is never edited; a source's next batch replaces it.
  4. Reconciliation is an ordered rule list run on each ingested batch, resolved separately for the interface level and the device level: the first rule at a level that finds exactly one CI links, two or more is left unlinked and raised as a proposal (never a guess). Interface level: R1 manual link or unlink (a pin; an unlink writes a never-match pin), R2 MAC (M25's merge, same normalisation code; a randomised MAC matches and never raises add). Device level: R1, R3 serial, R4 the source's own stable device key that survives a MAC change (a Home Assistant device id, an SNMP chassis id, a UniFi infrastructure device id), then the has_interface of the interface found, and R5 hostname plus network, which only proposes a merge (a MACD change) and is never applied alone. R4 links at device level and creates a new interface CI for a new MAC; it never moves an interface to another MAC. A UniFi client _id is not a key (UniFi keys a client by MAC). When the two levels disagree (the MAC's interface belongs to device A, the serial or stable key finds device B) nothing is linked at device level and a merge proposal is raised (dsc_903_level_disagreement_proposes_merge). A keyless record attaches through a class 1–3 address binding (ADR-923) or becomes an unconfirmed CI. M25's ADR-910 classes, name ranks, freshness and retention become the built-in default precedence and freshness of the matching attributes, so the CMDB is the general form of ADR-910's fixed orders.
  5. Attributes come from a code-defined catalog (type, single or set cardinality, reporting sources, whether manual is allowed, default precedence, whether a change is detected, whether history is kept). Sets (addresses, member_of) never conflict and a set has no definitive source. manual is a source and is first by default wherever allowed.
  6. Definitive source. The merged value is the first fresh source's value. Resolution order: (1) a per-CI attribute pin (a source or a manual value), (2) a per-CI override list, (3) a scoped rule (type, attribute, scope = group:<id> | network:<id>), (4) the owner's type-and-attribute rule ([[cmdb.precedence]], a managed admin-only settings kind), (5) the built-in default. T25.18's link direction is not a precedence rule and the CMDB never drives it (this amends ADR-998 §14, which the T25.18 owner adopts): the [[group_link]] keeps unifi_definitive, wrendns_definitive or two_way (a three-way set merge with no definitive side), and the CMDB shows it as a read-only, mirrored line (two_way shown as merge), never authoritative, with no control. member_of is a set with two sources, so a precedence rule would mean nothing for it, and letting CMDB precedence steer a write to the gateway would let CMDB data reach filtering, against DSC-901. The sync runs on the primary (ADR-998 §13) and the CMDB on the designated node (ADR-1005 §1); they can differ when a node is named, so the CMDB reads the links from shared configuration and the router adapter, never from the sync's state.db. Silence: a source is stale after two poll intervals (ADR-924 values; imports 30 days; config, cluster, manual never). Default silent = "next": the value falls to the next fresh source with a visible fallback badge, the definitive source's last value and its age; with no fresh next source the last value is held, marked stale (as silent = "hold" does for hold_days (7), then falls back). A source instance silent over 24 h raises one source_silent finding, not a MACD. Conflict: a single attribute where a fresh non-definitive source differs after normalisation; resolved by Accept (pin that source), Keep (mute, optional expiry) or a MACD change. Mutes are capped at 1,024 (oldest first) and pins plus override entries at 64 per CI.
  7. MACD. A change record with kind (move, add, change, delete), CI, attribute, from and to, origin (detected:<source>, user:<name>, agent:<token> (owner: <user>)), observed, reason, approver and a closure reason. States: requested, approved, done, rejected. An observed (detected) change is born requested and approving it goes straight to done; rejecting it flags the change unexpected on the CI. A planned change goes requested, approved, then done when a source reports the expected end state or an operator closes it, or rejected with reason expired after plan_expiry_days (30). A detected change that reverts first closes rejected with reason reverted (shown as Withdrawn). Closure reasons: rejected, expired, reverted, superseded. Baseline: the detector keeps an acknowledged value per CI, attribute and source, advanced on approve and on reject, and compares only a source's own value with it, so a rejected change does not re-raise every settle period; the flag is cleared by an operator's Clear flag action (audited).
  8. Detection runs per source record, never on the merged value: only a change of the same source's own value raises a record, and a switch of the deciding source (the definitive source going silent or returning) raises nothing and writes no history row. After a 24 h learning period and after any empty start (ADR-910); debounced by detect_settle_secs (600) and two batches; one open record per CI and attribute: add (a new non-randomised device from a class 1–3 source; imports, mDNS-only and queries-only records become unconfirmed CIs, never an add), move (a wired port, VLAN or network change; never AP roaming or an address change), change (serial, model or role of an infrastructure device; a network's CIDR; a merge proposal), delete (a registry row with a class 1–3 presence source, days_seen of at least 3 and a CI-level last_seen older than disappear_after_days (14); the registry, not the 7-day derived records, holds these). At most 200 open detected records; past that they are counted, not stored.
  9. Approval. Viewers none. Operators approve detected changes and planned changes on CIs not marked protected. Admins approve all and manage protected and the precedence rules; setting protected or editing a protected attribute's manual value is admin-only (403 for an operator). Agents never approve; the scope ops:cmdb lets one create a requested record, which is its plan, at most 50 open agent-made records per token and 10 creations an hour per token (429 past that). [cmdb] require_second_approver (default false) forbids approving your own request. A record unconfirmed for unconfirmed_alert_hours (24) raises one event through the existing sinks (ADR-984) with source = "cmdb", under ADR-102 (off at privacy level 1 and above like the new-device alert).
  10. History. Every MACD transition is a row and a cmdb.macd.* audit entry (AGT-005 attribution). Each CI keeps merged-value history only for the catalog rows that allow it (single-valued, non-derived; never sets, derived values, ap, addresses or last_seen), one row per change of a source's value.

Alternatives rejected

growing the inventory entry with more fields (it keeps no per-source record, so no conflict view and no definitive source); one flat precedence order for all attributes (a UniFi name and an SNMP serial need different orders); automatic hostname matching (two phones called iphone on one VLAN would merge); MACD as full ticketing (assignment, SLA: not wanted); five or six states (closure reasons carry the difference); letting a MACD apply a gateway change (read-only rule, ADR-907); keying a CI on its MAC (randomised MACs and multi-interface devices break it).

Consequences

a MAC now yields two CIs (interface and device), which the UI hides behind one row by default. The inventory and the CMDB duplicate some state until the inventory becomes a view (Open, not planned). New requirements DSC-901 to DSC-905; new scopes in ADR-1005. The T25.18 owner amends ADR-998 §14 so that the CMDB displays the link and never drives it (owner question 13). Task: T31.1 to T31.6.

Test plan

dsc_901_* to dsc_905_* as in docs/design/cmdb.md (rules, precedence order, silence, conflicts, state machine, detection debounce, approval rights, containment), plus a property test that the same batches in any order give the same links.

Requirements AGT-005 CLU-004 DSC-012 DSC-015 DSC-901 DSC-905

Builds on ADR-1005 ADR-102 ADR-907 ADR-910 ADR-923 ADR-924 ADR-984 ADR-994 ADR-998 ADR-999

Referenced by ADR-1005 ADR-1022

ADR-1005 The CMDB's storage, API, MCP tools, federation and retentionAccepted 2026-11-19, owner request; revised 2026-11-18 after reviewAGTADR-1004 fixes the model.

Notes

Owner decisions (2026-11-19, see ADR-1004, asked one by one through AskUserQuestion): the design's recommendation was taken for questions 1 to 13, 15 and 16 (all six CI types with node, service and upstream read-only; manual first, then ADR-910's order; wired port, VLAN and network moves only, delete after 14 days with at least 3 days seen; operators approve detected changes and unprotected plans, admins the rest, agents never, one approver; done only records; a manual CMDB name never names a device in DNS; like discovery for privacy; MACD 365 days (cap 10,000) and value history 90 days (cap 20,000); authored data replicates and a backup carries it only with a passphrase; fall back with a badge when the definitive source is silent, hold per rule; the unconfirmed alert after 24 h; hostname plus network proposes only; the [[group_link]] keeps its direction and the CMDB mirrors it read-only; Kubernetes CIs only when the feature is on; the CMDB runs on the node [discovery] designates). Question 14 departs from the recommendation: the Pi-hole importer is not a CMDB source (no pihole_import source kind; imported Pi-hole clients reach the CMDB only through the configuration they become, as the config source).

Context

ADR-1004 fixes the model. A CI registry row alone is not authored: it is rebuilt by the sources, and only the manual data on it is (§3, §5), though the registry (with days_seen and last_seen) is replicated so a new node has it. Two kinds of data differ in a way ADR-910 did not have to face. Derived data (source records, links the rules made) can be rebuilt from the sources, so it can live on one node and stay out of backups, like the inventory. Authored data (manual values, manual links and unlinks, pins and overrides, MACD records, value history, mutes) cannot be rebuilt and must survive a failover and a restore. The inventory is memory-resident and capped at 4,096 entries; a CMDB with several records per CI is larger and the RSS budgets are hard.

Decision

  1. Where it runs. On the node [discovery] designates (ADR-930's gate: named node, else the primary or standalone node, never an ephemeral pod or a witness), even when [discovery] is off, so the inventory is in process. [cmdb] is a managed settings kind, admin-only, no agent scope (as ADR-928): enabled (false), disappear_after_days (14), detect_settle_secs (600), unconfirmed_alert_hours (24), plan_expiry_days (30), history_days (90), macd_retention_days (365), require_second_approver (false), and up to 256 [[cmdb.precedence]] rules (type, attribute, optional scope, sources, silent, hold_days). Each has a UI control, a help topic and a Playwright test. A failover happens only when no node is named: with a named node down nothing runs (ADR-930), there is no failover, CMDB writes answer 503 with a hint until an admin clears or changes the name, and DNS is unaffected. The T25.18 sync runs on the primary (ADR-998 §13); the two can be different nodes.
  2. Storage. A SQLite database <data_dir>/cmdb.db (WAL, 0600) through wrendns-store, on its own thread; never the telemetry database (ADR-006). Only a compact index is in memory: id, type, display name and keys per CI, about 100 B each; records and history are read from the database for a page. Target: at most 8 MiB extra RSS and 64 MiB on disk at the caps; T31.2 measures it and the acceptance criterion binds. A query on the DNS path never touches it.
  3. Caps. 16,384 CIs of all types (ports included); 8 source records per CI and 65,536 in total (oldest absent first); 24 attributes per record; 32 manual attributes per CI; 20,000 history rows; 10,000 MACD records (open ones are never dropped, the oldest closed ones go first); 256 precedence rules; 1,024 conflict mutes (oldest first); 64 pins and override entries per CI; 50 open agent-made requests per token. CI cap overflow: a CI is authored only with a manual value, link, unlink, pin or override, or an open MACD record; registry rows alone are not. At the cap the oldest unconfirmed or derived-only CIs are evicted first; when everything left is authored a new CI is refused and counted (wrendns_cmdb_dropped_total{kind="ci"}), and the status says so. Registry rows carry first_seen, a CI-level last_seen and days_seen (distinct days, capped at 32). History and writes: history rows are written only for catalog rows that allow history and only when a source's value changes; a record is written only when its content hash changes, and last_seen is kept in memory and flushed in one batch every 15 minutes for rows whose stored value is over 6 hours old. Ingestion goes through a bounded channel that drops the oldest batch when full and counts it (wrendns_cmdb_dropped_total{kind="batch"}).
  4. Ingestion. Each source adapter pushes a SourceBatch { source, complete, records } to a sink beside the inventory feed: M22 routers (UniFi, OPNsense, Home Assistant), M25 (neighbour table, SNMP, imports), leases, mDNS, queries (read from the aggregator's snapshot once a minute, never from the hot path, off at privacy level 2 and above), the Pi-hole importer (a one-shot pihole_import), Kubernetes when on, and config and cluster (nodes, networks, upstreams, services, read from the live configuration). No new network I/O is added to any poller.
  5. Retention. Source records follow ADR-924 (a record absent for two complete batches leaves present; derived-only data ages out after [discovery] retention_days, imports after [discovery.import] retention_days), but the CI's registry last_seen and days_seen outlive them so delete detection works. An unlinked unconfirmed CI with no present record and no authored data is removed after 30 days, and is the first evicted at the cap (§3). History 90 days, MACD 365 days. A CI with authored data is never removed automatically.
  6. Replication. Authored data is written only on the designated node (the single writer; other nodes forward writes there and answer 503 with a hint when it is unreachable, never affecting DNS). It is replicated to full members as a hot standby with row stamps (epoch, seq) and tombstones, using the mechanism of ADR-903 and ADR-917 outside configuration versions, and applied only if the member becomes designated. Derived data is node-local and rebuilt after a failover; after an empty start the 24 h learning period applies and no add or delete MACD is raised. T31.2's first step is a spike confirming that the secrets replication code takes a non-secret writer; if it does not, the fallback is an authored-data snapshot in the cluster channel, recorded as an amendment.
  7. Backups and support packages. Authored data (the registry with MACs and names, manual values, links, MACD, history) is identifying, and this reverses DSC-008's rule that inventory data stays out of backups, for this data only. A backup includes it only when it is encrypted with a passphrase; an unencrypted backup omits it, and requesting it without a passphrase is a validation error. Derived data and source records are never in backups, and are out of support packages unless --include-inventory, which pseudonymises (ADR-156, ADR-910).
  8. API (OpenAPI with dry run, Idempotency-Key and reason, AGT-001..006; a UI control for each): GET /api/v1/cmdb/cis (filters type, q, source, conflict, unconfirmed; cursor pages of at most 500 and 256 KiB), GET /api/v1/cmdb/cis/{id} (merged attributes with deciding source, source records side by side, relations, history), GET /api/v1/cmdb/conflicts, GET /api/v1/cmdb/macd and /{id}, GET /api/v1/cmdb/precedence, GET /api/v1/cmdb/status; writes POST /cis/{id}/link, /unlink, /merge, /split, PUT /cis/{id}/attributes/{name} (manual value or pin), POST /macd (request), POST /macd/{id}/approve|reject|close, POST /cis/{id}/attributes/{name}/clear-flag, PUT /cis/{id}/ports/{port}/alias, PUT /api/v1/cmdb/precedence (admin). The CI detail carries policy only as a link to GET /api/v1/clients/{id}/policy (T24.30); the CMDB resolves no policy.
  9. Scopes and roles. cmdb:read (Viewer role), ops:cmdb (Operator role; for agents it allows creating a requested record, capped per token (§3, ADR-1004 §9), and plan-only link, unlink and value requests). Neither is in DEFAULT_SCOPES, and neither is granted by a wildcard or config:write:* (as DSC-013). Precedence and protected are admin only and have no agent scope. Every mutation needs a reason from an agent and is audited as cmdb.*. Applying a CMDB plan is human-only (ADR-903 §5): apply_plan refuses a CMDB plan presented with an agent token.
  10. MCP (names follow spec/13's list_*, get_* and plan_* convention and are added to the spec/13 catalog). Read tools: search_cmdb_cis, get_cmdb_ci, list_cmdb_conflicts, list_cmdb_macd, get_cmdb_macd, get_cmdb_status. Writes are plan-only: plan_cmdb_link, plan_cmdb_unlink, plan_cmdb_value return the diff and a plan id that a human applies (AGT-002; apply_plan refuses them from an agent token), and the immediate op request_cmdb_macd (ops:cmdb) creates one requested record (the request is the plan), capped at 50 open and 10 an hour per token. No tool approves, merges, splits, clears a flag or edits precedence. Device-supplied strings are marked as untrusted data in tool descriptions (DSC-015).
  11. Federation. Read::Cmdb, federated like Read::Discovery with AGT-011 missingNodes: a node that is not designated asks the designated node for a filtered page (500 rows, 256 KiB, trimmed by the server); an N−1 node answers "unknown call". The designated node's answer is authoritative; replicas do not answer from their standby copy.
  12. Privacy (ADR-102). At level 1, names are hashed as the inventory's are, and the unconfirmed-change alert is off; at level 2 and above [cmdb] enabled = true is a validation error and queries is not read. Whether to amend ADR-102 instead is an owner question.
  13. Observability. wrendns_cmdb_cis{type}, wrendns_cmdb_records{source}, wrendns_cmdb_conflicts, wrendns_cmdb_macd_open{state}, wrendns_cmdb_dropped_total, wrendns_cmdb_batch_seconds; a status API (last batch per source, the sink's queue depth, the learning-period end); health reasons that never mark DNS unhealthy; log once on change.

Alternatives rejected

keeping everything in inventory.json (memory-resident, 0600 JSON written every 15 minutes: unsuitable for hand-entered data that must not be lost, and 65,536 records break the RSS budget); everything node-local (a failover loses every manual link and MACD); replicating source records (spreads identifying data and doubles the traffic for data a poll rebuilds); storing authored data as configuration (thousands of rows per configuration version and a diff for each hand edit); extending Names (ADR-910's frame limit); letting a replica answer reads (two nodes could differ).

Consequences

a new database file and migration set; a new federated read call (N−1 safe); new scopes, OpenAPI and MCP snapshot changes; backups grow by the authored data. The failover loses derived data for one poll cycle. docs/design/cmdb.md and the help topics describe the settings.

Test plan

dsc_906_* (caps; retention; replication, failover and the learning period; backups hold authored data only; privacy levels), dsc_907_* (OpenAPI examples, scopes not in wildcards, plan-only agent writes, an agent cannot approve, missingNodes, N−1 unknown call, 503 when the designated node is away while DNS keeps answering; with a named designated node down no failover happens and writes stay 503), a memory test against the 8 MiB target at the caps, a write-volume test (T31.2 AC 5), a CI-cap eviction and refusal test, and deploy/cluster3/e2e.sh (T31.6).

Requirements AGT-001 AGT-002 AGT-011 DSC-008 DSC-013 DSC-015

Builds on ADR-006 ADR-1004 ADR-102 ADR-156 ADR-903 ADR-910 ADR-917 ADR-924 ADR-928 ADR-930 ADR-998

Referenced by ADR-1004 ADR-1021 ADR-1024

ADR-1006 Per-node sections and small shared singletons for the cache and the small settingsAccepted 2026-11-18T27.2 (the cache) and T27.11 (the small settings) expose settings that have no UI editing path today.

Context

T27.2 (the cache) and T27.11 (the small settings) expose settings that have no UI editing path today. Three are node-local ([cache], [support], [updates]): each node has its own value, so the value has to be named by the node it applies to and replicate in the node-managed blob (ADR-903 §6, ADR-967). Three are shared singletons ([dnssec], [filter], [drill]) that the settings-kinds framework (T24.12, T25.2) already handles.

Decision

  1. cache, support and updates are node-managed kinds, named by the node they apply to (the name the guarded module uses, node_label). A node applies only its own row. The rows travel in the manifest's node_managed blob (references only; these kinds carry no secret), and an older node ignores them.
  2. dnssec, filter and drill are shared singletons (one entry, default). The files win field by field; explicit_keys records the six sections so a field a file sets is read-only in the UI (ADR-040).
  3. Roles: the cache is an operator's setting (T27.2 says operator-editable); support and update switches are admins' (T27.11); the drill schedule is admins' (it starts failover drills on the cluster's nodes); the DNSSEC mode, its trust anchors and the list refresh settings are operators'. No agent changes any of them; a write from a node too old to say who asked is refused (409 upgrade_required).
  4. Restart: [cache], [support], [updates] and [filter] are read once, when the node starts (restart_only_changes; [updates] joins that list here, since its daily loop starts with the value it had). The status view, GET /api/v1/node-settings[/{node}], reports pendingRestart against a start-time snapshot. [dnssec] applies on reload; [drill] is read at each check.

Alternatives rejected

keeping cache in the singleton framework (one entry per kind; the node would have to be in the key anyway); making the cache admin-only (T27.2 says operators); a restart-window (guarded, ADR-956) flow for the cache (it is not a bootstrap or security setting, so ADR-914's tier doesn't apply).

Consequences

a node's row stays in the store after the node leaves the cluster, until it is deleted, and applies to nothing. The routes add 8 documented paths (166 in all). Every change to a per-node section reads "pending restart" until the node restarts.

Test plan

dns_006_cache_settings_node_managed, dns_006_file_wins_over_the_cache_settings, dns_006_pending_restart_until_the_node_starts_again, dns_006_blob_applies_only_this_nodes_row, ops_011_ops_012_support_and_updates_per_node, clu_014_drill_schedule_admin_only, dns_011_dnssec_mode_and_trust_anchors, flt_004_filter_refresh_and_stale_settings (wrendns), the path count in api_001, and the Playwright files 8-settings.spec.ts (T27.2 tests) and the T27.11 tests in the same file.

Decisions for the owner

the drill schedule's tier (admins here, the conservative choice; the task text is silent); the operator tier for the DNSSEC mode and the list refresh settings; whether a departed node's rows should be swept at the next primary start.

Builds on ADR-040 ADR-903 ADR-914 ADR-956 ADR-967

Referenced by ADR-1017

ADR-1007 Zones and route limits made in the UI; tuning settings as shared and node-managed singletonsAccepted 2026-11-18APIDNSOBST27.7 (DNS-010, API-901) and T27.5 (OBS-020, OBS-013, OBS-003, OBS-016 and OBS-019 settings, API-901; ADR-914) give the UI controls the fork still lacks.

Context

T27.7 (DNS-010, API-901) and T27.5 (OBS-020, OBS-013, OBS-003, OBS-016 and OBS-019 settings, API-901; ADR-914) give the UI controls the fork still lacks. The routes form has no way to limit a route to client groups or query types, to keep it on one node, or to set its DNSSEC trust anchor. Zones are read-only on the local DNS page. Records have no TTL or node-only control in the UI. The tuning sections ([slo], [probe], [upstream_check], [telemetry.anomaly], [telemetry.qlog], [telemetry.metrics]) have no control at all. The task text leaves open how each sits beside the file, which role may write it, and whether a change applies without a restart. This ADR records the choices made while building T27.7 (the first half of the track).

Decision (T27.7):

  1. Zones are a managed kind zone (/api/v1/zones/{name}), operators write it. The body is a [[zone]] without its file: an API zone that names one is refused (422, the file is T27.17's guarded path). A zone the files define is read-only here (409 set_by_file); the API zone is merged after the files' zones and replaces nothing. Writes need config:write:records for agents (zones are local data), so no new agent scope enters the catalog. Zone records have no node_only flag: a replica's own zone records would be overwritten by the primary's zone, and the shared-part filter only covers top-level lists. The record fields in a zone are the record fields of [[record]] without node_only.
  2. Route limits are stored on the forward. match_group, match_qtype, dnssec_nta (on by default, as a forward always had it) and node_only are fields of the stored forward, expanded into its route and group. A node-only forward marks its group, its route and its servers node_only, so shared_part keeps them on the node. A route the files define with a group or query type stays out of the "send this domain" list, as before; an API route with them is listed.
  3. Records gain ttl (already stored) and node_only in the API and UI. A blank TTL means [local] default_ttl, as before. The TTL column shows in Simple view too.
  4. No new config fields. The config schema is unchanged: Route, LocalRecord and ZoneConfig already carry these fields.

Decision (T27.5):

  1. Shared singletons for slo, probe and upstream_check (operators). They are one entry each (/slo-settings/default, /probe-settings/default, /upstream-check-settings/default), replicated with the shared configuration, and they go through the same singleton code as the rate limit and [special] (settings_kinds): the fields the files set are locked (409 set_by_file), a field left out takes its default. [probe] targets is an empty list when unset.
  2. Node-managed admin-only singletons for the telemetry sections. [telemetry.anomaly] (/anomaly-settings/default), [telemetry.qlog] (/qlog-settings/default) and [telemetry.metrics] (/metrics-settings/default, per_client and its cap only; the listener and the switch stay in the file). They are node-local sections, so they are rows of the node-managed kinds (ADR-903 §6, ADR-984) and replicate in node-managed.json. The whole kind is an admin's: an operator's write is 403 even when it changes no field, an agent is refused (no scope), and a node too old to say who asked is 409 upgrade_required. This follows the task's "admins, since privacy and retention are at stake" and makes privacy_level an admin's too. Like OTLP, the setting is cluster-wide: every member applies the same value, not one entry per node. ADR-914's per-node key (node/<id>/<kind>) is not used here; a per-node tuning setting would need that key, and it is left to the owner (Open).
  3. When a change applies. Probes (read each round), the objectives and per-client metric series (set_client_metrics on reload), second opinions (Checker::from_config on reload), anomaly detection (reconfigure on reload) and the query log's privacy level (set_privacy on reload) apply on every node without a restart. The query log's other settings (on or off, retention, flush, fsync) are read when the store opens, so they are restart-only: telemetry_at_start leaves out exactly the parts that apply on reload, and the server's existing "takes effect after a restart" warning covers the rest. The UI says so in the change's sentence.
  4. The probe loop looks again every second until the listeners serve. Before, a round waited a whole interval when the first attempt came before the listeners were bound, so a new interval (or the default 30 s) showed no results for half a minute after start. The first round now follows the listeners' start, as the page's text already said.
  5. Form and API. Each section has a disclosure on the page where its data is (SLO card, Settings → System for the listener checks and the metric series, Upstreams for second opinions, Anomalies, Query log), shown read-only to roles below its writer. The API has one PUT and one DELETE per section; no MCP tool, because agents never write these (as for [discovery], ADR-907). The OpenAPI gains six paths (165 in all).

Test plan (T27.5): obs_020_probe_settings_apply_on_reload, obs_013_anomaly_settings_node_managed, obs_003_qlog_retention_node_managed, obs_016_slo_settings_operator_and_bounds (server, settings_kinds_tests); Playwright obs_020 change probe interval and obs_003 operator cannot change privacy level; help topics slo, probes, upstream-checks (updated), anomaly-settings, qlog-settings, metrics-settings (new).

Consequences

a zone is answered from the next query on every node, and a forward's limits apply to the route the same way the files' do. The OpenAPI gains /api/v1/zones/{name} (159 paths) and the schemas ZoneInput, ZoneRecordInput; ZoneInfo gains source and values, ForwardInput/ForwardInfo the four limit fields, RecordInput nodeOnly.

Test plan

Playwright dns_010 route by group and type, dns_010 add a zone, dns_010 record ttl (DNS answers checked on the wire for TTL and address; ghost.zone010.e2e.test gets NXDOMAIN); help topics routes, records and zones (check:help); the OpenAPI path count and committed snapshot.

Requirements API-901 DNS-010 OBS-003 OBS-013 OBS-016 OBS-019 OBS-020

Builds on ADR-903 ADR-907 ADR-914 ADR-984

ADR-1008 The GeoIP database as built: [map.geoip] inside [map], a task that looks every 5 s, positional reads, an admin-only write pathProposed 2026-11-18NFROBST26.4 (OBS-902, NFR-001) built ADR-959.

Context

T26.4 (OBS-902, NFR-001) built ADR-959. The ADR left room in a few places (where the setting lives, how an admin-only part rides in a section operators write, what the tests may relax, how the schedule behaves on the first fetch); this records the choices and the three small departures from the text.

Decision

  1. Where the settings live. [map.geoip] is a nested table of [map] (MapGeoipConfig: enabled, source_url, sha256, home_country), not a kind of its own: the section stays one GET/PUT/DELETE /api/v1/map-settings/default entry and one stored override. Validation is in wrendns-config (map.geoip.source_url: an https:// URL with a host and no user@; sha256: 64 hex digits; home_country: two letters), so every writer (API, UI, files, GitOps) meets it and the 422 names the field.
  2. Admin-only inside a section operators write. settings_kinds::check_admin_fields gained ManagedKind::Map => ["geoip"] (ADR-914's second tier, the same function special.ddr_name and [discovery] use): a change that moves the geoip object is 403 naming it for an operator or a viewer, agent_not_allowed for an agent whatever its scopes, 409 upgrade_required from a node too old to say who asked. A [map] body that leaves geoip out keeps the one in effect (map_body_keeping_geoip), so T26.6's thresholds form, which does not carry it, never resets it. A consequence, documented: an operator's DELETE /map-settings/default (back to the file's [map]) would also take geoip back to the file's and is therefore refused for as long as that moves it.
  3. Routes. GET /api/v1/map/geoip (every role; agents config:read), POST /api/v1/map/geoip/update (202, admin) and DELETE /api/v1/map/geoip (admin) act on the node that answers (each node serving the console has its own copy), are in OpenAPI, and have no agent scope and no MCP tool (an agent cannot make a node download from the internet or delete a file; required() denies them by default and obs_902_geoip_admin_only proves it). They are audited as map.geoip.update and map.geoip.delete; a settings change is audited as the [map] change it is. A resolver pod answers 404.
  4. The task. GeoIp::run looks at [map.geoip] every 5 s (and at once when the configuration reloads or Update now is pressed: poke). It never runs on a worker or a query's path. Off: nothing is requested, nothing is written, the file stays, and the handle is dropped so nothing can read it. On: it opens what is on disk (country.ttgeo, else .prev), and fetches when there is no database, when the stored month is older than the current one and the next check is due, or when an admin changed the source or pressed Update now. A changed source is fetched once (the backoff governs repeats). After a success the next check is 24 h plus the node's jitter (a stable hash of its name, 0 to 6 h); a failure backs off 1 h doubling to 24 h. Departure 1: ADR-959 says the node "starts" at a jitter of up to 6 h; here the first fetch after an admin opts in is immediate (an admin waiting up to six hours for the thing they just turned on would be wrong), and the jitter spreads the scheduled monthly refreshes of a cluster. Delete database removes the files and suppresses automatic fetching until Update now or an off-and-on toggle, so the world view says geoip_missing as ADR-959 asks. Departure 2: the status gained a state missing (on, no database here yet or deleted) beside off, downloading, ready, failed, because failed with no error read wrongly after a delete.
  5. Download. The list fetcher's Client (hyper over rustls, the same address rule: link-local and cloud-metadata addresses refused, everything else allowed), HTTPS only, 120 s for the attempt, 32 MiB compressed, a redirect to HTTP refused, no response body ever shown (an error is a code: not_found, http_error, redirect_refused, too_many_redirects, too_large, tls_failed, dns_failed, timeout, address_refused, not_https, download_failed, and the verification codes below). Departure 3: the client follows 5 redirects, not 3: changing the shared client's limit would touch wrendns-filter, a hot-path-listed crate, for a number that buys no safety here (each hop is HTTPS and address-checked). The default URL is this month's file, then, on a 404 only, last month's.
  6. Verification and build (geoip/ttgeo.rs, no new dependency: miniz_oxide streaming inflate, ring for the digest, a table-driven CRC-32): the gzip header, trailer CRC and size are checked while the CSV streams through a 16 KiB buffer (the text is never held; a line over 256 bytes is malformed); rows are start,end,CC (a v4-mapped range is a v4 range); sorted (a mirror's unsorted file is sorted, not refused); no overlap; at least 100,000 rows, 150 countries, both families; the row count within 30% of the database replaced; the pinned digest. Contiguous ranges of one country are merged; IPv6 is cut to /64 (a /64 two ranges share belongs to the earlier one); gap rows (country 0) are stored wherever a range ends before the next begins, including before the first and after the last, so an address in a gap is nobody's. The codes are corrupt_download, malformed_row, overlapping_ranges, too_few_rows, too_few_countries, missing_family, size_changed, too_large, digest_mismatch, write_failed.
  7. File and lookup. country.ttgeo: a 40-byte header (magic, version, source month, row counts, build time, the CRC-32 of the body, the source's row count), the v4 table (u32 start, u16 country; 6 bytes) and the v6 table (u64 first 64 bits, u16; 10 bytes). Written to .tmp, fsynced, the current file hard-linked as .prev, then one rename over the current file (no instant without a database); at most 16 MiB. Db is a file handle and five integers (at most 64 bytes, asserted); lookup is a binary search of preads (read_exact_at, seek_read on Windows), 2 x log2(rows) reads of at most 10 bytes, no allocation (obs_902_geoip_lookup_not_resident, and 2,000,000 lookups in obs_902_geoip_probe_database: 0 allocations). Not a memory map: unsafe stays in wrendns-net.
  8. Test allowances (ADR-959 section 8). Options carries the limits and extra trusted roots. The harness sets WRENDNS_GEOIP_TEST=1 (a handful of rows is accepted) and WRENDNS_GEOIP_TEST_CA=<pem> (the fake source's certificate is trusted): both are read only when debug_assertions is on, so a release build ignores them. The real address rule needed no loopback allowance: only link-local addresses are refused, and the fake source is on 127.0.0.1.
  9. Resolver pods never start the task (Role::Resolver), and /map/geoip answers 404 there.

Measured (this host, release build, Pi profile of 2 workers, bench/geoipprobe.py, a 7.15 MiB database of 600,000 rows written by obs_902_geoip_probe_database; 4 runs each, a flood of 3,000 lookups a second from 2,000 devices for 30 s and 30 s of rest): idle 13.2 to 13.3 MiB off and 13.4 to 13.5 MiB on (+0.2); after the flood and the rest 34.6 to 34.8 MiB off and 34.7 to 35.1 MiB on (+0.2 to +0.4), one first run at +1.5 MiB (35.9 off, 37.4 on) that did not repeat. The gate for a feature on the map's budget is 1.5 MiB. The database is read by position, so its 7 MiB never appears in the resident set. In-process, 2,000,000 random lookups added 192 KiB against 768 KiB for a control loop with no lookups. Binary size and the UI's budget: see the Done note of T26.4 and T26.5.

Alternatives rejected

a separate [map.geoip] kind with its own route and scope (a second override to keep in step, and the UI's thresholds form would need to know it); holding the table on the heap or in a memory map (RSS is the budget, and unsafe is not allowed here); parsing the whole CSV into a Vec<u8> (96 MiB peak); an allowance in release builds for a private CA (a way to point a production node at a forged source).

Consequences

an operator can tune the map's thresholds and never touches the database; an admin controls it from Settings with the status in front of everyone; going "back to the file's [map]" is an admin's act once the database is on; the download is a few MB a month per node that serves the console, and none at all until someone turns it on.

Review addendum (T26.4 review fixes): (a) the card is in Settings, Query handling, next to the other map controls, not in Monitoring as ADR-959 section 2 says; Monitoring holds node-wide telemetry sinks and the card needs the map thresholds beside it. (b) The parse keeps at most Limits::max_rows (1,200,000 since the second review, about twice the real file; IPv6 rows have their own cap of 700,000, 48 bytes each, and the tables grow in 64 Ki-row steps instead of doubling) source rows and rejects at the first row over it with too_large; before this only the 96 MiB byte limit bounded the heap, and a file of short IPv6 lines could hold 48 bytes of heap per 11 bytes of text. The compressed body is freed after the parse and the built tables after the write. Worst case heap while building is now bounded near 86 MiB for a hostile file, about 25 MiB for the real one (a build is a monthly event; the lookup path never holds it). Measured (second review, debug build, this host, obs_902_geoip_build_memory): a real-sized parse and build (300,000 IPv4 and 300,000 IPv6 rows) peaks at 67.5 MiB resident from a 14.6 MiB start (+51 MiB, about 35 MiB left after the build and freed after the write); the worst case at the caps (500,000 IPv4 and 699,999 IPv6 rows) peaks at 117.8 MiB (+103 MiB). The allocator is not mimalloc in that run (the release figures are in (h)). (h) Release measurement in the resolver's own configuration (fourth pass, review M2 of the third). The third pass measured the build with MIMALLOC_ARENA_RESERVE=0 (the workers' environment, ADR-988), not as the resolver runs (mimalloc's default arena and allocator_purge_at_once at start-up), and its throwaway harness never ran a build inside the resolver. Harness (committed): bench/geoipbuild.py. It runs a release-profile resolver (bench-fast: the shipped profile except thin LTO and 16 codegen units) built with the bench-only cargo feature geoip-probe, which only makes a release build trust WRENDNS_GEOIP_TEST_CA (the fake source's certificate) as a debug build does: production limits, the default arena and the purge at once are unchanged, and the feature is never in a release build. One process per run (VmHWM is per process). It writes a DB-IP-format gzip CSV (300,000 IPv4 + 300,000 IPv6 ranges of random length, mostly back to back with a gap before one row in ten, over 400 country codes: 5.5 MiB compressed, a 5.0 MiB .ttgeo), serves it over HTTPS from 127.0.0.1, starts the node with 1,000,000 blocked names, the cache filled to 100,000 entries (over a TCP upstream: a UDP upstream query binds a socket, 10 to 200 ms each on Docker Desktop), [map] enabled and telemetry on, reads idle, then turns [map.geoip] enabled on and reloads (SIGHUP) with the source holding its answer, resets VmHWM once the request is in (clear_refs 5), lets the source answer, and reads the peak, RSS 2 s after the file is published and settled 30 s later; --builds 2 builds again in the same process (a changed source is fetched at once). The download (Client::get collecting the body) is inside the window. Before (this branch's tip before the fourth pass, run with the harness): the build ran on the shared runtime (the body collected by a runtime worker, the build in spawn_blocking). Idle 69.9 MiB; peak 113.6 MiB (+36.9 over the post-reload level); settled 80.0 MiB after one build and 82.3 after a second (+12.4 over idle: anonymous +3.4 MiB, the rest the code pages the reload, download and build touched). On an idle node (no list, no cache): 22.8 MiB idle, settled 28.4, 37.7 and 38.8 MiB after 1, 2 and 3 builds, so what a build left behind stacked. The third pass's "stays at its 55.4 MiB peak" did not reproduce with the purge at once (the resolver's setting): it is the build's pages held by the threads that allocated them plus code pages, not the whole peak, but it climbed with each build, which is still a breach of a hard budget. Fix (the most conservative option consistent with ADR-988 and the AGENTS rules: no new process, no new crate, unsafe only in wrendns-net): the download and the build run on a thread of their own (geoip-build, normal priority) with a one-thread tokio runtime that ends with it, so every buffer of the attempt (the TLS session, the body, the parse and the tables) belongs to that thread's heap; when it is done the thread calls wrendns_net::allocator_collect() (mi_collect(true), one // SAFETY: call in wrendns-net/src/sys.rs), drops the code pages the attempt touched (server::trim_code_pages, as after a list compile), and exits. Running it in the discovery worker (ADR-988) was not chosen: it would add a process, a new IPC message and the worker's address-space limit to a monthly job whose memory now comes back in-process. After (two runs, within 1.5 MiB of each other): gate set-up: idle 69.8 MiB, peak 112.0 MiB (+35.0 MiB over the post-reload level, +42.2 over idle), 58.2 MiB 2 s after, settled 64.3 and 65.8 MiB after one and two builds, against 69.8 idle (anonymous memory 50.5 to 50.8 MiB: +0.3). Idle node: 23.4 MiB idle, settled 22.2, 22.6 and 22.4 MiB after 1, 2 and 3 builds (anonymous 8.5 to 8.8). Twice the real file (600,000 + 600,000 rows, 11.0 MiB compressed, a 10.0 MiB .ttgeo, idle node): peak +74.2 MiB over the post-reload level (+77.6 in the recheck), settled 22.2 and 22.6 MiB against 23.0 idle. A reload with nothing changed (--control) adds 4.8 to 7 MiB of code pages that stay (anonymous +0.3), so part of "post-reload" is the reload, not the build. Reading against the gates (spec/00 section 5, hard): the resolver returns to its idle size after every build, so the 64 MiB working-set gate is what it was before the first build; this host can't check the absolute 64 MiB figure here (bench/lists/ is not on it, and 1,000,000 synthetic names compile larger than the real lists: idle 69.8 MiB with them, above the gate before any build, so the harness checks the absolute gate only with the real lists and the full cache). The transient is 35 MiB for a real-sized file (64 + 35 = 99 MiB, under a 128 MiB pod) and 74 to 78 MiB at twice the size (64 + 74 to 78 = 138 to 142 MiB, over it: the residual recorded by the third pass, unchanged, bounded by the row caps and a monthly event). Bounds the review asked for: the built tables are now sized exactly by a counting pass (merge_v4/merge_v6 run twice, count then fill; obs_902_geoip_tables_are_sized_exactly): the third pass's estimate len + len / 8 + 2 regrew (doubling, with the old and new buffers held together) on a file with a gap before every row, whose tables have 2 x len + 1 rows; exact sizing never regrows. The download's body is one Vec grown by doubling in wrendns-filter's client (not changed here: a hot-path crate), capped at max_download, 32 MiB: at most 32 MiB of capacity and 48 MiB while the last doubling copies (a hostile source at the cap; the parse then rejects or caps it by rows); for the real 5.5 MiB body that is 8 MiB of capacity (12 MiB while it grows), inside the measured peak. Recheck (independent, same harness, HEAD dc628553): the glibc bench-fast figures reproduced within 1.5 MiB (gate set-up with real lists: idle 70.4, peak +35.0 over the post-reload level, settled 64.7 and 66.6 after two builds, anonymous +0.3 to +0.4; the pre-fix binary: settled 79.8 and 82.1, anonymous +3.9; idle node settled 21.5, 23.3, 22.5 after three builds, anonymous +0.4; twice the file +77.6; a reload alone +4.9). The absolute gate, checked with real lists in the shipped build: a musl release build (fat LTO, cargo zigbuild as the image builds it, with geoip-probe), the first 1,000,000 unique names of OISD big, HaGeZi Pro, StevenBlack and HaGeZi TIF (the snapshot's sources, fetched 2026-11-19), 99,908 cache entries, telemetry on: idle 64.8 MiB 10 s after the fill, peak 104.9 MiB (+34.9 over the post-reload level), settled 59.6 and 61.0 MiB after one and two builds (anonymous 49.4 to 49.5 MiB): under the 64 MiB gate after a build, and below the idle reading because the build's thread trims the code pages start-up left resident. The idle reading itself is 0.8 MiB over the gate at 10 s after the fill (bench/gate.py recorded 60.0 MiB at 40 s for the shipped build, docs/v1-gate.md); that is the node before any GeoIP build and outside T26.4. Not measured here: a Pi. (c) A delete while a fetch runs bumps a generation: the running attempt throws its result away and removes what it wrote. (d) A working database stays ready when only the latest refresh failed; lastError shows the failure. (e) source_url may carry no query string or fragment (it is shown to every role). (f) A mirror's database is labelled with the month it was fetched in: a mirror's file has no month, and the monthly cadence of the refresh is the intended one. (g) Departure 1 (every node fetches at opt-in) remains Proposed for the owner.

Requirements NFR-001 OBS-902

Builds on ADR-914 ADR-959 ADR-988

Referenced by ADR-1031

ADR-1009 The world view as built: a pure world() over merged prefixes, upstream markers while the answer address is unrecorded, a baked-in dot-grid mapAccepted 2026-11-19OBST26.5 (OBS-902) built ADR-958 sections 5, 6, 8 and 9 and ADR-970's answer: the node does not record the address an answer points at, so the world view starts with the upstreams' places and says so.

Context

T26.5 (OBS-902) built ADR-958 sections 5, 6, 8 and 9 and ADR-970's answer: the node does not record the address an answer points at, so the world view starts with the upstreams' places and says so.

Decision

  1. The data. GET /api/v1/map/world is map::world(parts, thresholds, now, node, locate): pure, tested without a node. A node's part now carries answers_recorded (false today) and answers (at most 256 prefixes, a /24 or /48 with weighted, sampled and slow counts) and each upstream's ip when its endpoint is an IP literal (a host name has none: it is counted in unplacedUpstreams). The answering node merges the prefixes across nodes (the same prefix adds), keeps the busiest 256, and asks its own database once for all of them and the upstream addresses. So the day the field is recorded, the arcs, the countries and the counts work with no change to this function; until then answers_recorded is false and the reason is address_not_recorded.
  2. Reasons, in order: geoip_off, geoip_missing (nothing is placed and nothing is asked of the database), then privacy (level 3 keeps nothing per event, so every answer is unlocated; levels 0 to 2 place answers, because an address says nothing about a device: ADR-958 section 7's own reading), then address_not_recorded (the markers are still returned). available is true only when countries are placed.
  3. Regions. Counts add by country (uppercased); qps is the weighted count over the 60 s window; slowPct the slow share; health is classify with the edge rules (idle under min_sample real answers, yellow from warn_slow_pct; there is no red: an answer's address carries no error). At most 64 regions, busiest first. unlocated is the window's lookups less the placed ones. Markers: one per upstream whose address has a country, health from classify with the upstream rules and the worst breaker across nodes.
  4. Filters. Departure from T26.5 step 6: the text says "the same filters"; a prefix is counted per node, not per device, group or network (keying it by device would put the 256-prefix cap per device and the memory ADR-970 measured at 0.6 MiB out of reach). So node narrows the read on the server, State narrows what is drawn, and the page says why the other three do not apply. Recorded as a limit, not hidden.
  5. The map. ui/src/lib/world-data.ts is generated by ui/scripts/gen-world-data.py from Natural Earth 1:110m (public domain) and the tz database's iso3166.tab and zone.tab: a 180 x 70 grid of 2-degree cells from 84 N to 56 S, 1 bit a cell (a cell is land when 3 of its 9 sample points are), and 247 countries (code, name, longitude, latitude; the point is the area centroid of the largest polygon, or the mean of the zone points for the small states the 110m set leaves out). 4.7 KiB gzipped on its own (the ADR's target is 12), baked into the page's lazy chunk. The land is drawn as one <path> of small squares (one DOM node), the arcs as quadratic curves that rise with their length (a country that is the home country loops above itself), the pulses reuse the network map's (pulse(): density from the rate, width from its log, a seed per arc; animation-play-state paused when the tab is hidden or the user pauses; nothing moves under prefers-reduced-motion, and the rate is written on each arc). Colour is never alone: the network map's shapes and words, and a diamond for an upstream. A table of countries and of upstream locations is the accessible equivalent, and the figure is a role="group" with a text summary.
  6. Words. Each reason has a title and a sentence (whyUnavailable), the admin gets a link to the setting (geoip_off, geoip_missing), everyone else "ask an admin"; with only markers the page says "Upstream locations, not where answers point" (as a banner whether the server calls it available or not); the footer carries the licence's attribution; "N of M lookups have no location" counts failed, blocked and local answers, level 3 and addresses with no country.
  7. No outside requests. The page loads no tile, font or script (a test records every request's origin); the CSP is unchanged.
  8. Bundle. The world page is its own lazy chunk (World-*.js 11.3 KiB gzipped + World-*.css 0.9 KiB) plus the code it shares with the network map (map-*.js 3.2 KiB, split out of the map's chunk): 15.1 KiB against the 30 KiB limit. The whole dist went from 356.3 KiB to 372.5 KiB gzipped (+16.2 KiB, of which the GeoIP card and the API client are about 4 KiB in the main bundle), against the 400 KiB limit.

Consequences

until the answer address is recorded the world view is a map of where the upstreams are, and says so; nothing in the page changes the day it is; a site without the database sees a clear message and, for an admin, the way to turn it on.

Requirements OBS-902

Builds on ADR-958 ADR-970

ADR-1010 The map's settings card: Query handling, one field per [map] setting, a client-side preview of the flowsAccepted 2026-11-18OBST26.6 (OBS-901).

Context

T26.6 (OBS-901). ADR-958 section 4 puts the [map] controls in "Settings → Monitoring" and asks for a live preview that reclassifies the current snapshot with the draft values. There is no Monitoring tab: Settings has Account, API tokens, Integrations and secrets, Users, Audit log, Sign-in, Telemetry, Pi-hole, System, Query handling and Cluster; Telemetry is operators-only, and the card has to be readable by viewers.

Decision

  1. Place. The card is on Settings → Query handling (every role sees that tab; the other shared sections [special], [ratelimit], [exclusions] and [simulate] are there), after Change simulation, and the map page links to it. It is the generic ConfigEditor (kind="map", path="map-settings", singleton) so the dry-run check, "Revert to the file", If-Match, the Git-authority TOML and the audit entry are the ones every shared section already has. Each field's label carries data-setting="map.<field>", the mark T27.18's check will read. Viewers see the summary and no Edit; the server refuses their write (403) regardless.
  2. Bounds. The form sets no min/max on the numbers: the server's 422 names the field and gives the range (map.event_rate: from 10 to 2000 lookups per second), and the help text under each field states it. A browser's own validation tooltip would hide the server's wording and is not testable.
  3. Preview. ui/src/lib/map-thresholds.ts reclassifies the devices, upstreams and answer kinds of the current GET /api/v1/map snapshot from each flow's errPct, slowPct and blockedPct and the node's real sampled count, with the server's rules (error rules not for an answer kind; blocked for devices only; idle below min_sample). What a snapshot can't carry (the rate limiter, anomalies, breakers, router errors) keeps its colour; the slow share was counted with the current warn_latency_ms, so a new latency threshold shows only after Apply (the card says so in the docs). It is a sentence under the fields (note), not a second map. Conservative choice: a server-side dry-run classification (?preview= on the map route) would be exact but adds an API route and a recompute on the aggregator's snapshot; deferred.
  4. No new route, scope or MCP tool. PUT/DELETE /api/v1/map-settings/default, config:write:map and plan_set_map are T26.2's; the OpenAPI document, the MCP snapshot and the config schema do not change.

Consequences

the Query handling tab loads one GET /api/v1/map for the preview (a 404 map_disabled is "no preview"). The web bundle grows by about 5 KiB gzipped (353.5 to 358.8 KiB of 400).

Test plan

Playwright obs_901 change map thresholds, obs_901 out of range value names the field, obs_901 viewer sees map settings read-only and obs_901 preview reclassifies by sample, scope and held reasons (ui/tests/e2e/7-map-settings.spec.ts).

Requirements OBS-901

Builds on ADR-958

ADR-1011 A witness is a voter: the cluster view says so and the checks skip it for configuration, secrets and DNSAccepted 2026-11-18A witness (ADR-056, wrendns cluster witness) runs the cluster channel and the election only: no configuration, no secrets, no DNS.

Context

A witness (ADR-056, wrendns cluster witness) runs the cluster channel and the election only: no configuration, no secrets, no DNS. The cluster view built every member the same way, so a witness showed "version 0, 13 behind", secrets "not reported", "not ready", uptime 0, an amber topology box, and counted in the Health and Compare tabs. An unreachable witness mattered, though: with three voters, losing one leaves two, and automatic failover needs a majority.

Decision

  1. The view keeps witness: true as the marker (the role string stays replica, so no consumer of role changes) and clears the fields that mean nothing for it (configSeq, configLag, behindSeconds, secrets, ready, load and cache). It adds vote (lastReplySecondsAgo, lastGrantSecondsAgo, votedEpoch), taken from the last reply the witness gave this node's vote request or lease renewal; absent times mean this node has not asked it (manual failover, or a node that is not the primary).
  2. A witness's heartbeat carries its process start and uptime (fields every peer already reads; nothing added to the wire, so older peers show 0 as before). Its version is already in its Hello.
  3. Checks, health reasons, alerts, the peer-lag metric and the rollout skip a witness for configuration, secrets and DNS (in_sync, serving, sync_lag, canary choice, rollout samples). An unreachable witness still fails peers_up and raises node_down (health reason and alert), which the health reason had suppressed.
  4. The UI shows "witness, votes only", "not applicable" for the three, and the vote state; the topology draws it green while up and red when down.

Alternatives rejected

a new role: "witness" string (every role comparison, the promote form and older clients would need to learn it); hiding the witness from the page (the owner needs to see its vote and that it is up); asking the witness for its ballot over a new RPC (a wire change for a number the primary already learns from the replies it gets).

Consequences

the view is a little different for a witness in the API (vote, cleared fields); docs/api/openapi.json and the UI types are regenerated. No DNS path change.

Builds on ADR-056

Referenced by ADR-1063

ADR-1012 A dead member of a group that still answers is a warning for the resolver; an upstream with no route says soAccepted 2026-11-18fork #25.

Context

fork #25. On a three-node Pi cluster every node was Failing on the map although every query was answered: two IPv6 members (Cloudflare, imported from Pi-hole) of the default fastest group had no IPv6 route and failed, and ADR-970 section 5 colours a resolver by the worst of what is downstream of it. A spare that cannot be reached is not an outage.

Decision (amends ADR-970 section 5; nothing else in it changes):

  1. Group-aware roll-up. For the resolver's roll-up, an upstream that is red counts as yellow when it is in at least one upstream group and every group it belongs to has a member that is not red (a green, yellow or idle one). The resolver's reasons then say member_down: "upstream X is down; its group still answers through Y". An upstream in no group, or in a group whose members are all red, stays red for the resolver: the group itself fails. The resolver's own ADR-104 level still applies, so a node that reports severe stays red. The dead upstream's own node on the map stays red and keeps its reasons. A map part now carries each upstream's groups (PartUpstream.groups, absent from an older peer, which then gets the old roll-up).
  2. "Answers failing above the threshold" is not a separate rule. The sampler has no per-group aggregate (an entry's group is the client group, not the upstream group), so a group is judged failing when no member is healthy, which includes members red by error rate. Adding a per-group aggregate would grow the window key, which ADR-970 section 3 sized; not done. Conservative: a group whose healthy-looking members actually fail some queries is yellow through the members' own colours, not red.
  3. No route. Each upstream given by IP address has a route state checked by a UDP connect() to its address (a route lookup; nothing is sent): at start and every 30 s, on the active-health timer, never on the query path, and no new dependency. A failed check is this node has no IPv6 route (or IPv4). It is shown on the Upstreams page (UpstreamInfo.routeProblem), on the map (reason no_route on the upstream node, and the node's tooltip), and in the node health: the upstream_down text when the breaker is open, and a degraded upstream_no_route reason when it is closed (a spare nobody has asked), so the map and the health API agree. An upstream with no route that is idle (nobody has asked it) is yellow, not idle; one that is red stays red. A hostname upstream is not checked (its family is the bootstrap's choice). Checking is advisory: it changes no query behaviour.
  4. The Pi-hole import adds a preview note for each IPv6 upstream: it fails on a host with no IPv6 route, with the member name to drop.

Consequences

a node with one dead spare is Warning, not Failing; a node whose whole group is down is Failing as before. Tests: obs_901_classify_group_aware, obs_901_dead_spare_member_is_a_warning, obs_901_unrouted_spare_is_yellow, ups_006_route_check, ups_006_no_route_with_closed_breaker_degrades, ups_006_pihole_import_notes_ipv6_upstreams; Playwright obs_901 legend (every icon under 24 px), obs_901 no_route and member_down reasons are drawn in the tooltips, ups_006 upstream with no route says why.

Builds on ADR-104 ADR-970

ADR-1013 One picker, and client takes severalAccepted 2026-11-18, T24.34FLTOwner request (fork #26): the Query log's client filter takes one address; the UI's list selections are a mix of checkbox lists.

Context

Owner request (fork #26): the Query log's client filter takes one address; the UI's list selections are a mix of checkbox lists. GET /queries read client as one value; axum's query extractor does not take a repeated key.

Decision

  1. One component (Picker.svelte) with a windowed list for every list selection; checkbox lists that choose from a growing list are replaced, short fixed lists with codes beside them (agent-token scopes) are not.
  2. client lists several, comma-separated, as status and qtype do (not a repeated key): addresses, hostname:<label> (ADR-973) and workloads (FLT-017). The server resolves them to addresses off the DNS path and searches client_any; at most 100 entries and 256 addresses (clientTruncated), 64 per router name or workload. clientNot keeps every other client, as for one. An unresolvable entry is a 400. The live stream takes the same list, resolved when the stream opens. A negated workload search no longer applies the pod-address history post-filter (it would drop every row).
  3. A device is all its addresses (revised after review). A named device with several addresses (IPv4 and IPv6, or a MAC holding more than one lease) is one picker item whose value lists them comma-separated, so picking it finds every address it queries from and clientNot leaves none of them behind; a link that carries them one by one is regrouped into the device when the list loads. An address no list knows (a MAC-only device's IPv6 that never leased) is still not found: choosing by name server-side (device:<name>) stays out, since names may contain commas and change.

Alternatives rejected

a repeated client key (needs a custom extractor and breaks peers on older nodes); client as a JSON array (unreadable URLs).

Consequences

a read to an older cluster peer with several clients is answered by it as an invalid address (400) and listed as not reached. Test plan: ui_901_*, kubernetes::tests::flt_017_a_deployment_is_one_device, tail::tests::obs_008_negated_filters.

Requirements FLT-017

Builds on ADR-973

ADR-1014 Log-only exclusions and a readiness check that asks the listenerAccepted 2026-11-18OBSOPSA cluster's query log can fill with client 127.0.0.1, group default, name localhost: a keepalived check every 2 s and a watchdog every 5 s query the node for localhost, and the node's own lookups show as 127.0.0.1.

Context

A cluster's query log can fill with client 127.0.0.1, group default, name localhost: a keepalived check every 2 s and a watchdog every 5 s query the node for localhost, and the node's own lookups show as 127.0.0.1. [exclusions] (OBS-022, ADR-111) already leaves names and clients out, but of the log and the statistics together. [telemetry] is node-local (NODE_LOCAL) and has no editable kind until T27.5. /readyz and wrendns health exist (OPS-006) but only report that listeners are bound. The probe name probe.wrendns.invalid (OBS-020) is already answered locally and kept out of the log and analytics.

Decision

  1. Log-only, and they still count. [exclusions.log] (clients, domains, own_lookups) leaves queries out of the query log, the live view and the event sinks only. The dashboard, top lists, device pages, anomalies, the live map and /metrics still count them. Reason: the owner asked for a quieter log, not different numbers. [exclusions] names and clients stay the way to remove a query from the statistics too; the docs say which does what. wrendns_queries_log_excluded_total counts what the log skipped.
  2. Where they live. Under the shared [exclusions] section (one UI card, one API route, one MCP tool, and the cluster's nodes agree) and not [telemetry.qlog]: that section is node-local with no editable kind (T27.5, open), so a UI control there would be a new node-managed kind for three fields. Spec gap, most conservative option, recorded here; per-node settings can be added with T27.5 without changing these keys.
  3. Applied at write time. The filter runs on the aggregator thread when a drained event is passed to the log's sink; the query path is unchanged. A device name resolves to the configured clients' references on every reload (case-blind; a name no client has matches nothing); own_lookups is loopback, the addresses the listeners are bound to, WRENDNS_NODE_IPS and the kernel's default-route address. It is off by default: a cluster with health checks turns it on; a fresh install logs everything it is asked.
  4. /readyz asks the listener. From the point the listeners are bound, /readyz sends one UDP question to the first UDP listener on loopback and answers 200 only if a response arrives within 1.5 s (503 dns_unanswered otherwise; no UDP listener: bound is the answer). The result is reused for 1 s so an unauthenticated route cannot be made into a query source. The body keeps its existing shape and carries no configuration. wrendns health is the CLI; the keepalived example calls it (or wget) instead of querying localhost.
  5. The probe name, not localhost. The task text said to resolve localhost through the real listener and flag it. A DNS query carries no flag, and localhost is a name real programs ask (it would have to be hidden from everyone). The existing probe name already is "flagged": answered locally, never forwarded, kept out of the log and analytics (OBS-020), and the watchdog uses it. The raw wrendns_queries_total still counts it (that counter is on the answer path; a check there would cost every query), as it counts the watchdog's.
  6. Importer. Pi-hole's excluded domains and clients map onto the log-only lists because Pi-hole still records those queries; but it hides them from its query list, top lists and history, so the dashboard and top lists here still count them and will differ from Pi-hole's (the preview note says so; names added to [exclusions] leave the statistics too). (.*\.)?suffix is both suffix and *.suffix; a value containing / is not imported. v6 values are regexes: ^name$ becomes the name, ^.*\.suffix$ becomes *.suffix, ^1\.2\.3\.4$ becomes an address; anything else is named in the preview as not imported (never guessed). v5 plain values are taken as they are.
  7. Probe limits. /readyz proves the first UDP listener replies; it does not exercise the cache, filter, upstreams or the TCP, DoT and DoH listeners (documented). Concurrent probes are single-flight. The keepalived scripts carry timeout 5.

Alternatives rejected

a second node-managed kind under [telemetry.qlog] (more machinery now, nothing gained); hiding localhost for everyone; subtracting probes from wrendns_queries_total on the query path; making the exclusions drop from the statistics too (changes what [exclusions] users already rely on).

Consequences

ExclusionsConfig gains log; the aggregator gains one flag check per event; /readyz gains one local UDP round trip per second at most; docs, help topic qlog-exclusions, OpenAPI, config schema and the MCP tool follow.

Test plan

in T24.35 (obs_903_*, ops_901_*, two Playwright tests) and make bench-smoke.

Requirements OBS-020 OBS-022 OPS-006

Builds on ADR-111

ADR-1015 A simple upstream picker beside the technical editor; the picker's entries are named, not trackedAccepted 2026-11-18T24.36, fork #27.

Context

T24.36, fork #27. Owner request: upstreams are hard for a general user; Pi-hole's checkboxes for public providers are easier; keep the technical view. ADR-036 says the global Simple mode never hides something that changes behavior, so a page-level choice, not the global mode, decides what the Upstreams page shows first.

Decision

  1. Two views on the page, chosen by a page-local control (Simple is the default, remembered per browser; the global Simple/Advanced mode is unchanged and still decides the extra columns). Both stay mounted, so nothing typed is lost on a switch.
  2. The picker owns entries by name: pub-<preset>-<protocol>-<n> and pub-custom-<n>. It reads its state back from those names and the address families in them, so there is no new storage and no new write API: it uses PUT/DELETE /upstreams/{name} and PUT /upstream-groups/default. Anything else is never rewritten or deleted and stays in the default group.
  3. Transport: Encrypted writes the provider's DNS over TLS addresses (the IP ones carry the TLS name, so no bootstrap), or its DoH address when it has no DoT one; Plain writes its udp:// addresses and says so when it has none. DoQ is not written (Open).
  4. IPv6 is offered only when the node has an IPv6 default route, read from /proc/net/ipv6_route when the page asks (off the DNS path); unknown (not Linux, unreadable) reads true. An IPv6 address already saved keeps its box ticked so it can be removed.
  5. Group: the picker sets the default group's strategy to fastest (the owner's choice) and keeps the members it did not make. A node that keeps configuration in Git gets the same "keep in Git" answer the other editors give.
  6. Catalog: presets/upstreams.toml gains provider, variant, note, simple; GET /api/v1/upstream-presets and the MCP tool list_upstream_presets expose it read-only (config:read). Presets stay inert templates.

Gaps and conservative choices (for the owner): the "config file" label reported in #27 could not be reproduced (the server labels API-made upstreams added); each upstream now states its origin. Notes are one line from the providers' public pages and can go stale; the nightly smoke test checks addresses, not notes. With the picker saving the default group as an override, a later change to the group in the config file no longer applies until the override is removed (the same rule as every other API-made override).

Alternatives rejected

a separate "simple" storage with its own table (a second source of truth for upstreams); expanding presets on the server with a write endpoint (more API for a few lines of UI logic); making the global Simple mode hide the editors (ADR-036).

Test plan

ups_004_simple_presets_are_complete, ups_004_ipv6_route_check, ups_004_rows_carry_endpoints_with_protocol_and_family, ups_004_api_made_upstream_is_not_labelled_file; Playwright ups_004 ... (four).

Consequences

a general user can set up upstreams with ticks; the technical forms are one click away. One read route and one MCP read tool; no new dependency; nothing on the query path.

Builds on ADR-036

ADR-1016 A promoted primary adopts the API entries the cluster last publishedAccepted 2026-11-18CLUSeen on a three-node test cluster: a Pi-hole import was applied through the API while node-b was primary (upstreams, lists, groups).

Context

Seen on a three-node test cluster: a Pi-hole import was applied through the API while node-b was primary (upstreams, lists, groups). After an automatic failover node-a was primary, GET /api/v1/upstreams listed an imported upstream and node-a served it, but DELETE of it (and ?dryRun=true) answered 404. The cause: the API's entries are rows of the node that took the write (state.db, managed); a replica applies the cluster's shared configuration, which already has them merged in, and holds no rows. A write on the promoted node looks an entry up in its own rows and in its own config files (override_step, plan_override), and the entry is in neither: it is only in the version the node builds on (applied.json, ADR-051). The same held for every kind that is not a node-managed one (devices, local records, forwards, quick rules, lists, groups, upstream groups, alert destinations and rules, schedules, anomaly mutes, routers, Kubernetes map rules and the sections the API replaces whole). Worse, a delete that did work (a Hidden or a removed row) would have come back, because the version the node builds on still carried the entry.

Decision

  1. The primary publishes its rows of the shared kinds whole. They ride in the manifest's existing node_managed blob (node_managed::SHARED_KINDS), as entries {kind, name, body}; the document carries managed: true. No new manifest field, so a build that doesn't know the kinds skips them (CLU-010), and a blob without the flag (an older primary) means "no rows published". The rows travel as the shared configuration already does (the shared part carries the same values, credentials included, so the blob adds no exposure; the node-managed kinds keep their references-only rule). Except node_only rows (CLU-006): the shared part keeps them on their node, so encode leaves them out of the blob too, and a promoted primary never applies an address only the old node could reach. Adoption keeps this node's own node_only rows (replace_managed_noted does not delete them), so they survive a failback.
  2. A node promoted from replica replaces its rows with the blob it inherited, once per blob. managed_adopt::adopt makes the shared kinds' rows exactly the blob's, in one transaction (State::replace_managed), and records the blob's hash as a marker in state.db's meta table, in the same transaction as the rows (State::replace_managed_noted: it also skips the whole step when the marker already matches), under a process-wide lock held for a whole adoption, so the publish loop, a reload and a write plan can never interleave a replacement with a write, and a marker that can't be written can't make the node adopt again on every tick. A call for a blob already adopted in this process answers from memory without reading the blob. "Exactly" is the rule that stops a stale store from winning: a node that rejoins with rows from an earlier time as primary has them replaced, not merged, and the marker is dropped while the node follows a primary, so a later promotion adopts the blob it inherits even when its hash is one adopted before.
  3. The version the node builds on loses the adopted entries (managed_adopt::strip), so what its rows say is what applies: a deleted row is a deleted entry, an edited row is the edit. A name this node's own files also define is put back as the files have it; a section the rows replace whole goes back to the files'. The same stripped version is the base of every write plan (plan_files: dry runs, the overrides view, the Pi-hole import), so entries from the old primary's files (not rows) can be hidden here too. Known limit: an API row that overrides an entry the old primary's files define (same name) is one row in the blob, and the version holds only the merged result, so the file's own version is not recoverable; on the new primary, deleting that row removes the entry from the cluster unless this node's files also define it (on the old primary it would have revealed its file version). Say so to the owner; the cluster's files should define the same entries. A name defined in the cluster version but not in this node's files answers 409 "defined in the config files" on a record, forward or rule, with a hint that it comes from the cluster's configuration.
  4. Replicas keep their rows alone. A replica ignores its store (as before) and does not clear it (unlike node-managed kinds): its rows may be a standalone node's first configuration. They are replaced at promotion.
  5. A blob without the rows (older primary) changes nothing (superseded by ADR-1019 (Proposed): such a node now adopts what it serves, and refuses writes until it has): the node keeps its rows and builds on the inherited configuration as it did; a write to an entry it serves but doesn't hold now answers 409 with the reason (the old primary didn't hand its entries over; upgrade, then change it on the current primary) instead of a bare 404, and the UI's error note shows that text.

Alternatives rejected

reconstructing rows from the published configuration by diffing it with the files (it can't tell the old primary's file entries from API entries, and forwards and replaced sections have no clean inverse); publishing the pre-merge configuration as a second blob (doubles the version and changes what replicas hash); keeping a replica's store in sync row by row (a replica writes nothing, and a second copy to keep consistent); clearing replicas' rows (destroys a joining node's local entries before the cluster's version arrives).

Consequences

the blob grows by the size of the API's entries (kilobytes); a promoted primary's first reload writes its rows once; DNS is unaffected (the adoption is on the reload path, not the query path); CLU-004 holds (an unreadable blob or a store that can't be written leaves the node serving the inherited configuration). Known limit: rows are published only by builds with this change, so the first failover after every node is upgraded is the first that hands entries over.

Test plan

clu_015_promoted_primary_edits_and_deletes_every_api_entry, clu_015_readoption_after_a_demotion_even_for_the_same_blob, clu_010_a_blob_without_the_rows_is_left_alone (superseded by the clu_015_t24_40_* tests, ADR-1019), clu_015_the_blob_carries_the_shared_rows, clu_015_replace_managed_is_exact; deploy/cluster3/e2e.sh step h.

Requirements CLU-004 CLU-006 CLU-010

Builds on ADR-051 ADR-1019

Referenced by ADR-1019 ADR-1063 ADR-1064

ADR-1017 How T24.29 resolved what the design left open: measured budget figures, the compile-sort cap, streaming fetch, the agent gate and the one-transaction writeProposed 2026-11-18, T24.29ADR-994 and ADR-995 fix the scope and the catalog.

Context

ADR-994 and ADR-995 fix the scope and the catalog. Building T24.29 needed choices neither named. The most conservative option consistent with them was taken in each case and is recorded here for the owner.

Decision

  1. Measured figures replace the estimates (design section 2.4): the snapshot is 12 bytes a domain (measured 10.4 to 11.7, kept at 12); the compile peak is min(source bytes x 5.0, merge budget) + 28 MiB (re-measured in review with bench/categories_rss.py: 37.8, 75.7 and 153 MiB for Basic, Enhanced and NRD 7 days, each under the estimate; the first figure, 4.0 with no fixed part, was under the measurement for a small selection); entry_budget stays 1,000,000 and the heavy threshold 500,000; heavy sources refresh every 24 hours.
  2. The compile's sort memory is min(compile_memory, a quarter of the node's memory limit) (floor 16 MiB), read from WRENDNS_MEMORY_LIMIT, the cgroup, then the machine's RAM. More passes, the same snapshot. Measured: 2.7M names compiled inside a 128 MiB container (peak 125 MiB).
  3. List fetches stream to disk through the zstd encoder and a blake3 hasher with the same size, content and line checks as the buffered path; the peak is one block plus one chunk.
  4. Category lists are virtual: categories::expand makes cat-<source> lists on the effective configuration; they are never stored, are shared by URL, are excluded from the "every enabled list" default, and a bare entry named cat-* may set only mode. A file list with a source's URL provides it (no second download); an API-managed list with the ad tier's URL is adopted by Ad Block.
  5. A content change is an operator's decision. An agent token's PUT of content is 403 agent_not_allowed; an agent may dry-run it (a plan, always pending) and an operator's approval of the plan applies it. A heavy selection is refused to an agent at planning. An over-budget or heavy selection from a person returns 409 confirm_required and is repeated with ?confirm=true.
  6. A profile's sources are written in one transaction (ManagedKind::GroupSources), [filter] entry_budget and ads_tier are a managed settings kind, and a content change waits until every cluster member is 0.8.0 or later (members_too_old); replicas never download lists and read the category state from the primary.
  7. A device in two profiles gets the union, and the Groups page says so (owner decision, design section 12).
  8. Review fixes (2026-11-19). (a) "Set by file" for a group's content is read from the files' own group (set_by_file on the config entry), not from the entry's source: a group saved through the API has source override and the files' content still holds; the same content sent back is no change. (b) A sources write starts from the stored entry, else the files' group, never the effective one (adopt_ad_list makes a synthetic content that is never written back), and waits for members that can't read content like a group write. (c) A content change that does not raise the node's needed memory is allowed on a node that already refuses the selection (so it can be reduced). (d) A change to [filter] ads_tier gets the budget check (refused when it raises the need past the line; a warning when it passes entry_budget). (e) A meta-file URL with a % is refused (%2e%2e is a dot segment). (f) An agent can't add a list whose URL is a heavy catalog source. (g) Explain and the block reason name the category for a provider list too. (h) The profile editor checks the content and sources with dry runs before the first real write, writes the content only when it changed, and removes a new profile again if a later step fails. (c) A PUT /groups/{name} that leaves content out (or sends it unchanged) stores no content from the request: the backend keeps the one in the group's own entry, the files' when they set it, else the stored one, never the effective group's (an adopted ad list makes a synthetic content.ads, which is not written back); and a file's content wins over a stale stored copy on merge, so a later edit to the file takes effect. (d) A configuration write runs in its own task, so it runs to its end (the audit record included) when the client hangs up first, as a browser does on a reload right after Apply; it was stored-but-not-applied otherwise.
  9. Basic on a 128 MiB node is refused (Proposed, owner to decide). Measured with the corrected model (item 1): Basic needs 71 MiB there on four CPUs, 58 to 60 MiB on one, against a line of 64 MiB (half the memory, Q8). The conservative choice is to keep the 50 % line and refuse it. Two ways to let it pass, neither done: compile on one thread when the node may use 256 MiB or less (the measured 47 %), or raise the line to 55 % on such nodes. A version gate that reads 0.8.0-dev as 0.8.0 stays: a development build can't be told from a release of the same number.
  10. One [filter] settings kind (merge with T27.11, 2026-11-19). T27.11 (ADR-1006) added ManagedKind::Filter for refresh_secs and stale_after_days at /filter-settings/default while T24.29 had added the same kind for entry_budget and ads_tier. They are one kind: stored under filter, four keys (the earlier filter_settings store key of T24.29 is dropped: it was never released), written together because a write replaces the section, with one card on the Lists page (the second Settings editor is gone). entry_budget and ads_tier apply on a reload, so restart_only_changes ignores them; the refresh and stale settings still need a restart. No agent changes any of it (ADR-1006's rule covers the budget too).
  11. The UI bundle and the size gate (resolved 2026-11-19). With T24.29 the bundle is 416.3 KiB gzipped after the merge of the base; the owner's ADR-1020 sets the budget at 512 KiB, so npm run build passes. T24.29's share is about 13 KiB (the Categories view, the profile editor, the provider labels); the lazy pages stay split out of the main chunk.

Alternatives rejected

storing category lists in the configuration (duplicates the catalog and survives its removal); buffering a 40 MB source (the Pi's RSS budget); letting an agent apply a content change with approval off (a content filter is a household decision).

Consequences

the refusal rule is conservative: NRD 7 days is refused on a 128 MiB node though it compiled in 125 MiB, and Basic is refused there too (item 9). Test plan: flt_901_*, flt_902_*, clu_901_* and ui/tests/e2e/9-categories.spec.ts.

Builds on ADR-1006 ADR-1020 ADR-994 ADR-995

Referenced by ADR-1031

ADR-1018 A peer's streams are all listed, and it stays connected until the last one endsProposed 2026-11-18, T24.38CLUOwner report: after a rolling upgrade (replicas, then the primary) a replica showed reachableVoters 2 of 3 and a node connected=false link=inbound, and another replica kept moving between the primary and the first replica.

Context

Owner report: after a rolling upgrade (replicas, then the primary) a replica showed reachableVoters 2 of 3 and a node connected=false link=inbound, and another replica kept moving between the primary and the first replica. Reproduced in net_tests::voters_linked: replicas that fall back to each other while the primary restarts, and then move back to it, lose the voter link between them for good. Cause: a node pair can hold several streams (the main link a replica dials; the voter mesh's, dialed by the lower node ID, ADR-056; the one the peer dialed); the outbox kept one sender per peer (a newer stream replaced an older one's), and any stream's end set the peer connected = false and purged the outbox, though another stream was open. The mesh does not redial while its stream task runs, so the open stream stayed unlisted and uncounted.

Decision

  1. Streams are listed side by side. The outbox holds every open stream to a peer, newest last; a stream's entry leaves only when that stream ends (a guard dropped with the task, so a cancelled task counts); RPCs (votes included) go out on the newest open one.
  2. connected means at least one open stream. Streams are counted from the first frame the cluster accepts (a Hello; a peer refused at Hello is not a link that dropped) to their end by a drop guard (a main link left by primary_is_back is a cancelled read and used to run no clean-up at all). The peer is marked disconnected, a disconnected event written and a link drop counted only when the last stream ends.
  3. Replica-to-replica links are not only for fallback. Every eligible voter keeps a link to every other (ADR-056's mesh), independent of a replica's main link: moving the main link between the primary and another replica never drops the voter link, and elections do not depend on which replica a replica is attached to. When the primary dies, the survivors vote over those links (tested: a survivor is elected within the lease time after the restarts, and neither moves its main link afterwards).
  4. Say so on the page. A voter whose link dropped three or more times in ten minutes while both processes stayed up is listed in failover.unstableVoters; the Cluster page shows a warning on the Failover line, the Health tab a failing voter_links check with a fix, and the help topic voter-links explains it. The end of a main link is logged at info with its duration and reason.
  5. One drop is not a detour. A main link to the primary that was up more than 3 s and ended is redialed to the primary's URLs first after a short wait; a replica is tried only if that fails (a primary host that is powered off can cost up to the 10 s connect timeout per URL first; only config sync waits). Only the main link owns the main-link record, and link-drop records older than an hour (and a removed node's) are forgotten.
  6. A restart is not a flapping link (amended 2026-11-18 after the cluster3 run of the integration branch: a rolling restart counted three drops of one voter and raised the warning for ten minutes). Every Hello carries instance (protobuf tag 13), a random id of the sending process made at start. A drop is held until the peer's next Hello: the same instance settles it (counted, the link failed while both processes ran), another one forgets it (the peer restarted, was upgraded or shut down gracefully). A drop the peer hasn't come back from counts until it does (conservative: a peer that is down is not proven to have restarted). This node's own restart starts its log empty, and its peers see it come back as another process. Compatibility: prost ignores the unknown tag, so an older peer is unaffected; an older peer sends "" each time, so its drops count as before (a restart is one drop); "" to an id, or an id to "", is an upgrade or a downgrade and is forgotten like a restart.

Alternatives rejected

forbidding a replica to fall back to another replica (it is how a replica keeps following the cluster while the primary is restarting, CLU-001, issue #4); one stream per pair, with the second refused (a stream the peer dialed would be refused by the node that needs it, and the two directions would need a tie-break on every restart); healing by redialing the mesh on a timer (hides the defect and leaves connected wrong). Open (for the owner): the replica's cycle's mechanism (one end of the main link, then a detour through a replica) is fixed by decision 5 (a test-only counter of dials to a non-primary shows the detour and the test fails without the redial), but that is a mechanism, not the cause; what ends the main link to the primary every 1 to 2 minutes is still unknown (T24.38a). The main link ended info lines are meant to show it. The threshold (3 drops in 10 minutes) is a conservative guess.

Test plan

see T24.38 in spec/10; decision 6: clu_005_t24_38_a_restarted_peer_is_not_an_unstable_link, clu_005_t24_38_three_drops_of_a_live_peer_are_an_unstable_link, and cluster3 step k's unstableVoters check after its rolling restart.

Consequences

a few lines of bookkeeping on the cluster port, none on the query path; a new read-only field (unstableVoters), one Hello field (instance), one check id (voter_links), one help topic. No dependency.

Requirements CLU-001

Builds on ADR-056

ADR-1019 A primary promoted from an older primary's version adopts what it serves; until it has, it refuses writes that would drop itAccepted 2026-11-18CLUSeen on a three-node test cluster after upgrading every node to a new build.

Context

Seen on a three-node test cluster after upgrading every node to a new build. node-b was primary and applied a Pi-hole import through the API (over a hundred rows of several kinds). After failovers node-c was primary, promoted from replica while every node ran a build without ADR-1016, so the blob it inherited has no rows of the shared kinds. node-c held 0 rows and served every entry from the last applied cluster version, and a dry-run write of one of them answered before: null. The cause: ADR-1016's adoption (managed_adopt::adopt) adopts what the inherited blob lists; a blob without the rows adopts nothing, so managed_base() answered None and plan_files() fell back to the node's config files. Every write's candidate is merge(plan_files, entries), so the first real write would have published the files plus that one entry and dropped all the others from live DNS. ADR-1016 point 5 took that case for "the old primary didn't hand its entries over: say so with 409" and left the entries served but unowned; that is the state node-c was in, and it stays in it for as long as the node is primary.

Decision

  1. Adopt what is served. A node that is primary after a promotion from replica (it has applied a cluster version), whose inherited version has no rows of the shared kinds (a blob without managed: true, or no blob at all), derives the entries of that version that its own files do not define, in managed_adopt::derive, and stores them as its own rows: once, in one transaction, with the marker served:<blob hash or none>:<seq> in meta written in the same transaction (State::insert_missing_managed_noted), updated_by adopted:<seq>. One info line says the counts by kind. The derived kinds are the ones ADR-1016 publishes: upstreams, upstream groups, lists, groups, devices, local names (one row per name, its records together), forwards (rebuilt from the route, the forward:<domain> group and its upstreams; a stub zone keeps stub), quick rules, alert destinations and rules, schedules, anomaly mutes, routers, Kubernetes map rules, and the sections the API replaces whole (ratelimit, exclusions, simulate, map, rollout, special, local, clients, discovery) when the version's section differs from the files'.
  2. When. In the same place as ADR-1016's adoption (replication::adopt_shared, run by every reload and every publish tick on a primary), so it happens at promotion and at startup for a node that is already primary in this state (node-c in that cluster), without a second code path. The marker and a per-process cache make every later call a no-op; a node that follows a primary again forgets the marker (forget), as ADR-1016 does.
  3. What stays. An entry the node's own files define stays a file entry (the conservative reading: the version cannot tell the old primary's file from an API override of it). A row the node already holds is kept as it is (the node's own row wins), and node_only rows are not touched (they are neither derived nor deleted). Nothing is deleted. The version the node builds on loses the derived names and the held rows' names (managed_adopt::strip, as ADR-1016), so an edit is the edit and a delete stays deleted, after a restart too (the derived names come from the inherited version, which does not change while the node is primary).
  4. A write never drops what is served. A promoted primary that cannot adopt (its state.db can't be written, or the version can't be read) answers 409 to every managed write, dry runs and the Pi-hole import included, when its served configuration has entries its files do not define and it does not hold: "this node serves N entries ... that it does not hold as its own yet, so a change now would drop them from DNS". Nothing is changed. A node with nothing to lose (or one that is not a promoted primary) is not affected. This replaces the bare 404 of the old fallback and ADR-1016 point 5's 409 text for the adoptable case.
  5. Publishing. The adopted rows are rows, so the primary's next blob carries them with the shared kinds (ADR-1016), and a later failover keeps them.

Known limits

an entry the old primary's API overrode in a name this node's files also define (for example the default upstream group the Pi-hole import replaces) stays the version's own entry on this node (point 3), not a row: it keeps being served, but deleting an upstream it lists is refused by validation until the group is edited (an edit stores an override, as ADR-069). If the cluster's files and this node's files define different entries, the differing ones are adopted as rows (they are what is served). Sections derived by comparison (special, ratelimit, ...) become rows even when the old primary's files, not its API, set them; the files of this node still win field by field for special, local, clients and discovery (ADR-914).

Alternatives rejected

keeping the files as the base and publishing the files plus the new entry (drops the rest, the finding above); refusing all writes on such a node until an operator re-imports (the entries are in the node's own version; asking the owner to redo an import is worse than adopting them); adopting every served entry including the ones the files define (would turn the node's own file entries into rows that can then be hidden or drift from the file).

Consequences

DNS is unaffected (adoption is on the reload path, not the query path, and a failure leaves the node serving what it served); the first write after an upgrade works with no operator step; a cluster whose first failover after the upgrade comes from this state now hands the entries over (the rows publish). CLU-004 holds: a store that can't be written leaves the node serving the inherited version and refusing writes, not dropping entries.

Test plan

clu_015_t24_40_a_promoted_replicas_dry_run_sees_the_served_entry, clu_015_t24_40_every_kind_is_adopted_and_the_files_entries_stay, clu_015_t24_40_edit_and_delete_stick_across_a_restart, clu_015_t24_40_a_primary_at_startup_adopts, clu_015_t24_40_a_version_without_a_blob_is_adopted_too, clu_015_t24_40_a_write_is_refused_until_the_entries_are_adopted, clu_015_t24_40_a_standalone_node_is_not_affected, clu_015_t24_40_insert_missing_keeps_own_rows_and_runs_once; deploy/cluster3/e2e.sh step j (older image, then upgraded). Review amendments (2026-11-18): (a) the publish loop adopts on the real merged base (managed_base_state), never on an empty config; (b) the names a served-version adoption derived are stored in meta (managed-adopted-names:<key>) and are the ones stripped after a restart, whatever the files derive to then; (c) derive leaves out an entry holding a credential, a path to one, or a router file path (ADR-921): it stays in the version, is logged, and is not stripped; (d) the whole candidate (stripped version plus held and derived rows) is merged on a scratch store before anything is inserted: if it does not merge, nothing is adopted and writes are refused (409). Tests: clu_015_t24_40_the_publish_loop_adopting_first_loses_nothing_after_a_restart, ..._the_adopted_names_are_remembered_not_rederived, ..._credentials_are_not_copied_into_rows, ..._a_row_that_would_not_merge_blocks_the_adoption. Amendment (2026-11-18, merge with the M27 settings kinds): the shared kinds T27.5, T27.7 and T27.11 added to SHARED_KINDS are adopted too: zone (by apex as the API names it, trimmed, no final dot, lower case; a zone the files define, or one read from a zone file, stays in the version), and the singleton sections dnssec, filter, drill, slo, probe and upstream_check, each only when the served section differs from the files' in a field the API edits (settings_kinds::keys), as for special, local, clients and discovery. Stripping one of those rows gives back the files' values of the API's fields only; a field only the files set ([dnssec] trust_anchors_file, aggressive_nsec, [filter] fetch_concurrency, [drill] hour, ...) stays as served, since it is never in a row. A probe target with a user or password in its URL is a credential: the section stays in the version. The node-managed kinds (cache, support, updates, anomaly_settings, qlog_settings, metrics_settings, and the older oidc_provider, sink, otlp) are never adopted: they are not in the shared version. Forwards carry their T27.7 route fields (match_group, match_qtype, dnssec_nta), and a node_only route is not adopted. refuse_unadopted counts what derive finds, so it covers the new kinds. managed_adopt::ADOPTED_KINDS lists the adopted kinds and NOT_ADOPTED the shared kinds that need no adoption, with a reason (none today); clu_015_t24_40_every_shared_kind_is_adopted_or_exempt fails when a shared kind is in neither, and clu_015_t24_40_derive_covers_every_adopted_kind when derive misses one. Tests: ..._tuning_sections_are_adopted_when_they_differ, ..._tuning_sections_strip_and_merge_back, ..._zones_are_adopted_by_apex, ..._a_probe_target_with_a_password_is_not_adopted.

Requirements CLU-004

Builds on ADR-069 ADR-1016 ADR-914 ADR-921

Referenced by ADR-1016 ADR-1063

ADR-1020 The web UI's size budget is 512 KiB gzippedAccepted 2026-11-18APIspec/07 §3 and API-005 set the web UI's budget at 400 KiB gzipped in total, enforced by ui/scripts/postbuild.mjs and the Playwright test `obs_901 ...

Context

spec/07 §3 and API-005 set the web UI's budget at 400 KiB gzipped in total, enforced by ui/scripts/postbuild.mjs and the Playwright test obs_901 ... dist at most ... gzipped. On 2026-11-18 the merge of the M27 settings branches (T27.2/T27.11 cache, support and update settings; T27.5/T27.7 tuning and zones) on top of the SNMP poller (T25.6) and the map settings (T26.6) brought the build to 402.9 KiB (each branch alone fit). The largest pieces are the main chunk (335.7 KiB: help topics about 42.7 KiB, uPlot about 32.4 KiB), the brand icons (36.3 KiB) and the CSS (18.2 KiB). Map-world (T26.4/T26.5), categories (T24.29) and the site exceptions (T24.39) each add a few KiB. Better gzip settings saved nothing; a zopfli-class encoder would save 3 to 5 % once; cutting features or moving help topics out of the bundle costs a wave and the next feature reopens it.

Decision (owner, 2026-11-18): the budget is 512 KiB gzipped in total. The per-chunk caps stay as they are (the map chunk at most 30 KiB, lazy pages split out of the main chunk), the main bundle still carries no page-only code, and every task still records its size delta. The image gate (25 MiB per architecture, ADR-916) and the RSS budgets are unchanged: the bundle is embedded gzipped, so 112 KiB more is under 0.5 % of the image gate.

Consequences

the build and obs_901 check 512 KiB; spec/02 and spec/07 say so. A first page load on a Pi-served LAN grows by a few milliseconds at most. When the UI nears 512 KiB, the next step is to load help topics from the API on demand and to split the brand icons, not another raise without an ADR.

Requirements API-005

Builds on ADR-916

Referenced by ADR-1017 ADR-1030 ADR-1041

ADR-1021 CMDB replication uses its own fetch RPC, not ADR-917's secret writerAccepted 2026-11-19, T31.2T31.2 step 1 asked whether the ADR-917 replication code takes a non-secret writer for the authored tables.

Context

T31.2 step 1 asked whether the ADR-917 replication code takes a non-secret writer for the authored tables. It is built around the secret store's rows and its encryption envelope; reusing it would couple the CMDB's schema to the credential path.

Decision

the fallback of ADR-1005 §6 applies. The authored tables (ci, ci_key, pin, alias, port_alias, tomb) carry a stamp (epoch, seq) and are replicated by a pull: a standby asks the node that runs the CMDB with the cluster RPC cmdb.fetch (pages of rows after its own head, bounded by rows and bytes) and imports them with the stamp rules (newer stamp wins; a tombstone at least as new suppresses a row). Derived tables (record, seen, addr, proposal) stay node-local and are rebuilt by whichever node is designated. A newly designated node promotes its replica and always starts a new epoch above its own and the standby's (also with no standby file, so its stamps sort above every other standby's head). A standby takes only the designated node's answer (the node [discovery] node names, else the primary). Tombstones are kept by count (the newest 200,000), not by a window of sequence numbers (every flush stamps thousands of ci_seen rows, so such a window covers hours); the writer sends the stamp of the newest tombstone it swept (the floor) and a standby whose head is behind it empties its copy and fetches from nothing, so a deletion is never missed. The RPC is read-only, voters and members only, and a failure never touches DNS.

Alternatives rejected

extending ADR-917's writer (couples two schemas; its envelope is for secrets); replicating derived tables (a standby would carry stale last_seen and doubled write volume).

Consequences

one RPC name, one pull task. Tests: replication::tests (export, import, tombstones, the floor and the reset, promote, a new epoch with no standby file). Open: none.

Builds on ADR-1005 ADR-917

ADR-1022 CMDB resolution is a pure, order-independent union-find with compatibility checksAccepted 2026-11-19, T31.2ADR-1004 lists rules R1 to R5 but not how conflicting evidence combines.

Context

ADR-1004 lists rules R1 to R5 but not how conflicting evidence combines.

Decision

resolve takes the evidence in canonical order and builds groups by union-find over R1 (manual pins), R2 (MAC), R3 (serial) and R4 (stable device key: Home Assistant device id, the SNMP agent's own device key (one per agent, shared by its interfaces' MACs; the agent's chassis id is not read), UniFi infrastructure device id; never a UniFi client _id). A join is refused when it would put two different serials, two keys of the same scope, or a pinned group and an unpinned one in one group; the refused join becomes a merge proposal (also for a MAC and serial that point at different devices). R5 (hostname plus network) only proposes, and looks at the whole group of devices that hold the pair: exactly two propose a merge, three or more propose nothing (and end a proposal an earlier, smaller group raised); devices whose records hold different serials do not propose (serials read from the records, not from the key table, which keeps a key a device once held). A pinned interface's MAC claims only that MAC. Keyless records attach by a class 1 to 3 address binding or become an unconfirmed CI, and re-attach when their device splits. The per-CI cap of 8 records is counted at the CI's own level. The result does not depend on batch order (property test dsc_903_any_order_gives_the_same_links, which generates MACs, serials, device keys, host names and networks, and found five order-dependent cases, all fixed).

Consequences

deterministic ids need no ordering guarantee from sources. Open: none.

Builds on ADR-1004

ADR-1023 The CMDB engine is stateless over SQLite with a compact index; measured memory and diskAccepted 2026-11-19, T31.2the first design held every record in a map: 14 MiB at the caps against the 8 MiB budget (AC 5).

Context

the first design held every record in a map: 14 MiB at the caps against the 8 MiB budget (AC 5).

Decision

the engine probes the database by (source, key) and a content hash, and keeps only a compact open-addressing table (compact::Table, u64 key to the times it needs) for batched last_seen flushes. Row writes happen only for changed records; meta seq is written only when a row is stamped. Eviction and retention run in bounded steps. Measured at the caps (65,536 records, 16,384 CIs, RssAnon, two runs) with representative records (about 12 attributes and 500 bytes of JSON: addresses, names, a VLAN, the network, access point, port, LLDP neighbours, model, firmware, role), the review's correction of a first measurement that used about 100-byte records: +7.1 MiB RSS after a bulk load (limit 8), +4.0 MiB after a restart, the engine keeps about 2.7 MiB, 57.7 MiB on disk (limit 64), 0 rows rewritten in three unchanged cycles. With those records the first design needed 82 MiB and 9.3 MiB, so: a per-record byte cap (2 KiB of attributes, the largest non-identity attribute goes first); attributes stored zstd-compressed with a raw primer of the names every record repeats (no training; text that did not shrink, and rows from before, stay plain); a 16 KiB page for a new file; a batch is ingested 128 records at a time, each part its own transaction, so a router with thousands of clients costs memory by the part and not by its size. The search q therefore matches the CI name, ids, keys, host names and addresses, not the free text of every attribute. The synthetic values repeat more than real ones: the disk figure is a measurement, not a bound, and the cap bounds the worst case. The write-volume test on a stable network writes only changed records and the batched flush.

Consequences

query path unchanged; no hot-path crate touched. Open: none.

ADR-1024 T31.2 adapter and feed conventions, defaults and deviationsAccepted 2026-11-19, T31.2

Decision

(1) Every source pushes SourceBatches into a bounded sink that drops the oldest on overflow (counted); a command queue carries manual changes and an immediate tick when the configuration changes. (2) The in-process feeds (observations, leases, configuration, cluster, networks, queries once a minute, workloads when Kubernetes is on) are adapters read on the CMDB thread. (3) Settings kind Cmdb is shared, admin-only and has no agent scope; the CMDB runs on the node [discovery] designates and enabled is a validation error at privacy level 2 and above (names hashed at level 1). (4) No Pi-hole importer source (owner, 2026-11-19). (5) DSC-901: no policy, matching, identify or DNS naming code reads a CMDB value (dsc_901_no_policy_code_reads_the_cmdb). (6) Health reasons for the CMDB never mark DNS unhealthy.

Deviations

Federated delegates the CMDB reads and writes to the local backend, so a node that does not run the CMDB answers 503 naming the designated node; that differs from ADR-1005 sections 6 and 11 (any node answers) and stays Open until T31.5 step 4, which forwards them. Retention uses the ADR-924 constants (derived-only records 7 days, imports 30) because [discovery] has no retention_days setting for ADR-1005 section 5 to read; adding one is a config change for the owner. The passphrase-only backup of authored data (ADR-1005 section 7) is not built (T31.6 step 6). With no node named, the CMDB and the inventory follow the cluster's primary: a watcher re-runs their reconcile within 10 s of a change. The learning and mac_is_randomized helpers are kept for T31.4's detector. Promotion (reconcile_cmdb) always starts a new epoch, so the epoch rises on every restart or reload; harmless, as epochs only order replication. The failover watcher has no automated test yet (needs a multi-node harness; the three-node test covers it). A standby resync resets at most once per pass. At privacy level 1 a search matches only mac, serial and devkey keys, since other key values (config client keys, k8s natural keys) can hold names. A full -p wrendns --bin wrendns run can exit 70 (the watchdog restart status) under heavy CPU load without a failing test; tracked as a flaky-under-load item.

Open

none.

Requirements DSC-901

Builds on ADR-1005 ADR-924

ADR-1025 A replica shows the primary's router data, read through the clusterAccepted 2026-11-19APICLUT24.41 (owner report, a 3-node cluster).

Context

T24.41 (owner report, a 3-node cluster). ADR-903 section 1 says a router with a stored credential is read by the primary only, and ADR-125 says a replica gets its names through the peer leases. That left the replica's Networks page without the router's networks (it listed its own interfaces), the network drawer without devices, and the Routers page with "Not read on this node (the primary)", 0 devices and no last read. The spec says (API-013, T22.2) that the networks are read where the routers are read, but the federated backend did not do that. A browser can land on any node behind the VIP, so the three nodes must show the same router data.

Decision (the most conservative option, no spec text contradicted):

  1. A new federated read, router_view, answered by the node that reads the routers: its router networks (source router), its router clients (source router) and each router's status. Results only: no credential, no secret value, and the status already carried only a state, a time, counts and an error message with the address's password removed (API-014).
  2. A replica asks its reachable primary (not every peer: a replica that reads a router itself keeps its own rows, and resolver pods read none). It merges: its own router rows first, then the primary's rows for subnets or addresses it has none for, then its own non-router rows (the networks it is directly on, a group's networks, its mDNS names) for subnets and addresses no router reported. A replica's status of a router is replaced by the primary's only when the replica itself skipped the router as "the primary's" (polledBy "the primary"); the status then carries readBy, the primary's node label, so the page can say who read it.
  3. A primary that cannot answer (away, a stream that times out within the federated 2 s deadline, or an older build that does not know the read: N-1) leaves the replica's own answer and is recorded as a missing node (missingNodes), so the UI shows a note. It is never an error and never blocks anything else (CLU-004). Nothing is polled from a replica, and no credential or secret travels.
  4. The API additions are RouterStatus.readBy and RouterList.missingNodes, both optional and omitted when empty (a client that does not know them is unaffected).
  5. Not changed: the group list's Source column and the category picker (T24.29) still use this node's own networks (T24.41, Open).

Consequences

the three nodes show the same networks and router state, with the replica's own interface rows added. A page load on a replica makes up to three small reads of the primary (one per call: networks, leases, routers), each bounded by 2 s. Nothing is added to the DNS path. A cluster with an older primary behaves as before, with a note.

Test plan

api_013_a_replica_shows_the_primarys_router_data, api_013_a_replica_answers_without_the_primarys_router_data, api_013_replica_networks_are_the_primarys_plus_its_own, api_013_own_router_rows_win, api_010_replica_leases_merge, api_016_replica_shows_the_primarys_router_status, clu_002_router_view_wire_form; Playwright api_013 a replica shows the primary router networks... and api_016 a replica shows the primary status of a router; deploy/cluster3/e2e.sh step e2.

Requirements API-013 API-014 CLU-004

Builds on ADR-125 ADR-903

ADR-1026 The fork goes its own way: no more upstream syncs, a watch for fixes only, its own name before any public releaseAccepted 2026-11-19, owner decisionOn 2026-11-19 the fork was 612 commits ahead of paimonsoror/telltaledns and 80 behind since the last shared commit (095b77f, 2026-11-17): about 198,000 lines added in 566 files against upstream's 8,600 in 69, its own milestones M22 to M32 and about 120 fork ADRs.

Context

On 2026-11-19 the fork was 612 commits ahead of paimonsoror/telltaledns and 80 behind since the last shared commit (095b77f, 2026-11-17): about 198,000 lines added in 566 files against upstream's 8,600 in 69, its own milestones M22 to M32 and about 120 fork ADRs. Each sync cost hours of conflict resolution. Upstream is dual-licensed Apache-2.0 or MIT, which permits a permanent independent fork; neither licence grants use of the project's name (Apache-2.0 section 6).

Decision (the owner, through AskUserQuestion):

  1. Independent, with a watch for fixes. No more full upstream merges; spec/upstream.md's sync procedure is retired. The daily upstream watch stays, but only to find security and bug fixes in code the fork still shares; such a fix is ported by cherry-pick or by hand on its own branch, citing the upstream commit. Upstream ADR and task numbers already taken keep their meaning; new work uses the fork's numbering only.
  2. Licence. The fork keeps both licence texts and the upstream copyright line; fork additions may carry their own. Distribution uses the MIT option or keeps Apache-2.0's notices, whichever the release says.
  3. Name. TelltaleDNS stays the name internally for now. A new name, and the rename of the binary, paths, images, units, docs and site, is its own task, done before anything is published (spec/10 M33).
  4. GitHub. The repository leaves upstream's fork network (Settings, Danger Zone, Leave fork network; the owner's click). Because that drops every issue and comment, they were exported first to .github/issues-archive/ (29 issues, 27 comments, 12 labels) and are recreated in order afterwards so #1 to #29 keep their numbers, each comment noting its original author and date.

Addendum (owner, 2026-11-19): the name is WrenDNS, the website wrendns.com; the rename covers crates too and runs on a clean main after the open branches merge (spec/10 T33.2). The repository left the fork network the same day, and GitHub kept every issue.

Consequences

shared bugs are no longer reported upstream by comment unless the owner asks; the "Upstream watch" issue reports candidates for porting instead of a sync; the README's fork box says the project is independent.

Referenced by ADR-1028 ADR-1029 ADR-1034

ADR-1027 Every full member is shown for each stored secret, the same on every node; a member without a secret is a warning and a degraded reason, never a DNS faultAccepted 2026-11-19CLUThe owner's concern: "a single node containing a key/secret defeats the point of the cluster".

Context

The owner's concern: "a single node containing a key/secret defeats the point of the cluster". Secrets do replicate (ADR-903, ADR-917; each full member reads a stored router secret), but GET /api/v1/secrets listed only the members a node knew had applied it: the primary listed itself, each replica listed the primary and itself. It looked as if one node held the key.

Decision

  1. One list, asked of everyone. GET /api/v1/secrets on any node asks every other full member (the registry's members that are neither ephemeral nor witnesses, plus a live member the registry does not list but that reports itself primary) for its own SecretsStatus, the read a replica already makes of the primary (Read::SecretsStatus, N-1 safe: a member that errors or does not know it is unknown). The canonical rows (names, stamps) are the primary's (this node's own on the primary; this node's own marked stale when the primary does not answer). For each stored secret every full member is listed with the stamp it holds and a state: applied, unreadable, behind, ahead, missing or unknown. Only stamps and health cross the wire (the answer type has no value, ciphertext or hash). New optional fields: SecretNode.state, SecretNode.stamp, SecretsStatus.members, .missingNodes, .warnings.
  2. By design, not missing. A resolver pod (ephemeral) and a witness are listed under members as not_held; they never appear per secret and never raise a warning. A full member that did not answer is unknown and is named in missingNodes, not shown as missing.
  3. Warning and health. A full member that lacks a secret, holds an older one or cannot read it adds a line to warnings (shown on the Secrets page). The health reason secret_not_held (degraded, never severe) is raised for a full member whose applied secrets head differs from the primary's, or that cannot read a secret, for 60 s (a write reaches members in seconds; a short lapse is not reported), from the cluster view already collected (no extra read). The summary says DNS is unaffected, because it is: nothing on the answer path uses a stored secret (CLU-004).
  4. Internal callers never wait on the primary. Backend::groups_local() answers from this node only; the category group contents, the list-overlap preview and the support package use it, so an away primary no longer delays them by the router read's deadline. The user-facing GET /api/v1/groups still includes the primary's router networks in the Source column.
  5. A failed primary router read is cached for 5 s (as a good one is), so a page that makes several reads waits at most once while the primary is away.

Consequences

the list costs one small read per full member (each bounded by the federated 2 s deadline), only when the Secrets page or GET /api/v1/secrets asks. A cluster of older nodes shows them as unknown until upgraded, never as a failure. Nothing is added to the DNS path.

Test plan

api_015_t24_42_every_member_is_listed_with_what_it_holds, ..._the_list_is_the_same_on_every_node, ..._a_replica_lists_every_full_member (a real two-node cluster), ..._a_member_that_does_not_answer_is_unknown, api_015_t24_42_a_member_without_the_secrets_is_degraded, api_013_a_failed_primary_router_read_is_cached, api_013_internal_group_reads_never_wait_on_the_primary, api_013_no_known_primary_still_names_the_primary; Playwright api_015 secrets are shown held by every cluster member...; deploy/cluster3/e2e.sh step h (T24.42), ONLY=secrets.

Requirements CLU-004

Builds on ADR-903 ADR-917

ADR-1028 One release of old names: what keeps working across the rename, and what is kept spelled the old wayAccepted 2026-11-19, T33.2the owner decided (ADR-1026, spec/10 T33.2) that the old paths, environment variables, command, metrics and probe name keep working for one release, that nodes of different versions must keep working together during a rolling upgrade, and that no one is logged out and no token stops working.

Context

the owner decided (ADR-1026, spec/10 T33.2) that the old paths, environment variables, command, metrics and probe name keep working for one release, that nodes of different versions must keep working together during a rolling upgrade, and that no one is logged out and no token stops working. The decision does not say, for each name, which direction wins, what is written and what is only read, or which names are stored in files and so must never change. These are the choices.

Decision

  1. Read both, write the new one, unless a peer or a client of the old version needs the old one. TELLTALE_* variables are copied to WRENDNS_* at the top of main (wrendns_net::legacy_env, the one crate that may use unsafe, because set_var is unsafe in edition 2024) and then removed, so the rest of the program and every child process it starts see only the new names; the new name wins when both are set; each adoption prints a warning on stderr. The config file /etc/telltale/telltale.toml is read when /etc/wrendns/wrendns.toml does not exist; the data directory /var/lib/telltale is used when the setting is the default, the new directory does not exist and the old one does; /etc/telltale/secrets stays in the default secret_file_dirs. The command telltale is a link to wrendns (packages, images, the migration script) and prints a deprecation warning when started under that name.
  2. Wire names between nodes and to clients. The session cookie is set as wrendns_session; a request carrying telltale_session is read as the same session (the new name wins) and sign-out expires both, so no one is signed out. X-Telltale-Reason and X-Telltale-Client are read as well as the X-Wrendns-* headers, and wrendns ctl and the Home Assistant integration send both (the MCP server calls its own node's API in process, same version); responses with the backup headers carry both. The sign-in flow cookie is read in both forms. API token prefixes (tt_...), the join token prefix (tt_join_) and every protobuf or HTTP path did not contain the old name and did not change.
  3. Cluster certificates keep the old names this release, and accept both. A node that issues <id>.node.telltale.invalid and cluster.telltale.invalid can be verified by a node that has not been upgraded; one that issued the new names could not. So nothing issues the new names yet. peer_node_id reads either suffix, and the dialling side tries cluster.telltale.invalid, then cluster.wrendns.invalid, so a later release can switch issuance with no flag day. deploy/cluster3/e2e.sh check l rolls a cluster from an image built before the rename to the renamed one with DNS asked of every node throughout.
  4. What is stored in files keeps its spelling for good. The backup manifest's format (telltale-backup) and telltale_version field, the cryptographic labels (telltale secrets key-id v1, ... idempotency v1, ... aead v1, telltale-secret\x01, telltale-backup-secrets v2, telltale-backup-binding v1) and the audit chain's telltale-audit-v1 are inputs to hashes, keys and authenticated data: changing a letter would make every existing backup, secret and audit record unreadable. They carry // rebrand:keep (ADR-1029). A backup made before the rename restores on the new version.
  5. Metrics. /metrics writes every wrendns_* family and then a copy of each under telltale_* (wrendns_telemetry::legacy_metrics), for the Prometheus text form and the OpenMetrics form alike; the OTLP exporter and the support package use the new names only. The bundled Grafana dashboard, the SLO rules and the Helm chart's alerts use wrendns_*.
  6. The node's own probe. probe.wrendns.invalid is what listener probes ask; probe.telltale.invalid is still recognised (LEGACY_PROBE_NAME) so a node not yet upgraded keeps its probes out of the statistics. The name is one byte shorter, so the wire-format constant is not a text substitution: its length byte changed by hand.
  7. The Kubernetes label telltaledns.io/group is read as well as wrendns.com/group while [kubernetes] label is the default.
  8. Release files are published as wrendns-<arch>-linux and, for this release, as telltale-<arch>-linux (same bytes, both in the signed SHA256SUMS), because a binary of upstream's TelltaleDNS looks for the second. This fork's own old binaries do not benefit: their self-update reads https://github.com/paimonsoror/telltaledns/releases, so on a native install the upgrade is install.sh (which migrates), never the old self-update (review fix, T33.2).
  9. Native installs are moved by deploy/systemd/migrate-from-telltale.sh (dry run, idempotent, never merges two populated directories, keeps links from the old paths and the old command, renames the user and group in place so ownership holds, carries the unit and its drop-ins over). install.sh runs it. Helm upgrades in place only with nameOverride/fullnameOverride set to the old name (StatefulSet selectors are immutable); docs/running.md says so. The Home Assistant integration changes domain (telltale to wrendns) and so is a breaking change with migration steps (its changelog); it sends both header spellings.
  10. The window closes with the release after the rename. That release removes: the telltale link and warning, the old config/data/secret paths, legacy_env, the telltale_* metrics, the legacy headers and cookies, the legacy probe name and label, the old release file names, the cluster certificate fallback (after issuance moves to the new names, one release earlier), deploy/systemd/migrate-from-telltale.sh and deploy/cluster3/compose-prerename.yaml. Every one is in a file or line carrying rebrand:keep or named legacy*, so grep -r 'rebrand:keep\|legacy' is the removal list.

Consequences

a rolling upgrade works in both directions between the last release before the rename and the first after it; the cost is a duplicate metric set on /metrics (about twice the size of one scrape) and a handful of legacy* modules for one release.

Builds on ADR-1026 ADR-1029

Referenced by ADR-1029 ADR-1034 ADR-1049

ADR-1029 scripts/rebrand.py: the rename is a script, and the rule for what is historyAccepted 2026-11-19, T33.2two branches (the CMDB and the secret-members fix) merge into feat/ipam-integrations and then main before the rename lands, and more may follow, so a hand rename would conflict on every file.

Context

two branches (the CMDB and the secret-members fix) merge into feat/ipam-integrations and then main before the rename lands, and more may follow, so a hand rename would conflict on every file. The rename also has to keep some old spellings (the licences, upstream's copyright, the history of the project).

Decision

  1. The rename is scripts/rebrand.py, deterministic and idempotent (--check exits 1 while anything is left), with an ordered table of substitutions (RULES) and an explicit keep list. Its output is committed alone ("chore: rename TelltaleDNS to WrenDNS (generated by scripts/rebrand.py)"), then cargo fmt ("wrendns" is a letter shorter than "telltale"). To redo it after the base moves: merge the base, run the script, run cargo fmt --all, commit, then re-apply the hand-written commits (the compatibility code, the brand, the site). It renames file and directory names too, rewrites Cargo.lock and re-sorts it the way Cargo does, and never touches the git index.
  2. The history rule: current-tense prose and every identifier is renamed; a statement of what the project was called, and the records of the rename itself, are history and stay. In practice the keep list (KEEP_PATHS, KEEP_TOKENS, KEEP_SECTIONS, KEEP_LINE_REGEX) holds: the licence texts and the upstream copyright line (The TelltaleDNS Authors); every paimonsoror/telltaledns reference that is attribution (the repository, issues, commits, contributors); .github/issues-archive/, brand/, spec/upstream.md; the notes of published releases (deploy/release/notes/v0.1.0.md to v0.7.x); ADR-1026 and ADR-1028 to ADR-1030 and the T33.x task entries (they describe the rename with both names); the version-numbered sections of any CHANGELOG*.md; and the format identifiers of ADR-1028 (rebrand:keep on the line, or between rebrand:keep-start and rebrand:keep-end). The compatibility modules (crates/*/src/legacy*.rs, the migration script and its tests) are kept by path.
  3. The project's own artifacts move to the fork's owner, upstream's stay attribution. Upstream published ghcr.io/paimonsoror/telltale and never will publish wrendns; install and download URLs, raw files, image and chart names, the cosign identity, badges and paimonsoror.github.io/telltaledns (now wrendns.com) become nbacheller and wrendns.com. nbacheller/telltaledns, the GitHub repository's slug, stays until the owner renames the repository (which the task does not do): GitHub redirects the old URLs after that.
  4. The old product domains telltaledns.dev (problem type URIs) and telltaledns.io (the Kubernetes label prefix) become wrendns.com.
  5. Not text substitutions (done by hand after the script, ADR-1028): the probe name's length byte, the keep lines, and the fixtures signed with a throwaway key (crates/wrendns/testdata/*/make.py regenerates them: renaming a signed file breaks its signature).

Consequences

python3 scripts/rebrand.py --check can run in CI after the rename to catch a merged branch that brings the old name back (it is not wired in yet: the other branches are still to merge).

Builds on ADR-1026 ADR-1028 ADR-1030

Referenced by ADR-1028

ADR-1030 The brand in the product and on the siteAccepted 2026-11-19, T33.2, T33.3DOCbrand/ (the brand book, tokens.json, the logo files) was set by the owner on 2026-11-19.

Context

brand/ (the brand book, tokens.json, the logo files) was set by the owner on 2026-11-19. The rename's UI, README, Home Assistant and site work follow it; the book leaves open how a dense admin UI uses a scale made for pages, where fonts come from, and how a site that needs a payment link keeps no secret.

Decision

  1. Tokens as CSS variables, generated. ui/scripts/brand-css.mjs writes ui/src/brand.css and site/brand.py writes site/assets/brand.css from brand/tokens.json: Day on :root, Night under prefers-color-scheme: dark unless data-theme="light", and forced by data-theme="dark". npm run check and site/build.py --check fail when they are stale. The UI's own variable names (--bg, --surface, --accent...) are mapped onto the brand's in app.css, so no component changed its colours by hand; the sidebar is light (surface-raised, the current page sky-soft with sky-strong text) because the brand has no dark navy shell.
  2. Density. The app steps the heading scale down one level (page title h2, card title h3) and sets body text in body-sm, as the brand book says dense tables and side panels do; the site uses the full scale. Table headers use the label style in sentence case, not capitals.
  3. Type. Figtree and IBM Plex Mono from @fontsource-variable/figtree and @fontsource/ibm-plex-mono (exact versions pinned), the latin subset of the three files tokens.json lists, as woff2 (already compressed). Measured: the three files are 49,752 bytes; with the logo files (8.4 KiB gzipped) the the brand costs the UI 57.4 KiB gzipped (437.6 KiB to 495.0 KiB when measured; 508.6 KiB on the base of the day, which has since grown by itself): under the 512 KiB budget (ADR-1020) with 3.4 KiB to spare, so the next UI addition has to make room; the amd64 image (bench-fast, as the base) went from 17.28 MiB to 17.35 MiB compressed, under the 25 MiB gate (ADR-916). The site serves the same files from site/assets/fonts/ with both OFL licences; docs/third-party-notices.md lists them.
  4. Logos. The five files the UI and the site use are copied byte for byte from brand/logos/ and a check fails when a copy differs; the app icon is the favicon; Day and Night each have their own file and the theme picks one. The lockup is the logo in the header; the mark replaces it only where the sidebar narrows to icons; the wren is never an icon inside a page.
  5. Theme toggle. System, Day and Night in the header, kept per viewer in localStorage (wrendns.theme; the earlier theme key is read once and removed). Status colours always come with a word (Playwright checks every status badge on five pages); the warning and alert counts in the sidebar are tinted chips with a border, not saturated fills, because the brand has no on-warn colour.
  6. The tagline "Put a bird on it!" is on the site hero and the README banner only; no UI string uses it.
  7. The site moves to Azure Static Web Apps (Free) at wrendns.com (the owner's decision): .github/workflows/site.yml builds site/ and deploys site/_site with Azure/static-web-apps-deploy pinned to a full commit SHA and the secret AZURE_STATIC_WEB_APPS_API_TOKEN; without the secret it builds and checks and says it did not deploy. It replaces the GitHub Pages workflow, and DOC-001's text says so. site/staticwebapp.config.json sets a Content-Security-Policy with no inline script or style (script-src 'self'; style-src 'self'), Strict-Transport-Security, nosniff, a referrer policy and a permissions policy; site/build.py fails on any inline script, style attribute, event handler, external script, stylesheet or image, and on a policy that allows unsafe-inline. The coverage report under /coverage/ keeps a looser policy, because the report's HTML carries inline script and style.
  8. Donations are optional and hold no secret. The Download page lists every download (all free); its "Support WrenDNS" section, and the new Support page (help by email at support@wrendns.com, the issue tracker, the upgrade guide, and the same links), show the Stripe Payment Links in site/data/site.json: the one-time link where the donor chooses the amount and the monthly tiers ($3, $5, $10), each with its own button label. The links come from a Stripe account branded WrenDNS (spec/10 T33.3), so the checkout carries WrenDNS's branding. The pages with a gift say plainly that it is a payment to the for-profit company and not a tax-deductible donation; thanks.html is where the links return to, and /privacy and /terms are the drafts in docs/legal/ rendered by site/build.py (the [confirm] markers in the Markdown show highlighted until the owner and counsel settle them); every page's footer links Support, Privacy and Terms and says that WrenDNS is a product of MySummitKeep LLC. A section with no link is left out, and a build with no link at all still passes. The build accepts only https://buy.stripe.com/... and https://donate.stripe.com/... (the one-time link's host) and fails on anything shaped like a Stripe key, secret or webhook signing key anywhere under site/; support.note can say, in one plain sentence, what the Stripe page will show.
  9. Left for the owner: the Stripe account's own settings (branding colour #22609c, accent #16273a, the icon, the statement descriptor, the support URL https://www.wrendns.com/support, the receipts) are set in the Stripe dashboard, not here; the site cannot check them. The footer still says the licence is "Apache-2.0 OR MIT": T33.5 (ADR-1033) changes it with the licence.

Consequences

docs/releasing.md and the site's own pages are unchanged in structure; the site gained site/brand.py, site/test_site.py (22 checks), site/data/site.json, the Download, Support and Thank-you pages, site/staticwebapp.config.json and assets/fonts, assets/brand.

Requirements DOC-001

Builds on ADR-1020 ADR-1033 ADR-916

Referenced by ADR-1029 ADR-1041 ADR-1042

ADR-1031 The fork's memory gates: idle ≤ 32 MiB, loaded ≤ 128 MiB, resolver pods request 128 MiB and stay limited at 256 MiBAccepted 2026-11-19, owner decisionspec/00 §5's hard memory gates (idle with no lists ≤ 20 MiB; with 1M blocked names, 100k cache entries and telemetry ≤ 64 MiB) came from upstream.

Context

spec/00 §5's hard memory gates (idle with no lists ≤ 20 MiB; with 1M blocked names, 100k cache entries and telemetry ≤ 64 MiB) came from upstream. The fork has added the CMDB (now on by default, DSC-901 as amended), content categories (ADR-1017), the GeoIP build (ADR-1008), discovery workers and more; the shipped musl build measured 64.8 MiB at 10 s after the fill in the GeoIP gate set-up (60.0 MiB at 40 s in bench/gate.py), at the edge of the gate, and several ADRs (1008 (h), 1017 item 9) were bounded by a 128 MiB pod. The owner (2026-11-19): "The default memory cap was a restriction imposed by the upstream repo. I am ok relaxing it."

Decision

the gates become idle ≤ 32 MiB and loaded ≤ 128 MiB (the same set-up), still hard (bench/gate.py fails over them). The Helm chart's resolver pods request 128 MiB (the loaded gate) and keep their 256 MiB limit, so a transient such as a monthly GeoIP build (+35 MiB for a real-sized file, +78 MiB at twice the size) fits under the limit. The image gate (25 MiB, ADR-916), the hot-path rules and every other budget are unchanged, and memory stays a feature: a change that adds resident memory still reports its delta.

Consequences

ADR-1008 (h)'s residual (a twice-real-size GeoIP file over a 128 MiB pod) and ADR-1017 item 9's 128 MiB case are re-read against the new figures when their owner points are asked. The CMDB's default caps (T31.2 AC 5, T31.7) are sized against the 128 MiB gate.

Requirements DSC-901

Builds on ADR-1008 ADR-1017 ADR-916

Referenced by ADR-1047 ADR-1050 ADR-1063 ADR-1064

ADR-1032 Names are normalised once, where they enter: HTML entities decoded once, repaired once for what is already storedAccepted 2026-11-19, records the owner's decision 4 of docs/design/ui-technical-info.mdLive data showed a device named Alex&amp;#039;s PC.

Context

Live data showed a device named Alex&#039;s PC. Pi-hole's admin page stores comments escaped with PHP's htmlspecialchars, and the importer copied client.comment as given (one_line only replaced control characters). The web UI prints text literally, so the entity showed on screen. Routers, UniFi and Home Assistant can hand over names the same way. Decoding at display would be a second, different rule in every view (and the API and MCP output would still carry the codes); decoding where a name enters keeps one stored form.

Decision

  1. One helper, decoded exactly once. names::clean_text decodes the named entities &amp; &lt; &gt; &quot; &apos; and the numeric &#NN; and &#xNN; references once (what a reference decodes to is never decoded again: &amp;#039; becomes &#039;), then strips control characters (a tab or line break becomes a space) and trims. An unknown or malformed reference stays as written.
  2. Where it applies. The Pi-hole importer's human-text columns only: a client's comment, a group's name, an adlist's comment (and any list or domain comment it reads); never a domain or regex column. Router, UniFi, OPNsense and Home Assistant device and network names where they are read (first_name). Nothing else is decoded, and the UI never renders text as markup (a CI check fails on {@html}, innerHTML, outerHTML or insertAdjacentHTML in ui/src), so a decoded < is inert.
  3. Duplicates. Two devices that end with one name are told apart by the tail of their address, Laptop (1.21) for an IPv4 address (its last two octets), Laptop (ee:0f) for a MAC (its last two bytes), and only then by a number. The import's notes list every name that lost characters (a control character stripped, a ? or a U+FFFD in it).
  4. A one-off, automatic repair (the owner's decision 4). On the primary, shortly after start, a task finds the API-managed clients and groups whose stored name holds an entity and stores the decoded name in one configuration change: the groups, quick rules (devices and groups) and routes that name it follow it; a collision takes the tail suffix of rule 3. The change is audited once as names.repair by the system actor, listing each rename, and is published to the replicas as any write is. It runs once per database: a node-local meta note (names-repair-v1) is recorded in the same transaction as the write (or on its own when a pass finds nothing to do), and a database that has it is never decoded again, so a name typed after the upgrade (R&amp;D lab) and a name that keeps one layer (Double&#039;d) are left alone and a second pass or a restart writes nothing. The note is node-local, so a replica later promoted may run the pass once more over the replicated rows (accepted: they are already decoded). The rename follows every API-managed reference (rules, clients, forwards, zones, anomaly mutes, drill, Kubernetes map, log exclusions); it is skipped, and logged, when a file still names the device or group, when an agent token is limited to the group, or when the configuration does not validate before or after (an invalid configuration can't judge a rename, so none is made). Lists need none (a list's name is an ID of lowercase letters, digits, - and _ and holds no entity).
  5. Files are never rewritten. A name a configuration file defines that holds an entity (also an API override of that name) is reported: the node's health says so as degraded, names_in_files, naming the file; DNS is unaffected.

Consequences

a name already stored cleanly is never changed; a name that really contains &amp; as typed by a person is decoded too (an accepted loss, as the same text could not be told from an escaped one). The repair runs only on the primary and does nothing in a GitOps cluster or a pinned one. Nothing is added to the DNS path. No other fork ADR number is used by this track.

Test plan

api_007_t35_1_decode_entities_table (a double-escaped case among them), api_007_t35_1_clean_text_strips_controls_after_decoding, api_007_t35_1_import_decodes_names_and_tells_duplicates_apart, api_007_t35_1_import_leaves_domain_columns_alone, dsc_901_t35_1_router_and_ha_names_are_decoded_where_read, api_007_t35_1_repair_decodes_stored_names_and_what_names_them, api_007_t35_1_repair_is_idempotent_across_passes_and_restarts, api_007_t35_1_file_entries_are_reported_and_never_rewritten, api_007_t35_1_a_replica_sees_the_repaired_names, api_007_t35_1_the_task_repairs_and_reloads_the_node, and npm run check (check-no-html).

ADR-1033 WrenDNS is AGPL-3.0-or-later with a commercial licence from MySummitKeep, LLC; upstream's code keeps its MIT/Apache-2.0 noticesAccepted 2026-11-19, owner decision; counsel review before the first commercial saleThe owner (2026-11-19): "If we want to make this a copyleft, eventual commercial solution, what license is necessary?" and "commercial will matter, even if it is only donate at the moment." The repository is Apache-2.0 OR MIT, inherited from paimonsoror/telltaledns.

Context

The owner (2026-11-19): "If we want to make this a copyleft, eventual commercial solution, what license is necessary?" and "commercial will matter, even if it is only donate at the moment." The repository is Apache-2.0 OR MIT, inherited from paimonsoror/telltaledns. Both licences allow the fork's combined work to be released under a copyleft licence as long as upstream's copyright line and permission text are kept for the parts that came from upstream. Everything published before the change stays available under Apache-2.0 OR MIT (a grant that cannot be withdrawn). WrenDNS is a network service with a web UI, so GPL-3.0's distribution trigger would leave hosted use uncovered.

Decision

  1. Licence: from the commit that changes it (with the WrenDNS rename, before the first WrenDNS release), the repository is AGPL-3.0-or-later. LICENSE is the AGPL-3.0 text. A NOTICE names the copyright holder and credits upstream: TelltaleDNS by paimonsoror and its contributors, under MIT or Apache-2.0. Upstream's texts are kept as LICENSE-UPSTREAM-MIT and LICENSE-UPSTREAM-APACHE. Package metadata follows: Cargo.toml license = "AGPL-3.0-or-later", ui/package.json, the Helm chart, and SPDX headers on new files.
  2. Commercial licence: the copyright holder, MySummitKeep, LLC (confirmed by the owner 2026-11-19; the notices use this spelling), may license WrenDNS under other terms, for example to a company that cannot accept the AGPL's obligations. Until a commercial licence text exists, the README says to ask at support@wrendns.com. Donations through the WrenDNS Stripe account are unrelated to the licence and buy no rights.
  3. Contributions: outside contributions are accepted only under a CLA that grants MySummitKeep, LLC the right to relicense them (a CONTRIBUTING.md, the CLA text, and a CLA check on pull requests, which the owner installs). A DCO sign-off alone is not enough for dual licensing.
  4. Satellites: the Home Assistant integration and the browser extension stay Apache-2.0, so other projects and stores can adopt them; each carries its own LICENSE.
  5. Unchanged: the clean-room rule (AGENTS.md rule 6) still forbids code from Pi-hole, Technitium, AdGuard Home and any copyleft source. GPLv3 code would now be licence-compatible, but it would break the commercial licence. deny.toml allows only licences compatible with both the AGPL and a proprietary commercial licence: permissive licences, plus MPL-2.0 per file.
  6. Not legal advice. Two points go to counsel before the first commercial sale: whether the commercial licence is enforceable, and the copyright status of code written by agents under the owner's direction (the US Copyright Office does not register purely AI-generated material, so the owner's specifications, decisions and reviews are the human authorship).

Addendum (owner, 2026-11-19, T33.5): the baseline is published: the annotated tag permissive-final (commit 2e99850b) and its source-only GitHub release are the last Apache-2.0 OR MIT version, and the owner requested a Software Heritage save of the repository. The CLA check is the CLA Assistant Lite GitHub Action (.github/workflows/cla.yml, pinned to a commit), which needs no app install: signatures are comments on the pull request, recorded in signatures/cla.json on the cla-signatures branch. The owner makes the check required in branch protection.

Alternatives considered (owner, 2026-11-19): FSL (no competing use for 2 years per release, then Apache-2.0 or MIT), BSL 1.1 (a custom use grant, a change licence after up to 4 years) and Elastic License 2.0 (no hosted service by others, never open). All three are source-available rather than open source and not copyleft; distributions generally won't package them, and WrenDNS's audience and comparable projects (Pi-hole EUPL, AdGuard Home GPL-3.0, Technitium GPL-3.0) are open-source copyleft. The owner chose AGPL-3.0 with a commercial licence, and open core later: future paid parts (for example a hosted resolver service, M32) may be proprietary or FSL, kept apart from the AGPL code.

Consequences

the rebrand's replay adds the licence change as its own commit (T33.5). The README's licence section (T33.4) and the site state the licence and the commercial contact. The name is protected by a trademark filing and a trademark policy, not by the licence (owner action).

Referenced by ADR-1030 ADR-1035 ADR-1052 ADR-1055 ADR-1058 ADR-1071

ADR-1034 WrenDNS signs its releases with its own minisign keyAccepted 2026-11-19, owner step, OPS-004wrendns self-update, the daily update check and install.sh trust only releases whose SHA256SUMS and releases.json are signed with the key built into the binary.

Context

wrendns self-update, the daily update check and install.sh trust only releases whose SHA256SUMS and releases.json are signed with the key built into the binary. That key was upstream's (67268E600FE95612), and the fork never had its private half, so no WrenDNS release could be published (ADR-1026, T33.2).

Decision

  1. A new Ed25519 minisign key pair, key ID 4CBF504A8FBF5357, public key RWRXU7+PSlC/THqf7tUqrCWT0rNnxIU3Z+bxy85CoSNkTzYQzOa+qMln. The owner generated it in a throwaway container, so the private key never passed through an agent.
  2. The private key has no password, because the tag build signs without a prompt. It is held as the CI secret MINISIGN_SECRET_KEY, with an offline backup.
  3. The public half is in deploy/release/wrendns-release.pub, RELEASE_KEY in crates/wrendns/src/selfupdate.rs and PUBKEY_DEFAULT in deploy/systemd/install.sh. The test ops_004_release_key_is_the_same_in_all_three_places fails if they disagree.
  4. Nodes that still run an upstream TelltaleDNS build trust only upstream's key and cannot self-update to WrenDNS. They move by install.sh or the migration script (ADR-1028), which is the path the rename already requires.

Rotation

a new key means a new pair, updating the three places and the secret in one commit, and noting it in the release notes. Nodes on the old key are moved by install.sh, as in point 4.

Builds on ADR-1026 ADR-1028

Referenced by ADR-1062

ADR-1035 The SPDX header check covers source files added after permissive-final, and nothing olderAccepted 2026-11-19, T33.5ADR-1033 asks for SPDX headers on new files and a check, without saying which files are new, which kinds of file count, or what is exempt.

Context

ADR-1033 asks for SPDX headers on new files and a check, without saying which files are new, which kinds of file count, or what is exempt. Editing every existing file would touch most of the repository, mix the licence change into unrelated history, and blur which files upstream wrote.

Decision

  1. Scope: scripts/check-spdx.py checks the files that git diff --diff-filter=A -M90% permissive-final lists against the working tree (so a move, a file at least 90% like a deleted one, is not an addition; a file that only borrows from an old one is), plus untracked files git does not ignore, with the extensions .rs, .ts, .svelte, .py, .sh and .js. Files that existed at the tag are not edited: LICENSE and NOTICE cover them, and upstream's portions keep their notices.
  2. The header: SPDX-License-Identifier: AGPL-3.0-or-later within the first five lines, in the file's comment syntax (after a shebang where there is one).
  3. Exempt: generated files (a comment line among the first three that starts with @generated, GENERATED by or auto-generated, or says generated by ...; do not edit), vendored code (node_modules/, vendor/, third_party/), test data (testdata/, fixtures/), .github/issues-archive/, build output (site/_site/, ui/dist/), and integrations/home-assistant/, which is Apache-2.0 (ADR-1033 §4) and carries its own LICENSE.
  4. Where it runs: CI's site job (the cheap checks), with the full history (fetch-depth: 0) because it needs the tag; a clone without the tag gets an error that says so. scripts/test_check_spdx.py tests it in a throwaway repository.

Consequences

a contributor adding a source file adds one line; .mjs, .css, .html, .toml and other files are not checked (a later ADR can widen the list). A file copied from another project keeps its own licence line and is listed as third-party work (CONTRIBUTING.md, CLA §6). It goes under a vendor/ or third_party/ directory, which the check skips; anywhere else the check fails on it, so a reviewer sees it.

Builds on ADR-1033

ADR-1040 Group colours are the brand's flock, in configured orderAccepted 2026-11-19, T33.6, API-005, DOC-006the brand book (brand/README.md, Color) gives device groups flock-1 to flock-5 in a fixed order, then flock-other, and keeps flock colours away from status.

Context

the brand book (brand/README.md, Color) gives device groups flock-1 to flock-5 in a fixed order, then flock-other, and keeps flock colours away from status. The server filled in a group's colour from a ten-colour Tailwind cycle (#3b82f6, #22c55e...), default got a slate grey, and the UI took any colour as given; the chart series for local answers (--s-local) reused flock-3. The book does not say what a colour set in the configuration does.

Decision

  1. The server's automatic colour for a group without one is flock-1 to flock-5 (their Day values from brand/tokens.json) by the group's place among the configured groups, default not counted; the sixth group on, and default, take flock-other. A unit test checks the values against tokens.json. The API field and its meaning ("configured, or a stable pick") are unchanged.
  2. The UI shows the theme's own flock: a group whose colour is one of the flock's Day values is drawn with that token (var(--brand-flock-N)), so Night shows Night's value; a group with no colour takes the token for its place. ui/src/lib/flock.ts does this for every group chip, dot, card swatch and chart series.
  3. An explicit color in the configuration still wins as written (the conservative choice: a setting the operator chose is never dropped silently). The docs say it overrides the brand colour for that place, and the demo network no longer sets one.
  4. Not a flock colour for status: --s-local (answers from your own names) is sky, not flock-3.

Consequences

API clients (Grafana, Home Assistant) see the brand's colours for groups without one; a client that compared a group's colour to the old cycle sees new values.

Referenced by ADR-1043

ADR-1041 Icons: Lucide-style paths drawn in the app, no icon libraryAccepted 2026-11-19, T33.6, API-005, DOC-006the brand book recommends Lucide at 20px with a 1.75px stroke in ink or ink-muted, "a recommendation, not a bundled asset".

Context

the brand book recommends Lucide at 20px with a 1.75px stroke in ink or ink-muted, "a recommendation, not a bundled asset". The UI had its own Icon.svelte (18px default) and used Unicode symbols as icons in places (✕, ▸ ▾, ✓ ✗, ★, ▲ ▼, ⚠; ⚠ draws as a colour emoji on Windows). The UI is within 4 KiB of its 512 KiB budget (ADR-1020), and the lucide package would add far more than the dozen shapes used.

Decision

  1. No icon package. Icon.svelte keeps drawing Lucide-style single paths (24×24 viewBox, currentColor, 1.75 stroke). The pass added x, chevron-right, chevron-down, check, alert, star, up, down, and distinct icons for Routers, CMDB and Network inventory (each had borrowed another page's).
  2. Sizes: 20px by default (the sidebar, the header); 16px inline with body-sm text (status marks, the Picker's tick, drawers' list marks), 12px beside a percentage change, 14px in a chip's remove button. Every Unicode symbol used as an icon was replaced; "×" stays where it is the multiplication sign (×3).
  3. Notices' status icons (info, alert-triangle, circle-check) are CSS masks in app.css, coloured by the tone, so the about 140 notices gained an icon without touching their markup.
  4. The wren stays the logo only (ADR-1030 §4); no icon draws it.

Consequences

a new icon is a path added to Icon.svelte; if a custom set ships later it replaces the paths in one file.

Builds on ADR-1020 ADR-1030

Referenced by ADR-1042

ADR-1042 The brand book's gaps in a dense admin UI, filled conservativelyAccepted 2026-11-19, T33.6, API-005, DOC-006the T33.6 audit (27 findings) met cases the brand book leaves open.

Context

the T33.6 audit (27 findings) met cases the brand book leaves open. Each was settled with the most conservative choice consistent with the book and ADR-1030.

Decision

  1. Disabled controls (buttons, inputs, selects, the switch, Picker, menu items) are ink-muted text with a line edge on surface-raised, opacity 1 (including Chrome's own fade of a disabled select); rows and options that are off are muted text, not faded.
  2. Selected is sky-soft with sky-strong text everywhere: tabs, pressed filter chips, the Picker's active option, menus' hovered item, the Cluster page's selected row. A pressed segment in a segmented control stays surface-raised with a line-strong edge (no shadow).
  3. Notices are a whole line hairline on the tone's -soft tint (sky-soft for information) with the tone's status icon (ADR-1041 §3), never a coloured left border; card titles lost their accent bar; the health panel's reasons lead with their level's shape.
  4. The switch: off is an ink-muted knob on surface-raised with a line-strong edge; on is sky-strong with an on-sky-strong knob. (The audit suggested a surface-raised knob when off; on a sunken track that is under 3:1, so the knob takes ink-muted.)
  5. Overlays wash the page toward surface (a color-mix of the page colour) instead of a dark scrim, in both themes; drawers, menus and popovers take the one shadow, shadow-float. A drawer's panel holds focus without a ring (it is not a control; a ring along its edge read as a coloured border); its controls keep theirs.
  6. The Flow diagram's "WrenDNS decides" box is the identity tint, sky with on-sky text (sky-strong is for interaction only; ink failed in Night).
  7. No gradients: chart area fills are flat and translucent; the two hatch patterns (maintenance in the topology legend, no data in the heatmap) are stripes, not colour gradients, and are allowlisted (ADR-1043). Domain monograms use the brand's neutrals instead of a hashed hue per name (the hues reached browns and oranges, which the palette excludes); other brands' marks keep their own colours.
  8. Motion: one token, --motion: 160ms ease-out, for every transition; prefers-reduced-motion: reduce turns every transition and animation off (one global rule) and the Cluster page jumps instead of scrolling smoothly. The wall display's slow title fade (0.8 s) stays: it is a display, not the app, and it is off under reduced motion.
  9. Type and shape: drawers and help panels use Figtree body-sm (they set a system font); domains on the dashboard's top lists and the wall are IBM Plex Mono; text under 12px became 12px (except labels inside scaled SVGs); radii map to radius-sm (badges, chips, small panels), radius-md (buttons, inputs, cards) and radius-full (pills, toggles); the app's primitives (cards, buttons, inputs, tables, badges, the shell) are on the 4px space scale. Snapping every other off-scale padding in the pages (about 300 values) is left for later work.

Consequences

the UI bundle went from 508.5 KiB to 507.8 KiB gzipped: removing dead fallbacks, the gradient code and the hashed monogram colours paid for the icons and notices.

Builds on ADR-1030 ADR-1041 ADR-1043

Referenced by ADR-1043

ADR-1043 npm run check keeps the UI on-brandAccepted 2026-11-19, T33.6, API-005, DOC-006the brand pass fixed what the audit found; without a check the next change can bring a hard-coded colour, a removed focus ring or an exclamation mark back.

Context

the brand pass fixed what the audit found; without a check the next change can bring a hard-coded colour, a removed focus ring or an exclamation mark back.

Decision

  1. ui/scripts/check-brand.mjs runs in npm run check and fails on: a hard-coded colour (hex, rgb()/hsl()/oklch() and the like, or a named colour in a colour property or a var() fallback) outside the token files (src/brand.css generated from brand/tokens.json; app.css names only var()s); outline: none (or 0) in a file that draws no replacement focus style (var(--focus)); an emoji, or an exclamation mark ending a word, in a UI string (script string literals, markup text and quoted attribute values) or in docs/help/topics.json; a CSS or canvas gradient; and "Telltale" anywhere in ui/src, ui/index.html or the help topics. Comments are not UI and are skipped (except for the old name). The generated API types and other brands' marks (icons/brands.ts) are not checked.
  2. Exceptions go in ui/scripts/brand-allowlist.txt, one per line with the check, the file, text on the line and why; an entry nothing matches fails the check, so the list only holds live exceptions. It starts with five: another brand's mark's letter colour, the flock's Day values the server fills in (ADR-1040), the two hatch patterns, and the drawer panel's focus (ADR-1042 §5).
  3. Help topics are not loaded on demand in this pass: they are already their own lazy chunk, the budget counts every chunk, so splitting them further would not lower the measured total, and the pass ended under the budget without it.
  4. Playwright (9-zbrand.spec.ts) checks, in Day and Night: the 2px focus-ring, 2px outside, on a nav link, a segmented button, an icon button, a switch, a select, the search box, a tab and a primary button (3:1 against what is around it); every status badge on eight pages has a word, and each tone is its colour on its -soft tint at 4.5:1; disabled controls are ink-muted on a line edge at opacity 1, and no disabled control on the page is faded; reduced motion leaves nothing moving on four pages, and without it the switch moves in 160 ms ease-out.
  5. Review round 1 (T33.6): the outline check is per rule, not per file: an outline: none (or 0, 0px, outline-style/outline-width) passes only on a selector that a var(--focus) rule in the same file names a class or element of, or on :focus:not(:focus-visible), and never in an inline style. Three more checks: case (text-transform: uppercase, small caps), disabled (opacity below 1 on a :disabled/[disabled]/[aria-disabled] rule) and edge (a left border that isn't a 1px line-colour divider). Named colours are caught in SVG attributes, Svelte style: directives and canvas styles too. flock checks that the Day copies of the group colours (src/lib/flock.ts, the server's defaults) match brand/tokens.json. Playwright adds the SVG rings (a Flow band, a map node, a topology chip and pod: 2px of focus-ring covering 2px to 4px out, none on hover; in 1-ui and 7-map, which hold the mocked data) and the group colours in each theme.

Builds on ADR-1040 ADR-1042

Referenced by ADR-1042

ADR-1045 A Pushover alert destination: two secrets, https, no emergency priorityAccepted 2026-11-19, T24.43, owner requestAPICLUPi-hole's DHCP hook sent a Pushover message when a new device joined.

Context

Pi-hole's DHCP hook sent a Pushover message when a new device joined. Pi-hole is gone, and the owner wants the new_device alert delivered to Pushover. Pushover takes a form POST with an application token and a user (or group) key, both secrets.

Decision

  1. [[alerts.destination]] type = "pushover". url is optional and defaults to https://api.pushover.net/1/messages.json (an empty url is the default; url no longer has to be present in the file). A url set must be https://; http:// is accepted only to 127.0.0.1, localhost or [::1], for a test server. This is stricter than the other destinations (which accept http://) because the message carries two secrets.
  2. The application token uses the existing token_file / token_ref. The user or group key is a second credential, user_key_file / user_key_ref, held exactly as password_ref is: a row of STORED_FIELDS (alert_destination, user_key), listed by GET /api/v1/secrets with its users, replicated to every member (ADR-903, ADR-917), never shown again, admin only, and user_key_file an API path that holds a credential. Both are required for the type (a file or a reference each).
  3. Options: device (a Pushover device name), sound, priority_firing (default 0) and priority_resolved (default -1), each priority from -2 to 1. Priority 2 (emergency) needs retry and expire and repeats until acknowledged: not offered (conservative; a later ADR can add it).
  4. The form carries token, user, title (rule and subject, cut to 250 characters), message (the summary with the node and the time, cut to 1024 characters with an ellipsis, the node and time kept), priority, timestamp, device and sound when set, and url (a link to the device in the UI) only for a new_device alert on a node that has [auth.oidc] public_url: the node knows no other address of its UI, so without it the link is left out. A link over 512 characters is left out, not cut.
  5. A 4xx with Pushover's {"status":0,"errors":[...]} (or a 2xx with status 0) is a failed delivery; the deliveries list shows HTTP 400: <errors>, cut to 300 characters, with the token and the key replaced by <redacted>. Nothing is logged with a secret. Alerts never affect DNS (CLU-004).
  6. credential_redirected: a pushover destination holds credentials, so changing its url (or type, or dropping the url to Pushover's default) is an admin's, the existing rule (API-014), and raises the alert.

Consequences

the config schema, OpenAPI and api-types.ts gain the six fields and the pushover type; the support-bundle classify table lists the four string fields; one help topic (pushover) says where to find the two values. No new dependency; the image size is unchanged.

Requirements API-014 CLU-004

Builds on ADR-903 ADR-917

ADR-1047 WrenDNS Cloud's remote UI is an SNI-passthrough relay over an outbound HTTP/2 tunnel; the portal holds tenant objects onlyAccepted 2026-11-19, amended per the owner decisions on cloud writes; owner accepted all recommendations; #41, T36.1; revised after review the same dayCLUThe owner wants a hosted site that shows each tenant's nodes' UI from anywhere (#41, docs/design/hosted.md).

Context

The owner wants a hosted site that shows each tenant's nodes' UI from anywhere (#41, docs/design/hosted.md). Nodes sit behind NAT. The UI assumes it owns its host (base /, absolute /api/v1 calls, CSP connect-src 'self' and frame-ancestors 'none', per-node sessions and public_url, ADR-045), so a path-prefix proxy or an iframe breaks it. A cloud that terminates TLS would see session cookies, CSRF tokens, query-log pages and secrets typed into forms, against #41's rule that the hosted side is never trusted with more than the signed-in user's role. The broker writes the PROXY header, so whatever it says about a caller's address is the cloud's claim, not a fact.

Decision

  1. Every full member of a linked cluster (never a resolver pod or witness) dials one outbound tunnel: HTTP/2 over TLS to tunnel.<suffix>:443, mutually authenticated (ADR-1048). QUIC is added later as the preferred transport with HTTP/2 as the fallback. No new runtime crate (h2, hyper, rustls are linked).
  2. The broker routes each public TCP connection by its TLS SNI into the tunnel of the tenant that holds the name, as one HTTP/2 stream, without decrypting it. The stream starts with a PROXY v2 header (caller address, port, SNI). Control messages use ADR-044's length-prefixed prost frames on a control stream. Devices and nodes reach the broker at one stable edge address (ADR-1052), never at a VM's own address.
  3. Two trusted channels, nothing unsigned (amended 2026-11-19 by the owner decisions on cloud writes; it said "the tunnel is a socket, not an API ... no way to change a node's configuration"). Besides relayed streams and the certificates the node asked for, the tunnel carries (a) the user channel: cloud-originated changes to the node's everyday policy, each signed with the editor's change-signing passkey and verified, authorized and audited on the node (ADR-1061, ADR-1063), and the node's signed cloud view going up (ADR-1063 point 9), plus proposed changes, unsigned patches that the node only displays on its own signing page and that change nothing (ADR-1061 point 1, added after the security review of 2026-11-19); and (b) the platform channel: content signed by the content key and hints for actions the node's owner opted into (ADR-1062, ADR-1066). Neither can change guarded settings (ADR-1049 point 3), and nothing the cloud sends unsigned changes the node's configuration or starts anything on it.
  4. Relayed streams on the node:
    • injected in-process into the node's TLS acceptors with a "relayed" context flag, never as a socket; ADR-039's PROXY rule for sockets is unchanged;
    • always remote: never loopback, never break-glass (ADR-944), never inside allowed_admin_networks;
    • the PROXY address never authorizes: a relayed stream never matches an IP or MAC client rule (ADR-976), a wall display's network binding or [access] allowed_networks; its device is the one its key or label names;
    • a PROXY address that is private, loopback, link-local, RFC 6598 or in the tenant's own LAN ranges is refused and counted;
    • the address is used for rate limits, lockout, the audit log and the query log (marked as reported by the relay), with the relay correlation ID; step-up lockout is also per account (10 failures in 15 minutes lock that account's relayed sign-in for 15 minutes);
    • refused unless an admin opts in (guarded settings): local password, HTTP Basic, the setup token, sessions created on the LAN, secret writes, guarded settings, backups, user and token management and the [cloud] settings. Remote MCP is off by default. Admin and guarded work over hosted names has the further conditions of ADR-1049 point 3.
  5. Heartbeats every 20 s carry {node_id, cluster_id, role, epoch, ready, version, maintenance}, and the primary's carries a signed lease (ADR-1048 point 6); reconnect uses full-jitter backoff from 1 s to 5 min.
  6. Stream budgets: up to 128 DNS streams with 4–16 KiB windows and up to 32 UI, API and MCP streams with 64–256 KiB windows, 1 MiB frames; a stream past its budget is refused with a counted reason. RSS targets +2 MiB idle and +12 MiB with both budgets full, measured against ADR-1031; tier device limits are derived from the measurement.
  7. <slug>.<suffix> routes primary first and sticky (the member with a valid lease confirmed by a majority of the tenant's tunnels, else the lowest-ID ready replica; re-routed only on disconnect, unready, maintenance or a new lease), and <node>.<slug>.<suffix> always reaches that node.
  8. The portal (dns.wrendns.com) holds tenants, members, slugs, enrolment, device-key IDs, custom names and billing, and links out to the nodes' own hostnames. It never renders node data, except (amended 2026-11-19) the synced policy kinds from its mirror, for its policy editor (ADR-1063), and the Shadow AI export (ADR-1059 point 3); never the query log, the CMDB or anything else. A fleet view, if ever, is an opt-in summary push.
  9. The tunnel runs as its own task with bounded queues and no lock shared with the DNS pipeline (spec/02 §3, §8; CLU-004). Loss of the cloud is cloud_unreachable (degraded, never severe).
  10. Every frame from a node is untrusted input to the cloud (a tenant may run a modified AGPL node): strings escaped where shown, CSRs and updates checked against the tenant, role and epoch claims never believed alone. spec/14 states it.

Consequences

Nothing in the UI changes, and query logs, cookies and secrets never reach the cloud in clear. A broker bug or a compromised broker cannot borrow a LAN device's policy or a display's binding by writing a false address. Each roaming device holds a stream open, which is why DNS has its own budget. The broker needs raw TCP ingress (VMs, ADR-1052), not Container Apps' HTTP ingress, and cannot scale to zero. The cloud cannot put a WAF or pre-authentication gate in front of node pages. Rejected: an L7 proxy (the cloud becomes trusted with every tenant's sessions), a separate hosted app (duplicates every control), WebSocket plus a multiplexer (two new crates for proxy traversal that nodes rarely need), WireGuard (exposes the host, needs privileges), Azure Relay Hybrid Connections (billed per listener, Azure lock-in), relayed streams as real sockets with proxy_protocol = true (ADR-039 has no source allowlist).

Amended 2026-11-19 (owner decisions on cloud writes A to D): the owner wants the cloud control plane to update the linked home nodes and cloud-based filtering kept in sync with what is on-prem both ways. Point 3 now names two trusted channels instead of "no way to change a node's configuration"; point 8 lets the portal show the synced policy it edits. The relay rules of point 4 are unchanged: signed changes are not relayed sessions, and guarded settings stay home-only or custom-domain-only. A compromise of the cloud's back end can now delay or drop a change but not create or alter one (ADR-1061); the residual risk of a compromised portal front end at the moment an editor signs is ADR-1061 point 7's.

Requirements CLU-004

Builds on ADR-039 ADR-044 ADR-045 ADR-1031 ADR-1048 ADR-1049 ADR-1052 ADR-1059 ADR-1061 ADR-1062 ADR-1063 ADR-1066 ADR-944 ADR-976

Referenced by ADR-1048 ADR-1051 ADR-1052 ADR-1056 ADR-1057 ADR-1059 ADR-1060 ADR-1061 ADR-1064

ADR-1048 Each node has its own cloud key; enrolment by device code or token; the cloud is never a cluster memberAccepted 2026-11-19, owner accepted all recommendations; #41, T36.1; revised after review the same dayThe tunnel (ADR-1047) needs a node identity the cloud can trust and revoke.

Context

The tunnel (ADR-1047) needs a node identity the cloud can trust and revoke. ADR-903 keeps a node's own identity keys out of the replicated store. ADR-054 lets any cluster member vouch for a user's role on a forwarded write (crates/wrendns/src/forward.rs), so a cloud process inside a tenant's cluster could forge admin writes; M32's T32.8 listed "the cloud node joins the home cluster" as an option. RFC 8628 device codes invite phishing (an attacker's code entered by the victim). WebPKI renewals may change a certificate's key, so a pin on a broker leaf would break every tunnel at a renewal.

Decision

  1. Each full member generates its own Ed25519 cloud key in <data_dir>/cloud/, mode 0600, node-local, never replicated and never a stored secret. The cloud CA issues it a client certificate of about 30 days carrying tenant, cluster and node IDs, renewed over the tunnel at two thirds of its life (as ADR-057). A node offline past expiry renews with its cloud key plus a fresh countersignature from the current primary within a 180-day grace period, unless removed; after that it links again.
  2. The broker presents for tunnel.<suffix> a certificate from the cloud's private tunnel CA. The node pins that CA's key and a backup key, both delivered at enrolment; a rollover is announced in the hello message, signed by the current CA key, at least 30 days ahead.
  3. Enrolment is outbound only: an RFC 8628 device code shown on the primary (UI and wrendns cloud link), entered at dns.wrendns.com/link, single use, 10 minutes, rate limited; or, for headless and Kubernetes installs, a portal-issued wren_enrol_... token read from a secret file (hash stored, expiring, one tenant). The confirmation page shows the requesting cluster's name, its node names, its source address and rough region and its version. The primary countersigns each member's first certificate request over the cluster channel.
  4. Each slug is bound to one cluster. A second cluster of the same tenant gets its own slug; moving a slug needs confirmation on a node of the cluster that holds it. The certificate helper issues a slug's names only to that cluster.
  5. Linking and unlinking are admin-only guarded settings, never for agents (added to spec/13 §3.2's list), and audited on both sides.
  6. Revocation and removal: Remove node in the portal closes the tunnel and denies the serial; Disconnect on the node deletes the key and notifies the cloud; when a member is removed from the registry (ADR-143) the primary tells the cloud at once, the cloud denies the node's serial and closes its tunnel, and the helper revokes that node's TLS certificates for the tenant's names. A primary's heartbeat carries a lease {cluster_id, node_id, epoch, expires} signed with its cloud key, and the broker routes the cluster name to it only when a majority of the tenant's connected tunnels agree.
  7. No cloud component ever joins a tenant's cluster, as a full member, ephemeral member or witness. A cloud resolver (T36.12) subscribes to signed policy snapshots over the tunnel instead. This replaces the cluster-member option of M32's T32.8; the tunnel settles T32.8's link direction (the home node dials out).

Consequences

The cloud can revoke one node without touching the others, and a cluster CA compromise is not a cloud compromise. A removed or stolen node stops receiving relayed streams within seconds and cannot capture the cluster name with an unsigned claim. Phishing a device code needs the victim to ignore a page that names the attacker's cluster. A lost cloud key is re-enrolled, not restored. Rejected: reusing the cluster certificate (no independent revocation, resolver pods hold one too), one replicated cluster-wide cloud secret (against ADR-903's node-identity rule) and an SPKI pin on the broker's WebPKI leaf (breaks at key rotation).

Builds on ADR-054 ADR-057 ADR-1047 ADR-143 ADR-903

Referenced by ADR-1047 ADR-1063

ADR-1049 Authorization stays on the node: the hosted issuer asserts identity only, every relayed sign-in needs a node-held factor, roles are mapped and capped on the node, and custom roles add create, update and remove per object kindAccepted 2026-11-19, amended per the owner decisions on cloud writes; owner accepted all recommendations; #41, T36.1; revised after review the same day#41 asks for single sign-on on the hosted site, RBAC with create, update and remove, and a hosted side trusted no further than the user's role.

Context

#41 asks for single sign-on on the hosted site, RBAC with create, update and remove, and a hosted side trusted no further than the user's role. Today's roles are viewer (which reads the query log), operator and admin; OIDC providers map group claims to a role (T3.6); agent tokens use a deny-by-default route table (required(method, path) in crates/wrendns-api/src/auth/agent.rs) and are capped by their owner's role (ADR-064). The API's PUT is an upsert. A compromised issuer can mint any number of subjects. The cloud controls the hosted names' zone, so it can mint a certificate for them and run a live man-in-the-middle; against that, a relayed TOTP code or a passkey (same origin) does not help. The OIDC state cookie is host-only on /api/v1/auth/oidc, and users arrive at the cluster name, not the node's.

Decision

  1. The portal is an OIDC issuer. Linking adds it to each node as a node-managed [[auth.oidc.provider]] (ADR-968; verified by ADR-951's verifier). Its tokens assert sub, email and the tenant ID only. (Amended 2026-11-19: the issuer authenticates people only through Microsoft Entra External ID, which holds accounts, MFA, passkeys and recovery, and asserts Entra's stable oid as sub; ADR-1065. Amended again 2026-11-19 by ADR-1067: the issuer is a federation broker that signs consumers in through External ID and organization members through their own IdP, and asserts a portal-minted user ID as sub.) For this provider the node ignores group claims (amended 2026-11-19 by ADR-1069 point 3: SCIM group memberships arrive as membership updates and count only under a hosted_group_rule a node admin signed, never as token claims). Each node registers two redirect URIs (<slug>.<suffix> and <node>.<slug>.<suffix>) and picks the one matching an allowlisted Host header.
  2. A node-local table maps hosted subjects to node roles, set by a node admin or approved after a user's first sign-in. Unmapped subjects are pending with no access (pending entries expire after 7 days; their email is shown as "unverified, from the cloud", security review L7). A session made on the LAN (the condition of every "on the LAN" step in the hosted design) is one that was not relayed, whose source is inside allowed_admin_networks, and that did not arrive through a public listener or a proxy_protocol listener (added 2026-11-19 after the security review). Over the relay, a hosted sign-in completes only with a second factor the node holds, enrolled on the LAN: a passkey (WebAuthn, relying party <slug>.<suffix>, the same at home and away) or TOTP. Sessions record how and where they were made; over the relay only sessions made over the relay with the issuer and the node factor are accepted. The hosted provider has a node-local max_role, default operator. (Amended 2026-11-19 by ADR-1069: subjects may also be granted by a signed group rule, up to operator and never admin, active only after onboarding; a node factor may be enrolled from away only through an admin-signed invitation (ADR-1069 point 8); a cloud SubjectDisabled or SubjectRelinked notice disables a subject, its sessions and its signers at once, unsigned, never deleting them, while restoring them needs a node admin (ADR-1069 points 5 and 6); and when the linked tenant is an organization, [cloud] factor_on_lan (on by default there) requires the node factor on hosted sign-ins on the LAN too (ADR-1069 point 9, after the identity security review).)
  3. Admin and guarded work over hosted names is refused by default, whatever the role and the cap, because the cloud could be in the middle. An admin on the LAN can allow it (a guarded setting) either only on a verified custom name whose A/AAAA records, tenant certificate and CAA (accounturi of the tenant's own account, validationmethods=dns-01) the node has checked (ADR-1050 point 7), or with out-of-band approval of each action from a session signed in on the LAN. Over hosted names, a relayed session's direct writes to synced kinds are refused (added 2026-11-19 after the security review; security review decision 2, confirmed by the owner 2026-11-19): such edits go through a signed change on the node's own signing page (ADR-1061 point 1), so a man-in-the-middle with a minted certificate cannot make them silently through a captured session; on a verified custom name direct writes stay allowed. Operator writes to kinds that are not synced, and agent tokens over the relay, stay as they are, and a man-in-the-middle could use them while it lasts (stated in the blast radius). When the CT watch (ADR-1051 point 6) sees an unknown certificate for the node's names, relayed sign-in and relayed sessions are refused until a LAN admin acknowledges.
  4. Session and OIDC state cookies use the __Host- prefix (the old name read for one release, ADR-1028's pattern).
  5. Custom roles: a role is a set of (kind, verb) permissions over the node's object kinds, with verbs create, update, remove and read. viewer, operator and admin are built-in presets that behave exactly as today. Verbs map onto routes in the agent route table; a token's permissions stay the intersection of its scopes and its owner's role. Guarded and never-for-agents routes stay admin-only whatever a role says.
  6. Create versus update is decided on the primary, inside the write, by whether the object exists under the If-Match version. A forwarded write carries the role name, and the primary resolves it to permissions (roles replicate with users, ADR-045).
  7. The node's hash-chained audit stays authoritative and records oidc:<issuer>/<sub>, the factor used, the client address the relay reported and the relay correlation ID. The cloud keeps its own append-only tenant event log and never records node content. Support access is impossible by default; a time-boxed grant is a node-side, audited admin action.
  8. Custom roles ship in the AGPL node first and are useful without the cloud.
  9. Cloud writes (added 2026-11-19 by the owner decisions on cloud writes; revised after the security review): a change made in the portal is signed on the node's own signing page whenever home is reachable (ADR-1061 point 1) and is authorized on the node by the editor's enrolled signing key, the mapping of that signer's enrolled subject (point 2; the role always comes from the signer's subject, never from the envelope or a token), its role and the hosted provider's max_role (points 2 and 5; security review decision 7, confirmed by the owner 2026-11-19), and the sync allowlist (ADR-1063), never by the issuer's token or a cloud claim; it is audited as point 7 says, with the change ID and signer. Guarded settings (listeners, TLS, cluster, secrets, auth) are never synced and stay home-only or custom-domain-only (point 3).

Consequences

A compromised issuer alone cannot sign in anywhere, and (since the amendment) cannot create a change either, because it holds no signer's key: new subjects get nothing and mapped users need their node factor. A compromise of the whole cloud that mints a certificate can still capture users who sign in during the attack and act as them up to max_role at operator level on kinds that are not synced, alter a change they sign on the node's page through the relay, and read what they open (the query log, the CMDB); the CT watch reports it, usually within a day, and then blocks remote access. Admin work from away needs a custom name or a LAN approval, which costs convenience. Every remote user enrols a passkey or TOTP at home first. The role editor, the pending list and the factor enrolment need a UI, a help topic and Playwright like every setting. Rejected: trusting the issuer's group claims (a cloud compromise would be admin everywhere), viewer for unmapped subjects (query-log read on every node for a compromised issuer), the node factor for admin only (an issuer compromise would read every node's query log) and keeping three fixed roles (does not meet #41).

Builds on ADR-045 ADR-064 ADR-1028 ADR-1050 ADR-1051 ADR-1061 ADR-1063 ADR-1065 ADR-1067 ADR-1069 ADR-951 ADR-968

Referenced by ADR-1047 ADR-1051 ADR-1057 ADR-1058 ADR-1060 ADR-1061 ADR-1065 ADR-1067 ADR-1068 ADR-1069 ADR-1070

ADR-1050 Configure-once names: a dedicated PSL-listed suffix with a separate site for device names, split-horizon records created on the node, a stable edge address, and roaming DoH and DoT through the home relay firstAccepted 2026-11-19, amended per the owner decisions on cloud writes; owner accepted all recommendations; #41, #28, T36.1; revised after review the same dayThe owner wants one device setting that reaches the local node at home and the same node away, and a per-tenant public resolver (#41).

Context

The owner wants one device setting that reaches the local node at home and the same node away, and a per-tenant public resolver (#41). Let's Encrypt allows 50 new certificates per registered domain per 7 days, global across accounts. Tenant pages under wrendns.com would share a browser site and reputation with the brand. Android Private DNS is DoT only, on port 853, by hostname; Apple profiles take a DoH ServerURL; Windows 11 DoH pairs a server IP with a template and will not resolve the server by name, and DDR needs an IP-address certificate that Let's Encrypt cannot issue for a private VIP. The DoT hostname, and so any ID in it, is sent in clear. ADR-039 answers 404 to a DoH request with an invalid client ID. Azure DNS allows 10,000 record sets per zone by default. ADR-1031's 32/128 MiB gates make one cloud resolver process per tenant impractical at scale.

Decision

  1. The portal is dns.wrendns.com. Tenant names live under a dedicated registrable suffix listed in the PSL's private section (the domain is the owner's first decision), so each <slug>.<suffix> is its own site and its own rate-limit bucket. Names under <slug>.<suffix> resolve only to that cluster's nodes or the edge: <slug>.<suffix> (cluster), <node>.<slug>.<suffix>, <dot-label>.<slug>.<suffix> (DoT), <location>.<slug>.<suffix>. Names that point at anything else (managed device names, dynamic DNS) live on the separate site <slug>-dev.<suffix>. Node names of 26 base32 characters are refused so they cannot pass for a device label. (Amended 2026-11-19, ADR-1064 point 2: roaming DNS names move to a third site, <slug>-dns.<suffix>: DoH https://<slug>-dns.<suffix>/dns-query/<key> and DoT <dot-label>.<slug>-dns.<suffix>, so the cloud resolver's certificate never covers a UI name; slugs may not end in -dns.)
  2. Linking creates node-managed local records (ADR-968) answering those names at home with the cluster VIP or the node's LAN address. Publicly one wildcard *.<suffix> answers with the edge; per-tenant record sets exist only for ACME challenges and dynamic DNS. A node keeps answering its local copies when the cloud is down. WrenDNS must be the LAN's only resolver (DHCPv4, IPv6 RDNSS, every VLAN); a home device seen on the cloud path is reported.
  3. Slugs: a-z, 0-9, hyphen, 6 to 32 characters, no xn--, not ending in -dev, a reserved and confusable list; opaque by default with vanity opt-in; never recycled.
  4. Roaming goes through the home relay first: the broker routes DoH (443) and DoT (853) by SNI to the home node, which answers with its own policy, identity and log. (Amended 2026-11-19 by owner decision C, ADR-1064: when home is unreachable, the broker sends the connection to the cloud resolver, which is in the MVP and answers from the last Accepted synced policy; roaming no longer fails closed. It is multi-tenant, verifies the primary's signed cloud view, is never a cluster member, never serves local records, and shares a cache only for unmodified public answers.)
  5. Every roaming query needs a device key or DoT label of at least 128 random bits (26 base32 characters). DoH carries the key in the path, inside TLS. The DoT label is sent in clear and is treated as leaked: relayed DoT gets the device's filtering policy with public answers only (no local, CMDB or location records, no private-range PTR) unless an admin allows internal names for that device; the broker refuses unknown labels; concurrent use from two ASNs is flagged. The node's known-ID gate (T36.2) is keyed on the relayed or public context flag, not the listener. Unknown, revoked and missing IDs are refused identically within a transport: 404 for DoH (as ADR-039) and REFUSED with an extended DNS error for DoT, counted and rate limited. Keys are created on the node, anchored to the CMDB device; the cloud learns only key IDs and DoT labels, and (amended 2026-11-19, ADR-1064 point 5) the SHA-256 of each DoH key, only for tenants whose roaming devices the cloud resolver may answer; the node never sends a key, but the cloud resolver sees one in the request path of each DoH request it answers and does not store it. No UDP 53 in the cloud.
  6. Every tenant name and tunnel.<suffix> resolve to one stable dual-stack edge address that moves between broker VMs on failover (ADR-1052), so no device or record ever needs to follow a VM.
  7. Custom names: a tenant's own name with A/AAAA records (never a CNAME) to the edge, proved by a TXT record, with the tenant's own CAA (accounturi, validationmethods=dns-01) checked by the node before it is marked protected from the cloud; routed by SNI with the node's own certificate (phase 2).
  8. Windows 11's built-in DoH is not a configure-once path: the setup page offers Chrome or Edge's template or dnscrypt-proxy, documents the built-in DoH as "away only", and T36.8 tests DNR (RFC 9463).

Consequences

Android, Apple, Chrome and Edge devices, and Windows through a client, are configure-once, with documented limits: Android strict mode has no DNS where port 853 is blocked, and Apple DNS profiles can block captive portals (the setup page gives the escape per OS, and generated profiles never set ProhibitDisablement). A leaked DoT label reveals no internal names by default. Roaming DNS depended on the home uplink until the fallback resolver existed; since the amendment the cloud resolver answers while home is down, and sees those queries in clear while it does. The PSL entry takes time and is hard to undo, and until it is live the whole suffix shares 50 new certificates a week (phase 2 files the PSL request and Let's Encrypt's rate-limit adjustment together). This amends ADR-039 only in adding the relayed context to the client-ID gate; its 404 is kept. Rejected: subdomains of wrendns.com without a PSL entry (a service-wide certificate cap, a shared browser site), device names under <slug>.<suffix> (a device's web page could toss cookies at the node UI), custom names by CNAME (the cloud could validate them and block their CAA), DNS failover of the broker (pinned IPs cannot follow), and a cloud resolver per tenant in v1.

Builds on ADR-039 ADR-1031 ADR-1052 ADR-1064 ADR-968

Referenced by ADR-1049 ADR-1064