@celilo/cli 1.6.0 → 1.8.0

package/src/services/alerting/monitors.ts

@@ -214,7 +214,59 @@ export function ensureInboundSubscriber(bus: SubscriberRegistrar): void {
   });
 }
 
-export function deleteMonitor(db: DbClient, monitorId: string, now: Date): void {
-  resolveMonitorAlerts(db, monitorId, now);
+/** A live alert about to be deleted along with the monitor that owns it. */
+export interface DroppedAlert {
+  key: string;
+  message: string;
+}
+
+/**
+ * Delete a monitor, and report the live alerts that go with it.
+ *
+ * The alerts are DELETED, not resolved. `alerts.monitorId` is
+ * `on delete cascade`, so the row goes the moment the monitor does. This used
+ * to call `resolveMonitorAlerts` first; that write was unreachable — the very
+ * next statement dropped the same rows, and nothing read them in between, so
+ * the resolved state existed for the duration of one statement. Deleted rather
+ * than restored, because resolving properly would need the alert rows to
+ * outlive their monitor, which the FK forbids and which no reader wants:
+ * `resolvedAt` is only ever read as a liveness predicate (`ack.ts`), never
+ * reported. Do not put the call back without changing the FK first.
+ *
+ * What IS worth keeping is what was lost, which is why the live alerts are
+ * returned. A monitor dropped while holding a firing alert takes a real
+ * failure and the coverage of it away together, and a caller that only names
+ * the monitor cannot tell an operator what stopped being watched.
+ */
+export function deleteMonitor(db: DbClient, monitorId: string): DroppedAlert[] {
+  const dropped = db
+    .select({ key: alerts.key, message: alerts.message })
+    .from(alerts)
+    .where(and(eq(alerts.monitorId, monitorId), isNotNull(alerts.activeKey)))
+    .all();
+
   db.delete(monitors).where(eq(monitors.id, monitorId)).run();
+  return dropped;
+}
+
+/**
+ * Drop the `module_hook` monitor belonging to a module that is going away.
+ *
+ * Called from the removal path rather than expressed as a foreign key, because
+ * `monitors.target` cannot carry one: it holds a module id for `module_hook`
+ * and an audit check name for `builtin_check`, and SQLite has no conditional
+ * reference. Splitting the table to get the constraint would need a synthetic
+ * monitor identity for `alerts.monitorId` — the trade the file header already
+ * weighs and declines.
+ *
+ * Deleting cascades the monitor's alerts away (`alerts.monitorId` is
+ * `on delete cascade`), which is what releases anything they were suppressing.
+ * They are deleted, not resolved — see `deleteMonitor`. Returns what was live
+ * so the caller can say what stopped being watched, or null if the module had
+ * no monitor.
+ */
+export function deleteMonitorForModule(db: DbClient, moduleId: string): DroppedAlert[] | null {
+  const monitor = findMonitor(db, 'module_hook', moduleId);
+  if (!monitor) return null;
+  return deleteMonitor(db, monitor.id);
 }

package/src/services/alerting/sweep-runner.ts

@@ -23,6 +23,7 @@ import type { DbClient } from '../../db/client';
 import type { Alert, Monitor } from '../../db/schema';
 import { MONITOR_INTERVAL_FLOOR_MINUTES } from '../cadence';
 import { isScheduled, loadModuleHealthCadences } from './health-cadence';
+import { type DroppedAlert, deleteMonitor } from './monitors';
 import type { NotifyDeps, NotifyOutcome } from './notifier';
 import { deliverDeferred, notifyAlert } from './notifier';
 import { type MonitorRunDeps, runOneMonitor } from './run-monitor';
@@ -102,6 +103,19 @@ export interface SweepReport {
    * former, because nothing ever reached the daemon.
    */
   failures: string[];
+  /**
+   * Modules whose `module_hook` monitor was dropped because the module itself
+   * is gone, and the live alerts each one took with it.
+   *
+   * The alerts are DELETED by the monitor's cascade, not resolved, so a firing
+   * check and the coverage of it disappear in the same instant with nothing
+   * else recording either. A bare module name is not enough to act on: the row
+   * that mattered on the fleet was holding `Cannot reach router: Router login
+   * failed`, and `1 stranded-dropped (greenwave)` would not have told anyone
+   * that a router had stopped being checked. Same reason `noPolicy`, `skipped`
+   * and `failures` all name their subject rather than counting it.
+   */
+  strandedDropped: { moduleId: string; alerts: DroppedAlert[] }[];
 }
 
 /**
@@ -129,6 +143,7 @@ export async function runSweep(
     noPolicy: [],
     skipped: [],
     failures: [],
+    strandedDropped: [],
   };
 
   // 1. Run due monitors.
@@ -139,8 +154,30 @@ export async function runSweep(
   // manifest could never reach an existing install (design.md D2/D8). A
   // `builtin_check` has no module and no manifest, so its row is the config.
   const cadences = loadModuleHealthCadences(db);
+
+  // Reconcile away monitors whose module is gone, before anything tries to run
+  // them. `loadModuleHealthCadences` holds every module, so a miss here means
+  // no module row — and a `module_hook` monitor without one is unschedulable
+  // forever: its cadence resolves to null, `isScheduled` says false, and the
+  // sweep never selects it again. Anything it left firing would sit there with
+  // no path back to `resolved`, suppressing every alert it is an ancestor of
+  // (celilo#1029).
+  //
+  // The removal path deletes the monitor itself, so this only fires for rows a
+  // celilo without that fix left behind, or a removal that died between the two
+  // deletes. Same stance `setMonitorEnabled` already takes: a monitor that will
+  // never report again must not hold live alerts.
+  const stranded = monitors.filter((m) => m.kind === 'module_hook' && !cadences.has(m.target));
+  for (const monitor of stranded) {
+    report.strandedDropped.push({
+      moduleId: monitor.target,
+      alerts: deleteMonitor(db, monitor.id),
+    });
+  }
+  const active = stranded.length > 0 ? monitors.filter((m) => !stranded.includes(m)) : monitors;
+
   const due = selectDueMonitors(
-    monitors.map((m) => {
+    active.map((m) => {
       if (m.kind !== 'module_hook') {
         return {
           id: m.id,

package/src/services/capability-table-rows.test.ts

@@ -0,0 +1,191 @@
+/**
+ * The ONE consumer-removal rule, driven by the declarations
+ * (openspec/changes/capability-owned-tables task 2.4).
+ *
+ * Before this, "the row dies with its consumer" had five implementations for one
+ * rule, and two of them were functions core imported BY NAME from
+ * `consumer-cleanup.ts` — the file whose whole purpose is deleting exactly that
+ * kind of per-capability special-casing.
+ *
+ * The property worth protecting is not "port forwards get deleted". It is that
+ * core clears EVERY declared table without naming any of them, so declaring a
+ * new one is sufficient to have it cleaned up.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { allDeclaredTables } from '@celilo/capabilities';
+import type { DbClient } from '../db/client';
+import { dnsInternalRecords, modules, portForwards, trustedSources, webRoutes } from '../db/schema';
+import { setupTestDatabase } from '../test-utils/setup-test-db';
+import { deleteClaimedRows, planClaimedRowDeletion } from './capability-table-rows';
+
+const FW = '192.168.0.254';
+
+describe('planClaimedRowDeletion', () => {
+  /**
+   * The anti-regression that matters. If someone declares a table and this plan
+   * does not grow, their rows outlive the consumer silently — which is the whole
+   * failure the declaration exists to make impossible.
+   */
+  it('covers every declared table, so declaring one is enough to have it cleared', () => {
+    const planned = new Set(planClaimedRowDeletion().map((t) => t.table));
+    const declared = allDeclaredTables().map((d) => d.declaration.table);
+
+    expect(declared.length).toBeGreaterThan(0);
+    for (const table of declared) expect(planned.has(table)).toBe(true);
+  });
+
+  it("carries each table's OWN claim column, which is spelled three ways", () => {
+    const byTable = new Map(planClaimedRowDeletion().map((t) => [t.table, t.claimColumn]));
+
+    expect(byTable.get('web_routes')).toBe('module_id');
+    expect(byTable.get('port_forwards')).toBe('registered_by');
+    expect(byTable.get('trusted_sources')).toBe('registered_by');
+    expect(byTable.get('dns_internal_records')).toBe('consumer_module_id');
+  });
+});
+
+describe('deleteClaimedRows', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'claimed-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabase(dbPath);
+
+    for (const id of ['caddy', 'forgejo', 'technitium']) {
+      db.insert(modules)
+        .values({
+          id,
+          name: id,
+          version: '1.0.0',
+          state: 'VERIFIED',
+          sourcePath: `/tmp/${id}`,
+          manifestData: {},
+        })
+        .run();
+    }
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function seed(consumer: string, hostname: string, port: number, subnet: string) {
+    db.insert(webRoutes)
+      .values({
+        slug: `${consumer}-slug`,
+        moduleId: consumer,
+        type: 'reverse_proxy',
+        path: `/${consumer}`,
+        hostname,
+      })
+      .run();
+    db.insert(portForwards)
+      .values({
+        firewallIp: FW,
+        internalIp: '10.0.20.5',
+        port,
+        protocol: 'TCP',
+        registeredBy: consumer,
+      })
+      .run();
+    db.insert(trustedSources).values({ firewallIp: FW, subnet, registeredBy: consumer }).run();
+    db.insert(dnsInternalRecords)
+      .values({
+        providerModuleId: 'technitium',
+        consumerModuleId: consumer,
+        host: hostname,
+        ip: '10.0.20.5',
+      })
+      .run();
+  }
+
+  it('clears the departing consumer from all four declared tables at once', () => {
+    seed('caddy', 'a.example.org', 443, '10.1.0.0/24');
+
+    const cleared = deleteClaimedRows(db, 'caddy');
+
+    expect(cleared.map((c) => c.table).sort()).toEqual([
+      'dns_internal_records',
+      'port_forwards',
+      'trusted_sources',
+      'web_routes',
+    ]);
+    expect(db.select().from(webRoutes).all()).toHaveLength(0);
+    expect(db.select().from(portForwards).all()).toHaveLength(0);
+    expect(db.select().from(trustedSources).all()).toHaveLength(0);
+    expect(db.select().from(dnsInternalRecords).all()).toHaveLength(0);
+  });
+
+  /**
+   * The refcount case, the bug most likely to ship silently. Two consumers each
+   * hold their own row, and one leaving must not withdraw what the other still
+   * needs.
+   */
+  it("leaves another consumer's rows untouched", () => {
+    seed('caddy', 'a.example.org', 443, '10.1.0.0/24');
+    seed('forgejo', 'b.example.org', 2222, '10.2.0.0/24');
+
+    deleteClaimedRows(db, 'caddy');
+
+    expect(
+      db
+        .select()
+        .from(webRoutes)
+        .all()
+        .map((r) => r.moduleId),
+    ).toEqual(['forgejo']);
+    expect(
+      db
+        .select()
+        .from(portForwards)
+        .all()
+        .map((r) => r.registeredBy),
+    ).toEqual(['forgejo']);
+    expect(
+      db
+        .select()
+        .from(trustedSources)
+        .all()
+        .map((r) => r.registeredBy),
+    ).toEqual(['forgejo']);
+    expect(
+      db
+        .select()
+        .from(dnsInternalRecords)
+        .all()
+        .map((r) => r.consumerModuleId),
+    ).toEqual(['forgejo']);
+  });
+
+  /**
+   * `dns_internal_records` is claimed by its CONSUMER, never its provider. The
+   * declaration cannot express anything else, which is what makes celilo#1010
+   * unrepresentable — but the runtime rule has to agree, or the declaration is
+   * decoration.
+   */
+  it('does not treat the PROVIDER as the claimant of a dns_internal record', () => {
+    seed('caddy', 'a.example.org', 443, '10.1.0.0/24');
+
+    deleteClaimedRows(db, 'technitium');
+
+    expect(db.select().from(dnsInternalRecords).all()).toHaveLength(1);
+  });
+
+  it('is a no-op for a module that claimed nothing', () => {
+    seed('caddy', 'a.example.org', 443, '10.1.0.0/24');
+
+    deleteClaimedRows(db, 'forgejo');
+
+    expect(db.select().from(webRoutes).all()).toHaveLength(1);
+    expect(db.select().from(portForwards).all()).toHaveLength(1);
+  });
+});

package/src/services/capability-table-rows.ts

@@ -0,0 +1,103 @@
+/**
+ * Acting on every capability-declared table without naming any of them
+ * (openspec/changes/capability-owned-tables, design D3).
+ *
+ * "This row dies with its consumer" had five implementations for one rule: an FK
+ * cascade for `web_routes`, two functions core imported BY NAME from
+ * `consumer-cleanup.ts` for `port_forwards` and `trusted_sources`, a second
+ * table pruned on read for `dns_registrations`, a cascade on both provider and
+ * consumer for `dns_internal_records`, and a hook rewriting a JSON blob for the
+ * rest. `consumer-cleanup.ts` exists specifically to delete that kind of
+ * per-capability special-casing. It succeeded for the hook dispatch and then
+ * grew two hardcoded imports for the rows, because the rows had no generic rule.
+ *
+ * This is the generic rule. The declaration names the claim column, so core no
+ * longer has to know that three tables spell it `module_id`, `registered_by` and
+ * `consumer_module_id`.
+ */
+
+import { CAPABILITY_DECLARED_TABLES, allDeclaredTables } from '@celilo/capabilities';
+import { type Column, eq, is } from 'drizzle-orm';
+import { SQLiteTable, getTableConfig } from 'drizzle-orm/sqlite-core';
+import type { DbClient } from '../db/client';
+import * as dbSchema from '../db/schema';
+
+export interface ClaimedRowTarget {
+  capability: string;
+  /** Physical table name. */
+  table: string;
+  /** The column holding the consumer's module id. */
+  claimColumn: string;
+}
+
+/**
+ * Physical table name → the drizzle table object, for the tables celilo can
+ * actually act on. Built by walking the schema rather than by a hand-written
+ * map, so a table cannot be declared and then silently unreachable.
+ */
+function schemaTables(): Map<string, SQLiteTable> {
+  const out = new Map<string, SQLiteTable>();
+  for (const value of Object.values(dbSchema)) {
+    if (!is(value, SQLiteTable)) continue;
+    out.set(getTableConfig(value).name, value);
+  }
+  return out;
+}
+
+/**
+ * What a consumer's removal must clear. Pure — the list is a property of the
+ * declarations, so it is worth being able to assert without a database.
+ *
+ * A declaration naming a table that does not exist is skipped here rather than
+ * throwing. `policy/capability-shape-drift.test.ts` Scan A is what fails on
+ * that, loudly and at build time; a removal is the wrong moment to discover it,
+ * and refusing to clear the OTHER tables because one declaration is wrong would
+ * strand real rows.
+ */
+export function planClaimedRowDeletion(): ClaimedRowTarget[] {
+  const tables = schemaTables();
+  return allDeclaredTables()
+    .filter(({ declaration }) => tables.has(declaration.table))
+    .map(({ capability, declaration }) => ({
+      capability,
+      table: declaration.table,
+      claimColumn: declaration.claim.column,
+    }))
+    .sort((a, b) => a.table.localeCompare(b.table));
+}
+
+/**
+ * Delete every declared row this consumer claimed.
+ *
+ * Called AFTER every provider has been told the consumer is going (its D4): a
+ * provider's `on_consumer_removed` is a full converge, and converging from a set
+ * the rows had already been removed from would withdraw more than the departing
+ * consumer's share.
+ *
+ * `web_routes` and `dns_internal_records` also carry an FK cascade, so their
+ * rows would go anyway once the `modules` row is deleted. Doing it here as well
+ * is deliberate and not merely harmless: it makes the ORDER explicit rather than
+ * a consequence of when some other statement happens to run, and it is the same
+ * point in the sequence at which `port_forwards` and `trusted_sources` were
+ * already being cleared by hand.
+ */
+export function deleteClaimedRows(db: DbClient, consumer: string): ClaimedRowTarget[] {
+  const tables = schemaTables();
+  const cleared: ClaimedRowTarget[] = [];
+  for (const target of planClaimedRowDeletion()) {
+    const table = tables.get(target.table);
+    if (!table) continue;
+    const column = getTableConfig(table).columns.find((c) => c.name === target.claimColumn);
+    if (!column) continue;
+    db.delete(table)
+      .where(eq(column as Column, consumer))
+      .run();
+    cleared.push(target);
+  }
+  return cleared;
+}
+
+/** Capability names that declare at least one table — for logs and reports. */
+export function capabilitiesWithDeclaredTables(): string[] {
+  return Object.keys(CAPABILITY_DECLARED_TABLES).sort();
+}

package/src/services/consumer-cleanup.ts

@@ -23,18 +23,19 @@ 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';
+import { deleteClaimedRows } from './capability-table-rows';
 
 /**
  * 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).
+ * a dependent — the guard, the cleanup and the provider-arrival backfill must
+ * keep ONE definition of a live module (D8). Exported rather than re-spelled:
+ * `module-remove.ts` had its own copy of the literal, and `provider-arrival.ts`
+ * would have been a third.
  */
-const PRE_DEPLOY_STATES = new Set(['IMPORTED', 'VALIDATED', 'CONFIGURED']);
+export const PRE_DEPLOY_STATES = new Set(['IMPORTED', 'VALIDATED', 'CONFIGURED']);
 
 export type CleanupSkipReason = 'paused' | 'not-deployed';
 
@@ -211,11 +212,18 @@ export async function runConsumerCleanup(
     );
   }
 
-  // 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);
+  // The rows, once every provider has converged without them (D4).
+  //
+  // Driven by the capability declarations rather than by name. This used to be
+  // two hardcoded imports, `deletePortForwardsForModule` and
+  // `deleteTrustedSourcesForModule`, which is the shape of the whole problem
+  // openspec/changes/capability-owned-tables addresses: this file exists to
+  // delete per-capability special-casing, it succeeded for the hook dispatch,
+  // and then grew two capability-named calls for the rows because the rows had
+  // no generic rule. Now they have one, and core no longer has to know that the
+  // claim column is spelled `module_id` on one table, `registered_by` on two and
+  // `consumer_module_id` on a fourth.
+  deleteClaimedRows(db, consumer);
 
   return result;
 }

package/src/services/container-service.test.ts

@@ -17,6 +17,8 @@ import {
   getServiceCredentials,
   listContainerServices,
   removeContainerService,
+  updateServiceCredentials,
+  updateVerificationStatus,
 } from './container-service';
 
 describe('container-service', () => {
@@ -270,6 +272,38 @@ describe('container-service', () => {
         /Container service not found/,
       );
     });
+
+    it('re-encrypts replacements and clears stale verification state', async () => {
+      const service = await addContainerService({
+        name: 'Moving Proxmox',
+        providerName: 'proxmox',
+        zones: ['internal'],
+        providerConfig: {},
+        apiCredentials: {
+          api_url: 'https://192.168.0.50:8006',
+          api_token_id: 'root@pam!celilo',
+          api_token_secret: 'existing-secret',
+        },
+      });
+      await updateVerificationStatus(service.id, { success: true, message: 'Connected' });
+
+      await updateServiceCredentials(service.id, {
+        api_url: 'https://10.77.20.50:8006',
+        api_token_id: 'root@pam!celilo',
+        api_token_secret: 'existing-secret',
+      });
+
+      const credentials = await getServiceCredentials(service.id);
+      const updated = await getContainerService(service.id);
+      expect(credentials).toEqual({
+        api_url: 'https://10.77.20.50:8006',
+        api_token_id: 'root@pam!celilo',
+        api_token_secret: 'existing-secret',
+      });
+      expect(updated?.verified).toBe(false);
+      expect(updated?.verifiedAt).toBeNull();
+      expect(updated?.verificationError).toBeNull();
+    });
   });
 
   describe('removeContainerService', () => {

package/src/services/container-service.ts

@@ -251,6 +251,50 @@ export async function getServiceCredentials(serviceId: string): Promise<ServiceC
   );
 }
 
+/**
+ * Replace a container service's encrypted API credentials.
+ *
+ * Credentials identify the remote provider endpoint as well as the principal
+ * used there, so changing either invalidates the previous verification result.
+ * Callers should explicitly re-run service verification after this update.
+ */
+export async function updateServiceCredentials(
+  id: string,
+  credentials: ServiceCredentials,
+): Promise<void> {
+  const service = await getContainerService(id);
+  if (!service) {
+    throw new Error(`Container service not found: ${id}`);
+  }
+
+  const validated =
+    service.providerName === 'proxmox'
+      ? ProxmoxCredentialsSchema.parse(credentials)
+      : service.providerName === 'digitalocean'
+        ? DigitalOceanCredentialsSchema.parse(credentials)
+        : null;
+
+  if (!validated) {
+    throw new Error(
+      `Unsupported provider for credential validation: ${service.providerName}. Supported providers: proxmox, digitalocean`,
+    );
+  }
+
+  const masterKey = await getOrCreateMasterKey();
+  const encrypted = encryptSecret(JSON.stringify(validated), masterKey);
+
+  await getDb()
+    .update(containerServices)
+    .set({
+      apiCredentialsEncrypted: JSON.stringify(encrypted),
+      verified: false,
+      verifiedAt: null,
+      verificationError: null,
+      updatedAt: new Date(),
+    })
+    .where(eq(containerServices.id, id));
+}
+
 /**
  * List container services with optional filters
  */

package/src/services/deployed-systems.test.ts

@@ -266,6 +266,57 @@ describe('backfillModuleSystems', () => {
     });
   });
 
+  test('backfill records a local machine by its interface in the resolved zone', () => {
+    db.insert(machines)
+      .values({
+        id: 'm-local-bf',
+        hostname: 'celilo-mgr',
+        // Local-execution sentinel, not the machine's network identity.
+        ipAddress: '127.0.0.1',
+        sshUser: 'jem',
+        sshKeyEncrypted: JSON.stringify({ encryptedValue: '', iv: '', authTag: '' }),
+        hardware: { cpu_cores: 4, memory_mb: 8192, disk_gb: 64 },
+        zone: 'secure-mgmt',
+        interfaces: [
+          { name: 'en0', ipAddress: '192.168.0.32', zone: 'external' },
+          { name: 'ens18', ipAddress: '10.77.20.32', zone: 'secure-mgmt' },
+        ],
+      })
+      .run();
+    db.insert(modules)
+      .values({
+        id: 'celilo-mgmt',
+        name: 'celilo-mgmt',
+        version: '1.0.0',
+        manifestData: { requires: { system: { zone: 'internal' } } },
+        sourcePath: '/tmp/celilo-mgmt',
+        state: 'VERIFIED',
+      })
+      .run();
+    db.insert(moduleInfrastructure)
+      .values({
+        id: 'infra-celilo-mgmt-local',
+        moduleId: 'celilo-mgmt',
+        infrastructureType: 'machine',
+        machineId: 'm-local-bf',
+      })
+      .run();
+    db.insert(moduleConfigs)
+      .values({
+        moduleId: 'celilo-mgmt',
+        key: 'hostname',
+        value: 'celilo-mgr',
+        valueJson: '"celilo-mgr"',
+      })
+      .run();
+
+    expect(backfillModuleSystems(db)).toEqual(['celilo-mgmt']);
+    expect(getModuleSystems('celilo-mgmt', db)[0]).toMatchObject({
+      zone: 'secure-mgmt',
+      ipv4_address: '10.77.20.32',
+    });
+  });
+
   // The control-plane case. celilo-mgmt declares `internal` (it bootstraps before
   // any firewall exists) but in a segmented fleet the operator earmarks a box on
   // `secure-mgmt`. What gets RECORDED must be where the system actually is, since
@@ -318,6 +369,56 @@ describe('backfillModuleSystems', () => {
     expect(getModuleSystems('celilo-mgmt', db)[0]).toMatchObject({ zone: 'secure-mgmt' });
   });
 
+  test('records a local machine by its interface in the resolved zone', async () => {
+    db.insert(machines)
+      .values({
+        id: 'm-local',
+        hostname: 'celilo-mgr',
+        // Local-execution sentinel, not the machine's network identity.
+        ipAddress: '127.0.0.1',
+        sshUser: 'jem',
+        sshKeyEncrypted: JSON.stringify({ encryptedValue: '', iv: '', authTag: '' }),
+        hardware: { cpu_cores: 4, memory_mb: 8192, disk_gb: 64 },
+        zone: 'secure-mgmt',
+        earmarkedModule: 'celilo-mgmt',
+        interfaces: [
+          { name: 'en0', ipAddress: '192.168.0.32', zone: 'external' },
+          { name: 'ens18', ipAddress: '10.77.20.32', zone: 'secure-mgmt' },
+        ],
+      })
+      .run();
+    db.insert(modules)
+      .values({
+        id: 'celilo-mgmt',
+        name: 'celilo-mgmt',
+        version: '1.0.0',
+        manifestData: { requires: { system: { zone: 'internal' } } },
+        sourcePath: '/tmp/celilo-mgmt',
+        state: 'VERIFIED',
+      })
+      .run();
+    db.insert(moduleConfigs)
+      .values({
+        moduleId: 'celilo-mgmt',
+        key: 'hostname',
+        value: 'celilo-mgr',
+        valueJson: '"celilo-mgr"',
+      })
+      .run();
+
+    const recorded = await recordDeployedSystemForModule(
+      'celilo-mgmt',
+      { requires: { system: { zone: 'internal' } } } as ModuleManifest,
+      { type: 'machine', machineId: 'm-local' },
+      db,
+    );
+
+    expect(recorded[0]).toMatchObject({
+      zone: 'secure-mgmt',
+      ipv4_address: '10.77.20.32',
+    });
+  });
+
   test('skips an API-only module (no declared systems)', () => {
     ensureProxmoxService(db);
     db.insert(modules)