@celilo/cli 0.20.0 → 0.22.0

package/src/services/audit/public-dns.ts

@@ -0,0 +1,286 @@
+/**
+ * Public-DNS reachability check.
+ *
+ * Every check celilo had reported healthy throughout celilo#626, during which
+ * five public names — including the apt repo and the module registry — resolved
+ * to an address that answered nothing for nine days. None of them was wrong:
+ * they all looked from *inside*, where the split-horizon resolver deliberately
+ * answers with an address that is reachable in-zone. celilo simply had no
+ * notion of a check whose vantage point is outside itself.
+ *
+ * This is that check. For every name in the DNS registration ledger it asks an
+ * OFF-FLEET resolver what the internet resolves, and compares that against the
+ * address the fleet actually appears to come from according to an independent
+ * echo service.
+ *
+ * Three properties are load-bearing, and each exists because of a specific way
+ * this check could quietly become useless:
+ *
+ *  - **The resolver must not be the fleet's.** A `public_dns` check that used
+ *    the configured resolver would pass forever, exactly like caddy's `dig`
+ *    does today. That is the original bug one layer up, so the probe asserts
+ *    it rather than leaving it to a comment (see `public-dns-probe.ts`).
+ *  - **The expectation must not come from the registrar.** Comparing what was
+ *    published against what we asked to publish is self-agreement — and worse
+ *    than useless here, because Namecheap's DDNS API returns `ErrCount 0` with
+ *    the requested address echoed back for a `www` update it silently does not
+ *    apply (design.md D3).
+ *  - **Missing evidence is not a pass.** The one genuine external probe the
+ *    fleet had (isitup.org, in celilo-website's health check) was itself
+ *    unreachable during the outage, and recorded that as *undetermined* with no
+ *    check item at all. So a real outage produced complete silence. A single
+ *    undetermined result stays quiet — a prober blip must not page — but
+ *    consecutive ones become their own finding, distinct from "unreachable".
+ *
+ * Pure over an injected probe and the previous run's evidence counters: no
+ * network, no DB. See design.md D2.
+ */
+
+import type { DriftFinding } from './types';
+
+/** What an off-fleet resolver answered for one name. */
+export type PublicResolution =
+  | { kind: 'answer'; ip: string; ttlSeconds: number }
+  /** The resolver answered authoritatively that there is no A record. */
+  | { kind: 'no_record' }
+  /** The resolver could not be reached, or failed. Not a pass, not a failure. */
+  | { kind: 'undetermined'; reason: string };
+
+/** The address the fleet appears to come from, per an independent third party. */
+export type IngressObservation =
+  | { kind: 'observed'; ip: string }
+  | { kind: 'undetermined'; reason: string };
+
+export interface PublicDnsProbe {
+  /** Named so findings can say where the answer came from, and so a test can assert it is off-fleet. */
+  readonly resolver: string;
+  /** Named for the same reason — an echo service outage must be attributable. */
+  readonly echoService: string;
+  observeIngress(): Promise<IngressObservation>;
+  resolve(fqdn: string): Promise<PublicResolution>;
+}
+
+/** One ledger name to check. */
+export interface PublicDnsRecord {
+  fqdn: string;
+  /**
+   * Claimed by celilo as the companion of a declared name rather than asked
+   * for by a module. Best effort at claim time, so its remediation is the
+   * manual registrar step rather than "fix the registrar and redeploy".
+   */
+  companion: boolean;
+  /**
+   * When the fleet last asserted this name (the provider's last refresh, or
+   * the registration). Divergence inside one TTL of an assert is propagation,
+   * not a fault — see the hysteresis note below.
+   */
+  lastAssertedAt: Date;
+}
+
+/**
+ * Per-subject counter of consecutive runs that produced no evidence. Carried
+ * across runs by the caller; the audit itself neither reads nor writes storage.
+ */
+export interface PublicDnsEvidence {
+  subject: string;
+  undeterminedRuns: number;
+}
+
+export interface PublicDnsAuditDeps {
+  records: PublicDnsRecord[];
+  probe: PublicDnsProbe;
+  /** Counters from the previous run. Empty on a first run. */
+  evidence?: PublicDnsEvidence[];
+  /** Sink for the updated counters. Omitted in unit tests. */
+  saveEvidence?: (evidence: PublicDnsEvidence[]) => void;
+  now?: Date;
+  /** Consecutive undetermined runs before the absence of evidence is itself a finding. */
+  undeterminedThreshold?: number;
+}
+
+/** The echo service's own subject, so its outage is counted like any other. */
+const ECHO_SUBJECT = 'system';
+
+const DEFAULT_UNDETERMINED_THRESHOLD = 3;
+
+/**
+ * A record that diverges within one TTL of the last assert is still
+ * propagating. Fleet records measure 180s, so alerting on first divergence
+ * would page on every ISP re-lease. Used when the resolver gave no TTL.
+ */
+const FALLBACK_TTL_SECONDS = 300;
+
+function companionRemediation(fqdn: string): string {
+  const label = fqdn.startsWith('www.') ? 'www' : '@';
+  return [
+    `celilo claims ${fqdn} alongside the name the module declared, but the`,
+    'registrar could not publish it. A DDNS API can update an existing record',
+    'and not create one, and Namecheap reports success for a `www` update it',
+    'silently does not apply — so this has to be fixed at the registrar:',
+    '',
+    `  1. Registrar → DNS for this domain → add an A record with Host="${label}"`,
+    '     (any value — celilo overwrites it), and enable Dynamic DNS.',
+    '  2. celilo claims it on the next assert; no redeploy needed.',
+  ].join('\n');
+}
+
+/**
+ * For callers that legitimately have nothing to check — `system update` runs a
+ * partial audit over what it already has and does not reach the network. It
+ * throws rather than answering, so a caller that grows records later cannot
+ * silently keep an inert vantage point.
+ */
+export const unusedPublicDnsProbe: PublicDnsProbe = {
+  resolver: '(not used)',
+  echoService: '(not used)',
+  observeIngress() {
+    throw new Error('public_dns probe used by a caller that declared no records');
+  },
+  resolve() {
+    throw new Error('public_dns probe used by a caller that declared no records');
+  },
+};
+
+export async function auditPublicDns(deps: PublicDnsAuditDeps): Promise<DriftFinding[]> {
+  // No names asserted publicly means nothing to verify — and no reason to
+  // reach the network or advance an undetermined counter.
+  if (deps.records.length === 0) return [];
+
+  const now = deps.now ?? new Date();
+  const threshold = deps.undeterminedThreshold ?? DEFAULT_UNDETERMINED_THRESHOLD;
+  const previous = new Map((deps.evidence ?? []).map((e) => [e.subject, e.undeterminedRuns]));
+  const next = new Map<string, number>();
+  const findings: DriftFinding[] = [];
+
+  /**
+   * Count an absence of evidence. The first few are silent — one prober blip
+   * must not page — but they are never forgotten, which is the difference
+   * between "we were not told" and "we could not have been told".
+   */
+  const countUndetermined = (subject: string): number => {
+    const runs = (previous.get(subject) ?? 0) + 1;
+    next.set(subject, runs);
+    return runs;
+  };
+
+  const ingress = await deps.probe.observeIngress();
+
+  if (ingress.kind === 'undetermined') {
+    const runs = countUndetermined(ECHO_SUBJECT);
+    // Every name is unverifiable when the expectation is, so the records are
+    // left uncounted rather than each accruing a duplicate of the same outage.
+    if (runs >= threshold) {
+      findings.push({
+        category: 'public_dns',
+        severity: 'drift',
+        code: 'public_dns_unverifiable',
+        message: `Public DNS has been unverifiable for ${runs} consecutive checks`,
+        details: `The echo service (${deps.probe.echoService}) could not be reached, so there is no\nexpectation to compare public DNS against. Latest reason: ${ingress.reason}.\n\nThis is NOT a report that the fleet is reachable, and not a report that it\nis unreachable — it is a report that nothing is currently checking. The\noutage this check exists for ran for nine days behind exactly this silence.`,
+        remediation: [
+          'Check outbound connectivity from the management host, then:',
+          `  celilo system config set public_dns.echo_url <url>   # current: ${deps.probe.echoService}`,
+        ].join('\n'),
+        actionable: false,
+        subject: ECHO_SUBJECT,
+      });
+    }
+    deps.saveEvidence?.(toEvidence(next));
+    return findings;
+  }
+
+  for (const record of deps.records) {
+    const resolution = await deps.probe.resolve(record.fqdn);
+
+    if (resolution.kind === 'undetermined') {
+      const runs = countUndetermined(record.fqdn);
+      if (runs >= threshold) {
+        findings.push({
+          category: 'public_dns',
+          severity: 'drift',
+          code: 'public_dns_unverifiable',
+          message: `${record.fqdn}: public reachability unverifiable for ${runs} consecutive checks`,
+          details: `${deps.probe.resolver} did not answer for this name. Latest reason: ${resolution.reason}.\nWhether the name resolves publicly is currently unknown — which is not the\nsame as it being fine.`,
+          remediation: `Resolve it by hand to see what the internet gets:\n  dig @${deps.probe.resolver} ${record.fqdn} A`,
+          actionable: false,
+          subject: record.fqdn,
+        });
+      }
+      continue;
+    }
+
+    if (resolution.kind === 'no_record') {
+      findings.push(
+        record.companion
+          ? {
+              category: 'public_dns',
+              severity: 'drift',
+              code: 'public_dns_companion_unclaimed',
+              message: `${record.fqdn}: not published (companion of a name celilo serves)`,
+              details:
+                'This name has no public A record, so it does not reach the fleet at all.\n' +
+                'A working www beside a dead apex (or the reverse) is the same defect as\n' +
+                'celilo#626 in miniature: publicly broken, locally invisible.',
+              remediation: companionRemediation(record.fqdn),
+              actionable: false,
+              subject: record.fqdn,
+            }
+          : {
+              category: 'public_dns',
+              severity: 'drift',
+              code: 'public_dns_missing',
+              message: `${record.fqdn}: no public A record`,
+              details: `celilo registered this name but ${deps.probe.resolver} resolves no A record for\nit. The registrar reported success; a provider's success response is a claim\nabout an API call, not evidence that the record was published.`,
+              remediation: `Re-assert it, then re-check:\n  celilo module run-hook <registrar> refresh_registrations\n  dig @${deps.probe.resolver} ${record.fqdn} A`,
+              actionable: false,
+              subject: record.fqdn,
+            },
+      );
+      continue;
+    }
+
+    if (resolution.ip === ingress.ip) continue;
+
+    // Hysteresis. A legitimate address change produces a genuinely divergent
+    // public record until the old answer's TTL expires, so a divergence is only
+    // a finding once it has outlived the TTL of the record we last asserted.
+    // Without this the check pages on every ISP re-lease.
+    const ttlSeconds = resolution.ttlSeconds > 0 ? resolution.ttlSeconds : FALLBACK_TTL_SECONDS;
+    const settledAt = record.lastAssertedAt.getTime() + ttlSeconds * 1000;
+    if (now.getTime() < settledAt) continue;
+
+    findings.push(
+      record.companion
+        ? {
+            category: 'public_dns',
+            severity: 'drift',
+            code: 'public_dns_companion_unclaimed',
+            message: `${record.fqdn}: publicly resolves to ${resolution.ip}, not ${ingress.ip}`,
+            details: `${deps.probe.resolver} serves ${resolution.ip} for this companion name while the fleet is\nreachable at ${ingress.ip} (per ${deps.probe.echoService}). A parked or redirect record is\nthe usual cause: Namecheap renders those as A records the DDNS endpoint\naccepts updates for and does not apply, reporting ErrCount 0 (design.md D3).`,
+            remediation: companionRemediation(record.fqdn),
+            actionable: false,
+            subject: record.fqdn,
+          }
+        : {
+            category: 'public_dns',
+            severity: 'drift',
+            code: 'public_dns_stale',
+            message: `${record.fqdn}: publicly resolves to ${resolution.ip}, not ${ingress.ip}`,
+            details: `${deps.probe.resolver} serves ${resolution.ip} for this name while the fleet is reachable at\n${ingress.ip} (per ${deps.probe.echoService}). The divergence has outlived the record's own\nTTL (${ttlSeconds}s since the last assert), so this is not propagation.\n\nNothing inside the fleet can see this: the split-horizon resolver answers\nwith an address that IS reachable in-zone, which is correct for its purpose\nand says nothing about the public internet.`,
+            remediation: `Re-assert the record, then re-check:\n  celilo module run-hook <registrar> refresh_registrations\n  dig @${deps.probe.resolver} ${record.fqdn} A`,
+            actionable: false,
+            subject: record.fqdn,
+          },
+    );
+  }
+
+  deps.saveEvidence?.(toEvidence(next));
+  return findings;
+}
+
+/**
+ * Only subjects that were undetermined THIS run survive. A subject that
+ * answered has no counter, which is what makes the count "consecutive".
+ */
+function toEvidence(next: Map<string, number>): PublicDnsEvidence[] {
+  return [...next].map(([subject, undeterminedRuns]) => ({ subject, undeterminedRuns }));
+}

package/src/services/audit/types.ts

@@ -37,6 +37,7 @@ export type DriftCategory =
   | 'secrets_decryptable'
   | 'services_reachable'
   | 'machines_reachable'
+  | 'public_dns'
   | 'disk_space'
   | 'transport_reads'
   | 'trusted_sources';

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,75 @@
  *
  * 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.
+ *
+ * It CHECKS before deleting, so the overwhelmingly common case (nothing
+ * orphaned) stays a pure read. The first version ran the DELETE
+ * unconditionally, which took a write lock on every list — including the
+ * refresh hook's, and `celilo dns registrations`. A read that quietly writes
+ * is a surprise on its own, and on SQLite it is a surprise that serialises
+ * against every other writer for no benefit.
+ */
+function pruneOrphanedRegistrations(db: DbClient): void {
+  const orphaned = sql`SELECT 1 FROM dns_registrations WHERE NOT EXISTS (
+      SELECT 1 FROM dns_registration_consumers c WHERE c.registration_id = dns_registrations.id
+    ) LIMIT 1`;
+  if (!db.get(orphaned)) return;
+
+  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 +80,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,25 +113,45 @@ 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();
 }
 
@@ -85,6 +168,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 +191,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;
     },