@celilo/cli 0.3.30 → 0.4.0-alpha.0

package/src/hooks/types.ts

@@ -6,6 +6,8 @@
  * (e.g., container_created triggers web automation for API key creation).
  */
 
+import type { DeployedSystem } from '@celilo/capabilities';
+
 /**
  * Hook definition from module manifest.
  *
@@ -52,6 +54,11 @@ export interface HookContext {
   config: Record<string, unknown>;
   /** Module secret values (decrypted) */
   secrets: Record<string, string>;
+  /**
+   * The 0..N systems this module has deployed onto (v2/MODULE_SYSTEMS_ADDRESSING.md).
+   * Always an array — no singular convenience, so the 0/1/N reality stays visible.
+   */
+  systems: DeployedSystem[];
   /** Logger for reporting progress */
   logger: HookLogger;
   /** Run in debug mode (e.g., Playwright headless: false) */
@@ -111,7 +118,8 @@ export type HookName =
   | 'validate_config'
   | 'on_backup'
   | 'on_backup_analyze'
-  | 'on_restore';
+  | 'on_restore'
+  | 'on_system_event';
 
 /**
  * Hook manifest section - maps hook names to definitions

package/src/manifest/contracts/v1.ts

@@ -81,6 +81,30 @@ export const V1_HOOKS: ContractHooks = {
   on_backup: {
     inputs: {
       backup_dir: { required: true },
+      /**
+       * Path to a directory containing read-only mirrors of OTHER modules'
+       * `generated/terraform/` trees, plus an `index.json` enumerating
+       * deployed modules. Populated by the framework ONLY when the
+       * declaring module has `cross_module_read` in its
+       * `requires.capabilities` AND is on the privilege allow-list (see
+       * `validatePrivilegedCapabilities` in manifest/validate.ts). Today
+       * only celilo-mgmt is allow-listed.
+       *
+       * Hooks that don't require the privilege won't see this input.
+       * Hooks that do require it should treat the directory as
+       * read-only — modifying it has no effect (the framework discards
+       * changes after the hook returns).
+       *
+       * Layout:
+       *   <cross_module_root>/
+       *     index.json          # { modules: [{ id, version, terraformStateDir }] }
+       *     modules/
+       *       <module-id>/
+       *         terraform/
+       *           terraform.tfstate
+       *           terraform.tfstate.backup
+       */
+      cross_module_root: { required: false },
     },
     outputs: {
       artifact_count: { required: true },
@@ -102,11 +126,57 @@ export const V1_HOOKS: ContractHooks = {
     inputs: {
       restore_dir: { required: true },
       schema_version: { required: true },
+      /**
+       * Path to a writable staging directory the framework atomically
+       * applies back onto OTHER modules' on-disk state after the hook
+       * returns successfully. Same allow-list as `cross_module_root`
+       * on on_backup; only celilo-mgmt receives it today.
+       *
+       * Hooks write files matching the on_backup layout
+       * (`modules/<module-id>/terraform/terraform.tfstate` etc.). The
+       * framework moves each subdir into the live storage path with
+       * a single rename + cleanup of any stale files, so a partial
+       * write (hook crashed mid-restore) leaves the live state intact.
+       */
+      cross_module_write_root: { required: false },
     },
     outputs: {
       restored_items: { required: true },
     },
   },
+  /**
+   * Per-system DNS lifecycle hook (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md D5).
+   *
+   * A dns_internal provider declares this hook; celilo's internal-dns bridge
+   * invokes it once per host when a system.created/destroyed event fires,
+   * supplying that host's identity. The bridge owns the cross-module concerns
+   * (which module is the provider, the full host inventory for backfill); the
+   * hook owns only the DNS mechanics (register/deregister across the zones the
+   * provider is authoritative for). No structured outputs — the hook throws on
+   * failure (no-surprises; v2/issues/ISS-0004).
+   */
+  on_system_event: {
+    inputs: {
+      /** Short hostname of the system being (de)registered, e.g. "www". */
+      hostname: { required: true },
+      /** The system's A-record target IP (no CIDR suffix), e.g. "10.0.10.10". */
+      target_ip: { required: true },
+      /** "register" on system.created, "deregister" on system.destroyed. */
+      op: { required: true },
+    },
+    outputs: {},
+  },
+  /**
+   * Build-bus upstream publish hook. The executor passes the
+   * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,
+   * CELILO_EVENT_PACKAGE_NAME, etc.) rather than as named inputs
+   * here — see v2/BUILD_BUS.md Phase 4 + the hook-dispatch executor.
+   * No structured outputs; hook reports success via exit code.
+   */
+  on_upstream_publish: {
+    inputs: {},
+    outputs: {},
+  },
 };
 
 /**

package/src/manifest/schema.ts

@@ -209,6 +209,23 @@ export const EnsureSchema = z.object({
 
 export type Ensure = z.infer<typeof EnsureSchema>;
 
+/**
+ * A computed capability field (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md D1).
+ *
+ * Declared alongside `data`, but derived ON ACCESS from other values via the
+ * `value:` DSL (see src/variables/computed/) and never persisted. The result
+ * TYPE is inferred from the expression — deliberately not declared, which is
+ * why `type` is the fixed literal `computed` rather than a real type.
+ */
+export const ComputedFieldSchema = z.object({
+  name: z.string().min(1),
+  type: z.literal('computed'),
+  value: z.string().min(1),
+  description: z.string().optional(),
+});
+
+export type ComputedField = z.infer<typeof ComputedFieldSchema>;
+
 /**
  * Capability provider
  * Module provides this capability to other modules
@@ -217,6 +234,13 @@ export const CapabilityProviderSchema = z.object({
   name: z.string().min(1),
   version: z.string().min(1),
   data: z.record(z.unknown()),
+  /**
+   * Computed fields, merged into the capability's data namespace at access
+   * time. A consumer reads `$capability:<name>.<computed-field>` exactly like
+   * a static data field; the resolver evaluates the DSL in the PROVIDER's
+   * context. Names must not collide with `data` keys.
+   */
+  computed: z.array(ComputedFieldSchema).optional(),
   secrets: z.array(CapabilitySecretSchema).optional(),
   functions: z.array(z.string()).optional(),
   /** Zones this capability applies to. Null/undefined = zone-agnostic. */
@@ -242,6 +266,38 @@ export const LifecycleHookSchema = z.object({
   timeout: z.number().positive().optional(),
 });
 
+/**
+ * Build-bus upstream-publish hook. Fires when a publish event lands
+ * on the local event bus from the receiver daemon
+ * ([[v2/BUILD_BUS.md]] Phase 4). Each module can declare multiple
+ * entries, each with its own match rule + action script.
+ *
+ * The action script runs with `CELILO_EVENT_PAYLOAD` in its env (the
+ * full PublishEvent as JSON), plus `CELILO_EVENT_PACKAGE_NAME` /
+ * `CELILO_EVENT_PACKAGE_VERSION` for the common fields. Exit status
+ * non-zero is logged but doesn't propagate to the publisher.
+ */
+export const UpstreamPublishHookSchema = z.object({
+  /** Optional display label for logs / `celilo subscribers status`. */
+  name: z.string().optional(),
+  /**
+   * Match rule — every non-undefined field must equal the
+   * corresponding field on the incoming event. Shape mirrors
+   * `SubscriberMatch` in @celilo/event-bus/build-bus.
+   */
+  match: z
+    .object({
+      registry: z.string().optional(),
+      tag: z.string().optional(),
+      package_pattern: z.string().optional(),
+    })
+    .default({}),
+  /** Path to the action script, relative to the module directory. */
+  script: z.string().min(1),
+  /** Seconds before the script is killed. Default: 600. */
+  timeout: z.number().positive().optional(),
+});
+
 /**
  * Machine resource recommendations
  * Module declares recommended machine resources (CPU, memory, disk, storage)
@@ -256,6 +312,21 @@ export const MachineResourceSchema = z.object({
     .describe('Required security zone for this module'),
 });
 
+/**
+ * One system a module deploys (v2/MODULE_SYSTEMS_ADDRESSING.md). A module
+ * declares 0..N of these under `requires.systems`. `name` is the stable
+ * authoring-time handle — referenced in templates via `$infra:<name>.…` and the
+ * per-system key in `module_systems`. `resources` carries the per-system machine
+ * spec + zone (each system can sit in a different zone).
+ */
+export const SystemDeclarationSchema = z.object({
+  name: z
+    .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,
+});
+
 /**
  * Ansible collection requirement
  * Declares Ansible collections this module needs
@@ -289,19 +360,45 @@ export const AnsibleCollectionSchema = z.object({
  *   - `$self` in `pattern` → the module's id
  *   - `${MODULE_PATH}` in `handler` → the module's installed path
  */
-export const ModuleSubscriptionSchema = z.object({
-  name: z
-    .string()
-    .min(1)
-    .regex(
-      /^[a-z][a-z0-9_-]*$/,
-      'Subscription name must be kebab/snake_case (lowercase, alphanumeric, dash/underscore)',
-    ),
-  pattern: z.string().min(1),
-  handler: z.string().min(1),
-  max_attempts: z.number().int().positive().optional(),
-  timeout_ms: z.number().int().positive().optional(),
-});
+export const ModuleSubscriptionSchema = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .regex(
+        /^[a-z][a-z0-9_-]*$/,
+        'Subscription name must be kebab/snake_case (lowercase, alphanumeric, dash/underscore)',
+      ),
+    pattern: z.string().min(1),
+    /**
+     * Shell-command handler the dispatcher spawns as a subprocess. Mutually
+     * exclusive with `hook` — a subscription declares exactly one.
+     */
+    handler: z.string().min(1).optional(),
+    /**
+     * Name of one of THIS module's own hooks to invoke when a matching event
+     * fires (v2/EVENT_DRIVEN_HOOK_SUBSCRIPTIONS.md). The framework synthesizes
+     * a `celilo events run-hook` handler that runs the hook in a
+     * fault-isolated subprocess with backend access (DB, capabilities,
+     * secrets). Mutually exclusive with `handler`.
+     */
+    hook: z.string().min(1).optional(),
+    /**
+     * Static inputs merged into the hook's `inputs` (e.g. `{ op: register }`),
+     * so two subscriptions can drive the same hook with different intent.
+     * Event payload fields are merged on top. Only valid alongside `hook`.
+     */
+    hook_inputs: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    max_attempts: z.number().int().positive().optional(),
+    timeout_ms: z.number().int().positive().optional(),
+  })
+  .strict()
+  .refine((s) => (s.handler ? 1 : 0) + (s.hook ? 1 : 0) === 1, {
+    message: 'subscription must declare exactly one of `handler` or `hook`',
+  })
+  .refine((s) => !s.hook_inputs || Boolean(s.hook), {
+    message: '`hook_inputs` is only valid together with `hook`',
+  });
 
 export type ModuleSubscription = z.infer<typeof ModuleSubscriptionSchema>;
 
@@ -337,9 +434,16 @@ export const ModuleManifestSchema = z
       .object({
         capabilities: z.array(CapabilityRequirementSchema).default([]),
         /**
-         * Infrastructure this module needs. Was `resources.machine` in v1.
-         * Optional because some modules (e.g. config-only providers like
-         * namecheap) don't deploy infrastructure.
+         * The 0..N systems this module deploys (v2/MODULE_SYSTEMS_ADDRESSING.md).
+         * Preferred over the legacy singular `machine`. 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`.
          */
         machine: MachineResourceSchema.optional(),
       })
@@ -399,6 +503,20 @@ export const ModuleManifestSchema = z
         on_backup: LifecycleHookSchema.optional(),
         on_backup_analyze: LifecycleHookSchema.optional(),
         on_restore: LifecycleHookSchema.optional(),
+        /**
+         * Per-system lifecycle hook. A dns_internal provider declares this
+         * to (de)register a single host's A records when celilo's bridge
+         * delivers a system.created/destroyed event. Inputs (hostname,
+         * target_ip, op) come from the contract — see contracts/v1.ts and
+         * [[v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md]] D5.
+         */
+        on_system_event: LifecycleHookSchema.optional(),
+        /**
+         * Build-bus upstream publish hooks. Array (a module can react
+         * to multiple upstream packages with different actions). See
+         * [[v2/BUILD_BUS.md]] Phase 4.
+         */
+        on_upstream_publish: z.array(UpstreamPublishHookSchema).optional(),
       })
       .strict()
       .optional(),
@@ -477,6 +595,113 @@ export const ModuleManifestSchema = z
      * use `manifest.subscriptions ?? []`.
      */
     subscriptions: z.array(ModuleSubscriptionSchema).optional(),
+
+    /**
+     * Optional base-module aspect — lightweight fleet-configuration
+     * code applied to OTHER systems in declared zones, on top of
+     * the module's primary deployment. See v2/CELILO_BASE.md.
+     *
+     * Modules without this block work exactly as today. When
+     * declared, the operator approves the aspect's scope at
+     * `celilo module import` time (or passes `--accept-aspects` for
+     * non-interactive use). The framework then runs the named
+     * Ansible role against every non-`api_only` system in
+     * `applicable_zones` whenever a declared trigger fires.
+     */
+    base_module_aspect: z
+      .object({
+        /**
+         * The Ansible role under `base-module-aspect/ansible/roles/`
+         * that runs on each target system. Receives module config
+         * + capability data as ansible vars plus a `target_zone`
+         * fact.
+         */
+        ansible_role: z.string().min(1),
+
+        /**
+         * Zones this aspect fans out to. There is no operator-level
+         * opt-in beyond import-time approval — these zones ARE the
+         * target set. At least one zone must be listed.
+         */
+        applicable_zones: z.array(z.string().min(1)).min(1),
+
+        /**
+         * Events that should cause the aspect to fan out.
+         *
+         * Phase 1 ships only `on_install`. Later phases add
+         * `on_new_system_in_zone`, `on_aspect_change`,
+         * `on_module_config_change`, `on_capability_data_change` —
+         * the enum is open here so manifests can declare future
+         * triggers ahead of framework support landing, but only the
+         * triggers the framework knows about will actually fire.
+         */
+        triggers: z
+          .array(
+            z.enum([
+              'on_install',
+              'on_new_system_in_zone',
+              'on_aspect_change',
+              'on_module_config_change',
+              'on_capability_data_change',
+            ]),
+          )
+          .min(1)
+          .default(['on_install']),
+
+        /**
+         * Optional Ansible variables to inject into the aspect's
+         * inventory before the role runs. Each entry maps a
+         * variable name (consumed by the role as `{{ name }}`) to
+         * a value template using the same `$self:` / `$capability:`
+         * / `$system:` substitution celilo uses elsewhere. Values
+         * resolve against the PROVIDING module's context at fan-out
+         * time, then land in `group_vars/all/aspect_vars.yml` so
+         * every targeted system's role can read them.
+         *
+         * Example (knot-unbound-internal):
+         *   ansible_vars:
+         *     knot_server_ip: $self:target_ip
+         *
+         * Without this block the role only receives `target_zone`
+         * — useful but rarely sufficient.
+         */
+        ansible_vars: z.record(z.string(), z.string()).optional(),
+
+        /**
+         * Optional Proxmox reconciliation (v2/CELILO_BASE.md D5).
+         *
+         * When an aspect manages a setting that Proxmox also owns
+         * authoritatively (DNS resolver via `proxmox_lxc.nameserver`
+         * is the canonical example), declaring `proxmox_reconcile.tfvars`
+         * tells the framework to ALSO update the LXC's owning
+         * module's terraform config — not just the running
+         * /etc/resolv.conf via Ansible. Without this, a re-provision
+         * would revert to the stale Proxmox-baked value.
+         *
+         * Each entry maps a `terraform.tfvars` variable name to a
+         * value-template. Templates support the same `$capability:`
+         * and `$self:` substitutions celilo uses elsewhere; the
+         * value is resolved against the providing module's context
+         * (capability data + module config) at fan-out time.
+         *
+         * Only applies to systems whose `module_infrastructure`
+         * row is `container_service` AND the service's provider is
+         * Proxmox. Machine-pool systems silently skip this block
+         * because they aren't terraform-managed at the celilo
+         * layer.
+         */
+        proxmox_reconcile: z
+          .object({
+            tfvars: z.record(z.string(), z.string()),
+          })
+          .strict()
+          .optional(),
+      })
+      // strict on the inner object: operators approve this exact
+      // block at import time (D2), so silently-ignored unknown
+      // fields would let a manifest broaden scope without consent.
+      .strict()
+      .optional(),
   })
   .strict();
 
@@ -494,3 +719,24 @@ 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 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.
+ */
+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 }];
+  }
+  return [];
+}

package/src/manifest/validate-privileged.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Tests for validatePrivilegedCapabilities — the allow-list gate that
+ * rejects modules requiring framework-granted privileges (today: only
+ * cross_module_read, allow-listed to celilo-mgmt).
+ */
+
+import { describe, expect, it } from 'bun:test';
+import type { ModuleManifest } from './schema';
+import { validatePrivilegedCapabilities } from './validate';
+
+function buildManifest(overrides: Partial<ModuleManifest>): ModuleManifest {
+  return {
+    celilo_contract: '1.0',
+    id: 'some-module',
+    name: 'some module',
+    version: '0.0.1',
+    requires: { capabilities: [] },
+    ...overrides,
+  } as ModuleManifest;
+}
+
+describe('validatePrivilegedCapabilities', () => {
+  it('accepts manifests with no privileged capabilities', () => {
+    const result = validatePrivilegedCapabilities(
+      buildManifest({
+        id: 'homebridge',
+        requires: { capabilities: [{ name: 'public_web', version: '^3.0' }] },
+      }),
+    );
+    expect(result).toBeNull();
+  });
+
+  it('accepts celilo-mgmt requiring cross_module_read', () => {
+    const result = validatePrivilegedCapabilities(
+      buildManifest({
+        id: 'celilo-mgmt',
+        requires: { capabilities: [{ name: 'cross_module_read', version: '^1.0' }] },
+      }),
+    );
+    expect(result).toBeNull();
+  });
+
+  it('rejects a non-allow-listed module requiring cross_module_read', () => {
+    const result = validatePrivilegedCapabilities(
+      buildManifest({
+        id: 'homebridge',
+        requires: { capabilities: [{ name: 'cross_module_read', version: '^1.0' }] },
+      }),
+    );
+    expect(result).not.toBeNull();
+    expect(result?.errors).toHaveLength(1);
+    expect(result?.errors[0].path).toBe('requires.capabilities.cross_module_read');
+    expect(result?.errors[0].message).toContain('framework-granted privilege');
+    expect(result?.errors[0].message).toContain('celilo-mgmt');
+    expect(result?.errors[0].message).toContain("'homebridge' is not on the allow-list");
+  });
+
+  it('also rejects when declared under optional.capabilities', () => {
+    const result = validatePrivilegedCapabilities(
+      buildManifest({
+        id: 'sneaky-module',
+        requires: { capabilities: [] },
+        optional: {
+          capabilities: [{ name: 'cross_module_read', version: '^1.0' }],
+        },
+      } as Partial<ModuleManifest>),
+    );
+    expect(result).not.toBeNull();
+    expect(result?.errors[0].path).toBe('optional.capabilities.cross_module_read');
+  });
+
+  it('aggregates errors when a module both requires AND optionally declares the privilege', () => {
+    const result = validatePrivilegedCapabilities(
+      buildManifest({
+        id: 'sneaky-module',
+        requires: { capabilities: [{ name: 'cross_module_read', version: '^1.0' }] },
+        optional: {
+          capabilities: [{ name: 'cross_module_read', version: '^1.0' }],
+        },
+      } as Partial<ModuleManifest>),
+    );
+    expect(result?.errors).toHaveLength(2);
+  });
+});

package/src/manifest/validate.test.ts

@@ -1321,3 +1321,159 @@ subscriptions:
     expect(result.success).toBe(false);
   });
 });
+
+describe('base_module_aspect field', () => {
+  test('accepts a minimal valid aspect block', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: knot-unbound-internal
+name: Internal DNS
+version: 1.0.0
+
+base_module_aspect:
+  ansible_role: dns-client-config
+  applicable_zones: [app]
+  triggers: [on_install]
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.base_module_aspect?.ansible_role).toBe('dns-client-config');
+      expect(result.data.base_module_aspect?.applicable_zones).toEqual(['app']);
+      expect(result.data.base_module_aspect?.triggers).toEqual(['on_install']);
+    }
+  });
+
+  test('defaults triggers to [on_install] when omitted', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: knot-unbound-internal
+name: Internal DNS
+version: 1.0.0
+
+base_module_aspect:
+  ansible_role: dns-client-config
+  applicable_zones: [dmz, app, secure, internal]
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.base_module_aspect?.triggers).toEqual(['on_install']);
+    }
+  });
+
+  test('accepts the full trigger set', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: knot-unbound-internal
+name: Internal DNS
+version: 1.0.0
+
+base_module_aspect:
+  ansible_role: dns-client-config
+  applicable_zones: [app]
+  triggers:
+    - on_install
+    - on_new_system_in_zone
+    - on_aspect_change
+    - on_module_config_change
+    - on_capability_data_change
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(true);
+  });
+
+  test('rejects empty applicable_zones', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: knot-unbound-internal
+name: Internal DNS
+version: 1.0.0
+
+base_module_aspect:
+  ansible_role: dns-client-config
+  applicable_zones: []
+  triggers: [on_install]
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects missing ansible_role', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: knot-unbound-internal
+name: Internal DNS
+version: 1.0.0
+
+base_module_aspect:
+  applicable_zones: [app]
+  triggers: [on_install]
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects unknown trigger names', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: knot-unbound-internal
+name: Internal DNS
+version: 1.0.0
+
+base_module_aspect:
+  ansible_role: dns-client-config
+  applicable_zones: [app]
+  triggers: [on_install, on_nonsense]
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects empty triggers when explicitly set', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: knot-unbound-internal
+name: Internal DNS
+version: 1.0.0
+
+base_module_aspect:
+  ansible_role: dns-client-config
+  applicable_zones: [app]
+  triggers: []
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(false);
+  });
+
+  test('omitting the block entirely is valid (most modules)', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: homebridge
+name: Homebridge
+version: 1.0.0
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.base_module_aspect).toBeUndefined();
+    }
+  });
+
+  test('rejects unknown fields inside the block (strict)', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: knot-unbound-internal
+name: Internal DNS
+version: 1.0.0
+
+base_module_aspect:
+  ansible_role: dns-client-config
+  applicable_zones: [app]
+  triggers: [on_install]
+  unknown_extra_field: foo
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(false);
+  });
+});