@celilo/cli 0.23.0 → 0.24.0

package/src/services/backup-retention.ts

@@ -1,19 +1,77 @@
 /**
- * Backup retention service.
- * Enforces retention policies defined in module manifests.
- * Policies are count-based (keep last N) and age-based (delete older than X days).
- * Whichever limit is hit first triggers deletion.
+ * Backup retention: how many copies to keep, and for how long.
+ *
+ * Policies are count-based (keep last N) and age-based (delete older than X
+ * days), and the two are INDEPENDENT — whichever limit is hit first triggers
+ * deletion. The manifest suggests; the operator's `backup_retention_count` and
+ * `backup_retention_max_age_days` overrides decide, each dimension resolved on
+ * its own.
+ *
+ * ⚠️ An unset dimension is UNBOUNDED, never a default bound. Today an absent
+ * `backup.retention` block means prune nothing at all — the block is optional,
+ * so its inner `count: 7` / `max_age_days: 30` defaults never apply. If setting
+ * one dimension made the other fall back to those defaults, an operator asking
+ * to keep 3 copies would silently also arm a 30-day deletion they never asked
+ * for, on a module that had been keeping everything. Deleting backups nobody
+ * asked to delete is the one failure here that cannot be undone.
  */
 
 import type { Backup } from '../db/schema';
+import type { ModuleManifest } from '../manifest/schema';
 import { deleteBackupRecord, listCompletedBackupsForModule } from './backup-metadata';
 import { createStorageProvider } from './backup-storage';
+import { configOverride } from './module-config';
+
+/** The `module_configs` keys an operator's retention policy is stored under. */
+export const BACKUP_RETENTION_COUNT_CONFIG_KEY = 'backup_retention_count';
+export const BACKUP_RETENTION_MAX_AGE_DAYS_CONFIG_KEY = 'backup_retention_max_age_days';
 
 export interface RetentionPolicy {
+  /** Copies to keep. `Infinity` means unbounded — keep every copy. */
   count: number;
+  /** Days to keep. `Infinity` means unbounded — never delete on age. */
   maxAgeDays: number;
 }
 
+/** Neither dimension bounded: nothing is ever pruned, so the pass can be skipped. */
+export function prunesNothing(policy: RetentionPolicy): boolean {
+  return (
+    policy.count === Number.POSITIVE_INFINITY && policy.maxAgeDays === Number.POSITIVE_INFINITY
+  );
+}
+
+/**
+ * Takes the module's operator config as loaded from `module_configs`. An
+ * unparseable or non-positive override leaves that dimension to the manifest:
+ * values are validated at SET time, so a bad one here means hand-edited state,
+ * and keeping too much is the only safe direction to fail in.
+ */
+export function effectiveBackupRetention(
+  manifest: ModuleManifest,
+  configs: Record<string, unknown> | undefined,
+): RetentionPolicy {
+  const declared = manifest.backup?.retention;
+  return {
+    count: positiveIntegerOr(
+      configOverride(configs, BACKUP_RETENTION_COUNT_CONFIG_KEY),
+      declared?.count,
+    ),
+    maxAgeDays: positiveIntegerOr(
+      configOverride(configs, BACKUP_RETENTION_MAX_AGE_DAYS_CONFIG_KEY),
+      declared?.max_age_days,
+    ),
+  };
+}
+
+/** Override, else the manifest's suggestion, else unbounded. Never a default bound. */
+function positiveIntegerOr(override: string | undefined, suggested: number | undefined): number {
+  if (override !== undefined) {
+    const parsed = Number(override);
+    if (Number.isInteger(parsed) && parsed > 0) return parsed;
+  }
+  return suggested ?? Number.POSITIVE_INFINITY;
+}
+
 export interface PruneResult {
   moduleId: string;
   deleted: number;
@@ -21,7 +79,10 @@ export interface PruneResult {
 }
 
 /**
- * Identify backups that should be pruned per the retention policy
+ * Identify backups that should be pruned per the retention policy.
+ *
+ * An unbounded dimension is `Infinity`, which needs no special case: no index
+ * reaches it and no age exceeds it.
  */
 export function identifyExpiredBackups(backupsList: Backup[], policy: RetentionPolicy): Backup[] {
   const now = Date.now();

package/src/services/backup-schedule.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Backup cadence: what a manifest declares, and when the sweep acts on it.
+ *
+ * The due-ness tests are the interesting half. celilo#685 was a *daily* module
+ * attempted 24 times a day for a day, each attempt assembling ~1.9 GB before
+ * being OOM-killed, because due-ness was measured only from the last SUCCESS
+ * and a module that cannot succeed never advances that timestamp.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest } from '../manifest/schema';
+import {
+  DEFAULT_BACKUP_SCHEDULE,
+  MAX_RAPID_RETRIES,
+  effectiveBackupSchedule,
+  isBackupDueFromHistory,
+} from './backup-schedule';
+import { type Cadence, parseCadence } from './cadence';
+
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+const NOW = Date.UTC(2026, 7, 13, 12, 0, 0);
+
+function ago(ms: number): Date {
+  return new Date(NOW - ms);
+}
+
+/** Parse a cadence in a test, failing loudly rather than passing null on (Rule 7.2). */
+function cadence(value: string): Cadence {
+  const parsed = parseCadence(value);
+  if (parsed === null) throw new Error(`test fixture is not a cadence: ${value}`);
+  return parsed;
+}
+
+function manifestWith(schedule?: string): ModuleManifest {
+  return { backup: schedule ? { schedule } : undefined } as unknown as ModuleManifest;
+}
+
+describe('effectiveBackupSchedule', () => {
+  test('an absent cadence from both sources means daily, not manual', () => {
+    expect(effectiveBackupSchedule(manifestWith(), undefined)).toEqual(cadence('daily'));
+    expect(DEFAULT_BACKUP_SCHEDULE).toEqual(cadence('daily'));
+  });
+
+  test("the manifest's suggestion is honoured when nobody has overridden", () => {
+    expect(effectiveBackupSchedule(manifestWith('manual'), undefined)).toBe('manual');
+    expect(effectiveBackupSchedule(manifestWith('weekly'), undefined)).toEqual(cadence('weekly'));
+  });
+
+  test('the operator override wins over the suggestion', () => {
+    expect(effectiveBackupSchedule(manifestWith('daily'), 'hourly')).toEqual(cadence('hourly'));
+    expect(effectiveBackupSchedule(manifestWith('daily'), '6h')).toEqual(cadence('6h'));
+  });
+
+  test('`manual` is reachable from either source', () => {
+    expect(effectiveBackupSchedule(manifestWith('daily'), 'manual')).toBe('manual');
+    expect(effectiveBackupSchedule(manifestWith('manual'), undefined)).toBe('manual');
+  });
+
+  test('an override applies to a module whose manifest suggests nothing', () => {
+    expect(effectiveBackupSchedule(manifestWith(), 'weekly')).toEqual(cadence('weekly'));
+  });
+
+  test('an unparseable override falls back to the manifest, never to manual', () => {
+    // Values are validated at SET time, so this is hand-edited state. Backing
+    // up MORE often than asked is the safe direction; silently never backing
+    // up is not.
+    expect(effectiveBackupSchedule(manifestWith('weekly'), 'dailyy')).toEqual(cadence('weekly'));
+  });
+});
+
+describe('isBackupDueFromHistory', () => {
+  test('manual never runs on a schedule', () => {
+    expect(
+      isBackupDueFromHistory(
+        'manual',
+        { lastSuccessAt: null, lastAttemptAt: null, consecutiveFailures: 0 },
+        NOW,
+      ),
+    ).toBe(false);
+  });
+
+  test('a module that has never been backed up is due', () => {
+    expect(
+      isBackupDueFromHistory(
+        cadence('daily'),
+        { lastSuccessAt: null, lastAttemptAt: null, consecutiveFailures: 0 },
+        NOW,
+      ),
+    ).toBe(true);
+  });
+
+  test('a fresh success is not due again until its interval has passed', () => {
+    const history = {
+      lastSuccessAt: ago(2 * HOUR),
+      lastAttemptAt: ago(2 * HOUR),
+      consecutiveFailures: 0,
+    };
+    expect(isBackupDueFromHistory(cadence('daily'), history, NOW)).toBe(false);
+    expect(isBackupDueFromHistory(cadence('hourly'), history, NOW)).toBe(true);
+  });
+
+  test('a single failure retries on the next tick', () => {
+    // Most failures are transient. Waiting a whole cadence period after one bad
+    // minute at the storage endpoint would cost more coverage than it saves.
+    expect(
+      isBackupDueFromHistory(
+        cadence('daily'),
+        {
+          lastSuccessAt: ago(2 * DAY),
+          lastAttemptAt: ago(5 * 60 * 1000),
+          consecutiveFailures: 1,
+        },
+        NOW,
+      ),
+    ).toBe(true);
+  });
+
+  test('a run of failures backs off to the module cadence', () => {
+    // The celilo#685 shape: daily module, no success in a week, failing every
+    // hour. Under the old rule this was due at every tick forever.
+    const forgejo = {
+      lastSuccessAt: ago(7 * DAY),
+      lastAttemptAt: ago(1 * HOUR),
+      consecutiveFailures: 20,
+    };
+    expect(isBackupDueFromHistory(cadence('daily'), forgejo, NOW)).toBe(false);
+
+    // ...and still runs once its own interval has elapsed. Backing off is not
+    // giving up.
+    expect(
+      isBackupDueFromHistory(cadence('daily'), { ...forgejo, lastAttemptAt: ago(25 * HOUR) }, NOW),
+    ).toBe(true);
+  });
+
+  test('the back-off boundary is MAX_RAPID_RETRIES', () => {
+    const justFailed = { lastSuccessAt: ago(7 * DAY), lastAttemptAt: ago(1 * HOUR) };
+    expect(
+      isBackupDueFromHistory(
+        cadence('daily'),
+        { ...justFailed, consecutiveFailures: MAX_RAPID_RETRIES - 1 },
+        NOW,
+      ),
+    ).toBe(true);
+    expect(
+      isBackupDueFromHistory(
+        cadence('daily'),
+        { ...justFailed, consecutiveFailures: MAX_RAPID_RETRIES },
+        NOW,
+      ),
+    ).toBe(false);
+  });
+
+  test('a never-succeeded module also backs off once it is clearly failing', () => {
+    // `signal` on celilo-mgr: no successful backup has ever existed. Without
+    // this branch "never succeeded" reads as "always due" and the doomed
+    // attempt runs every tick.
+    expect(
+      isBackupDueFromHistory(
+        cadence('daily'),
+        { lastSuccessAt: null, lastAttemptAt: ago(1 * HOUR), consecutiveFailures: 8 },
+        NOW,
+      ),
+    ).toBe(false);
+  });
+});

package/src/services/backup-schedule.ts

@@ -6,30 +6,120 @@
  * one. If those two read the manifest differently, a module can be
  * alerted-on-but-never-backed-up — an alert no human action can clear.
  *
- * Absent means `daily`, not `manual`. Treating "the author didn't say"
+ * The manifest is the author's SUGGESTION about a fleet they have never
+ * seen; the operator's `backup_schedule` override wins. Resolution
+ * happens HERE, at read time, so a corrected manifest still reaches
+ * every install that has not overridden it.
+ *
+ * Absent from both means `daily`, not `manual`. Treating "nobody said"
  * as "never check and never run" is what let celilo-mgmt go 55 days
  * without a backup and forgejo and signal go without one entirely, all
  * silently. Opting out is a decision worth writing down, so it takes an
- * explicit `schedule: manual`.
+ * explicit `manual`.
  */
 
 import type { ModuleManifest } from '../manifest/schema';
+import { type Cadence, cadenceMs, parseCadence } from './cadence';
 
-export type BackupSchedule = 'hourly' | 'daily' | 'weekly' | 'monthly' | 'manual';
+/** The `module_configs` key an operator's backup cadence is stored under. */
+export const BACKUP_SCHEDULE_CONFIG_KEY = 'backup_schedule';
 
-/** Used when a manifest declares an `on_backup` hook but no cadence. */
-export const DEFAULT_BACKUP_SCHEDULE: BackupSchedule = 'daily';
+/** Used when neither the operator nor the manifest says anything. */
+export const DEFAULT_BACKUP_SCHEDULE: Cadence = { minutes: 24 * 60 };
 
-export function effectiveBackupSchedule(manifest: ModuleManifest): BackupSchedule {
+/**
+ * `override` is the raw stored value of `backup_schedule`, or undefined when
+ * the operator has set none. An unparseable override falls back to the
+ * manifest rather than to `manual`: values are validated at SET time, so a bad
+ * one here means hand-edited state, and the safe direction is backing up more
+ * often than asked, never less.
+ */
+export function effectiveBackupSchedule(
+  manifest: ModuleManifest,
+  override: string | undefined,
+): Cadence {
+  if (override !== undefined) {
+    const chosen = parseCadence(override);
+    if (chosen !== null) return chosen;
+  }
   const declared = manifest.backup?.schedule;
-  switch (declared) {
-    case 'hourly':
-    case 'daily':
-    case 'weekly':
-    case 'monthly':
-    case 'manual':
-      return declared;
-    default:
-      return DEFAULT_BACKUP_SCHEDULE;
+  if (declared !== undefined) {
+    const suggested = parseCadence(declared);
+    if (suggested !== null) return suggested;
   }
+  return DEFAULT_BACKUP_SCHEDULE;
+}
+
+/**
+ * Failures in a row after which retrying stops being worth the resources.
+ *
+ * Under this many, a failure is assumed transient and the module stays due on
+ * the next tick, because most failures ARE transient — a storage endpoint
+ * having a bad minute should not cost a full cadence period of coverage.
+ *
+ * At or over it, the evidence says otherwise and the retry slows to the
+ * module's own cadence. Three is deliberately small: the useful information
+ * from a retry is almost entirely in the first one or two, and the cost of
+ * being wrong in this direction is bounded (one delayed backup) while the cost
+ * of the other direction is not.
+ */
+export const MAX_RAPID_RETRIES = 3;
+
+/** What the backup history says about one module, for the due-ness decision. */
+export interface BackupHistory {
+  /**
+   * When the last successful backup COMPLETED, or null if there has never
+   * been one. Completion, not start — the same instant the freshness audit
+   * measures from, so the run path and the alert path cannot disagree about
+   * how old a backup is (design.md D6).
+   */
+  lastSuccessAt: Date | null;
+  /** Last attempt of any outcome, or null if none has ever been made. */
+  lastAttemptAt: Date | null;
+  /** Attempts since the last success. */
+  consecutiveFailures: number;
+}
+
+/**
+ * Whether to start a backup for a module right now.
+ *
+ * Due-ness used to be "has it been an interval since the last SUCCESS", which
+ * is correct in the healthy case and degenerate in the failing one: a module
+ * that cannot back up never advances that timestamp, so it is due at every
+ * tick forever. The sweep runs hourly, so a *daily* module that started failing
+ * was re-picked 24 times a day. On celilo-mgr that meant 20+ consecutive
+ * forgejo attempts, each one assembling ~1.9 GB of staging and then dying, none
+ * of them ever going to succeed for a reason no retry could change (celilo#685).
+ *
+ * Retrying is still right — it just cannot be unconditional. So the failure
+ * count decides which clock applies: under `MAX_RAPID_RETRIES` the module stays
+ * due against its last success, and at or over it the interval is measured from
+ * the last ATTEMPT instead, which turns 24 doomed attempts a day into one.
+ *
+ * Backing off is not the same as going quiet. The `backups` drift monitor
+ * measures staleness from the last success and is unaffected by this, so a
+ * module that has slowed to one attempt a day still alerts as stale on exactly
+ * the schedule it would have before — see services/audit/backups.ts.
+ *
+ * Pure, and time is a parameter, so the policy tests without a database.
+ */
+export function isBackupDueFromHistory(
+  schedule: Cadence,
+  history: BackupHistory,
+  now: number,
+): boolean {
+  if (schedule === 'manual') return false;
+
+  const interval = cadenceMs(schedule);
+
+  if (history.consecutiveFailures >= MAX_RAPID_RETRIES) {
+    // A run of failures with no attempt recorded is not a state the sweep can
+    // produce, but "cannot prove an interval has passed" must not mean "start
+    // another 1.9 GB attempt".
+    if (!history.lastAttemptAt) return false;
+    return now - history.lastAttemptAt.getTime() >= interval;
+  }
+
+  if (!history.lastSuccessAt) return true;
+  return now - history.lastSuccessAt.getTime() >= interval;
 }

package/src/services/backup-staging.ts

@@ -95,9 +95,22 @@ export interface ReapedStaging {
  * drift check can read a module as recently backed up when every attempt in
  * fact died. Nine such rows were live on celilo-mgr while forgejo had no usable
  * backup at all.
+ *
+ * It names no cause because this pass genuinely cannot know one: it runs later,
+ * in a different process, and infers the death from a pid that is no longer
+ * there. The observer that DOES know is the dispatcher, which holds the exit
+ * code and translates it (`describeHandlerExit` in packages/event-bus) — a
+ * SIGKILL, say, and the OOM killer that most likely sent it.
+ *
+ * The two facts existing in two places is fine; the operator having no way to
+ * learn that is not. In celilo#685 this string was the whole of what an
+ * operator saw for twenty consecutive OOM kills, so it now points at the record
+ * that has the answer rather than terminating the trail.
  */
 export const ABANDONED_BACKUP_MESSAGE =
-  'abandoned — the backup process ended without recording an outcome';
+  'abandoned — the backup process ended without recording an outcome. ' +
+  'Only the process that ran it saw how it died, so the cause is recorded ' +
+  'against the event delivery rather than here: run `celilo system doctor`.';
 
 /**
  * Whether reclaiming this directory also means its record was lying about

package/src/services/backup-sweep.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, test } from 'bun:test';
 import type { ModuleManifest } from '../manifest/schema';
-import type { BackupSchedule } from './backup-schedule';
 import {
   BACKUP_SWEEP_MAX_ATTEMPTS,
   BACKUP_SWEEP_PATTERN,
@@ -13,13 +12,13 @@ import {
 } from './backup-sweep';
 import { InFlightError } from './module-operations';
 
-function moduleWith(id: string, schedule?: BackupSchedule): BackupSweepModule {
+function moduleWith(id: string, schedule?: string, scheduleOverride?: string): BackupSweepModule {
   const manifest = {
     id,
     hooks: { on_backup: { script: 'backup.ts' } },
     ...(schedule ? { backup: { schedule } } : {}),
   } as unknown as ModuleManifest;
-  return { id, manifest };
+  return { id, manifest, scheduleOverride };
 }
 
 function deps(
@@ -123,6 +122,26 @@ describe('runBackupSweep', () => {
     expect(report.skippedManual).toEqual(['scratch']);
   });
 
+  test("an operator's override decides the cadence, not the manifest", async () => {
+    const d = deps([moduleWith('caddy', 'daily', '6h')]);
+    const seen: Array<[string, unknown]> = [];
+    d.isDue = (moduleId, schedule) => {
+      seen.push([moduleId, schedule]);
+      return true;
+    };
+
+    await runBackupSweep(d);
+
+    expect(seen).toEqual([['caddy', { minutes: 360 }]]);
+  });
+
+  test('an override of manual stops a module the manifest wanted backed up', async () => {
+    const report = await runBackupSweep(deps([moduleWith('caddy', 'daily', 'manual')]));
+
+    expect(report.backedUp).toEqual([]);
+    expect(report.skippedManual).toEqual(['caddy']);
+  });
+
   test('an undeclared schedule is backed up, not treated as manual', async () => {
     // The regression this whole subsystem exists for: forgejo and signal
     // declare no `backup:` block and had never been backed up.

package/src/services/backup-sweep.ts

@@ -17,12 +17,16 @@
  */
 
 import type { ModuleManifest } from '../manifest/schema';
-import { type BackupSchedule, effectiveBackupSchedule } from './backup-schedule';
+import { effectiveBackupSchedule } from './backup-schedule';
 import type { ReapStagingReport, ResolveAbandonedReport } from './backup-staging';
+import { BACKUP_SWEEP_PATTERN, type Cadence } from './cadence';
 import { InFlightError } from './module-operations';
 
 export const BACKUP_SWEEP_SUBSCRIBER = 'celilo-backup-sweep';
-export const BACKUP_SWEEP_PATTERN = 'timer.tick.1h';
+// The tick itself lives in services/cadence.ts, next to the floor derived from
+// it — a sweep whose tick and whose finest servable cadence are stated in two
+// files is the pair that drifts.
+export { BACKUP_SWEEP_PATTERN };
 
 /**
  * How long the sweep may run before the dispatcher kills it.
@@ -99,12 +103,18 @@ export function ensureBackupSweepSubscriber(bus: SubscriberRegistrar): void {
 export interface BackupSweepModule {
   id: string;
   manifest: ModuleManifest;
+  /**
+   * The operator's `backup_schedule` override, or undefined when they have set
+   * none. Carried rather than pre-resolved so the cadence is resolved through
+   * the one shared accessor here, the same way the freshness audit resolves it.
+   */
+  scheduleOverride: string | undefined;
 }
 
 export interface BackupSweepDeps {
   /** Installed modules that declare an `on_backup` hook. */
   listEligible(): BackupSweepModule[];
-  isDue(moduleId: string, schedule: BackupSchedule): boolean;
+  isDue(moduleId: string, schedule: Cadence): boolean;
   backup(moduleId: string): Promise<{ success: boolean; error?: string }>;
   /** Apply the module's declared retention. No-op when it declares none. */
   prune(module: BackupSweepModule): Promise<void>;
@@ -126,7 +136,7 @@ export interface BackupSweepReport {
   /** Records corrected from a stale `in_progress`. */
   records: ResolveAbandonedReport;
   backedUp: string[];
-  /** Explicit `schedule: manual` — the author opted out. */
+  /** Effective cadence `manual` — the operator or the author opted out. */
   skippedManual: string[];
   skippedNotDue: string[];
   /** Another module operation held the lock. Not a failure; retried next tick. */
@@ -157,7 +167,7 @@ export async function runBackupSweep(deps: BackupSweepDeps): Promise<BackupSweep
   };
 
   for (const module of deps.listEligible()) {
-    const schedule = effectiveBackupSchedule(module.manifest);
+    const schedule = effectiveBackupSchedule(module.manifest, module.scheduleOverride);
     if (schedule === 'manual') {
       report.skippedManual.push(module.id);
       continue;

package/src/services/cadence.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  ALERTING_SWEEP_PATTERN,
+  BACKUP_CADENCE_FLOOR_MINUTES,
+  BACKUP_SWEEP_PATTERN,
+  MONITOR_INTERVAL_FLOOR_MINUTES,
+  cadenceMs,
+  cadenceSchema,
+  formatCadence,
+  parseCadence,
+  tickIntervalMinutes,
+} from './cadence';
+
+describe('parseCadence', () => {
+  test('every named period equals its duration equivalent', () => {
+    expect(parseCadence('hourly')).toEqual(parseCadence('1h'));
+    expect(parseCadence('daily')).toEqual(parseCadence('24h'));
+    expect(parseCadence('weekly')).toEqual(parseCadence('7d'));
+    expect(parseCadence('monthly')).toEqual(parseCadence('30d'));
+  });
+
+  test('durations normalise to minutes', () => {
+    expect(parseCadence('90m')).toEqual({ minutes: 90 });
+    expect(parseCadence('6h')).toEqual({ minutes: 360 });
+    expect(parseCadence('3d')).toEqual({ minutes: 4320 });
+  });
+
+  test('manual is its own value, not a number', () => {
+    expect(parseCadence('manual')).toBe('manual');
+    expect(cadenceMs('manual')).toBe(Number.POSITIVE_INFINITY);
+  });
+
+  test('rejects malformed, zero and negative values', () => {
+    for (const bad of ['dailyy', '', '6', 'h6', '6w', '0h', '-1h', '1.5h', 'never']) {
+      expect(parseCadence(bad)).toBeNull();
+    }
+  });
+});
+
+describe('formatCadence', () => {
+  test('prefers the word an operator would have typed', () => {
+    expect(formatCadence({ minutes: 60 })).toBe('hourly');
+    expect(formatCadence({ minutes: 1440 })).toBe('daily');
+    expect(formatCadence('manual')).toBe('manual');
+  });
+
+  test('falls back to the coarsest exact duration', () => {
+    expect(formatCadence({ minutes: 360 })).toBe('6h');
+    expect(formatCadence({ minutes: 2880 })).toBe('2d');
+    expect(formatCadence({ minutes: 90 })).toBe('90m');
+  });
+});
+
+describe('the floor follows the sweep tick', () => {
+  test('each floor is the tick of the sweep that would serve it', () => {
+    expect(BACKUP_CADENCE_FLOOR_MINUTES).toBe(tickIntervalMinutes(BACKUP_SWEEP_PATTERN));
+    expect(MONITOR_INTERVAL_FLOOR_MINUTES).toBe(tickIntervalMinutes(ALERTING_SWEEP_PATTERN));
+  });
+
+  test('a finer tick admits a cadence the coarser one refused', () => {
+    const coarse = cadenceSchema({ floorMinutes: tickIntervalMinutes('timer.tick.1h') });
+    const fine = cadenceSchema({ floorMinutes: tickIntervalMinutes('timer.tick.5m') });
+    expect(coarse.safeParse('15m').success).toBe(false);
+    expect(fine.safeParse('15m').success).toBe(true);
+  });
+
+  test('a pattern that is not a timer tick is a programming error, not a floor of zero', () => {
+    expect(() => tickIntervalMinutes('module.deployed')).toThrow();
+  });
+});
+
+describe('cadenceSchema', () => {
+  const schema = cadenceSchema({ floorMinutes: 60 });
+
+  test('accepts words, durations at or above the floor, and manual', () => {
+    for (const good of ['hourly', 'daily', 'weekly', 'monthly', 'manual', '6h', '2d', '60m']) {
+      expect(schema.safeParse(good).success).toBe(true);
+    }
+  });
+
+  test('names the permitted forms when the value is unparseable', () => {
+    const result = schema.safeParse('dailyy');
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues[0].message).toContain('named period');
+      expect(result.error.issues[0].message).toContain('manual');
+    }
+  });
+
+  test('names the finest servable cadence when the value is below the floor', () => {
+    const result = schema.safeParse('5m');
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues[0].message).toContain('hourly');
+    }
+  });
+});