@celilo/cli 0.26.1 → 1.0.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/cli/commands/module-remove.ts

@@ -14,7 +14,7 @@ import { capabilities as capabilitiesTable, moduleInfrastructure, modules } from
 import { createGaugeLogger } from '../../hooks/logger';
 import { runNamedHook } from '../../hooks/run-named-hook';
 import { deallocateForModule } from '../../ipam/auto-allocator';
-import { ModuleManifestSchema } from '../../manifest/schema';
+import { type ModuleManifest, ModuleManifestSchema } from '../../manifest/schema';
 import { executeBuildWithProgress } from '../../services/build-stream';
 import { askConfirm, withInterviewSession } from '../../services/bus-interview';
 import {
@@ -22,6 +22,7 @@ import {
   emitUninstallFailed,
   emitUninstallStarted,
 } from '../../services/celilo-events';
+import { loadConsumerCleanupPlan, runConsumerCleanup } from '../../services/consumer-cleanup';
 import { getContainerService, getServiceCredentials } from '../../services/container-service';
 import { completeOperation, failOperation, startOperation } from '../../services/module-operations';
 import {
@@ -29,7 +30,6 @@ import {
   describeRemovalRefusal,
   findRemovalBlockers,
 } from '../../services/remove-guard';
-import { cleanupWebRoutesForModule } from '../../services/web-route-cleanup';
 import { getArg, hasFlag, validateRequiredArgs } from '../parser';
 import { log } from '../prompts';
 import type { CommandResult } from '../types';
@@ -243,28 +243,31 @@ async function performModuleRemove(
     }
   }
 
-  // Reclaim public_web routes BEFORE terraform destroy, so the provider host
-  // is still reachable for the /srv/www cleanup. Runs after on_uninstall so a
-  // module that tears its own routes down still wins (this then no-ops).
+  // Tell every provider whose capability this module consumed that it is
+  // leaving, so each withdraws what it minted on its behalf
+  // (openspec/changes/consumer-removal-cleanup). BEFORE terraform destroy, so
+  // provider hosts are still reachable; AFTER on_uninstall, so a module that
+  // tears its own state down first still wins.
   //
-  // Without this, removal deleted the rows via the FK cascade on `modules.id`
-  // and emitted nothing, so the provider kept serving a route for a module that
-  // no longer existed. See services/web-route-cleanup.ts.
-  try {
-    const routeCleanup = await cleanupWebRoutesForModule({ moduleId, db });
-    if (routeCleanup.routesRemoved > 0) {
-      const reclaimed =
-        routeCleanup.assetDirsRemoved.length > 0
-          ? ` and reclaimed ${routeCleanup.assetDirsRemoved.join(', ')}`
-          : '';
-      log.info(`Removed ${routeCleanup.routesRemoved} web route(s) for ${moduleId}${reclaimed}`);
-    }
-    for (const warning of routeCleanup.warnings) {
-      log.warn(warning);
-    }
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    log.warn(`Web route cleanup failed (continuing): ${msg}`);
+  // This replaces the by-name `cleanupWebRoutesForModule` call, which did the
+  // same job for exactly one capability. A failed withdrawal never blocks the
+  // removal — the failing PROVIDER is marked ERROR instead (D6).
+  const cleanupLogger = {
+    info: (m: string) => log.info(m),
+    warn: (m: string) => log.warn(m),
+    error: (m: string) => log.warn(m),
+    success: (m: string) => log.info(m),
+  };
+  const cleanup = await runConsumerCleanup(
+    moduleId,
+    loadConsumerCleanupPlan(moduleId, module.manifestData as ModuleManifest, db),
+    db,
+    cleanupLogger,
+  );
+  if (cleanup.failures.length > 0) {
+    log.warn(
+      `${cleanup.failures.length} provider(s) could not withdraw state for '${moduleId}' and are now marked ERROR: ${cleanup.failures.map((f) => f.providerId).join(', ')}. Removal continues; run \`celilo system audit\` to see what each is holding.`,
+    );
   }
 
   // Check if module has infrastructure that needs to be destroyed

package/src/cli/commands/system-audit.ts

@@ -371,7 +371,11 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
     backups: { modules: installedBackupInfo },
     abandonedOperations: { records: loadAbandonedOperations(db) },
     undeployedModules: {
-      modules: installed.map((m) => ({ id: m.id, state: m.state })),
+      modules: installed.map((m) => ({
+        id: m.id,
+        state: m.state,
+        errorMessage: m.errorMessage,
+      })),
     },
     unconfiguredModules: {
       modules: installed.map((m) => ({

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

@@ -573,7 +573,11 @@ export async function handleSystemUpdate(
     },
     abandonedOperations: { records: loadAbandonedOperations(db) },
     undeployedModules: {
-      modules: installed.map((m) => ({ id: m.id, state: m.state })),
+      modules: installed.map((m) => ({
+        id: m.id,
+        state: m.state,
+        errorMessage: m.errorMessage,
+      })),
     },
     unconfiguredModules: {
       modules: installed.map((m) => ({
@@ -801,7 +805,11 @@ export function rebuildAuditDepsForRerun(
       })),
     },
     undeployedModules: {
-      modules: installed.map((m) => ({ id: m.id, state: m.state })),
+      modules: installed.map((m) => ({
+        id: m.id,
+        state: m.state,
+        errorMessage: m.errorMessage,
+      })),
     },
     unconfiguredModules: {
       modules: installed.map((m) => ({

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'),
   /**
@@ -589,19 +591,34 @@ export const portForwards = sqliteTable(
     /** Dedicated INTERNAL ingress IP (ISS-0156); NULL for the normal public path. */
     ingressIp: text('ingress_ip'),
     description: text('description').notNull().default(''),
+    /**
+     * The CONSUMER that registered it, stamped by the store from the calling
+     * module (openspec/changes/consumer-removal-cleanup, D5a). `''` for rows
+     * written before this column existed — unattributed, so no consumer removal
+     * withdraws them.
+     */
+    registeredBy: text('registered_by').notNull().default(''),
     createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   },
   (table) => ({
-    // One row per (firewall, backend, port, protocol, ingress). The store also
-    // delete-then-inserts on this tuple so a re-expose is an idempotent upsert
-    // (NULL ingress_ip is compared with `is null` there, since SQLite treats
-    // NULLs as distinct in a unique index).
+    // One row per (OWNER, firewall, backend, port, protocol, ingress). The
+    // owner is IN the index, not merely alongside it, and that is the whole
+    // point: without it, consumer B exposing a forward A already has silently
+    // REPLACES A's row, and B leaving then deletes a rule A still needs. Two
+    // owners of one forward are two rows — the set, denormalised into the
+    // table that already exists rather than a second table. `renderRuleset`
+    // dedupes on the rule tuple so the duplicate renders once.
+    //
+    // This is the `dns_registration_consumers` lesson (see below): a single
+    // overwritten owner column is not a label, because what cascades on it
+    // decides when a LIVE record is forgotten.
     forwardUnique: uniqueIndex('port_forwards_unique_idx').on(
       table.firewallIp,
       table.internalIp,
       table.port,
       table.protocol,
       table.ingressIp,
+      table.registeredBy,
     ),
   }),
 );
@@ -630,11 +647,14 @@ export const trustedSources = sqliteTable(
     createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   },
   (table) => ({
-    // One row per (firewall, subnet) — the store delete-then-inserts on this
-    // tuple so re-registering the same subnet is an idempotent upsert.
+    // One row per (OWNER, firewall, subnet) — same reason the owner is in
+    // `port_forwards_unique_idx`. Two modules trusting the same subnet are two
+    // rows, so one leaving does not revoke the other's reach. The renderer
+    // already dedupes trusted subnets (`new Set`), so the pair renders once.
     trustedSourceUnique: uniqueIndex('trusted_sources_unique_idx').on(
       table.firewallIp,
       table.subnet,
+      table.registeredBy,
     ),
   }),
 );