@celilo/cli 0.13.3 → 0.14.1

package/src/services/alerting/sweep-runner.test.ts

@@ -0,0 +1,229 @@
+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 { eq } from 'drizzle-orm';
+import type { DbClient } from '../../db/client';
+import { type Alert, type Monitor, alerts, monitors } from '../../db/schema';
+import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import type { HealthCheckResult } from '../health-runner';
+import { moduleCheckAlertKey } from './keys';
+import type { MonitorRunDeps } from './run-monitor';
+import { type SuppressionTopology, machineAlertKey } from './suppression';
+import { type SweepDeps, runSweep } from './sweep-runner';
+
+const NOW = new Date('2026-07-28T12:00:00Z');
+const later = (minutes: number) => new Date(NOW.getTime() + minutes * 60_000);
+
+const MODULE = 'homebridge';
+const PORT_CHECK = moduleCheckAlertKey(MODULE, 'port');
+
+const failing: HealthCheckResult = {
+  moduleId: MODULE,
+  status: 'unhealthy',
+  checks: [{ name: 'port', status: 'fail', message: 'port 8581 closed' }],
+};
+const healthy: HealthCheckResult = { moduleId: MODULE, status: 'healthy', checks: [] };
+
+const TOPOLOGY: SuppressionTopology = {
+  moduleSystems: [{ moduleId: MODULE, hostname: 'iot', zone: 'internal', infraType: 'machine' }],
+  zoneProviders: [],
+};
+
+describe('runSweep', () => {
+  let dir: string;
+  let db: DbClient;
+  let monitor: Monitor;
+
+  function monitorDeps(result: HealthCheckResult, now: Date): MonitorRunDeps {
+    return {
+      runModuleCheck: async () => result,
+      runBuiltinCheck: async () => [],
+      loadModuleCoverage: () => [],
+      now: () => now,
+      graceMs: 60_000,
+    };
+  }
+
+  function deps(over: Partial<SweepDeps> = {}, result = failing, now = NOW): SweepDeps {
+    return {
+      monitorDeps: monitorDeps(result, now),
+      loadTopology: () => TOPOLOGY,
+      loadDeployWindowModules: () => new Set(),
+      isSuppressible: () => true,
+      // No routes configured: the sweep must still run everything else.
+      notifyDepsFor: () => null,
+      now: () => now,
+      ...over,
+    };
+  }
+
+  const liveAlerts = (): Alert[] => db.select().from(alerts).all();
+  const currentMonitors = () => db.select().from(monitors).all();
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'sweep-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabase(dbPath);
+    db.insert(monitors)
+      .values({
+        id: 'mon-1',
+        kind: 'module_hook',
+        target: MODULE,
+        intervalMinutes: 15,
+        severity: 'critical',
+      })
+      .run();
+    monitor = db.select().from(monitors).where(eq(monitors.id, 'mon-1')).get() as Monitor;
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  test('a never-run monitor is due and its failure becomes an alert', async () => {
+    const report = await runSweep(db, currentMonitors(), deps());
+    expect(report.monitorsRun).toBe(1);
+    expect(liveAlerts().map((a) => a.key)).toEqual([PORT_CHECK]);
+  });
+
+  // Inside the grace window an alert is recorded but not yet firing, so a
+  // check that clears immediately never pages.
+  test('a fresh alert stays pending until its grace window elapses', async () => {
+    const report = await runSweep(db, currentMonitors(), deps());
+    expect(report.promoted).toBe(0);
+    expect(liveAlerts()[0].state).toBe('pending');
+  });
+
+  test('a later sweep promotes it to firing', async () => {
+    await runSweep(db, currentMonitors(), deps());
+    const report = await runSweep(db, currentMonitors(), deps({}, failing, later(20)));
+    expect(report.promoted).toBe(1);
+    expect(liveAlerts()[0].state).toBe('firing');
+  });
+
+  test('a monitor within its interval is not re-run', async () => {
+    await runSweep(db, currentMonitors(), deps());
+    // 5 minutes later, well inside the 15-minute interval.
+    const report = await runSweep(db, currentMonitors(), deps({}, failing, later(5)));
+    expect(report.monitorsRun).toBe(0);
+  });
+
+  test('a disabled monitor is never run', async () => {
+    db.update(monitors).set({ enabled: false }).where(eq(monitors.id, 'mon-1')).run();
+    const report = await runSweep(db, currentMonitors(), deps());
+    expect(report.monitorsRun).toBe(0);
+    expect(liveAlerts()).toEqual([]);
+  });
+
+  test('recovery resolves the alert on a later sweep', async () => {
+    await runSweep(db, currentMonitors(), deps());
+    await runSweep(db, currentMonitors(), deps({}, healthy, later(20)));
+    expect(liveAlerts().every((a) => a.state === 'resolved')).toBe(true);
+  });
+
+  // The whole point of step 3 running after step 1: the machine alert may not
+  // exist yet when the module check fails.
+  describe('suppression is applied across the sweep, not during it', () => {
+    beforeEach(() => {
+      // A SEPARATE monitor owns the machine alert. Attaching it to the module's
+      // monitor would have it resolved by set difference on the very first
+      // sweep — that monitor does not report the machine key, and absence from
+      // a successful run means resolved. Correct behaviour, wrong fixture.
+      db.insert(monitors)
+        .values({
+          id: 'mon-machines',
+          kind: 'builtin_check',
+          target: 'machines_reachable',
+          intervalMinutes: 5,
+          severity: 'critical',
+          enabled: false,
+        })
+        .run();
+      db.insert(alerts)
+        .values({
+          id: 'machine-alert',
+          key: machineAlertKey('iot'),
+          activeKey: machineAlertKey('iot'),
+          monitorId: 'mon-machines',
+          state: 'firing',
+          severity: 'critical',
+          graceUntil: NOW,
+          message: 'iot unreachable',
+        })
+        .run();
+    });
+
+    test('a module alert is suppressed by its machine being down', async () => {
+      // Suppression lands on the FIRST sweep: step 3 runs after every monitor
+      // has reported, so the machine alert is already visible.
+      const report = await runSweep(db, currentMonitors(), deps());
+      expect(report.suppressed).toBeGreaterThanOrEqual(1);
+
+      const moduleAlert = db.select().from(alerts).where(eq(alerts.key, PORT_CHECK)).get();
+      expect(moduleAlert?.state).toBe('suppressed');
+      expect(moduleAlert?.suppressedByAlertId).toBe(machineAlertKey('iot'));
+    });
+
+    // Lifting suppression must NOT page immediately — it waits for a run that
+    // confirms the problem outlived its cause.
+    test('un-suppression sets awaitingConfirmation rather than notifying', async () => {
+      await runSweep(db, currentMonitors(), deps());
+
+      // The machine recovers.
+      db.update(alerts)
+        .set({ state: 'resolved', activeKey: null })
+        .where(eq(alerts.id, 'machine-alert'))
+        .run();
+
+      const report = await runSweep(db, currentMonitors(), deps({}, failing, later(40)));
+      expect(report.unsuppressed).toBe(1);
+
+      const moduleAlert = db.select().from(alerts).where(eq(alerts.key, PORT_CHECK)).get();
+      expect(moduleAlert?.awaitingConfirmation).toBe(true);
+      expect(moduleAlert?.state).toBe('firing');
+    });
+
+    test('an unsuppressible alert is never suppressed', async () => {
+      await runSweep(db, currentMonitors(), deps({ isSuppressible: () => false }));
+      const report = await runSweep(
+        db,
+        currentMonitors(),
+        deps({ isSuppressible: () => false }, failing, later(20)),
+      );
+      expect(report.suppressed).toBe(0);
+    });
+  });
+
+  // The sweep is the fleet's only heartbeat. One broken module must not stop
+  // every other alert from being evaluated.
+  test('a monitor that throws is counted, and the sweep continues', async () => {
+    const exploding: MonitorRunDeps = {
+      ...monitorDeps(failing, NOW),
+      runModuleCheck: async () => {
+        throw new Error('hook executor blew up');
+      },
+    };
+    const report = await runSweep(db, currentMonitors(), deps({ monitorDeps: exploding }));
+    expect(report.monitorsErrored).toBe(1);
+  });
+
+  test('a sweep with no monitors does nothing and does not throw', async () => {
+    db.delete(monitors).run();
+    const report = await runSweep(db, [], deps());
+    expect(report).toMatchObject({ monitorsRun: 0, promoted: 0, notified: 0 });
+  });
+
+  test('lastRunAt advances so the next sweep respects the interval', async () => {
+    await runSweep(db, currentMonitors(), deps());
+    expect(db.select().from(monitors).get()?.lastRunAt).toEqual(NOW);
+    expect(monitor.lastRunAt).toBeNull();
+  });
+});

package/src/services/alerting/sweep-runner.ts

@@ -0,0 +1,204 @@
+/**
+ * The sweep — the one thing that makes alerting run by itself.
+ *
+ * Everything else in services/alerting/ is inert until this runs: monitors are
+ * rows nobody executes, alerts never leave `pending`, escalation never fires.
+ * The dispatcher invokes `celilo alerts sweep` on `timer.tick.5m`, and this is
+ * what that becomes.
+ *
+ * Order matters, and each step depends on the previous one having settled:
+ *
+ *   1. run every DUE monitor        → alerts created / refreshed / resolved
+ *   2. promote past-grace alerts    → pending becomes firing
+ *   3. re-evaluate suppression      → at notify time, never at fire time (S1)
+ *   4. notify what is still due     → escalation decides whether and whom
+ *
+ * Step 3 sits after 1 and 2 deliberately. Monitors do not run in a guaranteed
+ * order, so a module's check can fail seconds before the machine check that
+ * explains it; deciding suppression during step 1 would page for the symptom
+ * moments before the cause lands.
+ */
+
+import type { DbClient } from '../../db/client';
+import type { Alert, Monitor } from '../../db/schema';
+import type { NotifyDeps, NotifyOutcome } from './notifier';
+import { deliverDeferred, notifyAlert } from './notifier';
+import { type MonitorRunDeps, runOneMonitor } from './run-monitor';
+import {
+  clearDeferral,
+  deferNotification,
+  dueDeferrals,
+  loadAllLiveAlerts,
+  markSuppressed,
+  markUnsuppressed,
+  promoteReadyAlerts,
+  recordStepTaken,
+} from './store';
+import { type SuppressionTopology, findSuppressor } from './suppression';
+import { selectDueMonitors } from './sweep';
+
+export interface SweepDeps {
+  monitorDeps: MonitorRunDeps;
+  /** Topology for suppression — read once per sweep, not per alert. */
+  loadTopology(): SuppressionTopology;
+  /** Modules currently inside a deploy window. */
+  loadDeployWindowModules(): Set<string>;
+  /** Whether the monitor owning an alert may be suppressed at all. */
+  isSuppressible(alert: Alert): boolean;
+  /** Compose the per-alert notification context. Null when nothing can page. */
+  notifyDepsFor(alert: Alert): NotifyDeps | null;
+  now(): Date;
+}
+
+export interface SweepReport {
+  monitorsRun: number;
+  monitorsErrored: number;
+  promoted: number;
+  suppressed: number;
+  unsuppressed: number;
+  notified: number;
+  deferred: number;
+  /** Messages held over quiet hours and delivered now that the window ended. */
+  deferredDelivered: number;
+  failed: number;
+}
+
+/**
+ * Run one sweep.
+ *
+ * Never throws for a single bad monitor or a single failed send: the sweep is
+ * the fleet's only heartbeat, and one broken module must not stop every other
+ * alert from being evaluated. Failures are counted and returned.
+ */
+export async function runSweep(
+  db: DbClient,
+  monitors: Monitor[],
+  deps: SweepDeps,
+): Promise<SweepReport> {
+  const report: SweepReport = {
+    monitorsRun: 0,
+    monitorsErrored: 0,
+    promoted: 0,
+    suppressed: 0,
+    unsuppressed: 0,
+    notified: 0,
+    deferred: 0,
+    deferredDelivered: 0,
+    failed: 0,
+  };
+
+  // 1. Run due monitors.
+  const due = selectDueMonitors(
+    monitors.map((m) => ({
+      id: m.id,
+      intervalMinutes: m.intervalMinutes,
+      enabled: m.enabled,
+      lastRunAt: m.lastRunAt,
+      monitor: m,
+    })),
+    deps.now(),
+  );
+
+  for (const entry of due) {
+    try {
+      const summary = await runOneMonitor(db, entry.monitor, deps.monitorDeps);
+      report.monitorsRun++;
+      if (summary.outcome === 'error') report.monitorsErrored++;
+    } catch {
+      // A monitor that throws outside its own error handling still must not
+      // stop the sweep — the other monitors are the rest of the fleet.
+      report.monitorsErrored++;
+    }
+  }
+
+  // 2. Promote alerts past their grace window.
+  report.promoted = promoteReadyAlerts(db, deps.now());
+
+  // 3. Re-evaluate suppression across everything live, now that this sweep's
+  //    monitors have all reported.
+  const live = loadAllLiveAlerts(db);
+  const firingKeys = new Set(
+    live.filter((a) => a.state === 'firing' || a.state === 'acked').map((a) => a.key),
+  );
+  const topology = deps.loadTopology();
+  const deployWindows = deps.loadDeployWindowModules();
+
+  for (const alert of live) {
+    const suppressor = findSuppressor({
+      key: alert.key,
+      firingKeys,
+      suppressible: deps.isSuppressible(alert),
+      modulesInDeployWindow: deployWindows,
+      topology,
+    });
+    const wasSuppressed = alert.state === 'suppressed';
+    if (suppressor && !wasSuppressed) {
+      markSuppressed(db, alert.id, {
+        alertId: suppressor.kind === 'alert' ? suppressor.key : undefined,
+        windowId: suppressor.kind === 'deploy_window' ? suppressor.moduleId : undefined,
+      });
+      report.suppressed++;
+    } else if (!suppressor && wasSuppressed) {
+      // Lifting suppression sets awaitingConfirmation, so this does NOT page
+      // now — it pages after a later run confirms the problem survived (S2).
+      markUnsuppressed(db, alert.id, deps.now());
+      report.unsuppressed++;
+    }
+  }
+
+  // 4. Flush anything held over quiet hours whose window has now ended. Runs
+  //    BEFORE new notifications so an overnight page arrives ahead of whatever
+  //    this morning's sweep decides.
+  for (const alert of dueDeferrals(db, deps.now())) {
+    const notifyDeps = deps.notifyDepsFor(alert);
+    const route = alert.deferredRouteId
+      ? notifyDeps?.routeDetails.get(alert.deferredRouteId)
+      : undefined;
+    // A deferral whose route was deleted overnight is dropped rather than
+    // retried forever — the escalation clock already moved past that step.
+    clearDeferral(db, alert.id);
+    if (!notifyDeps || !route) continue;
+
+    try {
+      const outcome = await deliverDeferred(alert, route, notifyDeps);
+      if (outcome.result === 'sent') report.deferredDelivered++;
+      else if (outcome.result === 'failed') report.failed++;
+    } catch {
+      report.failed++;
+    }
+  }
+
+  // 5. Notify. Re-read: the steps above changed state under us.
+  for (const alert of loadAllLiveAlerts(db)) {
+    const notifyDeps = deps.notifyDepsFor(alert);
+    if (!notifyDeps) continue;
+
+    let outcome: NotifyOutcome;
+    try {
+      outcome = await notifyAlert(alert, notifyDeps);
+    } catch {
+      // notifyAlert already converts transport errors into a `failed` outcome;
+      // reaching here means something above the transport broke.
+      report.failed++;
+      continue;
+    }
+
+    if (outcome.result === 'sent') {
+      recordStepTaken(db, alert.id, outcome);
+      report.notified++;
+    } else if (outcome.result === 'deferred') {
+      // The step counts as taken even though nothing was sent (D13), so the
+      // chain keeps moving and a later step can reach someone who is awake.
+      recordStepTaken(db, alert.id, {
+        stepIndex: alert.escalationStep,
+        nextStepDueAt: alert.nextEscalationAt,
+      });
+      deferNotification(db, alert.id, { routeId: outcome.routeId, until: outcome.until });
+      report.deferred++;
+    } else if (outcome.result === 'failed') {
+      report.failed++;
+    }
+  }
+
+  return report;
+}

package/src/services/alerting/sweep.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'bun:test';
+import { type SchedulableMonitor, selectDueMonitors } from './sweep';
+
+const NOW = new Date('2026-07-28T12:00:00Z');
+const minutesAgo = (n: number) => new Date(NOW.getTime() - n * 60_000);
+
+function monitor(over: Partial<SchedulableMonitor> = {}): SchedulableMonitor {
+  return { id: 'm1', intervalMinutes: 15, enabled: true, lastRunAt: minutesAgo(20), ...over };
+}
+
+describe('selectDueMonitors', () => {
+  test('a monitor past its interval is due', () => {
+    expect(selectDueMonitors([monitor()], NOW)).toHaveLength(1);
+  });
+
+  test('a monitor within its interval is not due', () => {
+    expect(selectDueMonitors([monitor({ lastRunAt: minutesAgo(5) })], NOW)).toEqual([]);
+  });
+
+  // Otherwise a newly created monitor stays silent for a full interval, which
+  // reads as "monitoring is broken" exactly when someone just switched it on.
+  test('a monitor that has never run is due immediately', () => {
+    expect(selectDueMonitors([monitor({ lastRunAt: null })], NOW)).toHaveLength(1);
+  });
+
+  test('a disabled monitor is never due, even when overdue', () => {
+    expect(
+      selectDueMonitors([monitor({ enabled: false, lastRunAt: minutesAgo(999) })], NOW),
+    ).toEqual([]);
+  });
+
+  test('a disabled monitor that has never run is still not due', () => {
+    expect(selectDueMonitors([monitor({ enabled: false, lastRunAt: null })], NOW)).toEqual([]);
+  });
+
+  test('exactly at the interval boundary is due', () => {
+    expect(selectDueMonitors([monitor({ lastRunAt: minutesAgo(15) })], NOW)).toHaveLength(1);
+  });
+
+  test('selects only the due subset, preserving order', () => {
+    const due = selectDueMonitors(
+      [
+        monitor({ id: 'a', lastRunAt: minutesAgo(20) }),
+        monitor({ id: 'b', lastRunAt: minutesAgo(1) }),
+        monitor({ id: 'c', lastRunAt: null }),
+        monitor({ id: 'd', enabled: false, lastRunAt: null }),
+      ],
+      NOW,
+    );
+    expect(due.map((m) => m.id)).toEqual(['a', 'c']);
+  });
+
+  // A 1h monitor swept on a 5m grid: not due at 55m, due at 60m. The grid
+  // rounds a period UP, it never fires one early.
+  test('a long interval is not fired early by a frequent sweep', () => {
+    const hourly = monitor({ intervalMinutes: 60, lastRunAt: minutesAgo(55) });
+    expect(selectDueMonitors([hourly], NOW)).toEqual([]);
+    const later = new Date(NOW.getTime() + 5 * 60_000);
+    expect(selectDueMonitors([hourly], later)).toHaveLength(1);
+  });
+});

package/src/services/alerting/sweep.ts

@@ -0,0 +1,41 @@
+/**
+ * Monitor sweep scheduling.
+ *
+ * The sweep rides the event bus's existing `timer.tick.5m` rather than
+ * introducing a scheduler: the bus's timer menu is deliberately fixed
+ * (packages/event-bus/src/timer.ts), and a five-minute grid is accurate enough
+ * for home-lab monitoring cadences. Consequence, accepted: a monitor's real
+ * period is its configured interval rounded up to the next sweep.
+ *
+ * See openspec/changes/add-alerting/design.md D2.
+ */
+
+const MINUTE_MS = 60_000;
+
+export interface SchedulableMonitor {
+  id: string;
+  intervalMinutes: number;
+  enabled: boolean;
+  /** Null when the monitor has never run. */
+  lastRunAt: Date | null;
+}
+
+/**
+ * Select the monitors due to run at `now`.
+ *
+ * A monitor that has never run is due immediately — otherwise a newly created
+ * monitor would stay silent for a full interval, which reads as "monitoring is
+ * broken" precisely when someone has just switched it on and is watching.
+ *
+ * Disabled monitors are never due. Their alerts are resolved when they are
+ * disabled rather than left to hang, so skipping them here cannot strand a
+ * firing alert.
+ */
+export function selectDueMonitors<T extends SchedulableMonitor>(monitors: T[], now: Date): T[] {
+  return monitors.filter((monitor) => {
+    if (!monitor.enabled) return false;
+    if (monitor.lastRunAt === null) return true;
+    const elapsed = now.getTime() - monitor.lastRunAt.getTime();
+    return elapsed >= monitor.intervalMinutes * MINUTE_MS;
+  });
+}

package/src/services/alerting/tokens.test.ts

@@ -0,0 +1,152 @@
+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 type { DbClient } from '../../db/client';
+import { modules, people, routes } from '../../db/schema';
+import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import {
+  consumeDelivery,
+  deliveriesForAlert,
+  findLiveDelivery,
+  generateToken,
+  mintDelivery,
+  normaliseToken,
+} from './tokens';
+
+const NOW = new Date('2026-07-28T03:00:00Z');
+const TTL_MS = 24 * 60 * 60_000;
+const ROUTE = 'route-1';
+
+describe('token generation', () => {
+  // These are read off a phone screen and typed back. Characters people
+  // reliably confuse are excluded on purpose.
+  test('never contains I, L, O, or U', () => {
+    for (let i = 0; i < 500; i++) {
+      expect(generateToken()).not.toMatch(/[ILOU]/);
+    }
+  });
+
+  test('is six characters of the expected alphabet', () => {
+    expect(generateToken()).toMatch(/^[0-9ABCDEFGHJKMNPQRSTVWXYZ]{6}$/);
+  });
+
+  test('is not obviously constant', () => {
+    const seen = new Set(Array.from({ length: 200 }, () => generateToken()));
+    expect(seen.size).toBeGreaterThan(150);
+  });
+});
+
+describe('normaliseToken — forgiving of how people actually type', () => {
+  test.each([
+    ['k7qm2x', 'K7QM2X'],
+    ['  K7QM2X  ', 'K7QM2X'],
+    ['K7Q-M2X', 'K7QM2X'],
+    ['K7Q M2X', 'K7QM2X'],
+  ])('%p → %p', (input, expected) => {
+    expect(normaliseToken(input)).toBe(expected);
+  });
+});
+
+describe('delivery records', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'tokens-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabase(dbPath);
+
+    db.insert(modules)
+      .values({
+        id: 'signal',
+        name: 'Signal',
+        version: '1.0.0',
+        manifestData: {},
+        sourcePath: '/tmp/signal',
+      })
+      .run();
+    db.insert(people).values({ id: 'p1', name: 'peter', timezone: 'UTC' }).run();
+    db.insert(routes)
+      .values({ id: ROUTE, personId: 'p1', transportModuleId: 'signal', address: '+15550000' })
+      .run();
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  const mint = (targetId = 'alert-1', now = NOW) =>
+    mintDelivery(db, { kind: 'alert', targetId, routeId: ROUTE, now, ttlMs: TTL_MS });
+
+  test('a minted delivery is findable by its token', () => {
+    const delivery = mint();
+    expect(findLiveDelivery(db, delivery.token, NOW)?.id).toBe(delivery.id);
+  });
+
+  test('lookup is case-insensitive and separator-tolerant', () => {
+    const delivery = mint();
+    const typed = `${delivery.token.slice(0, 3)}-${delivery.token.slice(3)}`.toLowerCase();
+    expect(findLiveDelivery(db, typed, NOW)?.id).toBe(delivery.id);
+  });
+
+  test('an unknown token finds nothing', () => {
+    expect(findLiveDelivery(db, 'ZZZZZZ', NOW)).toBeUndefined();
+  });
+
+  test('an expired token is not live', () => {
+    const delivery = mint();
+    const afterExpiry = new Date(NOW.getTime() + TTL_MS + 1000);
+    expect(findLiveDelivery(db, delivery.token, afterExpiry)).toBeUndefined();
+  });
+
+  // A token is single-use: replaying it must not re-acknowledge, and must not
+  // let someone who saw the message once act on it repeatedly.
+  test('a consumed token is no longer live', () => {
+    const delivery = mint();
+    consumeDelivery(db, delivery.id, NOW);
+    expect(findLiveDelivery(db, delivery.token, NOW)).toBeUndefined();
+  });
+
+  test('tokens are unique across concurrent outstanding deliveries', () => {
+    const tokens = new Set<string>();
+    for (let i = 0; i < 50; i++) {
+      tokens.add(mint(`alert-${i}`).token);
+    }
+    expect(tokens.size).toBe(50);
+  });
+
+  // The all-clear must reach everyone who was told, and only them.
+  test('deliveriesForAlert finds every delivery made for that alert', () => {
+    mint('alert-A');
+    mint('alert-A');
+    mint('alert-B');
+    expect(deliveriesForAlert(db, 'alert-A')).toHaveLength(2);
+    expect(deliveriesForAlert(db, 'alert-B')).toHaveLength(1);
+  });
+
+  test('a delivery records which route it went to, so a reply identifies who', () => {
+    const delivery = mint();
+    expect(delivery.routeId).toBe(ROUTE);
+  });
+
+  test('interview deliveries share the table but not the kind', () => {
+    mintDelivery(db, {
+      kind: 'interview',
+      targetId: 'bus-event-42',
+      routeId: ROUTE,
+      now: NOW,
+      ttlMs: TTL_MS,
+    });
+    // An interview delivery is not an alert delivery, so an all-clear for an
+    // alert with a colliding id must not reach it.
+    expect(deliveriesForAlert(db, 'bus-event-42')).toEqual([]);
+  });
+});