Release v1.1.0

docs/RECONCILIATION.md

@@ -72,19 +72,24 @@ pub struct ReconciliationPlan {
 
 ### A. WireGuard Interfaces
 - Checks if desired interfaces (`Interface`) exist in kernel links via RTNETLINK.
-- Detects missing interfaces, wrong MTU, or down status.
+- Detects missing interfaces, wrong MTU, down status, or public key mismatch.
+- **Dynamic Port Drift Tolerance**: When desired `listen_port` is `None` (standard for Upstream interfaces), the reconciler accepts kernel-selected ephemeral dynamic ports without generating false drift.
+- **Orphan Interface Detection**: Scans live kernel WireGuard interfaces; any interface present in kernel but absent from SQLite desired state is scheduled for removal (`delete_orphan_interface`).
 
 ### B. Cryptographic Peers
 - Queries live WireGuard device via `WG_CMD_GET_DEVICE`.
 - Detects missing peers, changed public keys, altered allowed IPs, or mismatched persistent keepalive intervals.
+- **Role-Aware Cryptokey Routing**: Overlay peers are checked against assigned `/32` or `/128` tunnel addresses, while Upstream provider peers are checked against configured full-tunnel AllowedIPs (`0.0.0.0/0, ::/0`).
 
 ### C. Kernel Routes
 - Queries active kernel routes via `RTM_GETROUTE`.
 - Evaluates exact equality on destination CIDR, gateway IP, interface name, and route metric.
+- Protects host default gateway (`192.168.1.1`) and physical WAN interfaces from unwanted modifications.
 
 ### D. nftables Firewall & NAT
 - Compares desired rules in SQLite against live rules in `table inet nx9_wg`.
 - Detects missing rules, priority shifts, or altered NAT masquerade subnet policies.
+- Outbound NAT masquerading remains scoped exclusively to Overlay client subnets.
 
 ### E. IP Forwarding
 - Inspects `/proc/sys/net/ipv4/ip_forward` and `/proc/sys/net/ipv6/conf/all/forwarding`.
@@ -105,3 +110,10 @@ Reconciliation mutations are protected by an asynchronous Mutex:
 1. **Clean Cold-Start Recovery**: When `nx9-wg` starts or restarts, the background daemon queries the kernel, detects unapplied state from SQLite, and applies all interfaces, peers, routes, and firewall rules in one unified cycle.
 2. **Idempotent Convergence**: Running `reconcile apply` multiple times in succession produces zero mutations (NOOP) once convergence is achieved.
 3. **Telemetry Protection**: Live kernel telemetry (transfer bytes, handshake timestamps) is ingested into memory/events and NEVER overwrites authoritative desired configuration in SQLite.
+
+---
+
+## 6. Orphan Interface Removal & Empty-State Guard
+
+- **Deterministic Orphan Cleanup**: When an interface is deleted or an unmanaged kernel device is detected, `apply()` removes the orphan interface from the Linux kernel.
+- **Empty-Desired-State Safety Guard**: If SQLite returns zero desired interfaces while live kernel interfaces are present, `apply()` aborts immediately with an error rather than mass-deleting kernel interfaces, protecting against catastrophic link destruction during transient database read errors.