@celilo/cli 0.26.0 → 0.27.0

package/src/ansible/dependencies.ts

@@ -575,7 +575,17 @@ export async function getInstalledCollections(): Promise<Map<string, InstalledCo
               version: parseSemanticVersion(versionStr),
               path: path as string,
             });
-          } catch {}
+          } catch (error) {
+            // Rule 6.2: never a bare catch. An unparseable version dropped the
+            // collection from the map entirely, so it read as NOT INSTALLED —
+            // and the installer would then try to install it again, every time,
+            // reporting success while nothing changed.
+            console.warn(
+              `  ⚠ Ignoring installed collection '${name}': unparseable version '${versionStr}' (${
+                error instanceof Error ? error.message : String(error)
+              })`,
+            );
+          }
         }
       }
     }
@@ -587,6 +597,41 @@ export async function getInstalledCollections(): Promise<Map<string, InstalledCo
   }
 }
 
+/**
+ * Decide what an integrity outcome means for the import, and say so.
+ *
+ * A REFUTED collection stops the import; an UNCHECKABLE one warns. The split is
+ * the point (celilo#524):
+ *
+ *   - `mismatch` — files on disk do not match the collection's own manifest.
+ *     Ansible is about to execute that content, and celilo cannot account for
+ *     it. Refusing costs an import; accepting runs unaccounted-for code.
+ *   - `unverifiable` — the check could not run, most often because the
+ *     collection ships no `file_manifest_file` checksum at all. That is a
+ *     property of the publisher, not evidence of tampering, and blocking on it
+ *     would refuse ordinary collections forever. It warns.
+ *
+ * Refusing is cheap HERE specifically. This runs during `module import`
+ * (`module/import.ts`), the only caller, and nothing installs collections in
+ * the deploy path — so a false positive means "this module did not import",
+ * not "the fleet stopped deploying". There is also no module row yet, so
+ * nothing is left half-created to clean up.
+ *
+ * ⚠️ This is SELF-ATTESTATION, not provenance: the checksums live inside the
+ * artifact being checked. It catches corruption and post-install modification.
+ * It cannot catch a coherently re-signed tampered collection, and a clean
+ * import must not be read as saying otherwise.
+ */
+export function reportIntegrity(name: string, outcome: IntegrityOutcome): string | null {
+  if (outcome.status === 'mismatch') {
+    return `Integrity check FAILED for Ansible collection '${name}': ${outcome.detail}.\nThe installed files do not match the collection's own manifest — this is corruption or tampering.\nImport refused rather than run unverified content.`;
+  }
+  if (outcome.status === 'unverifiable') {
+    console.warn(`  ⚠ Integrity could not be checked for ${name}: ${outcome.reason} (non-fatal)`);
+  }
+  return null;
+}
+
 /**
  * Install result
  */
@@ -599,16 +644,22 @@ export interface InstallResult {
 }
 
 /**
- * Verify checksum of a file
+ * The three things checking one file's checksum can tell you.
  *
- * @param filePath - Path to file
- * @param expectedChecksum - Expected SHA256 checksum
- * @returns True if checksum matches, null if file doesn't exist
- */
-async function verifyFileChecksum(
-  filePath: string,
-  expectedChecksum: string,
-): Promise<boolean | null> {
+ * Named states rather than `boolean | null` (celilo#524). The tri-state was
+ * right — a file that is not on disk is genuinely neither a match nor a
+ * mismatch — but spelled as `null` it read as "nothing to worry about", and
+ * every caller duly treated it as one. `absent` cannot be misread.
+ */
+export type FileCheck = 'match' | 'mismatch' | 'absent';
+
+/**
+ * Verify one file against its expected SHA-256.
+ *
+ * `absent` means the file could not be read at all, which is a statement about
+ * our knowledge, not about the file's integrity.
+ */
+async function verifyFileChecksum(filePath: string, expectedChecksum: string): Promise<FileCheck> {
   const { createHash } = await import('node:crypto');
   const { readFile, access } = await import('node:fs/promises');
   const { constants } = await import('node:fs');
@@ -621,112 +672,130 @@ async function verifyFileChecksum(
     const hash = createHash('sha256');
     hash.update(content);
     const actualChecksum = hash.digest('hex');
-    return actualChecksum === expectedChecksum;
+    return actualChecksum === expectedChecksum ? 'match' : 'mismatch';
   } catch (_error: unknown) {
-    // File doesn't exist or can't be read - this is OK, not all files are installed
-    return null;
+    // Unreadable. NOT evidence of integrity — see the type's note.
+    return 'absent';
   }
 }
 
 /**
- * Verify integrity of installed collection
+ * What a verification run actually established.
+ *
+ * Three states, because there are three (celilo#524). The function used to
+ * return `boolean` and could not, in practice, return `false`: three
+ * independent paths reported "integrity verified" for a collection that had
+ * been tampered with, and no constructible input reached the failure return.
+ *
+ * `unverifiable` is the state that was missing. A manifest that declares no
+ * checksum, or a file set with nothing on disk to sample, tells you NOTHING
+ * about integrity — and folding that into `verified` is what let the one thing
+ * an attacker fully controls (the manifest they ship) switch the check off.
+ * Same absent-vs-empty distinction as `parseInterfaceBaseline`.
+ */
+export type IntegrityOutcome =
+  | { status: 'verified'; filesChecked: number }
+  /** Something was checked and did not match. Integrity is refuted. */
+  | { status: 'mismatch'; detail: string }
+  /** Nothing could be checked. Integrity is unknown — NOT confirmed. */
+  | { status: 'unverifiable'; reason: string };
+
+/**
+ * Verify an installed Galaxy collection against the checksums in its own
+ * MANIFEST.json / FILES.json.
  *
- * @param collectionInfo - Collection installation info
- * @returns True if integrity checks pass
+ * ⚠️ This is self-attestation, not provenance: the checksums live inside the
+ * artifact being checked. It detects corruption and post-install modification,
+ * and it CANNOT detect a coherently re-signed tampered collection. That is a
+ * reason to be precise about what it reports, not a reason to report a
+ * comforting answer.
  */
-async function verifyCollectionIntegrity(collectionInfo: InstalledCollection): Promise<boolean> {
+export async function verifyCollectionIntegrity(
+  collectionInfo: InstalledCollection,
+): Promise<IntegrityOutcome> {
   const { readFile } = await import('node:fs/promises');
   const { join } = await import('node:path');
 
+  const [namespace, collection] = collectionInfo.name.split('.');
+  const dir = join(collectionInfo.path, namespace, collection);
+
   try {
-    // Read MANIFEST.json
-    const manifestPath = join(
-      collectionInfo.path,
-      collectionInfo.name.split('.')[0],
-      collectionInfo.name.split('.')[1],
-      'MANIFEST.json',
-    );
-    const manifestContent = await readFile(manifestPath, 'utf-8');
     const manifest = parseJsonWithValidation(
-      manifestContent,
+      await readFile(join(dir, 'MANIFEST.json'), 'utf-8'),
       GalaxyManifestSchema,
       'Ansible Galaxy MANIFEST.json',
     );
 
-    // Verify FILES.json checksum
-    const filesJsonPath = join(
-      collectionInfo.path,
-      collectionInfo.name.split('.')[0],
-      collectionInfo.name.split('.')[1],
-      'FILES.json',
-    );
-
     const expectedFilesChecksum = manifest.file_manifest_file?.chksum_sha256;
     if (!expectedFilesChecksum) {
-      // No checksum to verify
-      return true;
+      // Was `return true`. Stripping `file_manifest_file` from the manifest was
+      // enough to report a tampered collection as verified.
+      return {
+        status: 'unverifiable',
+        reason: 'MANIFEST.json declares no FILES.json checksum',
+      };
     }
 
-    const filesChecksumValid = await verifyFileChecksum(filesJsonPath, expectedFilesChecksum);
-    if (!filesChecksumValid) {
-      console.warn(`  ⚠ Checksum mismatch for FILES.json in ${collectionInfo.name}`);
-      return false;
+    const filesJsonPath = join(dir, 'FILES.json');
+    switch (await verifyFileChecksum(filesJsonPath, expectedFilesChecksum)) {
+      case 'mismatch':
+        return { status: 'mismatch', detail: 'FILES.json does not match its manifest checksum' };
+      case 'absent':
+        return { status: 'unverifiable', reason: 'FILES.json is missing or unreadable' };
     }
 
-    // Sample verify a few files from FILES.json
-    const filesContent = await readFile(filesJsonPath, 'utf-8');
     const filesData = parseJsonWithValidation(
-      filesContent,
+      await readFile(filesJsonPath, 'utf-8'),
       GalaxyFilesSchema,
       'Ansible Galaxy FILES.json',
     );
     const files = filesData.files.filter(
       (f: { ftype: string; chksum_sha256?: string }) => f.ftype === 'file' && f.chksum_sha256,
     );
+    if (files.length === 0) {
+      return { status: 'unverifiable', reason: 'FILES.json lists no checksummed files' };
+    }
 
-    // Verify up to 5 random files that exist
+    // Sample rather than verify everything: a large collection is thousands of
+    // files and this runs on every deploy. Sampling bounds the cost; what it
+    // must never do is report a sample of ZERO as a pass.
     let verified = 0;
     let attempts = 0;
     const maxAttempts = Math.min(20, files.length);
 
     while (verified < 5 && attempts < maxAttempts) {
+      attempts++;
       const file = files[Math.floor(Math.random() * files.length)];
+      if (!file.chksum_sha256) continue;
 
-      // Skip files without checksums
-      if (!file.chksum_sha256) {
-        attempts++;
-        continue;
-      }
-
-      const filePath = join(
-        collectionInfo.path,
-        collectionInfo.name.split('.')[0],
-        collectionInfo.name.split('.')[1],
-        file.name,
-      );
-
-      const fileChecksumValid = await verifyFileChecksum(filePath, file.chksum_sha256);
-
-      if (fileChecksumValid === false) {
-        // File exists but checksum mismatch - this is a real error
-        console.warn(`  ⚠ Checksum mismatch for ${file.name} in ${collectionInfo.name}`);
-        return false;
+      const result = await verifyFileChecksum(join(dir, file.name), file.chksum_sha256);
+      if (result === 'mismatch') {
+        return { status: 'mismatch', detail: `${file.name} does not match its checksum` };
       }
+      if (result === 'match') verified++;
+      // 'absent' — try another. Bounded by maxAttempts, and a run that finds
+      // nothing present is reported as unverifiable below, not as a pass.
+    }
 
-      if (fileChecksumValid === true) {
-        // File exists and checksum matches
-        verified++;
-      }
-
-      // If fileChecksumValid === null, file doesn't exist, try another
-
-      attempts++;
+    if (verified === 0) {
+      // Was `return true`. A collection whose every listed file was missing
+      // from disk verified clean.
+      return {
+        status: 'unverifiable',
+        reason: `none of the ${attempts} sampled file(s) were present on disk`,
+      };
     }
 
-    return true;
-  } catch {
-    // If verification fails, log warning but don't fail install
-    return true;
+    return { status: 'verified', filesChecked: verified };
+  } catch (error) {
+    // Was `return true` behind a comment claiming it logged, which it did not —
+    // so ANY exception in the body above (unreadable manifest, schema
+    // violation, malformed JSON) was reported as integrity verified. Rule 6.2:
+    // the caller renders this, and it is now a distinct outcome from success.
+    return {
+      status: 'unverifiable',
+      reason: error instanceof Error ? error.message : String(error),
+    };
   }
 }
 
@@ -778,10 +847,11 @@ export async function installAnsibleCollections(
           const freshInstalled = await getInstalledCollections();
           const installedCollection = freshInstalled.get(req.name);
           if (installedCollection) {
-            const integrityOk = await verifyCollectionIntegrity(installedCollection);
-            if (!integrityOk) {
-              console.warn(`  ⚠ Integrity check failed for ${req.name} (non-fatal)`);
-            }
+            const refusal = reportIntegrity(
+              req.name,
+              await verifyCollectionIntegrity(installedCollection),
+            );
+            if (refusal) return { success: false, installed, skipped, error: refusal };
           }
         } catch (installError) {
           // Installation failed
@@ -800,10 +870,8 @@ export async function installAnsibleCollections(
         skipped.push(`${req.name} ${existingVersionStr}`);
 
         // Verify integrity of existing collection
-        const integrityOk = await verifyCollectionIntegrity(existing);
-        if (!integrityOk) {
-          console.warn(`  ⚠ Integrity check failed for ${req.name} (non-fatal)`);
-        }
+        const refusal = reportIntegrity(req.name, await verifyCollectionIntegrity(existing));
+        if (refusal) return { success: false, installed, skipped, error: refusal };
       }
     }
 

package/src/cli/commands/alerts-sweep.ts

@@ -94,9 +94,20 @@ export async function handleAlertsSweep(): Promise<CommandResult> {
 
   // The reason escalation declined is the single most useful fact when someone
   // asks "why was I not paged", so name it rather than aggregating it away.
-  const skipped = Object.entries(report.skipped).sort(([, a], [, b]) => b - a);
-  if (skipped.length > 0) {
-    lines.push(`  not delivered: ${skipped.map(([r, n]) => `${r}×${n}`).join(', ')}`);
+  if (report.skipped.length > 0) {
+    // Aggregate first — the shape of a sweep at a glance — then name each alert.
+    // A bare `within_grace×2` does not answer "why was I not paged" for the
+    // alert someone is actually looking at, and that question is the whole
+    // reason the reason is reported at all (#450).
+    const byReason = new Map<string, number>();
+    for (const { reason } of report.skipped) {
+      byReason.set(reason, (byReason.get(reason) ?? 0) + 1);
+    }
+    const counts = [...byReason].sort(([, a], [, b]) => b - a);
+    lines.push(`  not delivered: ${counts.map(([r, n]) => `${r}×${n}`).join(', ')}`);
+    for (const { alertKey, reason } of report.skipped) {
+      lines.push(`    ${alertKey}  (${reason})`);
+    }
   }
   // The error itself, not just a count: the transport is loaded lazily inside
   // the send, so a capability that will not load produces no other record

package/src/cli/commands/machine-add.ts

@@ -298,7 +298,6 @@ export async function handleMachineAdd(
         hardware: detectedInfo.hardware,
         role,
         interfaces,
-        assignedModuleIds: [],
         earmarkedModule: earmark || null,
       });
 

package/src/cli/commands/machine-list.ts

@@ -4,7 +4,11 @@
  */
 
 import type { NetworkZone } from '../../db/schema';
-import { type MachineFilters, listMachines } from '../../services/machine-pool';
+import {
+  type MachineFilters,
+  getModulesOnMachine,
+  listMachines,
+} from '../../services/machine-pool';
 import { celiloIntro } from '../prompts';
 import type { CommandResult } from '../types';
 
@@ -38,9 +42,11 @@ export async function handleMachineList(
 
     console.log('');
     for (const machine of machines) {
-      const assignedCount = machine.assignedModuleIds.length;
-      const assignedText =
-        assignedCount === 0 ? 'None (available)' : machine.assignedModuleIds.join(', ');
+      // Derived, not a stored snapshot (celilo#773): this line reported
+      // "None (available)" for a machine that was in fact hosting a VERIFIED
+      // module, which is the one place an operator would look to check.
+      const occupants = getModulesOnMachine(machine.id);
+      const assignedText = occupants.length === 0 ? 'None (available)' : occupants.join(', ');
 
       const roleLabel = machine.role === 'router' ? ' [router]' : '';
       console.log(`${machine.hostname} (${machine.zone})${roleLabel}`);

package/src/cli/commands/machine-remove.ts

@@ -4,7 +4,12 @@
  */
 
 import { askConfirm, withInterviewSession } from '../../services/bus-interview';
-import { getMachineByHostname, getMachineByIp, removeMachine } from '../../services/machine-pool';
+import {
+  getMachineByHostname,
+  getMachineByIp,
+  getModulesOnMachine,
+  removeMachine,
+} from '../../services/machine-pool';
 import { celiloIntro, celiloOutro } from '../prompts';
 import type { CommandResult } from '../types';
 
@@ -43,12 +48,13 @@ export async function handleMachineRemove(
     }
     const hostname = machine.hostname;
 
-    // Check for assigned modules
-    if (machine.assignedModuleIds.length > 0) {
-      console.log(
-        `\nError: Machine '${hostname}' has ${machine.assignedModuleIds.length} assigned module(s):`,
-      );
-      for (const moduleId of machine.assignedModuleIds) {
+    // Derived from the same source placement uses (celilo#773), so the two
+    // cannot disagree. Previously this refused to remove an empty machine over
+    // a module that no longer existed, and let an occupied one be removed.
+    const occupants = getModulesOnMachine(machine.id);
+    if (occupants.length > 0) {
+      console.log(`\nError: Machine '${hostname}' has ${occupants.length} assigned module(s):`);
+      for (const moduleId of occupants) {
         console.log(`  - ${moduleId}`);
       }
       console.log('\nModules must be unassigned or shut down before removing the machine.\n');

package/src/cli/commands/machine-status.ts

@@ -4,7 +4,7 @@
  */
 
 import { detectMachineInfo, testSshConnection } from '../../services/machine-detector';
-import { getMachineByHostname, getModuleResourcesOnMachine } from '../../services/machine-pool';
+import { getMachineByHostname, getModulesOnMachine } from '../../services/machine-pool';
 import { ManagedSshKey } from '../../services/ssh-key-manager';
 import { celiloIntro } from '../prompts';
 import type { CommandResult } from '../types';
@@ -57,21 +57,19 @@ export async function handleMachineStatus(
 
     console.log('Assigned Modules');
     console.log('───────────────');
-    if (machine.assignedModuleIds.length === 0) {
+    const occupants = getModulesOnMachine(machine.id);
+    if (occupants.length === 0) {
       console.log('None (available)');
     } else {
-      for (const moduleId of machine.assignedModuleIds) {
+      for (const moduleId of occupants) {
         console.log(`  - ${moduleId}`);
       }
 
-      // Show resource allocation
-      const allocated = await getModuleResourcesOnMachine(machine.id);
-      console.log('');
-      console.log('Resource Allocation');
-      console.log('──────────────────');
-      console.log(`CPU:    ${allocated.cpu} / ${machine.hardware.cpu_cores} cores`);
-      console.log(`Memory: ${allocated.memory} / ${machine.hardware.memory_mb} MB`);
-      console.log(`Disk:   ${allocated.disk} / ${machine.hardware.disk_gb} GB`);
+      // No "Resource Allocation" block (celilo#773). It printed
+      // `0 / <total>` for every resource on every machine, because its source
+      // returned hard-coded zeros behind a TODO — an operator reading it would
+      // conclude a fully-committed box was entirely free. The machine's own
+      // hardware is already printed above; that part is real.
     }
     console.log('');
 

package/src/db/schema.ts

@@ -428,10 +428,12 @@ export const machines = sqliteTable('machines', {
     .$type<Array<{ name: string; ipAddress: string; zone: string }>>()
     .notNull()
     .default(sql`'[]'`),
-  assignedModuleIds: text('assigned_module_ids', { mode: 'json' })
-    .$type<string[]>()
-    .notNull()
-    .default(sql`'[]'`),
+  // No `assigned_module_ids` (celilo#773). Occupancy is derived from
+  // `module_infrastructure` / `module_systems` at the point of use — both are
+  // written by the deploy path and both cascade on module removal, so a machine
+  // frees itself. The dropped column had one append-only writer, no removal
+  // path, and no reader that reconciled it, and it had already diverged in both
+  // directions on the live fleet.
   /** Module ID this machine is earmarked for. If set, only this module can use this machine. */
   earmarkedModule: text('earmarked_module'),
   /**

package/src/hooks/capability-loader.ts

@@ -332,6 +332,11 @@ export async function loadCapabilityFunctions(
           secrets: providerSecrets,
           systems: getModuleSystems(capability.moduleId, db),
           logger,
+          // WHO IS CALLING, so a provider can scope per-consumer state to them.
+          // `createPublicWeb` has always had this; compiled factories did not,
+          // which made a module-provided capability structurally unable to
+          // offer `unregisterRoutes()`-style methods.
+          consumerModuleId: consumingModuleId,
         });
         // Stamp here too, not only on the legacy path: a consumer that cannot
         // get what it needs must be able to name WHICH provider could not give
@@ -1037,6 +1042,7 @@ async function buildFirewallChain(
       secrets: leafSecrets,
       systems: getModuleSystems(hasExternal.moduleId, db),
       logger,
+      consumerModuleId: consumingModuleId,
     });
     leafFirewall = stampProvider(leafFirewall, hasExternal.moduleId);
     debugLog(

package/src/hooks/define-hook.test.ts

@@ -46,6 +46,7 @@ function makeContext(overrides: Partial<HookContext> = {}): HookContext {
     secrets: {},
     systems: [],
     logger: makeLogger(),
+    consumerModuleId: 'test-consumer',
     debug: false,
     screenshotDir: '',
     capabilities: {},
@@ -350,6 +351,7 @@ describe('defineCapabilityFunction', () => {
       secrets: { token: 'abc' },
       systems: [],
       logger: makeLogger(),
+      consumerModuleId: 'test-consumer',
     });
 
     expect(typeof methods.create_oidc_client).toBe('function');
@@ -376,6 +378,7 @@ describe('defineCapabilityFunction', () => {
       secrets: {},
       systems: [],
       logger: makeLogger(),
+      consumerModuleId: 'test-consumer',
     });
 
     const result = await methods.registerHost({ fqdn: 'www.example.com' });
@@ -404,6 +407,7 @@ describe('defineCapabilityFunction', () => {
       secrets: {},
       systems: [],
       logger: makeLogger(),
+      consumerModuleId: 'test-consumer',
     });
 
     const result = await methods.exposeService({

package/src/hooks/types.ts

@@ -121,7 +121,8 @@ export type HookName =
   | 'on_restore'
   | 'on_system_event'
   | 'refresh_registrations'
-  | 'reassert_dhcp_dns';
+  | 'reassert_dhcp_dns'
+  | 'reconcile_clients';
 
 /**
  * Hook manifest section - maps hook names to definitions

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

@@ -26,7 +26,6 @@ describe('extractMachineProperties', () => {
       zone: 'external',
       role: 'host',
       interfaces: [],
-      assignedModuleIds: [],
       createdAt: new Date(),
       updatedAt: new Date(),
     };
@@ -51,7 +50,6 @@ describe('extractMachineProperties', () => {
       zone: 'internal',
       role: 'host',
       interfaces: [],
-      assignedModuleIds: [],
       createdAt: new Date(),
       updatedAt: new Date(),
     };

package/src/manifest/contracts/v1.ts

@@ -210,6 +210,25 @@ export const V1_HOOKS: ContractHooks = {
     inputs: {},
     outputs: {},
   },
+  /**
+   * Reconcile the clients a self-service app has enrolled against what the
+   * VPN provider actually carries (openspec/changes/wireguard-manager, D1).
+   *
+   * The hook, rather than a bus `handler` subscription, because it needs
+   * CAPABILITY INJECTION: it calls `control_plane_vpn.registerClient` and
+   * `revokeClient`, and a handler gets no capabilities. No framework inputs —
+   * it reads the app's address from its own `systems` and holds a token it
+   * minted for itself at install.
+   *
+   * Typically driven by a `timer.tick.*` subscription, and the tick interval IS
+   * the window in which a revoked device still has reach — which is why the
+   * design requires the UI to show the pending state rather than imply
+   * revocation is instant (D12).
+   */
+  reconcile_clients: {
+    inputs: {},
+    outputs: {},
+  },
   /**
    * Build-bus upstream publish hook. The executor passes the
    * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,

package/src/manifest/schema.ts

@@ -674,6 +674,7 @@ export const ModuleManifestSchema = z
          * client can be handed the wrong resolver. See celilo#739.
          */
         reassert_dhcp_dns: LifecycleHookSchema.optional(),
+        reconcile_clients: LifecycleHookSchema.optional(),
         /**
          * Build-bus upstream publish hooks. Array (a module can react
          * to multiple upstream packages with different actions). See