@celilo/cli 0.4.0 → 0.5.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.4.0",
+  "version": "0.5.0-alpha.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/cli/commands/module-show.ts

@@ -6,7 +6,7 @@
 import { eq } from 'drizzle-orm';
 import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
-import type { ModuleManifest } from '../../manifest/schema';
+import { type ModuleManifest, getSingularSystemSpec } from '../../manifest/schema';
 import { buildResolutionContext } from '../../variables/context';
 import { getArg, validateRequiredArgs } from '../parser';
 import type { CommandResult } from '../types';
@@ -60,7 +60,7 @@ export async function handleModuleShowConfig(args: string[]): Promise<CommandRes
 
     for (const [key, value] of Object.entries(context.selfConfig)) {
       // Skip internal/derived keys that aren't useful for display
-      if (key.startsWith('requires.machine.')) continue;
+      if (key.startsWith('requires.system.')) continue;
 
       const line = `  ${key} = ${value}`;
 
@@ -152,7 +152,7 @@ export async function handleModuleShowZone(args: string[]): Promise<CommandResul
     const context = await buildResolutionContext(moduleId, db);
     const manifest = module.manifestData as ModuleManifest;
 
-    const zone = context.selfConfig.zone || manifest.requires?.machine?.zone;
+    const zone = context.selfConfig.zone || getSingularSystemSpec(manifest)?.zone;
 
     if (!zone) {
       return {

package/src/cli/commands/restore.ts

@@ -98,6 +98,11 @@ export async function handleRestore(
   if (result.systemDbApplied) lines.push('  • celilo.db swapped into place');
   if (result.masterKeyApplied) lines.push('  • master.key swapped into place');
   if (result.sshKeyApplied) lines.push('  • fleet SSH key restored to <data-dir>/.ssh/');
+  if (result.moduleSourcesApplied && result.moduleSourcesApplied > 0) {
+    lines.push(
+      `  • module source laid down for ${result.moduleSourcesApplied} module(s) (paths reconciled to this box)`,
+    );
+  }
   if (result.crossModuleApplied && result.crossModuleApplied.length > 0) {
     lines.push(
       `  • terraform state restored for ${result.crossModuleApplied.length} module(s): ${result.crossModuleApplied.join(', ')}`,

package/src/cli/commands/status.ts

@@ -9,7 +9,7 @@ import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { getDb } from '../../db/client';
 import { capabilities, moduleConfigs, modules, systemConfig, systemSecrets } from '../../db/schema';
-import type { ModuleManifest } from '../../manifest/schema';
+import { type ModuleManifest, getSingularSystemSpec } from '../../manifest/schema';
 import type { CommandResult } from '../types';
 
 /**
@@ -131,7 +131,7 @@ export async function handleStatus(): Promise<CommandResult> {
         lines.push(`    Status: ${statusInfo.status}`);
 
         // Type: VPS or Container
-        const zone = manifest.requires?.machine?.zone;
+        const zone = getSingularSystemSpec(manifest)?.zone;
         if (zone) {
           lines.push(`    Type: Container (${zone.toUpperCase()})`);
 

package/src/hooks/capability-loader.ts

@@ -368,13 +368,24 @@ export async function loadCapabilityFunctions(
         // otherwise race the async reconcile.
         onRoutesChanged: async () => {
           const reconcile = await emitWebRoutesChangedAndWait(consumingModuleId);
+          // Authoritative (ISS-0081): a route the provider (caddy) never
+          // reconciled is a deploy FAILURE, not a warning. These used to be
+          // logger.warn while register_route returned success anyway, so a
+          // consumer could report "ready" while caddy never learned the
+          // hostname — no site block, no cert, TLS internal_error for clients.
+          if (reconcile.noDispatcher) {
+            throw new Error(
+              `public_web route for ${consumingModuleId} was persisted but NOT delivered to the provider (caddy): no event dispatcher is running, so caddy never reconciled and the hostname has no site block or cert. Run this through \`celilo module deploy\` (which runs the dispatcher) rather than a bare hook.`,
+            );
+          }
           if (reconcile.timedOut) {
-            logger.warn(
-              `public_web reconcile for ${consumingModuleId} did not finish within the deadline (${reconcile.succeeded} ok, ${reconcile.failed} failed of ${reconcile.events} change event(s)); the route is persisted and the provider will reconcile on its next run`,
+            throw new Error(
+              `public_web reconcile for ${consumingModuleId} did not finish within the deadline (${reconcile.succeeded} ok, ${reconcile.failed} failed of ${reconcile.events} change event(s)) — caddy did not confirm the route is live.`,
             );
-          } else if (reconcile.failed > 0) {
-            logger.warn(
-              `public_web reconcile for ${consumingModuleId}: ${reconcile.failed} delivery(ies) failed; the route is persisted but the provider config may be stale`,
+          }
+          if (reconcile.failed > 0) {
+            throw new Error(
+              `public_web reconcile for ${consumingModuleId}: ${reconcile.failed} delivery(ies) failed — caddy could not apply the route, so the hostname is not served.`,
             );
           }
         },

package/src/manifest/schema.ts

@@ -306,7 +306,7 @@ export const UpstreamPublishHookSchema = z.object({
  * Machine resource recommendations
  * Module declares recommended machine resources (CPU, memory, disk, storage)
  */
-export const MachineResourceSchema = z.object({
+export const SystemResourceSchema = z.object({
   cpu: z.number().int().positive().optional().describe('Recommended CPU cores'),
   memory: z.number().int().positive().optional().describe('Recommended memory in MB'),
   disk: z.number().int().positive().optional().describe('Recommended disk size in GB'),
@@ -328,7 +328,7 @@ export const SystemDeclarationSchema = z.object({
     .string()
     .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'system name must be kebab-case')
     .describe('Stable handle for this system; used in $infra:<name> and as the per-system key'),
-  resources: MachineResourceSchema,
+  resources: SystemResourceSchema,
 });
 
 /**
@@ -439,17 +439,17 @@ export const ModuleManifestSchema = z
         capabilities: z.array(CapabilityRequirementSchema).default([]),
         /**
          * The 0..N systems this module deploys (v2/MODULE_SYSTEMS_ADDRESSING.md).
-         * Preferred over the legacy singular `machine`. A module declaring
+         * Preferred over the singular `system`. A module declaring
          * `systems` gets one host per entry, each addressable as `$infra:<name>`.
          */
         systems: z.array(SystemDeclarationSchema).optional(),
         /**
-         * Legacy singular form — sugar for a single unnamed system. Normalized
-         * to one `systems` entry (name `main`) by `getDeclaredSystems`. Optional
-         * because config-only providers (e.g. namecheap) deploy no infrastructure.
-         * New modules should prefer `systems`.
+         * Singular form — sugar for a single unnamed system. Normalized to one
+         * `systems` entry (name `main`) by `getDeclaredSystems`. Optional because
+         * config-only providers (e.g. namecheap) deploy no infrastructure.
+         * Modules declaring more than one host should use `systems`.
          */
-        machine: MachineResourceSchema.optional(),
+        system: SystemResourceSchema.optional(),
       })
       .default({ capabilities: [] }),
 
@@ -730,25 +730,36 @@ export type LifecycleHook = z.infer<typeof LifecycleHookSchema>;
 export type VariableSource = z.infer<typeof VariableSourceSchema>;
 export type VariableType = z.infer<typeof VariableTypeSchema>;
 export type AnsibleCollection = z.infer<typeof AnsibleCollectionSchema>;
-export type MachineResource = z.infer<typeof MachineResourceSchema>;
+export type SystemResource = z.infer<typeof SystemResourceSchema>;
 export type SystemDeclaration = z.infer<typeof SystemDeclarationSchema>;
 export type BaseModuleAspect = NonNullable<ModuleManifest['base_module_aspect']>;
 export type BaseModuleAspectTrigger = BaseModuleAspect['triggers'][number];
 
 /**
  * Normalize a manifest's declared systems (v2/MODULE_SYSTEMS_ADDRESSING.md).
- * Returns `requires.systems` if present; else the legacy singular
- * `requires.machine` as one entry named `main`; else `[]` (config-only module
- * like namecheap). This is the single place the machine→systems sugar lives, so
- * the rest of the codebase only ever reasons about the 0..N collection.
+ * Returns `requires.systems` if present; else the singular `requires.system`
+ * as one entry named `main`; else `[]` (config-only module like namecheap).
+ * This is the single place the system→systems sugar lives, so the rest of the
+ * codebase only ever reasons about the 0..N collection.
  */
 export function getDeclaredSystems(manifest: ModuleManifest): SystemDeclaration[] {
   const requires = manifest.requires;
   if (requires?.systems && requires.systems.length > 0) {
     return requires.systems;
   }
-  if (requires?.machine) {
-    return [{ name: 'main', resources: requires.machine }];
+  const singular = getSingularSystemSpec(manifest);
+  if (singular) {
+    return [{ name: 'main', resources: singular }];
   }
   return [];
 }
+
+/**
+ * The singular system resource spec a module declares: `requires.system`. The
+ * one place callers read the single-system spec (zone, sizing, "does this module
+ * need infra?"). Returns undefined for config-only modules or those declaring the
+ * plural `requires.systems`.
+ */
+export function getSingularSystemSpec(manifest: ModuleManifest): SystemResource | undefined {
+  return manifest.requires?.system;
+}

package/src/manifest/template-validator.test.ts

@@ -14,7 +14,7 @@ function createTestManifest(overrides?: Partial<ModuleManifest>): ModuleManifest
     description: 'Test module',
     requires: {
       capabilities: [],
-      machine: {
+      system: {
         cpu: 2,
         memory: 2048,
         disk: 20,
@@ -54,16 +54,16 @@ function createTestManifest(overrides?: Partial<ModuleManifest>): ModuleManifest
 
 describe('template-validator', () => {
   describe('validateModuleTemplates - valid references', () => {
-    test('validates nested manifest paths (requires.machine.*)', async () => {
+    test('validates nested manifest paths (requires.system.*)', async () => {
       const manifest = createTestManifest();
 
-      // Test that requires.machine.cpu is valid
-      const machine = manifest.requires.machine;
+      // Test that requires.system.cpu is valid
+      const system = manifest.requires.system;
 
-      expect(machine?.cpu).toBe(2);
-      expect(machine?.memory).toBe(2048);
-      expect(machine?.disk).toBe(20);
-      expect(machine?.storage).toBe('local-lvm');
+      expect(system?.cpu).toBe(2);
+      expect(system?.memory).toBe(2048);
+      expect(system?.disk).toBe(20);
+      expect(system?.storage).toBe('local-lvm');
     });
 
     test('validates capability references', async () => {

package/src/manifest/template-validator.ts

@@ -26,7 +26,7 @@ export interface TemplateValidationResult {
  * Returns undefined if path doesn't exist
  *
  * @param obj - Object to traverse
- * @param path - Dot-separated path (e.g., 'requires.machine.cpu')
+ * @param path - Dot-separated path (e.g., 'requires.system.cpu')
  * @returns Value if found, undefined otherwise
  */
 function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
@@ -50,7 +50,7 @@ function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
  * Check if a path exists in the manifest
  *
  * @param manifest - Module manifest
- * @param path - Dot-separated path (e.g., 'requires.machine.cpu')
+ * @param path - Dot-separated path (e.g., 'requires.system.cpu')
  * @returns True if path exists in manifest
  */
 function pathExistsInManifest(manifest: ModuleManifest, path: string): boolean {
@@ -126,7 +126,7 @@ function validateSelfVariable(
     return `Self variable '${path}' not found in module configuration`;
   }
 
-  // Check if it's a nested path (e.g., $self:requires.machine.cpu)
+  // Check if it's a nested path (e.g., $self:requires.system.cpu)
   if (pathExistsInManifest(manifest, path)) {
     return null; // Valid
   }

package/src/manifest/validate.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from 'bun:test';
+import { getSingularSystemSpec } from './schema';
 import {
   validateCapabilityNames,
   validateCapabilityRequirements,
@@ -42,7 +43,7 @@ description: HomeKit bridge for smart home devices
 
 requires:
   capabilities: []
-  machine:
+  system:
     cpu: 1
     memory: 1024
     disk: 20
@@ -71,8 +72,8 @@ variables:
     if (result.success) {
       expect(result.data.id).toBe('homebridge');
       expect(result.data.variables.owns).toHaveLength(2);
-      expect(result.data.requires.machine?.cpu).toBe(1);
-      expect(result.data.requires.machine?.zone).toBe('app');
+      expect(result.data.requires.system?.cpu).toBe(1);
+      expect(result.data.requires.system?.zone).toBe('app');
     }
   });
 
@@ -442,7 +443,7 @@ build:
     }
   });
 
-  test('should validate manifest with VM resource recommendations under requires.machine', () => {
+  test('should validate manifest with VM resources under requires.system (canonical name)', () => {
     const yaml = `
 ${CONTRACT_LINE}
 id: grafana
@@ -451,7 +452,7 @@ version: 1.0.0
 
 requires:
   capabilities: []
-  machine:
+  system:
     cpu: 2
     memory: 2048
     disk: 20
@@ -463,11 +464,11 @@ requires:
 
     expect(result.success).toBe(true);
     if (result.success) {
-      expect(result.data.requires.machine?.cpu).toBe(2);
-      expect(result.data.requires.machine?.memory).toBe(2048);
-      expect(result.data.requires.machine?.disk).toBe(20);
-      expect(result.data.requires.machine?.storage).toBe('local-lvm');
-      expect(result.data.requires.machine?.zone).toBe('app');
+      expect(result.data.requires.system?.cpu).toBe(2);
+      expect(result.data.requires.system?.memory).toBe(2048);
+      expect(result.data.requires.system?.zone).toBe('app');
+      // getSingularSystemSpec resolves the canonical field…
+      expect(getSingularSystemSpec(result.data)?.cpu).toBe(2);
     }
   });
 
@@ -480,7 +481,7 @@ version: 1.0.0
 
 requires:
   capabilities: []
-  machine:
+  system:
     zone: dmz
 `;
 
@@ -488,9 +489,9 @@ requires:
 
     expect(result.success).toBe(true);
     if (result.success) {
-      expect(result.data.requires.machine?.zone).toBe('dmz');
-      expect(result.data.requires.machine?.cpu).toBeUndefined();
-      expect(result.data.requires.machine?.memory).toBeUndefined();
+      expect(result.data.requires.system?.zone).toBe('dmz');
+      expect(result.data.requires.system?.cpu).toBeUndefined();
+      expect(result.data.requires.system?.memory).toBeUndefined();
     }
   });
 
@@ -503,7 +504,7 @@ version: 1.0.0
 
 requires:
   capabilities: []
-  machine:
+  system:
     cpu: -2
     zone: app
 `;
@@ -521,7 +522,7 @@ version: 1.0.0
 
 requires:
   capabilities: []
-  machine:
+  system:
     zone: invalid
 `;
 
@@ -538,7 +539,7 @@ version: 1.0.0
 
 requires:
   capabilities: []
-  machine:
+  system:
     cpu: 2.5
     zone: app
 `;

package/src/manifest/validate.ts

@@ -3,7 +3,7 @@ import { parse as parseYaml } from 'yaml';
 import type { ZodError } from 'zod';
 import { validateModuleZoneRequirements } from '../services/zone-policy';
 import { resolveContract, supportedContractVersions } from './contracts';
-import { ModuleManifestSchema } from './schema';
+import { ModuleManifestSchema, getSingularSystemSpec } from './schema';
 import type { ModuleManifest } from './schema';
 
 /**
@@ -304,16 +304,16 @@ export function validateVariableSources(manifest: ModuleManifest): ValidationErr
 export function validateZoneRequirements(manifest: ModuleManifest): ValidationError | null {
   const errors: Array<{ path: string; message: string }> = [];
 
-  // Check if module has infrastructure spec (requires.machine)
-  const hasInfrastructureSpec = manifest.requires?.machine;
+  // Check if module has infrastructure spec (requires.system)
+  const hasInfrastructureSpec = getSingularSystemSpec(manifest);
 
   // If module requires infrastructure, zone field is mandatory
   if (hasInfrastructureSpec) {
-    const zone = manifest.requires?.machine?.zone;
+    const zone = hasInfrastructureSpec.zone;
 
     if (!zone) {
       errors.push({
-        path: 'requires.machine.zone',
+        path: 'requires.system.zone',
         message: 'Zone field is required for modules with infrastructure requirements',
       });
       // Can't validate zone requirements without a zone
@@ -327,7 +327,7 @@ export function validateZoneRequirements(manifest: ModuleManifest): ValidationEr
 
       if (!zoneValidation.valid && zoneValidation.error) {
         errors.push({
-          path: 'requires.machine.zone',
+          path: 'requires.system.zone',
           message: zoneValidation.error,
         });
       }

package/src/module/import.ts

@@ -10,7 +10,7 @@ import { getModuleStoragePath } from '../config/paths';
 import { type DbClient, getDb } from '../db/client';
 import { capabilities, moduleIntegrity, modules } from '../db/schema';
 import type { NewModule, NewModuleIntegrity } from '../db/schema';
-import type { ModuleManifest } from '../manifest/schema';
+import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import {
   validateCapabilityNames,
   validateDeriveFromSources,
@@ -348,7 +348,7 @@ export async function validateWellKnownCapabilities(
     }
 
     // Check 2: Zone enforcement - module must be in the correct zone
-    const moduleZone = manifest.requires?.machine?.zone;
+    const moduleZone = getSingularSystemSpec(manifest)?.zone;
 
     if (wellKnown.zone_enforced && moduleZone) {
       if (moduleZone !== wellKnown.required_zone) {
@@ -402,11 +402,16 @@ async function installScriptDependencies(
   targetPath: string,
   manifest: ModuleManifest,
 ): Promise<void> {
-  // Determine where scripts live by looking at hook declarations.
-  // All hooks use paths like `./scripts/setup-admin.ts`, so the
-  // scripts directory is the common parent.
-  if (!manifest.hooks || Object.keys(manifest.hooks).length === 0) {
-    return; // No hooks → no scripts → nothing to install
+  // A module's scripts/ holds hook scripts AND/OR capability-provider
+  // implementations (e.g. dns_registrar's register-host.ts, referenced via
+  // provides.capabilities, not hooks). BOTH import @celilo/capabilities and
+  // need deps. A capability-only provider (hooks: {}) still has scripts to
+  // resolve — keying solely off hooks left its node_modules un-vendored, so
+  // the capability-loader's import() failed with ENOENT @celilo/capabilities.
+  const hasHooks = Boolean(manifest.hooks && Object.keys(manifest.hooks).length > 0);
+  const hasCapabilities = (manifest.provides?.capabilities?.length ?? 0) > 0;
+  if (!hasHooks && !hasCapabilities) {
+    return; // No hook or capability scripts → nothing to install
   }
 
   const scriptsDir = join(targetPath, 'scripts');

package/src/services/celilo-events.test.ts

@@ -217,7 +217,13 @@ describe('celilo lifecycle events', () => {
     it('returns immediately when the deploy changed no routes', async () => {
       const since = routesChangedHighWater();
       const result = await waitForRouteReconcile(since, { timeoutMs: 1000 });
-      expect(result).toEqual({ events: 0, succeeded: 0, failed: 0, timedOut: false });
+      expect(result).toEqual({
+        events: 0,
+        succeeded: 0,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: false,
+      });
     });
 
     it('skips the wait (no time-out) when no dispatcher is running', async () => {
@@ -226,7 +232,13 @@ describe('celilo lifecycle events', () => {
       emitWebRoutesChanged('celilo-website');
       // No heartbeat stamped → health() is no_dispatcher.
       const result = await waitForRouteReconcile(since, { timeoutMs: 5000, pollMs: 50 });
-      expect(result).toEqual({ events: 1, succeeded: 0, failed: 0, timedOut: false });
+      expect(result).toEqual({
+        events: 1,
+        succeeded: 0,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: true,
+      });
     });
 
     it('settles immediately when no provider subscribes (zero deliveries)', async () => {
@@ -234,7 +246,13 @@ describe('celilo lifecycle events', () => {
       const since = routesChangedHighWater();
       emitWebRoutesChanged('celilo-website');
       const result = await waitForRouteReconcile(since, { timeoutMs: 1000, pollMs: 50 });
-      expect(result).toEqual({ events: 1, succeeded: 0, failed: 0, timedOut: false });
+      expect(result).toEqual({
+        events: 1,
+        succeeded: 0,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: false,
+      });
     });
 
     it('times out while the provider delivery is still pending', async () => {
@@ -255,7 +273,13 @@ describe('celilo lifecycle events', () => {
       settleDelivery('succeed');
 
       const result = await waitForRouteReconcile(since, { timeoutMs: 1000, pollMs: 50 });
-      expect(result).toEqual({ events: 1, succeeded: 1, failed: 0, timedOut: false });
+      expect(result).toEqual({
+        events: 1,
+        succeeded: 1,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: false,
+      });
     });
 
     it('reports a failed delivery without timing out', async () => {
@@ -284,7 +308,13 @@ describe('celilo lifecycle events', () => {
       settleDelivery('succeed');
 
       const result = await pending;
-      expect(result).toEqual({ events: 1, succeeded: 1, failed: 0, timedOut: false });
+      expect(result).toEqual({
+        events: 1,
+        succeeded: 1,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: false,
+      });
     });
   });
 });

package/src/services/celilo-events.ts

@@ -222,6 +222,13 @@ export interface RouteReconcileWaitResult {
   succeeded: number;
   failed: number;
   timedOut: boolean;
+  /**
+   * True when no event dispatcher was running, so the `routes_changed` event
+   * was persisted but never DELIVERED to the provider (caddy). The route is
+   * therefore NOT live. Authoritative callers (ISS-0081) must treat this as a
+   * failure, not a benign "0 deliveries" success.
+   */
+  noDispatcher: boolean;
 }
 
 /**
@@ -283,14 +290,20 @@ export async function waitForRouteReconcile(
       .filter((e) => e.id > sinceEventId);
 
     if (events.length === 0) {
-      return { events: 0, succeeded: 0, failed: 0, timedOut: false };
+      return { events: 0, succeeded: 0, failed: 0, timedOut: false, noDispatcher: false };
     }
 
     if (b.health().status === 'no_dispatcher') {
       console.warn(
         `[celilo] route-reconcile: no dispatcher running — not waiting; ${events.length} change event(s) persisted, the provider will reconcile on its next run`,
       );
-      return { events: events.length, succeeded: 0, failed: 0, timedOut: false };
+      return {
+        events: events.length,
+        succeeded: 0,
+        failed: 0,
+        timedOut: false,
+        noDispatcher: true,
+      };
     }
 
     while (true) {
@@ -306,6 +319,7 @@ export async function waitForRouteReconcile(
           succeeded: settled('succeeded'),
           failed: settled('failed') + settled('abandoned'),
           timedOut: pending > 0,
+          noDispatcher: false,
         };
       }
 
@@ -314,7 +328,7 @@ export async function waitForRouteReconcile(
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.warn(`[celilo] route-reconcile wait errored: ${msg}`);
-    return { events: 0, succeeded: 0, failed: 0, timedOut: false };
+    return { events: 0, succeeded: 0, failed: 0, timedOut: false, noDispatcher: false };
   } finally {
     bus?.close();
   }

package/src/services/celilo-mgmt-hooks.test.ts

@@ -147,11 +147,41 @@ describe('celilo-mgmt on_backup', () => {
     ).toBe(true);
     expect(existsSync(join(backupDir, 'cross_module_state', 'index.json'))).toBe(true);
 
-    expect(result.schema_version).toBe('1.0');
+    expect(result.schema_version).toBe('1.1');
     expect(result.artifact_count).toBeGreaterThan(0);
     expect(result.size_bytes).toBeGreaterThan(0);
   });
 
+  it('captures LEAN module source (excludes generated/, node_modules/, large build artifacts)', async () => {
+    // stateDir = dirname(db_path) = dir; on_backup reads dir/modules/<id>.
+    const modSrc = join(dir, 'modules', 'caddy');
+    mkdirSync(join(modSrc, 'scripts', 'node_modules', '@celilo'), { recursive: true });
+    mkdirSync(join(modSrc, 'generated', 'terraform'), { recursive: true });
+    mkdirSync(join(modSrc, 'ansible', 'files'), { recursive: true });
+    writeFileSync(join(modSrc, 'manifest.yml'), 'id: caddy');
+    writeFileSync(join(modSrc, 'scripts', 'hook.ts'), '// hook');
+    writeFileSync(join(modSrc, 'generated', 'terraform', 'main.tf'), 'resource {}');
+    writeFileSync(join(modSrc, 'scripts', 'node_modules', '@celilo', 'dep.js'), '// vendored');
+    // A >2MB "compiled binary" sitting in source — must be skipped by size.
+    writeFileSync(join(modSrc, 'ansible', 'files', 'server-bin'), Buffer.alloc(3 * 1024 * 1024));
+
+    const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
+    await hook(buildContext({ backup_dir: backupDir, cross_module_root: crossModuleRoot }));
+
+    // Source files captured...
+    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'manifest.yml'))).toBe(true);
+    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'scripts', 'hook.ts'))).toBe(true);
+    // ...but build/vendored content excluded (keeps the backup small enough to
+    // not OOM the in-memory tar+encrypt — turnip's full dirs were ~1.6GB).
+    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'generated'))).toBe(false);
+    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'scripts', 'node_modules'))).toBe(
+      false,
+    );
+    expect(
+      existsSync(join(backupDir, 'module_src', 'caddy', 'ansible', 'files', 'server-bin')),
+    ).toBe(false);
+  });
+
   it('machine-pool.json is valid JSON (array)', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
     await hook(buildContext({ backup_dir: backupDir, cross_module_root: crossModuleRoot }));
@@ -168,7 +198,7 @@ describe('celilo-mgmt on_backup', () => {
 
     expect(existsSync(join(backupDir, 'celilo.db'))).toBe(true);
     expect(existsSync(join(backupDir, 'cross_module_state'))).toBe(false);
-    expect(result.schema_version).toBe('1.0');
+    expect(result.schema_version).toBe('1.1');
   });
 
   it('proceeds (with a warning) when master.key is missing on disk', async () => {

package/src/services/deploy-preflight.ts

@@ -26,7 +26,7 @@ import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { getDb } from '../db/client';
 import { capabilities, moduleConfigs, modules, secrets } from '../db/schema';
-import type { ModuleManifest } from '../manifest/schema';
+import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import { buildResolutionContext } from '../variables/context';
 import { E2E_CONFLICT_FIX, runningE2eContainers } from './e2e-guard';
 
@@ -241,8 +241,9 @@ export async function runPreflight(
   }
 
   // 5. Infrastructure availability (for modules that need it)
-  if (manifest.requires?.machine) {
-    const zone = manifest.requires.machine.zone;
+  const systemSpec = getSingularSystemSpec(manifest);
+  if (systemSpec) {
+    const zone = systemSpec.zone;
     if (zone) {
       // Simplified check: is there a machine or service for the module's zone?
       // The full infrastructure selector (selectInfrastructure) needs a Module

package/src/services/deployed-systems.test.ts

@@ -60,7 +60,7 @@ function seedProxmoxModule(
       id: opts.id,
       name: opts.id,
       version: '1.0.0',
-      manifestData: { requires: { machine: { zone: opts.zone } } },
+      manifestData: { requires: { system: { zone: opts.zone } } },
       sourcePath: `/tmp/${opts.id}`,
       state: 'VERIFIED',
     })
@@ -180,7 +180,7 @@ describe('backfillModuleSystems', () => {
         id: 'technitium',
         name: 'technitium',
         version: '1.0.0',
-        manifestData: { requires: { machine: { zone: 'internal' } } },
+        manifestData: { requires: { system: { zone: 'internal' } } },
         sourcePath: '/tmp/technitium',
         state: 'VERIFIED',
       })