@celilo/cli 0.5.0-alpha.4 → 0.5.0-alpha.6

package/src/config/paths.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { skipIntegration } from '../test-utils/integration-guard';
 import { getDataDir, getDbPath, getMasterKeyPath, getModuleStoragePath } from './paths';
 
 describe('paths configuration', () => {
@@ -34,18 +35,21 @@ describe('paths configuration', () => {
       expect(path).toMatch(/celilo-data\/modules$/);
     });
 
-    it('returns platform-specific path by default', () => {
-      process.env.CELILO_DATA_DIR = undefined;
-      process.env.ENVIRONMENT = undefined;
+    it.skipIf(skipIntegration({ platform: 'darwin' }))(
+      'returns platform-specific path by default',
+      () => {
+        process.env.CELILO_DATA_DIR = undefined;
+        process.env.ENVIRONMENT = undefined;
 
-      const path = getModuleStoragePath();
+        const path = getModuleStoragePath();
 
-      if (process.platform === 'darwin') {
-        expect(path).toMatch(/Library\/Application Support\/celilo\/modules$/);
-      } else {
-        expect(path).toBe('/var/lib/celilo/modules');
-      }
-    });
+        if (process.platform === 'darwin') {
+          expect(path).toMatch(/Library\/Application Support\/celilo\/modules$/);
+        } else {
+          expect(path).toBe('/var/lib/celilo/modules');
+        }
+      },
+    );
 
     it('prioritizes CELILO_DATA_DIR over ENVIRONMENT=dev', () => {
       process.env.CELILO_DATA_DIR = '/custom/data';
@@ -73,18 +77,21 @@ describe('paths configuration', () => {
       expect(path).toMatch(/celilo-data$/);
     });
 
-    it('returns platform-specific path by default', () => {
-      process.env.CELILO_DATA_DIR = undefined;
-      process.env.ENVIRONMENT = undefined;
-
-      const path = getDataDir();
-
-      if (process.platform === 'darwin') {
-        expect(path).toMatch(/Library\/Application Support\/celilo$/);
-      } else {
-        expect(path).toBe('/var/lib/celilo');
-      }
-    });
+    it.skipIf(skipIntegration({ platform: 'darwin' }))(
+      'returns platform-specific path by default',
+      () => {
+        process.env.CELILO_DATA_DIR = undefined;
+        process.env.ENVIRONMENT = undefined;
+
+        const path = getDataDir();
+
+        if (process.platform === 'darwin') {
+          expect(path).toMatch(/Library\/Application Support\/celilo$/);
+        } else {
+          expect(path).toBe('/var/lib/celilo');
+        }
+      },
+    );
   });
 
   describe('getMasterKeyPath', () => {
@@ -103,19 +110,22 @@ describe('paths configuration', () => {
       expect(path).toBe('/custom/data/master.key');
     });
 
-    it('uses platform-specific data dir by default', () => {
-      process.env.CELILO_MASTER_KEY_PATH = undefined;
-      process.env.CELILO_DATA_DIR = undefined;
-      process.env.ENVIRONMENT = undefined;
-
-      const path = getMasterKeyPath();
-
-      if (process.platform === 'darwin') {
-        expect(path).toMatch(/Library\/Application Support\/celilo\/master\.key$/);
-      } else {
-        expect(path).toBe('/var/lib/celilo/master.key');
-      }
-    });
+    it.skipIf(skipIntegration({ platform: 'darwin' }))(
+      'uses platform-specific data dir by default',
+      () => {
+        process.env.CELILO_MASTER_KEY_PATH = undefined;
+        process.env.CELILO_DATA_DIR = undefined;
+        process.env.ENVIRONMENT = undefined;
+
+        const path = getMasterKeyPath();
+
+        if (process.platform === 'darwin') {
+          expect(path).toMatch(/Library\/Application Support\/celilo\/master\.key$/);
+        } else {
+          expect(path).toBe('/var/lib/celilo/master.key');
+        }
+      },
+    );
   });
 
   describe('getDbPath', () => {
@@ -128,19 +138,22 @@ describe('paths configuration', () => {
       expect(path).toBe('/custom/path/celilo.db');
     });
 
-    it('returns data dir + celilo.db on macOS in production', () => {
-      process.env.CELILO_DB_PATH = undefined;
-      process.env.CELILO_DATA_DIR = undefined;
-      process.env.ENVIRONMENT = undefined;
-
-      const path = getDbPath();
-
-      if (process.platform === 'darwin') {
-        expect(path).toMatch(/Library\/Application Support\/celilo\/celilo.db$/);
-      } else {
-        expect(path).toBe('/var/lib/celilo/celilo.db');
-      }
-    });
+    it.skipIf(skipIntegration({ platform: 'darwin' }))(
+      'returns data dir + celilo.db on macOS in production',
+      () => {
+        process.env.CELILO_DB_PATH = undefined;
+        process.env.CELILO_DATA_DIR = undefined;
+        process.env.ENVIRONMENT = undefined;
+
+        const path = getDbPath();
+
+        if (process.platform === 'darwin') {
+          expect(path).toMatch(/Library\/Application Support\/celilo\/celilo.db$/);
+        } else {
+          expect(path).toBe('/var/lib/celilo/celilo.db');
+        }
+      },
+    );
 
     it('returns celilo-data/celilo.db in development mode', () => {
       process.env.CELILO_DB_PATH = undefined;

package/src/db/client.ts

@@ -41,145 +41,6 @@ export function findMigrationsFolder(): string {
   throw new Error(`Could not find drizzle migrations folder. Tried: ${candidates.join(', ')}`);
 }
 
-/**
- * Check if database needs initialization (tables don't exist)
- */
-function needsMigration(sqlite: Database): boolean {
-  try {
-    // Check if the modules table exists at all (new database)
-    const result = sqlite
-      .query("SELECT name FROM sqlite_master WHERE type='table' AND name='modules'")
-      .get();
-    if (!result) return true; // New database — run full migrations
-
-    // Existing database — apply incremental schema updates
-    // Each statement is wrapped in try/catch (no-op if already applied)
-    const alterStatements = [
-      'ALTER TABLE capabilities ADD zones text',
-      'ALTER TABLE machines ADD earmarked_module text',
-      // web_routes' subdomain/custom_domain columns were folded into a
-      // single `hostname` field by migration 0004. Don't re-add them
-      // here — the migration drops and recreates the table.
-      // Backup system tables (Phase 1)
-      `CREATE TABLE IF NOT EXISTS backup_storages (
-        id text PRIMARY KEY NOT NULL,
-        storage_id text NOT NULL UNIQUE,
-        name text NOT NULL,
-        provider_name text NOT NULL,
-        credentials_encrypted text NOT NULL,
-        provider_config text NOT NULL,
-        verified integer DEFAULT 0 NOT NULL,
-        verified_at integer,
-        verification_error text,
-        is_default integer DEFAULT 0 NOT NULL,
-        created_at integer DEFAULT (unixepoch()) NOT NULL,
-        updated_at integer DEFAULT (unixepoch()) NOT NULL
-      )`,
-      `CREATE TABLE IF NOT EXISTS backups (
-        id text PRIMARY KEY NOT NULL,
-        module_id text REFERENCES modules(id) ON DELETE SET NULL,
-        storage_id text NOT NULL REFERENCES backup_storages(id),
-        storage_path text NOT NULL,
-        backup_type text NOT NULL,
-        module_version text,
-        schema_version text,
-        size_bytes integer,
-        metadata text DEFAULT '{}' NOT NULL,
-        status text DEFAULT 'in_progress' NOT NULL,
-        error_message text,
-        started_at integer DEFAULT (unixepoch()) NOT NULL,
-        completed_at integer
-      )`,
-      // Backup naming support
-      'ALTER TABLE backups ADD name text',
-      // Module systems (v2/MODULE_SYSTEMS_ADDRESSING.md) — a module's 0..N
-      // deployed hosts. Fresh DBs get this via migration 0007; existing installs
-      // get it here. Replaces the scalar target_ip/vmid rows in module_configs.
-      `CREATE TABLE IF NOT EXISTS module_systems (
-        module_id text NOT NULL REFERENCES modules(id) ON DELETE cascade,
-        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 REFERENCES machines(id),
-        service_id text REFERENCES container_services(id),
-        vmid integer,
-        created_at integer DEFAULT (unixepoch()) NOT NULL,
-        updated_at integer DEFAULT (unixepoch()) NOT NULL,
-        PRIMARY KEY (module_id, name)
-      )`,
-      // Aspect consent decision (ISS-0027). Fresh DBs get this via migration
-      // 0008; existing installs get it here. Defaults to true so pre-existing
-      // rows (all approvals) keep running; false = a durable refusal.
-      'ALTER TABLE aspect_approvals ADD consented integer DEFAULT true NOT NULL',
-    ];
-
-    for (const stmt of alterStatements) {
-      try {
-        sqlite.exec(stmt);
-      } catch {
-        // Column already exists — fine
-      }
-    }
-
-    // web_routes hostname migration (CADDY_HOSTNAME_LIST design).
-    // Drizzle's auto-migrate path (`migrate()`) only runs for fresh
-    // databases — for existing celilo installs we apply the schema
-    // change here. Phase 0 + no production users = destructive
-    // rebuild; modules repopulate routes on their next deploy.
-    try {
-      const cols = sqlite.query("SELECT name FROM pragma_table_info('web_routes')").all() as Array<{
-        name: string;
-      }>;
-      const hasHostname = cols.some((c) => c.name === 'hostname');
-      const hasOldColumns = cols.some((c) => c.name === 'subdomain' || c.name === 'custom_domain');
-      if (!hasHostname && cols.length > 0) {
-        // Old shape detected (or missing hostname) — drop and recreate.
-        // Wrap in a transaction so the table is never half-migrated.
-        sqlite.exec('BEGIN');
-        try {
-          sqlite.exec('DROP TABLE web_routes');
-          sqlite.exec(`CREATE TABLE web_routes (
-            id integer PRIMARY KEY AUTOINCREMENT NOT NULL,
-            slug text NOT NULL,
-            module_id text NOT NULL,
-            type text NOT NULL,
-            path text NOT NULL,
-            hostname text NOT NULL,
-            target_host text,
-            target_port integer,
-            websocket integer DEFAULT false NOT NULL,
-            content_hash text,
-            created_at integer DEFAULT (unixepoch()) NOT NULL,
-            updated_at integer DEFAULT (unixepoch()) NOT NULL,
-            FOREIGN KEY (module_id) REFERENCES modules(id) ON UPDATE no action ON DELETE cascade
-          )`);
-          sqlite.exec(
-            'CREATE UNIQUE INDEX web_routes_hostname_path_idx ON web_routes (hostname, path)',
-          );
-          sqlite.exec('COMMIT');
-          if (hasOldColumns) {
-            console.log(
-              'web_routes migrated to hostname-based schema. Modules will repopulate their routes on next deploy.',
-            );
-          }
-        } catch (err) {
-          sqlite.exec('ROLLBACK');
-          throw err;
-        }
-      }
-    } catch (err) {
-      console.error('Failed to migrate web_routes schema:', err);
-      throw err;
-    }
-
-    return false; // Schema is up to date
-  } catch {
-    return true;
-  }
-}
-
 /**
  * Create database client and run migrations if needed
  */
@@ -209,12 +70,21 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
 
   const db = drizzle(sqlite, { schema });
 
-  // Auto-run migrations if database is new
-  if (!readonly && needsMigration(sqlite)) {
+  // Apply migrations on open (ISS-0100). Drizzle's migrator is the single
+  // migration mechanism for ALL DBs — fresh and existing — and the only place
+  // schema changes live (the old imperative hand-list is gone). migrate() is
+  // idempotent: it applies every migration newer than the latest recorded in
+  // `__drizzle_migrations` and no-ops once current.
+  //
+  // One-time caveat (ISS-0100): an existing DB from the hand-list era has a
+  // frozen `__drizzle_migrations` watermark; it must be remediated by hand
+  // (stamp the watermark to the latest migration + create any missing table)
+  // BEFORE this code opens it, or migrate() re-runs already-applied migrations
+  // and throws. `celilo system doctor` (checkSchemaDrift) detects the drift.
+  if (!readonly) {
     try {
       const migrationsFolder = findMigrationsFolder();
       migrate(db, { migrationsFolder });
-      console.log('Database initialized with migrations');
     } catch (error) {
       console.error('Failed to run migrations:', error);
       throw error;
@@ -222,10 +92,9 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
   }
 
   // One-time upgrade backfill for the target_ip → module_systems refactor
-  // (v2/MODULE_SYSTEMS_ADDRESSING.md). Runs for both paths above: needsMigration
-  // has already ensured the module_systems table exists (via migration 0007 for
-  // a fresh DB, or the imperative CREATE for an existing install). A deployment
-  // created before the refactor has its host data only in module_configs /
+  // (v2/MODULE_SYSTEMS_ADDRESSING.md). migrate() above has ensured the
+  // module_systems table exists (migration 0007). A deployment created before
+  // the refactor has its host data only in module_configs /
   // ip_allocations / module_infrastructure and an EMPTY module_systems, so its
   // modules resolve to no system and the migrated hooks throw "No deployed
   // system found". This lifts that state across. Idempotent (skips modules

package/src/db/migrate.ts

@@ -1,17 +1,25 @@
 import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
-import { closeDb, createDbClient, findMigrationsFolder } from './client';
+import { type DbClient, closeDb, createDbClient, findMigrationsFolder } from './client';
 
 /**
- * Run database migrations
+ * Apply pending drizzle migrations to an open DB. Idempotent — drizzle applies
+ * only migrations newer than the latest recorded in `__drizzle_migrations`.
+ * The single migration mechanism (ISS-0100); createDbClient also calls this
+ * shape on open (auto-migrate).
+ */
+export function runMigrationsOn(db: DbClient): void {
+  migrate(db, { migrationsFolder: findMigrationsFolder() });
+}
+
+/**
+ * Run database migrations (standalone entrypoint — `bun run src/db/migrate.ts`).
+ * createDbClient already migrates on open; this re-asserts for explicit use.
  */
 export async function runMigrations(dbPath?: string) {
   console.log('Running database migrations...');
-
   const db = createDbClient(dbPath ? { path: dbPath } : undefined);
-
   try {
-    const migrationsFolder = findMigrationsFolder();
-    await migrate(db, { migrationsFolder });
+    runMigrationsOn(db);
     console.log('Migrations completed successfully');
   } catch (error) {
     console.error('Migration failed:', error);

package/src/db/schema-introspection.ts

@@ -0,0 +1,88 @@
+/**
+ * Schema introspection — compare the DB's actual tables/columns against the
+ * tables the running code's drizzle schema declares. The single source for
+ * "what does the code expect, and is it present?" shared by:
+ *   - the migration baseline (db/migrate.ts) — to decide which migrations are
+ *     already applied on an existing DB before running migrate() (ISS-0100), and
+ *   - the doctor's schema-drift check (services/fleet-checks.ts) — to report
+ *     missing tables/columns to the operator (ISS-0113).
+ */
+
+import type { Database } from 'bun:sqlite';
+import { is } from 'drizzle-orm';
+import { SQLiteTable, getTableConfig } from 'drizzle-orm/sqlite-core';
+import * as dbSchema from './schema';
+
+export interface SchemaDrift {
+  /** Tables the code's schema declares that the DB lacks. */
+  missingTables: string[];
+  /** `table.column` the code declares that the DB's table lacks. */
+  missingColumns: string[];
+  /** Total number of tables the code's schema declares. */
+  tableCount: number;
+}
+
+/** Every table name + column names the drizzle schema declares. */
+export function getSchemaTables(): Array<{ name: string; columns: string[] }> {
+  const out: Array<{ name: string; columns: string[] }> = [];
+  for (const value of Object.values(dbSchema)) {
+    if (!is(value, SQLiteTable)) continue;
+    const cfg = getTableConfig(value);
+    out.push({ name: cfg.name, columns: cfg.columns.map((c) => c.name) });
+  }
+  return out;
+}
+
+/** Names of all tables that physically exist in the DB. */
+export function getExistingTables(sqlite: Database): Set<string> {
+  return new Set(
+    sqlite
+      .query<{ name: string }, []>("SELECT name FROM sqlite_master WHERE type='table'")
+      .all()
+      .map((r) => r.name),
+  );
+}
+
+/** Names of all indexes that physically exist in the DB. */
+export function getExistingIndexes(sqlite: Database): Set<string> {
+  return new Set(
+    sqlite
+      .query<{ name: string }, []>("SELECT name FROM sqlite_master WHERE type='index'")
+      .all()
+      .map((r) => r.name),
+  );
+}
+
+/** Column names physically present on a table (empty if the table is absent). */
+export function getExistingColumns(sqlite: Database, table: string): Set<string> {
+  // `table` is a schema/migration identifier (never user input) — safe to inline.
+  return new Set(
+    sqlite
+      .query<{ name: string }, []>(`SELECT name FROM pragma_table_info('${table}')`)
+      .all()
+      .map((r) => r.name),
+  );
+}
+
+/**
+ * Compare the running code's drizzle schema to the DB and report what's missing.
+ * Track-agnostic: it reads actual table/column presence, so it's honest whether
+ * the DB was migrated, baselined, or hand-patched.
+ */
+export function findSchemaDrift(sqlite: Database): SchemaDrift {
+  const present = getExistingTables(sqlite);
+  const missingTables: string[] = [];
+  const missingColumns: string[] = [];
+  const tables = getSchemaTables();
+  for (const t of tables) {
+    if (!present.has(t.name)) {
+      missingTables.push(t.name);
+      continue;
+    }
+    const cols = getExistingColumns(sqlite, t.name);
+    for (const c of t.columns) {
+      if (!cols.has(c)) missingColumns.push(`${t.name}.${c}`);
+    }
+  }
+  return { missingTables, missingColumns, tableCount: tables.length };
+}

package/src/db/schema.ts

@@ -468,6 +468,44 @@ export const dnsRegistrations = sqliteTable(
   }),
 );
 
+/**
+ * Internal split-horizon DNS A-record ledger. Mirrors `dns_registrations`
+ * but for the dns_internal capability (technitium/knot): the capability
+ * loader records every `dns_internal.registerRecord({type:'A'})` here so
+ * celilo has an offline, queryable record of what hostname → IP it asked
+ * the internal resolver to serve. Without this, the only source of truth
+ * is the resolver's own DB, requiring a live probe (ISS-0094 / ISS-0111).
+ *
+ * `celilo system doctor` reads this to assert service hostnames resolve to
+ * the firewall natIp (LAN-reachable) and not a zone-side container IP that
+ * a LAN device can't route to. Rows die with either module via FK cascade.
+ */
+export const dnsInternalRecords = sqliteTable(
+  'dns_internal_records',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    providerModuleId: text('provider_module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    consumerModuleId: text('consumer_module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    /** The registered hostname (e.g. "git-ssh.git.celilo.computer"). */
+    host: text('host').notNull(),
+    /** The A-record value celilo asked the resolver to serve. */
+    ip: text('ip').notNull(),
+    registeredAt: integer('registered_at', { mode: 'timestamp' })
+      .notNull()
+      .default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    providerHostUnique: uniqueIndex('dns_internal_records_provider_host_idx').on(
+      table.providerModuleId,
+      table.host,
+    ),
+  }),
+);
+
 /**
  * Backup storage providers - destinations for backup archives
  * Supports local filesystem and S3-compatible storage (AWS S3, MinIO, Backblaze B2, Wasabi)

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

@@ -37,7 +37,7 @@ export default defineCapabilityFunction({
   capability: 'firewall',
   handler: ({ config, secrets }) => ({
     exposeService: async (opts) => ({
-      externalIp: '71.36.99.96',
+      externalIp: '203.0.113.10',
       natIp: opts.internalIp,
     }),
     unexposeService: async () => {},
@@ -135,7 +135,7 @@ describe('Firewall Chain Building', () => {
       ports: [80],
       description: 'test',
     });
-    expect(exposed.externalIp).toBe('71.36.99.96');
+    expect(exposed.externalIp).toBe('203.0.113.10');
   });
 
   test('builds chain with two providers (iptables → greenwave)', async () => {
@@ -206,7 +206,7 @@ describe('Firewall Chain Building', () => {
     });
 
     // External IP came from greenwave (leaf)
-    expect(exposed.externalIp).toBe('71.36.99.96');
+    expect(exposed.externalIp).toBe('203.0.113.10');
     // NAT IP is iptables' NAT address
     expect(exposed.natIp).toBe('192.168.0.253');
     // iptables created local rules

package/src/hooks/capability-loader.ts

@@ -31,6 +31,7 @@ import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
 import { getModuleSystems } from '../services/deployed-systems';
+import { withDnsInternalLedger } from '../services/dns-internal-records';
 import { withDnsRegistrationLedger } from '../services/dns-registrations';
 import { loadHookConfigMap } from './load-hook-config';
 
@@ -200,19 +201,27 @@ export async function loadCapabilityFunctions(
     const providerConfig = await loadModuleConfig(capability.moduleId, db);
     const providerSecrets = await loadModuleSecrets(capability.moduleId, masterKey, db);
 
-    // dns_registrar interfaces get the registration-ledger wrapper:
-    // every successful registerHost is recorded in dns_registrations so
-    // the provider's refresh_registrations hook can re-assert it later
-    // (designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md B2). The loader is
-    // the one layer that knows both provider and consumer.
-    const withLedgerIfDnsRegistrar = (iface: unknown): unknown =>
-      capName === 'dns_registrar'
-        ? withDnsRegistrationLedger(iface as DnsRegistrarCapability, {
-            db,
-            providerModuleId: capability.moduleId,
-            consumerModuleId: consumingModuleId,
-          })
-        : iface;
+    // dns_registrar and dns_internal interfaces get a registration-ledger
+    // wrapper: every successful registerHost / registerRecord is recorded so
+    // celilo has an offline record of what it asked DNS to serve. The
+    // external ledger feeds the provider's refresh_registrations hook
+    // (DISPATCHER_DAEMON_AND_TIMER_EVENTS.md B2); the internal ledger feeds
+    // the doctor's natIp drift check (CELILO_DOCTOR_FLEET_DRIFT.md Phase 4).
+    // The loader is the one layer that knows both provider and consumer.
+    const ledgerCtx = {
+      db,
+      providerModuleId: capability.moduleId,
+      consumerModuleId: consumingModuleId,
+    };
+    const withLedger = (iface: unknown): unknown => {
+      if (capName === 'dns_registrar') {
+        return withDnsRegistrationLedger(iface as DnsRegistrarCapability, ledgerCtx);
+      }
+      if (capName === 'dns_internal') {
+        return withDnsInternalLedger(iface as DnsInternalCapability, ledgerCtx);
+      }
+      return iface;
+    };
 
     try {
       // Dynamically import the capability module. Try the default export
@@ -237,7 +246,7 @@ export async function loadCapabilityFunctions(
           systems: getModuleSystems(capability.moduleId, db),
           logger,
         });
-        result[capName] = withLedgerIfDnsRegistrar(capabilityInterface);
+        result[capName] = withLedger(capabilityInterface);
         debugLog(`${capName}: loaded via defineCapabilityFunction`);
         continue;
       }
@@ -253,7 +262,7 @@ export async function loadCapabilityFunctions(
       );
 
       if (capabilityInterface) {
-        result[capName] = withLedgerIfDnsRegistrar(
+        result[capName] = withLedger(
           wrapWithLogging(capabilityInterface as object, logger, capName),
         );
         debugLog(`${capName}: loaded via legacy factory`);

package/src/infrastructure/property-extractor.test.ts

@@ -78,6 +78,21 @@ describe('extractProxmoxProperties', () => {
     });
   });
 
+  test('omits vm_template when the service config has none (LXC services)', () => {
+    const properties = extractProxmoxProperties(100, '10.0.10.5', 'caddy', mockProxmoxConfig);
+    // Omitted, not empty — so a required-infrastructure `vm_template` var fails
+    // loudly rather than resolving to "".
+    expect('vm_template' in properties).toBe(false);
+  });
+
+  test('includes vm_template when the service config provides one (VM services)', () => {
+    const properties = extractProxmoxProperties(100, '10.0.10.5', 'builder', {
+      ...mockProxmoxConfig,
+      vm_template: 'ubuntu-2204-cloudinit',
+    });
+    expect(properties.vm_template).toBe('ubuntu-2204-cloudinit');
+  });
+
   test('converts vmid number to string', () => {
     const properties = extractProxmoxProperties(12345, '10.0.20.15', 'caddy', mockProxmoxConfig);
 

package/src/infrastructure/property-extractor.ts

@@ -47,6 +47,13 @@ export interface ProxmoxProviderConfig {
   default_target_node: string;
   lxc_template: string;
   storage: string;
+  /**
+   * Cloud-init VM template to clone for `requires.system.type: vm` modules — the
+   * VM analogue of `lxc_template`. Optional: only Proxmox services that host VM
+   * modules configure it. A VM module declares `vm_template` as a *required*
+   * infrastructure var, so a service missing it fails loudly at resolution.
+   */
+  vm_template?: string;
 }
 
 /**
@@ -72,6 +79,11 @@ export function extractProxmoxProperties(
     target_node: providerConfig.default_target_node,
     lxc_template: providerConfig.lxc_template,
     storage: providerConfig.storage,
+    // VM clone source — present only when the service configures it. VM modules
+    // declare `vm_template` as a required infrastructure var (resolution errors
+    // if absent); LXC modules never reference it. Omitted (not empty) when unset
+    // so the resolver's required/optional handling stays correct.
+    ...(providerConfig.vm_template ? { vm_template: providerConfig.vm_template } : {}),
   };
 }
 

package/src/manifest/schema.ts

@@ -311,6 +311,13 @@ export const SystemResourceSchema = z.object({
   memory: z.number().int().positive().optional().describe('Recommended memory in MB'),
   disk: z.number().int().positive().optional().describe('Recommended disk size in GB'),
   storage: z.string().optional().describe('Proxmox storage backend (defaults to system config)'),
+  type: z
+    .enum(['lxc', 'vm'])
+    .default('lxc')
+    .describe(
+      'Proxmox provisioning type: lxc (default) or vm (qemu, for Docker / kernel-module workloads). ' +
+        'Modules declare this explicitly; celilo never infers it. Moot for machine-pool / external infra.',
+    ),
   zone: z
     .enum(['internal', 'dmz', 'app', 'secure', 'external'])
     .describe('Required security zone for this module'),