@celilo/cli 1.5.0 → 1.6.0

package/src/module/packaging/audit.ts

@@ -4,8 +4,12 @@ import { join, relative } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { getDb } from '../../db/client';
 import { moduleIntegrity, modules } from '../../db/schema';
+import type { ModuleManifest } from '../../manifest/schema';
 import { computeFileChecksum } from './checksum';
 import type { IntegrityViolation } from './extract';
+import { compareVerbatimRoleAssets, readVerbatimRoleAssets } from './generated-plane';
+import { type HostPlaneResult, verifyModuleOnHosts } from './host-plane';
+import { classifyModulePath } from './package-rules';
 
 /**
  * Audit result for a module
@@ -15,24 +19,27 @@ export interface AuditResult {
   moduleId: string;
   violations: IntegrityViolation[];
   error?: string;
+  /** What the module records, and what version the baseline describes. */
+  moduleVersion?: string;
+  baselineVersion?: string | null;
+  /** Present only under `deep`. See `host-plane.ts`. */
+  hostPlane?: HostPlaneResult;
 }
 
-/**
- * Files the framework manages on the imported module's behalf and which
- * are NOT part of the package's signed checksums. Audit treats them as
- * neither modified nor extra — they're owned by Celilo, not the
- * module's source.
- *
- * `celilo/types.d.ts` is regenerated by `module import` (HOOK_API_V2
- * Phase 2 belt-and-suspenders). A fresh copy appears on disk after
- * extracting the package, but it isn't in `checksums.json` because the
- * package may have been built before the type was generated.
- */
-const FRAMEWORK_OWNED_PATHS = new Set(['celilo/types.d.ts']);
+export interface AuditOptions {
+  /**
+   * Also ask each of the module's systems whether what is running is what
+   * celilo generated. One SSH per system, so it is off by default.
+   */
+  deep?: boolean;
+}
 
 /**
- * Recursively scan directory and return all file paths, skipping
- * framework-owned files that shouldn't participate in audit checks.
+ * Recursively scan the installed tree, keeping only paths whose content is a
+ * stable integrity claim (`package`) or whose presence is a finding in itself
+ * (`unknown`). `derived` paths — `generated/**`, the hook runtime closure,
+ * `checksums.json` — are celilo's own and are dropped here, because a check
+ * that reports them can only ever be wrong.
  */
 async function scanDirectory(dir: string, baseDir: string): Promise<string[]> {
   const files: string[] = [];
@@ -42,21 +49,14 @@ async function scanDirectory(dir: string, baseDir: string): Promise<string[]> {
     const fullPath = join(dir, entry.name);
     const relativePath = relative(baseDir, fullPath);
 
-    if (FRAMEWORK_OWNED_PATHS.has(relativePath)) {
-      continue;
-    }
-
-    // Skip node_modules anywhere in the tree — these are installed by
-    // the framework during `module import` (NPM_PACKAGE_RESOLUTION
-    // Option B), not part of the module's signed checksums.
-    if (entry.isDirectory() && entry.name === 'node_modules') {
-      continue;
-    }
-
     if (entry.isDirectory()) {
+      // Prune whole derived subtrees rather than walking them. `generated/`
+      // alone carries terraform provider binaries.
+      if (classifyModulePath(relativePath) === 'derived') continue;
       const subFiles = await scanDirectory(fullPath, baseDir);
       files.push(...subFiles);
     } else if (entry.isFile()) {
+      if (classifyModulePath(relativePath) === 'derived') continue;
       files.push(relativePath);
     }
   }
@@ -71,7 +71,11 @@ async function scanDirectory(dir: string, baseDir: string): Promise<string[]> {
  * @param db - Database client (optional, for testing)
  * @returns Audit result with any violations found
  */
-export async function auditModule(moduleId: string, db = getDb()): Promise<AuditResult> {
+export async function auditModule(
+  moduleId: string,
+  db = getDb(),
+  options: AuditOptions = {},
+): Promise<AuditResult> {
   const violations: IntegrityViolation[] = [];
 
   try {
@@ -106,6 +110,26 @@ export async function auditModule(moduleId: string, db = getDb()): Promise<Audit
     const expectedChecksums: Record<string, string> = integrity.checksums;
     const moduleDir = module.sourcePath;
 
+    // Which version do these checksums describe? Ahead of every file finding,
+    // because when the answer is "not the installed one" the file findings are
+    // a consequence of it and not independent evidence. Before D1 this was
+    // unanswerable: the row was written once at first import and `module
+    // update` never touched it, so verify reported the same violations whether
+    // the files were old or the checksums were old.
+    if (integrity.version === null) {
+      violations.push({
+        type: 'stale-baseline',
+        path: 'checksums.json',
+        message: `Baseline records no version — it was written before celilo stamped them, so it cannot be compared to the installed ${module.version}. Re-run 'celilo module update' for this module to refresh it.`,
+      });
+    } else if (integrity.version !== module.version) {
+      violations.push({
+        type: 'stale-baseline',
+        path: 'checksums.json',
+        message: `Baseline describes ${integrity.version}, module records ${module.version}. The checksums are old, not the files. Re-run 'celilo module update' for this module to refresh it.`,
+      });
+    }
+
     // Check if module directory exists
     if (!existsSync(moduleDir)) {
       return {
@@ -116,8 +140,12 @@ export async function auditModule(moduleId: string, db = getDb()): Promise<Audit
       };
     }
 
-    // Validate all expected files exist and have correct checksums
+    // Validate all expected files exist and have correct checksums. A baseline
+    // entry for a derived path is not checkable: celilo rewrites those bytes
+    // after install (`bun install` over the hook runtime closure), so comparing
+    // them to what the package shipped can only ever produce a false positive.
     for (const [filePath, expectedChecksum] of Object.entries(expectedChecksums)) {
+      if (classifyModulePath(filePath) === 'derived') continue;
       const fullPath = join(moduleDir, filePath);
 
       if (!existsSync(fullPath)) {
@@ -125,6 +153,8 @@ export async function auditModule(moduleId: string, db = getDb()): Promise<Audit
           type: 'missing',
           path: filePath,
           message: `Missing file: ${filePath}`,
+          expectedDigest: expectedChecksum,
+          actualDigest: null,
         });
         continue;
       }
@@ -135,6 +165,33 @@ export async function auditModule(moduleId: string, db = getDb()): Promise<Audit
           type: 'modified',
           path: filePath,
           message: `Checksum mismatch: ${filePath}`,
+          expectedDigest: expectedChecksum,
+          actualDigest: actualChecksum,
+        });
+      }
+    }
+
+    // Plane two: is what we would deploy built from what we installed? Only
+    // verbatim role assets have a meaningful expected digest — Ansible
+    // templates the rest, and a `.j2` in `generated/` is SUPPOSED to differ.
+    // A module that has never been generated has nothing to compare and is not
+    // a finding; it is simply pre-deploy.
+    const generatedDir = join(moduleDir, 'generated');
+    if (existsSync(generatedDir)) {
+      const differences = compareVerbatimRoleAssets(
+        await readVerbatimRoleAssets(moduleDir),
+        await readVerbatimRoleAssets(generatedDir),
+      );
+      for (const difference of differences) {
+        violations.push({
+          type: 'stale-generated',
+          path: difference.relPath,
+          expectedDigest: difference.installedDigest,
+          actualDigest: difference.generatedDigest,
+          message:
+            difference.reason === 'missing'
+              ? `Generated project is missing ${difference.relPath} — the next deploy would ship nothing for it. Run 'celilo module generate ${moduleId}'.`
+              : `Generated project holds different bytes for ${difference.relPath} (generated ${difference.generatedDigest}, installed ${difference.installedDigest}) — the next deploy would ship the wrong ones. Run 'celilo module generate ${moduleId}'.`,
         });
       }
     }
@@ -153,10 +210,28 @@ export async function auditModule(moduleId: string, db = getDb()): Promise<Audit
       }
     }
 
+    // Plane three: is what is running what we generated? One SSH per system,
+    // so it is asked only when the caller says so.
+    let hostPlane: HostPlaneResult | undefined;
+    if (options.deep) {
+      hostPlane = await verifyModuleOnHosts({
+        moduleId,
+        manifest: module.manifestData as unknown as ModuleManifest,
+        generatedPath: generatedDir,
+      });
+    }
+
+    // An `unmeasured` host is not a pass. A check that could not reach its
+    // subject says so, and does not count as green.
+    const hostPlaneClean = (hostPlane?.findings ?? []).every((f) => f.state === 'converged');
+
     return {
-      success: violations.length === 0,
+      success: violations.length === 0 && hostPlaneClean,
       moduleId,
       violations,
+      moduleVersion: module.version,
+      baselineVersion: integrity.version,
+      hostPlane,
     };
   } catch (error) {
     return {

package/src/module/packaging/build.ts

@@ -9,7 +9,7 @@ import { log } from '../../cli/prompts';
 import { formatViolations, scanModuleDirectory } from '../../policy/module-script-scan';
 import { validateModuleDirectory } from '../import';
 import { computeFileChecksum } from './checksum';
-import { includeNodeModulesPath } from './package-rules';
+import { classifyModulePath, includeNodeModulesPath } from './package-rules';
 import { signChecksums } from './signature';
 import { rewriteWorkspaceDeps } from './workspace-deps';
 
@@ -49,63 +49,22 @@ export interface ModuleBuildResult {
 }
 
 /**
- * Files/directories to exclude from package.
+ * Check if a path inside the source dir should be excluded from the package.
  *
- * `node_modules` is NOT listed here — it's path-aware via the canonical
- * `includeNodeModulesPath` rule (package-rules.ts), so the hook-script runtime
- * closure is bundled while other node_modules is dropped.
- */
-const EXCLUDE_PATTERNS = [
-  '.git',
-  '.DS_Store',
-  '*.netapp',
-  '*.test.ts',
-  // Dev-only, same bucket as the tests: scripts/tsconfig.json exists so tsc can
-  // check hooks in CI. Nothing on a target ever runs tsc, and shipping it would
-  // make every module's packaged content change whenever the shared base moves.
-  'tsconfig.json',
-  'checksums.json',
-  'signature.sig',
-];
-
-/**
- * Path-relative files the framework manages and that should never be
- * bundled into a `.netapp` package. `celilo/types.d.ts` is generated
- * post-import by `module import` (HOOK_API_V2 Phase 2 belt-and-suspenders),
- * so shipping the local copy would just stamp the package with whatever
- * was on the author's disk at build time — including potentially stale
- * versions if the manifest changed since.
- */
-const FRAMEWORK_OWNED_PATHS = new Set(['celilo/types.d.ts']);
-
-/**
- * Check if a path inside the source dir should be excluded from the
- * package.
- *
- * The `node_modules` decision is delegated to the canonical
- * `includeNodeModulesPath` rule (package-rules.ts) — the single source of truth
- * the registry-server's bootstrap packager is held to as well (ISS-0046).
+ * `classifyModulePath` (package-rules.ts) is the one answer to what belongs to
+ * a module. Packaging differs from it in exactly one place: the hook runtime
+ * closure under `scripts/node_modules/` is `derived` (celilo's `bun install`
+ * owns the on-disk copy) and still SHIPS, because a target may have no
+ * reachable registry (ISS-0046). Everything else `derived` is celilo's own
+ * output, or the checksum manifest that cannot list itself.
  */
 function shouldExclude(filePath: string): boolean {
-  if (FRAMEWORK_OWNED_PATHS.has(filePath)) return true;
-
-  const segments = filePath.split('/');
-
-  // Module's e2e/ directory at the source root is tests + their deps —
-  // not part of the deployed module.
-  if (segments[0] === 'e2e') return true;
-
-  if (segments.includes('node_modules')) {
+  const cls = classifyModulePath(filePath);
+  if (cls === 'package') return false;
+  if (cls === 'derived' && filePath.split('/').includes('node_modules')) {
     return !includeNodeModulesPath(filePath);
   }
-
-  const name = basename(filePath);
-  return EXCLUDE_PATTERNS.some((pattern) => {
-    if (pattern.startsWith('*')) {
-      return name.endsWith(pattern.slice(1));
-    }
-    return name === pattern;
-  });
+  return true;
 }
 
 /**

package/src/module/packaging/classify-module-path.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { classifyModulePath } from './package-rules';
+
+/**
+ * Real input, not input built by the same helper as the expectation.
+ *
+ * These fixtures are verbatim `celilo module verify` output captured from the
+ * live fleet on 2026-08-19 (see the fixture README). Every path below is a path
+ * that actually exists in an installed module tree on celilo-mgr. celilo#951
+ * shipped 18 false positives because its comparator's test synthesised both
+ * sides of the comparison and so never saw real input.
+ */
+function fixturePaths(name: string): string[] {
+  const raw = readFileSync(
+    join(process.cwd(), 'test-fixtures', 'module-integrity', `${name}-verify.txt`),
+    'utf-8',
+  );
+  const paths: string[] = [];
+  for (const line of raw.split('\n')) {
+    const match = /(?:Checksum mismatch|Unexpected file): (.+)$/.exec(line.trim());
+    if (match?.[1]) paths.push(match[1]);
+  }
+  return paths;
+}
+
+describe('classifyModulePath against the live fleet listings', () => {
+  for (const [moduleName, expectedCount] of [
+    ['wireguard-manager', 47],
+    ['wireguard', 25],
+  ] as const) {
+    describe(moduleName, () => {
+      const paths = fixturePaths(moduleName);
+
+      test(`fixture carries all ${expectedCount} reported paths`, () => {
+        expect(paths.length).toBe(expectedCount);
+      });
+
+      test('no path in a real installed tree classifies unknown', () => {
+        const unknown = paths.filter((p) => classifyModulePath(p) === 'unknown');
+        expect(unknown).toEqual([]);
+      });
+
+      test('celilo-owned paths classify derived', () => {
+        const derived = paths.filter(
+          (p) =>
+            p.startsWith('generated/') ||
+            p.includes('node_modules/') ||
+            p === 'checksums.json' ||
+            p === 'signature.sig',
+        );
+        // Guard the guard: if this is empty the assertion below is vacuous.
+        expect(derived.length).toBeGreaterThan(0);
+        for (const p of derived) {
+          expect(`${p} => ${classifyModulePath(p)}`).toBe(`${p} => derived`);
+        }
+      });
+
+      test("the module's own content classifies package", () => {
+        const own = paths.filter(
+          (p) =>
+            !p.startsWith('generated/') &&
+            !p.includes('node_modules/') &&
+            p !== 'checksums.json' &&
+            p !== 'signature.sig',
+        );
+        expect(own.length).toBeGreaterThan(0);
+        for (const p of own) {
+          expect(`${p} => ${classifyModulePath(p)}`).toBe(`${p} => package`);
+        }
+      });
+    });
+  }
+});
+
+describe('classifyModulePath: source-tree paths that must never be installed', () => {
+  test.each([
+    ['e2e/deploy.test.ts'],
+    ['.git/config'],
+    ['scripts/tsconfig.json'],
+    ['.DS_Store'],
+    ['server/src/api.test.ts'],
+    ['wireguard.netapp'],
+    ['node_modules/tldts/package.json'],
+  ])('%s is unknown', (relPath) => {
+    expect(classifyModulePath(relPath)).toBe('unknown');
+  });
+});
+
+describe('classifyModulePath: composes with includeNodeModulesPath', () => {
+  test('the hook runtime closure is derived, not unknown', () => {
+    expect(classifyModulePath('scripts/node_modules/tldts/index.js')).toBe('derived');
+  });
+
+  test('a .bin shim is still excluded', () => {
+    expect(classifyModulePath('scripts/node_modules/.bin/tsc')).toBe('unknown');
+  });
+
+  test('non-scripts node_modules ships only @celilo/capabilities', () => {
+    expect(classifyModulePath('node_modules/@celilo/capabilities/src/index.ts')).toBe('derived');
+    expect(classifyModulePath('node_modules/@celilo/cli/index.js')).toBe('unknown');
+  });
+});

package/src/module/packaging/extract.ts

@@ -5,13 +5,40 @@ import { extract as tarExtract } from 'tar';
 import { z } from 'zod';
 import { parseJsonWithValidation } from '../../validation/schemas';
 import { computeFileChecksum } from './checksum';
+import { classifyModulePath } from './package-rules';
 import { verifySignature } from './signature';
 
 /**
  * Integrity violation types
  */
 export interface IntegrityViolation {
-  type: 'missing' | 'modified' | 'extra';
+  /**
+   * `stale-baseline` is not a file finding. It says the recorded checksums
+   * describe a DIFFERENT version of the module than the one celilo has
+   * installed, so every file finding beneath it is explained by the baseline
+   * being old rather than by the files having changed. Only `auditModule`
+   * produces it; package verification compares a package to its own manifest
+   * and cannot be stale in this sense.
+   *
+   * `stale-generated` is the second plane (D3): a verbatim role asset in
+   * `generated/` whose bytes are not the installed module's. That is what
+   * celilo#925 was, and what would ship on the next deploy.
+   */
+  type: 'missing' | 'modified' | 'extra' | 'stale-baseline' | 'stale-generated';
+  /**
+   * What the baseline says the file should hash to, and what it actually
+   * hashes to. Both optional because not every violation is about a digest —
+   * a `stale-baseline` finding is about the row, not a file.
+   *
+   * These exist so `module verify --json` can answer "is the installed tree
+   * the 0.3.2 package" in one call. celilo#925 stalled for days on that
+   * question because nothing could read a file on celilo-mgr, and the
+   * tempting fix — a remote read primitive — is a real security surface (every
+   * module's secrets and vault material live under the same tree) for a
+   * question file hashes answer directly (D9).
+   */
+  expectedDigest?: string;
+  actualDigest?: string | null;
   path: string;
   message: string;
 }
@@ -164,8 +191,9 @@ export async function verifyPackageIntegrity(
     const expectedFiles = new Set(Object.keys(expectedChecksums));
 
     for (const file of actualFiles) {
-      // Skip checksums.json and signature.sig
-      if (file === 'checksums.json' || file === 'signature.sig') {
+      // `checksums.json` / `signature.sig` and the rest of the derived set are
+      // never listed by the manifest they accompany.
+      if (classifyModulePath(file) === 'derived') {
         continue;
       }
 

package/src/module/packaging/generated-plane.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  compareVerbatimRoleAssets,
+  describeVerbatimDifferences,
+  readVerbatimRoleAssets,
+} from './generated-plane';
+
+describe('compareVerbatimRoleAssets', () => {
+  const asset = 'ansible/roles/vpn/files/vpn-linux-x86_64';
+
+  test('identical trees produce no differences', () => {
+    const both = new Map([[asset, 'aaa']]);
+    expect(compareVerbatimRoleAssets(both, new Map(both))).toEqual([]);
+  });
+
+  test('the celilo#925 shape: generated holds the previous version bytes', () => {
+    const differences = compareVerbatimRoleAssets(
+      new Map([[asset, 'new-digest']]),
+      new Map([[asset, 'old-digest']]),
+    );
+    expect(differences).toEqual([
+      {
+        relPath: asset,
+        reason: 'stale',
+        installedDigest: 'new-digest',
+        generatedDigest: 'old-digest',
+      },
+    ]);
+    expect(describeVerbatimDifferences(differences)[0]).toContain(asset);
+  });
+
+  test('an asset generation never produced is missing, not stale', () => {
+    expect(compareVerbatimRoleAssets(new Map([[asset, 'aaa']]), new Map())).toEqual([
+      { relPath: asset, reason: 'missing', installedDigest: 'aaa', generatedDigest: null },
+    ]);
+  });
+
+  test('output for a role the module no longer has is not a difference', () => {
+    // Nothing includes it, so refusing a deploy over it would refuse a correct
+    // module for a file Ansible never reads.
+    expect(
+      compareVerbatimRoleAssets(new Map(), new Map([['ansible/roles/gone/files/x', 'aaa']])),
+    ).toEqual([]);
+  });
+});
+
+describe('readVerbatimRoleAssets', () => {
+  test('digests role files/ assets and nothing else', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'celilo-plane-'));
+    try {
+      mkdirSync(join(root, 'ansible', 'roles', 'vpn', 'files', 'nested'), { recursive: true });
+      mkdirSync(join(root, 'ansible', 'roles', 'vpn', 'templates'), { recursive: true });
+      writeFileSync(join(root, 'ansible', 'roles', 'vpn', 'files', 'bin'), 'NEW');
+      writeFileSync(join(root, 'ansible', 'roles', 'vpn', 'files', 'nested', 'blob'), 'B');
+      // Templated, and expected to differ once generated. Must not be compared.
+      writeFileSync(join(root, 'ansible', 'roles', 'vpn', 'templates', 'x.j2'), '{{ v }}');
+
+      const assets = await readVerbatimRoleAssets(root);
+      expect([...assets.keys()].sort()).toEqual([
+        'ansible/roles/vpn/files/bin',
+        'ansible/roles/vpn/files/nested/blob',
+      ]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('a module with no ansible/ at all yields nothing rather than throwing', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'celilo-plane-'));
+    try {
+      expect((await readVerbatimRoleAssets(root)).size).toBe(0);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/module/packaging/generated-plane.ts

@@ -0,0 +1,134 @@
+/**
+ * The second plane: is what we would deploy built from what we installed?
+ *
+ * A module exists in four places — the published package, the installed tree,
+ * the generated project, and the host — and celilo reported a version for the
+ * first as though it described the last. Between them sit three copies and two
+ * transformations, and nothing verified any of them against the one before it
+ * (openspec/changes/module-integrity-rigor, D3).
+ *
+ * Only VERBATIM assets have a meaningful expected digest. Ansible templates
+ * most of what it writes, and a `.j2` in `generated/` is supposed to differ
+ * from its source. `ansible/roles/<role>/files/` is the exception: it holds
+ * static assets — built binaries, certs, blobs — copied byte for byte because
+ * they need no variable resolution and may not survive utf-8 round-tripping.
+ *
+ * That is exactly where celilo#925 lived. `copyAnsibleRoleFilesDirs` skipped an
+ * existing destination on bun, so a module's built binary landed in
+ * `generated/` once, at first generate, and no later version replaced it.
+ * `cp` reported no error, Ansible copied that first binary forever and reported
+ * `ok`, and the module's version field advanced past code that was never
+ * shipped. This comparison is local, takes milliseconds, needs no SSH, and is
+ * the check that turns that silence into a refusal.
+ */
+
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { computeFileChecksum } from './checksum';
+
+export interface VerbatimAssetDifference {
+  /** Path relative to the module root, identical in both trees. */
+  relPath: string;
+  /** `missing`: generation never produced it. `stale`: it holds other bytes. */
+  reason: 'missing' | 'stale';
+  installedDigest: string;
+  generatedDigest: string | null;
+}
+
+/**
+ * Pure. Both sides are digest maps keyed by the same module-relative path.
+ *
+ * An asset present in `generated` but absent from `installed` is NOT reported.
+ * That is a role the module no longer has, whose old output nothing includes,
+ * and failing a deploy for it would refuse a correct module for a stale file
+ * Ansible never reads.
+ */
+export function compareVerbatimRoleAssets(
+  installed: ReadonlyMap<string, string>,
+  generated: ReadonlyMap<string, string>,
+): VerbatimAssetDifference[] {
+  const differences: VerbatimAssetDifference[] = [];
+  for (const [relPath, installedDigest] of installed) {
+    const generatedDigest = generated.get(relPath) ?? null;
+    if (generatedDigest === null) {
+      differences.push({ relPath, reason: 'missing', installedDigest, generatedDigest: null });
+    } else if (generatedDigest !== installedDigest) {
+      differences.push({ relPath, reason: 'stale', installedDigest, generatedDigest });
+    }
+  }
+  return differences;
+}
+
+/**
+ * Digest every `ansible/roles/<role>/files/**` asset under `root`, keyed by its
+ * path relative to `root`. The generated project mirrors that layout, so the
+ * two maps this produces are directly comparable.
+ */
+export async function readVerbatimRoleAssets(root: string): Promise<Map<string, string>> {
+  const assets = new Map<string, string>();
+  const rolesDir = join(root, 'ansible', 'roles');
+  if (!existsSync(rolesDir)) return assets;
+
+  for (const role of await readdir(rolesDir, { withFileTypes: true })) {
+    if (!role.isDirectory()) continue;
+    const filesDir = join(rolesDir, role.name, 'files');
+    if (!existsSync(filesDir)) continue;
+    for (const filePath of await listFiles(filesDir)) {
+      assets.set(relative(root, filePath), await computeFileChecksum(filePath));
+    }
+  }
+  return assets;
+}
+
+async function listFiles(dir: string): Promise<string[]> {
+  const found: string[] = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      found.push(...(await listFiles(full)));
+    } else if (entry.isFile()) {
+      found.push(full);
+    }
+  }
+  return found;
+}
+
+/**
+ * One line per difference, naming the file. celilo#925 took days partly because
+ * nothing anywhere named the file that had gone stale.
+ */
+export function describeVerbatimDifferences(differences: VerbatimAssetDifference[]): string[] {
+  return differences.map((d) =>
+    d.reason === 'missing'
+      ? `${d.relPath}: generation never produced it (installed ${d.installedDigest})`
+      : `${d.relPath}: generated holds ${d.generatedDigest}, installed is ${d.installedDigest}`,
+  );
+}
+
+/**
+ * The deploy pre-flight (D6). Returns the refusal message, or `null` to proceed.
+ *
+ * Local, milliseconds, no SSH, and it runs before anything contacts a system.
+ * It deliberately does NOT verify after the deploy: Ansible's `changed` is
+ * truthful about what Ansible did, and the lie in celilo#925 was upstream of
+ * Ansible.
+ */
+export async function refuseIfGeneratedIsStale(
+  moduleId: string,
+  modulePath: string,
+  generatedPath: string,
+): Promise<string | null> {
+  const differences = compareVerbatimRoleAssets(
+    await readVerbatimRoleAssets(modulePath),
+    await readVerbatimRoleAssets(generatedPath),
+  );
+  if (differences.length === 0) return null;
+  return [
+    `Refusing to deploy ${moduleId}: the generated project does not match the installed module.`,
+    `  ${differences.length} verbatim asset(s) differ:`,
+    ...describeVerbatimDifferences(differences).map((line) => `    ${line}`),
+    '',
+    `Deploying would ship these bytes and report success. Run 'celilo module generate ${moduleId}' and try again.`,
+  ].join('\n');
+}