@celilo/cli 0.23.0 → 0.24.1

package/src/services/zone-detector.ts

@@ -6,7 +6,24 @@
 import { subnetContains } from '@celilo/capabilities';
 import { eq } from 'drizzle-orm';
 import { getDb } from '../db/client';
-import { type NetworkZone, systemConfig } from '../db/schema';
+import { NETWORK_ZONES, type NetworkZone, systemConfig } from '../db/schema';
+
+/**
+ * The zones a subnet can be declared for — every `NetworkZone` except
+ * `external`.
+ *
+ * `external` is deliberately absent and must stay absent: it has no
+ * `network.external.subnet` and must never be given one. It is not a segment
+ * celilo manages, it is whatever the ISP handed you, so it is the RESIDUAL —
+ * decided by `isPubliclyRoutable`, not by containment (design D1, amended).
+ *
+ * Derived from NETWORK_ZONES rather than listed by hand. The hand-written list
+ * that used to be here had already dropped `control-plane-vpn`, which is the
+ * third instance of that bug class in this repo.
+ */
+const SUBNET_BACKED_ZONES: readonly NetworkZone[] = NETWORK_ZONES.filter(
+  (zone) => zone !== 'external',
+);
 
 /**
  * Get system network configuration for a zone
@@ -28,25 +45,28 @@ async function getZoneSubnet(zone: NetworkZone): Promise<string | null> {
 }
 
 /**
- * Detect network zone from IP address
- * Matches IP against system network configuration
+ * Which zone an address belongs to, or `'unknown'` when celilo cannot say.
+ *
+ * **`'unknown'` is the honest answer, and it used to be unreachable.** This
+ * returned `'external'` on no-match — so on a firewall with five RFC1918 legs
+ * and three declared zones, private gateway addresses were each reported as
+ * facing the internet. `NetworkInterface.zone` was already typed
+ * `NetworkZone | 'unknown'` and nothing could produce it, because this claimed
+ * `external` instead. The slot for the honest answer existed and was
+ * unreachable.
  *
- * @param ip - IP address to check
- * @returns Detected network zone, or 'external' if no match
+ * This answers ONLY the containment question. Whether an unmatched address is
+ * an external edge is a different question, answered by `isPubliclyRoutable` —
+ * see design D1 on why conflating the two was the defect.
  */
-export async function detectZoneFromIp(ip: string): Promise<NetworkZone> {
-  // Check each zone's subnet
-  const zones: NetworkZone[] = ['internal', 'dmz', 'app', 'secure', 'secure-mgmt'];
-
-  for (const zone of zones) {
+export async function detectZoneFromIp(ip: string): Promise<NetworkZone | 'unknown'> {
+  for (const zone of SUBNET_BACKED_ZONES) {
     const subnet = await getZoneSubnet(zone);
     if (subnet && subnetContains(subnet, ip)) {
       return zone;
     }
   }
-
-  // No match found - must be external
-  return 'external';
+  return 'unknown';
 }
 
 /**

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