@celilo/cli 0.24.1 → 0.25.0

package/CELILO_CORE_MODULES.md

@@ -23,11 +23,11 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 
 - **axon** — Axon Networks Q1000K ISP router driver (Brightspeed-branded); port-forwarding + public-IP discovery + DHCP DNS + DHCP address-pool bounds via the TR-181 CGI API. **provides:** `firewall`, `dhcp_server`. Fork of **greenwave** — identical protocol, differing only in the vendor extension prefix (`X_AXON_` vs `X_GWS_`/`X_LANTIQ_COM_`). Pick by device: Q1000K → **axon**, C4000XG → **greenwave**. Two device behaviours shape this driver and are not shared by **greenwave** (celilo#739): the router **regenerates** `Pool.1.DNSServers` from its own upstream resolver list every ~15 min and on any config commit, so `setDhcpDns` also writes `Device.DNS.X_AXON_CustomServer` — the *input* to that computation, which survives — and **technitium re-asserts** the pool value on `timer.tick.1m`. Optional `dhcp_pool_start`/`dhcp_pool_end` bound the leased range; set them below the addresses IPAM allocates, because **IPAM has no knowledge of the router's DHCP pool** and nothing otherwise stops the router leasing an address celilo already assigned.
 - **greenwave** — GreenWave C4000XG ISP router driver; port-forwarding + public-IP discovery via REST. **provides:** `firewall`, `dhcp_server`. Legacy device; new deployments on Axon hardware want **axon**.
-- **iptables** — iptables firewall + NAT; cross-VLAN port exposure with recursive upstream delegation. Converge model: `exposeService` registers into the shared-core port-forward registry, then renders the complete ruleset and applies it atomically via `iptables-restore` (default-DROP FORWARD + coarse zone-tier matrix; SSH-free). **provides:** `firewall`.
+- **iptables** — iptables firewall + NAT; cross-VLAN port exposure with recursive upstream delegation. Converge model: `exposeService` registers into the shared-core port-forward registry, then renders the complete ruleset and applies it atomically via `iptables-restore` (default-DROP FORWARD + coarse zone-tier matrix; SSH-free). **REQUIRES the networks it has legs on and defines none of them** (`requires.networks: [{from: $self:zones}]`) — the required set is resolved from the same `zones` value that says which NICs the box has, so the legs and the declared networks are ONE list. They used to be two: `zones` and a `provided_networks` array this module wrote into system config from its install hook, with nothing forcing them to agree. A leg whose network has no declared subnet classifies `alien`, and on a firewall with a recorded baseline an alien interface is DISABLED — so under-declaring was never cosmetic. `firewall-interface-classification` §3/D8 reached that conclusion for the test harness; `networks-are-declared-not-written` applies it in production and deletes `provided_networks` outright (breaking: iptables 3.0.0). celilo supplies each range, asking the operator when it holds none. **provides:** `firewall`.
 - **knot-unbound-internal** — split-horizon internal DNS via Knot (authoritative) + Unbound (recursive); lightweight, plain apt, no .NET. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/knot-unbound-internal/base-module-aspect/`).
 - **technitium** — internal split-horizon DNS resolver + authoritative server (web UI + HTTP API); heavier alternative to knot-unbound. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/technitium/base-module-aspect/`).
 - **namecheap** — public DNS A-record management via Namecheap Dynamic DNS API (HTTP, no browser automation). A caller supplies a NAME and nothing else: the address is the source IP of celilo's own update, re-derived on every assert. Registering `<domain>` also claims `www.<domain>` and vice versa (best effort, reported back as `outputs.companion_fqdn` so the framework's `public_dns` check watches it — Namecheap answers `ErrCount 0` for `www` updates it does not apply). DDNS passwords are keyed by the **registrable domain**, never the FQDN. **provides:** `dns_registrar`.
-- **wireguard** — owns the admin WireGuard tunnel on the firewall host: interface, listen port, peers (as records), and client subnet are module config rather than hand-maintained state. Exposes the listen port and **registers the client subnet as a trusted source**, so VPN reach into the managed zones is in the firewall registry and every converge re-emits it. **Declares `network.control-plane-vpn.subnet` BEFORE it creates the interface** — the first side effect of `on_install`, before any command touches the box. The ordering is load-bearing, not tidiness: the firewall classifies every interface on its host and one no declaration accounts for is `alien`, so creating `wg0` first would leave a window in which a converge — a timer, the registry-poll CD, any unrelated module deploy — could shut the admin VPN down as an intruder's interface. The module declares the NETWORK, never the device: only the firewall decides what an interface is for. `health_check` asserts the declaration still holds, because the other checks all pass while it is missing. That same key is what the internal resolver's split-horizon view consumes. Adopts a running tunnel in place (existing key and peers retained; `wg syncconf`, never `wg-quick down`) because that tunnel is the operator's recovery path. **requires:** `firewall` (and the provider must support trusted-source registration — `iptables` does; the ISP-router drivers `greenwave` and `axon` do not).
+- **wireguard** — owns the admin WireGuard tunnel on the firewall host: interface, listen port, peers (as records), and client subnet are module config rather than hand-maintained state. Exposes the listen port and **registers the client subnet as a trusted source**, so VPN reach into the managed zones is in the firewall registry and every converge re-emits it. **REQUIRES the `control-plane-vpn` network and READS its range** (`requires.networks`; `client_subnet` is a `source: system` derive of `network.control-plane-vpn.subnet`). It does not write that network and has no way to — celilo owns the namespace, and the deploy will not reach any hook until the network is defined, asking for a range if one is missing. So `wg0` is attributable the moment it exists. This replaces a declare-before-you-create ordering inside `on_install`, which could only narrow the window and not close it: a consumer that captured config before the hook started could not see a value the hook wrote, whatever order it wrote it in, and that is exactly what left `wg0` unattributable (celilo#759). `health_check` still asserts the declaration matches what the tunnel serves — what it catches now is divergence, celilo's network having changed since the module resolved its config. That same key is what the internal resolver's split-horizon view consumes. Adopts a running tunnel in place (existing key and peers retained; `wg syncconf`, never `wg-quick down`) because that tunnel is the operator's recovery path. **requires:** `firewall` (and the provider must support trusted-source registration — `iptables` does; the ISP-router drivers `greenwave` and `axon` do not).
 
 ## Public edge (ingress / identity)
 

package/CELILO_SUBSYSTEMS.md

@@ -27,7 +27,9 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 - **Infrastructure selection (container-service vs machine pool)** — `apps/celilo/src/services/machine-pool.ts` (`getMachineByHostname`, `addMachine`, `assignModuleToMachine`) and `apps/celilo/src/services/container-service.ts` (`getContainerServiceByName`, `addContainerService`, `verifyContainerService`). Provider API clients: `apps/celilo/src/api-clients/proxmox.ts`, `apps/celilo/src/api-clients/digitalocean.ts`.
 - **Zone detection / system config** — `apps/celilo/src/services/zone-detector.ts` — `detectZoneFromIp` reads `network.<zone>.subnet` from the `systemConfig` table and returns `NetworkZone | 'unknown'`. It answers CONTAINMENT ONLY. It used to return `'external'` on no-match, which conflated "no declared subnet contains this" with "the internet can route to this" — on a firewall with five RFC1918 legs that reported four of them as facing the internet. `'unknown'` is the honest answer; the caller resolves it (see `machine add`: publicly routable → `external`, otherwise fail asking for `--zone`). The subnet-backed zone list is derived from `NETWORK_ZONES` minus `external`, which has no subnet and must never be given one.
 - **Interface classification** — `packages/capabilities/src/interface-classification.ts` — THE shared classifier, used by the backend and every firewall provider module so the two cannot drift apart again. `isPubliclyRoutable(ip)` is a property of the address alone (false for RFC 1918, RFC 6598 carrier-grade NAT, loopback, link-local, multicast, reserved). `classifyInterfaces(interfaces, zones)` assigns each interface `zone → external → alien`, first match winning, where `external` is the RESIDUAL — routable and claimed by no declared zone — and is never subnet-matched. `externalEdge()` returns none/single/**ambiguous** rather than silently picking the first public address. `defaultRouteFinding()` enforces the invariant that the default route leaves through `internal` or `external`. **`subnetContains(cidr, ip)` lives here and is the ONLY implementation** — three existed and disagreed (the backend's mishandled `/0`); the other two are deleted, not aliased. Design: `openspec/changes/firewall-interface-classification/design.md`.
-- **Declared networks (classification input)** — `readDeclaredNetworks(db)` in `apps/celilo/src/hooks/capability-loader.ts` — every `network.<name>.subnet` in system config, which is what an interface is attributed against. Read from the CONFIG, not from `NETWORK_ZONES`: celilo declares networks that are not placement zones (`network.control-plane-vpn.subnet`, written by `wireguard` before it brings `wg0` up). Injected into the firewall capability as a LIVE reader (`declaredNetworks`), alongside the trusted-source store and for the same reason — a declaration written during a hook run must be visible to the converge that follows it in that same run, which a snapshot taken at capability-build time cannot be.
+- **Declared networks (classification input)** — `readDeclaredNetworks(db)` in `apps/celilo/src/hooks/capability-loader.ts` — every `network.<name>.subnet` in system config, which is what an interface is attributed against. Read from the CONFIG, not from `NETWORK_ZONES`: celilo holds networks that are not placement zones (`network.control-plane-vpn.subnet`, which `wireguard` requires and reads). Injected into the firewall capability as a LIVE reader (`declaredNetworks`) — that liveness was a mitigation for values written mid-run by a module hook, which `network-declaration` removes; see that spec before assuming a snapshot is still unsafe.
+- **Network requirement + ensure (celilo owns the namespace)** — `apps/celilo/src/services/network-ensure.ts` (`ensureRequiredNetworks`), `NetworkRequirementSchema` / `getRequiredNetworkNames` in `apps/celilo/src/manifest/schema.ts`. A module declares `requires.networks: [{name}]` — a NAME, never a value; the schema is `.strict()` so a `subnet:` on the requirement is rejected with a message saying why. The deploy calls `ensureRequiredNetworks` in its interview phase, BEFORE generation and before any hook, and asks over the generic bus interview (`askText`, so it is answerable headless) for anything undefined. Which attributes a network has is celilo's answer, taken from `apps/celilo/schemas/system_config.json`: that file declares `network.<n>.gateway` for the routed segments and omits it for `control-plane-vpn`, so a gateway is never asked for a network that has none. Well-known names carry a `suggested` range there — deliberately NOT `default`, which `getDefaultConfiguration()` would seed at `system init`. Spec: `openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md`.
+- **The network write path (closed) + celilo's own discovery** — `celilo system apply-config` (`apps/celilo/src/cli/commands/system-apply-config.ts`) REFUSES the whole `network.` namespace, `network.bridge` excepted (a Proxmox bridge name is not addressing, and it is the one network key with a schema default). That is the automation surface a module hook shells out to, so closing it there is what makes "networks are celilo's" an authority rather than a convention every module has to remember. The refusal names the alternative — declare the network, read it with `$system:` — because a bare rejection sends a module author hunting for a typo. The one write that legitimately needed the surface moved INTO celilo: `celilo system discover-network` (`apps/celilo/src/services/network-discovery.ts`, `cli/commands/system-discover-network.ts`) parses the box's own `ip route` and records `network.internal.*` — or `network.secure-mgmt.*` when the box is off the internal LAN (#300). `celilo-mgmt` calls it and decides nothing; it used to parse and write this itself. Idempotent and never overwrites addressing already set. Recurrence gate: `test-integration/module/no-module-writes-networks.test.ts`.
 - **Firewall interface audit** — `apps/celilo/src/services/audit/interface-classification.ts` — reports per-firewall classification in `celilo audit`: alien interfaces by name and address (drift), and the blocking findings a converge refuses on — a carrier-grade NAT leg, an ambiguous external edge, a default route on the wrong leg.
 - **Zone taxonomy (canonical list)** — `apps/celilo/src/db/schema.ts` — `NETWORK_ZONES` is the single array; `NetworkZone` is DERIVED from it. Never hand-maintain a second copy: a duplicate that dropped a member made zone validation return null and silently fall back to a wrong-but-valid zone.
 - **Control-plane network (`secure-mgmt`)** — `apps/celilo/src/hooks/capability-loader.ts` — `loadControlPlaneSubnet` returns the subnet of the zone `celilo-mgmt` is deployed in. `secure-mgmt` is a placement zone AND the control-plane tier, deliberately NOT in `ZONE_TIER_ORDER` (it is not part of the `dmz → app → secure` data-plane chain; it reaches every tier by trust). The firewall's `trustedSubnets` derives from this rather than assuming celilo-mgr sits on `internal`. Reported as an actionable gap by `checkControlPlaneNetwork` in `apps/celilo/src/services/fleet-checks.ts` when the management address matches no configured subnet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/schemas/system_config.json

@@ -13,7 +13,8 @@
     "network.dmz.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
-      "description": "DMZ subnet CIDR (not defaulted \u2014 appears only when a firewall module provides this zone; see openspec/specs/progressive-zone-disclosure/spec.md)"
+      "description": "DMZ subnet CIDR (not defaulted \u2014 appears only when a firewall module provides this zone; see openspec/specs/progressive-zone-disclosure/spec.md)",
+      "suggested": "10.0.10.0/24"
     },
     "network.dmz.gateway": {
       "type": "string",
@@ -29,7 +30,8 @@
     "network.app.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
-      "description": "App subnet CIDR (not defaulted \u2014 appears only when a firewall module provides this zone)"
+      "description": "App subnet CIDR (not defaulted \u2014 appears only when a firewall module provides this zone)",
+      "suggested": "10.0.20.0/24"
     },
     "network.app.gateway": {
       "type": "string",
@@ -45,7 +47,8 @@
     "network.secure.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
-      "description": "Secure subnet CIDR (not defaulted \u2014 appears only when a firewall module provides this zone)"
+      "description": "Secure subnet CIDR (not defaulted \u2014 appears only when a firewall module provides this zone)",
+      "suggested": "10.0.30.0/24"
     },
     "network.secure.gateway": {
       "type": "string",
@@ -77,12 +80,14 @@
     "network.control-plane-vpn.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
-      "description": "WireGuard VPN client subnet CIDR (remote-access tunnel; consumed by technitium's split-horizon \u2192 in-zone caddy view, #275, and by the firewall's trusted sources once the wireguard module registers it)"
+      "description": "WireGuard VPN client subnet CIDR (remote-access tunnel; consumed by technitium's split-horizon \u2192 in-zone caddy view, #275, and by the firewall's trusted sources once the wireguard module registers it)",
+      "suggested": "10.255.255.0/24"
     },
     "network.secure-mgmt.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
-      "description": "Control-plane subnet CIDR \u2014 the network celilo-mgr itself occupies when it does not sit on the internal LAN (not defaulted \u2014 discovered at celilo-mgmt install, or recorded by firewall onboarding). Derives the firewall's trusted sources and the internal resolver's split-horizon view for celilo's own traffic."
+      "description": "Control-plane subnet CIDR \u2014 the network celilo-mgr itself occupies when it does not sit on the internal LAN (not defaulted \u2014 discovered at celilo-mgmt install, or recorded by firewall onboarding). Derives the firewall's trusted sources and the internal resolver's split-horizon view for celilo's own traffic.",
+      "suggested": "10.0.120.0/24"
     },
     "network.secure-mgmt.gateway": {
       "type": "string",

package/src/cli/commands/system-apply-config-equivalence.test.ts

@@ -10,6 +10,18 @@
  * Catches the bug class where a future change to system-init (e.g.
  * adding a side-effect or gateway computation) drifts away from
  * what apply-config writes.
+ *
+ * ── One deliberate DIVERGENCE, added by `network-declaration` ──
+ *
+ * The two surfaces are no longer equivalent for `network.*` keys, and that is
+ * the point rather than drift. `system init` is the OPERATOR's surface and may
+ * still set addressing; `apply-config` is the AUTOMATION surface a module hook
+ * shells out to, and networks are celilo's to define, not a module's
+ * (openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md).
+ * So the equivalence below is asserted over everything EXCEPT addressing, and a
+ * separate test asserts the refusal — because "these two agree" and "this one
+ * refuses" are both properties worth keeping, and collapsing them would lose
+ * whichever was written second.
  */
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
@@ -40,11 +52,9 @@ describe('system apply-config equivalence with system init --accept-defaults', (
   });
 
   test('apply-config writes the same systemConfig keys as system init --accept-defaults', async () => {
+    // No `network.*` here: apply-config refuses those now, deliberately.
+    // Everything else must still land identically through both paths.
     const overrides = [
-      'network.dmz.subnet=10.99.10.0/24',
-      'network.app.subnet=10.99.20.0/24',
-      'network.secure.subnet=10.99.30.0/24',
-      'network.internal.subnet=192.168.99.0/24',
       'dns.primary=9.9.9.9',
       'dns.fallback=1.1.1.1 8.8.8.8',
       'ssh.public_key=ssh-ed25519 AAAA== test@equivalence',
@@ -71,6 +81,37 @@ describe('system apply-config equivalence with system init --accept-defaults', (
     }
   });
 
+  test('the operator surface may still set addressing; the automation surface may not', async () => {
+    // Same key, same value, two surfaces, two answers. `system init` is the
+    // operator saying what the topology is; `apply-config` is a module asking to
+    // decide it. Only the first is an authority over the network namespace.
+    process.env.CELILO_DB_PATH = join(tmpDir, 'operator.db');
+    const viaInit = await handleSystemInit(['network.dmz.subnet=10.99.10.0/24'], {
+      'accept-defaults': true,
+    });
+    expect(viaInit.success).toBe(true);
+    expect(loadExistingConfiguration(getDb())['network.dmz.subnet']).toBe('10.99.10.0/24');
+
+    process.env.CELILO_DB_PATH = join(tmpDir, 'automation.db');
+    const viaApply = await handleSystemApplyConfig(['network.dmz.subnet=10.99.10.0/24']);
+    expect(viaApply.success).toBe(false);
+    if (!viaApply.success) {
+      expect(viaApply.error).toContain('requires.networks');
+    }
+  });
+
+  test('a refused network key takes the whole write with it — no partial application', async () => {
+    // Half-applying would be worse than refusing: the caller sees an error and
+    // the box is left in a state neither surface intended.
+    process.env.CELILO_DB_PATH = join(tmpDir, 'partial.db');
+    const result = await handleSystemApplyConfig([
+      'dns.primary=9.9.9.9',
+      'network.dmz.subnet=10.99.10.0/24',
+    ]);
+    expect(result.success).toBe(false);
+    expect(loadExistingConfiguration(getDb())['dns.primary']).toBeUndefined();
+  });
+
   test('apply-config refuses to run with no overrides (unlike init which has defaults)', async () => {
     process.env.CELILO_DB_PATH = join(tmpDir, 'empty.db');
     const result = await handleSystemApplyConfig([]);
@@ -92,10 +133,7 @@ describe('system apply-config equivalence with system init --accept-defaults', (
 
   test('apply-config writes report the number of values applied', async () => {
     process.env.CELILO_DB_PATH = join(tmpDir, 'count.db');
-    const result = await handleSystemApplyConfig([
-      'dns.primary=1.1.1.1',
-      'network.dmz.subnet=10.0.10.0/24',
-    ]);
+    const result = await handleSystemApplyConfig(['dns.primary=1.1.1.1', 'network.bridge=vmbr9']);
     expect(result.success).toBe(true);
     if (result.success) {
       // initializeSystem() merges with defaults + computed gateways,

package/src/cli/commands/system-apply-config.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, test } from 'bun:test';
-import { parseKeyValueArgs } from './system-apply-config';
+import { networkWriteRefusal, parseKeyValueArgs, rejectedNetworkKeys } from './system-apply-config';
 
 describe('parseKeyValueArgs', () => {
   test('empty args → empty overrides + no errors', () => {
@@ -68,3 +68,59 @@ describe('parseKeyValueArgs', () => {
     expect(result.overrides['dns.primary']).toBe('8.8.8.8');
   });
 });
+
+/**
+ * §2.2 — the write path is CLOSED, not merely unused.
+ *
+ * `apply-config` is the automation surface a module hook shells out to, and it
+ * is how `wireguard` and `iptables` used to write network definitions. Deleting
+ * those two calls stops those two modules; refusing the key stops the next one.
+ * The distinction matters because the authority is the point: a rule every
+ * caller must remember is not a rule.
+ */
+describe('network keys are refused (celilo owns the network namespace)', () => {
+  test('the subnet a module used to write is rejected', () => {
+    expect(rejectedNetworkKeys(['network.control-plane-vpn.subnet'])).toEqual([
+      'network.control-plane-vpn.subnet',
+    ]);
+  });
+
+  test('the whole network namespace is refused, not just .subnet', () => {
+    // A module that could set a gateway or a VLAN tag for a network it does not
+    // own would be redefining that network by increments, and a subnet-only rule
+    // would read as an invitation to do exactly that.
+    expect(
+      rejectedNetworkKeys([
+        'network.dmz.subnet',
+        'network.dmz.gateway',
+        'network.dmz.vlan',
+        'network.secure-mgmt.subnet',
+      ]),
+    ).toHaveLength(4);
+  });
+
+  test('network.bridge is exempt — a container-service concept, not addressing', () => {
+    // It is also the one network.* key with a schema default, so refusing it
+    // would break `system init`.
+    expect(rejectedNetworkKeys(['network.bridge'])).toEqual([]);
+  });
+
+  test('everything else still writes', () => {
+    expect(rejectedNetworkKeys(['dns.primary', 'ssh.public_key', 'public_dns.resolver'])).toEqual(
+      [],
+    );
+  });
+
+  test('the refusal says whose the namespace is, and what to do instead', () => {
+    // A bare "rejected" would send a module author looking for a typo. The
+    // message has to name the alternative, because there IS one: declare the
+    // network and read it.
+    const message = networkWriteRefusal(['network.dmz.subnet']);
+    expect(message).toContain('network.dmz.subnet');
+    expect(message).toContain('requires.networks');
+    expect(message).toContain('$system:network.<name>.subnet');
+    // And the operator's own escape hatches, which are not closed.
+    expect(message).toContain('celilo system config set');
+    expect(message).toContain('celilo system discover-network');
+  });
+});

package/src/cli/commands/system-apply-config.ts

@@ -29,6 +29,44 @@ interface ParsedInput {
   errors: string[];
 }
 
+/**
+ * Keys this command will not write, however they arrive.
+ *
+ * `apply-config` is the automation surface — the one a module hook can shell out
+ * to — and networks are celilo's to define, never a module's
+ * (openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md).
+ * Closing it here rather than trusting each module is the point: an authority
+ * that depends on every caller behaving is not an authority.
+ *
+ * This is deliberately the WHOLE `network.` namespace and not just `.subnet`.
+ * A module that could set a gateway or a VLAN tag for a network it does not own
+ * would be redefining that network by increments, and the subnet-only rule would
+ * read as an invitation to do exactly that.
+ *
+ * `network.bridge` is exempt: it is a container-service concept (a Proxmox bridge
+ * name like `vmbr0`), not addressing, and it is the one `network.` key that
+ * carries a schema default.
+ */
+const NETWORK_KEY = /^network\./;
+const NETWORK_KEY_EXEMPT = new Set(['network.bridge']);
+
+export function rejectedNetworkKeys(keys: string[]): string[] {
+  return keys.filter((key) => NETWORK_KEY.test(key) && !NETWORK_KEY_EXEMPT.has(key));
+}
+
+export function networkWriteRefusal(keys: string[]): string {
+  return [
+    `Refusing to write ${keys.length === 1 ? 'a network key' : 'network keys'}: ${keys.join(', ')}.`,
+    '',
+    "Networks are celilo's to define, not a module's. A module declares the networks it",
+    'needs under `requires.networks` and reads them with `$system:network.<name>.subnet`;',
+    'celilo supplies the value, asking the operator when it does not already hold one.',
+    '',
+    'If you are the operator: `celilo system config set <key> <value>`.',
+    'If this is the management box recording its own network: `celilo system discover-network`.',
+  ].join('\n');
+}
+
 /**
  * Pure parser for the positional key=value arguments. Exported so the
  * test suite can exercise it without spinning up the CLI.
@@ -113,6 +151,11 @@ export async function handleSystemApplyConfig(
     };
   }
 
+  const refused = rejectedNetworkKeys(Object.keys(overrides));
+  if (refused.length > 0) {
+    return { success: false, error: networkWriteRefusal(refused) };
+  }
+
   const db = getDb();
   try {
     const applied = initializeSystem(db, overrides);

package/src/cli/commands/system-discover-network.ts

@@ -0,0 +1,35 @@
+/**
+ * `celilo system discover-network` — record the network this box sits on.
+ *
+ * The celilo-side half of "celilo owns the network namespace"
+ * (openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md).
+ * `system apply-config` refuses `network.*` keys outright, so this is the surface
+ * that writes the one network nobody can be asked about: the management box's
+ * own, which celilo reads off the kernel rather than out of anyone's config.
+ *
+ * Idempotent and non-destructive — a value already set is left alone, so a
+ * redeploy cannot clobber an operator's addressing.
+ */
+
+import { getDb } from '../../db/client';
+import { discoverAndRecordNetwork } from '../../services/network-discovery';
+import type { CommandResult } from '../types';
+
+export async function handleSystemDiscoverNetwork(): Promise<CommandResult> {
+  const result = discoverAndRecordNetwork(getDb());
+
+  if (result.applied.length === 0) {
+    // Not an error. "Nothing to record" is the ordinary outcome of a redeploy,
+    // and an undiscoverable route is a fact to report rather than a failure to
+    // abort a deploy on — the operator can set the value by hand.
+    return {
+      success: true,
+      message: `No network recorded: ${result.skipped ?? 'nothing to do'}.`,
+    };
+  }
+
+  return {
+    success: true,
+    message: `Recorded the network this box sits on:\n  ${result.applied.join('\n  ')}`,
+  };
+}

package/src/cli/completion.ts

@@ -620,6 +620,7 @@ export async function getCompletions(words: string[], current: number): Promise<
     const subcommands = [
       'init',
       'apply-config',
+      'discover-network',
       'config',
       'secret',
       'vault-password',

package/src/cli/index.ts

@@ -119,6 +119,7 @@ import { handleSubscribersTest } from './commands/subscribers-test';
 import { handleSystemApplyConfig } from './commands/system-apply-config';
 import { handleSystemAudit } from './commands/system-audit';
 import { handleSystemConfigGet, handleSystemConfigSet } from './commands/system-config';
+import { handleSystemDiscoverNetwork } from './commands/system-discover-network';
 import { handleSystemDoctor } from './commands/system-doctor';
 import { handleSystemInit } from './commands/system-init';
 import { handleSystemMigrate } from './commands/system-migrate';
@@ -1100,6 +1101,10 @@ Subcommands:
   apply-config <key=val>... | --from-stdin
                                        Headless config write — designed for module
                                        hooks (no prompts, no guidance, just writes).
+                                       Refuses network.* keys: networks are celilo's
+                                       to define, not a module's.
+
+  discover-network                     Record the network this box sits on, from its own routing table (idempotent)
 
   config set <key> <value>             Set system-wide configuration value
   config get [key]                     Get system configuration value(s)
@@ -2173,6 +2178,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       return handleSystemApplyConfig(parsed.args, parsed.flags);
     }
 
+    if (parsed.subcommand === 'discover-network') {
+      return handleSystemDiscoverNetwork();
+    }
+
     if (parsed.subcommand === 'config') {
       const configSubcommand = parsed.args[0];
       if (!configSubcommand) {

package/src/hooks/capability-loader.ts

@@ -632,8 +632,8 @@ function buildCapabilityInterface(
         undefined, // no upstream — the chain path handles that
         undefined, // logger is applied by wrapWithLogging at the loader site
         trustedSourceStore,
-        // LIVE, for the same reason as the chain path: a declaration written
-        // during this hook run must be visible to the converge that follows it.
+        // LIVE — see FirewallZones.declaredNetworks for why this stays live
+        // even though nothing writes a network mid-run any more.
         zones ? { list: zones.declaredNetworks } : undefined,
       );
       return stampProvider(iface, providerModuleId);
@@ -742,10 +742,28 @@ interface FirewallZones {
    * subnet (design D1, amended).
    */
   /**
-   * A LIVE read, not a snapshot. Everything else here is captured when the
-   * capability is built — before any hook runs — and for declarations that is
-   * wrong: `wireguard` declares its VPN subnet and brings `wg0` up inside one
-   * hook run, and the converge that follows has to see the declaration.
+   * A LIVE read, not a snapshot — and it STAYS live, deliberately, now that the
+   * race it was introduced for is gone.
+   *
+   * It was introduced because `wireguard` declared its VPN subnet and brought
+   * `wg0` up inside one hook run, so a converge later in that run had to see a
+   * value written after the capability was built. Modules no longer write
+   * networks at all (openspec/changes/networks-are-declared-not-written), and
+   * `ensureRequiredNetworks` defines every required one BEFORE the deploy loads
+   * any capability. So a snapshot would be correct today.
+   *
+   * It is kept live because being correct today is not the property worth having
+   * here. What a stale read costs is specific and severe: an interface celilo
+   * cannot attribute is ALIEN, and on a firewall with a recorded baseline an
+   * alien interface is disabled — which is how a converge came to shut down the
+   * admin VPN, the operator's way back into a remote box. A live read costs one
+   * query per converge. That is a trade worth making permanently, not one to
+   * re-evaluate whenever the write paths happen to look clean.
+   *
+   * And they are not entirely clean: `celilo system discover-network` writes
+   * `network.internal.*` from inside `celilo-mgmt`'s install hook. No firewall
+   * capability exists during that deploy, so it cannot bite — today. Liveness is
+   * what makes that sentence not need to stay true.
    */
   declaredNetworks: () => Array<{ zone: string; subnet: string }>;
   /**
@@ -851,14 +869,13 @@ export function loadTrustedSubnets(db: DbClient, firewallIp?: string): TrustedSu
  * Every network celilo can attribute an interface to: one entry per
  * `network.<name>.subnet` in system config.
  *
- * Read from the config rather than from `NETWORK_ZONES`, because celilo declares
- * networks that are not placement zones. `wireguard`'s `on_install` writes
- * `network.control-plane-vpn.subnet` before it brings `wg0` up, exactly as the
- * design requires (D3), and the firewall is supposed to classify `wg0` "by the
- * same subnet containment it uses for every other leg". Reading only
- * `NETWORK_ZONES` left that declaration invisible: the converge could not
- * attribute `wg0` and refused — and on a firewall with a baseline it would have
- * ISOLATED it, shutting down the admin VPN.
+ * Read from the config rather than from `NETWORK_ZONES`, because celilo holds
+ * networks that are not placement zones — `network.control-plane-vpn.subnet`,
+ * which `wireguard` requires and reads. The firewall classifies `wg0` "by the
+ * same subnet containment it uses for every other leg", and reading only
+ * `NETWORK_ZONES` left that network invisible: the converge could not attribute
+ * `wg0` and refused — and on a firewall with a baseline it would have ISOLATED
+ * it, shutting down the admin VPN.
  *
  * `external` is deliberately absent even when something has set
  * `network.external.subnet`: it is the RESIDUAL, decided by `isPubliclyRoutable`
@@ -1109,9 +1126,8 @@ async function buildFirewallChain(
       currentUpstream,
       logger,
       trustedSourceStore,
-      // LIVE, not a snapshot: a declaration written during this hook run —
-      // `wireguard` declaring its VPN subnet before creating `wg0` — must be
-      // visible to the converge that follows it in the same run.
+      // LIVE — see FirewallZones.declaredNetworks. Cheap insurance against a
+      // failure whose consequence is isolating the admin VPN.
       { list: zones.declaredNetworks },
     );
 

package/src/manifest/network-requirement-schema.test.ts

@@ -0,0 +1,141 @@
+/**
+ * `requires.networks` — a module NAMES the networks it depends on and never
+ * carries their values
+ * (openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md).
+ *
+ * The rejection below is the schema-level half of "a module has no path to
+ * create a network definition". The other half is the write path
+ * ([[cli/commands/system-apply-config.ts]]).
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { NetworkRequirementSchema, getRequiredNetworkNames } from './schema';
+import type { ModuleManifest } from './schema';
+
+describe('NetworkRequirementSchema', () => {
+  test('a requirement is just a name', () => {
+    expect(NetworkRequirementSchema.safeParse({ name: 'control-plane-vpn' }).success).toBe(true);
+  });
+
+  test('names are kebab-case, like every other user-facing identifier', () => {
+    expect(NetworkRequirementSchema.safeParse({ name: 'control_plane_vpn' }).success).toBe(false);
+    expect(NetworkRequirementSchema.safeParse({ name: 'DMZ' }).success).toBe(false);
+  });
+
+  test('a requirement carrying a subnet is rejected, and the message says why', () => {
+    const result = NetworkRequirementSchema.safeParse({
+      name: 'control-plane-vpn',
+      subnet: '10.255.255.0/24',
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    const message = result.error.errors.map((e) => e.message).join(' ');
+    expect(message).toContain('celilo owns');
+    expect(message).toContain('$system:network.<name>.subnet');
+  });
+
+  test('a gateway or vlan on the requirement is rejected too', () => {
+    expect(NetworkRequirementSchema.safeParse({ name: 'dmz', gateway: '10.0.10.1' }).success).toBe(
+      false,
+    );
+    expect(NetworkRequirementSchema.safeParse({ name: 'dmz', vlan: 10 }).success).toBe(false);
+  });
+
+  /**
+   * `from:` is the second form, for a module whose required set is decided per
+   * install rather than at authoring time — a firewall requires the networks it
+   * has legs on, and which legs it has is a property of the box it lands on.
+   * It still names networks and still carries no values.
+   */
+  test('a requirement may name a config array instead of a literal', () => {
+    expect(NetworkRequirementSchema.safeParse({ from: '$self:zones' }).success).toBe(true);
+  });
+
+  test("from must reference this module's own config, not another source", () => {
+    // `$machine:` / `$capability:` would make some other thing the author of the
+    // required set, which is the authority question this change exists to settle.
+    expect(NetworkRequirementSchema.safeParse({ from: '$machine:zones' }).success).toBe(false);
+    expect(NetworkRequirementSchema.safeParse({ from: '$capability:firewall.zones' }).success).toBe(
+      false,
+    );
+    expect(NetworkRequirementSchema.safeParse({ from: 'zones' }).success).toBe(false);
+  });
+
+  test('exactly one of name or from — neither both nor neither', () => {
+    expect(NetworkRequirementSchema.safeParse({ name: 'dmz', from: '$self:zones' }).success).toBe(
+      false,
+    );
+    expect(NetworkRequirementSchema.safeParse({}).success).toBe(false);
+  });
+});
+
+describe('getRequiredNetworkNames', () => {
+  function manifestWith(
+    networks: Array<{ name?: string; from?: string }> | undefined,
+  ): ModuleManifest {
+    return {
+      requires: { capabilities: [], networks },
+    } as unknown as ModuleManifest;
+  }
+
+  test('is empty for a module that requires no network', () => {
+    expect(getRequiredNetworkNames(manifestWith(undefined))).toEqual([]);
+  });
+
+  test('keeps declaration order and drops duplicates', () => {
+    expect(
+      getRequiredNetworkNames(manifestWith([{ name: 'dmz' }, { name: 'app' }, { name: 'dmz' }])),
+    ).toEqual(['dmz', 'app']);
+  });
+
+  test("resolves a from: requirement against the module's own config", () => {
+    expect(
+      getRequiredNetworkNames(manifestWith([{ from: '$self:zones' }]), {
+        zones: ['dmz', 'app', 'secure'],
+      }),
+    ).toEqual(['dmz', 'app', 'secure']);
+  });
+
+  test('an array stored as JSON resolves too', () => {
+    // Array config arrives as either shape depending on how it was written, and
+    // a requirement that silently resolved to nothing would leave a firewall leg
+    // undeclared — which is how an interface ends up classified alien.
+    expect(
+      getRequiredNetworkNames(manifestWith([{ from: '$self:zones' }]), {
+        zones: '["dmz","secure-mgmt"]',
+      }),
+    ).toEqual(['dmz', 'secure-mgmt']);
+  });
+
+  /**
+   * `external` is the RESIDUAL: an interface is external because it is publicly
+   * routable and matched no declared zone, never because it is contained in a
+   * subnet. Giving it one would reintroduce the overload that
+   * `readDeclaredNetworks` and `deployFirewall` both already exclude.
+   */
+  test('external is dropped, however it is named', () => {
+    expect(
+      getRequiredNetworkNames(manifestWith([{ from: '$self:zones' }]), {
+        zones: ['dmz', 'external'],
+      }),
+    ).toEqual(['dmz']);
+    expect(getRequiredNetworkNames(manifestWith([{ name: 'external' }]))).toEqual([]);
+  });
+
+  test('an unanswered config array requires nothing rather than throwing', () => {
+    // The firewall's zones are answered by the config interview, which runs
+    // before this. An empty result here means the interview has not happened
+    // yet, not that the module needs no networks.
+    expect(getRequiredNetworkNames(manifestWith([{ from: '$self:zones' }]), {})).toEqual([]);
+  });
+
+  test('literal and dynamic requirements combine', () => {
+    expect(
+      getRequiredNetworkNames(
+        manifestWith([{ name: 'control-plane-vpn' }, { from: '$self:zones' }]),
+        { zones: ['dmz'] },
+      ),
+    ).toEqual(['control-plane-vpn', 'dmz']);
+  });
+});