@serve.zone/dcrouter 16.4.1 → 17.0.0

package/ts/email/classes.mail-dns-sync.ts

@@ -1,218 +1,985 @@
+import * as plugins from '../plugins.js';
 import { logger } from '../logger.js';
 import { DnsRecordDoc } from '../db/documents/classes.dns-record.doc.js';
 import { DomainDoc } from '../db/documents/classes.domain.doc.js';
 import { EmailDomainDoc } from '../db/documents/classes.email-domain.doc.js';
 import type { DcRouter } from '../classes.dcrouter.js';
-import type { IRemoteIngress } from '../../ts_interfaces/data/remoteingress.js';
+import type {
+  IEmailDnsRecordIntent,
+  IEmailDomainDnsRevision,
+  IEmailDomainEdgeIdentity,
+  IEmailDomainMxSlot,
+  IEmailDomainOperationError,
+  IEmailDkimMaterial,
+} from '../../ts_interfaces/data/email-domain.js';
+import type { TDnsRecordType } from '../../ts_interfaces/data/dns-record.js';
+import {
+  MailEdgeEligibility,
+  ReleasedRemoteIngressEgressIdentitySource,
+  type IEligibleMailEdge,
+} from './classes.mail-edge-eligibility.js';
 
-export const MAIL_DNS_SYNC_CREATED_BY = 'mail-edge-sync';
+export const MAIL_DNS_SYNC_CREATED_BY = 'mail-dns-reconciler';
+export const MAIL_DNS_MANAGED_BY = 'mail-dns-reconciler';
+export const MAIL_DNS_RETRY_INTERVAL_MS = 5 * 60_000;
 
-interface IDesiredMailDnsRecord {
-  name: string;
-  type: 'A' | 'AAAA';
-  value: string;
+
+export interface IMailDnsVerificationResult {
+  valid: boolean;
+  reason?: string;
+}
+
+export interface IMailDnsVerifier {
+  verifyRecord(intent: IEmailDnsRecordIntent): Promise<IMailDnsVerificationResult>;
+  verifyMxSet?(intents: IEmailDnsRecordIntent[]): Promise<IMailDnsVerificationResult>;
+  verifyForwardConfirmedIdentity(
+    identity: IEmailDomainEdgeIdentity,
+  ): Promise<IMailDnsVerificationResult>;
+  destroy?(): void;
+}
+
+function normalizeHostname(value: string): string {
+  return value.trim().toLowerCase().replace(/\.$/, '');
+}
+
+function normalizeMx(value: string): string {
+  const [priority, exchange = ''] = value.trim().split(/\s+/);
+  return `${Number(priority)} ${normalizeHostname(exchange)}`;
+}
+
+function expandIpv6(address: string): string[] | undefined {
+  let normalized = address.toLowerCase();
+  if (normalized.includes('.')) {
+    const lastColon = normalized.lastIndexOf(':');
+    const ipv4 = normalized.slice(lastColon + 1).split('.').map(Number);
+    if (ipv4.length !== 4 || ipv4.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+      return undefined;
+    }
+    normalized = `${normalized.slice(0, lastColon)}:${((ipv4[0] << 8) | ipv4[1]).toString(16)}:${((ipv4[2] << 8) | ipv4[3]).toString(16)}`;
+  }
+  const halves = normalized.split('::');
+  if (halves.length > 2) return undefined;
+  const left = halves[0] ? halves[0].split(':') : [];
+  const right = halves[1] ? halves[1].split(':') : [];
+  const missing = 8 - left.length - right.length;
+  if ((halves.length === 1 && missing !== 0) || missing < 0) return undefined;
+  const groups = [...left, ...Array.from({ length: missing }, () => '0'), ...right];
+  if (groups.length !== 8 || groups.some((group) => !/^[0-9a-f]{1,4}$/.test(group))) return undefined;
+  return groups.map((group) => group.padStart(4, '0'));
+}
+
+export function toReverseDnsName(address: string): string {
+  const family = plugins.smartnetwork.getIpVersion(address);
+  if (family === 4) {
+    return `${address.split('.').reverse().join('.')}.in-addr.arpa`;
+  }
+  if (family === 6) {
+    const groups = expandIpv6(address);
+    if (!groups) throw new Error(`Invalid IPv6 address: ${address}`);
+    return `${groups.join('').split('').reverse().join('.')}.ip6.arpa`;
+  }
+  throw new Error(`Invalid IP address: ${address}`);
+}
+
+export class SmartDnsMailVerifier implements IMailDnsVerifier {
+  private client?: plugins.smartdns.dnsClientMod.Smartdns;
+
+  private getClient(): plugins.smartdns.dnsClientMod.Smartdns {
+    this.client ||= new plugins.smartdns.dnsClientMod.Smartdns({});
+    return this.client;
+  }
+
+  public async verifyRecord(intent: IEmailDnsRecordIntent): Promise<IMailDnsVerificationResult> {
+    try {
+      const records = await this.getClient().getRecords(intent.name, intent.type);
+      const values = (records || []).map((record) => String(record.value).trim());
+      if (intent.type === 'MX') {
+        return values.some((value) => normalizeMx(value) === normalizeMx(intent.value))
+          ? { valid: true }
+          : { valid: false, reason: `MX ${intent.value} has not propagated` };
+      }
+      if (intent.type === 'TXT') {
+        const exact = values.filter((value) => value === intent.value.trim());
+        const relevant = intent.value.startsWith('v=spf1')
+          ? values.filter((value) => value.toLowerCase().startsWith('v=spf1'))
+          : intent.value.startsWith('v=DMARC1')
+            ? values.filter((value) => value.toLowerCase().startsWith('v=dmarc1'))
+            : values;
+        return exact.length === 1 && relevant.length === 1
+          ? { valid: true }
+          : { valid: false, reason: `TXT ${intent.name} is missing, conflicting, or duplicated` };
+      }
+      const exact = values.filter((value) => normalizeHostname(value) === normalizeHostname(intent.value));
+      return exact.length === 1 && values.length === 1
+        ? { valid: true }
+        : { valid: false, reason: `${intent.type} ${intent.name} is missing, conflicting, or duplicated` };
+    } catch (error: unknown) {
+      return { valid: false, reason: `DNS lookup failed: ${(error as Error).message}` };
+    }
+  }
+
+  public async verifyMxSet(intents: IEmailDnsRecordIntent[]): Promise<IMailDnsVerificationResult> {
+    if (intents.length === 0) return { valid: false, reason: 'No desired MX records' };
+    try {
+      const records = await this.getClient().getRecords(intents[0].name, 'MX');
+      const actual = (records || []).map((record) => normalizeMx(String(record.value))).sort();
+      const desired = intents.map((intent) => normalizeMx(intent.value)).sort();
+      return actual.length === desired.length && actual.every((value, index) => value === desired[index])
+        ? { valid: true }
+        : {
+            valid: false,
+            reason: `MX set for ${intents[0].name} does not exactly match priorities and exchanges`,
+          };
+    } catch (error: unknown) {
+      return { valid: false, reason: `MX lookup failed: ${(error as Error).message}` };
+    }
+  }
+
+  public async verifyForwardConfirmedIdentity(
+    identity: IEmailDomainEdgeIdentity,
+  ): Promise<IMailDnsVerificationResult> {
+    const checks: Array<{ family: 'A' | 'AAAA'; address: string }> = [];
+    if (identity.ipv4) checks.push({ family: 'A', address: identity.ipv4 });
+    if (identity.ipv6) checks.push({ family: 'AAAA', address: identity.ipv6 });
+    try {
+      for (const check of checks) {
+        const ptrRecords = await this.getClient().getRecords(toReverseDnsName(check.address), 'PTR');
+        const ptrNames = (ptrRecords || []).map((record) => normalizeHostname(String(record.value)));
+        if (ptrNames.length !== 1 || ptrNames[0] !== normalizeHostname(identity.hostname)) {
+          return {
+            valid: false,
+            reason: `PTR for ${check.address} must be exactly ${identity.hostname}`,
+          };
+        }
+        const forwardRecords = await this.getClient().getRecords(identity.hostname, check.family);
+        const forwardIps = (forwardRecords || []).map((record) => String(record.value));
+        if (!forwardIps.includes(check.address)) {
+          return {
+            valid: false,
+            reason: `${check.family} ${identity.hostname} does not resolve back to ${check.address}`,
+          };
+        }
+      }
+      return checks.length > 0
+        ? { valid: true }
+        : { valid: false, reason: `No source-bound address is available for ${identity.edgeId}` };
+    } catch (error: unknown) {
+      return { valid: false, reason: `FCrDNS lookup failed: ${(error as Error).message}` };
+    }
+  }
+
+  public destroy(): void {
+    this.client?.destroy();
+    this.client = undefined;
+  }
+}
+
+interface IPlannedDomain {
+  doc: EmailDomainDoc;
+  revision: IEmailDomainDnsRevision;
+  intents: IEmailDnsRecordIntent[];
+  preliminaryErrors: IEmailDomainOperationError[];
+  egressIdentitySupported: boolean;
+  selectorCorrectSigningSupported: boolean;
 }
 
 /**
- * Reconciles the mail-facing A/AAAA records that make edges — never the hub —
- * the public identity of the mail platform:
- *  (a) shared mail hostname → publicIp/publicIpV6 of every enabled mail edge,
- *  (b) each edge's mailHostname → that edge's IPs (FCrDNS for outbound EHLO),
- *  (c) mx.<domain> → the pinned edges' IPs for every pinned email domain.
- * Records are DB-backed DnsRecordDoc rows owned via createdBy 'mail-edge-sync';
- * provider-hosted zones (e.g. Cloudflare) are written through DnsManager's
- * provider path, dcrouter-authoritative zones serve immediately.
+ * Sole owner of managed mail DNS. API, topology, timer, and startup events only
+ * mark this globally serialized reconciler dirty.
  */
 export class MailDnsSync {
-  private syncInFlight?: Promise<void>;
-  private resyncQueued = false;
+  private started = false;
+  private stopped = false;
+  private dirty = false;
+  private runPromise?: Promise<void>;
+  private retryTimer?: ReturnType<typeof setInterval>;
+  private edgeEligibility: MailEdgeEligibility;
+
+  constructor(
+    private dcRouterRef: DcRouter,
+    edgeEligibility?: MailEdgeEligibility,
+    private verifier: IMailDnsVerifier = new SmartDnsMailVerifier(),
+  ) {
+    this.edgeEligibility = edgeEligibility
+      || dcRouterRef.mailEdgeEligibility
+      || new MailEdgeEligibility(dcRouterRef, new ReleasedRemoteIngressEgressIdentitySource(dcRouterRef));
+  }
+
+  public async start(): Promise<void> {
+    if (this.started) {
+      await this.runPromise;
+      return;
+    }
+    this.started = true;
+    this.stopped = false;
+    this.retryTimer = setInterval(() => this.requestSync('periodic retry'), MAIL_DNS_RETRY_INTERVAL_MS);
+    this.dirty = true;
+    try {
+      await this.kick('startup');
+    } catch (error: unknown) {
+      if (this.retryTimer) clearInterval(this.retryTimer);
+      this.retryTimer = undefined;
+      this.started = false;
+      this.dirty = false;
+      throw error;
+    }
+  }
 
-  constructor(private dcRouterRef: DcRouter) {}
+  public async stop(): Promise<void> {
+    this.stopped = true;
+    this.started = false;
+    this.dirty = false;
+    if (this.retryTimer) {
+      clearInterval(this.retryTimer);
+      this.retryTimer = undefined;
+    }
+    await this.runPromise?.catch(() => undefined);
+    this.verifier.destroy?.();
+  }
 
-  /** Fire-and-forget trigger for CRUD hooks; failures are logged, not thrown. */
   public requestSync(reason: string): void {
-    this.sync(reason).catch((err: unknown) => {
-      logger.log('error', `MailDnsSync failed (${reason}): ${(err as Error).message}`);
+    if (this.stopped) return;
+    this.dirty = true;
+    if (!this.started) return;
+    this.kick(reason).catch((error: unknown) => {
+      logger.log('error', `MailDnsSync failed (${reason}): ${(error as Error).message}`);
     });
   }
 
-  /** Coalescing entry point: concurrent triggers fold into one follow-up pass. */
+  /** Coalescing entry point used by API actions that need the durable outcome. */
   public async sync(reason: string): Promise<void> {
-    if (this.syncInFlight) {
-      this.resyncQueued = true;
-      return this.syncInFlight;
-    }
-    this.syncInFlight = this.reconcile(reason).finally(() => {
-      this.syncInFlight = undefined;
-      if (this.resyncQueued) {
-        this.resyncQueued = false;
-        this.requestSync(`${reason} (coalesced)`);
+    if (this.stopped) throw new Error('MailDnsSync is stopped');
+    this.dirty = true;
+    await this.kick(reason);
+  }
+
+  private async kick(reason: string): Promise<void> {
+    if (this.runPromise) return await this.runPromise;
+    // Defer execution one microtask so runPromise is assigned before the first
+    // awaited provider/eligibility hook can synchronously enqueue another event.
+    this.runPromise = Promise.resolve().then(() => this.runLoop(reason, false)).finally(() => {
+      this.runPromise = undefined;
+      if (this.dirty && this.started && !this.stopped) {
+        this.requestSync(`${reason} (follow-up)`);
       }
     });
-    return this.syncInFlight;
+    return await this.runPromise;
+  }
+
+  private async runLoop(reason: string, singlePass: boolean): Promise<void> {
+    do {
+      this.dirty = false;
+      await this.reconcile(reason);
+      if (singlePass) break;
+      // An event during the run leaves dirty=true and forces exactly one
+      // immediate follow-up; repeated events coalesce into that pass.
+    } while (this.dirty && !this.stopped);
   }
 
   private async reconcile(reason: string): Promise<void> {
-    if (this.dcRouterRef.options.dbConfig?.enabled === false) {
-      return;
-    }
+    if (this.dcRouterRef.options.dbConfig?.enabled === false) return;
     const dnsManager = this.dcRouterRef.dnsManager;
-    const remoteIngressManager = this.dcRouterRef.remoteIngressManager;
-    if (!dnsManager || !remoteIngressManager) {
-      // Without both managers the edge registry / record store is not
-      // authoritative — skip entirely rather than delete managed records.
+    if (!dnsManager) {
+      logger.log('warn', `MailDnsSync (${reason}): DnsManager unavailable; retry intent retained`);
       return;
     }
 
-    const desired = await this.computeDesiredRecords();
-    const zones = await DomainDoc.findAll();
+    // Refresh the broad operational status independently from per-domain pins.
+    await this.edgeEligibility.resolveForDomain();
 
-    // Place each desired record in its zone (longest-suffix match). Records
-    // without a managed zone are reported — the operator must onboard the zone.
-    const placed = new Map<string, { domainId: string; record: IDesiredMailDnsRecord }>();
-    const unplacedNames = new Set<string>();
-    for (const record of desired) {
-      const zone = this.findZoneForName(record.name, zones);
-      if (!zone) {
-        unplacedNames.add(record.name);
+    const zones = await DomainDoc.findAll();
+    const docs = await EmailDomainDoc.findAll();
+    const plans: IPlannedDomain[] = [];
+    for (const loadedDoc of docs) {
+      const doc = await this.dcRouterRef.emailDomainManager?.stageDkimRotationIfDue?.(loadedDoc.id)
+        || loadedDoc;
+      if (doc.reconciliation?.lifecycleStatus === 'deleting') {
+        await this.persistDeletingAttempt(doc);
         continue;
       }
-      placed.set(`${zone.id}|${record.name}|${record.type}|${record.value}`, {
-        domainId: zone.id,
-        record,
+      const plan = await this.buildPlan(doc, zones);
+      await this.persistDesiredPlan(plan);
+      plans.push(plan);
+    }
+
+    const uniqueIntents = new Map<string, IEmailDnsRecordIntent>();
+    for (const plan of plans) {
+      for (const intent of plan.intents) {
+        uniqueIntents.set(intent.key, intent);
+      }
+    }
+
+    const zoneErrors = await this.reconcileZones([...uniqueIntents.values()], zones);
+    for (const plan of plans) {
+      const errors = [...plan.preliminaryErrors];
+      for (const intent of plan.intents) {
+        const outcome = uniqueIntents.get(intent.key);
+        if (outcome) Object.assign(intent, outcome);
+        if (intent.error) errors.push(intent.error);
+      }
+      await this.validateAndActivate(plan, errors, zoneErrors);
+    }
+
+    await this.cleanupStaleManagedRecords(zones);
+    await this.finalizeDeletingDomains();
+    await this.dcRouterRef.emailDomainManager?.syncManagedDomainsToRuntime();
+    await this.dcRouterRef.workAppMailManager?.applyStoredIdentitiesToRuntime();
+  }
+
+  private async buildPlan(doc: EmailDomainDoc, zones: DomainDoc[]): Promise<IPlannedDomain> {
+    const now = new Date().toISOString();
+    const eligibility = await this.edgeEligibility.resolveForDomain(doc);
+    const preliminaryErrors: IEmailDomainOperationError[] = [
+      ...(doc.reconciliation?.errors || []).filter((error) => error.code === 'DKIM_ROTATION_STAGE_FAILED'),
+    ];
+    if (!eligibility.supported) {
+      preliminaryErrors.push({
+        code: 'EGRESS_IDENTITY_PROOF_UNAVAILABLE',
+        message: eligibility.reason || 'RemoteIngress egress identity proof is unavailable',
+        retryable: true,
+      });
+    } else if (eligibility.edges.length === 0) {
+      preliminaryErrors.push({
+        code: 'NO_ELIGIBLE_MAIL_EDGE',
+        message: eligibility.reason || 'No eligible mail edge is connected',
+        retryable: true,
       });
     }
-    for (const name of unplacedNames) {
-      logger.log('warn', `MailDnsSync: no managed DNS zone covers ${name} — record skipped`);
+
+    const activeDkim = this.getActiveDkim(doc);
+    const upstreamSelectorCapability = this.dcRouterRef.emailDomainManager?.supportsSelectorCorrectSigning?.() === true;
+    const selectorCorrectSigningSupported = (
+      (!activeDkim || activeDkim.selector === 'default') && !doc.pendingDkim
+    ) || upstreamSelectorCapability;
+    if (!activeDkim) {
+      preliminaryErrors.push({
+        code: 'DKIM_KEY_UNAVAILABLE',
+        message: `No usable active DKIM key exists for ${doc.domain}`,
+        retryable: false,
+      });
+    } else if (!selectorCorrectSigningSupported) {
+      preliminaryErrors.push({
+        code: 'SMARTMTA_SELECTOR_SIGNING_UNSUPPORTED',
+        message: 'The consumed SmartMTA release cannot safely sign with a non-default selector',
+        retryable: false,
+      });
     }
 
-    const existing = (await DnsRecordDoc.findAll())
-      .filter((record) => record.createdBy === MAIL_DNS_SYNC_CREATED_BY);
+    const edgeIdentities = eligibility.edges.map((candidate) => this.toDomainEdgeIdentity(candidate));
+    const mxSlots = this.allocateMxSlots(doc, eligibility.edges);
+    if (eligibility.edges.length >= 2 && mxSlots.length < 2) {
+      preliminaryErrors.push({
+        code: 'INSUFFICIENT_DISTINCT_MX_IDENTITIES',
+        message: 'At least two eligible mail edges exist but they do not provide two distinct MX hostnames',
+        retryable: false,
+      });
+    }
+    const revisionId = plugins.smartunique.shortId();
+    const intents: IEmailDnsRecordIntent[] = [];
 
-    let created = 0;
-    let deleted = 0;
+    for (const candidate of eligibility.edges) {
+      for (const identity of candidate.identities) {
+        const type = identity.family === 4 ? 'A' : 'AAAA';
+        intents.push(this.intentForName(zones, {
+          key: `mail-topology:${candidate.edge.id}:${type}:${candidate.hostname}:${identity.address}`,
+          ownerType: 'topology',
+          ownerId: `topology:${candidate.edge.id}`,
+          name: candidate.hostname,
+          type,
+          value: identity.address,
+          ttl: 300,
+        }));
+      }
+    }
 
-    for (const record of existing) {
-      const key = `${record.domainId}|${record.name}|${record.type}|${record.value}`;
-      if (placed.has(key)) {
-        placed.delete(key); // already present — nothing to create
-        continue;
+    if (eligibility.edges.length > 0) {
+      for (const slot of mxSlots) {
+        intents.push(this.intentForName(zones, {
+          key: `mail-domain:${doc.id}:mx:${slot.priority}:${slot.edgeId}:${slot.hostname}`,
+          ownerType: 'domain',
+          ownerId: `domain:${doc.id}`,
+          name: doc.domain,
+          type: 'MX',
+          value: `${slot.priority} ${slot.hostname}`,
+          ttl: 300,
+        }));
       }
-      const result = await dnsManager.deleteRecord(record.id);
-      if (result.success) {
-        deleted++;
-      } else {
-        logger.log('warn', `MailDnsSync: failed to delete stale ${record.type} ${record.name} → ${record.value}: ${result.message}`);
+      const spfIdentities = [
+        ...edgeIdentities,
+        ...(doc.reconciliation?.activeRevision?.edgeIdentities || []),
+      ];
+      intents.push(this.intentForName(zones, {
+        key: `mail-domain:${doc.id}:spf`,
+        ownerType: 'domain',
+        ownerId: `domain:${doc.id}`,
+        name: doc.domain,
+        type: 'TXT',
+        value: this.buildSpfValue(spfIdentities),
+        ttl: 300,
+      }));
+    }
+
+    if (activeDkim) intents.push(this.buildDkimIntent(doc, activeDkim, zones));
+    if (doc.pendingDkim) intents.push(this.buildDkimIntent(doc, doc.pendingDkim, zones));
+    for (const retiring of doc.retiringDkim || []) {
+      if (!retiring.retireAfter || Date.parse(retiring.retireAfter) > Date.now()) {
+        intents.push(this.buildDkimIntent(doc, retiring, zones));
       }
     }
+    intents.push(this.intentForName(zones, {
+      key: `mail-domain:${doc.id}:dmarc`,
+      ownerType: 'domain',
+      ownerId: `domain:${doc.id}`,
+      name: `_dmarc.${doc.domain}`,
+      type: 'TXT',
+      value: `v=DMARC1; p=none; rua=mailto:dmarc@${doc.domain}`,
+      ttl: 3600,
+    }));
 
-    for (const { domainId, record } of placed.values()) {
-      const result = await dnsManager.createRecord({
-        domainId,
-        name: record.name,
-        type: record.type,
-        value: record.value,
-        // Short TTL: edge IPs are burnable identities and failover heals via DNS.
-        ttl: 300,
-        createdBy: MAIL_DNS_SYNC_CREATED_BY,
-      });
-      if (result.success) {
-        created++;
-      } else {
-        logger.log('warn', `MailDnsSync: failed to create ${record.type} ${record.name} → ${record.value}: ${result.message}`);
+    for (const intent of intents) {
+      if (!intent.domainId) {
+        intent.status = 'failed';
+        intent.error = {
+          code: 'DNS_ZONE_UNMANAGED',
+          message: `No managed DNS zone covers ${intent.name}`,
+          recordKey: intent.key,
+          retryable: false,
+        };
       }
     }
+    const revision: IEmailDomainDnsRevision = {
+      id: revisionId,
+      createdAt: now,
+      selector: doc.pendingDkim?.selector || activeDkim?.selector || doc.dkim.selector || 'default',
+      edgeIdentities,
+      mxSlots,
+      recordKeys: intents.map((intent) => intent.key),
+    };
+    return {
+      doc,
+      revision,
+      intents,
+      preliminaryErrors,
+      egressIdentitySupported: eligibility.supported,
+      selectorCorrectSigningSupported,
+    };
+  }
+
+  private getActiveDkim(doc: EmailDomainDoc): IEmailDkimMaterial | undefined {
+    if (doc.activeDkim?.publicKey) return doc.activeDkim;
+    const publicKey = doc.dkim?.publicKey?.trim();
+    if (!publicKey) return undefined;
+    return {
+      selector: doc.dkim.selector || 'default',
+      keySize: doc.dkim.keySize || 2048,
+      publicKey,
+      createdAt: doc.createdAt,
+    };
+  }
 
-    if (created > 0 || deleted > 0) {
-      logger.log('info', `MailDnsSync (${reason}): ${created} record(s) created, ${deleted} deleted`);
+  private buildDkimIntent(
+    doc: EmailDomainDoc,
+    material: IEmailDkimMaterial,
+    zones: DomainDoc[],
+  ): IEmailDnsRecordIntent {
+    return this.intentForName(zones, {
+      key: `mail-domain:${doc.id}:dkim:${material.selector}`,
+      ownerType: 'domain',
+      ownerId: `domain:${doc.id}`,
+      name: `${material.selector}._domainkey.${doc.domain}`,
+      type: 'TXT',
+      value: `v=DKIM1; h=sha256; k=rsa; p=${material.publicKey}`,
+      ttl: 3600,
+    });
+  }
+
+  private intentForName(
+    zones: DomainDoc[],
+    input: Omit<IEmailDnsRecordIntent, 'domainId' | 'status'>,
+  ): IEmailDnsRecordIntent {
+    return {
+      ...input,
+      domainId: this.findZoneForName(input.name, zones)?.id || '',
+      status: 'pending',
+    };
+  }
+
+  private toDomainEdgeIdentity(candidate: IEligibleMailEdge): IEmailDomainEdgeIdentity {
+    const ipv4 = candidate.identities.find((identity) => identity.family === 4);
+    const ipv6 = candidate.identities.find((identity) => identity.family === 6);
+    const observedAt = Math.min(...candidate.identities.map((identity) => identity.observedAt));
+    const hubReceivedAt = Math.min(...candidate.identities.map((identity) => identity.hubReceivedAt));
+    return {
+      edgeId: candidate.edge.id,
+      hostname: candidate.hostname,
+      ...(ipv4 ? { ipv4: ipv4.address } : {}),
+      ...(ipv6 ? { ipv6: ipv6.address } : {}),
+      observedAt: new Date(observedAt).toISOString(),
+      hubReceivedAt: new Date(hubReceivedAt).toISOString(),
+    };
+  }
+
+  private allocateMxSlots(doc: EmailDomainDoc, candidates: IEligibleMailEdge[]): IEmailDomainMxSlot[] {
+    if (candidates.length === 1) {
+      return [{
+        priority: 10,
+        edgeId: candidates[0].edge.id,
+        hostname: candidates[0].hostname,
+      }];
+    }
+    const byId = new Map(candidates.map((candidate) => [candidate.edge.id, candidate]));
+    const result: IEmailDomainMxSlot[] = [];
+    const usedEdges = new Set<string>();
+    const usedHostnames = new Set<string>();
+    const previous = [
+      ...(doc.reconciliation?.activeRevision?.mxSlots || []),
+      ...(doc.reconciliation?.pendingRevision?.mxSlots || []),
+    ];
+    for (const priority of [10, 20] as const) {
+      const old = previous.find((slot) => slot.priority === priority);
+      const candidate = old ? byId.get(old.edgeId) : undefined;
+      if (!candidate || candidate.hostname !== old?.hostname) continue;
+      if (usedEdges.has(candidate.edge.id) || usedHostnames.has(candidate.hostname)) continue;
+      result.push({ priority, edgeId: candidate.edge.id, hostname: candidate.hostname });
+      usedEdges.add(candidate.edge.id);
+      usedHostnames.add(candidate.hostname);
     }
+    for (const priority of [10, 20] as const) {
+      if (result.some((slot) => slot.priority === priority)) continue;
+      const candidate = candidates.find((entry) => (
+        !usedEdges.has(entry.edge.id) && !usedHostnames.has(entry.hostname)
+      ));
+      if (!candidate) continue;
+      result.push({ priority, edgeId: candidate.edge.id, hostname: candidate.hostname });
+      usedEdges.add(candidate.edge.id);
+      usedHostnames.add(candidate.hostname);
+    }
+    return result.sort((left, right) => left.priority - right.priority);
   }
 
-  private async computeDesiredRecords(): Promise<IDesiredMailDnsRecord[]> {
-    const remoteIngressManager = this.dcRouterRef.remoteIngressManager!;
-    const desired: IDesiredMailDnsRecord[] = [];
+  private buildSpfValue(identities: IEmailDomainEdgeIdentity[]): string {
+    const terms = new Set<string>();
+    for (const identity of identities) {
+      if (identity.ipv4) terms.add(`ip4:${identity.ipv4}`);
+      if (identity.ipv6) terms.add(`ip6:${identity.ipv6}`);
+    }
+    return `v=spf1 ${[...terms].sort().join(' ')} -all`.replace(/\s+/g, ' ').trim();
+  }
 
-    const pushEdgeIps = (name: string | undefined, edge: IRemoteIngress) => {
-      if (!name) return;
-      const normalizedName = name.toLowerCase();
-      if (edge.publicIp) {
-        desired.push({ name: normalizedName, type: 'A', value: edge.publicIp });
-      }
-      if (edge.publicIpV6) {
-        desired.push({ name: normalizedName, type: 'AAAA', value: edge.publicIpV6 });
+  private async persistDesiredPlan(plan: IPlannedDomain): Promise<void> {
+    const previous = plan.doc.reconciliation;
+    const previousSignature = JSON.stringify((previous?.intents || []).map((intent) => [intent.key, intent.value]));
+    const nextSignature = JSON.stringify(plan.intents.map((intent) => [intent.key, intent.value]));
+    const generation = (previous?.desiredGeneration || 0) + (previousSignature === nextSignature ? 0 : 1);
+    plan.doc.reconciliation = {
+      lifecycleStatus: previous?.lifecycleStatus === 'active' ? 'active' : 'pending',
+      desiredGeneration: Math.max(generation, 1),
+      activeRevision: previous?.activeRevision,
+      pendingRevision: plan.revision,
+      intents: plan.intents,
+      errors: plan.preliminaryErrors,
+      capability: {
+        egressIdentityProof: plan.egressIdentitySupported ? 'supported' : 'unsupported',
+        selectorCorrectSigning: plan.selectorCorrectSigningSupported ? 'supported' : 'unsupported',
+      },
+      lastAttemptAt: new Date().toISOString(),
+      retryAt: new Date(Date.now() + MAIL_DNS_RETRY_INTERVAL_MS).toISOString(),
+    };
+    plan.doc.updatedAt = new Date().toISOString();
+    await plan.doc.save();
+  }
+
+  private async persistDeletingAttempt(doc: EmailDomainDoc): Promise<void> {
+    doc.reconciliation = {
+      ...(doc.reconciliation || {
+        lifecycleStatus: 'deleting',
+        desiredGeneration: 1,
+        intents: [],
+        errors: [],
+      }),
+      lifecycleStatus: 'deleting',
+      intents: [],
+      errors: (doc.reconciliation?.errors || []).filter((error) => error.code !== 'DNS_CLEANUP_FAILED'),
+      lastAttemptAt: new Date().toISOString(),
+      retryAt: new Date(Date.now() + MAIL_DNS_RETRY_INTERVAL_MS).toISOString(),
+    };
+    await doc.save();
+  }
+
+  private async reconcileZones(
+    intents: IEmailDnsRecordIntent[],
+    zones: DomainDoc[],
+  ): Promise<Map<string, IEmailDomainOperationError>> {
+    const errors = new Map<string, IEmailDomainOperationError>();
+    const byZone = new Map<string, IEmailDnsRecordIntent[]>();
+    for (const intent of intents) {
+      if (!intent.domainId || intent.error) continue;
+      const group = byZone.get(intent.domainId) || [];
+      group.push(intent);
+      byZone.set(intent.domainId, group);
+    }
+    for (const [zoneId, zoneIntents] of byZone) {
+      const zone = zones.find((candidate) => candidate.id === zoneId);
+      if (!zone) continue;
+      try {
+        if (zone.source === 'provider') {
+          const result = await this.dcRouterRef.dnsManager!.syncDomain(zone.id);
+          if (!result.success) throw new Error(result.message || `Failed to refresh ${zone.name}`);
+        }
+        for (const intent of this.sortIntents(zoneIntents)) {
+          await this.reconcileIntent(intent, zoneIntents);
+        }
+      } catch (error: unknown) {
+        const outcome: IEmailDomainOperationError = {
+          code: 'DNS_PROVIDER_ZONE_FAILED',
+          message: `DNS zone ${zone.name} reconciliation failed: ${(error as Error).message}`,
+          retryable: true,
+        };
+        errors.set(zone.id, outcome);
+        for (const intent of zoneIntents) {
+          intent.status = 'failed';
+          intent.error = { ...outcome, recordKey: intent.key };
+        }
       }
+    }
+    return errors;
+  }
+
+  private sortIntents(intents: IEmailDnsRecordIntent[]): IEmailDnsRecordIntent[] {
+    const rank = (intent: IEmailDnsRecordIntent): number => {
+      if (intent.type === 'A' || intent.type === 'AAAA') return 0;
+      if (intent.type === 'TXT' && intent.name.includes('._domainkey.')) return 1;
+      if (intent.type === 'TXT') return 2;
+      return 3; // MX is exposed only after identity/auth records exist.
     };
+    return [...intents].sort((left, right) => rank(left) - rank(right) || left.key.localeCompare(right.key));
+  }
 
-    // (a) shared mail hostname → every enabled mail edge
-    const sharedHostname = this.getSharedMailHostname();
-    const mailEdges = remoteIngressManager.getMailEdges();
-    for (const edge of mailEdges) {
-      pushEdgeIps(sharedHostname, edge);
+  private async reconcileIntent(
+    intent: IEmailDnsRecordIntent,
+    zoneIntents: IEmailDnsRecordIntent[],
+  ): Promise<void> {
+    const records = await DnsRecordDoc.findByDomainId(intent.domainId);
+    const rrset = records.filter((record) => (
+      record.name.toLowerCase() === intent.name.toLowerCase() && record.type === intent.type
+    ));
+    const exact = rrset.filter((record) => this.valuesEqual(intent.type, record.value, intent.value));
+    const desiredValues = zoneIntents
+      .filter((candidate) => candidate.name.toLowerCase() === intent.name.toLowerCase() && candidate.type === intent.type)
+      .map((candidate) => candidate.value);
+    const unmanaged = rrset.filter((record) => (
+      record.managedBy !== MAIL_DNS_MANAGED_BY && this.isRelevantUnmanagedTxt(intent, record.value)
+    ));
+    const exactUnmanaged = exact.filter((record) => record.managedBy !== MAIL_DNS_MANAGED_BY);
+    const conflictingUnmanaged = unmanaged.filter((record) => (
+      !desiredValues.some((desired) => this.valuesEqual(intent.type, record.value, desired))
+    ));
+    if (conflictingUnmanaged.length > 0 || (intent.type === 'TXT' && exactUnmanaged.length > 1)) {
+      intent.status = 'conflict';
+      intent.error = {
+        code: 'DNS_UNMANAGED_CONFLICT',
+        message: `Unmanaged ${intent.type} record conflicts with ${intent.name}`,
+        recordKey: intent.key,
+        retryable: false,
+      };
+      return;
+    }
+    if (exactUnmanaged.length === 1) {
+      // Exact operator record satisfies the intent without adoption/deletion.
+      // Remove only a dcrouter-owned duplicate of this same intent; other MX
+      // values in the desired RRset remain independently managed.
+      const ownedDuplicates = rrset.filter((record) => (
+        record.managedBy === MAIL_DNS_MANAGED_BY
+        && (
+          record.managedRecordKey === intent.key
+          || this.valuesEqual(intent.type, record.value, intent.value)
+        )
+      ));
+      for (const duplicate of ownedDuplicates) {
+        const result = await this.dcRouterRef.dnsManager!.deleteRecord(duplicate.id);
+        if (!result.success) throw new Error(result.message || `Failed to delete duplicate ${intent.key}`);
+      }
+      intent.status = 'satisfied';
+      return;
     }
 
-    // (b) per-edge FCrDNS hostname → that edge only
-    for (const edge of remoteIngressManager.getAllEdges()) {
-      if (!edge.enabled) continue;
-      pushEdgeIps(edge.mailHostname, edge);
+    let managed = rrset.find((record) => record.managedRecordKey === intent.key);
+    if (!managed) {
+      const adoptable = exact.find((record) => record.managedBy === MAIL_DNS_MANAGED_BY);
+      if (adoptable) {
+        adoptable.managedOwnerId = intent.ownerId;
+        adoptable.managedRecordKey = intent.key;
+        await adoptable.save();
+        managed = adoptable;
+      }
+    }
+    if (managed) {
+      if (!this.valuesEqual(intent.type, managed.value, intent.value) || managed.name !== intent.name) {
+        const result = await this.dcRouterRef.dnsManager!.updateRecord({
+          id: managed.id,
+          name: intent.name,
+          value: intent.value,
+          ttl: intent.ttl,
+        });
+        if (!result.success) throw new Error(result.message || `Failed to update ${intent.key}`);
+      }
+      intent.providerRecordId = managed.providerRecordId;
+      intent.status = 'satisfied';
+      intent.lastAttemptAt = new Date().toISOString();
+      return;
     }
 
-    // (c) mx.<domain> → pinned edges for every pinned email domain
-    const emailDomainDocs = await EmailDomainDoc.findAll();
-    for (const doc of emailDomainDocs) {
-      const edgeFilter = doc.remoteIngress?.edgeFilter;
-      if (!edgeFilter?.length) continue;
-      const pinnedEdges = remoteIngressManager.resolveEdgesByFilter(edgeFilter);
-      if (pinnedEdges.length === 0) {
-        logger.log('warn', `MailDnsSync: email domain ${doc.domain} pin [${edgeFilter.join(', ')}] matches no enabled edge — mx.${doc.domain} not published`);
-        continue;
+    const result = await this.dcRouterRef.dnsManager!.createRecord({
+      domainId: intent.domainId,
+      name: intent.name,
+      type: intent.type,
+      value: intent.value,
+      ttl: intent.ttl,
+      createdBy: MAIL_DNS_SYNC_CREATED_BY,
+      managedBy: MAIL_DNS_MANAGED_BY,
+      managedOwnerId: intent.ownerId,
+      managedRecordKey: intent.key,
+    });
+    if (!result.success) throw new Error(result.message || `Failed to create ${intent.key}`);
+    intent.status = 'satisfied';
+    intent.lastAttemptAt = new Date().toISOString();
+  }
+
+  private valuesEqual(type: TDnsRecordType, left: string, right: string): boolean {
+    if (type === 'MX') return normalizeMx(left) === normalizeMx(right);
+    if (type === 'A' || type === 'AAAA') return left.trim() === right.trim();
+    return left.trim() === right.trim();
+  }
+
+  private isRelevantUnmanagedTxt(intent: IEmailDnsRecordIntent, value: string): boolean {
+    if (intent.type !== 'TXT') return true;
+    const normalizedIntent = intent.value.trim().toLowerCase();
+    const normalizedValue = value.trim().toLowerCase();
+    if (normalizedIntent.startsWith('v=spf1')) return normalizedValue.startsWith('v=spf1');
+    if (normalizedIntent.startsWith('v=dmarc1')) return normalizedValue.startsWith('v=dmarc1');
+    if (normalizedIntent.startsWith('v=dkim1')) return normalizedValue.startsWith('v=dkim1');
+    return this.valuesEqual(intent.type, value, intent.value);
+  }
+
+  private async validateAndActivate(
+    plan: IPlannedDomain,
+    errors: IEmailDomainOperationError[],
+    zoneErrors: Map<string, IEmailDomainOperationError>,
+  ): Promise<void> {
+    const verifiable = plan.intents.filter((intent) => (
+      !intent.error && !zoneErrors.has(intent.domainId)
+    ));
+    const markResult = (intent: IEmailDnsRecordIntent, result: IMailDnsVerificationResult) => {
+      if (result.valid) {
+        intent.status = 'valid';
+        intent.validatedAt = new Date().toISOString();
+        intent.error = undefined;
+      } else {
+        intent.status = 'pending';
+        intent.error = {
+          code: 'DNS_PROPAGATION_PENDING',
+          message: result.reason || `${intent.type} ${intent.name} has not propagated`,
+          recordKey: intent.key,
+          retryable: true,
+        };
       }
-      for (const edge of pinnedEdges) {
-        pushEdgeIps(`mx.${doc.domain}`, edge);
+    };
+    const mxByName = new Map<string, IEmailDnsRecordIntent[]>();
+    for (const intent of verifiable.filter((candidate) => candidate.type === 'MX')) {
+      const group = mxByName.get(intent.name) || [];
+      group.push(intent);
+      mxByName.set(intent.name, group);
+    }
+    await Promise.all([
+      ...verifiable.filter((intent) => intent.type !== 'MX').map(async (intent) => {
+        const result = await this.verifier.verifyRecord(intent)
+          .catch((error: unknown) => ({ valid: false, reason: (error as Error).message }));
+        markResult(intent, result);
+      }),
+      ...[...mxByName.values()].map(async (intents) => {
+        const previousMx = (plan.doc.reconciliation?.activeRevision?.mxSlots || [])
+          .map((slot) => `${slot.priority} ${slot.hostname}`).sort();
+        const desiredMx = intents.map((intent) => normalizeMx(intent.value)).sort();
+        const isMakeBeforeBreakTransition = previousMx.length > 0
+          && JSON.stringify(previousMx) !== JSON.stringify(desiredMx);
+        const result = await (this.verifier.verifyMxSet && !isMakeBeforeBreakTransition
+          ? this.verifier.verifyMxSet(intents)
+          : Promise.all(intents.map((intent) => this.verifier.verifyRecord(intent))).then((results) => ({
+              valid: results.every((entry) => entry.valid),
+              reason: results.find((entry) => !entry.valid)?.reason,
+            })))
+          .catch((error: unknown) => ({ valid: false, reason: (error as Error).message }));
+        for (const intent of intents) markResult(intent, result);
+      }),
+    ]);
+    for (const intent of plan.intents) {
+      if (intent.error && !errors.some((error) => error.code === intent.error!.code && error.recordKey === intent.key)) {
+        errors.push(intent.error);
       }
     }
 
-    // Hard hub-hiding guard: a hub IP must never become a mail-facing answer.
-    const hubIps = new Set(
-      [this.dcRouterRef.options.publicIp, this.dcRouterRef.detectedPublicIp].filter(Boolean),
-    );
-    const guarded = desired.filter((record) => {
-      if (hubIps.has(record.value)) {
-        logger.log('error', `MailDnsSync: refusing to publish ${record.type} ${record.name} → ${record.value} — value is the hub public IP`);
-        return false;
+    if (plan.egressIdentitySupported && plan.revision.edgeIdentities.length > 0) {
+      const identityResults = await Promise.all(plan.revision.edgeIdentities.map(async (identity) => ({
+        identity,
+        result: await this.verifier.verifyForwardConfirmedIdentity(identity)
+          .catch((error: unknown) => ({ valid: false, reason: (error as Error).message })),
+      })));
+      for (const { identity, result } of identityResults) {
+        if (!result.valid) {
+          errors.push({
+            code: 'FCRDNS_INVALID',
+            message: result.reason || `FCrDNS validation failed for ${identity.edgeId}`,
+            retryable: true,
+          });
+        }
       }
-      return true;
-    });
+    }
 
-    // Dedupe (several edges may share a tag and a pin may overlap the mail pool)
-    const seen = new Set<string>();
-    return guarded.filter((record) => {
-      const key = `${record.name}|${record.type}|${record.value}`;
-      if (seen.has(key)) return false;
-      seen.add(key);
-      return true;
+    const canActivate = plan.egressIdentitySupported
+      && plan.revision.edgeIdentities.length > 0
+      && (plan.revision.edgeIdentities.length >= 2
+        ? plan.revision.mxSlots.length === 2
+        : plan.revision.mxSlots.length === 1)
+      && plan.selectorCorrectSigningSupported
+      && Boolean(this.getActiveDkim(plan.doc))
+      && plan.intents.length > 0
+      && plan.intents.every((intent) => intent.status === 'valid')
+      && errors.length === 0;
+    const hasPermanentError = errors.some((error) => error.retryable === false)
+      || errors.some((error) => ['DNS_PROVIDER_ZONE_FAILED', 'DNS_UNMANAGED_CONFLICT'].includes(error.code));
+    const previousActive = plan.doc.reconciliation?.activeRevision;
+    const topologyChanged = Boolean(previousActive) && JSON.stringify({
+      selector: previousActive?.selector,
+      edgeIdentities: previousActive?.edgeIdentities,
+      mxSlots: previousActive?.mxSlots,
+    }) !== JSON.stringify({
+      selector: plan.revision.selector,
+      edgeIdentities: plan.revision.edgeIdentities,
+      mxSlots: plan.revision.mxSlots,
     });
+    const now = new Date().toISOString();
+    if (canActivate && plan.doc.pendingDkim) {
+      this.promotePendingDkim(plan.doc, now);
+    }
+    plan.doc.reconciliation = {
+      lifecycleStatus: canActivate ? 'active' : hasPermanentError ? 'failed' : 'pending',
+      desiredGeneration: plan.doc.reconciliation?.desiredGeneration || 1,
+      activeRevision: canActivate
+        ? { ...plan.revision, activatedAt: now }
+        : plan.doc.reconciliation?.activeRevision,
+      pendingRevision: canActivate ? undefined : plan.revision,
+      intents: plan.intents,
+      errors,
+      capability: {
+        egressIdentityProof: plan.egressIdentitySupported ? 'supported' : 'unsupported',
+        selectorCorrectSigning: plan.selectorCorrectSigningSupported ? 'supported' : 'unsupported',
+      },
+      lastAttemptAt: now,
+      ...(canActivate ? { lastSuccessAt: now } : { retryAt: new Date(Date.now() + MAIL_DNS_RETRY_INTERVAL_MS).toISOString() }),
+    };
+    plan.doc.dnsStatus = {
+      mx: this.statusForIntent(plan.intents, (intent) => intent.type === 'MX'),
+      spf: this.statusForIntent(plan.intents, (intent) => intent.type === 'TXT' && intent.value.startsWith('v=spf1')),
+      dkim: this.statusForIntent(plan.intents, (intent) => intent.type === 'TXT' && intent.name.includes('._domainkey.')),
+      dmarc: this.statusForIntent(plan.intents, (intent) => intent.type === 'TXT' && intent.value.startsWith('v=DMARC1')),
+      lastCheckedAt: now,
+    };
+    plan.doc.updatedAt = now;
+    await plan.doc.save();
+    if (canActivate && topologyChanged) {
+      // The transition SPF intentionally authorizes old + new identities. Run
+      // one immediate follow-up to contract it to the newly active revision.
+      this.dirty = true;
+    }
   }
 
-  private getSharedMailHostname(): string | undefined {
-    const hostname = this.dcRouterRef.options.emailConfig?.hostname
-      || this.dcRouterRef.options.tls?.domain;
-    if (!hostname || hostname === 'localhost') {
-      return undefined;
+  private promotePendingDkim(doc: EmailDomainDoc, now: string): void {
+    const pending = doc.pendingDkim;
+    if (!pending) return;
+    const previous = this.getActiveDkim(doc);
+    const overlapDays = Math.max(1, doc.dkim.retirementOverlapDays || 30);
+    const retiring = (doc.retiringDkim || []).filter((material) => (
+      material.selector !== pending.selector
+      && (!material.retireAfter || Date.parse(material.retireAfter) > Date.now())
+    ));
+    if (previous && previous.selector !== pending.selector) {
+      retiring.push({
+        ...previous,
+        retireAfter: new Date(Date.now() + overlapDays * 86_400_000).toISOString(),
+      });
     }
-    return hostname;
+    doc.activeDkim = { ...pending, validatedAt: now, promotedAt: now };
+    doc.pendingDkim = undefined;
+    doc.retiringDkim = retiring;
+    doc.dkim.selector = pending.selector;
+    doc.dkim.keySize = pending.keySize;
+    doc.dkim.publicKey = pending.publicKey;
+    doc.dkim.lastRotatedAt = now;
   }
 
-  /** Longest-suffix zone match: 'mx.gated.one' → zone 'gated.one'. */
-  private findZoneForName(name: string, zones: DomainDoc[]): DomainDoc | undefined {
-    let best: DomainDoc | undefined;
-    for (const zone of zones) {
-      const zoneName = zone.name.toLowerCase();
-      if (name === zoneName || name.endsWith(`.${zoneName}`)) {
-        if (!best || zoneName.length > best.name.length) {
-          best = zone;
+  private statusForIntent(
+    intents: IEmailDnsRecordIntent[],
+    predicate: (intent: IEmailDnsRecordIntent) => boolean,
+  ): 'valid' | 'missing' | 'invalid' | 'unchecked' {
+    const selected = intents.filter(predicate);
+    if (selected.length === 0) return 'missing';
+    if (selected.every((intent) => intent.status === 'valid')) return 'valid';
+    if (selected.some((intent) => intent.status === 'conflict' || intent.status === 'failed')) return 'invalid';
+    return 'missing';
+  }
+
+  private async cleanupStaleManagedRecords(zones: DomainDoc[]): Promise<void> {
+    const docs = await EmailDomainDoc.findAll();
+    const keep = new Set<string>();
+    for (const doc of docs) {
+      if (doc.reconciliation?.lifecycleStatus === 'deleting') continue;
+      for (const intent of doc.reconciliation?.intents || []) keep.add(intent.key);
+      if (doc.reconciliation?.lifecycleStatus !== 'active') {
+        for (const key of doc.reconciliation?.activeRevision?.recordKeys || []) keep.add(key);
+      }
+    }
+    const managed = (await DnsRecordDoc.findAll()).filter((record) => record.managedBy === MAIL_DNS_MANAGED_BY);
+    for (const record of managed) {
+      if (record.managedRecordKey && keep.has(record.managedRecordKey)) continue;
+      try {
+        const result = await this.dcRouterRef.dnsManager!.deleteRecord(record.id);
+        if (!result.success) throw new Error(result.message || 'delete failed');
+      } catch (error: unknown) {
+        const ownerId = record.managedOwnerId?.replace(/^domain:/, '');
+        const owner = ownerId ? docs.find((doc) => doc.id === ownerId) : undefined;
+        if (owner?.reconciliation) {
+          owner.reconciliation.errors.push({
+            code: 'DNS_CLEANUP_FAILED',
+            message: `Failed to delete ${record.type} ${record.name}: ${(error as Error).message}`,
+            recordKey: record.managedRecordKey,
+            retryable: true,
+          });
+          owner.reconciliation.retryAt = new Date(Date.now() + MAIL_DNS_RETRY_INTERVAL_MS).toISOString();
+          await owner.save();
         }
       }
     }
-    return best;
   }
+
+  private async finalizeDeletingDomains(): Promise<void> {
+    const docs = await EmailDomainDoc.findAll();
+    const records = await DnsRecordDoc.findAll();
+    for (const doc of docs) {
+      if (doc.reconciliation?.lifecycleStatus !== 'deleting') continue;
+      const owned = records.some((record) => (
+        record.managedBy === MAIL_DNS_MANAGED_BY && record.managedOwnerId === `domain:${doc.id}`
+      ));
+      if (owned || doc.reconciliation.errors.some((error) => error.code === 'DNS_CLEANUP_FAILED')) continue;
+      await doc.delete();
+      logger.log('info', `Email domain deletion finalized: ${doc.domain}`);
+    }
+  }
+
+  private findZoneForName(name: string, zones: DomainDoc[]): DomainDoc | undefined {
+    const normalized = normalizeHostname(name);
+    return [...zones]
+      .filter((zone) => normalized === normalizeHostname(zone.name) || normalized.endsWith(`.${normalizeHostname(zone.name)}`))
+      .sort((left, right) => right.name.length - left.name.length)[0];
+  }
+
 }