@celilo/cli 0.24.0 → 0.25.0

package/src/manifest/schema.ts

@@ -354,6 +354,68 @@ export const SystemResourceSchema = z.object({
   zone: z.enum(NETWORK_ZONES).describe('Required security zone for this module'),
 });
 
+/**
+ * A network a module depends on, declared under `requires.networks`
+ * (openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md).
+ *
+ * It names the network and stops there. celilo owns the network namespace: the
+ * range belongs to the operator's topology, not to whichever module happens to
+ * arrive first and need it. A module that carried the value here would be
+ * defining the network by another route, which is the authority this change
+ * reverses — so `.strict()` is load-bearing rather than tidiness, and its
+ * message says why.
+ *
+ * When the named network has no `network.<name>.subnet` in system config, the
+ * deploy asks for one BEFORE anything is generated or any hook runs
+ * ([[services/network-ensure.ts]]).
+ *
+ * ── Two forms, because some requirements are not knowable at authoring time ──
+ *
+ * `name:` is a literal — `wireguard` always needs `control-plane-vpn`, and says
+ * so once. `from:` names a config array whose VALUES are the network names, for
+ * a module whose set is decided per install: a firewall requires the networks it
+ * has legs on, and which legs it has is a property of the box it lands on.
+ *
+ * `from:` is not a loophole in "a requirement carries no value". It still names
+ * networks and still carries none — it just names them indirectly. What it fixes
+ * is the split that `firewall-interface-classification` §3 already diagnosed from
+ * the harness side: the legs a firewall has and the networks it declares were two
+ * hand-maintained lists, and every one of the ~20 call sites that had to keep
+ * them in step got it wrong. A leg whose network has no declared subnet
+ * classifies `alien`, so under-declaring is not cosmetic — it is how an interface
+ * gets isolated. One list makes that structurally impossible.
+ */
+export const NetworkRequirementSchema = z
+  .object({
+    name: z
+      .string()
+      .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'network name must be kebab-case')
+      .describe('Name of a network this module needs defined before it deploys')
+      .optional(),
+    from: z
+      .string()
+      .regex(
+        /^\$self:[a-zA-Z_][a-zA-Z0-9_]*$/,
+        'from must reference one of this module\'s own config values, e.g. "$self:zones"',
+      )
+      .describe('A config array whose values are network names, e.g. "$self:zones"')
+      .optional(),
+  })
+  .strict(
+    'A network requirement NAMES networks; it never carries their values. celilo owns ' +
+      'the network namespace — the range is supplied before the deploy runs — so a ' +
+      'requirement takes `name:` (a literal) or `from:` (a $self: config array of names) ' +
+      'and nothing else. Read the range with `source: system` / ' +
+      '`derive_from: "$system:network.<name>.subnet"`.',
+  )
+  .refine((requirement) => Boolean(requirement.name) !== Boolean(requirement.from), {
+    message:
+      'A network requirement declares exactly one of `name:` (a literal network) or ' +
+      '`from:` (a $self: config array whose values are network names)',
+  });
+
+export type NetworkRequirement = z.infer<typeof NetworkRequirementSchema>;
+
 /**
  * One system a module deploys (openspec/specs/module-systems-addressing/spec.md). A module
  * declares 0..N of these under `requires.systems`. `name` is the stable
@@ -505,6 +567,11 @@ export const ModuleManifestSchema = z
          * `systems` gets one host per entry, each addressable as `$infra:<name>`.
          */
         systems: z.array(SystemDeclarationSchema).optional(),
+        /**
+         * Networks that must be DEFINED in celilo's own config before this
+         * module deploys. Names only — see `NetworkRequirementSchema`.
+         */
+        networks: z.array(NetworkRequirementSchema).optional(),
         /**
          * Singular form — sugar for a single unnamed system. Normalized to one
          * `systems` entry (name `main`) by `getDeclaredSystems`. Optional because
@@ -857,3 +924,60 @@ export function getDeclaredSystems(manifest: ModuleManifest): SystemDeclaration[
 export function getSingularSystemSpec(manifest: ModuleManifest): SystemResource | undefined {
   return manifest.requires?.system;
 }
+
+/**
+ * The network names a module requires
+ * (openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md).
+ * Deduplicated and in declaration order. Empty for the modules that depend on no
+ * network, which is most of them.
+ *
+ * `from:` entries are resolved against `config` — the module's own values, as
+ * answered by the config interview. A module whose required set is decided per
+ * install (a firewall requires the networks it has legs on) therefore needs its
+ * config populated before this is meaningful, which is why the ensure runs after
+ * the config interview and before generation.
+ *
+ * `external` is dropped wherever it appears. It 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 — so giving it one would reintroduce the
+ * overload that `readDeclaredNetworks` and `deployFirewall` both already exclude.
+ */
+export function getRequiredNetworkNames(
+  manifest: ModuleManifest,
+  config: Record<string, unknown> = {},
+): string[] {
+  const names: string[] = [];
+  for (const requirement of manifest.requires?.networks ?? []) {
+    if (requirement.name) {
+      names.push(requirement.name);
+      continue;
+    }
+    if (!requirement.from) continue;
+    const key = requirement.from.slice('$self:'.length);
+    names.push(...asNetworkNameArray(config[key]));
+  }
+  return [...new Set(names)].filter((name) => name !== 'external');
+}
+
+/**
+ * Narrow a `from:`-referenced config value to network names.
+ *
+ * Tolerates the JSON-string form as well as a real array: an array config value
+ * arrives as either depending on how it was written, and a requirement that
+ * silently resolved to nothing would leave a leg undeclared — which is the
+ * failure this whole mechanism exists to prevent.
+ */
+function asNetworkNameArray(raw: unknown): string[] {
+  const value =
+    typeof raw === 'string' && raw.trim().startsWith('[')
+      ? (() => {
+          try {
+            return JSON.parse(raw) as unknown;
+          } catch {
+            return undefined;
+          }
+        })()
+      : raw;
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === 'string' && entry.length > 0);
+}

package/src/services/config-provenance.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Who owns a config value — the operator, or celilo.
+ *
+ * The load-bearing case here is the one that looks like a special case and is
+ * not: `derive_from` does NOT mean derived. Getting that backwards refuses an
+ * operator's edit to their own config, and a migration written on the same test
+ * would delete the row.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { VariableDeclare } from '../manifest/schema';
+import {
+  declaredVariables,
+  describeDerivedSource,
+  explainNotSettable,
+  isDerivedVariable,
+} from './config-provenance';
+
+function variable(overrides: Partial<VariableDeclare> & { name: string }): VariableDeclare {
+  return {
+    type: 'string',
+    required: false,
+    source: 'user',
+    ...overrides,
+  } as VariableDeclare;
+}
+
+describe('isDerivedVariable', () => {
+  test('a user-sourced variable is the operator’s', () => {
+    expect(isDerivedVariable(variable({ name: 'acme_email', source: 'user' }))).toBe(false);
+  });
+
+  test.each(['capability', 'system', 'infrastructure', 'terraform'] as const)(
+    'a %s-sourced variable is celilo’s',
+    (source) => {
+      expect(isDerivedVariable(variable({ name: 'x', source }))).toBe(true);
+    },
+  );
+
+  test('a variable with NO declared source reads as the operator’s', () => {
+    // The manifest schema requires `source`, so this only happens for a
+    // malformed or pre-schema manifest already sitting in `manifest_data`. The
+    // question is which way to be wrong: guessing "derived" refuses an
+    // operator's `set` with a message insisting celilo owns a value nothing
+    // computes, which they cannot act on.
+    const noSource = {
+      name: 'app_port',
+      type: 'integer',
+      required: false,
+    } as unknown as VariableDeclare;
+
+    expect(isDerivedVariable(noSource)).toBe(false);
+  });
+
+  test('a user-sourced variable WITH a derive_from is still the operator’s', () => {
+    // iptables: `firewall_ip`, `source: user`, `derive_from: $machine:ipAddress`.
+    // `$machine:` derives are answered by the config interview — they seed a
+    // default the operator confirms — so the row is operator config. Classing
+    // it as derived would refuse an operator correcting their own firewall
+    // address, and deleting it on the same test would blind the trusted-sources
+    // audit in services/firewall-reach.ts, which reads exactly this row.
+    const firewallIp = variable({
+      name: 'firewall_ip',
+      source: 'user',
+      required: true,
+      derive_from: '$machine:ipAddress',
+    });
+
+    expect(isDerivedVariable(firewallIp)).toBe(false);
+  });
+});
+
+describe('declaredVariables', () => {
+  test('indexes a manifest’s owned variables by name', () => {
+    const declared = declaredVariables({
+      variables: {
+        owns: [variable({ name: 'hostname' }), variable({ name: 'vpn_subnet', source: 'system' })],
+      },
+    } as never);
+
+    expect([...declared.keys()].sort()).toEqual(['hostname', 'vpn_subnet']);
+    expect(declared.get('vpn_subnet')?.source).toBe('system');
+  });
+
+  test('a manifest declaring nothing yields an empty index, not a throw', () => {
+    expect(declaredVariables({} as never).size).toBe(0);
+  });
+});
+
+describe('explainNotSettable', () => {
+  test('a capability-sourced value points at the provider, not at this module', () => {
+    // The live footgun: `celilo module config set authentik auth_url …`
+    // reported success, wrote the row, and was discarded on the next deploy.
+    const message = explainNotSettable(
+      'authentik',
+      variable({
+        name: 'auth_url',
+        source: 'capability',
+        derive_from: '$capability:authentication.url',
+      }),
+    );
+
+    expect(message).toContain('not operator-settable');
+    expect(message).toContain('source: capability');
+    // Actionable: the only way to change a derived value is to fix its source.
+    expect(message).toContain('provider');
+    expect(message).toContain('redeploy');
+  });
+
+  test('a system-sourced value names the system key to set', () => {
+    const message = explainNotSettable(
+      'technitium',
+      variable({
+        name: 'vpn_subnet',
+        source: 'system',
+        derive_from: '$system:network.control-plane-vpn.subnet',
+      }),
+    );
+
+    // The operator should be able to copy the fix out of the error. The
+    // `$system:` prefix is stripped so the key is the one `system config set`
+    // actually takes.
+    expect(message).toContain('celilo system config set network.control-plane-vpn.subnet');
+  });
+
+  test('an infrastructure-sourced value keeps the placement guidance', () => {
+    const message = explainNotSettable(
+      'caddy',
+      variable({ name: 'vmid', source: 'infrastructure' }),
+    );
+
+    expect(message).toContain('IPAM');
+    expect(message).toContain('celilo proxmox migrate');
+  });
+});
+
+describe('describeDerivedSource', () => {
+  test('names the upstream, and the template when there is one', () => {
+    expect(
+      describeDerivedSource(
+        variable({
+          name: 'dmz_subnet',
+          source: 'system',
+          derive_from: '$system:network.dmz.subnet',
+        }),
+      ),
+    ).toBe('from system config ($system:network.dmz.subnet)');
+  });
+
+  test('degrades to the upstream alone when no template is declared', () => {
+    expect(describeDerivedSource(variable({ name: 'vmid', source: 'infrastructure' }))).toContain(
+      'infrastructure celilo selected',
+    );
+  });
+});

package/src/services/config-provenance.ts

@@ -0,0 +1,104 @@
+/**
+ * Who owns a module-config value: the operator, or celilo.
+ *
+ * A module's manifest declares a `source` for every variable it owns. `user`
+ * means the operator supplies it. Every other source — `capability`, `system`,
+ * `infrastructure`, `terraform` — means celilo computes it from somewhere else:
+ * another module's published capability data, system config, the selected
+ * infrastructure, a Terraform output.
+ *
+ * That distinction has to be shared rather than re-derived per command, because
+ * it was previously spelled differently in each place and the disagreements were
+ * silent. `module config set` refused only `source: infrastructure`, so setting
+ * a `capability`- or `system`-sourced value REPORTED SUCCESS, wrote the row, and
+ * was then discarded on the next deploy —
+ * `celilo module config set authentik auth_url …` being the live example. And
+ * `module config get` printed every row flat, so a value celilo derived was
+ * indistinguishable from one the operator had chosen.
+ *
+ * ## `derive_from` does not mean derived
+ *
+ * The tempting shortcut is "it has a `derive_from` template, so celilo computes
+ * it". That is wrong, and expensively so. `iptables` declares:
+ *
+ *     - name: firewall_ip
+ *       source: user
+ *       derive_from: "$machine:ipAddress"
+ *
+ * `$machine:` derivations are answered by the config interview — they seed a
+ * default the operator confirms — not by template resolution. The row is
+ * operator config. Treating it as derived would refuse an operator's attempt to
+ * correct their own firewall address, and a migration that deleted rows on the
+ * same test would blind the trusted-sources audit that reads it.
+ *
+ * `source` is the authority. Nothing else is.
+ */
+import type { ModuleManifest, VariableDeclare } from '../manifest/schema';
+
+/**
+ * Does celilo compute this variable, rather than the operator supply it?
+ *
+ * An ABSENT source reads as the operator's. The manifest schema requires
+ * `source`, so absent means a malformed or pre-schema manifest sitting in
+ * `modules.manifest_data` — and for those the question is which way to be
+ * wrong. Guessing "derived" refuses an operator's attempt to set their own
+ * config with a message insisting celilo owns a value nothing computes, which
+ * is unanswerable. Guessing "user" preserves what celilo did before this
+ * predicate existed, when only `infrastructure` was refused.
+ */
+export function isDerivedVariable(variable: Pick<VariableDeclare, 'source'>): boolean {
+  return variable.source !== undefined && variable.source !== 'user';
+}
+
+/** Every variable a module's manifest declares, indexed by name. */
+export function declaredVariables(manifest: ModuleManifest): Map<string, VariableDeclare> {
+  return new Map((manifest.variables?.owns ?? []).map((variable) => [variable.name, variable]));
+}
+
+/**
+ * A one-line explanation of where a derived value comes from, for output an
+ * operator reads. Says which upstream to go fix, since fixing the source is the
+ * only way to change a derived value.
+ */
+export function describeDerivedSource(variable: VariableDeclare): string {
+  switch (variable.source) {
+    case 'capability':
+      return variable.derive_from
+        ? `from another module's capability data (${variable.derive_from})`
+        : "from another module's capability data";
+    case 'system':
+      return variable.derive_from
+        ? `from system config (${variable.derive_from})`
+        : 'from system config';
+    case 'infrastructure':
+      return 'from the infrastructure celilo selected for this module';
+    case 'terraform':
+      return 'from a Terraform output, at deploy time';
+    default:
+      return `computed by celilo (source: ${variable.source})`;
+  }
+}
+
+/**
+ * Why `module config set` refuses this variable, and what to do instead.
+ * Actionable per source: a derived value is only wrong because its upstream is
+ * wrong, and fixing the upstream fixes every consumer at once, where pinning one
+ * module hides the divergence.
+ */
+export function explainNotSettable(moduleId: string, variable: VariableDeclare): string {
+  const header = `'${variable.name}' is derived by celilo (source: ${variable.source}) — not operator-settable.`;
+  const origin = `It is computed ${describeDerivedSource(variable)}, so a value set here would be overwritten the next time ${moduleId} is generated.`;
+
+  switch (variable.source) {
+    case 'capability':
+      return `${header}\n${origin}\n  • Fix it at the provider: change the config of the module that publishes this capability, then redeploy it.\n  • 'celilo module config get ${moduleId}' shows the value celilo currently computes.`;
+    case 'system':
+      return `${header}\n${origin}\n  • Fix it at the source: 'celilo system config set ${variable.derive_from?.replace(/^\$\{?system:/, '').replace(/\}$/, '') ?? '<key>'} <value>'.\n  • That corrects every module deriving from it at once, rather than pinning this one.`;
+    case 'infrastructure':
+      return `${header}\n${origin}\n  • node placement: set the service default for NEW deploys (celilo service reconfigure); move an existing container with 'celilo proxmox migrate'.\n  • vmid / IP: auto-allocated by IPAM.`;
+    case 'terraform':
+      return `${header}\n${origin}\n  • It is read back from Terraform outputs after the deploy creates the resource.`;
+    default:
+      return `${header}\n${origin}`;
+  }
+}

package/src/services/module-deploy.ts

@@ -38,6 +38,7 @@ import { getModuleSystems } from './deployed-systems';
 import { E2E_CONFLICT_MESSAGE, runningE2eContainers } from './e2e-guard';
 import { resolveInfrastructureVariables } from './infrastructure-variable-resolver';
 import { findMachineForModule } from './machine-pool';
+import { ensureRequiredNetworks } from './network-ensure';
 import { checkProxmoxReachable, formatProxmoxUnreachableError } from './proxmox-preflight';
 import { republishStaticWebConsumers } from './public-web-republish';
 import { LOCAL_MACHINE_IP, deleteTemporarySshKey, writeTemporarySshKey } from './ssh-key-manager';
@@ -367,6 +368,32 @@ async function deployModuleImpl(
       return { success: false, error: E2E_CONFLICT_MESSAGE, phases };
     }
 
+    // Every network this module REQUIRES must be defined before ANYTHING else
+    // (openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md).
+    //
+    // First, not merely "before the hooks". `validateAndPrepareDeployment`
+    // generates templates itself when no variable is missing, and generation is
+    // where `$system:` derivations resolve and get persisted. A module reading
+    // `network.<name>.subnet` would derive it BEFORE the network existed, get
+    // nothing, and — because generation does not run twice — never get it. The
+    // hook would then fail on an unset value the deploy had just been told to
+    // supply. Ensuring the network up front is what makes "the value is
+    // available before any hook runs" true rather than nearly true.
+    const declaringModule = await db.select().from(modules).where(eq(modules.id, moduleId)).get();
+    if (declaringModule?.manifestData) {
+      const networksEnsured = await ensureRequiredNetworks(
+        moduleId,
+        declaringModule.manifestData as ModuleManifest,
+        db,
+      );
+      if (!networksEnsured.success) {
+        return { success: false, error: networksEnsured.error, phases };
+      }
+      for (const line of networksEnsured.applied) {
+        log.success(`network defined: ${line}`);
+      }
+    }
+
     const validation = await validateAndPrepareDeployment(moduleId, db);
     phases.validation = validation.success;
     phases.autoGenerated = validation.autoGenerated;
@@ -517,9 +544,10 @@ async function deployModuleImpl(
     // The bus-mediated interview has fired and any responders have
     // answered; the operator can inspect the encrypted store and
     // module config to confirm what landed without spinning up
-    // terraform / ansible / actual hooks. Cross-module `ensure`
-    // events fire later from hook execution, so they're NOT
-    // exercised here — that requires a real run.
+    // terraform / ansible / actual hooks. The required-network
+    // interview above HAS run by this point; the cross-module
+    // `ensure` events fire later from hook execution, so those are
+    // NOT exercised here — that requires a real run.
     if (options.stopAfterInterview) {
       log.info('--stop-after-interview: exiting before infrastructure phase.');
       return {

package/src/services/network-discovery.test.ts

@@ -0,0 +1,198 @@
+/**
+ * celilo discovering the network of the box it is installed on.
+ *
+ * These tests moved here with the code, from
+ * `modules/celilo-mgmt/scripts/discovery.test.ts`. They were always claims about
+ * CELILO — that it reflects whatever network it finds and bakes in no range of
+ * its own — being made in a module's test file because that is where the code
+ * happened to live
+ * (openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md).
+ *
+ * The headline test feeds a RANDOM RFC1918 /24 and asserts celilo uses exactly
+ * that: the product-level guarantee that no specific address range is baked in.
+ */
+
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { systemConfig } from '../db/schema';
+import { setupTestDatabase } from '../test-utils/database';
+import {
+  discoverAndRecordNetwork,
+  discoveredNetworkKeys,
+  parseInternalNetwork,
+} from './network-discovery';
+
+/** Build an `ip route` output for a given /24 base, gateway, and host IP. */
+function ipRouteFor(base: string, gateway: string, hostIp: string, dev = 'eth0'): string {
+  return [
+    `default via ${gateway} dev ${dev} proto dhcp src ${hostIp} metric 100`,
+    `${base}/24 dev ${dev} proto kernel scope link src ${hostIp} metric 100`,
+    '',
+  ].join('\n');
+}
+
+/** Pick a random RFC1918 /24 base + a host IP + gateway within it. */
+function randomRfc1918Slash24(): { base: string; gateway: string; hostIp: string } {
+  const r = Math.random();
+  let a: number;
+  let b: number;
+  if (r < 0.34) {
+    a = 10;
+    b = Math.floor(Math.random() * 256);
+  } else if (r < 0.67) {
+    a = 172;
+    b = 16 + Math.floor(Math.random() * 16); // 172.16–172.31
+  } else {
+    a = 192;
+    b = 168;
+  }
+  const c = Math.floor(Math.random() * 256);
+  return {
+    base: `${a}.${b}.${c}.0`,
+    gateway: `${a}.${b}.${c}.1`,
+    hostIp: `${a}.${b}.${c}.${10 + Math.floor(Math.random() * 200)}`,
+  };
+}
+
+describe('parseInternalNetwork', () => {
+  test('uses whatever /24 the host is actually on — no hard-coded range', () => {
+    for (let i = 0; i < 50; i++) {
+      const { base, gateway, hostIp } = randomRfc1918Slash24();
+      const result = parseInternalNetwork(ipRouteFor(base, gateway, hostIp));
+      expect(result).toEqual({ subnet: `${base}/24`, gateway });
+      // Guard against any latent assumption of the old default.
+      if (base !== '192.168.0.0') {
+        expect(result?.subnet).not.toBe('192.168.0.0/24');
+      }
+    }
+  });
+
+  test('parses a typical dhcp default route + connected subnet', () => {
+    const out = ipRouteFor('10.37.42.0', '10.37.42.1', '10.37.42.50');
+    expect(parseInternalNetwork(out)).toEqual({ subnet: '10.37.42.0/24', gateway: '10.37.42.1' });
+  });
+
+  test('honors a non-/24 prefix length', () => {
+    const out = [
+      'default via 172.20.0.1 dev ens3',
+      '172.20.0.0/16 dev ens3 proto kernel scope link src 172.20.5.9',
+    ].join('\n');
+    expect(parseInternalNetwork(out)).toEqual({ subnet: '172.20.0.0/16', gateway: '172.20.0.1' });
+  });
+
+  test('returns null when there is no default route', () => {
+    expect(parseInternalNetwork('10.0.0.0/24 dev eth0 proto kernel scope link src 10.0.0.5')).toBe(
+      null,
+    );
+  });
+
+  test('returns null when the connected subnet route is missing', () => {
+    expect(parseInternalNetwork('default via 10.0.0.1 dev eth0')).toBe(null);
+  });
+});
+
+describe('discoveredNetworkKeys (issue #300 redeploy idempotency)', () => {
+  const internal = { subnet: '192.168.1.0/24', gateway: '192.168.1.1' };
+
+  test('writes discovered subnet+gateway on first install (unset)', () => {
+    expect(discoveredNetworkKeys(internal, false)).toEqual({
+      'network.internal.subnet': '192.168.1.0/24',
+      'network.internal.gateway': '192.168.1.1',
+    });
+  });
+
+  test('preserves an already-set subnet on redeploy (no override)', () => {
+    // The regression: a redeploy on a box off the internal network discovers the
+    // WRONG subnet — it must not clobber the operator's value.
+    expect(discoveredNetworkKeys(internal, true)).toEqual({});
+  });
+
+  test('box IS on the configured internal network → nothing to record', () => {
+    expect(discoveredNetworkKeys(internal, true, { internalSubnet: '192.168.1.0/24' })).toEqual({});
+  });
+
+  test('box is OFF the internal network → records it as secure-mgmt, not discarded', () => {
+    // #300 discarded this value to protect `internal`. Correct, but it left celilo
+    // blind to its own network: untrusted by the firewall, and absent from the
+    // resolver's split-horizon views (NOERROR/0-records → public DNS → hairpin).
+    const mgmtBox = { subnet: '10.0.120.0/24', gateway: '10.0.120.1' };
+    expect(discoveredNetworkKeys(mgmtBox, true, { internalSubnet: '192.168.0.0/24' })).toEqual({
+      'network.secure-mgmt.subnet': '10.0.120.0/24',
+      'network.secure-mgmt.gateway': '10.0.120.1',
+    });
+  });
+
+  test('never clobbers an already-set secure-mgmt subnet', () => {
+    const mgmtBox = { subnet: '10.0.120.0/24', gateway: '10.0.120.1' };
+    expect(
+      discoveredNetworkKeys(mgmtBox, true, {
+        internalSubnet: '192.168.0.0/24',
+        secureMgmtAlreadySet: true,
+      }),
+    ).toEqual({});
+  });
+
+  test('internal set but its value unreadable → stays conservative, writes nothing', () => {
+    // Without knowing the configured subnet we cannot tell whether this box is on
+    // it; guessing wrong would mislabel the LAN. Preserve #300's behaviour.
+    expect(discoveredNetworkKeys(internal, true, {})).toEqual({});
+  });
+
+  test('writes nothing when discovery failed and nothing is set', () => {
+    expect(discoveredNetworkKeys(null, false)).toEqual({});
+  });
+});
+
+describe('discoverAndRecordNetwork', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+  });
+
+  function read(key: string): string | undefined {
+    return db.select().from(systemConfig).where(eq(systemConfig.key, key)).get()?.value;
+  }
+
+  test('records the discovered network on a box that has none', () => {
+    const result = discoverAndRecordNetwork(db, () =>
+      ipRouteFor('10.31.7.0', '10.31.7.1', '10.31.7.20'),
+    );
+
+    expect(result.applied).toHaveLength(2);
+    expect(read('network.internal.subnet')).toBe('10.31.7.0/24');
+    expect(read('network.internal.gateway')).toBe('10.31.7.1');
+  });
+
+  test('a redeploy on the same box changes nothing and says so', () => {
+    const routes = () => ipRouteFor('10.31.7.0', '10.31.7.1', '10.31.7.20');
+    discoverAndRecordNetwork(db, routes);
+    const second = discoverAndRecordNetwork(db, routes);
+
+    expect(second.applied).toEqual([]);
+    expect(second.skipped).toContain('already accounts for');
+    expect(read('network.internal.subnet')).toBe('10.31.7.0/24');
+  });
+
+  test('a box off the internal LAN records its own network as secure-mgmt', () => {
+    db.insert(systemConfig)
+      .values({ key: 'network.internal.subnet', value: '192.168.0.0/24' })
+      .run();
+
+    discoverAndRecordNetwork(db, () => ipRouteFor('10.0.120.0', '10.0.120.1', '10.0.120.10'));
+
+    // The operator's internal value is untouched, and celilo is no longer blind
+    // to the network its own control plane occupies.
+    expect(read('network.internal.subnet')).toBe('192.168.0.0/24');
+    expect(read('network.secure-mgmt.subnet')).toBe('10.0.120.0/24');
+  });
+
+  test('an unreadable routing table is reported, not guessed at', () => {
+    const result = discoverAndRecordNetwork(db, () => null);
+
+    expect(result.applied).toEqual([]);
+    expect(result.skipped).toContain('ip route');
+    expect(read('network.internal.subnet')).toBeUndefined();
+  });
+});