@celilo/cli 0.27.0 → 1.0.0

package/src/services/consumer-cleanup.ts

@@ -0,0 +1,244 @@
+/**
+ * Telling every provider that one of its consumers is leaving
+ * (openspec/changes/consumer-removal-cleanup).
+ *
+ * A capability is two-sided. The consumer asks, the provider mints something in
+ * its own world — a site block in caddy's Caddyfile, a DNAT rule in a ruleset,
+ * an OIDC client at authentik — and removal only ever touched one side of it.
+ * The FK cascade made that worse rather than better: the registry row
+ * disappeared, so the provider's next converge had no way to learn the thing
+ * had ever existed. The registry went quiet and the machine kept serving.
+ *
+ * This is the generic path that replaces `web-route-cleanup.ts`, which did the
+ * same job for exactly one capability, called by name from core.
+ *
+ * Split plan/execute (Rule 10.4) because the interesting decisions — which
+ * providers, which are skipped and why — are pure, and the part that isn't is
+ * just "run each hook and record what happened".
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { capabilities, modules } from '../db/schema';
+import { type RunNamedHookResult, runNamedHook } from '../hooks/run-named-hook';
+import type { HookLogger } from '../hooks/types';
+import type { ModuleManifest } from '../manifest/schema';
+import { deletePortForwardsForModule } from './port-forwards';
+import { deleteTrustedSourcesForModule } from './trusted-sources';
+
+/**
+ * States in which a module has never resolved a capability and therefore holds
+ * nothing minted on anyone's behalf. Capabilities are registered at IMPORT, not
+ * deploy, so the `capabilities` table routinely names providers that were never
+ * deployed. The same predicate `remove-guard.ts` uses to decide a module is not
+ * a dependent — the guard and the cleanup must keep ONE definition of a live
+ * provider (D8).
+ */
+const PRE_DEPLOY_STATES = new Set(['IMPORTED', 'VALIDATED', 'CONFIGURED']);
+
+export type CleanupSkipReason = 'paused' | 'not-deployed';
+
+export interface CleanupTarget {
+  /** The provider module to notify. */
+  providerId: string;
+  /** Which of its capabilities the departing consumer used — for the log line. */
+  capabilityNames: string[];
+  /** Set when the provider will NOT be notified. */
+  skip?: CleanupSkipReason;
+}
+
+export interface ProviderRow {
+  moduleId: string;
+  capabilityName: string;
+}
+
+export interface ProviderState {
+  moduleId: string;
+  state: string;
+}
+
+/**
+ * Which providers must be told that `consumer` is going away.
+ *
+ * Pure. Sorted by provider id so dispatch order is deterministic and a failure
+ * is reproducible.
+ *
+ * ONE ENTRY PER PROVIDER, not per capability (D1): a provider can hold two
+ * capabilities the same consumer used, and dispatching per capability would run
+ * the same withdrawal twice. But MANY providers per capability (D3) —
+ * `capabilities` has no uniqueness on the name, and `firewall` deliberately has
+ * several rows (an edge provider plus inner layers). Every one is told.
+ *
+ * The provider is never its own consumer: a module that both provides and
+ * requires a capability would otherwise be asked to withdraw its own state as
+ * it is being removed, which its `on_uninstall` already owns.
+ */
+export function planConsumerCleanup(
+  consumer: string,
+  manifest: ModuleManifest,
+  providerRows: ProviderRow[],
+  providerStates: ProviderState[],
+): CleanupTarget[] {
+  // `requires` AND `optional` — the same set `remove-guard.ts` counts as a
+  // dependency edge. A capability consumed optionally still minted state.
+  const consumed = new Set([
+    ...(manifest.requires?.capabilities ?? []).map((c) => c.name),
+    ...(manifest.optional?.capabilities ?? []).map((c) => c.name),
+  ]);
+  if (consumed.size === 0) return [];
+
+  const stateOf = new Map(providerStates.map((s) => [s.moduleId, s.state]));
+  const byProvider = new Map<string, Set<string>>();
+
+  for (const row of providerRows) {
+    if (!consumed.has(row.capabilityName)) continue;
+    if (row.moduleId === consumer) continue;
+    const names = byProvider.get(row.moduleId) ?? new Set<string>();
+    names.add(row.capabilityName);
+    byProvider.set(row.moduleId, names);
+  }
+
+  return [...byProvider.entries()]
+    .map(([providerId, names]): CleanupTarget => {
+      const state = stateOf.get(providerId);
+      const capabilityNames = [...names].sort();
+      if (state === 'PAUSED') return { providerId, capabilityNames, skip: 'paused' };
+      if (state === undefined || PRE_DEPLOY_STATES.has(state)) {
+        return { providerId, capabilityNames, skip: 'not-deployed' };
+      }
+      return { providerId, capabilityNames };
+    })
+    .sort((a, b) => a.providerId.localeCompare(b.providerId));
+}
+
+/** Read the plan's inputs out of the DB. */
+export function loadConsumerCleanupPlan(
+  consumer: string,
+  manifest: ModuleManifest,
+  db: DbClient,
+): CleanupTarget[] {
+  const providerRows = db
+    .select({ moduleId: capabilities.moduleId, capabilityName: capabilities.capabilityName })
+    .from(capabilities)
+    .all();
+  const providerStates = db
+    .select({ moduleId: modules.id, state: modules.state })
+    .from(modules)
+    .all();
+  return planConsumerCleanup(consumer, manifest, providerRows, providerStates);
+}
+
+export interface CleanupFailure {
+  providerId: string;
+  error: string;
+}
+
+export interface ConsumerCleanupResult {
+  notified: string[];
+  skipped: Array<{ providerId: string; reason: CleanupSkipReason }>;
+  failures: CleanupFailure[];
+}
+
+/**
+ * Run the plan. Sequential, deterministic, and it CONTINUES PAST A FAILURE
+ * (D13) — every provider is told even if an earlier one threw. Stopping early
+ * would leave MORE providers holding state for a module that is about to
+ * disappear, which is the failure this exists to fix.
+ *
+ * A failed withdrawal NEVER blocks the removal (D6). The record is an ERRORed
+ * PROVIDER, not a refused removal: the hook is a full converge, so a failure
+ * does not mean "it failed to forget one thing" — the provider may have
+ * re-rendered its state without the departing consumer AND without everything
+ * else. ERROR is the honest label for a provider whose state is now unknown,
+ * and `audit/undeployed-modules.ts` already turns it into a `blocked` finding.
+ * Nothing refuses to USE an ERRORed module, so the provider keeps serving while
+ * carrying the flag.
+ */
+export async function runConsumerCleanup(
+  consumer: string,
+  plan: CleanupTarget[],
+  db: DbClient,
+  logger: HookLogger,
+  /** Injectable hook runner — tests drive the failure and paused paths through it. */
+  runHook: (providerId: string) => Promise<RunNamedHookResult> = (providerId) =>
+    runNamedHook(providerId, 'on_consumer_removed', db, logger, { inputs: { consumer } }),
+): Promise<ConsumerCleanupResult> {
+  const result: ConsumerCleanupResult = { notified: [], skipped: [], failures: [] };
+
+  for (const target of plan) {
+    if (target.skip) {
+      result.skipped.push({ providerId: target.providerId, reason: target.skip });
+      // Reported, not silent (D7/D8). Nothing was attempted, so nothing is
+      // unknown and the provider is NOT marked ERROR.
+      if (target.skip === 'paused') {
+        logger.warn(
+          `${target.providerId} is paused, so it was not told that '${consumer}' is gone — it is still holding whatever it minted for it (${target.capabilityNames.join(', ')}). Unpause and redeploy it to reconcile.`,
+        );
+      }
+      continue;
+    }
+
+    const hookResult = await runHook(target.providerId);
+
+    // A module paused BETWEEN the plan and this dispatch. `runNamedHook` reports
+    // that as success, so taking it at face value would log a withdrawal that
+    // did not happen — which is the silence this whole change exists to end.
+    // The window is small (one CLI process) and the consequence of trusting it
+    // is not, so it is read rather than assumed.
+    if (hookResult.skippedPaused) {
+      result.skipped.push({ providerId: target.providerId, reason: 'paused' });
+      logger.warn(
+        `${target.providerId} was paused while '${consumer}' was being removed, so it was not told — it is still holding whatever it minted for it (${target.capabilityNames.join(', ')}). Unpause and redeploy it to reconcile.`,
+      );
+      continue;
+    }
+
+    if (hookResult.success) {
+      // `notDefined` means the provider declares no such hook — it mints
+      // nothing per consumer, and the dispatch succeeding is the right answer.
+      if (!hookResult.notDefined) {
+        result.notified.push(target.providerId);
+        logger.info(`${target.providerId} withdrew what it held for '${consumer}'`);
+      }
+      continue;
+    }
+
+    const error = hookResult.error ?? 'unknown error';
+    result.failures.push({ providerId: target.providerId, error });
+    markProviderErrored(target.providerId, consumer, error, db);
+    logger.warn(
+      `${target.providerId} failed to withdraw what it held for '${consumer}' and is now marked ERROR: ${error}`,
+    );
+  }
+
+  // The rows, once every provider has converged without them (D4). `web_routes`
+  // dies with the `modules` row via its FK cascade; these two carry a plain
+  // `registered_by` text column and do not.
+  deletePortForwardsForModule(db, consumer);
+  deleteTrustedSourcesForModule(db, consumer);
+
+  return result;
+}
+
+/**
+ * Mark the PROVIDER — not the module being removed — as ERROR, naming the
+ * departing consumer and the raw hook error.
+ *
+ * The consumer is in `errorMessage` because the audit finding is read long
+ * after the removal, by someone with no reason to connect the two.
+ */
+function markProviderErrored(
+  providerId: string,
+  consumer: string,
+  error: string,
+  db: DbClient,
+): void {
+  db.update(modules)
+    .set({
+      state: 'ERROR',
+      errorMessage: `Failed to withdraw state held for removed consumer '${consumer}': ${error}`,
+      updatedAt: new Date(),
+    })
+    .where(eq(modules.id, providerId))
+    .run();
+}

package/src/services/module-validator/index.test.ts

@@ -15,6 +15,15 @@ const REPO_ROOT = resolve(__dirname, '../../../../..');
 const CADDY_MODULE_PATH = resolve(REPO_ROOT, 'modules/caddy');
 
 describe('runChecks (orchestrator)', () => {
+  // celilo#804: this test timed out at 60000ms on a docs-only CI run yet
+  // measures ~500ms end-to-end locally (all 3 tests in this file, combined).
+  // The work here is a handful of synchronous `git`/`spawnSync` calls
+  // (checkGitHygiene) with nothing to cut without dropping the git_hygiene
+  // check this test exists to exercise — so this was a saturated CI runner
+  // stalling those spawns, not this suite sitting close to its budget.
+  // Raising the timeout further wouldn't shrink that margin (a real stall
+  // would blow through any budget); left at the file's default (60000ms,
+  // ~100x the measured runtime) rather than bumped without evidence it helps.
   test('healthy in-tree module produces all-ok report', async () => {
     const checks = await runChecks(CADDY_MODULE_PATH, {
       noBuild: true,

package/src/services/port-forwards.test.ts

@@ -3,11 +3,14 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { PortForwardStore } from '@celilo/capabilities';
+import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
+import { portForwards } from '../db/schema';
 import { setupTestDatabase } from '../test-utils/setup-test-db';
-import { buildPortForwardStore } from './port-forwards';
+import { buildPortForwardStore, deletePortForwardsForModule } from './port-forwards';
 
 const FW = '192.168.0.254';
+const CADDY = { internalIp: '10.0.20.5', protocol: 'TCP' as const, description: 'caddy' };
 
 describe('port-forward store', () => {
   let dir: string;
@@ -19,7 +22,7 @@ describe('port-forward store', () => {
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
     db = await setupTestDatabase(dbPath);
-    store = buildPortForwardStore(db);
+    store = buildPortForwardStore(db, 'caddy');
   });
   afterEach(() => {
     db.$client.close();
@@ -31,62 +34,112 @@ describe('port-forward store', () => {
     }
   });
 
-  it('adds and lists forwards for a firewall', () => {
-    store.add(FW, { internalIp: '10.0.20.5', port: 443, protocol: 'TCP', description: 'caddy' });
-    store.add(FW, {
-      internalIp: '10.0.20.42',
-      port: 2222,
-      protocol: 'TCP',
-      description: 'forgejo',
-    });
+  it('declares and lists forwards for a firewall', () => {
+    store.replace(FW, CADDY, [80, 443]);
     const forwards = store.list(FW);
     expect(forwards).toHaveLength(2);
-    expect(forwards.map((f) => f.port).sort((a, b) => a - b)).toEqual([443, 2222]);
+    expect(forwards.map((f) => f.port).sort((a, b) => a - b)).toEqual([80, 443]);
   });
 
-  it('add is an idempotent upsert — same tuple → one row, description updated', () => {
-    store.add(FW, { internalIp: '10.0.20.5', port: 443, protocol: 'TCP', description: 'v1' });
-    store.add(FW, { internalIp: '10.0.20.5', port: 443, protocol: 'TCP', description: 'v2' });
+  it('stamps registeredBy from the bound consumer, and no caller can supply it', () => {
+    store.replace(FW, CADDY, [443]);
+    expect(store.list(FW)[0].registeredBy).toBe('caddy');
+    // The write takes only (firewall, target, ports) — there is no parameter an
+    // owner could be passed through, which is the point rather than an omission.
+    expect(store.replace.length).toBe(3);
+  });
+
+  it('replace is idempotent — same declaration twice → one row per port', () => {
+    store.replace(FW, { ...CADDY, description: 'v1' }, [443]);
+    store.replace(FW, { ...CADDY, description: 'v2' }, [443]);
     const forwards = store.list(FW);
     expect(forwards).toHaveLength(1);
     expect(forwards[0].description).toBe('v2');
   });
 
   it('scopes forwards by firewallIp', () => {
-    store.add(FW, { internalIp: '10.0.20.5', port: 443, protocol: 'TCP', description: 'a' });
-    store.add('10.0.30.254', {
-      internalIp: '10.0.30.5',
-      port: 53,
-      protocol: 'UDP',
-      description: 'b',
-    });
+    store.replace(FW, CADDY, [443]);
+    store.replace(
+      '10.0.30.254',
+      { internalIp: '10.0.30.5', protocol: 'UDP', description: 'b' },
+      [53],
+    );
     expect(store.list(FW)).toHaveLength(1);
     expect(store.list('10.0.30.254')).toHaveLength(1);
   });
 
-  it('remove deletes exactly the tuple and leaves others', () => {
-    store.add(FW, { internalIp: '10.0.20.5', port: 443, protocol: 'TCP', description: 'x' });
-    store.add(FW, { internalIp: '10.0.20.5', port: 80, protocol: 'TCP', description: 'y' });
-    store.remove(FW, '10.0.20.5', 443, 'TCP');
-    const forwards = store.list(FW);
-    expect(forwards).toHaveLength(1);
-    expect(forwards[0].port).toBe(80);
-  });
-
   it('ingressIp forwards are distinct from the public (NULL) ones', () => {
-    store.add(FW, { internalIp: '10.0.20.5', port: 53, protocol: 'UDP', description: 'public' });
-    store.add(FW, {
-      internalIp: '10.0.20.5',
-      port: 53,
-      protocol: 'UDP',
-      ingressIp: '10.0.10.53',
-      description: 'ingress',
-    });
+    const target = { internalIp: '10.0.20.5', protocol: 'UDP' as const, description: 'dns' };
+    store.replace(FW, target, [53]);
+    store.replace(FW, { ...target, ingressIp: '10.0.10.53' }, [53]);
     expect(store.list(FW)).toHaveLength(2);
-    // removing the public (NULL-ingress) one leaves the ingress one intact
-    store.remove(FW, '10.0.20.5', 53, 'UDP');
+    // Re-declaring the public (NULL-ingress) set as empty leaves the ingress one.
+    store.replace(FW, target, []);
     const forwards = store.list(FW);
     expect(forwards).toHaveLength(1);
     expect(forwards[0].ingressIp).toBe('10.0.10.53');
   });
+
+  // D5b / celilo#855. Before this, `exposeService` upserted per port and nothing
+  // ever removed a forward a consumer stopped wanting: a module that exposed
+  // :8080 and redeployed exposing :9090 kept both, forever.
+  it('re-declaring with a shorter port list drops the ports left out', () => {
+    store.replace(FW, CADDY, [80, 443, 8080]);
+    store.replace(FW, CADDY, [80, 443]);
+    expect(
+      store
+        .list(FW)
+        .map((f) => f.port)
+        .sort((a, b) => a - b),
+    ).toEqual([80, 443]);
+  });
+
+  it('a consumer narrowing its declaration withdraws no other module rows', () => {
+    const forgejo = buildPortForwardStore(db, 'forgejo');
+    store.replace(FW, CADDY, [80, 443]);
+    forgejo.replace(FW, { internalIp: '10.0.20.42', protocol: 'TCP', description: 'git' }, [2222]);
+
+    store.replace(FW, CADDY, [443]);
+
+    expect(store.list(FW).filter((f) => f.registeredBy === 'forgejo')).toHaveLength(1);
+  });
+
+  // D5a, the refcount case — the bug most likely to ship silently. The owner is
+  // IN the unique index, so two consumers of the same forward are two rows and
+  // one leaving does not delete a rule the other still needs.
+  it('two consumers of the SAME forward are two rows, and one leaving leaves the other', () => {
+    const other = buildPortForwardStore(db, 'greenwave-app');
+    store.replace(FW, CADDY, [443]);
+    other.replace(FW, { ...CADDY, description: 'also 443' }, [443]);
+    expect(store.list(FW)).toHaveLength(2);
+
+    deletePortForwardsForModule(db, 'caddy');
+
+    const left = store.list(FW);
+    expect(left).toHaveLength(1);
+    expect(left[0].registeredBy).toBe('greenwave-app');
+    expect(left[0].port).toBe(443);
+  });
+
+  // Migration 0025 leaves pre-existing rows with an empty owner so the fleet
+  // keeps serving. They are adopted the first time their owner re-declares the
+  // same target, which is the only moment we can safely say who owns them.
+  it('adopts an unattributed legacy row when its owner re-declares the target', () => {
+    db.insert(portForwards)
+      .values({
+        firewallIp: FW,
+        internalIp: CADDY.internalIp,
+        port: 443,
+        protocol: 'TCP',
+        description: 'legacy',
+        registeredBy: '',
+      })
+      .run();
+
+    store.replace(FW, CADDY, [443]);
+
+    const rows = db.select().from(portForwards).where(eq(portForwards.firewallIp, FW)).all();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].registeredBy).toBe('caddy');
+  });
 });

package/src/services/port-forwards.ts

@@ -2,15 +2,20 @@
  * Port-forward registry — the DB-backed `PortForwardStore` (openspec/changes/unified-management-no-ssh/proposal.md).
  *
  * The shared-core desired-state store for the `firewall` capability. The
- * capability-loader constructs one of these and injects it into the firewall
- * provider factory, so `exposeService`/`unexposeService` become register/
- * unregister and the provider's converge renders the complete ruleset from
- * `list(firewallIp)` and applies it atomically (`iptables-restore`). Replaces
- * "read the box back with `iptables -L`" as the source of truth.
+ * capability-loader constructs one of these bound to the CONSUMING module and
+ * injects it into the firewall provider factory, so `exposeService` becomes a
+ * declaration of that consumer's complete port set and the provider's converge
+ * renders the whole ruleset from `list(firewallIp)`, applying it atomically
+ * (`iptables-restore`). Replaces "read the box back with `iptables -L`" as the
+ * source of truth.
+ *
+ * `registeredBy` is stamped HERE, never accepted from a caller — the same rule
+ * `buildTrustedSourceStore` follows, so a forward cannot be attributed to the
+ * wrong module (openspec/changes/consumer-removal-cleanup, D2).
  */
 
-import type { PortForward, PortForwardStore, Protocol } from '@celilo/capabilities';
-import { and, eq, isNull } from 'drizzle-orm';
+import type { PortForward, PortForwardStore, PortForwardTarget } from '@celilo/capabilities';
+import { and, eq, isNull, or } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { portForwards } from '../db/schema';
 
@@ -19,7 +24,37 @@ function ingressMatch(ingressIp: string | undefined) {
   return ingressIp ? eq(portForwards.ingressIp, ingressIp) : isNull(portForwards.ingressIp);
 }
 
-export function buildPortForwardStore(db: DbClient): PortForwardStore {
+/**
+ * Every row this consumer owns for one target, plus the UNATTRIBUTED rows for
+ * the same target.
+ *
+ * The unattributed half is the migration's other end: rows written before
+ * `registered_by` existed carry `''`, and a consumer re-declaring the target
+ * they describe is the one moment we can safely say who owns them — one module
+ * owns a backend IP. Without this they would render forever with no owner to
+ * withdraw them.
+ */
+function ownedOrUnattributed(firewallIp: string, target: PortForwardTarget, consumer: string) {
+  return and(
+    eq(portForwards.firewallIp, firewallIp),
+    eq(portForwards.internalIp, target.internalIp),
+    eq(portForwards.protocol, target.protocol),
+    ingressMatch(target.ingressIp),
+    or(eq(portForwards.registeredBy, consumer), eq(portForwards.registeredBy, '')),
+  );
+}
+
+/**
+ * Build the store bound to the module that will call through the capability.
+ *
+ * ponytail: a consumer that stops exposing a target ENTIRELY — its backend IP
+ * changes, or it drops a host — leaves rows for the old target, because no call
+ * arrives to declare that target's set empty. Bounded: the rows die when the
+ * module is removed, and a redeploy onto a new host is the only way to reach
+ * it. Closing it needs a sweep against `getModuleSystems`, which is not
+ * obviously worth its own failure mode.
+ */
+export function buildPortForwardStore(db: DbClient, registeredBy: string): PortForwardStore {
   return {
     list(firewallIp: string): PortForward[] {
       return db
@@ -33,54 +68,45 @@ export function buildPortForwardStore(db: DbClient): PortForwardStore {
           protocol: r.protocol,
           ingressIp: r.ingressIp ?? undefined,
           description: r.description,
+          registeredBy: r.registeredBy,
         }));
     },
 
-    add(firewallIp: string, forward: PortForward): void {
-      // Idempotent upsert: delete any existing row for this exact tuple, then
-      // insert. Matches buildRouteOps' delete-then-insert (keeps the operation
-      // atomic w.r.t. the unique index, and NULL-aware on ingress_ip).
+    replace(firewallIp: string, target: PortForwardTarget, ports: number[]): void {
+      // Delete-then-insert over the consumer's WHOLE set for this target, not
+      // per port: that is what makes a redeploy exposing a shorter port list
+      // withdraw the ports it left out (celilo#855). Scoped to this consumer,
+      // so another module's forward for the same target is untouched.
       db.delete(portForwards)
-        .where(
-          and(
-            eq(portForwards.firewallIp, firewallIp),
-            eq(portForwards.internalIp, forward.internalIp),
-            eq(portForwards.port, forward.port),
-            eq(portForwards.protocol, forward.protocol),
-            ingressMatch(forward.ingressIp),
-          ),
-        )
+        .where(ownedOrUnattributed(firewallIp, target, registeredBy))
         .run();
-      db.insert(portForwards)
-        .values({
-          firewallIp,
-          internalIp: forward.internalIp,
-          port: forward.port,
-          protocol: forward.protocol,
-          ingressIp: forward.ingressIp ?? null,
-          description: forward.description,
-        })
-        .run();
-    },
 
-    remove(
-      firewallIp: string,
-      internalIp: string,
-      port: number,
-      protocol: Protocol,
-      ingressIp?: string,
-    ): void {
-      db.delete(portForwards)
-        .where(
-          and(
-            eq(portForwards.firewallIp, firewallIp),
-            eq(portForwards.internalIp, internalIp),
-            eq(portForwards.port, port),
-            eq(portForwards.protocol, protocol),
-            ingressMatch(ingressIp),
-          ),
+      if (ports.length === 0) return;
+
+      db.insert(portForwards)
+        .values(
+          ports.map((port) => ({
+            firewallIp,
+            internalIp: target.internalIp,
+            port,
+            protocol: target.protocol,
+            ingressIp: target.ingressIp ?? null,
+            description: target.description,
+            registeredBy,
+          })),
         )
         .run();
     },
   };
 }
+
+/**
+ * Drop every forward a departing module owns, across every firewall.
+ *
+ * `registered_by` is plain text rather than a FK, so unlike `web_routes` these
+ * rows do NOT die with the `modules` row — core deletes them explicitly, AFTER
+ * the provider has converged without them (D4).
+ */
+export function deletePortForwardsForModule(db: DbClient, moduleId: string): void {
+  db.delete(portForwards).where(eq(portForwards.registeredBy, moduleId)).run();
+}