@celilo/cli 0.24.0 → 0.25.0

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/hooks/load-hook-config.test.ts

@@ -17,8 +17,9 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
-import { machines, moduleInfrastructure, modules } from '../db/schema';
+import { machines, moduleConfigs, moduleInfrastructure, modules, systemConfig } from '../db/schema';
 import { upsertModuleConfig } from '../services/module-config';
 import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
 import { loadHookConfigMap } from './load-hook-config';
@@ -165,3 +166,170 @@ describe('loadHookConfigMap', () => {
     expect(result['ip.primary']).toBeUndefined();
   });
 });
+
+/**
+ * The 2026-08-14 outage, as a test.
+ *
+ * `technitium` declares `vpn_subnet` with `source: system` and
+ * `derive_from: $system:network.control-plane-vpn.subnet`. The system key was
+ * set on the fleet AFTER the module had already been configured, so no
+ * `module_configs` row was ever written for it — `applyDeclarativeDerivations`
+ * skips a `source: system` variable once the module has any stored config for
+ * it, and nothing re-derives one that is absent. The variable is
+ * `required: false`, so deploy-validation passed without comment.
+ *
+ * The consumer was a capability factory, which gets its config from
+ * `loadHookConfigMap`. A direct `module_configs` select cannot see a value that
+ * was never stored, so the factory built split-horizon DNS with no view for the
+ * admin VPN: queries from it matched nothing, returned NOERROR with zero
+ * records, fell through to public DNS, and the operator could not reach the
+ * forge while every service reported healthy.
+ *
+ * The fix is that the hook config map is built from the resolution context —
+ * which recomputes derived values on every build — not from the table alone.
+ */
+describe('loadHookConfigMap: derived values the config table never stored', () => {
+  let db: DbClient;
+
+  const VPN_SUBNET_KEY = 'network.control-plane-vpn.subnet';
+  const VPN_SUBNET = '10.255.255.0/24';
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+    db.insert(modules)
+      .values({
+        id: 'technitium',
+        name: 'Technitium DNS',
+        version: '1.0.0',
+        sourcePath: '/tmp/technitium',
+        manifestData: {
+          variables: {
+            owns: [
+              { name: 'hostname', type: 'string', source: 'user' },
+              {
+                name: 'vpn_subnet',
+                type: 'string',
+                source: 'system',
+                required: false,
+                derive_from: `$system:${VPN_SUBNET_KEY}`,
+              },
+            ],
+          },
+        },
+      })
+      .run();
+    // The module was configured first: it has its user rows, and no row for
+    // the derived variable.
+    upsertModuleConfig(db, 'technitium', 'hostname', 'dns-int');
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  test('a hook sees a source:system derive whose system key was set after the module was configured', async () => {
+    db.insert(systemConfig).values({ key: VPN_SUBNET_KEY, value: VPN_SUBNET }).run();
+
+    const result = await loadHookConfigMap('technitium', db);
+
+    expect(result.hostname).toBe('dns-int');
+    expect(result.vpn_subnet).toBe(VPN_SUBNET);
+  });
+
+  test('recomputing does not write the derived value back into module_configs', async () => {
+    db.insert(systemConfig).values({ key: VPN_SUBNET_KEY, value: VPN_SUBNET }).run();
+
+    await loadHookConfigMap('technitium', db);
+
+    // Reading a hook's config is not a deploy. It must not seed or refresh
+    // stored config as a side effect — that is how a stale snapshot gets
+    // written in the first place.
+    const stored = db
+      .select()
+      .from(moduleConfigs)
+      .where(eq(moduleConfigs.moduleId, 'technitium'))
+      .all();
+    expect(stored.map((row) => row.key).sort()).toEqual(['hostname']);
+  });
+
+  test('an optional derive whose system key is still unset stays absent, not an error', async () => {
+    // No systemConfig row at all — the state the fleet was in before the VPN
+    // subnet was declared. `required: false`, so this is silence, not failure.
+    const result = await loadHookConfigMap('technitium', db);
+
+    expect(result.hostname).toBe('dns-int');
+    expect(result.vpn_subnet).toBeUndefined();
+  });
+
+  test('an already-stored value reaches the hook unchanged', async () => {
+    // Precedence: a stored row wins, and the recomputed context only fills
+    // keys the table has no row for. Every derived value on the fleet today is
+    // stored, so this is what keeps the new read path from changing what any
+    // deployed hook already receives — the change is purely additive here.
+    // (Once derived values stop being persisted, the stored row disappears and
+    // the recomputed value is all that is left.)
+    db.insert(systemConfig).values({ key: VPN_SUBNET_KEY, value: VPN_SUBNET }).run();
+    upsertModuleConfig(db, 'technitium', 'vpn_subnet', '10.99.0.0/24');
+
+    const result = await loadHookConfigMap('technitium', db);
+
+    expect(result.vpn_subnet).toBe('10.99.0.0/24');
+  });
+});
+
+/**
+ * Recomputation must not make a hook's config LESS available than reading the
+ * table did.
+ *
+ * `applyDeclarativeDerivations` throws when a `required: true` variable's
+ * derivation fails, which at generate time is exactly right — a deploy that
+ * cannot resolve a required value should stop. But this reader also serves
+ * health checks and `module run-hook`, which used to be unable to fail this
+ * way at all: they read stored rows, and a stored row cannot throw. A provider
+ * that is paused, removed, or not yet deployed would take its consumers'
+ * health checks down with it — reporting the consumer as broken when the
+ * consumer is fine.
+ */
+describe('loadHookConfigMap: a failing derive does not take the hook down', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+    db.insert(modules)
+      .values({
+        id: 'caddy',
+        name: 'Caddy',
+        version: '1.0.0',
+        sourcePath: '/tmp/caddy',
+        manifestData: {
+          variables: {
+            owns: [
+              { name: 'hostname', type: 'string', source: 'user' },
+              {
+                name: 'primary_domain',
+                type: 'string',
+                source: 'capability',
+                required: true,
+                derive_from: '$capability:dns_registrar.zone.primary_domain',
+              },
+            ],
+          },
+        },
+      })
+      .run();
+    upsertModuleConfig(db, 'caddy', 'hostname', 'caddy');
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  test('stored config still reaches the hook when a required derive cannot resolve', async () => {
+    // No `dns_registrar` capability is registered — the provider is paused,
+    // removed, or has not been deployed yet.
+    const result = await loadHookConfigMap('caddy', db);
+
+    expect(result.hostname).toBe('caddy');
+    expect(result.primary_domain).toBeUndefined();
+  });
+});

package/src/hooks/load-hook-config.ts

@@ -11,30 +11,65 @@
  * `capability-loader.ts:loadModuleConfig` had — same shape, different
  * code, easy to miss.
  *
- * The shape:
- *   - Every row from `module_configs`, parsed from `valueJson` via
- *     the shared `parseStoredConfigValue` helper. This preserves the
- *     types declared in each module's manifest: `number` reads as
- *     `number`, `boolean` as `boolean`, complex types as their
- *     parsed JSON shape. Pre-Defect-1, this path returned raw strings
- *     for primitives (because `valueJson` was NULL for them); that
- *     broke capability calls like `firewall.exposeService({ports:[...]})`
- *     that did a `typeof === 'number'` check downstream. Fixed in
- *     v2 by always populating valueJson on write.
- *   - If `target_ip` isn't in the row set, look up the deployment
- *     machine and inject both `target_ip` AND `ip.primary` from
- *     `machines.ipAddress`. Two keys because consumers historically used
- *     either name (e.g. caddy's `setup-network.ts` checks
- *     `target_ip || ip.primary`); fixing the drift means filling both.
+ * The shape, in the order the layers are applied:
+ *   1. Every row from `module_configs`, parsed from `valueJson` via
+ *      the shared `parseStoredConfigValue` helper. This preserves the
+ *      types declared in each module's manifest: `number` reads as
+ *      `number`, `boolean` as `boolean`, complex types as their
+ *      parsed JSON shape. Pre-Defect-1, this path returned raw strings
+ *      for primitives (because `valueJson` was NULL for them); that
+ *      broke capability calls like `firewall.exposeService({ports:[...]})`
+ *      that did a `typeof === 'number'` check downstream. Fixed in
+ *      v2 by always populating valueJson on write.
+ *   2. If `target_ip` isn't in the row set, look up the deployment
+ *      machine and inject both `target_ip` AND `ip.primary` from
+ *      `machines.ipAddress`. Two keys because consumers historically used
+ *      either name (e.g. caddy's `setup-network.ts` checks
+ *      `target_ip || ip.primary`); fixing the drift means filling both.
+ *   3. For each variable the module's manifest declares, the value the
+ *      resolution context currently computes — but only where the first two
+ *      layers left that key unset. See below.
  *
  * Container deploys write `target_ip` into `module_configs` explicitly
  * during generate/deploy, so the fallback only fires for machine
  * deploys (existing iron, no terraform — what every e2e test uses).
+ *
+ * ## Why layer 3 exists
+ *
+ * A derived variable — one whose value comes from system config, a
+ * capability, or the selected infrastructure rather than from the operator —
+ * only reaches a hook through this map. Reading `module_configs` alone can
+ * only see the derives that happen to have been WRITTEN there, and one that
+ * was never written is indistinguishable from one that does not exist.
+ *
+ * On 2026-08-14 that was not a theoretical gap. `technitium`'s `vpn_subnet`
+ * (`source: system`) had no row, because the system key was set after the
+ * module was configured and nothing re-derives a `source: system` value that
+ * is already absent. Being `required: false`, deploy-validation passed in
+ * silence. The capability factory that builds split-horizon DNS therefore
+ * built no view for the admin VPN; queries from it matched nothing, returned
+ * NOERROR with zero records, fell through to public DNS, and the operator
+ * could not reach the forge while every service reported healthy.
+ *
+ * So the map is completed from `readResolutionContext` — the same computation
+ * a build does, run without any of a build's side effects. Stored rows still
+ * win, which is what makes this purely additive for every value already on
+ * the fleet; the context only supplies what the table is missing. Context
+ * values arrive as strings (declarative derivation resolves string templates
+ * only), so this layer never overwrites a typed row with a stringified one.
+ *
+ * It is narrowed to the manifest's declared variables on purpose. The
+ * resolution context also carries values that exist to drive template
+ * generation — `inventory.*`, `requires.system.*`, `lxc_nameserver` — which a
+ * hook has no business reading and which have never appeared in this map.
+ * Widening a hook's view of the world is not what this layer is for.
  */
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
-import { machines, moduleConfigs, moduleInfrastructure } from '../db/schema';
+import { machines, moduleConfigs, moduleInfrastructure, modules } from '../db/schema';
+import type { ModuleManifest } from '../manifest/schema';
 import { parseStoredConfigValue } from '../services/module-config';
+import { readResolutionContext } from '../variables/context';
 
 export async function loadHookConfigMap(
   moduleId: string,
@@ -51,19 +86,82 @@ export async function loadHookConfigMap(
     configMap[c.key] = parseStoredConfigValue(c);
   }
 
-  if (configMap.target_ip) return configMap;
+  applyMachineAddressFallback(configMap, moduleId, db);
+  await applyRecomputedDerivedValues(configMap, moduleId, db);
+
+  return configMap;
+}
+
+/**
+ * Fill in the declared variables the config rows have no value for, using the
+ * value the resolution context computes right now. Mutates `configMap`.
+ */
+async function applyRecomputedDerivedValues(
+  configMap: Record<string, unknown>,
+  moduleId: string,
+  db: DbClient,
+): Promise<void> {
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module?.manifestData) return;
+
+  const declared = (module.manifestData as ModuleManifest).variables?.owns ?? [];
+  const missing = declared.filter((variable) => !(variable.name in configMap));
+  if (missing.length === 0) return;
+
+  let context: Awaited<ReturnType<typeof readResolutionContext>>;
+  try {
+    context = await readResolutionContext(moduleId, db);
+  } catch (error) {
+    // Derivation THROWS when a `required: true` variable cannot be resolved —
+    // correct at generate time, where a deploy that cannot resolve a required
+    // value should stop. This reader also serves health checks and
+    // `module run-hook`, which previously could not fail this way at all: a
+    // stored row cannot throw. Letting it propagate would mean a provider that
+    // is paused, removed, or not yet deployed takes down the health checks of
+    // every module that derives from it, reporting healthy consumers as
+    // broken.
+    //
+    // So the hook falls back to what the table holds — exactly what it
+    // received before recomputation existed, never less. Logged rather than
+    // swallowed (Rule 6.2): a derive that cannot resolve is worth knowing
+    // about even when the hook survives it.
+    console.error(
+      `Could not recompute derived config for '${moduleId}'; the hook sees only its stored config. ` +
+        `Derived values (${missing.map((v) => v.name).join(', ')}) may be missing:`,
+      error,
+    );
+    return;
+  }
+
+  for (const variable of missing) {
+    const value = context.selfConfig[variable.name];
+    if (value !== undefined) {
+      configMap[variable.name] = value;
+    }
+  }
+}
+
+/**
+ * Fill `target_ip` / `ip.primary` from the deployment machine when the config
+ * rows carry no address of their own. Mutates `configMap` in place.
+ */
+function applyMachineAddressFallback(
+  configMap: Record<string, unknown>,
+  moduleId: string,
+  db: DbClient,
+): void {
+  if (configMap.target_ip) return;
 
   const infra = db
     .select()
     .from(moduleInfrastructure)
     .where(eq(moduleInfrastructure.moduleId, moduleId))
     .get();
-  if (!infra?.machineId) return configMap;
+  if (!infra?.machineId) return;
 
   const machine = db.select().from(machines).where(eq(machines.id, infra.machineId)).get();
-  if (!machine) return configMap;
+  if (!machine) return;
 
   configMap.target_ip = machine.ipAddress;
   configMap['ip.primary'] = machine.ipAddress;
-  return configMap;
 }

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']);
+  });
+});