@celilo/cli 0.24.0 → 0.24.1

package/package.json

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

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/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/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/variables/context.ts

@@ -185,9 +185,14 @@ function resolveSelfRefsInObject(
 }
 
 /**
- * Build resolution context for a module
+ * Build the resolution context for a module, provisioning as it goes.
  *
- * Execution function (Rule 10.1) - performs database queries
+ * Execution function (Rule 10.1) - performs database queries AND writes:
+ * it seeds `module_configs` with defaults and zone-derived networking, and
+ * records the module's deployed system (allocating IPAM addresses when the
+ * host is a celilo-provisioned container). This is the generate/deploy-time
+ * entrypoint. Anything that only wants to READ the resolved configuration
+ * wants {@link readResolutionContext} instead.
  *
  * @param moduleId - Module to build context for
  * @param db - Database client (optional, for testing)
@@ -197,6 +202,55 @@ export async function buildResolutionContext(
   moduleId: string,
   db = getDb(),
 ): Promise<ResolutionContext> {
+  return assembleResolutionContext(moduleId, db, { provision: true });
+}
+
+/**
+ * The same resolved configuration, computed without touching the database.
+ *
+ * Every derived value is recomputed from its current upstream, exactly as a
+ * build would compute it, but nothing is written: no config rows are seeded,
+ * no addresses are allocated, no deployed system is recorded. That makes it
+ * safe to call from read paths that run on a cadence — health checks, hook
+ * invocations, capability factories — where a provisioning side effect would
+ * be both surprising and, in the IPAM case, harmful.
+ *
+ * This is what {@link import('../hooks/load-hook-config').loadHookConfigMap}
+ * uses so a hook sees the value a derive currently produces rather than only
+ * the ones that happen to have been stored.
+ *
+ * @param moduleId - Module to build context for
+ * @param db - Database client (optional, for testing)
+ * @returns Resolution context with all data sources
+ */
+export async function readResolutionContext(
+  moduleId: string,
+  db = getDb(),
+): Promise<ResolutionContext> {
+  return assembleResolutionContext(moduleId, db, { provision: false });
+}
+
+/**
+ * The shared body of both entrypoints. `provision` is deliberately private
+ * (Rule 10.3): callers choose a named function, not a flag.
+ */
+async function assembleResolutionContext(
+  moduleId: string,
+  db: DbClient,
+  { provision }: { provision: boolean },
+): Promise<ResolutionContext> {
+  /**
+   * Seed a config row — a no-op when only reading. Every seeded value is also
+   * assigned into `selfConfig` by the caller, so the resolved context is the
+   * same either way; what differs is whether it is written down.
+   */
+  const persistConfig = (
+    key: string,
+    value: string | number | boolean | unknown[] | Record<string, unknown>,
+  ): void => {
+    if (provision) upsertModuleConfig(db, moduleId, key, value);
+  };
+
   // Fetch module manifest for VM resources
   const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
 
@@ -226,12 +280,12 @@ export async function buildResolutionContext(
 
     // Store assigned values in module config
     if (assigned.hostname) {
-      upsertModuleConfig(db, moduleId, 'hostname', assigned.hostname);
+      persistConfig('hostname', assigned.hostname);
       selfConfig.hostname = assigned.hostname;
     }
 
     if (assigned.zone) {
-      upsertModuleConfig(db, moduleId, 'zone', assigned.zone);
+      persistConfig('zone', assigned.zone);
       selfConfig.zone = assigned.zone;
     }
   }
@@ -248,9 +302,7 @@ export async function buildResolutionContext(
       // declared shape — e.g. `default: 2222` (YAML int) round-trips as
       // `number` not the string "2222". This is the root of Defect 1.
       if (variable.default !== undefined && !selfConfig[variable.name]) {
-        upsertModuleConfig(
-          db,
-          moduleId,
+        persistConfig(
           variable.name,
           variable.default as string | number | boolean | unknown[] | Record<string, unknown>,
         );
@@ -303,7 +355,7 @@ export async function buildResolutionContext(
       for (const { manifestKey, configKey, systemValue } of resourceMappings) {
         if (systemValue != null) {
           // Canonical system size — always wins so a resize propagates.
-          upsertModuleConfig(db, moduleId, configKey, systemValue);
+          persistConfig(configKey, systemValue);
           selfConfig[configKey] = String(systemValue);
           continue;
         }
@@ -312,9 +364,7 @@ export async function buildResolutionContext(
         // Pass them through unstringified so valueJson preserves the
         // shape — see comment in the variable-defaults block above.
         if (value !== undefined && !selfConfig[configKey]) {
-          upsertModuleConfig(
-            db,
-            moduleId,
+          persistConfig(
             configKey,
             value as string | number | boolean | unknown[] | Record<string, unknown>,
           );
@@ -333,7 +383,11 @@ export async function buildResolutionContext(
   //                         outputs (resolveInfrastructureVariables), not here.
   // This is the single place generate-time addresses are recorded — `target_ip`
   // no longer lives in module_configs.
-  if (module?.manifestData) {
+  //
+  // Provisioning only. A read must never reach this: allocating an address is
+  // not something looking at a config should do, and by the time any hook runs
+  // the row is already there for `buildInfraSystemsMap` below to read.
+  if (provision && module?.manifestData) {
     const manifest = module.manifestData as ModuleManifest;
     const declared = getDeclaredSystems(manifest);
     const hostname = selfConfig.hostname;
@@ -593,7 +647,7 @@ export async function buildResolutionContext(
 
     // If zone from manifest but not in selfConfig, store it as first-class config
     if (zone && !selfConfig.zone) {
-      upsertModuleConfig(db, moduleId, 'zone', zone);
+      persistConfig('zone', zone);
       selfConfig.zone = zone;
     }
 
@@ -625,7 +679,7 @@ export async function buildResolutionContext(
               }
               return value;
             })();
-            upsertModuleConfig(db, moduleId, field, coerced);
+            persistConfig(field, coerced);
             selfConfig[field] = String(coerced);
           }
         }
@@ -685,7 +739,7 @@ export async function buildResolutionContext(
       }
 
       if (isNew || isChanged) {
-        upsertModuleConfig(db, moduleId, key, value);
+        persistConfig(key, value);
         selfConfig[key] = value;
       }
     }

package/src/variables/declarative-derivation.test.ts

@@ -52,6 +52,59 @@ describe('resolveDeclarativeDerivation', () => {
       expect(result).toBe('10.0.10.0/24');
     });
 
+    test('resolves a system key containing hyphens', () => {
+      // celilo's zone names are kebab-case, so shipped manifests contain
+      // `$system:network.control-plane-vpn.subnet` and
+      // `$system:network.secure-mgmt.subnet`. While the match stopped at the
+      // first hyphen these looked up `network.control` / `network.secure`,
+      // threw, and — being optional — resolved to nothing in silence. That is
+      // half of the 2026-08-14 DNS outage.
+      const variable: VariableDeclare = {
+        name: 'vpn_subnet',
+        type: 'string',
+        required: false,
+        source: 'system',
+        derive_from: '$system:network.control-plane-vpn.subnet',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'technitium',
+        selfConfig: {},
+        systemConfig: { 'network.control-plane-vpn.subnet': '10.255.255.0/24' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      expect(resolveDeclarativeDerivation(variable, context)).toBe('10.255.255.0/24');
+    });
+
+    test('names the whole hyphenated key when it is missing', () => {
+      // The message has to name the key the manifest asked for. Reporting
+      // `network.secure` for a manifest that says `network.secure-mgmt` sends
+      // the reader looking for a key that was never requested.
+      const variable: VariableDeclare = {
+        name: 'secure_mgmt_subnet',
+        type: 'string',
+        required: true,
+        source: 'system',
+        derive_from: '$system:network.secure-mgmt.subnet',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'technitium',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      expect(() => resolveDeclarativeDerivation(variable, context)).toThrow(
+        "Missing system config: network.secure-mgmt.subnet (required by variable 'secure_mgmt_subnet')",
+      );
+    });
+
     test('throws on missing system config', () => {
       const variable: VariableDeclare = {
         name: 'primary_domain',

package/src/variables/declarative-derivation.ts

@@ -56,8 +56,19 @@ function substituteVariables(
 ): string {
   let result = input;
 
-  // Replace $system:key patterns (both $system:key and ${system:key} forms)
-  result = result.replace(/\$\{?system:([a-zA-Z0-9_.]+)\}?/g, (_match, key) => {
+  // Replace $system:key patterns (both $system:key and ${system:key} forms).
+  //
+  // The key may contain hyphens. celilo's own zone names are kebab-case, so
+  // `$system:network.control-plane-vpn.subnet` and
+  // `$system:network.secure-mgmt.subnet` are both real keys in shipped
+  // manifests — and neither could ever resolve while this class excluded `-`:
+  // the match stopped at the first hyphen, looked up `network.control`, and
+  // threw. For an optional variable that throw is swallowed, so the derive
+  // simply produced nothing, forever, in silence. That is half of the
+  // 2026-08-14 DNS outage (`technitium.vpn_subnet`); the other half is that
+  // nothing re-derived the value at read time — see
+  // `hooks/load-hook-config.ts`.
+  result = result.replace(/\$\{?system:([a-zA-Z0-9_.-]+)\}?/g, (_match, key) => {
     const value = context.systemConfig[key];
     if (value === undefined) {
       throw new Error(`Missing system config: ${key} (required by variable '${variableName}')`);