@celilo/cli 0.3.30 → 0.4.0-alpha.1

package/drizzle/0005_module_operations.sql

@@ -0,0 +1,12 @@
+CREATE TABLE `module_operations` (
+	`id` text PRIMARY KEY NOT NULL,
+	`module_id` text NOT NULL,
+	`operation` text NOT NULL,
+	`status` text DEFAULT 'in_progress' NOT NULL,
+	`pid` integer NOT NULL,
+	`started_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`completed_at` integer,
+	`error_message` text
+);
+--> statement-breakpoint
+CREATE INDEX `module_operations_status_idx` ON `module_operations` (`status`, `operation`);

package/drizzle/0006_base_module_aspects.sql

@@ -0,0 +1,15 @@
+CREATE TABLE `aspect_approvals` (
+	`id` text PRIMARY KEY NOT NULL,
+	`module_id` text NOT NULL,
+	`version` text NOT NULL,
+	`scope_hash` text NOT NULL,
+	`approved_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`approver` text,
+	FOREIGN KEY (`module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `aspect_approvals_module_version` ON `aspect_approvals` (`module_id`,`version`);
+--> statement-breakpoint
+ALTER TABLE `machines` ADD `api_only` integer DEFAULT false NOT NULL;
+--> statement-breakpoint
+ALTER TABLE `module_infrastructure` ADD `api_only` integer DEFAULT false NOT NULL;

package/drizzle/0007_module_systems.sql

@@ -0,0 +1,17 @@
+CREATE TABLE `module_systems` (
+	`module_id` text NOT NULL,
+	`name` text NOT NULL,
+	`hostname` text NOT NULL,
+	`ipv4_address` text NOT NULL,
+	`zone` text NOT NULL,
+	`infra_type` text NOT NULL,
+	`machine_id` text,
+	`service_id` text,
+	`vmid` integer,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch()) NOT NULL,
+	PRIMARY KEY(`module_id`, `name`),
+	FOREIGN KEY (`module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`machine_id`) REFERENCES `machines`(`id`) ON UPDATE no action ON DELETE no action,
+	FOREIGN KEY (`service_id`) REFERENCES `container_services`(`id`) ON UPDATE no action ON DELETE no action
+);

package/drizzle/meta/_journal.json

@@ -36,6 +36,27 @@
       "when": 1777680000000,
       "tag": "0004_caddy_hostname_list",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "6",
+      "when": 1779408000000,
+      "tag": "0005_module_operations",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "6",
+      "when": 1779840000000,
+      "tag": "0006_base_module_aspects",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "6",
+      "when": 1780459200000,
+      "tag": "0007_module_systems",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.3.30",
+  "version": "0.4.0-alpha.1",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -52,9 +52,9 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1024.0",
-    "@celilo/capabilities": "^0.1.10",
-    "@celilo/cli-display": "^0.1.9",
-    "@celilo/event-bus": "^0.1.4",
+    "@celilo/capabilities": "0.2.0-alpha.0",
+    "@celilo/cli-display": "0.1.9-alpha.0",
+    "@celilo/event-bus": "0.1.5-alpha.0",
     "@clack/prompts": "^1.1.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",
@@ -75,5 +75,6 @@
     "ink-testing-library": "^4.0.0",
     "typescript": "^5.9.3",
     "zod-to-json-schema": "^3.25.2"
-  }
+  },
+  "gitHead": "26189a1eaaa2a7da94a9098a16305d8a9a95ac50"
 }

package/schemas/system_config.json

@@ -13,89 +13,75 @@
     "network.dmz.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
-      "default": "10.0.10.0/24",
-      "description": "DMZ subnet CIDR"
+      "description": "DMZ subnet CIDR (not defaulted — appears only when a firewall module provides this zone; see v2/NETWORK_CONFIG_TO_FIREWALL.md)"
     },
     "network.dmz.gateway": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",
-      "default": "10.0.10.1",
-      "description": "DMZ gateway IP address"
+      "description": "DMZ gateway IP address (not defaulted)"
     },
     "network.dmz.vlan": {
       "type": "integer",
       "minimum": 1,
       "maximum": 4094,
-      "default": 10,
-      "description": "VLAN tag for DMZ zone (public-facing services)"
+      "description": "VLAN tag for DMZ zone (public-facing services; not defaulted)"
     },
     "network.app.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
-      "default": "10.0.20.0/24",
-      "description": "App subnet CIDR"
+      "description": "App subnet CIDR (not defaulted — appears only when a firewall module provides this zone)"
     },
     "network.app.gateway": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",
-      "default": "10.0.20.1",
-      "description": "App gateway IP address"
+      "description": "App gateway IP address (not defaulted)"
     },
     "network.app.vlan": {
       "type": "integer",
       "minimum": 1,
       "maximum": 4094,
-      "default": 20,
-      "description": "VLAN tag for app zone (internal application services)"
+      "description": "VLAN tag for app zone (internal application services; not defaulted)"
     },
     "network.secure.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
-      "default": "10.0.30.0/24",
-      "description": "Secure subnet CIDR"
+      "description": "Secure subnet CIDR (not defaulted — appears only when a firewall module provides this zone)"
     },
     "network.secure.gateway": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",
-      "default": "10.0.30.1",
-      "description": "Secure gateway IP address"
+      "description": "Secure gateway IP address (not defaulted)"
     },
     "network.secure.vlan": {
       "type": "integer",
       "minimum": 1,
       "maximum": 4094,
-      "default": 30,
-      "description": "VLAN tag for secure zone (authentication, databases)"
+      "description": "VLAN tag for secure zone (authentication, databases; not defaulted)"
     },
     "network.internal.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
-      "default": "192.168.0.0/24",
-      "description": "Internal subnet CIDR (home devices, trusted)"
+      "description": "Internal subnet CIDR (home devices, trusted; not defaulted — discovered from the management box's primary interface at celilo-mgmt install)"
     },
     "network.internal.gateway": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",
-      "default": "192.168.0.1",
-      "description": "Internal gateway IP address"
+      "description": "Internal gateway IP address (not defaulted — discovered from the default route)"
     },
     "network.internal.vlan": {
       "type": "integer",
       "minimum": 1,
       "maximum": 4094,
-      "default": 192,
-      "description": "VLAN tag for internal zone"
+      "description": "VLAN tag for internal zone (not defaulted; internal is untagged)"
     },
     "dns.primary": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",
-      "default": "1.1.1.1",
-      "description": "Primary DNS server IP address"
+      "description": "Primary DNS server IP address (not defaulted — discovered from the host resolver at celilo-mgmt install; repointed at a dns_internal provider when one deploys)"
     },
     "dns.fallback": {
       "type": "string",
-      "default": "1.0.0.1,8.8.8.8",
-      "description": "Fallback DNS servers (comma-separated IP addresses)"
+      "description": "Fallback DNS servers (comma-separated IP addresses; not defaulted — discovered, with 1.1.1.1 as last resort)"
     },
     "ssh.public_key": {
       "type": "string",

package/src/ansible/inventory.test.ts

@@ -2,7 +2,8 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { existsSync } from 'node:fs';
 import { rm } from 'node:fs/promises';
 import { type DbClient, createDbClient } from '../db/client';
-import { moduleConfigs, systemConfig } from '../db/schema';
+import { systemConfig } from '../db/schema';
+import { upsertModuleConfig } from '../services/module-config';
 import {
   buildHostVars,
   buildSystemVars,
@@ -93,6 +94,28 @@ describe('generateHostsIni', () => {
       `machine-host ansible_host=192.168.1.100 ansible_user=ubuntu ansible_ssh_private_key_file=${keyPath}`,
     );
   });
+
+  test('emits ansible_connection=local for a local machine (no SSH host/key)', () => {
+    // The management box deploying to itself uses Ansible's local
+    // connection (v2/CELILO_BOOTSTRAP_VIRTUAL_PACKAGE.md).
+    const hosts: InventoryHost[] = [
+      {
+        hostname: 'celilo-mgr',
+        ansibleHost: '127.0.0.1',
+        ansibleUser: 'root',
+        groups: ['celilo-mgmt'],
+        local: true,
+        // even if a key path were present, local hosts must ignore it
+        ansibleSshPrivateKeyFile: '/tmp/should-not-appear.key',
+      },
+    ];
+
+    const result = generateHostsIni(hosts);
+
+    expect(result).toContain('celilo-mgr ansible_connection=local');
+    expect(result).not.toContain('ansible_host=127.0.0.1');
+    expect(result).not.toContain('should-not-appear');
+  });
 });
 
 describe('generateHostVarsYaml', () => {
@@ -283,20 +306,14 @@ describe('Database integration', () => {
         `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('homebridge', 'Homebridge', '1.0.0', '/path', '{}')`,
       );
 
-      // Insert module config with proper schema
-      db.insert(moduleConfigs)
-        .values([
-          { moduleId: 'homebridge', key: 'vmid', value: '2110', valueJson: null },
-          { moduleId: 'homebridge', key: 'hostname', value: 'iot', valueJson: null },
-          {
-            moduleId: 'homebridge',
-            key: 'target_ip',
-            value: '192.168.0.110/24',
-            valueJson: null,
-          },
-          { moduleId: 'homebridge', key: 'cores', value: '1', valueJson: null },
-        ])
-        .run();
+      // Insert module config via the typed-storage helper so
+      // parseStoredConfigValue can roundtrip them. Numbers stay numbers,
+      // strings stay strings, etc. (vmid=2110, cores=1 are integers in
+      // the manifest — test that the type round-trips correctly.)
+      upsertModuleConfig(db, 'homebridge', 'vmid', 2110);
+      upsertModuleConfig(db, 'homebridge', 'hostname', 'iot');
+      upsertModuleConfig(db, 'homebridge', 'target_ip', '192.168.0.110/24');
+      upsertModuleConfig(db, 'homebridge', 'cores', 1);
 
       const vars = buildHostVars('homebridge', db);
 
@@ -311,12 +328,8 @@ describe('Database integration', () => {
         `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('test', 'Test', '1.0.0', '/path', '{}')`,
       );
 
-      db.insert(moduleConfigs)
-        .values([
-          { moduleId: 'test', key: 'network.interface', value: 'eth0', valueJson: null },
-          { moduleId: 'test', key: 'network.ip', value: '192.168.0.1', valueJson: null },
-        ])
-        .run();
+      upsertModuleConfig(db, 'test', 'network.interface', 'eth0');
+      upsertModuleConfig(db, 'test', 'network.ip', '192.168.0.1');
 
       const vars = buildHostVars('test', db);
 
@@ -329,18 +342,9 @@ describe('Database integration', () => {
         `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('test', 'Test', '1.0.0', '/path', '{}')`,
       );
 
-      db.insert(moduleConfigs)
-        .values([
-          { moduleId: 'test', key: 'hostname', value: 'iot', valueJson: null },
-          { moduleId: 'test', key: 'inventory.hostname', value: 'iot', valueJson: null },
-          {
-            moduleId: 'test',
-            key: 'inventory.ansible_host',
-            value: '192.168.0.110',
-            valueJson: null,
-          },
-        ])
-        .run();
+      upsertModuleConfig(db, 'test', 'hostname', 'iot');
+      upsertModuleConfig(db, 'test', 'inventory.hostname', 'iot');
+      upsertModuleConfig(db, 'test', 'inventory.ansible_host', '192.168.0.110');
 
       const vars = buildHostVars('test', db);
 
@@ -354,17 +358,9 @@ describe('Database integration', () => {
         `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('dns', 'DNS', '1.0.0', '/path', '{}')`,
       );
 
-      // Complex array type - store in valueJson column
-      db.insert(moduleConfigs)
-        .values([
-          {
-            moduleId: 'dns',
-            key: 'zone_records',
-            value: '', // Empty for complex types
-            valueJson: '[{"name":"ns1","type":"A","value":"188.166.157.2"}]',
-          },
-        ])
-        .run();
+      upsertModuleConfig(db, 'dns', 'zone_records', [
+        { name: 'ns1', type: 'A', value: '188.166.157.2' },
+      ]);
 
       const vars = buildHostVars('dns', db);
 
@@ -402,12 +398,8 @@ describe('Database integration', () => {
         `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('homebridge', 'Homebridge', '1.0.0', '/path', '{}')`,
       );
 
-      db.insert(moduleConfigs)
-        .values([
-          { moduleId: 'homebridge', key: 'hostname', value: 'iot' },
-          { moduleId: 'homebridge', key: 'target_ip', value: '192.168.0.110/24' },
-        ])
-        .run();
+      upsertModuleConfig(db, 'homebridge', 'hostname', 'iot');
+      upsertModuleConfig(db, 'homebridge', 'target_ip', '192.168.0.110/24');
 
       const host = extractInventoryHost('homebridge', db);
 
@@ -423,12 +415,8 @@ describe('Database integration', () => {
         `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('dns-external', 'DNS External', '1.0.0', '/path', '{}')`,
       );
 
-      db.insert(moduleConfigs)
-        .values([
-          { moduleId: 'dns-external', key: 'hostname', value: 'dns-ext' },
-          { moduleId: 'dns-external', key: 'vps_ip', value: '188.166.157.2' },
-        ])
-        .run();
+      upsertModuleConfig(db, 'dns-external', 'hostname', 'dns-ext');
+      upsertModuleConfig(db, 'dns-external', 'vps_ip', '188.166.157.2');
 
       const host = extractInventoryHost('dns-external', db);
 
@@ -444,12 +432,8 @@ describe('Database integration', () => {
         `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('test', 'Test', '1.0.0', '/path', '{}')`,
       );
 
-      db.insert(moduleConfigs)
-        .values([
-          { moduleId: 'test', key: 'hostname', value: 'iot' },
-          // Missing target_ip or vps_ip for ansible_host
-        ])
-        .run();
+      upsertModuleConfig(db, 'test', 'hostname', 'iot');
+      // Missing target_ip or vps_ip for ansible_host
 
       const host = extractInventoryHost('test', db);
 

package/src/ansible/inventory.ts

@@ -4,6 +4,8 @@ import { eq } from 'drizzle-orm';
 import { stringify as stringifyYaml } from 'yaml';
 import type { DbClient } from '../db/client';
 import { machines, moduleConfigs, systemConfig } from '../db/schema';
+import { getModuleSystems } from '../services/deployed-systems';
+import { parseStoredConfigValue } from '../services/module-config';
 import { getTempKeyPath } from '../services/ssh-key-manager';
 
 /**
@@ -25,6 +27,12 @@ export interface InventoryHost {
   ansibleUser: string;
   groups: string[];
   ansibleSshPrivateKeyFile?: string;
+  /**
+   * The management box deploying to itself (127.0.0.1) uses Ansible's
+   * local connection — no SSH, no ansible_host/key. See
+   * v2/CELILO_BOOTSTRAP_VIRTUAL_PACKAGE.md.
+   */
+  local?: boolean;
 }
 
 /**
@@ -54,6 +62,11 @@ export function generateHostsIni(hosts: InventoryHost[]): string {
   for (const [group, groupHosts] of groupMap) {
     lines.push(`[${group}]`);
     for (const host of groupHosts) {
+      if (host.local) {
+        // Local connection: no SSH, no key — Ansible runs commands directly.
+        lines.push(`${host.hostname} ansible_connection=local`);
+        continue;
+      }
       let hostLine = `${host.hostname} ansible_host=${host.ansibleHost} ansible_user=${host.ansibleUser}`;
       if (host.ansibleSshPrivateKeyFile) {
         hostLine += ` ansible_ssh_private_key_file=${host.ansibleSshPrivateKeyFile}`;
@@ -175,27 +188,27 @@ export function buildHostVars(moduleId: string, db: DbClient): Record<string, un
       continue;
     }
 
-    // Parse value from correct column
-    let parsedValue: unknown;
-    if (config.valueJson) {
-      // Complex type stored in valueJson
-      try {
-        parsedValue = JSON.parse(config.valueJson);
-      } catch (error) {
-        throw new Error(
-          `Failed to parse config value for ${config.key}: ${error instanceof Error ? error.message : 'Invalid JSON'}`,
-        );
-      }
-    } else {
-      // Primitive type stored in value
-      parsedValue = parseConfigValue(config.value);
-    }
+    // Use shared typed-storage parser — preserves number/boolean/string/
+    // complex types end-to-end. The two-column logic that used to live
+    // here (valueJson ? parse : parseConfigValue) was a casualty of
+    // Defect 1 and no longer makes sense — every row has valueJson
+    // populated as of the type-fidelity refactor.
+    const parsedValue = parseStoredConfigValue(config);
 
     // Store with underscore naming
     const key = config.key.replace(/\./g, '_');
     vars[key] = parsedValue;
   }
 
+  // The host's IP is sourced from the deployed-systems model now, not a
+  // `target_ip` config row (v2/MODULE_SYSTEMS_ADDRESSING.md). Emit it as the
+  // `target_ip` host_var so Ansible templates that reference `{{ target_ip }}`
+  // (zone files, DNS record tasks) keep working. Single-system modules have one.
+  const recordedSystems = getModuleSystems(moduleId, db);
+  if (recordedSystems[0]) {
+    vars.target_ip = recordedSystems[0].ipv4_address;
+  }
+
   // Sort keys alphabetically for deterministic YAML output
   return sortObjectKeys(vars);
 }
@@ -244,14 +257,21 @@ export function extractInventoryHost(moduleId: string, db: DbClient): InventoryH
 
   const moduleConfig: Record<string, string> = {};
   for (const config of configs) {
-    // Parse value from correct column (same logic as buildHostVars)
-    if (config.valueJson) {
-      // Complex type stored in valueJson
-      moduleConfig[config.key] = config.valueJson;
-    } else {
-      // Primitive type stored in value
-      moduleConfig[config.key] = config.value;
-    }
+    // Inventory derivation works in string form (hostnames, IPs, group
+    // names). Use the display-string `value` column — it's already the
+    // canonical human-readable form populated by upsertModuleConfig.
+    // For complex types `value` is the JSON-stringified form, which
+    // matches the legacy behavior here.
+    moduleConfig[config.key] = config.value;
+  }
+
+  // The host's IP now comes from the deployed-systems model, not a `target_ip`
+  // config row (v2/MODULE_SYSTEMS_ADDRESSING.md). Inject it so the
+  // ansible_host derivation below and the Ansible `{{ target_ip }}` host_var
+  // (zone files, DNS record tasks) resolve. Single-system modules have one.
+  const recordedSystems = getModuleSystems(moduleId, db);
+  if (recordedSystems[0]) {
+    moduleConfig.target_ip = recordedSystems[0].ipv4_address;
   }
 
   // Auto-derive inventory variables (same logic as context.ts)
@@ -373,13 +393,16 @@ export async function generateInventory(
         (c: typeof moduleConfigs.$inferSelect) => c.key === 'hostname',
       )?.value;
 
-      // Build host definition from machine
+      // Build host definition from machine. The local box (127.0.0.1)
+      // uses Ansible's local connection — no SSH key/host.
+      const isLocal = machine.ipAddress === '127.0.0.1';
       host = {
         hostname: moduleHostname || machine.hostname,
         ansibleHost: machine.ipAddress,
         ansibleUser: machine.sshUser,
         groups: [moduleId], // Use module ID as group
-        ansibleSshPrivateKeyFile: getTempKeyPath(machine.id),
+        local: isLocal,
+        ansibleSshPrivateKeyFile: isLocal ? undefined : getTempKeyPath(machine.id),
       };
     } else {
       // Container service or no infrastructure: use module config

package/src/capabilities/registration.ts

@@ -9,6 +9,7 @@ import type { ModuleManifest } from '../manifest/schema';
 import { encryptSecret } from '../secrets/encryption';
 import type { EncryptedSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
+import { computedMarker } from '../variables/computed/marker';
 
 export interface RegistrationResult {
   success: boolean;
@@ -45,7 +46,9 @@ export async function registerModuleCapabilities(
   }
 
   try {
-    const _masterKey = await getOrCreateMasterKey();
+    // Ensure the master key exists (side effect); registration stores secret
+    // metadata only, so the key itself isn't used here.
+    await getOrCreateMasterKey();
 
     for (const capability of manifest.provides.capabilities) {
       // Build capability data by resolving $self: variables
@@ -104,16 +107,31 @@ export async function registerModuleCapabilities(
  * @returns Capability data with resolved variables
  */
 export function buildCapabilityData(
-  capability: { data?: Record<string, unknown> },
+  capability: {
+    name?: string;
+    data?: Record<string, unknown>;
+    computed?: Array<{ name: string; value: string }>;
+  },
   _manifest: ModuleManifest,
 ): Record<string, unknown> {
-  if (!capability.data) {
-    return {};
+  // Static data is stored verbatim (any $self: refs are resolved lazily at
+  // read time by the variable resolver).
+  const data: Record<string, unknown> = capability.data ? structuredClone(capability.data) : {};
+
+  // Fold computed fields into the data namespace as markers. They resolve
+  // lazily in the PROVIDER's context at read time — see resolver.ts and
+  // src/variables/computed/. A computed name colliding with a static data
+  // key is a manifest error.
+  for (const field of capability.computed ?? []) {
+    if (field.name in data) {
+      throw new Error(
+        `Capability '${capability.name ?? '?'}': computed field '${field.name}' collides with a static data key`,
+      );
+    }
+    data[field.name] = computedMarker(field.value);
   }
 
-  // Capability data is static (no $self: variables in well-known capabilities)
-  // This function is here for future extensibility
-  return structuredClone(capability.data);
+  return data;
 }
 
 /**

package/src/capabilities/validation.test.ts

@@ -241,6 +241,36 @@ describe('Capability Access Validation', () => {
       expect(result.error).toContain('No module provides this capability');
     });
 
+    test('should skip framework-granted privileges (no provider required)', async () => {
+      // cross_module_read is a privilege (allow-listed to celilo-mgmt),
+      // not a provider-backed capability. validateCapabilityAccess must
+      // not demand a providing module for it — otherwise celilo-mgmt
+      // can't be imported (regression: v2/NETWORK_CONFIG_TO_FIREWALL.md).
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'celilo-mgmt',
+        name: 'Celilo Management Server',
+        version: '1.0.0',
+        description: 'Management server',
+        requires: {
+          capabilities: [{ name: 'cross_module_read', version: '^1.0' }],
+        },
+        provides: { capabilities: [] },
+        variables: { owns: [], imports: [] },
+      };
+
+      // DB must NOT be consulted for a privilege — fail loudly if it is.
+      const mockDb = {
+        prepare: () => {
+          throw new Error('getProviderManifest should not be called for a privilege');
+        },
+      } as unknown as Database;
+
+      const result = await validateCapabilityAccess(manifest, mockDb);
+
+      expect(result.success).toBe(true);
+    });
+
     test('should return success when capability has no secrets', async () => {
       const manifest: ModuleManifest = {
         celilo_contract: '1.0',

package/src/capabilities/validation.ts

@@ -5,6 +5,7 @@
 
 import type { Database } from 'bun:sqlite';
 import type { ModuleManifest } from '../manifest/schema';
+import { isPrivilegedCapability } from '../manifest/validate';
 
 export interface ValidationResult {
   success: boolean;
@@ -35,6 +36,13 @@ export async function validateCapabilityAccess(
 
   // Check each required capability
   for (const requiredCapability of manifest.requires.capabilities) {
+    // Framework-granted privileges (e.g. cross_module_read) are not
+    // provider-backed — they're gated separately by the allow-list in
+    // validatePrivilegedCapabilities. Don't demand a providing module.
+    if (isPrivilegedCapability(requiredCapability.name)) {
+      continue;
+    }
+
     // Get the provider module's manifest
     const providerManifest = getProviderManifest(requiredCapability.name, db);