@celilo/cli 0.3.30 → 0.4.0-alpha.1

package/src/db/schema.ts

@@ -1,5 +1,12 @@
 import { sql } from 'drizzle-orm';
-import { integer, sqliteTable, text, unique, uniqueIndex } from 'drizzle-orm/sqlite-core';
+import {
+  integer,
+  primaryKey,
+  sqliteTable,
+  text,
+  unique,
+  uniqueIndex,
+} from 'drizzle-orm/sqlite-core';
 
 /**
  * Module lifecycle states
@@ -33,16 +40,25 @@ export const modules = sqliteTable('modules', {
 });
 
 /**
- * Module configuration - user-provided key-value pairs
- * Stores configuration like container_ip, zone, etc.
+ * Module configuration - user-provided key-value pairs.
  *
- * For primitive types (string, number, boolean):
- *   - value: contains the value (as string)
- *   - valueJson: NULL
+ * Two columns, with strictly different roles:
+ *   - `valueJson`: JSON-encoded canonical value, ALWAYS populated by
+ *     the write path. This is the source of truth — readers MUST
+ *     consume `valueJson` and `JSON.parse` it. Type fidelity is
+ *     preserved here: `number` round-trips as `number`, `boolean` as
+ *     `boolean`, arrays/objects as their JSON shape.
+ *   - `value`: human-readable string form, used only by the CLI for
+ *     display (`module config get`). NEVER used as a source of typed
+ *     data — that path leaked stringly-typed numbers through to
+ *     capability calls (see commit history for the forgejo SSH:2222
+ *     case, where ssh_external_port was read back as "2222" the
+ *     string and silently broke firewall.exposeService).
  *
- * For complex types (arrays, objects):
- *   - value: empty string
- *   - valueJson: JSON-stringified complex value
+ * Historically `value` was the canonical storage for primitives and
+ * `valueJson` only for arrays/objects. That was Defect 1 — TS types
+ * generated from the manifest claimed `number` while the runtime
+ * value was string. Now closed.
  */
 export const moduleConfigs = sqliteTable(
   'module_configs',
@@ -298,6 +314,13 @@ export const machines = sqliteTable('machines', {
     .default(sql`'[]'`),
   /** Module ID this machine is earmarked for. If set, only this module can use this machine. */
   earmarkedModule: text('earmarked_module'),
+  /**
+   * Appliance machines (e.g., greenwave = ISP modem) where celilo
+   * has no shell-level access — only API calls. Base-module aspects
+   * cannot Ansible to these systems, so the aspect runner skips
+   * them. See v2/CELILO_BASE.md D8.
+   */
+  apiOnly: integer('api_only', { mode: 'boolean' }).notNull().default(false),
   createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
 });
@@ -317,9 +340,66 @@ export const moduleInfrastructure = sqliteTable('module_infrastructure', {
   machineId: text('machine_id').references(() => machines.id),
   serviceId: text('service_id').references(() => containerServices.id),
   containerMetadata: text('container_metadata', { mode: 'json' }).$type<Record<string, unknown>>(), // VMID, droplet ID, etc.
+  /**
+   * Mirrors machines.api_only — set when the container_service
+   * driver registers an entry that has no SSH surface (rare today,
+   * but exists for future API-only providers). Aspect runner reads
+   * this to decide whether the system is reachable via Ansible.
+   * See v2/CELILO_BASE.md D8.
+   */
+  apiOnly: integer('api_only', { mode: 'boolean' }).notNull().default(false),
   createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
 });
 
+/**
+ * Module systems table
+ *
+ * A module deploys onto 0..N *systems*, each an addressed host. This is the
+ * deployment-STATE counterpart to module_configs (declared inputs): it records,
+ * per deployed system, the hostname + IPv4 + zone + where it lives. Replaces the
+ * old scalar `target_ip`/`vmid` rows in module_configs, which baked in the
+ * one-module-one-host assumption. See v2/MODULE_SYSTEMS_ADDRESSING.md.
+ *
+ *   - 0 rows: API-only modules (e.g. namecheap — no host).
+ *   - 1 row:  the common case (technitium, homebridge, …).
+ *   - N rows: multi-system modules (e.g. app + db).
+ *
+ * Keyed by (module_id, name): `name` is the stable, authoring-time handle from
+ * the manifest's `requires.systems[].name` — what templates reference via
+ * `$infra:<name>.…`. `hostname` is the runtime DNS hostname (often == name, but
+ * user/well-known-assignable), used by DNS and events. See
+ * v2/MODULE_SYSTEMS_ADDRESSING.md.
+ */
+export const moduleSystems = sqliteTable(
+  'module_systems',
+  {
+    moduleId: text('module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    /** Stable authoring-time handle (requires.systems[].name) — the per-system key. */
+    name: text('name').notNull(),
+    /** Runtime DNS hostname (often == name). */
+    hostname: text('hostname').notNull(),
+    /** CIDR-stripped IPv4 — the canonical address. */
+    ipv4Address: text('ipv4_address').notNull(),
+    /** Network zone the host sits in; CIDR is derived from this + ipv4Address. */
+    zone: text('zone').$type<NetworkZone>().notNull(),
+    /** Where the system lives: a pool machine or a celilo-provisioned container. */
+    infraType: text('infra_type').$type<'machine' | 'container_service'>().notNull(),
+    /** FK machines.id — set for machine-pool deploys (null otherwise). */
+    machineId: text('machine_id').references(() => machines.id),
+    /** FK container_services.id — set for container_service deploys (null otherwise). */
+    serviceId: text('service_id').references(() => containerServices.id),
+    /** Proxmox VMID — set only for proxmox containers. */
+    vmid: integer('vmid'),
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    pk: primaryKey({ columns: [table.moduleId, table.name] }),
+  }),
+);
+
 /**
  * Web routes table
  * Tracks routes registered by modules via public_web capability functions.
@@ -404,6 +484,74 @@ export const backups = sqliteTable('backups', {
   completedAt: integer('completed_at', { mode: 'timestamp' }),
 });
 
+/**
+ * Module operations - in-flight tracking for deploy/uninstall/backup/restore.
+ *
+ * Used by `checkInFlight()` to refuse a backup or restore while another
+ * operation is active on any module. A row is created with status='in_progress'
+ * when an operation starts and updated to 'completed' or 'failed' when it ends.
+ *
+ * The `pid` column carries the process that started the operation; a row whose
+ * pid is no longer alive is treated as abandoned (the process crashed before
+ * the completion update landed) and ignored by in-flight checks.
+ */
+export type ModuleOperationKind = 'deploy' | 'uninstall' | 'backup' | 'restore';
+export type ModuleOperationStatus = 'in_progress' | 'completed' | 'failed';
+
+export const moduleOperations = sqliteTable('module_operations', {
+  id: text('id').primaryKey(), // UUID
+  moduleId: text('module_id').notNull(), // not a FK — survives module deletion (uninstall flow)
+  operation: text('operation').$type<ModuleOperationKind>().notNull(),
+  status: text('status').$type<ModuleOperationStatus>().notNull().default('in_progress'),
+  pid: integer('pid').notNull(),
+  startedAt: integer('started_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  completedAt: integer('completed_at', { mode: 'timestamp' }),
+  errorMessage: text('error_message'),
+});
+
+/**
+ * Aspect approvals table
+ *
+ * Records operator consent for a module's base-module aspect. The
+ * operator approves the aspect's scope (applicable_zones +
+ * triggers) at `celilo module import` time; that consent is
+ * captured here and consulted before any aspect fan-out.
+ *
+ * `scopeHash` is a stable digest of `applicable_zones` + `triggers`
+ * — it lets the framework detect scope-changing upgrades (D7).
+ * If a new module version has the same hash, the prior approval
+ * still covers it; if the hash differs, the upgrade is blocked
+ * until the operator re-approves.
+ *
+ * Unique on (moduleId, version) — there's at most one approval
+ * per module version. Cascade delete on module removal so stale
+ * approvals don't linger.
+ *
+ * See v2/CELILO_BASE.md D2 + D7.
+ */
+export const aspectApprovals = sqliteTable(
+  'aspect_approvals',
+  {
+    id: text('id').primaryKey(), // UUID
+    moduleId: text('module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    /** Module version this approval covers (matches modules.version). */
+    version: text('version').notNull(),
+    /** Hash of `applicable_zones` + `triggers` — see table comment. */
+    scopeHash: text('scope_hash').notNull(),
+    approvedAt: integer('approved_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    /** Operator identifier (e.g., $USER at approval time). Null when --accept-aspects was used in a context with no USER. */
+    approver: text('approver'),
+  },
+  (table) => ({
+    uniqueModuleVersion: unique('aspect_approvals_module_version').on(
+      table.moduleId,
+      table.version,
+    ),
+  }),
+);
+
 /**
  * Type exports for use in application code
  */
@@ -441,3 +589,7 @@ export type BackupStorage = typeof backupStorages.$inferSelect;
 export type NewBackupStorage = typeof backupStorages.$inferInsert;
 export type Backup = typeof backups.$inferSelect;
 export type NewBackup = typeof backups.$inferInsert;
+export type ModuleOperation = typeof moduleOperations.$inferSelect;
+export type NewModuleOperation = typeof moduleOperations.$inferInsert;
+export type AspectApproval = typeof aspectApprovals.$inferSelect;
+export type NewAspectApproval = typeof aspectApprovals.$inferInsert;

package/src/hooks/capability-loader-firewall.test.ts

@@ -10,6 +10,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { HookLogger } from '@celilo/capabilities';
 import type { DbClient } from '../db/client';
+import { upsertModuleConfig } from '../services/module-config';
 import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
 import { loadCapabilityFunctions } from './capability-loader';
 
@@ -102,9 +103,7 @@ describe('Firewall Chain Building', () => {
     db.$client.run(
       `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('greenwave', 'firewall', '1.0.0', '{"has_external":true}', '["internal"]')`,
     );
-    db.$client.run(
-      `INSERT INTO module_configs (module_id, key, value) VALUES ('greenwave', 'router_ip', '192.168.0.1')`,
-    );
+    upsertModuleConfig(db, 'greenwave', 'router_ip', '192.168.0.1');
 
     // Set up encrypted secrets
     const { encryptSecret } = await import('../secrets/encryption');
@@ -152,9 +151,7 @@ describe('Firewall Chain Building', () => {
     db.$client.run(
       `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('greenwave', 'firewall', '1.0.0', '{"has_external":true}', '["internal"]')`,
     );
-    db.$client.run(
-      `INSERT INTO module_configs (module_id, key, value) VALUES ('greenwave', 'router_ip', '192.168.0.1')`,
-    );
+    upsertModuleConfig(db, 'greenwave', 'router_ip', '192.168.0.1');
 
     const { encryptSecret } = await import('../secrets/encryption');
     const { getOrCreateMasterKey } = await import('../secrets/master-key');
@@ -181,15 +178,9 @@ describe('Firewall Chain Building', () => {
     db.$client.run(
       `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('iptables', 'firewall', '1.0.0', '{}', '["dmz","app","secure"]')`,
     );
-    db.$client.run(
-      `INSERT INTO module_configs (module_id, key, value) VALUES ('iptables', 'firewall_ip', '192.168.0.254')`,
-    );
-    db.$client.run(
-      `INSERT INTO module_configs (module_id, key, value) VALUES ('iptables', 'nat_ip', '192.168.0.253')`,
-    );
-    db.$client.run(
-      `INSERT INTO module_configs (module_id, key, value) VALUES ('iptables', 'upstream_zone', 'internal')`,
-    );
+    upsertModuleConfig(db, 'iptables', 'firewall_ip', '192.168.0.254');
+    upsertModuleConfig(db, 'iptables', 'nat_ip', '192.168.0.253');
+    upsertModuleConfig(db, 'iptables', 'upstream_zone', 'internal');
 
     const result = await loadCapabilityFunctions('test-consumer', db, noopLogger);
     expect(result.firewall).toBeTruthy();

package/src/hooks/capability-loader.test.ts

@@ -8,6 +8,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { HookLogger } from '@celilo/capabilities';
 import type { DbClient } from '../db/client';
+import { upsertModuleConfig } from '../services/module-config';
 import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
 import { loadCapabilityFunctions } from './capability-loader';
 
@@ -78,9 +79,7 @@ describe('Capability Loader', () => {
     db.$client.run(
       `INSERT INTO capabilities (module_id, capability_name, version, data, registered_at) VALUES ('namecheap', 'dns_registrar', '2.0.0', '{}', unixepoch())`,
     );
-    db.$client.run(
-      `INSERT INTO module_configs (module_id, key, value) VALUES ('namecheap', 'primary_domain', 'example.com')`,
-    );
+    upsertModuleConfig(db, 'namecheap', 'primary_domain', 'example.com');
 
     // Set encrypted secrets
     const { encryptSecret } = await import('../secrets/encryption');

package/src/hooks/capability-loader.ts

@@ -23,6 +23,7 @@ import type { DbClient } from '../db/client';
 import { capabilities, modules, secrets, webRoutes } from '../db/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
+import { getModuleSystems } from '../services/deployed-systems';
 import { loadHookConfigMap } from './load-hook-config';
 
 /**
@@ -184,6 +185,7 @@ export async function loadCapabilityFunctions(
         const capabilityInterface = exported({
           config: providerConfig,
           secrets: providerSecrets,
+          systems: getModuleSystems(capability.moduleId, db),
           logger,
         });
         result[capName] = capabilityInterface;
@@ -281,17 +283,48 @@ export async function loadCapabilityFunctions(
       // apps/celilo/designs/DNS_REGISTRAR_MULTI_DOMAIN.md). Older
       // registrars that haven't been migrated still use the split shape;
       // we keep that fallback so a stale config can still be read.
+      let foundAny = false;
       if (Array.isArray(drConfig.domains)) {
         for (const d of drConfig.domains) {
-          if (typeof d === 'string' && d) dnsManagedDomains.push(d);
+          if (typeof d === 'string' && d) {
+            dnsManagedDomains.push(d);
+            foundAny = true;
+          }
         }
       } else {
         if (typeof drConfig.primary_domain === 'string' && drConfig.primary_domain) {
           dnsManagedDomains.push(drConfig.primary_domain);
+          foundAny = true;
         }
         if (Array.isArray(drConfig.additional_domains)) {
           for (const d of drConfig.additional_domains) {
-            if (typeof d === 'string' && d) dnsManagedDomains.push(d);
+            if (typeof d === 'string' && d) {
+              dnsManagedDomains.push(d);
+              foundAny = true;
+            }
+          }
+        }
+      }
+      // namecheap 3.1.1+ derives its managed-domain list from
+      // `Object.keys(secret.ddns_passwords)` (a JSON-encoded
+      // domain→password map) and no longer exposes a `domains` config.
+      // Mirror that derivation here so the cross-module flow knows
+      // which zones the registrar covers. See
+      // apps/celilo/designs/STRING_LIST_AND_DERIVED_KEYS.md.
+      if (!foundAny) {
+        const drSecrets = await loadModuleSecrets(drp.moduleId, masterKey, db);
+        const raw = drSecrets.ddns_passwords;
+        if (typeof raw === 'string' && raw) {
+          try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+              for (const k of Object.keys(parsed)) {
+                if (k) dnsManagedDomains.push(k);
+              }
+            }
+          } catch {
+            // Bad JSON → empty list; consumer will throw
+            // MissingProviderInputError naming this registrar.
           }
         }
       }
@@ -462,6 +495,7 @@ async function buildFirewallChain(
     leafFirewall = leafExported({
       config: leafConfig,
       secrets: leafSecrets,
+      systems: getModuleSystems(hasExternal.moduleId, db),
       logger,
     });
     debugLog(

package/src/hooks/define-hook.test.ts

@@ -44,6 +44,7 @@ function makeContext(overrides: Partial<HookContext> = {}): HookContext {
   return {
     config: {},
     secrets: {},
+    systems: [],
     logger: makeLogger(),
     debug: false,
     screenshotDir: '',
@@ -329,6 +330,7 @@ describe('defineCapabilityFunction', () => {
     const methods = factory({
       config: { target_ip: '10.0.0.5' },
       secrets: { token: 'abc' },
+      systems: [],
       logger: makeLogger(),
     });
 
@@ -354,6 +356,7 @@ describe('defineCapabilityFunction', () => {
     const methods = factory({
       config: {},
       secrets: {},
+      systems: [],
       logger: makeLogger(),
     });
 
@@ -381,6 +384,7 @@ describe('defineCapabilityFunction', () => {
     const methods = factory({
       config: {},
       secrets: {},
+      systems: [],
       logger: makeLogger(),
     });
 

package/src/hooks/executor.test.ts

@@ -112,6 +112,7 @@ describe('Hook Executor', () => {
       const result = await executeHookScript(scriptPath, {
         config: { username: 'testuser' },
         secrets: { password: 'secret' },
+        systems: [],
         logger,
         debug: false,
         screenshotDir: '/tmp',
@@ -131,6 +132,7 @@ describe('Hook Executor', () => {
         executeHookScript('/nonexistent/hook.ts', {
           config: {},
           secrets: {},
+          systems: [],
           logger,
           debug: false,
           screenshotDir: '/tmp',
@@ -147,6 +149,7 @@ describe('Hook Executor', () => {
         executeHookScript(scriptPath, {
           config: {},
           secrets: {},
+          systems: [],
           logger,
           debug: false,
           screenshotDir: '/tmp',
@@ -167,6 +170,7 @@ describe('Hook Executor', () => {
         executeHookScript(scriptPath, {
           config: {},
           secrets: {},
+          systems: [],
           logger,
           debug: false,
           screenshotDir: '/tmp',
@@ -182,6 +186,7 @@ describe('Hook Executor', () => {
       const result = await executeHookScript(scriptPath, {
         config: {},
         secrets: {},
+        systems: [],
         logger,
         debug: false,
         screenshotDir: '/tmp',
@@ -199,6 +204,7 @@ describe('Hook Executor', () => {
         executeHookScript(scriptPath, {
           config: {},
           secrets: {},
+          systems: [],
           logger,
           debug: false,
           screenshotDir: '/tmp',
@@ -458,5 +464,17 @@ describe('Hook Executor', () => {
       expect(result).toContain("'idp'");
       expect(result).toContain('each missing capability');
     });
+
+    test('skips framework-granted privileges (not provider-loaded)', () => {
+      // cross_module_read is a privilege granted by the framework to the
+      // hooks that use it (backup/restore), not a provider-loaded
+      // capability. It must not block other hooks like on_install
+      // (regression: celilo-mgmt deploy, v2/NETWORK_CONFIG_TO_FIREWALL.md).
+      expect(checkRequiredCapabilities('on_install', ['cross_module_read'], {})).toBeNull();
+      // Real missing providers still flagged alongside a privilege.
+      const mixed = checkRequiredCapabilities('on_install', ['cross_module_read', 'idp'], {});
+      expect(mixed).toContain("'idp'");
+      expect(mixed).not.toContain('cross_module_read');
+    });
   });
 });

package/src/hooks/executor.ts

@@ -21,12 +21,17 @@
 
 import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { isCompiledHook, isMissingProviderInputError } from '@celilo/capabilities';
+import {
+  type DeployedSystem,
+  isCompiledHook,
+  isMissingProviderInputError,
+} from '@celilo/capabilities';
 import {
   type ContractHookSignature,
   resolveContract,
   supportedContractVersions,
 } from '../manifest/contracts';
+import { isPrivilegedCapability } from '../manifest/validate';
 import type { HookContext, HookDefinition, HookLogger, HookResult } from './types';
 
 /** Default total timeout: 60 seconds */
@@ -256,6 +261,13 @@ export interface InvokeHookOptions {
   debug?: boolean;
   /** Pre-loaded capability function interfaces to inject into context */
   capabilities?: Record<string, unknown>;
+  /**
+   * The module's 0..N deployed systems, injected as `ctx.systems`
+   * (v2/MODULE_SYSTEMS_ADDRESSING.md). Callers load these from the DB via
+   * `getModuleSystems` — the executor stays decoupled from the database, the
+   * same way `capabilities` is loaded by the caller. Defaults to `[]`.
+   */
+  systems?: DeployedSystem[];
   /**
    * Names of capabilities the hook's module declares in
    * `requires.capabilities`. The executor checks each one is present in
@@ -280,7 +292,13 @@ export function checkRequiredCapabilities(
   requiredCapabilities: string[],
   loadedCapabilities: Record<string, unknown>,
 ): string | null {
-  const missing = requiredCapabilities.filter((name) => !(name in loadedCapabilities));
+  // Framework-granted privileges (e.g. cross_module_read) aren't loaded as
+  // provider capability-functions — they're granted by the framework to the
+  // specific hooks that use them (backup/restore), via a separate mechanism.
+  // Don't treat them as missing providers for every hook (e.g. on_install).
+  const missing = requiredCapabilities.filter(
+    (name) => !isPrivilegedCapability(name) && !(name in loadedCapabilities),
+  );
   if (missing.length === 0) return null;
 
   const lines = [
@@ -404,6 +422,7 @@ export async function invokeHook(
     ...inputs,
     config,
     secrets,
+    systems: options.systems ?? [],
     logger,
     debug,
     screenshotDir,

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

@@ -18,7 +18,8 @@
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import type { DbClient } from '../db/client';
-import { machines, moduleConfigs, moduleInfrastructure, modules } from '../db/schema';
+import { machines, moduleInfrastructure, modules } from '../db/schema';
+import { upsertModuleConfig } from '../services/module-config';
 import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
 import { loadHookConfigMap } from './load-hook-config';
 
@@ -48,39 +49,42 @@ describe('loadHookConfigMap', () => {
   });
 
   test('returns scalar string config values from module_configs', async () => {
-    db.insert(moduleConfigs)
-      .values([
-        { moduleId: 'mod', key: 'hostname', value: 'caddy', valueJson: null },
-        { moduleId: 'mod', key: 'acme_email', value: 'admin@example.com', valueJson: null },
-      ])
-      .run();
+    upsertModuleConfig(db, 'mod', 'hostname', 'caddy');
+    upsertModuleConfig(db, 'mod', 'acme_email', 'admin@example.com');
 
     const result = await loadHookConfigMap('mod', db);
     expect(result).toEqual({ hostname: 'caddy', acme_email: 'admin@example.com' });
   });
 
   test('parses valueJson for complex types (arrays, objects)', async () => {
-    db.insert(moduleConfigs)
-      .values([
-        {
-          moduleId: 'mod',
-          key: 'hostnames',
-          value: '',
-          valueJson: '["www.example.com","example.com"]',
-        },
-        { moduleId: 'mod', key: 'plain', value: 'string-val', valueJson: null },
-      ])
-      .run();
+    upsertModuleConfig(db, 'mod', 'hostnames', ['www.example.com', 'example.com']);
+    upsertModuleConfig(db, 'mod', 'plain', 'string-val');
 
     const result = await loadHookConfigMap('mod', db);
     expect(result.hostnames).toEqual(['www.example.com', 'example.com']);
     expect(result.plain).toBe('string-val');
   });
 
+  test('preserves primitive types (numbers, booleans) — Defect 1 round-trip', async () => {
+    // The headline defect that motivated Commit C: primitives used to
+    // stringify on write and come back as strings (e.g. ssh_external_port:
+    // 2222 → stored "2222" → read "2222" → silently broke
+    // firewall.exposeService that expected a number). With upsertModuleConfig
+    // routing through JSON, types round-trip cleanly.
+    upsertModuleConfig(db, 'mod', 'port', 2222);
+    upsertModuleConfig(db, 'mod', 'enabled', true);
+    upsertModuleConfig(db, 'mod', 'disabled', false);
+
+    const result = await loadHookConfigMap('mod', db);
+    expect(result.port).toBe(2222);
+    expect(typeof result.port).toBe('number');
+    expect(result.enabled).toBe(true);
+    expect(typeof result.enabled).toBe('boolean');
+    expect(result.disabled).toBe(false);
+  });
+
   test('preserves an explicit target_ip in module_configs (skips machine fallback)', async () => {
-    db.insert(moduleConfigs)
-      .values({ moduleId: 'mod', key: 'target_ip', value: '10.0.10.10', valueJson: null })
-      .run();
+    upsertModuleConfig(db, 'mod', 'target_ip', '10.0.10.10');
     // A machine record exists but should NOT override the explicit value.
     db.insert(machines)
       .values({
@@ -137,9 +141,7 @@ describe('loadHookConfigMap', () => {
   });
 
   test('leaves target_ip unset when there is no infrastructure record', async () => {
-    db.insert(moduleConfigs)
-      .values({ moduleId: 'mod', key: 'hostname', value: 'caddy', valueJson: null })
-      .run();
+    upsertModuleConfig(db, 'mod', 'hostname', 'caddy');
     // no moduleInfrastructure row inserted
 
     const result = await loadHookConfigMap('mod', db);

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

@@ -12,7 +12,15 @@
  * code, easy to miss.
  *
  * The shape:
- *   - Every row from `module_configs`, parsed from `valueJson` when set.
+ *   - 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
@@ -26,6 +34,7 @@
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { machines, moduleConfigs, moduleInfrastructure } from '../db/schema';
+import { parseStoredConfigValue } from '../services/module-config';
 
 export async function loadHookConfigMap(
   moduleId: string,
@@ -39,7 +48,7 @@ export async function loadHookConfigMap(
 
   const configMap: Record<string, unknown> = {};
   for (const c of configRecords) {
-    configMap[c.key] = c.valueJson ? JSON.parse(c.valueJson) : c.value;
+    configMap[c.key] = parseStoredConfigValue(c);
   }
 
   if (configMap.target_ip) return configMap;

package/src/hooks/run-named-hook.ts

@@ -18,6 +18,7 @@ import { modules, secrets } from '../db/schema';
 import type { ModuleManifest } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
+import { getModuleSystems } from '../services/deployed-systems';
 import { loadCapabilityFunctions } from './capability-loader';
 import { invokeHook } from './executor';
 import { loadHookConfigMap } from './load-hook-config';
@@ -81,6 +82,20 @@ export async function runNamedHook(
       notDefined: true,
     };
   }
+  // Defensive narrow: `on_upstream_publish` is also under
+  // `manifest.hooks` (build-bus, Phase 4) but is an ARRAY of
+  // match-rule hooks dispatched by the receiver daemon — NOT
+  // runnable via `celilo module run-hook`. The HookName type
+  // excludes it, but the indexed-access return type can't prove
+  // that, so narrow at the value level.
+  if (Array.isArray(hookDef)) {
+    return {
+      success: true,
+      outputs: {},
+      duration: Date.now() - startedAt,
+      notDefined: true,
+    };
+  }
 
   const configMap = await loadHookConfigMap(moduleId, db);
 
@@ -123,6 +138,7 @@ export async function runNamedHook(
       debug: options.debug ?? false,
       capabilities: capabilityFunctions,
       requiredCapabilities,
+      systems: getModuleSystems(moduleId, db),
     },
   );
 }