@celilo/cli 0.23.0 → 0.24.1

package/src/cli/index.ts

@@ -48,6 +48,7 @@ import {
   handleEventsTail,
   handleEventsUninstallDaemon,
 } from './commands/events';
+import { handleFirewallInterfaceList } from './commands/firewall-interface-list';
 import { handleHookRun } from './commands/hook-run';
 import {
   handleIpamIpListReservations,
@@ -68,7 +69,11 @@ import { moduleAudit } from './commands/module-audit';
 import { handleModuleBuild } from './commands/module-build';
 import { handleModuleChangeset } from './commands/module-changeset';
 import { handleModuleCheck } from './commands/module-check';
-import { handleModuleConfigGet, handleModuleConfigSet } from './commands/module-config';
+import {
+  handleModuleConfigGet,
+  handleModuleConfigSet,
+  handleModuleConfigUnset,
+} from './commands/module-config';
 import { handleModuleDeploy } from './commands/module-deploy';
 import { handleModuleGenerate } from './commands/module-generate';
 import { handleModuleHealth } from './commands/module-health';
@@ -204,6 +209,7 @@ Commands:
   storage                  Manage backup storage destinations
   backup                   Create and manage backups
   restore                  Restore a celilo-mgmt backup from a local file (fresh-bootstrap path)
+  firewall                 Inspect a firewall's interfaces (classification, on demand)
   machine                  Manage machine pool (bring-your-own-hardware)
   system                   Manage system configuration
   apt-upgrade              Upgrade the deb-installed celilo packages + apply migrations
@@ -598,6 +604,7 @@ Subcommands:
 
   config set <id> <key> <value>        Set module configuration value
   config get <id> [key]                Get module configuration value(s)
+  config unset <id> <key>              Remove an override; follow the manifest again
 
   secret set <id> <key> <value>        Set encrypted module secret
   secret list <id>                     List module secrets
@@ -675,6 +682,8 @@ Examples:
   celilo module config set homebridge container_ip "192.168.0.110/24"
   celilo module config get homebridge
   celilo module config get homebridge hostname
+  celilo module config set caddy backup_schedule 6h
+  celilo module config unset caddy backup_schedule
   celilo module show-config homebridge
   celilo module show-zone homebridge
   celilo module build caddy
@@ -917,6 +926,28 @@ Related Commands:
 /**
  * Display machine command help
  */
+function displayFirewallHelp(): CommandResult {
+  console.log(`
+celilo firewall — inspect a firewall's interfaces
+
+Usage:
+  celilo firewall interface list [<hostname>]
+
+  Shows how celilo classifies every interface on a firewall: the zone it
+  matched, the external edge, or ALIEN when nothing accounts for it.
+
+  Read-only. It reads the recorded interface table and the declared zone
+  subnets and classifies in memory — it never touches the box, so it is safe
+  to run against a firewall whose converge is currently refusing.
+
+  With no hostname, every machine celilo classifies as a router is shown.
+
+  An interface celilo cannot attribute is resolved by DECLARING it:
+    celilo system config set network.<zone>.subnet <cidr>
+`);
+  return { success: true, message: 'firewall help' };
+}
+
 function displayMachineHelp(): CommandResult {
   const helpText = `
 Celilo - Machine Pool Management
@@ -1544,7 +1575,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         if (!configSubcommand) {
           return {
             success: false,
-            error: 'Config action required (set or get)\n\nRun "celilo help" for usage',
+            error: 'Config action required (set, get or unset)\n\nRun "celilo help" for usage',
           };
         }
         const configArgs = parsed.args.slice(1);
@@ -1554,6 +1585,9 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         if (configSubcommand === 'get') {
           return handleModuleConfigGet(configArgs);
         }
+        if (configSubcommand === 'unset') {
+          return handleModuleConfigUnset(configArgs);
+        }
         return {
           success: false,
           error: `Unknown config action: ${configSubcommand}`,
@@ -2050,6 +2084,29 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     };
   }
 
+  if (parsed.command === 'firewall') {
+    if (parsed.flags.help || parsed.flags.h || !parsed.subcommand) {
+      return displayFirewallHelp();
+    }
+    if (parsed.subcommand === 'interface') {
+      // `interface` is a group, not a leaf: `list` is its only verb today.
+      // `acknowledge` and `enforce` were both deleted in the design amendments —
+      // there is no policy toggle and no per-interface escape hatch.
+      const verb = parsed.args[0];
+      if (!verb || verb === 'list') {
+        return handleFirewallInterfaceList(parsed.args.slice(1), parsed.flags);
+      }
+      return {
+        success: false,
+        error: `Unknown firewall interface subcommand: ${verb}\n\nRun "celilo firewall --help" for usage`,
+      };
+    }
+    return {
+      success: false,
+      error: `Unknown firewall subcommand: ${parsed.subcommand}\n\nRun "celilo firewall --help" for usage`,
+    };
+  }
+
   if (parsed.command === 'machine') {
     // Handle machine --help
     if (parsed.flags.help || parsed.flags.h) {

package/src/cli/tui/audit-state.ts

@@ -88,9 +88,11 @@ export const ALL_CATEGORIES: readonly DriftCategory[] = [
   'disk_space',
   'transport_reads',
   'trusted_sources',
+  'interface_classification',
 ];
 
 export const CATEGORY_LABELS: Record<DriftCategory, string> = {
+  interface_classification: 'Firewall interfaces',
   cli_version: 'CLI version',
   schema: 'Schema migrations',
   capability_abi: 'Capability ABI',

package/src/hooks/capability-loader.ts

@@ -154,6 +154,32 @@ export async function resolveFirewallNatIp(db: DbClient): Promise<string | undef
   return undefined;
 }
 
+/**
+ * The addresses of every machine a `firewall` capability provider manages.
+ *
+ * This is the authoritative answer to "which machines are firewalls", and it has
+ * to be: a machine's stored `role` is decided by `machine add`, from the zones
+ * declared AT THAT MOMENT. The normal order is `machine add` and THEN deploy
+ * iptables, whose `on_install` writes the zone subnets — so the firewall is
+ * recorded as a plain host and stays that way. A firewall provider naming an IP
+ * is a statement, not an inference from a snapshot.
+ */
+export async function listFirewallIps(db: DbClient): Promise<string[]> {
+  const providers = db
+    .select()
+    .from(capabilities)
+    .where(eq(capabilities.capabilityName, 'firewall'))
+    .all();
+  const ips: string[] = [];
+  for (const provider of providers) {
+    const config = await loadModuleConfig(provider.moduleId, db);
+    if (typeof config.firewall_ip === 'string' && config.firewall_ip) {
+      ips.push(config.firewall_ip);
+    }
+  }
+  return ips;
+}
+
 /**
  * Caddy's zone-routable IP — its own DMZ ingress address (`target_ip`, the same
  * value public_web exposes as `dmz_ip`). This is the in-zone split-horizon
@@ -606,6 +632,9 @@ 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.
+        zones ? { list: zones.declaredNetworks } : undefined,
       );
       return stampProvider(iface, providerModuleId);
     }
@@ -707,6 +736,18 @@ interface FirewallZones {
   trustedSubnets: string[];
   /** celilo's control-plane network, as a DESTINATION for trusted sources. */
   controlPlaneSubnet?: string;
+  /**
+   * Every zone with a declared subnet, WITH its name — the input to interface
+   * classification. Excludes `external`, which is a residual rather than a
+   * 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.
+   */
+  declaredNetworks: () => Array<{ zone: string; subnet: string }>;
   /**
    * Every declared zone subnet — read from
    * `network.<zone>.subnet` across all of `NETWORK_ZONES`, not just the three
@@ -806,6 +847,35 @@ export function loadTrustedSubnets(db: DbClient, firewallIp?: string): TrustedSu
  * of them. Zones with no configured subnet are omitted — their traffic stays
  * denied (fail-closed).
  */
+/**
+ * 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.
+ *
+ * `external` is deliberately absent even when something has set
+ * `network.external.subnet`: it is the RESIDUAL, decided by `isPubliclyRoutable`
+ * and never by containment (design D1, amended). Matching an interface to
+ * `external` by subnet would reintroduce the overload this change removes.
+ */
+export function readDeclaredNetworks(db: DbClient): Array<{ zone: string; subnet: string }> {
+  return db
+    .select()
+    .from(systemConfig)
+    .all()
+    .flatMap((row) => {
+      const zone = /^network\.(.+)\.subnet$/.exec(row.key)?.[1];
+      return zone && zone !== 'external' && row.value ? [{ zone, subnet: row.value }] : [];
+    });
+}
+
 function loadFirewallZones(db: DbClient): FirewallZones {
   const zoneTiers: Array<{ name: string; subnet: string }> = [];
   for (const zone of ZONE_TIER_ORDER) {
@@ -822,17 +892,65 @@ function loadFirewallZones(db: DbClient): FirewallZones {
   // snapshot put the subnet straight back, so the set could grow but never
   // shrink. That is exactly what happened: `on_uninstall` withdrew the VPN's
   // trusted source, logged success, and the reach rules were re-rendered anyway.
+  // Every zone that HAS a declared subnet, keeping the zone NAME. Interface
+  // classification needs the name — `external` and `internal` are the only two
+  // legs a default route may leave through (design D11), which is not a question
+  // a bare list of subnets can answer.
+  //
+  // `external` is deliberately absent from this list even when something has set
+  // `network.external.subnet`: `external` is the RESIDUAL, decided by
+  // `isPubliclyRoutable`, never by containment (design D1, amended). Matching an
+  // interface to `external` by subnet would reintroduce the overload this change
+  // removes.
+  //
+  // EVERY declared network, not just the six `NETWORK_ZONES`. celilo declares
+  // networks that are not placement zones — `network.control-plane-vpn.subnet`,
+  // written by `wireguard`'s `on_install` — and the design is explicit that the
+  // firewall "classifies `wg0` by the same subnet containment it uses for every
+  // other leg". Reading only `NETWORK_ZONES` left that declaration invisible:
+  // the module declared the subnet before bringing the interface up, exactly as
+  // designed, and the converge still could not attribute `wg0` and refused. On a
+  // firewall that already had a baseline it would have gone further and ISOLATED
+  // the interface — celilo shutting down the admin VPN, which for a remote
+  // operator is the way back in.
+  //
+  // So the source is the config itself. A hardcoded list here could only ever
+  // describe the networks celilo knew about when this line was written.
+
   return {
     zoneTiers,
     trustedSubnets: loadTrustedSubnets(db).map((e) => e.subnet),
     controlPlaneSubnet: loadControlPlaneSubnet(db) ?? readZoneSubnet(db, 'internal'),
-    // Every zone celilo knows about, not the tier list — see the field doc.
-    frontedSubnets: NETWORK_ZONES.map((zone) => readZoneSubnet(db, zone)).filter(
-      (subnet): subnet is string => !!subnet,
-    ),
+    declaredNetworks: () => readDeclaredNetworks(db),
+    // Placement ZONES only — deliberately NOT `declaredNetworks`, which is wider.
+    // Fronting a subnet renders translation for it; the control-plane VPN
+    // reaches the fleet as a trusted source instead, and giving it a second
+    // mechanism would change the rendered ruleset for every existing fleet.
+    frontedSubnets: NETWORK_ZONES.filter((zone) => zone !== 'external').flatMap((zone) => {
+      const subnet = readZoneSubnet(db, zone);
+      return subnet ? [subnet] : [];
+    }),
   };
 }
 
+/**
+ * The interface baseline as stored in module config: a comma-separated list of
+ * interface names, or absent.
+ *
+ * Absent and empty are the SAME thing here and both mean "no baseline" — a
+ * firewall with zero interfaces does not exist, so an empty string can only be
+ * a cleared or never-written value. Treating it as a baseline of nothing would
+ * mean every interface is "new", which is the opposite of what it says.
+ */
+function parseInterfaceBaseline(raw: unknown): string[] | undefined {
+  if (typeof raw !== 'string') return undefined;
+  const names = raw
+    .split(',')
+    .map((n) => n.trim())
+    .filter((n) => n.length > 0);
+  return names.length > 0 ? names : undefined;
+}
+
 async function buildFirewallChain(
   allProviders: Array<{
     id: number;
@@ -982,11 +1100,19 @@ async function buildFirewallChain(
         trustedSubnets: zones.trustedSubnets,
         controlPlaneSubnet: zones.controlPlaneSubnet,
         frontedSubnets: zones.frontedSubnets,
+        // The recorded baseline (D12), from this firewall's own module config.
+        // Absent means the box has never converged cleanly, so an interface
+        // celilo cannot attribute refuses rather than being disabled.
+        interfaceBaseline: parseInterfaceBaseline(provConfig.interface_baseline),
       },
       store,
       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.
+      { list: zones.declaredNetworks },
     );
 
     debugLog(`firewall chain: wired ${provider.moduleId} → ${hasExternal.moduleId}`);

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;
 }