@celilo/cli 0.24.0 → 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.0",
+  "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/module-config.test.ts

@@ -57,7 +57,12 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
     const result = await handleModuleConfigSet(['testmod', 'vmid', '203']);
     expect(result.success).toBe(false);
     if (!result.success) {
-      expect(result.error).toContain('infrastructure-managed');
+      // The refusal now names the source rather than a bespoke
+      // "infrastructure-managed" phrase, because `infrastructure` stopped being
+      // the only refused source — every non-`user` source is refused, and each
+      // gets guidance aimed at its own upstream.
+      expect(result.error).toContain('derived by celilo (source: infrastructure)');
+      expect(result.error).toContain('not operator-settable');
     }
   });
 

package/src/cli/commands/module-config.ts

@@ -6,6 +6,7 @@ import { eq } from 'drizzle-orm';
 import { z } from 'zod';
 import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
+import type { ModuleManifest, VariableDeclare } from '../../manifest/schema';
 import {
   HEALTH_CHECK_INTERVAL_CONFIG_KEY,
   reconcileModuleWatchState,
@@ -20,6 +21,12 @@ import {
   MONITOR_INTERVAL_FLOOR_MINUTES,
   cadenceSchema,
 } from '../../services/cadence';
+import {
+  declaredVariables,
+  describeDerivedSource,
+  explainNotSettable,
+  isDerivedVariable,
+} from '../../services/config-provenance';
 import {
   deleteModuleConfig,
   formatConfigValue,
@@ -27,6 +34,7 @@ import {
   getModuleConfigValue,
   setModuleConfigValue,
 } from '../../services/module-config';
+import { readResolutionContext } from '../../variables/context';
 import { getArg, validateRequiredArgs } from '../parser';
 import type { CommandResult } from '../types';
 
@@ -180,17 +188,14 @@ export async function handleModuleConfigSet(args: string[]): Promise<CommandResu
   const isFrameworkKey = key in FRAMEWORK_CONFIG_KEYS;
 
   // Validate key against manifest
-  const manifest = module.manifestData as Record<string, unknown>;
-  const variables = manifest.variables as
-    | { owns?: Array<{ name: string; required?: boolean; default?: string; source?: string }> }
-    | undefined;
-  const declaredVars = variables?.owns || [];
+  const manifest = module.manifestData as ModuleManifest;
+  const declaredVars = manifest.variables?.owns ?? [];
 
   // Check if key is declared in manifest
   const declaredVar = declaredVars.find((v) => v.name === key);
   if (!declaredVar && !isFrameworkKey) {
     const settableKeys = declaredVars
-      .filter((v) => v.source !== 'infrastructure')
+      .filter((v) => !isDerivedVariable(v))
       .map((v) => v.name)
       .join(', ');
     const frameworkKeys = Object.keys(FRAMEWORK_CONFIG_KEYS).join(', ');
@@ -200,15 +205,23 @@ export async function handleModuleConfigSet(args: string[]): Promise<CommandResu
     };
   }
 
-  // ISS-0069: reject infrastructure-managed keys at SET time rather than
-  // accepting-then-silently-overriding them at deploy. `source: infrastructure`
-  // variables (vmid, target_ip, target_node, gateway, vlan, lxc_template) are
-  // derived by the deploy (IPAM allocates vmid/IP; the container service supplies
-  // node/template/gateway/vlan), so a value set here would be ignored.
-  if (declaredVar?.source === 'infrastructure') {
+  // Refuse EVERY derived source, not just `infrastructure`.
+  //
+  // ISS-0069 established the principle — refuse at SET time rather than
+  // accepting-then-silently-overriding at deploy — and then applied it to one
+  // source out of four. So `celilo module config set authentik auth_url …`
+  // (a `capability`-sourced value) reported success, wrote the row, and was
+  // discarded on the next deploy. A command that says "Set config for authentik"
+  // and changes nothing is worse than one that refuses.
+  //
+  // No counter-example survived review of a good reason to pin a derived value:
+  // a derived value computes the right answer from one source of truth, so if
+  // the answer is wrong the source is wrong, and fixing the source fixes every
+  // consumer at once while pinning one module hides the divergence.
+  if (declaredVar && isDerivedVariable(declaredVar)) {
     return {
       success: false,
-      error: `'${key}' is infrastructure-managed by celilo (source: infrastructure) — not operator-settable.\nThe deploy derives it automatically, so a value set here would be silently ignored.\n  • node placement: set the service default for NEW deploys (celilo service reconfigure); move an existing container with 'celilo proxmox migrate' (ISS-0062).\n  • vmid / IP: auto-allocated by IPAM.`,
+      error: explainNotSettable(moduleId, declaredVar),
     };
   }
 
@@ -354,10 +367,24 @@ export async function handleModuleConfigGet(args: string[]): Promise<CommandResu
     };
   }
 
-  // Get all config for module
-  const configs = getAllModuleConfigValues(moduleId);
+  // Get all config for module, split by who owns each value.
+  //
+  // Printing every row flat presented a value celilo computed as if the
+  // operator had chosen it, which is how a derived value gets "corrected" by
+  // hand and silently reverted. The derived section is also read from the
+  // resolution context rather than the config rows, so it shows what celilo
+  // computes RIGHT NOW — including values that were never written down, the
+  // absence that caused the 2026-08-14 DNS outage.
+  const declared = declaredVariables(module.manifestData as ModuleManifest);
+  const stored = getAllModuleConfigValues(moduleId);
+  const userConfigs = stored.filter((c) => {
+    const variable = declared.get(c.key);
+    return !variable || !isDerivedVariable(variable);
+  });
+
+  const derivedValues = await resolveDerivedForDisplay(moduleId, declared, db);
 
-  if (configs.length === 0) {
+  if (userConfigs.length === 0 && derivedValues.length === 0) {
     return {
       success: true,
       message: `No configuration set for ${moduleId}`,
@@ -365,14 +392,70 @@ export async function handleModuleConfigGet(args: string[]): Promise<CommandResu
   }
 
   const lines = [`Configuration for ${moduleId}:`, ''];
-  for (const config of configs) {
-    const formatted = formatConfigValue(config);
-    lines.push(`${config.key} = ${formatted}`);
+  if (userConfigs.length > 0) {
+    for (const config of userConfigs) {
+      lines.push(`${config.key} = ${formatConfigValue(config)}`);
+    }
+  } else {
+    lines.push('(nothing set by you)');
+  }
+
+  if (derivedValues.length > 0) {
+    lines.push('', 'Derived by celilo (not settable — fix the source instead):', '');
+    for (const derived of derivedValues) {
+      lines.push(`${derived.key} = ${derived.value}`);
+      lines.push(`    ${describeDerivedSource(derived.variable)}`);
+    }
   }
 
   return {
     success: true,
     message: lines.join('\n'),
-    data: configs.map((c) => ({ key: c.key, value: c.value })),
+    data: {
+      config: userConfigs.map((c) => ({ key: c.key, value: c.value })),
+      derived: derivedValues.map((d) => ({
+        key: d.key,
+        value: d.value,
+        source: d.variable.source,
+      })),
+    },
   };
 }
+
+/**
+ * The current value of each derived variable, for display only.
+ *
+ * Uses the side-effect-free resolution context: reading a config must not seed
+ * rows or allocate addresses. A module whose derives cannot resolve yet (an
+ * undeployed provider, an unset system key) reports nothing derived rather than
+ * failing the whole command — `get` is how an operator diagnoses that state, so
+ * it has to survive it.
+ */
+async function resolveDerivedForDisplay(
+  moduleId: string,
+  declared: Map<string, VariableDeclare>,
+  db: ReturnType<typeof getDb>,
+): Promise<Array<{ key: string; value: string; variable: VariableDeclare }>> {
+  const derivedVars = [...declared.values()].filter(isDerivedVariable);
+  if (derivedVars.length === 0) return [];
+
+  let selfConfig: Record<string, string>;
+  try {
+    selfConfig = (await readResolutionContext(moduleId, db)).selfConfig;
+  } catch {
+    // Reported as "not computed yet" below rather than as an error, so the
+    // command still shows the operator their own config.
+    return [];
+  }
+
+  const resolved: Array<{ key: string; value: string; variable: VariableDeclare }> = [];
+  for (const variable of derivedVars) {
+    const value = selfConfig[variable.name];
+    resolved.push({
+      key: variable.name,
+      value: value ?? '(not computed yet)',
+      variable,
+    });
+  }
+  return resolved;
+}

package/src/cli/commands/module-status.ts

@@ -21,6 +21,7 @@ import {
   effectiveBackupSchedule,
 } from '../../services/backup-schedule';
 import { formatCadence } from '../../services/cadence';
+import { declaredVariables, isDerivedVariable } from '../../services/config-provenance';
 import { getModuleSystems } from '../../services/deployed-systems';
 import { configOverride, parseStoredConfigValue } from '../../services/module-config';
 import { formatPlacementLine, reconcilePlacement } from '../../services/placement-reconcile';
@@ -210,22 +211,40 @@ export async function handleModuleStatus(args: string[]): Promise<CommandResult>
     sections.push(placementLines.join('\n'));
   }
 
-  // Section 2: Configuration
-  if (configs.length > 0) {
-    const configLines = ['Configuration:'];
-    for (const config of configs) {
-      // `value` is the human-readable display form (e.g. "test-host"
-      // for a string, "2222" for a number, JSON-stringified for
-      // complex types) — populated by upsertModuleConfig alongside
-      // the canonical valueJson. Using it here keeps the status
-      // output free of JSON-quote noise around primitives.
-      configLines.push(`  ${config.key}: ${config.value}`);
-    }
-    sections.push(configLines.join('\n'));
+  // Section 2: Configuration, split by who owns each value. A flat list
+  // presented a value celilo computed as if the operator had chosen it, which
+  // is how a derived value gets "corrected" by hand and silently reverted.
+  // `source` is the authority for the split, never the presence of a
+  // `derive_from` — see services/config-provenance.ts.
+  const declared = declaredVariables(module.manifestData as ModuleManifest);
+  const isDerivedKey = (key: string) => {
+    const variable = declared.get(key);
+    return variable !== undefined && isDerivedVariable(variable);
+  };
+  // `value` is the human-readable display form (e.g. "test-host" for a string,
+  // "2222" for a number, JSON-stringified for complex types) — populated by
+  // upsertModuleConfig alongside the canonical valueJson. Using it here keeps
+  // the status output free of JSON-quote noise around primitives.
+  const userConfigs = configs.filter((c) => !isDerivedKey(c.key));
+  const derivedConfigs = configs.filter((c) => isDerivedKey(c.key));
+
+  if (userConfigs.length > 0) {
+    sections.push(
+      ['Configuration:', ...userConfigs.map((c) => `  ${c.key}: ${c.value}`)].join('\n'),
+    );
   } else {
     sections.push('Configuration: (none)');
   }
 
+  if (derivedConfigs.length > 0) {
+    sections.push(
+      [
+        'Derived by celilo (not settable):',
+        ...derivedConfigs.map((c) => `  ${c.key}: ${c.value}  [${declared.get(c.key)?.source}]`),
+      ].join('\n'),
+    );
+  }
+
   // Section 2b: Per-module policy — what celilo will DO to this module, and
   // whether that came from the operator or from the module's author. A raw
   // config key does not tell an operator what the manifest said, and an

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',