docs: add comprehensive docstrings and inline comments

Add docstrings to all handler functions in daemon/handlers/firewall.py, covering
params, return values, and raised exceptions. Add inline comments to
_config_apply() reconciliation steps and the request body merge order.

Add docstrings across lib/ modules for emit helpers (_emit_str, _emit_int, etc.),
volatile stripping logic, two-layer diff strategy, sync event dispatch, and all
cross-subsystem sync subscribers (DnsToFirewall, WgToFirewall, FirewallToDhcp,
NetworkToAllSync).

Document WireGuard/networkd config parsers and key-value mappers in
system_import.py. Add docstrings to _ep(), Registry.decorator,
setup_logging, and _replace helper across daemon/ and lib/.

lib/system_import.py

@@ -253,7 +253,12 @@ def import_wireguard() -> bool:
 
 
 def _parse_wireguard_conf(text: str) -> dict[str, Any]:
-    """Parse wg-quick INI format into JSON config dict."""
+    """Parse wg-quick INI format into JSON config dict.
+
+    Uses a simple state machine: [Interface] section populates the interface
+    dict; each [Peer] section accumulates into current_peer until the next
+    section header triggers _flush_peer() to commit it.
+    """
     interface: dict[str, Any] = {
         "name": "wg0",
         "listen_port": 51820,
@@ -270,6 +275,15 @@ def _parse_wireguard_conf(text: str) -> dict[str, Any]:
     current_peer: dict[str, Any] | None = None
 
     def _flush_peer() -> None:
+        """Flush the current peer dict into the peers map if it has a public key.
+
+        Resets ``current_peer`` and ``current_peer_name`` to ``None``,
+        preparing for the next [Peer] section.
+
+        Note:
+            Only peers with a ``public_key`` are stored; sections without
+            a key (malformed or incomplete) are silently skipped.
+        """
         nonlocal current_peer, current_peer_name
         if (
             current_peer is not None
@@ -416,7 +430,13 @@ def import_networkd() -> bool:
 
 
 def _parse_network_file(path: Path) -> dict[str, Any] | None:
-    """Parse a .network INI file into interface config dict."""
+    """Parse a .network INI file into interface config dict.
+
+    State machine: [Match] section is skipped; [Link] keys go to iface["link"];
+    [Network] keys go directly on iface. Numbered sections ([Address#N], [Route#N])
+    accumulate into cur_addr / cur_route dicts until a section boundary triggers
+    _flush() to commit them into the corresponding list.
+    """
     text = path.read_text()
     iface: dict[str, Any] = {}
     cur_section: str | None = None
@@ -424,6 +444,7 @@ def _parse_network_file(path: Path) -> dict[str, Any] | None:
     cur_route: dict[str, Any] | None = None
 
     def _flush() -> None:
+        """Commit accumulated address/route dicts into the iface lists."""
         nonlocal cur_addr, cur_route
         if cur_addr is not None:
             if "address" in cur_addr and len(cur_addr) == 1:
@@ -541,6 +562,16 @@ def _parse_network_section(
 
 
 def _set_link_key(link: dict[str, Any], key: str, val: str) -> None:
+    """Parse a [Link] section key-value pair and set the corresponding config field.
+
+    Maps systemd-networkd Link INI keys to snake_case config keys.
+    Boolean keys (ARP, Multicast, etc.) are auto-converted via ``_parse_bool``.
+
+    Args:
+        link: Link config dict to populate.
+        key: INI key name from the .network file.
+        val: Value string from the .network file.
+    """
     if key == "MTUBytes":
         parsed = _safe_int(val)
         if isinstance(parsed, int):
@@ -563,6 +594,17 @@ def _set_link_key(link: dict[str, Any], key: str, val: str) -> None:
 
 
 def _set_network_key(iface: dict[str, Any], key: str, val: str) -> None:
+    """Parse a [Network] section key-value pair and set the corresponding config field.
+
+    Maps systemd-networkd Network INI keys to snake_case config dict keys.
+    Comma-separated values (DNS, Domains, etc.) are split into lists.
+    Boolean and integer keys are auto-converted.
+
+    Args:
+        iface: Interface config dict to populate.
+        key: INI key name from the .network file.
+        val: Value string from the .network file.
+    """
     if key == "DHCP":
         iface["dhcp"] = val
     elif key == "Gateway":