@celilo/cli 0.4.1 → 0.5.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.4.1",
+  "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/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) {

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

@@ -152,14 +152,18 @@ describe('celilo-mgmt on_backup', () => {
     expect(result.size_bytes).toBeGreaterThan(0);
   });
 
-  it('captures module SOURCE (excluding generated/) into module_src/', async () => {
+  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'), { recursive: true });
+    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 }));
@@ -167,8 +171,15 @@ describe('celilo-mgmt on_backup', () => {
     // 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 generated/ excluded (TF state travels via cross_module_state).
+    // ...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 () => {

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',
       })

package/src/services/deployed-systems.ts

@@ -150,7 +150,7 @@ function asZone(value: string | undefined): NetworkZone | null {
  * single sink the old scattered `target_ip` writes collapse into.
  *
  * Transition: every current module declares exactly one system (via
- * `requires.machine`, normalized to name `main`, or one `requires.systems`
+ * `requires.system`, normalized to name `main`, or one `requires.systems`
  * entry), so this records that single host from `hostname` config + the
  * resolved IP. Returns the systems it recorded ([] for an API-only module with
  * no host — e.g. namecheap). See v2/MODULE_SYSTEMS_ADDRESSING.md.

package/src/services/infrastructure-selector.test.ts

@@ -61,7 +61,7 @@ describe('infrastructure-selector', () => {
         version: '1.0.0',
         manifestData: {
           requires: {
-            machine: {
+            system: {
               cpu: 2,
               memory: 2048,
               disk: 20,
@@ -119,7 +119,7 @@ describe('infrastructure-selector', () => {
         version: '1.0.0',
         manifestData: {
           requires: {
-            machine: {
+            system: {
               cpu: 2,
               memory: 2048,
               disk: 20,
@@ -162,7 +162,7 @@ describe('infrastructure-selector', () => {
         version: '1.0.0',
         manifestData: {
           requires: {
-            machine: {
+            system: {
               cpu: 2,
               memory: 2048,
               disk: 20,
@@ -197,7 +197,7 @@ describe('infrastructure-selector', () => {
       const module = (await db.select().from(modules).limit(1))[0] as Module;
 
       await expect(selectInfrastructure(module)).rejects.toThrow(InfrastructureError);
-      await expect(selectInfrastructure(module)).rejects.toThrow(/missing requires.machine/);
+      await expect(selectInfrastructure(module)).rejects.toThrow(/missing requires.system/);
     });
 
     it('throws error when module manifest missing zone', async () => {
@@ -210,7 +210,7 @@ describe('infrastructure-selector', () => {
         version: '1.0.0',
         manifestData: {
           requires: {
-            machine: {
+            system: {
               cpu: 2,
               memory: 2048,
               disk: 20,
@@ -224,20 +224,20 @@ describe('infrastructure-selector', () => {
       const module = (await db.select().from(modules).limit(1))[0] as Module;
 
       await expect(selectInfrastructure(module)).rejects.toThrow(InfrastructureError);
-      await expect(selectInfrastructure(module)).rejects.toThrow(/missing requires.machine.zone/);
+      await expect(selectInfrastructure(module)).rejects.toThrow(/missing requires.system.zone/);
     });
 
-    it('supports requires.machine format', async () => {
+    it('supports requires.system format', async () => {
       const db = createDbClient({ path: testDbPath });
 
-      // Create test module with requires.machine format
+      // Create test module with requires.system format
       await db.insert(modules).values({
         id: 'test-module',
         name: 'Test Module',
         version: '1.0.0',
         manifestData: {
           requires: {
-            machine: {
+            system: {
               cpu: 2,
               memory: 2048,
               disk: 20,
@@ -284,7 +284,7 @@ describe('infrastructure-selector', () => {
         version: '1.0.0',
         manifestData: {
           requires: {
-            machine: {
+            system: {
               cpu: 2,
               memory: 2048,
               disk: 20,
@@ -326,7 +326,7 @@ describe('infrastructure-selector', () => {
         version: '1.0.0',
         manifestData: {
           requires: {
-            machine: {
+            system: {
               cpu: 2,
               memory: 2048,
               disk: 20,
@@ -366,7 +366,7 @@ describe('infrastructure-selector', () => {
         version: '1.0.0',
         manifestData: {
           requires: {
-            machine: {
+            system: {
               cpu: 2,
               memory: 2048,
               disk: 20,
@@ -406,7 +406,7 @@ describe('infrastructure-selector', () => {
         version: '1.0.0',
         manifestData: {
           requires: {
-            machine: {
+            system: {
               cpu: 2,
               memory: 2048,
               disk: 20,
@@ -449,7 +449,7 @@ describe('infrastructure-selector', () => {
         version: '1.0.0',
         manifestData: {
           requires: {
-            machine: {
+            system: {
               cpu: 4,
               memory: 4096,
               disk: 128,

package/src/services/infrastructure-selector.ts

@@ -1,5 +1,5 @@
 import type { Module } from '../db/schema';
-import type { ModuleManifest } from '../manifest/schema';
+import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import type {
   InfrastructureSelection,
   Machine,
@@ -25,27 +25,26 @@ export class InfrastructureError extends Error {
 function getResourceRequirements(module: Module): ResourceRequirements {
   const manifest = module.manifestData as ModuleManifest;
 
-  // Check for requires.machine
-  const machine = manifest.requires?.machine;
+  const system = getSingularSystemSpec(manifest);
 
-  if (!machine) {
+  if (!system) {
     throw new InfrastructureError(
-      `Module ${module.id} manifest missing requires.machine configuration`,
+      `Module ${module.id} manifest missing requires.system configuration`,
     );
   }
 
-  if (!machine.zone) {
+  if (!system.zone) {
     throw new InfrastructureError(
-      `Module ${module.id} manifest missing requires.machine.zone field`,
+      `Module ${module.id} manifest missing requires.system.zone field`,
     );
   }
 
   return {
-    cpu: machine.cpu ?? 1,
-    memory: machine.memory ?? 1024,
-    disk: machine.disk ?? 10,
-    storage: machine.storage,
-    zone: machine.zone,
+    cpu: system.cpu ?? 1,
+    memory: system.memory ?? 1024,
+    disk: system.disk ?? 10,
+    storage: system.storage,
+    zone: system.zone,
   };
 }
 

package/src/services/module-deploy.ts

@@ -16,7 +16,7 @@ import { loadCapabilityFunctions } from '../hooks/capability-loader';
 import { invokeHook } from '../hooks/executor';
 import { createGaugeLogger } from '../hooks/logger';
 import type { HookDefinition, HookLogger, HookResult } from '../hooks/types';
-import type { ModuleManifest } from '../manifest/schema';
+import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { buildResolutionContext } from '../variables/context';
@@ -416,7 +416,7 @@ async function deployModuleImpl(
       );
       if (machineDerivable.length > 0) {
         const isFirewall = manifest.provides?.capabilities?.some((cap) => cap.name === 'firewall');
-        const moduleZone = manifest.requires?.machine?.zone;
+        const moduleZone = getSingularSystemSpec(manifest)?.zone;
         const matchedMachine = await findMachineForModule(
           moduleId,
           moduleZone,
@@ -473,7 +473,7 @@ async function deployModuleImpl(
       if (regularConfig.length > 0) {
         // Look up machine for $machine: derivation (earmarked or best match from pool)
         const isFirewall = manifest.provides?.capabilities?.some((cap) => cap.name === 'firewall');
-        const moduleZone = manifest.requires?.machine?.zone;
+        const moduleZone = getSingularSystemSpec(manifest)?.zone;
         const matchedMachine = await findMachineForModule(
           moduleId,
           moduleZone,
@@ -668,7 +668,7 @@ async function deployModuleImpl(
     }
 
     // Config-only modules (no infrastructure requirements) don't need terraform/ansible
-    const isConfigOnly = !manifest.requires?.machine;
+    const isConfigOnly = !getSingularSystemSpec(manifest);
     if (isConfigOnly) {
       log.success('Config-only module — no infrastructure deployment needed');
 

package/src/services/restore-from-file.ts

@@ -208,10 +208,21 @@ export async function restoreFromArtifactFile(
       hookInputs.cross_module_write_root = crossModuleWriteRoot;
     }
 
-    // 5. Invoke the hook.
+    // 5. Invoke the hook. Resolve the module path from getModuleStoragePath()
+    //    rather than the stored mod.sourcePath (ISS-0052): on a box whose DB was
+    //    produced by a prior restore from ANOTHER box, source_path is that box's
+    //    absolute path (e.g. a macOS /Users/... path on a Linux box), and the
+    //    hook executor's screenshot-dir mkdir then EACCES'es on it. By
+    //    construction (import.ts) the code always lives at
+    //    ${getModuleStoragePath()}/<id>, so resolve there. Falls back to the
+    //    stored path only if the canonical dir is absent (e.g. a custom layout).
+    const canonicalModulePath = join(getModuleStoragePath(), mod.id);
+    const onRestoreModulePath = existsSync(canonicalModulePath)
+      ? canonicalModulePath
+      : mod.sourcePath;
     const logger = createConsoleLogger(mod.id, 'on_restore');
     const hookResult = await invokeHook(
-      mod.sourcePath,
+      onRestoreModulePath,
       'on_restore',
       manifest.celilo_contract,
       hookDef,

package/src/services/terraform-safety.ts

@@ -57,8 +57,14 @@ export function validateTerraformPlanSafety(planOutput: string): PlanSafetyResul
       };
     }
 
-    // Rule 2: Only CREATE operations allowed
-    if (action.action !== 'create') {
+    // Rule 2: CREATE and in-place UPDATE are allowed; REPLACE and DELETE are
+    // refused. (ISS-0055) An in-place update — the lifecycle-ignored
+    // computed-attribute redeploy, or a deliberate memory/cpu resize — is safe
+    // and must go through, so the management plane can update containers in
+    // place. Only destroy+recreate (replace) and delete are data-loss
+    // operations we hard-block. The parser matches `replace` before `update`,
+    // so a "must be replaced" plan is still classified as replace and refused.
+    if (action.action !== 'create' && action.action !== 'update') {
       return {
         safe: false,
         error: formatUnsafeOperationError(action),

package/src/services/zone-policy.ts

@@ -101,12 +101,12 @@ export function validateModuleZoneRequirements(
  * Policy function - determines if zone validation applies
  *
  * Zone is required if:
- * - Module specifies requires.machine (infrastructure provisioning)
+ * - Module specifies requires.system (infrastructure provisioning)
  *
  * Zone is optional if:
  * - Module has no infrastructure requirements (e.g., VPS-based modules)
  *
- * @param hasInfrastructureSpec - Whether module has requires.machine
+ * @param hasInfrastructureSpec - Whether module has requires.system
  * @returns True if zone field is required
  */
 export function isZoneRequired(hasInfrastructureSpec: boolean): boolean {

package/src/templates/generator.test.ts

@@ -495,7 +495,7 @@ resource "proxmox_lxc" "container" {
         provides: { capabilities: [] },
         requires: {
           capabilities: [],
-          machine: {
+          system: {
             cpu: 1,
             memory: 1024,
             disk: 10,
@@ -650,7 +650,9 @@ resource "proxmox_lxc" "container" {
       const out = injectProxmoxLxcDns(LXC, true);
       expect(out).toContain('  nameserver = "$self:lxc_nameserver"');
       expect(out).toContain('  lifecycle {');
-      expect(out).toContain('    ignore_changes = [nameserver]');
+      expect(out).toContain(
+        '    ignore_changes = [nameserver, network[0].hwaddr, rootfs[0].volume]',
+      );
       // Injected immediately after the opening line, before author attributes.
       const lines = out.split('\n');
       expect(lines[0]).toBe('resource "proxmox_lxc" "caddy" {');
@@ -665,7 +667,9 @@ resource "proxmox_lxc" "container" {
       const out = injectProxmoxLxcDns(LXC, false);
       expect(out).not.toContain('nameserver = "$self:lxc_nameserver"');
       expect(out).toContain('  lifecycle {');
-      expect(out).toContain('    ignore_changes = [nameserver]');
+      expect(out).toContain(
+        '    ignore_changes = [nameserver, network[0].hwaddr, rootfs[0].volume]',
+      );
     });
 
     test('is idempotent — already-injected content is returned unchanged', () => {
@@ -687,8 +691,8 @@ resource "proxmox_lxc" "container" {
       const out = injectProxmoxLxcDns(stale, true);
       // Exactly one nameserver attribute survives.
       expect(out.match(/nameserver\s*=/g)?.length).toBe(1);
-      // The lifecycle guard is still added.
-      expect(out).toContain('ignore_changes = [nameserver]');
+      // The lifecycle guard is still added (ISS-0055 extended the ignore list).
+      expect(out).toContain('ignore_changes = [nameserver,');
     });
 
     test('leaves non-proxmox_lxc resources untouched', () => {
@@ -699,7 +703,7 @@ resource "proxmox_lxc" "container" {
     test('injects into every proxmox_lxc block in a multi-resource file', () => {
       const two = `${LXC}\n\n${LXC.replace('"caddy"', '"forgejo"')}`;
       const out = injectProxmoxLxcDns(two, true);
-      expect(out.match(/ignore_changes = \[nameserver\]/g)?.length).toBe(2);
+      expect(out.match(/ignore_changes = \[nameserver,/g)?.length).toBe(2);
     });
 
     test('matches the indentation of the resource opening line', () => {
@@ -707,7 +711,9 @@ resource "proxmox_lxc" "container" {
       const out = injectProxmoxLxcDns(indented, true);
       expect(out).toContain('    nameserver = "$self:lxc_nameserver"');
       expect(out).toContain('    lifecycle {');
-      expect(out).toContain('      ignore_changes = [nameserver]');
+      expect(out).toContain(
+        '      ignore_changes = [nameserver, network[0].hwaddr, rootfs[0].volume]',
+      );
     });
   });
 });

package/src/templates/generator.ts

@@ -15,6 +15,7 @@ import {
   moduleInfrastructure,
   modules,
 } from '../db/schema';
+import { getSingularSystemSpec } from '../manifest/schema';
 import type { AnsibleCollection, ModuleManifest } from '../manifest/schema';
 import { validateZoneRequirements } from '../manifest/validate';
 import { selectInfrastructure } from '../services/infrastructure-selector';
@@ -161,7 +162,10 @@ export function getOutputFilename(templateFilename: string): string {
  */
 export function injectProxmoxLxcDns(content: string, hasNameserver: boolean): string {
   // Already injected (idempotent) or author opted into the lifecycle — done.
-  if (content.includes('ignore_changes = [nameserver]')) {
+  // Match the `[nameserver` prefix (no closing bracket) so this stays true
+  // whether the list is the original `[nameserver]` or the ISS-0055-extended
+  // `[nameserver, network[0].hwaddr, …]` — otherwise re-generate double-injects.
+  if (content.includes('ignore_changes = [nameserver')) {
     return content;
   }
 
@@ -181,7 +185,17 @@ export function injectProxmoxLxcDns(content: string, hasNameserver: boolean): st
       injected.push(`${inner}nameserver = "$self:lxc_nameserver"`);
     }
     injected.push(`${inner}lifecycle {`);
-    injected.push(`${inner}  ignore_changes = [nameserver]`);
+    // ISS-0055: ignore the ForceNew attributes Proxmox assigns at create time —
+    // the MAC (network hwaddr) and the rootfs volume path. telmate marks these
+    // ForceNew, so leaving them out of the config makes every re-deploy plan a
+    // destructive REPLACE. Ignoring just these two makes an unchanged re-deploy a
+    // no-op (the computed network id/type stay stable once the block is no longer
+    // being replaced) and a real change (e.g. a memory bump) an in-place UPDATE.
+    // We deliberately do NOT list network[0].id / network[0].type — they aren't
+    // schema attributes in telmate ~>2.9 and `terraform validate` rejects them.
+    // `nameserver` stays for the original DNS reason; `rootfs.size` is NOT ignored
+    // so a disk grow still applies in place.
+    injected.push(`${inner}  ignore_changes = [nameserver, network[0].hwaddr, rootfs[0].volume]`);
     injected.push(`${inner}}`);
     return injected.join('\n');
   });
@@ -507,9 +521,9 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
 
   // Infrastructure Selection
   // Select infrastructure for this module and store in database
-  // Only required for modules that specify requires.machine (container-based or machine-poolbased)
+  // Only required for modules that specify requires.system (container-based or machine-pool-based)
   let infrastructureSelection: InfrastructureSelection | undefined;
-  const hasResourcesSpec = manifest.requires?.machine;
+  const hasResourcesSpec = getSingularSystemSpec(manifest);
 
   if (hasResourcesSpec) {
     // Check if infrastructure already selected (from previous generation)
@@ -559,7 +573,7 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
   // IPAM Auto-Allocation
   // Only allocate for Proxmox container services (not Digital Ocean or machines)
   // Digital Ocean gets IPs from Terraform outputs; Proxmox needs local IPAM
-  const zone = manifest.requires?.machine?.zone;
+  const zone = getSingularSystemSpec(manifest)?.zone;
   const hasManualVmid = manifest.variables?.owns?.some((v) => v.name === 'vmid');
   const isContainerService = infrastructureSelection?.type === 'container_service';
 
@@ -1094,7 +1108,7 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
   // Build infrastructure info for CLI output
   let infrastructureInfo: import('./types').InfrastructureInfo | undefined;
   if (infrastructureSelection) {
-    const zone = manifest.requires?.machine?.zone || 'unknown';
+    const zone = getSingularSystemSpec(manifest)?.zone || 'unknown';
 
     if (infrastructureSelection.type === 'machine' && infrastructureSelection.machineId) {
       const machine = await db

package/src/variables/context.test.ts

@@ -358,7 +358,7 @@ describe('Variable Context', () => {
             name: 'Grafana',
             version: '1.0.0',
             requires: {
-              machine: {
+              system: {
                 cpu: 2,
                 memory: 2048,
                 disk: 20,
@@ -372,34 +372,11 @@ describe('Variable Context', () => {
 
       const context = await buildResolutionContext('grafana', db);
 
-      expect(context.selfConfig['requires.machine.cpu']).toBe('2');
-      expect(context.selfConfig['requires.machine.memory']).toBe('2048');
-      expect(context.selfConfig['requires.machine.disk']).toBe('20');
-      expect(context.selfConfig['requires.machine.storage']).toBe('local-lvm');
-      expect(context.selfConfig['requires.machine.zone']).toBe('app');
-    });
-
-    test('should handle module without VM resources', async () => {
-      // Create module without VM resources
-      db.insert(modules)
-        .values({
-          id: 'simple',
-          name: 'Simple Module',
-          version: '1.0.0',
-          sourcePath: '/test/simple',
-          manifestData: {
-            id: 'simple',
-            name: 'Simple Module',
-            version: '1.0.0',
-          },
-        })
-        .run();
-
-      const context = await buildResolutionContext('simple', db);
-
-      // Should not have requires.machine keys
-      expect(context.selfConfig['requires.machine.cpu']).toBeUndefined();
-      expect(context.selfConfig['requires.machine.memory']).toBeUndefined();
+      expect(context.selfConfig['requires.system.cpu']).toBe('2');
+      expect(context.selfConfig['requires.system.memory']).toBe('2048');
+      expect(context.selfConfig['requires.system.disk']).toBe('20');
+      expect(context.selfConfig['requires.system.storage']).toBe('local-lvm');
+      expect(context.selfConfig['requires.system.zone']).toBe('app');
     });
 
     test('should auto-derive inventory variables from target_ip', async () => {
@@ -472,7 +449,7 @@ describe('Variable Context', () => {
               ],
             },
             requires: {
-              machine: {
+              system: {
                 zone: 'dmz',
               },
             },
@@ -529,7 +506,7 @@ describe('Variable Context', () => {
                 { name: 'target_ip', type: 'string', required: true, source: 'user' },
               ],
             },
-            requires: { machine: { zone: 'dmz' } },
+            requires: { system: { zone: 'dmz' } },
           },
         })
         .run();
@@ -649,7 +626,7 @@ describe('Variable Context', () => {
                 { name: 'target_ip', type: 'string', required: true, source: 'user' },
               ],
             },
-            requires: { machine: { zone: 'dmz' } },
+            requires: { system: { zone: 'dmz' } },
           },
         })
         .run();
@@ -672,7 +649,7 @@ describe('Variable Context', () => {
                 { name: 'target_ip', type: 'string', required: true, source: 'user' },
               ],
             },
-            requires: { machine: { zone: 'dmz' } },
+            requires: { system: { zone: 'dmz' } },
           },
         })
         .run();
@@ -890,7 +867,7 @@ describe('Variable Context', () => {
             name: 'App With Resources',
             version: '1.0.0',
             requires: {
-              machine: {
+              system: {
                 cpu: 2,
                 memory: 2048,
                 disk: 20,
@@ -935,7 +912,7 @@ describe('Variable Context', () => {
             name: 'Custom Resources',
             version: '1.0.0',
             requires: {
-              machine: {
+              system: {
                 cpu: 2,
                 memory: 2048,
               },
@@ -997,7 +974,7 @@ describe('Variable Context', () => {
             name: 'Partial Resources',
             version: '1.0.0',
             requires: {
-              machine: {
+              system: {
                 cpu: 1,
                 memory: 512,
                 // No disk or storage specified
@@ -1031,7 +1008,7 @@ describe('Variable Context', () => {
             name: 'DMZ Module',
             version: '1.0.0',
             requires: {
-              machine: {
+              system: {
                 zone: 'dmz',
               },
             },
@@ -1073,7 +1050,7 @@ describe('Variable Context', () => {
             name: 'App Module',
             version: '1.0.0',
             requires: {
-              machine: {
+              system: {
                 zone: 'app',
               },
             },
@@ -1103,7 +1080,7 @@ describe('Variable Context', () => {
             name: 'Secure Module',
             version: '1.0.0',
             requires: {
-              machine: {
+              system: {
                 zone: 'secure',
               },
             },
@@ -1158,7 +1135,7 @@ describe('Variable Context', () => {
             name: 'Custom Network',
             version: '1.0.0',
             requires: {
-              machine: {
+              system: {
                 zone: 'dmz',
               },
             },
@@ -1198,7 +1175,7 @@ describe('Variable Context', () => {
             name: 'VPS External',
             version: '1.0.0',
             requires: {
-              machine: {
+              system: {
                 zone: 'external',
               },
             },
@@ -1228,7 +1205,7 @@ describe('Variable Context', () => {
             name: 'No Net Config',
             version: '1.0.0',
             requires: {
-              machine: {
+              system: {
                 zone: 'dmz',
               },
             },

package/src/variables/context.ts

@@ -14,7 +14,7 @@ import {
   systemSecrets,
 } from '../db/schema';
 import { allocateResources, getAllocation } from '../ipam/allocator';
-import { type ModuleManifest, getDeclaredSystems } from '../manifest/schema';
+import { type ModuleManifest, getDeclaredSystems, getSingularSystemSpec } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { upsertModuleConfig } from '../services/module-config';
@@ -76,7 +76,7 @@ async function autoAssignFromWellKnown(
     const wellKnown = getWellKnownCapability(capability.name);
 
     // Determine current zone (from config or manifest)
-    const currentZone = selfConfig.zone || manifest.requires?.machine?.zone;
+    const currentZone = selfConfig.zone || getSingularSystemSpec(manifest)?.zone;
 
     // Auto-assign hostname if not already set
     if (!selfConfig.hostname) {
@@ -261,22 +261,22 @@ export async function buildResolutionContext(
   // Auto-apply VM resource defaults from manifest if not already configured
   if (module?.manifestData) {
     const manifest = module.manifestData as ModuleManifest;
-    const machineResources = manifest.requires?.machine;
+    const systemResources = getSingularSystemSpec(manifest);
 
-    if (machineResources) {
+    if (systemResources) {
       // Map manifest fields to module variable names and apply defaults
       const resourceMappings: Array<{
-        manifestKey: keyof typeof machineResources;
+        manifestKey: keyof typeof systemResources;
         configKey: string;
       }> = [
-        { manifestKey: 'cpu', configKey: 'cores' }, // manifest.requires.machine.cpu → cores variable
+        { manifestKey: 'cpu', configKey: 'cores' }, // manifest.requires.system.cpu → cores variable
         { manifestKey: 'memory', configKey: 'memory' },
         { manifestKey: 'disk', configKey: 'disk' },
         { manifestKey: 'storage', configKey: 'storage' },
       ];
 
       for (const { manifestKey, configKey } of resourceMappings) {
-        const value = machineResources[manifestKey];
+        const value = systemResources[manifestKey];
 
         // Manifest fields are typed (cpu: number, storage: string, etc.).
         // Pass them through unstringified so valueJson preserves the
@@ -374,15 +374,13 @@ export async function buildResolutionContext(
     }
   }
 
-  // Add machine requirements from manifest to selfConfig so templates can
-  // reference them via $self:requires.machine.<field>
+  // Add system requirements from manifest to selfConfig so templates can
+  // reference them via $self:requires.system.<field>.
   if (module?.manifestData) {
-    const manifest = module.manifestData as Record<string, unknown>;
-    const requires = manifest.requires as Record<string, unknown> | undefined;
-    if (requires?.machine) {
-      const machineRequires = requires.machine as Record<string, unknown>;
-      for (const [key, value] of Object.entries(machineRequires)) {
-        selfConfig[`requires.machine.${key}`] = String(value);
+    const systemSpec = getSingularSystemSpec(module.manifestData as ModuleManifest);
+    if (systemSpec) {
+      for (const [key, value] of Object.entries(systemSpec)) {
+        selfConfig[`requires.system.${key}`] = String(value);
       }
     }
   }
@@ -550,7 +548,7 @@ export async function buildResolutionContext(
   // Auto-derive network config from zone (gateway, vlan, subnet, bridge)
   if (module?.manifestData) {
     const manifest = module.manifestData as ModuleManifest;
-    const zone = selfConfig.zone || manifest.requires?.machine?.zone;
+    const zone = selfConfig.zone || getSingularSystemSpec(manifest)?.zone;
 
     // If zone from manifest but not in selfConfig, store it as first-class config
     if (zone && !selfConfig.zone) {

package/src/variables/lxc-nameserver.test.ts

@@ -24,7 +24,7 @@ describe('lxc_nameserver composition', () => {
         id: 'consumer',
         name: 'consumer',
         version: '1.0.0',
-        manifestData: { requires: { machine: { zone: 'app' } } },
+        manifestData: { requires: { system: { zone: 'app' } } },
         sourcePath: '/tmp/consumer',
       })
       .run();

package/tsconfig.json

@@ -16,6 +16,6 @@
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src/**/*"],
+  "include": ["src/**/*", "test-integration/**/*"],
   "exclude": ["node_modules"]
 }