milestone 20: declarative configuration for iac

docs/explanation/architecture.md

@@ -35,7 +35,7 @@ Directories:
 | `src/upstream/` | Upstream resolution: shared vocabulary and the `Client` interface (`transport.zig`), DoH client (RFC 8484), DoT client (RFC 7858), per-endpoint health and backoff (`health.zig`), and `pool.zig` — priority-ordered failover that is itself a `transport.Client`, so the handler sees one interface. |
 | `src/server/` | The serving side: UDP/TCP/DoH/DoT listeners, `handler.zig` (the whole query pipeline), `cert_store.zig` (refcounted TLS cert holder), `rate_limiter.zig`, `pause.zig`, `clients.zig` (client auto-materialisation), `local_tables.zig` (published local-answer tables), `query_sink.zig` (log and SSE fanout), `shutdown.zig` (SIGINT/SIGTERM into one `std.Io.Event`). |
 | `src/storage/` | SQLite ownership: `db.zig` is the only file that calls SQLite, `config_schema.zig` + `migrations.zig` for `config.db`, `querylog_schema.zig` (open-or-recreate), async query `logger.zig`, `retention.zig`, `disk_monitor.zig`, and one repository per table under `repositories/`. |
-| `src/config/` | The one configuration model (`model.zig`), the pure validator (`validate.zig`), `import.zig`/`export.zig` (ZON to and from `config.db`, byte-stable round trip), `bootstrap.zig` (first-start seeding — a policy wrapper over import). |
+| `src/config/` | The one configuration model (`model.zig`), the pure validator (`validate.zig`), `import.zig`/`export.zig` (ZON to and from `config.db`, byte-stable round trip), `loader.zig` (read/parse/validate a named file, with the shared fault mapping), `reconcile.zig` (converge the database onto a parsed config by row identity). |
 | `src/web/` | The admin HTTP layer: `server.zig` (listener), `router.zig`/`routes.zig`, one file per resource under `handlers/`, `auth.zig` (sessions), `sse.zig` (live query fanout), `static.zig` (embedded SPA), `metrics.zig` (Prometheus), `openapi.zig` (served contract), `api_limiter.zig`, `http_util.zig`. |
 | `src/platform/` | OS and TLS edges: IP address values, the `std.log` sink (`logging.zig`), `statfs.zig` (free-space query via libc), client TLS over `std.crypto.tls` (`tls_client.zig`), server TLS over vendored Mbed TLS (`tls_server.zig`). |
 
@@ -47,7 +47,7 @@ main.zig ── cli.zig ── app.zig (composition root)
                           │ injects std.Io + collaborators
    ┌──────────────────────┴───────────────────────┐
    │  server/    web/    upstream/    storage/    │  I/O edge
-   │  platform/  config/{import,export,bootstrap} │
+   │  platform/  config/{loader,reconcile,import} │
    ├──────────────────────────────────────────────┤
    │  dns/   filter/*   local/*   cache/          │  pure core:
    │  config/{model,validate}                     │  bytes in, bytes out
@@ -162,14 +162,20 @@ working resolver over a correct-looking failure.
 Two databases with opposite contracts, in one data directory (see
 [reference/files-and-directories.md](../reference/files-and-directories.md)).
 
-**`config.db` is the truth.** Its schema is versioned: `migrations.zig` holds
+**`config.db` is what the server reads.** Its schema is versioned: `migrations.zig` holds
 an ordered list of steps, step 1 being the verbatim DDL from
 `config_schema.zig`, each applied inside one transaction. `nxdns import`
 replaces the whole content atomically under `BEGIN IMMEDIATE`, so a failed
 import changes nothing; `nxdns export` renders it back as canonical ZON,
-byte-identical across round trips. A config file seeds this database exactly
-once at first start. Why it works that way is
-[configuration-model.md](configuration-model.md).
+byte-identical across round trips.
+
+Which of the file and the database is *authoritative* is chosen by the
+invocation, not by state: bare `nxdns run` serves the database, and
+`nxdns run --config FILE` makes the file authoritative and reconciles the
+database onto it at every start. `reconcile.zig` is that convergence, matching
+rows by identity and writing only differences, so runtime state — blocklist
+checksums, compiled snapshots, client history — survives. Why it works that way
+is [configuration-model.md](configuration-model.md).
 
 **`querylog.db` is expendable.** It is never migrated. Its schema carries a
 fingerprint derived from the DDL text, and at open, a missing, corrupt,