@celilo/cli 0.20.0 → 0.21.0

package/src/services/dns-registrations.test.ts

@@ -2,7 +2,8 @@
  * Unit tests for the DNS registration ledger
  * (designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md B2): upsert semantics,
  * the registerHost recording wrapper (success-only), refresh stamping,
- * and FK-cascade cleanup when a module is removed.
+ * companion rows, and the consumer-set lifecycle (design.md D5) — a row
+ * survives every consumer but the last.
  */
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
@@ -28,7 +29,7 @@ describe('dns_registrations ledger', () => {
     tempDir = mkdtempSync(join(tmpdir(), 'celilo-dnsreg-'));
     process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
     db = getDb();
-    for (const id of ['namecheap', 'caddy']) {
+    for (const id of ['namecheap', 'caddy', 'authentik']) {
       db.insert(modules)
         .values({
           id,
@@ -46,25 +47,23 @@ describe('dns_registrations ledger', () => {
     process.env.CELILO_DB_PATH = undefined;
   });
 
-  test('record + list roundtrip; upsert replaces ip and consumer', () => {
+  test('record + list roundtrip; a re-assert is an upsert, not a second row', () => {
     recordDnsRegistration(db, {
       providerModuleId: 'namecheap',
       consumerModuleId: 'caddy',
       fqdn: 'www.example.net',
-      ip: '198.51.100.7',
     });
     recordDnsRegistration(db, {
       providerModuleId: 'namecheap',
       consumerModuleId: 'caddy',
       fqdn: 'www.example.net',
-      ip: '198.51.100.8',
     });
 
     const rows = listDnsRegistrations(db, { providerModuleId: 'namecheap' });
     expect(rows.length).toBe(1);
     expect(rows[0].fqdn).toBe('www.example.net');
-    expect(rows[0].ip).toBe('198.51.100.8');
     expect(rows[0].consumerModuleId).toBe('caddy');
+    expect(rows[0].companion).toBe(false);
     expect(rows[0].refreshedAt).toBeNull();
   });
 
@@ -73,21 +72,62 @@ describe('dns_registrations ledger', () => {
       providerModuleId: 'namecheap',
       consumerModuleId: 'caddy',
       fqdn: 'git.example.net',
-      ip: null,
     });
     stampDnsRegistrationsRefreshed(db, 'namecheap');
     const [row] = listDnsRegistrations(db, { providerModuleId: 'namecheap' });
     expect(row.refreshedAt).not.toBeNull();
   });
 
-  test('rows die with the consumer module (FK cascade)', () => {
+  // ── design.md D5: attribution is a set, and it is load-bearing ─────────────
+  test('a blanket re-assert ADDS a consumer instead of overwriting the introducer', () => {
+    recordDnsRegistration(db, {
+      providerModuleId: 'namecheap',
+      consumerModuleId: 'authentik',
+      fqdn: 'auth.example.net',
+    });
+    // What `run-hook caddy on_install` does to every served name.
     recordDnsRegistration(db, {
       providerModuleId: 'namecheap',
       consumerModuleId: 'caddy',
-      fqdn: 'www.example.net',
-      ip: '198.51.100.7',
+      fqdn: 'auth.example.net',
+    });
+
+    const [row] = listDnsRegistrations(db);
+    expect(row.consumerModuleIds).toEqual(['authentik', 'caddy']);
+    // The module that introduced the name is still identifiable.
+    expect(row.consumerModuleId).toBe('authentik');
+  });
+
+  test('the row survives a consumer removal and dies with the last one', () => {
+    recordDnsRegistration(db, {
+      providerModuleId: 'namecheap',
+      consumerModuleId: 'authentik',
+      fqdn: 'auth.example.net',
     });
+    recordDnsRegistration(db, {
+      providerModuleId: 'namecheap',
+      consumerModuleId: 'caddy',
+      fqdn: 'auth.example.net',
+    });
+
+    // Removing caddy on the live fleet would, under the single-value column,
+    // have cascade-deleted a name authentik still serves.
     db.delete(modules).where(eq(modules.id, 'caddy')).run();
+    const [row] = listDnsRegistrations(db);
+    expect(row.fqdn).toBe('auth.example.net');
+    expect(row.consumerModuleIds).toEqual(['authentik']);
+
+    db.delete(modules).where(eq(modules.id, 'authentik')).run();
+    expect(listDnsRegistrations(db).length).toBe(0);
+  });
+
+  test('rows die with the provider module (FK cascade)', () => {
+    recordDnsRegistration(db, {
+      providerModuleId: 'namecheap',
+      consumerModuleId: 'caddy',
+      fqdn: 'www.example.net',
+    });
+    db.delete(modules).where(eq(modules.id, 'namecheap')).run();
     expect(listDnsRegistrations(db).length).toBe(0);
   });
 
@@ -106,15 +146,37 @@ describe('dns_registrations ledger', () => {
       consumerModuleId: 'caddy',
     });
 
-    await wrapped.registerHost({ fqdn: 'www.example.net', ip: '198.51.100.7' });
-    await wrapped.registerHost({ fqdn: 'fail.example.net', ip: '198.51.100.7' });
+    await wrapped.registerHost({ fqdn: 'www.example.net' });
+    await wrapped.registerHost({ fqdn: 'fail.example.net' });
     await wrapped.registerHost({ fqdn: 'auto.example.net' });
 
     expect(calls.length).toBe(3);
-    const rows = listDnsRegistrations(db);
-    const fqdns = rows.map((r) => r.fqdn).sort();
+    const fqdns = listDnsRegistrations(db)
+      .map((r) => r.fqdn)
+      .sort();
     expect(fqdns).toEqual(['auto.example.net', 'www.example.net']);
-    const auto = rows.find((r) => r.fqdn === 'auto.example.net');
-    expect(auto?.ip).toBeNull();
+  });
+
+  test('a companion the provider attempted gets its own watched row', async () => {
+    const fake: DnsRegistrarCapability = {
+      async registerHost(request) {
+        return {
+          success: true,
+          outputs: { companion_fqdn: `www.${request.fqdn}` },
+          duration: 1,
+        };
+      },
+    };
+    const wrapped = withDnsRegistrationLedger(fake, {
+      db,
+      providerModuleId: 'namecheap',
+      consumerModuleId: 'caddy',
+    });
+
+    await wrapped.registerHost({ fqdn: 'example.net' });
+
+    const rows = listDnsRegistrations(db).sort((a, b) => a.fqdn.localeCompare(b.fqdn));
+    expect(rows.map((r) => r.fqdn)).toEqual(['example.net', 'www.example.net']);
+    expect(rows.map((r) => r.companion)).toEqual([false, true]);
   });
 });

package/src/services/dns-registrations.ts

@@ -4,36 +4,63 @@
  *
  * The capability loader records every successful
  * dns_registrar.registerHost here; the run-hook path reads the ledger
- * back to feed a provider's `refresh_registrations` hook, and `celilo
- * dns registrations` lists it for the operator. Row lifecycle is FK
- * cascade — registrations die with their provider or consumer module.
+ * back to feed a provider's `refresh_registrations` hook, the
+ * `public_dns` check resolves every row from off-fleet, and `celilo dns
+ * registrations` lists it for the operator.
+ *
+ * The ledger records WHICH MODULE ASKED FOR WHICH NAME. It stores no
+ * address — see the schema comment and design.md D1.
+ *
+ * Lifecycle: a row dies with its provider by FK cascade, and with its
+ * LAST consumer via the `dns_registration_consumers` set (design.md D5).
  */
 
 import type { DnsRegistrarCapability, HookResult } from '@celilo/capabilities';
-import { eq } from 'drizzle-orm';
+import { and, eq, sql } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
-import { dnsRegistrations } from '../db/schema';
+import { dnsRegistrationConsumers, dnsRegistrations } from '../db/schema';
 
 export interface DnsRegistrationRow {
   fqdn: string;
-  /** null = the provider auto-detected the request's source IP. */
-  ip: string | null;
   providerModuleId: string;
+  /** The module that introduced the name — the earliest consumer. */
   consumerModuleId: string;
+  /** Every module currently depending on the name, introducer first. */
+  consumerModuleIds: string[];
+  /** Claimed by celilo as the companion of a declared name, not asked for. */
+  companion: boolean;
   registeredAt: Date;
   refreshedAt: Date | null;
 }
 
+/**
+ * Drop registrations whose last consumer module is gone.
+ *
+ * ponytail: pruned on read rather than by trigger — SQLite fires delete
+ * triggers for FK-cascaded deletes only when `recursive_triggers` is on,
+ * and reads are the only thing that consumes the ledger. Move it into a
+ * trigger if something ever reads these rows without going through here.
+ */
+function pruneOrphanedRegistrations(db: DbClient): void {
+  db.run(
+    sql`DELETE FROM dns_registrations WHERE NOT EXISTS (
+      SELECT 1 FROM dns_registration_consumers c WHERE c.registration_id = dns_registrations.id
+    )`,
+  );
+}
+
 export function listDnsRegistrations(
   db: DbClient,
   options: { providerModuleId?: string } = {},
 ): DnsRegistrationRow[] {
+  pruneOrphanedRegistrations(db);
+
   const query = db
     .select({
+      id: dnsRegistrations.id,
       fqdn: dnsRegistrations.fqdn,
-      ip: dnsRegistrations.ip,
       providerModuleId: dnsRegistrations.providerModuleId,
-      consumerModuleId: dnsRegistrations.consumerModuleId,
+      companion: dnsRegistrations.companion,
       registeredAt: dnsRegistrations.registeredAt,
       refreshedAt: dnsRegistrations.refreshedAt,
     })
@@ -41,7 +68,31 @@ export function listDnsRegistrations(
   const rows = options.providerModuleId
     ? query.where(eq(dnsRegistrations.providerModuleId, options.providerModuleId)).all()
     : query.all();
-  return rows;
+
+  const consumers = db
+    .select({
+      registrationId: dnsRegistrationConsumers.registrationId,
+      moduleId: dnsRegistrationConsumers.moduleId,
+    })
+    .from(dnsRegistrationConsumers)
+    .orderBy(dnsRegistrationConsumers.id)
+    .all();
+
+  const byRegistration = new Map<number, string[]>();
+  for (const c of consumers) {
+    const list = byRegistration.get(c.registrationId);
+    if (list) list.push(c.moduleId);
+    else byRegistration.set(c.registrationId, [c.moduleId]);
+  }
+
+  return rows.map(({ id, ...row }) => {
+    const consumerModuleIds = byRegistration.get(id) ?? [];
+    return {
+      ...row,
+      consumerModuleIds,
+      consumerModuleId: consumerModuleIds[0] ?? '',
+    };
+  });
 }
 
 export function recordDnsRegistration(
@@ -50,26 +101,46 @@ export function recordDnsRegistration(
     providerModuleId: string;
     consumerModuleId: string;
     fqdn: string;
-    ip: string | null;
+    companion?: boolean;
   },
 ): void {
   db.insert(dnsRegistrations)
     .values({
       providerModuleId: registration.providerModuleId,
-      consumerModuleId: registration.consumerModuleId,
       fqdn: registration.fqdn,
-      ip: registration.ip,
+      companion: registration.companion ?? false,
       registeredAt: new Date(),
     })
     .onConflictDoUpdate({
       target: [dnsRegistrations.providerModuleId, dnsRegistrations.fqdn],
-      set: {
-        consumerModuleId: registration.consumerModuleId,
-        ip: registration.ip,
-        registeredAt: new Date(),
-      },
+      // `companion` is not re-asserted: once a module declares a name
+      // outright it stops being something celilo claimed on its behalf.
+      set: { registeredAt: new Date() },
     })
     .run();
+
+  const row = db
+    .select({ id: dnsRegistrations.id })
+    .from(dnsRegistrations)
+    .where(
+      and(
+        eq(dnsRegistrations.providerModuleId, registration.providerModuleId),
+        eq(dnsRegistrations.fqdn, registration.fqdn),
+      ),
+    )
+    .get();
+  if (!row) return;
+
+  // A re-assert ADDS the asserting module rather than replacing whoever
+  // was there — the row must outlive any single one of them (D5).
+  db.insert(dnsRegistrationConsumers)
+    .values({
+      registrationId: row.id,
+      moduleId: registration.consumerModuleId,
+      firstSeenAt: new Date(),
+    })
+    .onConflictDoNothing()
+    .run();
 }
 
 /** Stamp every row of a provider as refreshed (successful refresh hook). */
@@ -85,6 +156,15 @@ export function stampDnsRegistrationsRefreshed(db: DbClient, providerModuleId: s
  * recorded in the ledger. Failures and MissingProviderInputError
  * interview throws pass through untouched — only a confirmed
  * registration earns a row.
+ *
+ * A provider that ATTEMPTED a companion name (`www.<domain>` ↔
+ * `<domain>`) reports it as `outputs.companion_fqdn`, and it gets its own
+ * row whether or not the attempt reported success. The row is not a claim
+ * that the name is published — it is what puts the name under the
+ * `public_dns` check, which is the only thing that can tell. Namecheap
+ * returns `ErrCount 0` for a `www` update it silently does not apply, so
+ * a companion recorded only on "success" would be a name celilo believes
+ * it owns and never looks at again (design.md D3).
  */
 export function withDnsRegistrationLedger(
   registrar: DnsRegistrarCapability,
@@ -99,8 +179,16 @@ export function withDnsRegistrationLedger(
           providerModuleId: ctx.providerModuleId,
           consumerModuleId: ctx.consumerModuleId,
           fqdn: request.fqdn,
-          ip: request.ip ?? null,
         });
+        const companion = result.outputs?.companion_fqdn;
+        if (typeof companion === 'string' && companion.length > 0) {
+          recordDnsRegistration(ctx.db, {
+            providerModuleId: ctx.providerModuleId,
+            consumerModuleId: ctx.consumerModuleId,
+            fqdn: companion,
+            companion: true,
+          });
+        }
       }
       return result;
     },

package/src/services/fleet-checks.test.ts

@@ -14,6 +14,8 @@ import {
 } from '../db/schema';
 import type { ModuleManifest } from '../manifest/schema';
 import { setupTestDatabase } from '../test-utils/setup-test-db';
+import { ensureInboundSubscriber, ensureSweepSubscriber } from './alerting/monitors';
+import { ensureBackupSweepSubscriber } from './backup-sweep';
 import { getDaemonUnitPath } from './events-daemon';
 import {
   checkCapabilityProviders,
@@ -25,6 +27,7 @@ import {
   describeCapabilityProblem,
   findBrokenCapabilityDerivations,
 } from './fleet-checks';
+import { ensureOperationsSweepSubscriber } from './module-operations';
 
 const MINUTE = 60_000;
 
@@ -274,10 +277,53 @@ describe('checkSubscribers + checkCapabilityProviders', () => {
 
     it('warns about a stale subscriber with no deployed module', () => {
       // No modules deployed, but a leftover subscriber lingers.
-      bus.subscribe({ name: 'ghost.sub', pattern: 'x', handler: 'echo' });
+      bus.subscribe({ name: 'ghost.sub', pattern: 'x', handler: 'echo', registeredBy: 'ghost' });
       const f = checkSubscribers(bus, db);
       expect(f.status).toBe('warn');
       expect(f.detail.join(' ')).toContain('ghost.sub');
+      // `resync-subscriptions` never deletes, so it cannot clear this (#624).
+      expect(f.autoFixable).toBe(false);
+      expect(f.remediation).toContain('subscribers remove');
+    });
+
+    it('ignores core-registered subscribers that no manifest declares (#624)', () => {
+      ensureSweepSubscriber(bus);
+      ensureInboundSubscriber(bus);
+      ensureBackupSweepSubscriber(bus);
+      ensureOperationsSweepSubscriber(bus);
+      const f = checkSubscribers(bus, db);
+      expect(f.status).toBe('ok');
+      expect(f.detail.join(' ')).not.toContain('celilo-');
+    });
+
+    // The guard for the invariant `checkSubscribers` classifies by, asserted
+    // at the sites that ESTABLISH it rather than the one that consumes it —
+    // so it keeps holding if the predicate is ever rewritten. Goes red the
+    // moment a core registrar names its row under its own registrar id
+    // (`celilo-alerting` registering `celilo-alerting.digest`), which would
+    // read as a module row, find no module of that name, and be reported
+    // stale — #624 again, and baffling to whoever hit it.
+    //
+    // ponytail: enumerates the registrars by hand because celilo has no
+    // registry of them. A fifth one is not covered until it is added here;
+    // if that ever bites, the upgrade is a shared `registerCoreSubscriber`
+    // helper that every core site goes through, tested once.
+    it('no core registrar produces a module-shaped subscriber name', () => {
+      ensureSweepSubscriber(bus);
+      ensureInboundSubscriber(bus);
+      ensureBackupSweepSubscriber(bus);
+      ensureOperationsSweepSubscriber(bus);
+
+      const rows = bus.db
+        .query<{ name: string; registered_by: string | null }, []>(
+          'SELECT name, registered_by FROM subscribers',
+        )
+        .all();
+      expect(rows.length).toBeGreaterThan(0);
+      for (const row of rows) {
+        expect(row.registered_by).not.toBeNull();
+        expect(row.name.startsWith(`${row.registered_by}.`)).toBe(false);
+      }
     });
   });
 

package/src/services/fleet-checks.ts

@@ -386,6 +386,9 @@ function loadDeployedModules(db: DbClient): DeployedModule[] {
  * manifests declare. A restore/migration starts it EMPTY (ISS-0088), so
  * every reactive subscription silently vanishes until a resync or a
  * redeploy. Missing rows fail; stale rows (a since-removed module) warn.
+ *
+ * Scoped to MODULE-owned rows — core's own subscribers share this bus and are
+ * declared by no manifest.
  */
 export function checkSubscribers(bus: Bus, db: DbClient): FleetFinding {
   const deployed = loadDeployedModules(db);
@@ -402,7 +405,9 @@ export function checkSubscribers(bus: Bus, db: DbClient): FleetFinding {
   }
 
   const actualRows = bus.db
-    .query<{ name: string; pattern: string }, []>('SELECT name, pattern FROM subscribers')
+    .query<{ name: string; pattern: string; registered_by: string | null }, []>(
+      'SELECT name, pattern, registered_by FROM subscribers',
+    )
     .all();
   const actual = new Map(actualRows.map((r) => [r.name, r.pattern]));
 
@@ -413,7 +418,25 @@ export function checkSubscribers(bus: Bus, db: DbClient): FleetFinding {
     if (have === undefined) missing.push(name);
     else if (have !== pattern) mismatched.push(`${name} (manifest: ${pattern}, bus: ${have})`);
   }
-  const stale = actualRows.map((r) => r.name).filter((name) => !expected.has(name));
+  // Only module-owned rows can be stale. celilo core registers subscribers on
+  // the same bus (the alerting/backup/operations sweeps) that no manifest
+  // declares, so judging every row against the manifest-derived map reported
+  // them as drift on every install, forever (#624).
+  //
+  // INVARIANT this relies on: a module row is named `<registered_by>.<sub>` —
+  // `resolveSubscription` (services/module-subscriptions.ts) derives both the
+  // scoped name and registered_by from the same module id. A core row is NOT
+  // scoped under its registrar's id (`celilo-alerting` registers
+  // `celilo-alerting-sweep`, not `celilo-alerting.sweep`). That's what lets
+  // provenance separate them with no allowlist to keep in sync.
+  //
+  // To break it: have a core registrar name a row under its own id — a future
+  // `celilo-alerting.digest` would read as module-owned, find no deployed
+  // module named `celilo-alerting`, and be reported stale. Which is #624 again.
+  const stale = actualRows
+    .filter((r) => r.registered_by !== null && r.name.startsWith(`${r.registered_by}.`))
+    .map((r) => r.name)
+    .filter((name) => !expected.has(name));
 
   const detail: string[] = [];
   const statuses: FleetFindingStatus[] = [];
@@ -436,6 +459,15 @@ export function checkSubscribers(bus: Bus, db: DbClient): FleetFinding {
     );
   }
 
+  // `resync-subscriptions` only upserts from manifests — it never deletes, so
+  // it cannot clear a stale row. Advertising that as the remedy (and as
+  // auto-fixable) made `--fix` run a guaranteed no-op and call it a fix.
+  const resyncable = missing.length > 0 || mismatched.length > 0;
+  const remediations: string[] = [];
+  if (resyncable) remediations.push('`celilo events resync-subscriptions` (safe, idempotent)');
+  if (stale.length > 0)
+    remediations.push(`\`celilo subscribers remove <name>\` for: ${stale.join(', ')}`);
+
   const status = worst(statuses);
   return {
     id: 'subscribers',
@@ -446,8 +478,8 @@ export function checkSubscribers(bus: Bus, db: DbClient): FleetFinding {
         ? `${expected.size} subscription(s) match the deployed fleet`
         : 'bus subscribers drifted from the deployed fleet',
     detail,
-    remediation: status === 'ok' ? null : '`celilo events resync-subscriptions` (safe, idempotent)',
-    autoFixable: status !== 'ok',
+    remediation: remediations.length > 0 ? remediations.join('; ') : null,
+    autoFixable: resyncable,
   };
 }
 

package/src/services/module-subscriptions.test.ts

@@ -46,6 +46,15 @@ describe('resolveSubscription', () => {
     expect(resolved.registeredBy).toBe('lunacycle');
   });
 
+  // The other half of the invariant `checkSubscribers` classifies by (#624):
+  // core rows are not scoped under their registrar id, module rows always are.
+  // Stop scoping the name here and every module row reads as core-owned — the
+  // stale check would go silently blind rather than noisily wrong.
+  it('always scopes the name under the id it stamps in registeredBy', () => {
+    const resolved = resolveSubscription({ name: 'a', pattern: 'x', handler: 'echo' }, 'foo', '/p');
+    expect(resolved.name.startsWith(`${resolved.registeredBy}.`)).toBe(true);
+  });
+
   it('only substitutes $self when followed by . or end-of-string', () => {
     // `$selfish` would not be a real pattern but we want to ensure the
     // substitution doesn't accidentally rewrite identifier-like names.

package/src/services/public-dns-probe.test.ts

@@ -0,0 +1,81 @@
+/**
+ * The gate for the original bug, one layer up.
+ *
+ * A `public_dns` check that quietly resolved through the fleet's own resolver
+ * would pass forever whatever the internet sees — exactly like caddy's `dig`
+ * check does today, and exactly the blindness that let celilo#626 run for nine
+ * days. So "the resolver is off-fleet" is asserted rather than left to a
+ * comment, and the assertion lives where the probe is built.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  DEFAULT_PUBLIC_RESOLVER,
+  FleetResolverAsPublicVantageError,
+  assertOffFleetResolver,
+  parseFleetResolvers,
+} from './public-dns-probe';
+
+const FLEET = [
+  { role: 'dns.primary', ip: '10.0.20.5' },
+  { role: 'dns.fallback', ip: '8.8.8.8' },
+];
+
+describe('assertOffFleetResolver', () => {
+  test("refuses the fleet's own resolver", () => {
+    expect(() => assertOffFleetResolver('10.0.20.5', FLEET)).toThrow(
+      FleetResolverAsPublicVantageError,
+    );
+  });
+
+  test('refuses it even when the fleet resolver is a public address', () => {
+    // The failure is "the fleet asks this resolver too", not "the address is
+    // private": a fleet configured to forward to 8.8.8.8 gets the same
+    // split-horizon answers back through it.
+    expect(() => assertOffFleetResolver('8.8.8.8', FLEET)).toThrow(
+      FleetResolverAsPublicVantageError,
+    );
+  });
+
+  test('accepts a resolver the fleet does not use', () => {
+    expect(() => assertOffFleetResolver(DEFAULT_PUBLIC_RESOLVER, FLEET)).not.toThrow();
+  });
+
+  test('the refusal says how to fix it', () => {
+    try {
+      assertOffFleetResolver('10.0.20.5', FLEET);
+      throw new Error('expected a refusal');
+    } catch (error) {
+      expect((error as Error).message).toContain('celilo system config set public_dns.resolver');
+    }
+  });
+});
+
+describe('parseFleetResolvers', () => {
+  test('a comma-separated dns.fallback yields one entry per address', () => {
+    // `system init` writes `dns.fallback=1.0.0.1,8.8.8.8`. Compared whole, the
+    // guard matched neither address and would have accepted 8.8.8.8 as the
+    // "off-fleet" vantage point of a fleet that forwards to 8.8.8.8.
+    expect(
+      parseFleetResolvers([
+        { role: 'dns.primary', value: '10.0.20.5' },
+        { role: 'dns.fallback', value: '1.0.0.1, 8.8.8.8' },
+      ]),
+    ).toEqual([
+      { role: 'dns.primary', ip: '10.0.20.5' },
+      { role: 'dns.fallback', ip: '1.0.0.1' },
+      { role: 'dns.fallback', ip: '8.8.8.8' },
+    ]);
+  });
+
+  test('an unset key contributes nothing', () => {
+    expect(parseFleetResolvers([{ role: 'dns.primary', value: undefined }])).toEqual([]);
+  });
+
+  test('a multi-entry fallback is caught by the guard', () => {
+    const fleet = parseFleetResolvers([{ role: 'dns.fallback', value: '1.0.0.1,8.8.8.8' }]);
+    expect(() => assertOffFleetResolver('8.8.8.8', fleet)).toThrow(
+      FleetResolverAsPublicVantageError,
+    );
+  });
+});