@celilo/cli 0.23.0 → 0.24.1

package/src/services/audit/backups.ts

@@ -1,24 +1,25 @@
 /**
  * Backup freshness drift check.
  *
- * For each installed module that declares an `on_backup` hook,
- * decides whether the most recent successful backup is too old based
- * on the module's declared `manifest.backup.schedule`. Each schedule
- * tier has a threshold with a small grace window so a slightly-late
- * scheduled run doesn't flag drift on every audit.
+ * For each installed module that declares an `on_backup` hook, decides whether
+ * the most recent successful backup is too old, against the module's EFFECTIVE
+ * cadence — the operator's override if they set one, else the manifest's
+ * suggestion. The threshold is that cadence plus a grace allowance, so a
+ * slightly-late scheduled run doesn't flag drift on every audit.
  *
- * Modules without an `on_backup` hook are skipped — there's nothing
- * to back up. Modules whose schedule is explicitly `manual` skip the
- * staleness check (the operator decides cadence) but still get a
- * `backup_missing` finding if no backup has ever been recorded. An
- * unset schedule is `daily`, not `manual` — see
- * [[services/backup-schedule.ts]] for why that default matters.
+ * Modules without an `on_backup` hook are skipped — there's nothing to back up.
+ * A module whose effective cadence is `manual` is skipped entirely: it has
+ * opted out, and a finding asking it to back up is one no operator action can
+ * clear, because the action it asks for is the one they declined. An unset
+ * cadence is `daily`, not `manual` — see [[services/backup-schedule.ts]] for
+ * why that default matters.
  *
  * Time is injected so tests can pin "now" deterministically.
  */
 
 import type { ModuleManifest } from '../../manifest/schema';
 import { effectiveBackupSchedule } from '../backup-schedule';
+import { type Cadence, cadenceMs, formatCadence } from '../cadence';
 import type { DriftFinding } from './types';
 
 export interface InstalledModuleBackupInfo {
@@ -26,6 +27,8 @@ export interface InstalledModuleBackupInfo {
   /** Lifecycle state — non-deployed modules have nothing to back up. */
   state: string;
   manifest: ModuleManifest;
+  /** The operator's `backup_schedule` override, or undefined when unset. */
+  scheduleOverride: string | undefined;
   /** Most recent successful backup timestamp (ms since epoch), or null. */
   lastSuccessfulBackupAt: number | null;
 }
@@ -33,9 +36,9 @@ export interface InstalledModuleBackupInfo {
 export interface BackupsAuditDeps {
   modules: InstalledModuleBackupInfo[];
   /**
-   * Test-only override: forces this threshold for every module,
-   * ignoring `manifest.backup.schedule`. Production code never sets
-   * this — schedule-based thresholds are the right behavior.
+   * Test-only override: forces this threshold for every module whose
+   * effective cadence is not `manual`. Production code never sets this —
+   * cadence-derived thresholds are the right behavior.
    */
   staleAfterMs?: number;
   /** Defaults to `Date.now()`. */
@@ -46,32 +49,26 @@ const HOUR = 60 * 60 * 1000;
 const DAY = 24 * HOUR;
 
 /**
- * Schedule → stale threshold. Each tier gets a grace window so a
- * legitimately-just-late run doesn't trip the audit:
+ * How old a backup may get before it is drift: the cadence itself plus a grace
+ * allowance, so a legitimately-just-late run doesn't trip the audit.
  *
- * - hourly  → 2h   (1h cadence + 1h grace)
- * - daily   → 25h  (24h + 1h grace)
- * - weekly  → 8d   (7d + 1d grace)
- * - monthly → 32d  (~30d + 2d grace)
- * - manual  → null (no staleness check; operator-driven cadence)
+ * A formula rather than a table because a table cannot answer for `6h`, and an
+ * operator who sets a custom cadence would get either no staleness reporting or
+ * an arbitrary threshold. The four previous values were not a formula in
+ * disguise — hourly had 100% grace, daily 4%, weekly 14%, monthly 7% — so this
+ * moves them: daily 25h → 26.4h, weekly 8d → 7.7d (the only one that alerts
+ * EARLIER), monthly 32d → 33d, hourly unchanged at 2h. See design.md D7.
  */
-const SCHEDULE_THRESHOLDS = {
-  hourly: 2 * HOUR,
-  daily: 25 * HOUR,
-  weekly: 8 * DAY,
-  monthly: 32 * DAY,
-  manual: null,
-} as const;
+export function backupStaleThresholdMs(cadence: Cadence): number | null {
+  if (cadence === 'manual') return null;
+  const interval = cadenceMs(cadence);
+  return interval + Math.max(HOUR, interval * 0.1);
+}
 
 function moduleHasBackupHook(manifest: ModuleManifest): boolean {
   return Boolean(manifest.hooks?.on_backup);
 }
 
-function thresholdFor(manifest: ModuleManifest, override: number | undefined): number | null {
-  if (override !== undefined) return override;
-  return SCHEDULE_THRESHOLDS[effectiveBackupSchedule(manifest)];
-}
-
 function formatAge(ms: number): string {
   const days = Math.floor(ms / DAY);
   if (days >= 1) return `${days}d`;
@@ -96,12 +93,18 @@ export async function auditBackups(deps: BackupsAuditDeps): Promise<DriftFinding
     // audit.
     if (!DEPLOYED_STATES.has(m.state)) continue;
 
+    const cadence = effectiveBackupSchedule(m.manifest, m.scheduleOverride);
+    // BEFORE the never-backed-up check, not after. A module opted out of
+    // scheduled backups was reported as missing one forever, and the only
+    // remediation offered was the very thing the operator declined.
+    if (cadence === 'manual') continue;
+
     if (m.lastSuccessfulBackupAt === null) {
       findings.push({
         category: 'backups',
         severity: 'drift',
         code: 'backup_missing',
-        message: `${m.id}: no successful backup recorded (schedule: ${effectiveBackupSchedule(m.manifest)})`,
+        message: `${m.id}: no successful backup recorded (schedule: ${formatCadence(cadence)})`,
         remediation: `celilo backup create ${m.id} --force`,
         actionable: true,
         subject: m.id,
@@ -109,8 +112,8 @@ export async function auditBackups(deps: BackupsAuditDeps): Promise<DriftFinding
       continue;
     }
 
-    const threshold = thresholdFor(m.manifest, deps.staleAfterMs);
-    if (threshold === null) continue; // manual cadence — staleness is user-defined
+    const threshold = deps.staleAfterMs ?? backupStaleThresholdMs(cadence);
+    if (threshold === null) continue;
 
     const age = now - m.lastSuccessfulBackupAt;
     if (age > threshold) {
@@ -118,7 +121,7 @@ export async function auditBackups(deps: BackupsAuditDeps): Promise<DriftFinding
         category: 'backups',
         severity: 'drift',
         code: 'backup_stale',
-        message: `${m.id}: last successful backup is ${formatAge(age)} old (schedule: ${effectiveBackupSchedule(m.manifest)}, threshold: ${formatAge(threshold)})`,
+        message: `${m.id}: last successful backup is ${formatAge(age)} old (schedule: ${formatCadence(cadence)}, threshold: ${formatAge(threshold)})`,
         remediation: `celilo backup create ${m.id} --force`,
         actionable: true,
         subject: m.id,

package/src/services/audit/interface-classification.test.ts

@@ -0,0 +1,220 @@
+/**
+ * §10 — what the audit says about a firewall's interfaces.
+ *
+ * The condition that produced `fw-keeper.sh` was not that celilo lacked
+ * information; it was that celilo said nothing. So the load-bearing assertions
+ * here are about what gets NAMED — an alien interface by name AND address, a
+ * carrier leg, an ambiguous edge — and about §10.2's converse: a fully declared
+ * firewall must produce no findings at all, or the report trains the operator to
+ * ignore it.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  type FirewallInterfaceView,
+  auditFirewallInterfaces,
+  auditInterfaceClassification,
+  describeClassification,
+} from './interface-classification';
+
+const DECLARED = [
+  { zone: 'internal', subnet: '192.168.0.0/24' },
+  { zone: 'dmz', subnet: '10.0.10.0/24' },
+  { zone: 'app', subnet: '10.0.20.0/24' },
+  { zone: 'secure', subnet: '10.0.30.0/24' },
+];
+
+/** celilo's own firewall: five RFC1918 legs, four declared, wg0 not. */
+function liveFleetShape(overrides: Partial<FirewallInterfaceView> = {}): FirewallInterfaceView {
+  return {
+    hostname: 'fw-main',
+    interfaces: [
+      { name: 'eth0', ip: '192.168.0.254' },
+      { name: 'eth1', ip: '10.0.10.1' },
+      { name: 'eth2', ip: '10.0.20.1' },
+      { name: 'eth3', ip: '10.0.30.1' },
+      { name: 'wg0', ip: '10.255.255.1' },
+    ],
+    zones: DECLARED,
+    defaultRouteInterface: 'eth0',
+    ...overrides,
+  };
+}
+
+function codes(findings: { code: string }[]): string[] {
+  return findings.map((f) => f.code);
+}
+
+describe('§10.2 — a fully declared firewall produces NO interface findings', () => {
+  test('every leg declared, default route on internal, no findings', () => {
+    // The positive control, and not a formality: a check that cries wolf on a
+    // healthy fleet is worse than no check, because it teaches an operator to
+    // ignore the one signal that matters.
+    const view = liveFleetShape({
+      zones: [...DECLARED, { zone: 'control-plane-vpn', subnet: '10.255.255.0/24' }],
+    });
+    expect(auditFirewallInterfaces(view)).toEqual([]);
+  });
+
+  test('a firewall that owns its WAN, fully declared, produces no findings', () => {
+    const view: FirewallInterfaceView = {
+      hostname: 'vps-fw',
+      interfaces: [
+        { name: 'eth0', ip: '10.0.10.1' },
+        { name: 'eth1', ip: '203.0.113.100' },
+      ],
+      zones: [{ zone: 'dmz', subnet: '10.0.10.0/24' }],
+      defaultRouteInterface: 'eth1',
+    };
+    expect(auditFirewallInterfaces(view)).toEqual([]);
+  });
+
+  test('loopback does not produce a finding', () => {
+    const view = liveFleetShape({
+      interfaces: [{ name: 'lo', ip: '127.0.0.1' }, ...liveFleetShape().interfaces.slice(0, 4)],
+      defaultRouteInterface: 'eth0',
+    });
+    expect(auditFirewallInterfaces(view)).toEqual([]);
+  });
+});
+
+describe('§10.1 — alien interfaces are named, by name AND address', () => {
+  const findings = auditFirewallInterfaces(liveFleetShape());
+
+  test('the undeclared VPN leg is reported', () => {
+    expect(codes(findings)).toContain('alien_interfaces');
+  });
+
+  test('the message carries both the interface name and its address', () => {
+    // "one alien interface" is useless at 3am. The operator needs to know
+    // which, and where.
+    const alien = findings.find((f) => f.code === 'alien_interfaces');
+    expect(alien?.message).toContain('wg0');
+    expect(alien?.message).toContain('10.255.255.1');
+  });
+
+  test('it is drift, not blocked — the converge decides, the audit reports', () => {
+    expect(findings.find((f) => f.code === 'alien_interfaces')?.severity).toBe('drift');
+  });
+
+  test('it is subjected on the hostname, never a UUID', () => {
+    // Suppression resolves a machine's ancestor key from its hostname; a
+    // finding subjected on a UUID produces an alert key nothing can match
+    // (#596). Users never see UUIDs either.
+    expect(findings.find((f) => f.code === 'alien_interfaces')?.subject).toBe('fw-main');
+  });
+
+  test('several alien legs are all named, not just the first', () => {
+    const view = liveFleetShape({ zones: [{ zone: 'internal', subnet: '192.168.0.0/24' }] });
+    const alien = auditFirewallInterfaces(view).find((f) => f.code === 'alien_interfaces');
+    for (const ip of ['10.0.10.1', '10.0.20.1', '10.0.30.1', '10.255.255.1']) {
+      expect(alien?.message).toContain(ip);
+    }
+  });
+});
+
+describe('§10.1 — the blocking findings match what the converge does', () => {
+  test('a carrier-grade NAT leg blocks, naming the interface and address', () => {
+    const view = liveFleetShape({
+      interfaces: [...liveFleetShape().interfaces, { name: 'eth9', ip: '100.83.4.17' }],
+      zones: [...DECLARED, { zone: 'control-plane-vpn', subnet: '10.255.255.0/24' }],
+    });
+    const finding = auditFirewallInterfaces(view).find(
+      (f) => f.code === 'carrier_grade_nat_interface',
+    );
+    expect(finding?.severity).toBe('blocked');
+    expect(finding?.message).toContain('eth9');
+    expect(finding?.message).toContain('100.83.4.17');
+  });
+
+  test('two public legs with no designation block, naming both candidates', () => {
+    const view: FirewallInterfaceView = {
+      hostname: 'fw-two-wans',
+      interfaces: [
+        { name: 'eth0', ip: '203.0.113.100' },
+        { name: 'eth1', ip: '198.51.100.7' },
+      ],
+      zones: [],
+      defaultRouteInterface: 'eth0',
+    };
+    const finding = auditFirewallInterfaces(view).find((f) => f.code === 'ambiguous_external_edge');
+    expect(finding?.severity).toBe('blocked');
+    expect(finding?.message).toContain('203.0.113.100');
+    expect(finding?.message).toContain('198.51.100.7');
+    expect(finding?.remediation).toContain('zone.external.ip');
+  });
+
+  test('a designated edge resolves the ambiguity, producing no finding', () => {
+    const view: FirewallInterfaceView = {
+      hostname: 'fw-two-wans',
+      interfaces: [
+        { name: 'eth0', ip: '203.0.113.100' },
+        { name: 'eth1', ip: '198.51.100.7' },
+      ],
+      zones: [],
+      defaultRouteInterface: 'eth0',
+      designatedExternalIp: '198.51.100.7',
+    };
+    expect(codes(auditFirewallInterfaces(view))).not.toContain('ambiguous_external_edge');
+  });
+
+  test('a default route on a segmented zone blocks', () => {
+    const view = liveFleetShape({
+      zones: [...DECLARED, { zone: 'control-plane-vpn', subnet: '10.255.255.0/24' }],
+      defaultRouteInterface: 'eth1', // the dmz leg
+    });
+    const finding = auditFirewallInterfaces(view).find((f) => f.code === 'default_route_off_edge');
+    expect(finding?.severity).toBe('blocked');
+    expect(finding?.message).toContain('eth1');
+  });
+
+  test('an unknown default route is not checked rather than guessed', () => {
+    // `undefined` means celilo did not read the routing table. Reporting a
+    // finding from an absent measurement would be inventing evidence.
+    const view = liveFleetShape({
+      zones: [...DECLARED, { zone: 'control-plane-vpn', subnet: '10.255.255.0/24' }],
+      defaultRouteInterface: undefined,
+    });
+    expect(codes(auditFirewallInterfaces(view))).not.toContain('default_route_off_edge');
+  });
+
+  test('blocking findings come before drift, so the report reads top-down', () => {
+    const view = liveFleetShape({
+      interfaces: [...liveFleetShape().interfaces, { name: 'eth9', ip: '100.83.4.17' }],
+    });
+    const severities = auditFirewallInterfaces(view).map((f) => f.severity);
+    expect(severities[0]).toBe('blocked');
+    expect(severities.at(-1)).toBe('drift');
+  });
+});
+
+describe('describeClassification — the picture, not a finding', () => {
+  test('names the role of every interface, and why an alien one is alien', () => {
+    const lines = describeClassification(liveFleetShape());
+    expect(lines).toContain('eth0: 192.168.0.254 → zone:internal');
+    expect(lines).toContain('wg0: 10.255.255.1 → alien (no declared subnet contains it)');
+  });
+
+  test('a publicly routable but unclaimed leg is described as external', () => {
+    const lines = describeClassification({
+      hostname: 'vps-fw',
+      interfaces: [{ name: 'eth1', ip: '203.0.113.100' }],
+      zones: [],
+    });
+    expect(lines[0]).toBe('eth1: 203.0.113.100 → external (the WAN edge)');
+  });
+});
+
+describe('auditInterfaceClassification — every firewall, flattened', () => {
+  test('reports across several firewalls, each subjected on its own hostname', () => {
+    const findings = auditInterfaceClassification([
+      liveFleetShape(),
+      liveFleetShape({ hostname: 'fw-branch' }),
+    ]);
+    expect(findings.map((f) => f.subject).sort()).toEqual(['fw-branch', 'fw-main']);
+  });
+
+  test('no firewalls means no findings', () => {
+    expect(auditInterfaceClassification([])).toEqual([]);
+  });
+});

package/src/services/audit/interface-classification.ts

@@ -0,0 +1,167 @@
+/**
+ * Firewall interface classification, reported where an operator already looks.
+ *
+ * The condition that produced `fw-keeper.sh` was not that celilo lacked
+ * information — it was that celilo said nothing. An interface it cannot
+ * attribute is an unowned network segment on a firewall, and one that is never
+ * surfaced is discovered as an outage rather than as a finding.
+ *
+ * What this reports, per firewall:
+ *
+ *   - every interface celilo cannot attribute, by name AND address;
+ *   - a carrier-grade NAT interface, which celilo refuses to converge on;
+ *   - an ambiguous external edge — more than one public leg, none designated;
+ *   - a default route leaving through neither `internal` nor `external`.
+ *
+ * The last three are BLOCKING, matching what the converge does with them. An
+ * audit that called them drift while the converge refused would be telling the
+ * operator something different from what the system does.
+ *
+ * Pure, like every other checker here: it consumes a pre-computed view so it is
+ * unit-testable without SSH or a live firewall.
+ *
+ * openspec: firewall-interface-classification §10 (design D1, D2, D11)
+ */
+
+import {
+  type InterfaceAddress,
+  type ZoneDeclaration,
+  classifyInterfaces,
+  defaultRouteFinding,
+  externalEdge,
+  isPubliclyRoutable,
+  subnetContains,
+} from '@celilo/capabilities';
+import type { DriftFinding } from './types';
+
+/** RFC 6598. celilo refuses to converge on one — see design D2 (amended). */
+const CARRIER_GRADE_NAT = '100.64.0.0/10';
+
+export interface FirewallInterfaceView {
+  /**
+   * User-facing hostname, and the key the finding is subjected on.
+   *
+   * NOT the machine UUID: suppression resolves a machine's ancestor key from
+   * its hostname, so a finding subjected on a UUID produces an alert key
+   * suppression can never match (#596). Users never see UUIDs either.
+   */
+  hostname: string;
+  /** Every address the firewall holds, as read from the box. */
+  interfaces: InterfaceAddress[];
+  /** The zones this firewall declares, with the subnets that define them. */
+  zones: ZoneDeclaration[];
+  /** The interface carrying the default route, when celilo knows it. */
+  defaultRouteInterface?: string | null;
+  /** The operator's designated edge, from the firewall's `zone.external.ip`. */
+  designatedExternalIp?: string | null;
+}
+
+/**
+ * Findings for one firewall's interfaces.
+ *
+ * Ordered most-severe first so the report reads top-down: the reasons a
+ * converge would refuse, then the interfaces that are merely unaccounted for.
+ */
+export function auditFirewallInterfaces(view: FirewallInterfaceView): DriftFinding[] {
+  const findings: DriftFinding[] = [];
+  const classifications = classifyInterfaces(view.interfaces, view.zones);
+
+  // ── Blocking: a carrier address celilo cannot reason about ────────────────
+  const carrier = view.interfaces.filter((i) => subnetContains(CARRIER_GRADE_NAT, i.ip));
+  for (const iface of carrier) {
+    findings.push({
+      category: 'interface_classification',
+      severity: 'blocked',
+      code: 'carrier_grade_nat_interface',
+      subject: view.hostname,
+      message: `${view.hostname}: ${iface.name} holds a carrier-grade NAT address (${iface.ip})`,
+      details:
+        "RFC 6598 space belongs to the carrier and is shared with other subscribers, so it cannot tell celilo the fleet's real external address. celilo does not know what such an interface is for, whether to NAT on it, or what reach it should have, so it refuses to converge rather than guessing. Only ISP equipment should hold one.",
+      remediation:
+        'Remove the carrier-grade NAT interface from this firewall, or place the ISP boundary on separate equipment (celilo drives an upstream router through the firewall capability).',
+      actionable: false,
+    });
+  }
+
+  // ── Blocking: two public legs and no designation ──────────────────────────
+  const edge = externalEdge(classifications, view.designatedExternalIp);
+  if (edge.kind === 'ambiguous') {
+    const named = edge.candidates.map((c) => `${c.name} (${c.ip})`).join(', ');
+    findings.push({
+      category: 'interface_classification',
+      severity: 'blocked',
+      code: 'ambiguous_external_edge',
+      subject: view.hostname,
+      message: `${view.hostname}: ${edge.candidates.length} publicly routable interfaces and none designated — ${named}`,
+      details:
+        'celilo will not pick an external edge by interface order. Before this check the first non-private address won silently, so a box with two public addresses had its edge chosen by enumeration with no warning and no way to override.',
+      remediation: `celilo module config set <firewall-module> zone.external.ip <one of: ${edge.candidates
+        .map((c) => c.ip)
+        .join(', ')}>`,
+      actionable: false,
+    });
+  }
+
+  // ── Blocking: egress leaving through a segment celilo cannot describe ─────
+  if (view.defaultRouteInterface !== undefined) {
+    const routeFinding = defaultRouteFinding(classifications, view.defaultRouteInterface);
+    if (routeFinding) {
+      findings.push({
+        category: 'interface_classification',
+        severity: 'blocked',
+        code: 'default_route_off_edge',
+        subject: view.hostname,
+        message: `${view.hostname}: ${routeFinding.message}`,
+        details:
+          'celilo supports two shapes: a firewall that owns its WAN egresses through its external leg, and a downstream firewall egresses via an upstream router on the internal segment. Egress anywhere else leaves through a segment celilo cannot describe.',
+        remediation:
+          'Move the default route onto the external or internal leg, or declare a zone for the interface that carries it.',
+        actionable: false,
+      });
+    }
+  }
+
+  // ── Drift: interfaces nobody accounted for ────────────────────────────────
+  const alien = classifications.filter((c) => c.role === 'alien');
+  if (alien.length > 0) {
+    const named = alien.map((c) => `${c.name} (${c.ip})`).join(', ');
+    findings.push({
+      category: 'interface_classification',
+      severity: 'drift',
+      code: 'alien_interfaces',
+      subject: view.hostname,
+      message: `${view.hostname}: ${alien.length} interface(s) celilo cannot attribute — ${named}`,
+      details:
+        'An interface in no declared zone is an unowned network segment on a firewall. celilo refuses to converge a firewall it is onboarding until every interface is accounted for; on one it has already brought to a known-good state, a NEWLY appeared interface like this is disabled.',
+      remediation: `celilo system config set network.<zone>.subnet <cidr>  # then add the zone to the firewall's declared zones`,
+      actionable: false,
+    });
+  }
+
+  return findings;
+}
+
+/** Every firewall's findings, flattened. */
+export function auditInterfaceClassification(views: FirewallInterfaceView[]): DriftFinding[] {
+  return views.flatMap(auditFirewallInterfaces);
+}
+
+/**
+ * The classification itself, for the report body rather than as a finding.
+ *
+ * §10.2 requires a fully declared firewall to produce NO findings, so the
+ * per-interface roles cannot be findings — they are what an operator reads to
+ * confirm the picture is what they intended.
+ */
+export function describeClassification(view: FirewallInterfaceView): string[] {
+  return classifyInterfaces(view.interfaces, view.zones).map((c) => {
+    if (c.role === 'zone') return `${c.name}: ${c.ip} → zone:${c.zone}`;
+    if (c.role === 'external') {
+      return `${c.name}: ${c.ip} → external (the WAN edge)`;
+    }
+    const why = isPubliclyRoutable(c.ip)
+      ? 'publicly routable but unclaimed'
+      : 'no declared subnet contains it';
+    return `${c.name}: ${c.ip} → alien (${why})`;
+  });
+}

package/src/services/audit/types.ts

@@ -40,7 +40,8 @@ export type DriftCategory =
   | 'public_dns'
   | 'disk_space'
   | 'transport_reads'
-  | 'trusted_sources';
+  | 'trusted_sources'
+  | 'interface_classification';
 
 export type DriftSeverity = 'todo' | 'drift' | 'blocked';
 

package/src/services/backup-age-agreement.test.ts

@@ -0,0 +1,118 @@
+/**
+ * The run path and the alert path must agree about how old a backup is.
+ *
+ * They did not. `isBackupDue` measured from `backups.startedAt` while the
+ * freshness audit measured from `completedAt`, so the two disagreed by however
+ * long the backup itself took — 5.5 minutes for forgejo, and unbounded for
+ * anything larger. The shared accessor prevented drift where it was looking and
+ * the drift moved into the columns underneath it (design.md D6).
+ *
+ * This is the gate for that: one completed backup whose start and finish are
+ * far apart, read by both paths, which must return the same instant.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb, getDb } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import { backupStorages, backups, modules } from '../db/schema';
+import { loadBackupAuditInfo } from './audit/backup-source';
+import { findBackupEligibleModules } from './backup-create';
+import { loadBackupHistory } from './backup-metadata';
+import { BACKUP_SCHEDULE_CONFIG_KEY, effectiveBackupSchedule } from './backup-schedule';
+import { parseCadence } from './cadence';
+import { configOverride, upsertModuleConfig } from './module-config';
+
+const STARTED = new Date('2026-04-25T00:00:00Z');
+// Six hours later — an extreme but not absurd gap for a multi-gigabyte module.
+const COMPLETED = new Date('2026-04-25T06:00:00Z');
+
+describe('backup age: the run path and the audit path read the same column', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-backup-age-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    await runMigrations(process.env.CELILO_DB_PATH);
+
+    const db = getDb();
+    db.insert(modules)
+      .values({
+        id: 'forgejo',
+        name: 'Forgejo',
+        sourcePath: dir,
+        version: '1.0.0',
+        state: 'INSTALLED',
+        manifestData: {
+          id: 'forgejo',
+          hooks: { on_backup: { script: './backup.ts' } },
+          backup: { schedule: 'daily' },
+        },
+      })
+      .run();
+    db.insert(backupStorages)
+      .values({
+        id: 'storage-1',
+        storageId: 'local',
+        name: 'Local',
+        providerName: 'local',
+        credentialsEncrypted: '',
+        providerConfig: {},
+        verified: true,
+      })
+      .run();
+    db.insert(backups)
+      .values({
+        id: 'backup-1',
+        moduleId: 'forgejo',
+        storageId: 'storage-1',
+        storagePath: '2026-04-25/forgejo.backup',
+        backupType: 'module_data',
+        status: 'completed',
+        startedAt: STARTED,
+        completedAt: COMPLETED,
+      })
+      .run();
+  });
+
+  afterEach(() => {
+    closeDb();
+    process.env.CELILO_DB_PATH = undefined;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('both measure from when the backup COMPLETED, not when it started', () => {
+    const history = loadBackupHistory('forgejo');
+    const [audited] = loadBackupAuditInfo(getDb());
+
+    expect(history.lastSuccessAt?.getTime()).toBe(COMPLETED.getTime());
+    expect(audited.lastSuccessfulBackupAt).toBe(COMPLETED.getTime());
+    expect(history.lastSuccessAt?.getTime()).toBe(audited.lastSuccessfulBackupAt ?? 0);
+  });
+
+  test('both resolve the same cadence for the same module', () => {
+    const [audited] = loadBackupAuditInfo(getDb());
+    const fromAudit = effectiveBackupSchedule(audited.manifest, audited.scheduleOverride);
+
+    expect(fromAudit).toEqual({ minutes: 24 * 60 });
+    expect(parseCadence('daily')).toEqual(fromAudit);
+  });
+
+  test("an operator's override reaches the sweep and the audit alike", () => {
+    upsertModuleConfig(getDb(), 'forgejo', BACKUP_SCHEDULE_CONFIG_KEY, '6h');
+
+    const [audited] = loadBackupAuditInfo(getDb());
+    const [eligible] = findBackupEligibleModules();
+
+    const fromAudit = effectiveBackupSchedule(audited.manifest, audited.scheduleOverride);
+    const fromSweep = effectiveBackupSchedule(
+      eligible.manifest,
+      configOverride(eligible.configs, BACKUP_SCHEDULE_CONFIG_KEY),
+    );
+
+    expect(fromAudit).toEqual({ minutes: 360 });
+    expect(fromSweep).toEqual(fromAudit);
+  });
+});