@celilo/cli 2.1.0 → 2.2.1

package/src/cli/commands/module-config.test.ts

@@ -10,8 +10,9 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { type DbClient, getDb } from '../../db/client';
-import { modules } from '../../db/schema';
+import { moduleConfigs, modules } from '../../db/schema';
 import { resolveDeployPosture } from '../../services/deploy-posture';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import {
   FRAMEWORK_CONFIG_KEYS,
   handleModuleConfigGet,
@@ -41,6 +42,7 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
               { name: 'vmid', type: 'integer', source: 'infrastructure' },
               { name: 'target_node', type: 'string', source: 'infrastructure' },
               { name: 'app_port', type: 'integer' },
+              { name: 'public_ip', type: 'string', source: 'hook' },
             ],
           },
         },
@@ -50,7 +52,7 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
   });
 
   test('rejects an infrastructure-managed key (no silent accept-then-override)', async () => {
@@ -79,6 +81,24 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
     expect(result.success).toBe(true);
   });
 
+  // Hook-owned-state task 2.4 (design D2/D6): a `source: hook` variable is
+  // written ONLY by the module's own hook via `context.config.set`. A hand set
+  // value would be meaningless — the next hook run overwrites it — so the
+  // command refuses rather than reporting success over nothing.
+  test('rejects a hook-owned key and points at the accessor', async () => {
+    const result = await handleModuleConfigSet(['testmod', 'public_ip', '203.0.113.7']);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain('source: hook');
+      expect(result.error).toContain('not operator-settable');
+      expect(result.error).toContain('context.config.set');
+    }
+    // And no row may exist — a refusal that leaves the row behind is the
+    // accept-then-override bug in a different coat.
+    const rows = db.select().from(moduleConfigs).all();
+    expect(rows).toEqual([]);
+  });
+
   test('still rejects an undeclared key, and omits infra keys from the valid-keys hint', async () => {
     const result = await handleModuleConfigSet(['testmod', 'nope', 'x']);
     expect(result.success).toBe(false);

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

@@ -14,7 +14,7 @@ import type { CommandResult } from '../types';
  * Handle module deploy command
  *
  * Usage:
- *   celilo module deploy <module-id> [--debug] [--preflight] [--verbose]
+ *   celilo module deploy <module-id> [--debug] [--preflight] [--verbose] [--keep]
  *
  * Note: there is no `--no-interactive` flag. The deploy interview
  * runs through the bus event system; automation answers via a
@@ -59,8 +59,14 @@ export async function handleModuleDeploy(
   const debug = hasFlag(flags, 'debug');
   const verbose = hasFlag(flags, 'verbose');
   const stopAfterInterview = hasFlag(flags, 'stop-after-interview');
+  const keepGeneratedProject = hasFlag(flags, 'keep');
 
-  const result = await deployModule(moduleId, db, { debug, verbose, stopAfterInterview });
+  const result = await deployModule(moduleId, db, {
+    debug,
+    verbose,
+    stopAfterInterview,
+    keepGeneratedProject,
+  });
 
   if (!result.success) {
     return {

package/src/cli/commands/module-generate.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, beforeEach, 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 type { ModuleManifest } from '../../manifest/schema';
+import { missingBuildOutputs } from './module-generate';
+
+const DECLARED = join('ansible', 'roles', 'fixture', 'files', 'binary');
+
+function manifestWithArtifacts(artifacts: string[]): ModuleManifest {
+  return {
+    celilo_contract: '1.0',
+    id: 'fixture',
+    name: 'Fixture',
+    version: '1.0.0',
+    description: 'fixture',
+    build: { command: 'true', artifacts },
+  } as ModuleManifest;
+}
+
+describe('missingBuildOutputs', () => {
+  let payload: string;
+
+  beforeEach(() => {
+    payload = mkdtempSync(join(tmpdir(), 'celilo-missing-outputs-'));
+  });
+
+  afterEach(() => {
+    rmSync(payload, { recursive: true, force: true });
+  });
+
+  test('names the declared output the payload is missing', () => {
+    expect(missingBuildOutputs(payload, manifestWithArtifacts([DECLARED]))).toEqual([DECLARED]);
+  });
+
+  test('reports nothing when the payload carries its declared outputs', () => {
+    mkdirSync(join(payload, 'ansible', 'roles', 'fixture', 'files'), { recursive: true });
+    writeFileSync(join(payload, DECLARED), 'built-bytes');
+    expect(missingBuildOutputs(payload, manifestWithArtifacts([DECLARED]))).toEqual([]);
+  });
+
+  test('reports nothing for a module with no build block', () => {
+    expect(
+      missingBuildOutputs(payload, {
+        celilo_contract: '1.0',
+        id: 'fixture',
+        name: 'Fixture',
+        version: '1.0.0',
+        description: 'fixture',
+      } as ModuleManifest),
+    ).toEqual([]);
+  });
+});

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

@@ -3,7 +3,7 @@
  */
 
 import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { eq } from 'drizzle-orm';
 import {
   promptForMissingCapabilitySecrets,
@@ -13,12 +13,25 @@ import { getDb } from '../../db/client';
 import { moduleConfigs, modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
 import { interviewForMissingSecrets, validateModuleSecrets } from '../../services/config-interview';
-import { getModuleBuildStatus, verifyArtifactsExist } from '../../services/module-build';
 import { generateTemplates } from '../../templates/generator';
 import { promptForMissingConfig } from '../interactive-config';
 import { getArg, getFlag, validateRequiredArgs } from '../parser';
 import type { CommandResult } from '../types';
 
+/**
+ * Declared `build.artifacts` absent from the module's delivered payload.
+ *
+ * D1 (control-plane-stops-building-modules): generation consumes the payload.
+ * A declared output the payload does not carry is a publish defect, so it is
+ * reported to the caller and named, never repaired by running a build here.
+ * A fallback build is the shape that hid celilo#1307 for four months: the
+ * failure must fail loudly at the boundary, not be repaired downstream.
+ */
+export function missingBuildOutputs(modulePath: string, manifest: ModuleManifest): string[] {
+  const artifacts = manifest.build?.artifacts ?? [];
+  return artifacts.filter((artifact) => !existsSync(join(modulePath, artifact)));
+}
+
 /**
  * Handle module generate command
  *
@@ -71,31 +84,23 @@ export async function handleModuleGenerate(
     };
   }
 
-  // Check if module requires build step
+  // D1 (control-plane-stops-building-modules): generation consumes the
+  // delivered payload. Whether this machine ever ran a build is a fact about
+  // its own history, not about the module in front of it — gating on it is
+  // what made celilo#1307 refuse generation on a production control plane
+  // whose payload carried the correct binaries one directory away.
   const manifest = module.manifestData as ModuleManifest;
-  if (manifest.build) {
-    const buildStatus = await getModuleBuildStatus(moduleId, db);
-
-    if (!buildStatus || buildStatus.status !== 'success') {
-      return {
-        success: false,
-        error:
-          `Module ${moduleId} requires build step before generation.\n\n` +
-          `Run: celilo module build ${moduleId}`,
-      };
-    }
-
-    // Verify artifacts still exist
-    if (buildStatus.artifacts.length > 0) {
-      const artifactsValid = verifyArtifactsExist(buildStatus.artifacts);
-
-      if (!artifactsValid) {
-        return {
-          success: false,
-          error: `Build artifacts missing or invalid.\n\nRebuild: celilo module build ${moduleId}`,
-        };
-      }
-    }
+  const missingOutputs = missingBuildOutputs(modulePath, manifest);
+  if (missingOutputs.length > 0) {
+    return {
+      success: false,
+      error: [
+        `Module payload is missing ${missingOutputs.length} declared build output(s):`,
+        ...missingOutputs.map((artifact) => `  ${artifact}`),
+        '',
+        "The payload must carry the module's build outputs; a control plane never builds. This is a publish defect: re-package the module and update it. Generation will not fall back to running a build.",
+      ].join('\n'),
+    };
   }
 
   const outputPathFlag = getFlag(flags, 'output', '');

package/src/cli/commands/module-import-aspect.test.ts

@@ -12,6 +12,7 @@ import { closeDb, getDb } from '../../db/client';
 import { runMigrations } from '../../db/migrate';
 import { modules } from '../../db/schema';
 import type { BaseModuleAspect } from '../../manifest/schema';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handleAspectApprovalAfterImport } from './module-import';
 
 const aspect: BaseModuleAspect = {
@@ -61,7 +62,7 @@ describe('handleAspectApprovalAfterImport (non-interactive)', () => {
   afterEach(() => {
     setTTY(originalIsTTY);
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/cli/commands/module-import-registry.test.ts

@@ -17,6 +17,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { IndexEntry } from '../../registry/client';
 import { RegistryClient } from '../../registry/client';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handlePublicRegistryImport } from './module-import';
 
 // handlePublicRegistryImport is not exported by default — re-exported at end of module-import.ts
@@ -42,7 +43,7 @@ afterEach(() => {
   getIndexSpy.mockRestore();
   downloadSpy.mockRestore();
   rmSync(tempDir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
+  resetTestDbPath();
   process.env.CELILO_DATA_DIR = undefined;
 });
 

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

@@ -339,7 +339,7 @@ async function handlePublicRegistryImport(
   // Download the .netapp
   const tmpPath = join(tmpdir(), `${name}-${latest.vers}-${Date.now()}.netapp`);
   try {
-    const pkgData = await client.download(name, latest.vers);
+    const pkgData = await client.download(name, latest.vers, latest.cksum);
     await Bun.write(tmpPath, pkgData);
   } catch (err) {
     return {

package/src/cli/commands/module-operations.test.ts

@@ -7,6 +7,7 @@ import { closeDb, getDb } from '../../db/client';
 import { runMigrations } from '../../db/migrate';
 import { moduleOperations } from '../../db/schema';
 import { ABANDONED_RELEASE_MESSAGE, OPERATION_TTL_MS } from '../../services/module-operations';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handleModuleOperations } from './module-operations';
 
 describe('celilo module operations', () => {
@@ -20,7 +21,7 @@ describe('celilo module operations', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     rmSync(dir, { recursive: true, force: true });
   });
 

package/src/cli/commands/module-publish.test.ts

@@ -15,6 +15,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import type { IndexEntry } from '../../registry/client';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handleModulePublish, resolveToken } from './module-publish';
 
 const TEST_DIR = `/tmp/test-module-publish-${Date.now()}`;
@@ -41,7 +42,6 @@ describe('handleModulePublish — validation', () => {
     // fallback in resolveToken() may read a real publish token and the test
     // will skip the validation path it's trying to exercise.
     const origToken = process.env.CELILO_PUBLISH_TOKEN;
-    const origDbPath = process.env.CELILO_DB_PATH;
     const origDataDir = process.env.CELILO_DATA_DIR;
     process.env.CELILO_PUBLISH_TOKEN = undefined;
     process.env.CELILO_DB_PATH = `/tmp/test-celilo-no-token-${Date.now()}.db`;
@@ -52,8 +52,7 @@ describe('handleModulePublish — validation', () => {
       if (!result.success) expect(result.error).toContain('Publish token required');
     } finally {
       if (origToken !== undefined) process.env.CELILO_PUBLISH_TOKEN = origToken;
-      if (origDbPath !== undefined) process.env.CELILO_DB_PATH = origDbPath;
-      else process.env.CELILO_DB_PATH = undefined;
+      resetTestDbPath();
       if (origDataDir !== undefined) process.env.CELILO_DATA_DIR = origDataDir;
       else process.env.CELILO_DATA_DIR = undefined;
     }
@@ -163,7 +162,6 @@ describe('revision auto-detection algorithm', () => {
 describe('resolveToken — precedence', () => {
   test('--token flag wins over env var and secret store', async () => {
     const origEnv = process.env.CELILO_PUBLISH_TOKEN;
-    const origDbPath = process.env.CELILO_DB_PATH;
     process.env.CELILO_PUBLISH_TOKEN = 'env-token';
     process.env.CELILO_DB_PATH = `/tmp/test-celilo-resolve-${Date.now()}.db`;
     try {
@@ -172,14 +170,12 @@ describe('resolveToken — precedence', () => {
     } finally {
       if (origEnv !== undefined) process.env.CELILO_PUBLISH_TOKEN = origEnv;
       else process.env.CELILO_PUBLISH_TOKEN = undefined;
-      if (origDbPath !== undefined) process.env.CELILO_DB_PATH = origDbPath;
-      else process.env.CELILO_DB_PATH = undefined;
+      resetTestDbPath();
     }
   });
 
   test('env var used when --token flag is empty', async () => {
     const origEnv = process.env.CELILO_PUBLISH_TOKEN;
-    const origDbPath = process.env.CELILO_DB_PATH;
     process.env.CELILO_PUBLISH_TOKEN = 'env-token';
     process.env.CELILO_DB_PATH = `/tmp/test-celilo-resolve-${Date.now()}.db`;
     try {
@@ -188,8 +184,7 @@ describe('resolveToken — precedence', () => {
     } finally {
       if (origEnv !== undefined) process.env.CELILO_PUBLISH_TOKEN = origEnv;
       else process.env.CELILO_PUBLISH_TOKEN = undefined;
-      if (origDbPath !== undefined) process.env.CELILO_DB_PATH = origDbPath;
-      else process.env.CELILO_DB_PATH = undefined;
+      resetTestDbPath();
     }
   });
 
@@ -197,7 +192,6 @@ describe('resolveToken — precedence', () => {
     // All three sources empty: secret-store fallback hits an isolated empty
     // DB and returns null gracefully.
     const origEnv = process.env.CELILO_PUBLISH_TOKEN;
-    const origDbPath = process.env.CELILO_DB_PATH;
     const origDataDir = process.env.CELILO_DATA_DIR;
     process.env.CELILO_PUBLISH_TOKEN = undefined;
     process.env.CELILO_DB_PATH = `/tmp/test-celilo-resolve-empty-${Date.now()}.db`;
@@ -207,8 +201,7 @@ describe('resolveToken — precedence', () => {
       expect(t).toBe('');
     } finally {
       if (origEnv !== undefined) process.env.CELILO_PUBLISH_TOKEN = origEnv;
-      if (origDbPath !== undefined) process.env.CELILO_DB_PATH = origDbPath;
-      else process.env.CELILO_DB_PATH = undefined;
+      resetTestDbPath();
       if (origDataDir !== undefined) process.env.CELILO_DATA_DIR = origDataDir;
       else process.env.CELILO_DATA_DIR = undefined;
     }

package/src/cli/commands/module-update.test.ts

@@ -18,8 +18,10 @@ import {
 import { tmpdir } from 'node:os';
 import { join, relative } from 'node:path';
 import { eq } from 'drizzle-orm';
+import { create as tarCreate } from 'tar';
 import { type DbClient, getDb } from '../../db/client';
 import { moduleIntegrity, modules } from '../../db/schema';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { classifyVersionChange, handleModuleUpdate, updateOne } from './module-update';
 
 describe('classifyVersionChange', () => {
@@ -123,7 +125,7 @@ description: fixture
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_ORIGINAL_CWD = undefined;
   });
 
@@ -312,7 +314,7 @@ describe('registry sweep — an unanswered breaking update is not a decline', ()
   afterEach(() => {
     server.stop(true);
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_ORIGINAL_CWD = undefined;
     process.env.EVENT_BUS_DB = undefined;
   });
@@ -386,7 +388,7 @@ description: fixture
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_ORIGINAL_CWD = undefined;
   });
 
@@ -498,7 +500,7 @@ describe('updateOne — an update that fails partway leaves the install untouche
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_ORIGINAL_CWD = undefined;
   });
 
@@ -556,3 +558,84 @@ describe('updateOne — an update that fails partway leaves the install untouche
     expect(mod?.version).toBe('1.0.0');
   });
 });
+
+describe('updateOne — a .netapp package source', () => {
+  let tempDir: string;
+  let installedDir: string;
+  let db: DbClient;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-netapp-'));
+    process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
+    process.env.CELILO_ORIGINAL_CWD = tempDir;
+
+    installedDir = join(tempDir, 'installed', 'testmod');
+    mkdirSync(installedDir, { recursive: true });
+    writeFileSync(
+      join(installedDir, 'manifest.yml'),
+      'celilo_contract: "1.0"\nid: testmod\nname: Test Module\nversion: 1.0.0\ndescription: fixture\n',
+    );
+
+    db = getDb();
+    db.insert(modules)
+      .values({
+        id: 'testmod',
+        name: 'Test Module',
+        sourcePath: installedDir,
+        version: '1.0.0+5',
+        manifestData: {
+          celilo_contract: '1.0',
+          id: 'testmod',
+          name: 'Test Module',
+          version: '1.0.0',
+        },
+      })
+      .run();
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+    resetTestDbPath();
+    process.env.CELILO_ORIGINAL_CWD = undefined;
+  });
+
+  // ce-h4of: the temp-dir cleanup ran BEFORE the staged swap, and
+  // `replaceInstalledModule` still reads the extracted package through
+  // `actualPath`, which IS the temp dir for a .netapp source. Every
+  // registry-driven upgrade died with `ENOENT ... scandir
+  // .tmp-module-extract/<ts>`. Directory sources never set tempDir, which
+  // is why the path-source tests above stayed green. This test drives the
+  // real extraction path to keep that ordering honest.
+  test('the staged swap reads the package before the temp dir is cleaned', async () => {
+    const srcDir = join(tempDir, 'pkg-src');
+    mkdirSync(srcDir, { recursive: true });
+    writeFileSync(
+      join(srcDir, 'manifest.yml'),
+      'celilo_contract: "1.0"\nid: testmod\nname: Test Module\nversion: 2.0.0\ndescription: fixture v2\n',
+    );
+    const pkgPath = join(tempDir, 'testmod-2.0.0.netapp');
+    await tarCreate({ file: pkgPath, cwd: srcDir }, ['manifest.yml']);
+
+    const extractRoot = join(process.cwd(), '.tmp-module-extract');
+    const extractCountBefore = existsSync(extractRoot) ? readdirSync(extractRoot).length : 0;
+
+    // Registry packages are pre-verified at publish time; updateOne gets
+    // skip-verify from the sweep, so no signature.sig is needed here.
+    const result = await updateOne(
+      pkgPath,
+      db,
+      { 'skip-verify': true },
+      { quiet: true, displayVersion: '2.0.0+7' },
+    );
+
+    expect(result.status).toBe('success');
+    if (result.status !== 'success') return;
+    expect(result.previousVersion).toBe('1.0.0+5');
+    expect(result.newVersion).toBe('2.0.0+7');
+    expect(readFileSync(join(installedDir, 'manifest.yml'), 'utf-8')).toContain('version: 2.0.0');
+
+    // The extraction scratch space is gone again once the swap has read it.
+    const extractCountAfter = existsSync(extractRoot) ? readdirSync(extractRoot).length : 0;
+    expect(extractCountAfter).toBe(extractCountBefore);
+  });
+});

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

@@ -128,7 +128,13 @@ export async function fetchAndUpdate(
 ): Promise<UpdateOutcome> {
   const tmpPath = join(tmpdir(), `${moduleId}-${version}-${Date.now()}.netapp`);
   try {
-    const pkgData = await client.download(moduleId, version);
+    // The index entry carries the published sha256. Look it up here rather than
+    // thread it through five call sites, so a short download is caught as a bad
+    // transfer instead of surfacing later as "zlib: unexpected end of file".
+    // Absence is tolerated: an entry predating cksum still downloads.
+    const entries = await client.getIndex(moduleId).catch(() => []);
+    const cksum = entries.find((entry) => entry.vers === version)?.cksum;
+    const pkgData = await client.download(moduleId, version, cksum);
     await Bun.write(tmpPath, pkgData);
   } catch (err) {
     return {
@@ -410,9 +416,6 @@ export async function updateOne(
     ? readFileSync(packagedSignaturePath, 'utf-8').trim()
     : null;
 
-  // Clean up temp dir if we extracted a .netapp
-  if (tempDir) await cleanupTempDir(tempDir);
-
   // Remove what the new version dropped. `updateOne` only ever overlaid files,
   // so a hook script deleted in 1.1.0 stayed on the box and stayed runnable —
   // code celilo no longer believes it has installed, which is the same class of
@@ -440,6 +443,13 @@ export async function updateOne(
   // below it runs only once the files are really in place.
   replaceInstalledModule(actualPath, installedPath, pruneDropped);
 
+  // Clean up the extracted package. This waits until after the swap because
+  // `replaceInstalledModule` reads `actualPath`, which IS `tempDir` for a
+  // .netapp source — deleting first is what made every registry-driven
+  // upgrade die with `ENOENT ... scandir .tmp-module-extract/<ts>`
+  // (ce-h4of, a regression from the celilo#1008 staging swap).
+  if (tempDir) await cleanupTempDir(tempDir);
+
   // Record it. `updateOne` never touched this table, so the baseline stayed
   // frozen at the module's FIRST import no matter how many times it was
   // updated. That is why `module verify` reported the same violations whether

package/src/cli/commands/module-upgrade.test.ts

@@ -4,6 +4,7 @@ import {
   type PollCandidate,
   isPollInvocation,
   needsPreUpgradeBackup,
+  needsSystemStateSnapshot,
   pickAutoUpgrade,
   pickUpgradePolicy,
   selectPollTargets,
@@ -102,6 +103,20 @@ describe('selectPollTargets (ISS-0139 — opted-in + a newer registry version)',
   });
 });
 
+// A 0.x minor/major bump can migrate the celilo DB schema; the system_state
+// snapshot is what makes a later `apt install celilo=<old>` (or dpkg -i from
+// the apt cache) a real rollback instead of a gamble. Patch/revision bumps
+// don't migrate, so they stay fast.
+describe('needsSystemStateSnapshot (safe posture snapshots the celilo DB before mutating)', () => {
+  test('safe posture (minor/major) requires the snapshot', () => {
+    expect(needsSystemStateSnapshot('safe')).toBe(true);
+  });
+
+  test('fast posture (patch/revision) skips the snapshot', () => {
+    expect(needsSystemStateSnapshot('fast')).toBe(false);
+  });
+});
+
 describe('needsPreUpgradeBackup (ISS-0168 — gate on the TARGET version manifest)', () => {
   // The regression: the upgrade that FIRST adds on_backup must still back up.
   // The installed version lacked the hook; the target (passed here) adds it.

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

@@ -20,7 +20,8 @@ import { type DbClient, getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
 import { RegistryClient } from '../../registry/client';
-import { createModuleBackup } from '../../services/backup-create';
+import { createModuleBackup, createSystemStateBackup } from '../../services/backup-create';
+import { getDefaultBackupStorage } from '../../services/backup-storage';
 import {
   type DeployPosture,
   type UpgradePolicy,
@@ -79,6 +80,47 @@ export function needsPreUpgradeBackup(
   return posture === 'safe' && Boolean(targetManifest.hooks?.on_backup);
 }
 
+/**
+ * Pure (Rule 10): does this upgrade snapshot the celilo DB first? Safe posture
+ * means a minor/major bump, and a minor bump can migrate the DB schema — the
+ * snapshot is what makes a later package downgrade a real rollback instead of
+ * a gamble on an older binary reading a newer-migrated database.
+ */
+export function needsSystemStateSnapshot(posture: DeployPosture): boolean {
+  return posture === 'safe';
+}
+
+/**
+ * Take the system_state snapshot a safe-posture upgrade requires.
+ *
+ * A host with no default backup storage keeps today's behavior (warn and
+ * proceed): refusing every safe upgrade there would break CD for a config
+ * gap, and the module-level backup below still runs when the target manifest
+ * declares on_backup. A configured-but-failing snapshot refuses the upgrade,
+ * same rule `system update` applies to its own snapshot (D7): the DB snapshot
+ * is the safety net, and an upgrade that cannot take it should not mutate.
+ */
+async function snapshotSystemStateBeforeUpgrade(
+  moduleId: string,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    if (!getDefaultBackupStorage()) {
+      log.warn(
+        `${moduleId}: no default backup storage configured — skipping pre-upgrade system_state snapshot`,
+      );
+      return { ok: true };
+    }
+    const snapshot = await createSystemStateBackup();
+    if (!snapshot.success) {
+      return { ok: false, error: snapshot.error ?? 'system_state backup failed' };
+    }
+    log.success(`System state snapshot taken before upgrading ${moduleId}`);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 export interface PollCandidate {
   moduleId: string;
   installed: string;
@@ -168,7 +210,17 @@ async function upgradeOneModule(
   });
   log.info(`Upgrading ${moduleId} ${mod.version} → ${targetVersion} (${posture} — ${reason})`);
 
-  // Safe → back up first, gated on the TARGET manifest's on_backup hook.
+  // Safe → snapshot the celilo DB first (the package rollback pair), then
+  // back up the module itself, gated on the TARGET manifest's on_backup hook.
+  if (needsSystemStateSnapshot(posture)) {
+    const snapshot = await snapshotSystemStateBeforeUpgrade(moduleId);
+    if (!snapshot.ok) {
+      return {
+        success: false,
+        error: `Pre-upgrade system_state snapshot failed for ${moduleId}: ${snapshot.error}`,
+      };
+    }
+  }
   if (needsPreUpgradeBackup(posture, targetManifest)) {
     const backup = await createModuleBackup(moduleId);
     if (!backup.success) {

package/src/cli/commands/module-verify.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { moduleAudit } from './module-audit';
 import { moduleVerify } from './module-verify';
 
@@ -19,7 +20,6 @@ describe('moduleVerify', () => {
 describe('moduleAudit (deprecation alias)', () => {
   let dataDir: string;
   const originalDataDir = process.env.CELILO_DATA_DIR;
-  const originalDbPath = process.env.CELILO_DB_PATH;
 
   beforeEach(() => {
     dataDir = mkdtempSync(join(tmpdir(), 'celilo-audit-alias-'));
@@ -29,10 +29,9 @@ describe('moduleAudit (deprecation alias)', () => {
 
   afterEach(() => {
     rmSync(dataDir, { recursive: true, force: true });
+    resetTestDbPath();
     if (originalDataDir === undefined) process.env.CELILO_DATA_DIR = undefined;
     else process.env.CELILO_DATA_DIR = originalDataDir;
-    if (originalDbPath === undefined) process.env.CELILO_DB_PATH = undefined;
-    else process.env.CELILO_DB_PATH = originalDbPath;
   });
 
   test('writes a deprecation warning to stderr and delegates to verify', async () => {

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

@@ -102,7 +102,6 @@ export async function moduleVerify(
     modified: '✗',
     extra: '!',
     'stale-baseline': '⚠',
-    'stale-generated': '✗',
   };
 
   return {