@celilo/cli 1.6.0 → 1.8.0

package/src/capabilities/validation.test.ts

@@ -3,6 +3,20 @@ import { describe, expect, test } from 'bun:test';
 import type { ModuleManifest } from '../manifest/schema';
 import { checkAllowlist, getProviderManifest, validateCapabilityAccess } from './validation';
 
+/**
+ * A consumer's reference to `dns_external`'s restricted `tsig` secret.
+ *
+ * The access gate fires only for a secret the consumer actually names
+ * (celilo#854), so every fixture that expects a REFUSAL has to name one.
+ */
+const TSIG_REFERENCE = {
+  name: 'tsig',
+  type: 'string' as const,
+  required: false,
+  source: 'capability' as const,
+  derive_from: '$capability:dns_external.tsig',
+};
+
 describe('Capability Access Validation', () => {
   describe('checkAllowlist', () => {
     test('should return true when consumer provides capability in allowlist', () => {
@@ -452,7 +466,7 @@ describe('Capability Access Validation', () => {
             },
           ],
         },
-        variables: { owns: [], imports: [] },
+        variables: { owns: [TSIG_REFERENCE], imports: [] },
       };
 
       const providerManifest: ModuleManifest = {
@@ -510,7 +524,7 @@ describe('Capability Access Validation', () => {
           capabilities: [{ name: 'dns_external', version: '1.0.0' }],
         },
         provides: { capabilities: [] }, // No provides section - empty
-        variables: { owns: [], imports: [] },
+        variables: { owns: [TSIG_REFERENCE], imports: [] },
       };
 
       const providerManifest: ModuleManifest = {
@@ -640,4 +654,226 @@ describe('Capability Access Validation', () => {
       expect(callCount).toBe(2); // Should query both capabilities
     });
   });
+
+  // celilo#854 — the gate is scoped to secrets the consumer actually names.
+  //
+  // knot-unbound-internal declares dns_internal's `tsig_key` with
+  // `readable_by: ["dns_internal"]`. Before this was fixed, ANY module listing
+  // dns_internal under `requires.capabilities` and not itself PROVIDING
+  // dns_internal was refused at import over a value it never references.
+  // caddy-internal was the first module to hit it, and it declared the
+  // capability under `optional` to get past the gate — a lie about the
+  // dependency graph that six core services read.
+  describe('celilo#854 — secret access is gated on reference, not on declaration', () => {
+    const knotManifest: ModuleManifest = {
+      celilo_contract: '1.0',
+      id: 'knot-unbound-internal',
+      name: 'Knot + Unbound',
+      version: '1.0.0',
+      description: 'Test',
+      requires: { capabilities: [] },
+      provides: {
+        capabilities: [
+          {
+            name: 'dns_internal',
+            version: '1.0.0',
+            data: {},
+            secrets: [
+              {
+                name: 'tsig_key',
+                type: 'string',
+                readable_by: ['dns_internal'],
+              },
+            ],
+          },
+        ],
+      },
+      variables: { owns: [], imports: [] },
+    };
+
+    const knotDb = {
+      prepare: () => ({
+        get: () => ({ manifest_data: JSON.stringify(knotManifest) }),
+      }),
+    } as unknown as Database;
+
+    test('a consumer that requires the capability but never names the secret imports', async () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'caddy-internal',
+        name: 'Caddy (fleet-only ingress)',
+        version: '1.0.0',
+        description: 'Test',
+        requires: {
+          capabilities: [{ name: 'dns_internal', version: '1.0.0' }],
+        },
+        provides: {
+          capabilities: [{ name: 'private_web', version: '1.0.0', data: {} }],
+        },
+        variables: { owns: [], imports: [] },
+      };
+
+      const result = await validateCapabilityAccess(manifest, knotDb);
+
+      expect(result.success).toBe(true);
+      expect(result.error).toBeUndefined();
+    });
+
+    test('a consumer that DOES name the restricted secret is still refused', async () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'nosy-app',
+        name: 'Nosy App',
+        version: '1.0.0',
+        description: 'Test',
+        requires: {
+          capabilities: [{ name: 'dns_internal', version: '1.0.0' }],
+        },
+        provides: {
+          capabilities: [{ name: 'private_web', version: '1.0.0', data: {} }],
+        },
+        variables: {
+          owns: [
+            {
+              name: 'stolen_key',
+              type: 'string',
+              required: false,
+              source: 'capability',
+              derive_from: '$capability:dns_internal.tsig_key',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const result = await validateCapabilityAccess(manifest, knotDb);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Module 'nosy-app' cannot access secret 'tsig_key'");
+      expect(result.error).toContain("capability 'dns_internal'");
+    });
+
+    /**
+     * The gate is per-SECRET, not per-capability. A provider that declares two
+     * restricted secrets must not put a consumer on the hook for the second
+     * one's allow-list just because it named the first — that would move the
+     * over-refusal from "requires the capability" down one level to "reads any
+     * of its secrets", which is the same conflation wearing a smaller hat.
+     */
+    const twoSecretManifest: ModuleManifest = {
+      ...knotManifest,
+      provides: {
+        capabilities: [
+          {
+            name: 'dns_internal',
+            version: '1.0.0',
+            data: {},
+            secrets: [
+              { name: 'tsig_key', type: 'string', readable_by: ['dns_internal'] },
+              { name: 'api_token', type: 'string', readable_by: ['private_web'] },
+            ],
+          },
+        ],
+      },
+    };
+
+    const twoSecretDb = {
+      prepare: () => ({
+        get: () => ({ manifest_data: JSON.stringify(twoSecretManifest) }),
+      }),
+    } as unknown as Database;
+
+    test('naming one secret enforces that secret allow-list and no other', async () => {
+      function consumer(deriveFrom: string): ModuleManifest {
+        return {
+          celilo_contract: '1.0',
+          id: 'caddy-internal',
+          name: 'Caddy (fleet-only ingress)',
+          version: '1.0.0',
+          description: 'Test',
+          requires: { capabilities: [{ name: 'dns_internal', version: '1.0.0' }] },
+          provides: { capabilities: [{ name: 'private_web', version: '1.0.0', data: {} }] },
+          variables: {
+            owns: [
+              {
+                name: 'borrowed',
+                type: 'string',
+                required: false,
+                source: 'capability',
+                derive_from: deriveFrom,
+              },
+            ],
+            imports: [],
+          },
+        };
+      }
+
+      // `api_token` is readable by `private_web`, which this consumer provides.
+      // The unnamed `tsig_key`, which it does not satisfy, must not interfere.
+      const allowed = await validateCapabilityAccess(
+        consumer('$capability:dns_internal.api_token'),
+        twoSecretDb,
+      );
+      expect(allowed.success).toBe(true);
+
+      // Naming `tsig_key` is still refused, by name.
+      const refused = await validateCapabilityAccess(
+        consumer('$capability:dns_internal.tsig_key'),
+        twoSecretDb,
+      );
+      expect(refused.success).toBe(false);
+      expect(refused.error).toContain('tsig_key');
+    });
+
+    /**
+     * A reference in a TEMPLATE counts too. `resolver.ts` does refuse one at
+     * the point of use, so nothing is unsafe without this, but the refusal
+     * lands at generation rather than at import.
+     *
+     * That gap sits exactly where the repo sends people. CLAUDE.md's module
+     * Definition of Done says "Capability variable usage — Templates use
+     * `$capability:` syntax" and gives a `.tf.tpl` example, so the first author
+     * who follows that instruction with a RESTRICTED secret is the one who
+     * finds out late. No module in the tree references a capability from a
+     * template today, which is why the gap is currently invisible rather than
+     * absent.
+     */
+    test('a secret named only in a template is refused at import', async () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'nosy-app',
+        name: 'Nosy App',
+        version: '1.0.0',
+        description: 'Test',
+        requires: { capabilities: [{ name: 'dns_internal', version: '1.0.0' }] },
+        provides: { capabilities: [{ name: 'private_web', version: '1.0.0', data: {} }] },
+        variables: { owns: [], imports: [] },
+      };
+
+      // The manifest names nothing. Only the .tf.tpl does.
+      const result = await validateCapabilityAccess(manifest, knotDb, ['dns_internal.tsig_key']);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("cannot access secret 'tsig_key'");
+    });
+
+    test('a non-secret template reference is still not a secret reference', async () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'caddy-internal',
+        name: 'Caddy (fleet-only ingress)',
+        version: '1.0.0',
+        description: 'Test',
+        requires: { capabilities: [{ name: 'dns_internal', version: '1.0.0' }] },
+        provides: { capabilities: [{ name: 'private_web', version: '1.0.0', data: {} }] },
+        variables: { owns: [], imports: [] },
+      };
+
+      const result = await validateCapabilityAccess(manifest, knotDb, [
+        'dns_internal.server.ip.primary',
+      ]);
+
+      expect(result.success).toBe(true);
+    });
+  });
 });

package/src/capabilities/validation.ts

@@ -6,6 +6,7 @@
 import type { Database } from 'bun:sqlite';
 import type { ModuleManifest } from '../manifest/schema';
 import { isPrivilegedCapability } from '../manifest/validate';
+import { parseVariables } from '../variables/parser';
 
 export interface ValidationResult {
   success: boolean;
@@ -20,11 +21,16 @@ export interface ValidationResult {
  *
  * @param manifest - Consumer module manifest
  * @param db - Database connection
+ * @param templateReferences - `<capability>.<path>` references found outside
+ *   the manifest, i.e. in the module's templates. Empty is the honest default
+ *   for a caller holding no template context; `module import` passes what the
+ *   template validator already parsed.
  * @returns Validation result
  */
 export async function validateCapabilityAccess(
   manifest: ModuleManifest,
   db: Database,
+  templateReferences: readonly string[] = [],
 ): Promise<ValidationResult> {
   // If module doesn't require capabilities, validation passes
   if (!manifest.requires?.capabilities || manifest.requires.capabilities.length === 0) {
@@ -34,6 +40,8 @@ export async function validateCapabilityAccess(
   // Get list of capabilities this module provides
   const consumerCapabilities = (manifest.provides?.capabilities || []).map((cap) => cap.name);
 
+  const references = collectCapabilityReferences(manifest, templateReferences);
+
   // Check each required capability
   for (const requiredCapability of manifest.requires.capabilities) {
     // Framework-granted privileges (e.g. cross_module_read) are not
@@ -63,8 +71,12 @@ export async function validateCapabilityAccess(
       continue;
     }
 
-    // Check allowlist for each secret
+    // Check allowlist for each secret the consumer actually names (celilo#854).
     for (const secret of capabilityDef.secrets) {
+      if (!referencesSecret(references, requiredCapability.name, secret.name)) {
+        continue;
+      }
+
       if (secret.readable_by && secret.readable_by.length > 0) {
         // Check if consumer provides any capability in the allowlist
         const hasAccess = checkAllowlist(consumerCapabilities, secret.readable_by);
@@ -89,6 +101,60 @@ export async function validateCapabilityAccess(
   return { success: true };
 }
 
+/**
+ * Every `$capability:<name>.<path>` reference the consumer's manifest makes.
+ *
+ * Policy function (Rule 10.1) - parses only, no I/O.
+ *
+ * Serializing the manifest and parsing the result finds a reference wherever it
+ * lives — a `variables.owns[].derive_from`, a default, a capability data block —
+ * without this having to track which fields may hold one.
+ *
+ * Template references are included too, supplied by the caller. `resolver.ts`
+ * does refuse a template reference at the point of use, so nothing is unsafe
+ * without them, but the refusal lands at generation rather than at import. That
+ * matters because a module's TEMPLATES are where this repo tells authors to put
+ * these: the Definition of Done in CLAUDE.md says "Capability variable usage —
+ * Templates use `$capability:` syntax" and gives a `.tf.tpl` example. A gate
+ * that does not fire where the documentation sends people is a gate with a hole
+ * in the shape of the instructions.
+ */
+function collectCapabilityReferences(
+  manifest: ModuleManifest,
+  templateReferences: readonly string[] = [],
+): Set<string> {
+  return new Set([
+    ...parseVariables(JSON.stringify(manifest))
+      .filter((variable) => variable.type === 'capability')
+      .map((variable) => variable.path),
+    ...templateReferences,
+  ]);
+}
+
+/**
+ * Does the consumer name this capability secret?
+ *
+ * Policy function (Rule 10.1) - pure logic, no I/O.
+ *
+ * A reference of `dns_internal.tsig_key` names the `tsig_key` secret, and so
+ * does `dns_internal.tsig_key.value` if the secret ever holds a structure.
+ * Requiring the capability alone names nothing (celilo#854): a module refused
+ * over a secret it never reads has to lie about its dependency graph to deploy.
+ */
+function referencesSecret(
+  references: Set<string>,
+  capabilityName: string,
+  secretName: string,
+): boolean {
+  const base = `${capabilityName}.${secretName}`;
+  for (const reference of references) {
+    if (reference === base || reference.startsWith(`${base}.`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Check if consumer capabilities match provider allowlist
  *

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

@@ -89,6 +89,12 @@ export async function handleAlertsSweep(): Promise<CommandResult> {
   if (report.deferredDelivered > 0) parts.push(`${report.deferredDelivered} deferred-delivered`);
   if (report.failed > 0) parts.push(`${report.failed} FAILED`);
   if (report.noPolicy.length > 0) parts.push(`${report.noPolicy.length} no-policy`);
+  // A monitor whose module is gone is dropped here rather than left to sit
+  // unschedulable forever (celilo#1029).
+  if (report.strandedDropped.length > 0) {
+    const names = report.strandedDropped.map((d) => d.moduleId).join(', ');
+    parts.push(`${report.strandedDropped.length} stranded-dropped (${names})`);
+  }
 
   const lines = [`alert sweep: ${parts.join(', ')}`];
 
@@ -109,6 +115,18 @@ export async function handleAlertsSweep(): Promise<CommandResult> {
       lines.push(`    ${alertKey}  (${reason})`);
     }
   }
+  // A dropped monitor's alerts are deleted with it, not resolved — nothing else
+  // anywhere records that they existed. Name each one and what it said: the
+  // failure it was reporting is real and is now unwatched, which is the fact an
+  // operator has to act on and the one a module name alone does not carry.
+  for (const { moduleId, alerts: dropped } of report.strandedDropped) {
+    if (dropped.length === 0) continue;
+    lines.push(`  ${moduleId} is gone; its monitor was holding ${dropped.length} live alert(s):`);
+    for (const alert of dropped) {
+      lines.push(`    ${alert.key}: ${alert.message}`);
+    }
+    lines.push(`    nothing checks ${moduleId} any more, so these will not be reported again.`);
+  }
   // 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
   // anywhere — nothing ever reaches the transport's own logs.

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

@@ -15,6 +15,7 @@ import { createGaugeLogger } from '../../hooks/logger';
 import { runNamedHook } from '../../hooks/run-named-hook';
 import { deallocateForModule } from '../../ipam/auto-allocator';
 import { type ModuleManifest, ModuleManifestSchema } from '../../manifest/schema';
+import { deleteMonitorForModule } from '../../services/alerting/monitors';
 import { executeBuildWithProgress } from '../../services/build-stream';
 import { askConfirm, withInterviewSession } from '../../services/bus-interview';
 import {
@@ -22,7 +23,11 @@ import {
   emitUninstallFailed,
   emitUninstallStarted,
 } from '../../services/celilo-events';
-import { loadConsumerCleanupPlan, runConsumerCleanup } from '../../services/consumer-cleanup';
+import {
+  PRE_DEPLOY_STATES,
+  loadConsumerCleanupPlan,
+  runConsumerCleanup,
+} from '../../services/consumer-cleanup';
 import { getContainerService, getServiceCredentials } from '../../services/container-service';
 import { completeOperation, failOperation, startOperation } from '../../services/module-operations';
 import {
@@ -97,7 +102,7 @@ export async function handleModuleRemove(
         id: m.id,
         manifest: parsed.data,
         paused: m.state === 'PAUSED',
-        deployed: !(['IMPORTED', 'VALIDATED', 'CONFIGURED'] as string[]).includes(m.state),
+        deployed: !PRE_DEPLOY_STATES.has(m.state),
       });
     }
 
@@ -403,6 +408,33 @@ async function performModuleRemove(
     log.warn(`Failed to unregister event-bus subscriptions: ${msg}`);
   }
 
+  // Drop the module's health monitor. No cascade can reach it — `monitors.target`
+  // holds a module id or an audit check name depending on `kind`, so the column
+  // carries no foreign key (celilo#1029). Left behind, the monitor fires
+  // `Module not found` and then becomes permanently unschedulable, because its
+  // cadence resolves from a module row that no longer exists — so nothing ever
+  // runs it again to resolve the alert it just raised.
+  //
+  // What it was holding is named, not just counted. The alerts are deleted with
+  // it (cascade), so a firing check goes silent and the coverage of it goes at
+  // the same moment — an operator who is told only `removed monitor` never
+  // learns which real failure just stopped being reported.
+  try {
+    const droppedAlerts = deleteMonitorForModule(db, moduleId);
+    if (droppedAlerts) {
+      log.info(`Removed health monitor for ${moduleId}`);
+      for (const alert of droppedAlerts) {
+        log.warn(`  dropped live alert ${alert.key}: ${alert.message}`);
+      }
+      if (droppedAlerts.length > 0) {
+        log.warn(`  nothing checks ${moduleId} any more, so this will not be reported again.`);
+      }
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    log.warn(`Failed to remove health monitor for ${moduleId}: ${msg}`);
+  }
+
   // Delete module (cascade will remove configs, secrets, capabilities, infrastructure records)
   db.delete(modules).where(eq(modules.id, moduleId)).run();
 

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

@@ -5,12 +5,21 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, relative } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { type DbClient, getDb } from '../../db/client';
-import { modules } from '../../db/schema';
+import { moduleIntegrity, modules } from '../../db/schema';
 import { classifyVersionChange, handleModuleUpdate, updateOne } from './module-update';
 
 describe('classifyVersionChange', () => {
@@ -409,3 +418,141 @@ description: fixture
     expect(snapshot(installedDir)).toEqual(before);
   });
 });
+
+/**
+ * celilo#1008. `updateOne` copied the new tree onto the installed one in
+ * place, so a copy that died partway left a module half old and half new,
+ * with no record anywhere of which files were which. Jeremy Banka's
+ * `f9a57f1b` staged into a sibling and swapped with two renames; the rest of
+ * that commit is superseded by celilo#925, but the atomicity is not, and this
+ * is where it lands.
+ *
+ * The failure is provoked rather than injected, so nothing test-only reaches
+ * production code. The source carries a FIFO, which `cpSync` refuses with
+ * ENOTSUP — a stand-in for any mid-copy failure a real update can hit (a full
+ * disk, a permission, an I/O error). It is chosen because it fails on the
+ * SOURCE, so it fires whether the copy targets the live install or a staging
+ * directory, which a destination-side collision would not. `z-` sorts last,
+ * so the entries ahead of it copy successfully first — precisely the
+ * half-applied state being ruled out.
+ */
+describe('updateOne — an update that fails partway leaves the install untouched', () => {
+  let tempDir: string;
+  let srcDir: string;
+  let installedDir: string;
+  let db: DbClient;
+
+  /** Every file under `root`, relative path → bytes, for an exact comparison. */
+  function snapshotTree(root: string, dir = root): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) Object.assign(out, snapshotTree(root, full));
+      else out[relative(root, full)] = readFileSync(full, 'utf-8');
+    }
+    return out;
+  }
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-atomic-'));
+    process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
+    process.env.CELILO_ORIGINAL_CWD = tempDir;
+
+    installedDir = join(tempDir, 'installed', 'testmod');
+    mkdirSync(join(installedDir, 'scripts'), { recursive: true });
+    mkdirSync(join(installedDir, 'generated'), { recursive: true });
+    writeFileSync(
+      join(installedDir, 'manifest.yml'),
+      'celilo_contract: "1.0"\nid: testmod\nname: Test Module\nversion: 1.0.0\ndescription: fixture\n',
+    );
+    writeFileSync(join(installedDir, 'scripts', 'on_install.ts'), 'export const OLD = 1;\n');
+    // `derived` — celilo's own output, must survive an update either way.
+    writeFileSync(join(installedDir, 'generated', 'terraform.tfstate'), '{"old":true}\n');
+
+    srcDir = join(tempDir, 'src');
+    mkdirSync(join(srcDir, 'scripts'), { recursive: true });
+    writeFileSync(
+      join(srcDir, 'manifest.yml'),
+      'celilo_contract: "1.0"\nid: testmod\nname: Test Module\nversion: 2.0.0\ndescription: fixture\n',
+    );
+    writeFileSync(join(srcDir, 'scripts', 'on_install.ts'), 'export const NEW = 2;\n');
+    // cpSync refuses a FIFO with ENOTSUP. Sorts last, so the real files copy first.
+    execFileSync('mkfifo', [join(srcDir, 'z-boom')]);
+
+    db = getDb();
+    db.insert(modules)
+      .values({
+        id: 'testmod',
+        name: 'Test Module',
+        sourcePath: installedDir,
+        version: '1.0.0',
+        manifestData: {
+          celilo_contract: '1.0',
+          id: 'testmod',
+          name: 'Test Module',
+          version: '1.0.0',
+        },
+      })
+      .run();
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+    process.env.CELILO_DB_PATH = undefined;
+    process.env.CELILO_ORIGINAL_CWD = undefined;
+  });
+
+  test('a failed update leaves the installed tree byte-identical', async () => {
+    const before = snapshotTree(installedDir);
+    expect(before['scripts/on_install.ts']).toBe('export const OLD = 1;\n');
+
+    await expect(updateOne(srcDir, db, {}, { quiet: true })).rejects.toThrow();
+
+    expect(snapshotTree(installedDir)).toEqual(before);
+  });
+
+  test('a successful update keeps celilo output and drops what the version removed', async () => {
+    // Same fixture minus the FIFO, so the update runs to completion.
+    rmSync(join(srcDir, 'z-boom'));
+    // A file the previous version shipped and the new one does not.
+    writeFileSync(join(installedDir, 'scripts', 'gone_in_2.ts'), 'export const OLD = 1;\n');
+
+    const result = await updateOne(srcDir, db, {}, { quiet: true });
+    expect(result.status).toBe('success');
+
+    // `derived`: celilo's own output survives (task 11.6).
+    expect(readFileSync(join(installedDir, 'generated', 'terraform.tfstate'), 'utf-8')).toBe(
+      '{"old":true}\n',
+    );
+    // `package`: the new version's content landed...
+    expect(readFileSync(join(installedDir, 'scripts', 'on_install.ts'), 'utf-8')).toBe(
+      'export const NEW = 2;\n',
+    );
+    // ...and what it dropped is gone, pruned in staging rather than in place.
+    expect(existsSync(join(installedDir, 'scripts', 'gone_in_2.ts'))).toBe(false);
+    // No staging debris on the success path either.
+    expect(readdirSync(join(tempDir, 'installed'))).toEqual(['testmod']);
+  });
+
+  test('a failed update leaves no staging directory behind', async () => {
+    await expect(updateOne(srcDir, db, {}, { quiet: true })).rejects.toThrow();
+
+    const siblings = readdirSync(join(tempDir, 'installed'));
+    expect(siblings).toEqual(['testmod']);
+  });
+
+  test('a failed update does not advance the integrity baseline', async () => {
+    await expect(updateOne(srcDir, db, {}, { quiet: true })).rejects.toThrow();
+
+    const row = db
+      .select()
+      .from(moduleIntegrity)
+      .where(eq(moduleIntegrity.moduleId, 'testmod'))
+      .get();
+    // Nothing recorded at all: the update never reached a state worth claiming.
+    expect(row).toBeUndefined();
+    // And the module row still names the version actually on disk.
+    const mod = db.select().from(modules).where(eq(modules.id, 'testmod')).get();
+    expect(mod?.version).toBe('1.0.0');
+  });
+});