@celilo/cli 0.5.0-alpha.1 → 0.5.0-alpha.2

package/drizzle/0009_dns_registrations.sql

@@ -0,0 +1,13 @@
+CREATE TABLE `dns_registrations` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`provider_module_id` text NOT NULL,
+	`consumer_module_id` text NOT NULL,
+	`fqdn` text NOT NULL,
+	`ip` text,
+	`registered_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`refreshed_at` integer,
+	FOREIGN KEY (`provider_module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`consumer_module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `dns_registrations_provider_fqdn_idx` ON `dns_registrations` (`provider_module_id`,`fqdn`);

package/drizzle/meta/_journal.json

@@ -64,6 +64,13 @@
       "when": 1781064000000,
       "tag": "0008_aspect_consent",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1781280898000,
+      "tag": "0009_dns_registrations",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.5.0-alpha.1",
+  "version": "0.5.0-alpha.2",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -52,9 +52,9 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1024.0",
-    "@celilo/capabilities": "^0.3.0",
+    "@celilo/capabilities": "^0.4.0",
     "@celilo/cli-display": "^0.1.9",
-    "@celilo/event-bus": "^0.1.5",
+    "@celilo/event-bus": "^0.1.6",
     "@clack/prompts": "^1.1.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/src/cli/command-registry.ts

@@ -227,7 +227,7 @@ export const COMMANDS: CommandDef[] = [
       },
       {
         name: 'install-daemon',
-        description: 'Write a systemd/launchd user unit for the dispatcher',
+        description: 'Write a systemd/launchd unit for the dispatcher',
         flags: [
           {
             name: 'celilo-path',
@@ -237,15 +237,47 @@ export const COMMANDS: CommandDef[] = [
           },
           { name: 'poll-ms', description: 'Polling interval in ms', takesValue: true },
           { name: 'concurrency', description: 'Max parallel handlers', takesValue: true },
+          {
+            name: 'system',
+            description:
+              'System scope: /etc/systemd/system unit or /Library/LaunchDaemons plist, run as the celilo state-dir owner (management-plane shape)',
+            takesValue: false,
+          },
+          {
+            name: 'print',
+            description:
+              'Render the unit to stdout without writing it (used by the celilo-mgmt role)',
+            takesValue: false,
+          },
         ],
       },
       {
         name: 'uninstall-daemon',
         description: 'Remove the installed supervisor unit',
+        flags: [{ name: 'system', description: 'Target the system-scope unit', takesValue: false }],
       },
       {
         name: 'show-daemon',
         description: 'Print the currently installed unit file',
+        flags: [{ name: 'system', description: 'Target the system-scope unit', takesValue: false }],
+      },
+    ],
+  },
+  {
+    name: 'dns',
+    description: 'View DNS bookkeeping (registrations ledger)',
+    subcommands: [
+      {
+        name: 'registrations',
+        description: 'List the DNS registration ledger',
+        flags: [
+          {
+            name: 'provider',
+            description: 'Only show registrations owned by one provider module',
+            takesValue: true,
+            valueHint: 'module_ids',
+          },
+        ],
       },
     ],
   },

package/src/cli/commands/dns.ts

@@ -0,0 +1,57 @@
+/**
+ * `celilo dns` — operator views over celilo's DNS bookkeeping.
+ *
+ * `registrations` lists the dns_registrations ledger: every (provider,
+ * fqdn) the framework has registered via dns_registrar.registerHost,
+ * with the consumer that asked for it and when it was last re-asserted
+ * by the provider's refresh_registrations hook. Read-only; names only
+ * (module ids), never UUIDs. See
+ * designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md (B2b).
+ */
+
+import { getDb } from '../../db/client';
+import { listDnsRegistrations } from '../../services/dns-registrations';
+import type { CommandResult } from '../types';
+
+function formatAge(from: Date | null, now: Date): string {
+  if (!from) return 'never';
+  const mins = Math.floor((now.getTime() - from.getTime()) / 60_000);
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+export async function handleDnsRegistrations(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const db = getDb();
+  const provider = typeof flags.provider === 'string' ? flags.provider : undefined;
+  const rows = listDnsRegistrations(db, { providerModuleId: provider });
+
+  if (rows.length === 0) {
+    const scope = provider ? ` for provider '${provider}'` : '';
+    return {
+      success: true,
+      message: `No DNS registrations recorded${scope}\n\nRegistrations are recorded when a module registers a hostname via the dns_registrar capability (e.g. during deploy).`,
+    };
+  }
+
+  const now = new Date();
+  const header = ['FQDN', 'IP', 'PROVIDER', 'CONSUMER', 'REGISTERED', 'REFRESHED'];
+  const table = rows.map((r) => [
+    r.fqdn,
+    r.ip ?? 'auto',
+    r.providerModuleId,
+    r.consumerModuleId,
+    formatAge(r.registeredAt, now),
+    formatAge(r.refreshedAt, now),
+  ]);
+  const widths = header.map((h, i) => Math.max(h.length, ...table.map((row) => row[i].length)));
+  const render = (row: string[]) => row.map((cell, i) => cell.padEnd(widths[i])).join('  ');
+
+  const lines = [render(header), ...table.map(render)];
+  return { success: true, message: lines.join('\n'), data: rows };
+}

package/src/cli/commands/events.ts

@@ -36,7 +36,12 @@ import { runNamedHook } from '../../hooks/run-named-hook';
 import type { HookName } from '../../hooks/types';
 import type { ModuleManifest } from '../../manifest/schema';
 import type { EnsureRequiredPayload } from '../../services/bus-interview';
-import { installDaemon, readInstalledUnit, uninstallDaemon } from '../../services/events-daemon';
+import {
+  installDaemon,
+  planDaemonInstall,
+  readInstalledUnit,
+  uninstallDaemon,
+} from '../../services/events-daemon';
 import { getArg, hasFlag } from '../parser';
 import type { CommandResult } from '../types';
 
@@ -778,27 +783,46 @@ function parseDurationMs(flag: string | boolean | undefined, defaultMs: number):
   }
 }
 
+function daemonScopeFrom(flags: Record<string, string | boolean>): 'user' | 'system' {
+  return flags.system ? 'system' : 'user';
+}
+
 /**
- * `celilo events install-daemon` — write a systemd user unit (Linux)
- * or launchd plist (macOS) that runs the dispatcher under supervision.
- * Writes the file but doesn't touch supervisor state — the operator
- * runs `systemctl --user enable --now ...` themselves so any change
- * is visible.
+ * `celilo events install-daemon` — write a systemd unit (Linux) or
+ * launchd plist (macOS) that runs the dispatcher under supervision.
+ * Default is a per-user unit; `--system` writes the system-scope unit
+ * (/etc/systemd/system, or a /Library/LaunchDaemons LaunchDaemon on
+ * macOS) that survives logout/reboot and runs as the celilo state-dir
+ * owner — the management-plane shape. Writes the file but doesn't
+ * touch supervisor state — the operator (or the celilo-mgmt Ansible
+ * role) runs the enable/bootstrap steps themselves so any change is
+ * visible.
  */
 export async function handleEventsInstallDaemon(
   _args: string[],
   flags: Record<string, string | boolean>,
 ): Promise<CommandResult> {
   try {
-    const result = installDaemon({
+    const options = {
       celiloPath: typeof flags['celilo-path'] === 'string' ? flags['celilo-path'] : undefined,
       pollMs: flags['poll-ms'] ? Number(flags['poll-ms']) : undefined,
       concurrency: flags.concurrency ? Number(flags.concurrency) : undefined,
-    });
+      scope: daemonScopeFrom(flags),
+    };
+    // --print: render-only, raw unit content on stdout. The celilo-mgmt
+    // Ansible role captures this and does the root-owned write itself
+    // (the deb wrapper runs celilo as the unprivileged celilo user, so
+    // a direct --system write would EACCES on /etc/systemd/system).
+    if (flags.print) {
+      const plan = planDaemonInstall(options);
+      return { success: true, message: plan.unitContent, rawOutput: true, data: plan };
+    }
+    const result = installDaemon(options);
     const lines = [
-      `Wrote ${result.platform} unit: ${shortenPath(result.unitPath)}`,
+      `Wrote ${result.platform} ${result.scope} unit: ${shortenPath(result.unitPath)}`,
       `  celilo:   ${shortenPath(result.celiloPath)}`,
       `  bus DB:   ${shortenPath(result.busDbPath)}`,
+      ...(result.runAsUser ? [`  runs as:  ${result.runAsUser}`] : []),
       '',
       'Next steps (run these yourself — install does not touch supervisor state):',
       ...result.nextSteps.map((s) => `  ${s}`),
@@ -813,13 +837,16 @@ export async function handleEventsInstallDaemon(
 }
 
 /**
- * `celilo events uninstall-daemon` — remove the supervisor unit file.
- * Symmetrical: prints the operator-facing disable steps, doesn't run
- * them.
+ * `celilo events uninstall-daemon` — remove the supervisor unit file
+ * (`--system` for the system-scope unit). Symmetrical: prints the
+ * operator-facing disable steps, doesn't run them.
  */
-export async function handleEventsUninstallDaemon(): Promise<CommandResult> {
+export async function handleEventsUninstallDaemon(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
   try {
-    const result = uninstallDaemon();
+    const result = uninstallDaemon({ scope: daemonScopeFrom(flags) });
     const lines = [
       result.removed
         ? `Removed unit: ${shortenPath(result.unitPath)}`
@@ -839,15 +866,20 @@ export async function handleEventsUninstallDaemon(): Promise<CommandResult> {
 
 /**
  * `celilo events show-daemon` — print whatever unit file is currently
- * installed so the operator can see exactly what the supervisor will
- * run, without grepping into platform-specific paths.
+ * installed (`--system` for the system-scope unit) so the operator can
+ * see exactly what the supervisor will run, without grepping into
+ * platform-specific paths.
  */
-export async function handleEventsShowDaemon(): Promise<CommandResult> {
-  const result = readInstalledUnit();
+export async function handleEventsShowDaemon(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const scope = daemonScopeFrom(flags);
+  const result = readInstalledUnit({ scope });
   if (!result.exists) {
     return {
       success: true,
-      message: `No supervisor unit installed at ${shortenPath(result.path)}\n\nRun \`celilo events install-daemon\` to create one.`,
+      message: `No supervisor unit installed at ${shortenPath(result.path)}\n\nRun \`celilo events install-daemon${scope === 'system' ? ' --system' : ''}\` to create one.`,
     };
   }
   return {

package/src/cli/commands/module-upgrade.test.ts

@@ -212,4 +212,41 @@ variables:
     expect(manifest.name).toBe('Test Module Renamed');
     expect(manifest.variables?.owns ?? []).toEqual([]);
   });
+
+  // Regression for ISS-0091: `module update` used to skip event-bus
+  // subscription registration (only `module import` did it), so a
+  // refreshed module silently lost its reconcile subscriptions — found
+  // live when caddy's reconcile_routes subscription vanished after a
+  // path-based update.
+  test('registers the new manifest subscriptions on the bus (ISS-0091)', async () => {
+    process.env.EVENT_BUS_DB = join(tempDir, 'events.db');
+    try {
+      writeFileSync(
+        join(srcDir, 'manifest.yml'),
+        `celilo_contract: "1.0"
+id: testmod
+name: Test Module
+version: 1.1.0
+description: fixture with subscriptions
+subscriptions:
+  - name: testmod-tick
+    pattern: timer.tick.15m
+    handler: "true"
+`,
+      );
+      const result = await upgradeOne(srcDir, db, {}, { quiet: true });
+      expect(result.status).toBe('success');
+
+      const { openBus, defineEvents } = await import('@celilo/event-bus');
+      const bus = openBus({ dbPath: join(tempDir, 'events.db'), events: defineEvents({}) });
+      try {
+        // Subscriber names are scoped `<module-id>.<sub-name>` on the bus.
+        expect(bus.getSubscriberByName('testmod.testmod-tick')).not.toBeNull();
+      } finally {
+        bus.close();
+      }
+    } finally {
+      process.env.EVENT_BUS_DB = undefined;
+    }
+  });
 });

package/src/cli/commands/module-upgrade.ts

@@ -293,6 +293,22 @@ export async function upgradeOne(
     }
   }
 
+  // (Re-)register event-bus subscriptions from the new manifest —
+  // mirrors import.ts (ISS-0091: update used to skip this, so a
+  // refreshed module silently lost its reconcile subscriptions).
+  // registerModuleSubscriptions is idempotent; best-effort like import:
+  // a bus problem shouldn't wedge the upgrade, but must be loud.
+  try {
+    const { registerModuleSubscriptions } = await import('../../services/module-subscriptions');
+    registerModuleSubscriptions(newManifest, installedPath);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    log.warn(`  ${moduleId}: failed to register event-bus subscriptions: ${msg}`);
+    log.warn(
+      '  Module upgraded, but reactive flows on the event bus will not fire until this is fixed.',
+    );
+  }
+
   if (!opts.quiet) {
     log.success(`Upgraded ${moduleId} (${previousVersion} → ${newVersion})`);
   }

package/src/cli/commands/publish/alpha.test.ts

@@ -14,6 +14,7 @@ import {
   isAlphaVersion,
   parsePackageSpec,
   pickNextAlphaN,
+  prereleaseDistTag,
   stripAlphaSuffix,
 } from './alpha';
 
@@ -80,6 +81,31 @@ describe('isAlphaVersion', () => {
   });
 });
 
+describe('prereleaseDistTag (ISS-0083)', () => {
+  test('stable versions get no override → @latest', () => {
+    expect(prereleaseDistTag('0.5.0')).toBeUndefined();
+    expect(prereleaseDistTag('1.0.0')).toBeUndefined();
+    expect(prereleaseDistTag('10.20.30')).toBeUndefined();
+  });
+
+  test('prerelease versions derive their dist-tag from the identifier', () => {
+    expect(prereleaseDistTag('0.5.0-alpha.0')).toBe('alpha');
+    expect(prereleaseDistTag('0.5.0-alpha.3')).toBe('alpha');
+    expect(prereleaseDistTag('1.0.0-beta.2')).toBe('beta');
+    expect(prereleaseDistTag('1.0.0-rc.1')).toBe('rc');
+  });
+
+  test('prerelease without a dotted counter still yields its identifier', () => {
+    expect(prereleaseDistTag('1.0.0-alpha')).toBe('alpha');
+    expect(prereleaseDistTag('1.0.0-next')).toBe('next');
+  });
+
+  test('a prerelease NEVER maps to latest', () => {
+    expect(prereleaseDistTag('0.5.0-alpha.0')).not.toBe('latest');
+    expect(prereleaseDistTag('0.5.0-alpha.0')).not.toBeUndefined();
+  });
+});
+
 describe('pickNextAlphaN', () => {
   test('returns 0 when no alphas exist for the target core', () => {
     expect(pickNextAlphaN([], '0.7.14')).toBe(0);

package/src/cli/commands/publish/alpha.ts

@@ -52,6 +52,29 @@ export function isAlphaVersion(version: string): boolean {
   return /-alpha\.\d+$/.test(version);
 }
 
+/**
+ * ISS-0083: the npm dist-tag a version must publish under, derived from
+ * its semver prerelease identifier. A prerelease (e.g. `0.5.0-alpha.0`,
+ * `1.0.0-beta.2`, `1.0.0-rc.1`) MUST be tagged with its prerelease name
+ * (`alpha`/`beta`/`rc`/…), NEVER `latest` — otherwise `npm install <pkg>`
+ * (no tag) pulls a prerelease, and the prerelease tag the .deb resolves
+ * (`@celilo/cli@alpha`) goes stale. A stable version returns undefined
+ * (publish defaults to `latest`, which is correct for stable).
+ *
+ * The tag is the FIRST dot-separated token of the prerelease component:
+ *   0.5.0-alpha.0   → "alpha"
+ *   1.0.0-beta.2    → "beta"
+ *   1.0.0-rc.1      → "rc"
+ *   1.0.0           → undefined (→ latest)
+ */
+export function prereleaseDistTag(version: string): string | undefined {
+  const dash = version.indexOf('-');
+  if (dash === -1) return undefined;
+  const prerelease = version.slice(dash + 1);
+  const identifier = prerelease.split('.')[0];
+  return identifier || undefined;
+}
+
 /**
  * Pure inner of `nextAlphaNumber`. Given the full list of versions
  * for a package (whatever `npm view <name> versions --json` returned)

package/src/cli/commands/publish/types.ts

@@ -166,8 +166,13 @@ export interface WorkspaceItem {
    * `X.Y.Z-alpha.N` for alpha mode, base-stripped for promote mode.
    */
   versionToPublish: string;
-  /** npm dist-tag override (only `'alpha'` for alpha mode; undefined → `@latest`). */
-  tag?: 'alpha';
+  /**
+   * npm dist-tag override. `'alpha'` for alpha mode; for normal mode a
+   * prerelease version (e.g. `0.5.0-alpha.0`) derives its tag from the
+   * prerelease identifier (ISS-0083) so it never lands on `@latest`.
+   * undefined → `@latest` (only for stable versions).
+   */
+  tag?: string;
   /**
    * Rewrite recipe applied to the package's package.json immediately
    * before `bun publish`. Restored from `originalPackageJson` after.

package/src/cli/commands/publish/workspace.ts

@@ -29,7 +29,13 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { join, relative } from 'node:path';
-import { ALPHA_TAG, alphaSkipDecision, nextAlphaNumber, stripAlphaSuffix } from './alpha';
+import {
+  ALPHA_TAG,
+  alphaSkipDecision,
+  nextAlphaNumber,
+  prereleaseDistTag,
+  stripAlphaSuffix,
+} from './alpha';
 import { REPO_ROOT, isPublished, readPkg } from './helpers';
 import type {
   PackageJson,
@@ -140,6 +146,10 @@ export function planWorkspace(opts: PlanWorkspaceInput): PlanWorkspaceOutput {
       workspaceVersions.set(name, versionToPublish);
     } else {
       versionToPublish = version;
+      // ISS-0083: a prerelease version in package.json (e.g. 0.5.0-alpha.0)
+      // must publish under its prerelease dist-tag, never `latest`. Only
+      // stable versions get `latest` (tag stays undefined).
+      tag = prereleaseDistTag(versionToPublish);
       if (isPublished(name, versionToPublish)) {
         skipReason = 'already published';
       }

package/src/cli/completion.ts

@@ -31,6 +31,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'audit',
       'backup',
       'capability',
+      'dns',
       'completion',
       'events',
       'help',
@@ -53,6 +54,11 @@ export async function getCompletions(words: string[], current: number): Promise<
 
   const command = args[0];
 
+  // DNS subcommands
+  if (command === 'dns' && currentIndex === 1) {
+    return filterSuggestions(['registrations'], args[1] || '');
+  }
+
   // Capability subcommands
   if (command === 'capability' && currentIndex === 1) {
     const subcommands = ['list', 'info'];

package/src/cli/index.ts

@@ -10,6 +10,7 @@ import { COMMANDS, type CommandDef } from './command-registry';
 import { handleCapabilityInfo } from './commands/capability-info';
 import { handleCapabilityList } from './commands/capability-list';
 import { handleCompletion } from './commands/completion';
+import { handleDnsRegistrations } from './commands/dns';
 import {
   handleEventsAck,
   handleEventsDrain,
@@ -162,6 +163,7 @@ Commands:
   audit                    Top-level alias for 'system audit'
   events                   SQLite event-bus operations (status, tail, run dispatcher, etc.)
   capability               View registered module capabilities
+  dns                      View DNS bookkeeping (registrations ledger)
   package                  Create distributable .netapp packages from module source
   module                   Manage modules (import, list, configure, build, generate)
   service                  Manage container services (Proxmox, Digital Ocean)
@@ -265,9 +267,9 @@ Subcommands:
   repair                       Crash-recovery sweep without starting the dispatcher
   resume                       Alias for repair (acknowledges halt-on-recovery)
   respond                      Run the terminal responder; answer deploy prompts from another shell
-  install-daemon               Write a systemd/launchd user unit for the dispatcher
-  uninstall-daemon             Remove the installed supervisor unit
-  show-daemon                  Print the currently installed unit file
+  install-daemon [--system]    Write a systemd/launchd unit for the dispatcher (--system: management-plane scope)
+  uninstall-daemon [--system]  Remove the installed supervisor unit
+  show-daemon [--system]       Print the currently installed unit file
 
 Description:
   The event bus is a SQLite-backed pub/sub layer for celilo modules.
@@ -380,6 +382,32 @@ Related Commands:
   };
 }
 
+function displayDnsHelp(): CommandResult {
+  const helpText = `
+Celilo - DNS Bookkeeping
+
+Usage:
+  celilo dns <subcommand> [options]
+
+Subcommands:
+  registrations           List the DNS registration ledger
+
+Description:
+  Every successful dns_registrar.registerHost (e.g. a deploy registering
+  its public hostname with namecheap) is recorded in the registration
+  ledger. The provider's refresh_registrations hook re-asserts these on
+  a timer; REFRESHED shows when that last succeeded.
+
+Options:
+  --provider <module-id>  Only show registrations owned by one provider
+
+Examples:
+  celilo dns registrations
+  celilo dns registrations --provider namecheap
+`;
+  return { success: true, message: helpText };
+}
+
 function displayCapabilityHelp(): CommandResult {
   const helpText = `
 Celilo - Capability Management
@@ -1075,6 +1103,28 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     };
   }
 
+  if (parsed.command === 'dns') {
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayDnsHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'DNS subcommand required\n\nRun "celilo dns --help" for usage',
+      };
+    }
+
+    if (parsed.subcommand === 'registrations') {
+      return handleDnsRegistrations(parsed.args, parsed.flags);
+    }
+
+    return {
+      success: false,
+      error: `Unknown dns subcommand: ${parsed.subcommand}\n\nRun "celilo dns --help" for usage`,
+    };
+  }
+
   if (parsed.command === 'capability') {
     if (parsed.flags.help || parsed.flags.h) {
       return displayCapabilityHelp();
@@ -1168,9 +1218,9 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       case 'install-daemon':
         return handleEventsInstallDaemon(parsed.args, parsed.flags);
       case 'uninstall-daemon':
-        return handleEventsUninstallDaemon();
+        return handleEventsUninstallDaemon(parsed.args, parsed.flags);
       case 'show-daemon':
-        return handleEventsShowDaemon();
+        return handleEventsShowDaemon(parsed.args, parsed.flags);
       default:
         return {
           success: false,

package/src/db/schema.ts

@@ -432,6 +432,42 @@ export const webRoutes = sqliteTable(
   }),
 );
 
+/**
+ * DNS registration ledger — one row per (provider, fqdn) the framework
+ * has successfully registered via dns_registrar.registerHost. Written
+ * framework-side by the capability loader (the only layer that knows
+ * both consumer and provider), read back to drive the provider's
+ * periodic refresh_registrations hook and the `celilo dns
+ * registrations` view. Rows die with either module via FK cascade; the
+ * remote DNS record itself stays (Namecheap DDNS has no delete API).
+ * See designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md (B2).
+ */
+export const dnsRegistrations = sqliteTable(
+  'dns_registrations',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    providerModuleId: text('provider_module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    consumerModuleId: text('consumer_module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    fqdn: text('fqdn').notNull(),
+    /** null = provider auto-detected the request's source IP (Namecheap-style). */
+    ip: text('ip'),
+    registeredAt: integer('registered_at', { mode: 'timestamp' })
+      .notNull()
+      .default(sql`(unixepoch())`),
+    refreshedAt: integer('refreshed_at', { mode: 'timestamp' }),
+  },
+  (table) => ({
+    providerFqdnUnique: uniqueIndex('dns_registrations_provider_fqdn_idx').on(
+      table.providerModuleId,
+      table.fqdn,
+    ),
+  }),
+);
+
 /**
  * Backup storage providers - destinations for backup archives
  * Supports local filesystem and S3-compatible storage (AWS S3, MinIO, Backblaze B2, Wasabi)