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

package/src/services/bus-interview.ts

@@ -23,6 +23,13 @@ export const EVENT_TYPES = {
   secretRequired: (module: string, key: string) => `secret.required.${module}.${key}`,
   ensureRequired: (provider: string, ensureId: string) => `ensure.required.${provider}.${ensureId}`,
   aspectRequired: (module: string, role: string) => `aspect.required.${module}.${role}`,
+  /**
+   * Generic interview family (ISS-0127). Unlike the module-scoped families
+   * above, this carries a free-form `scope` (e.g. `service:proxmox-home-lab`)
+   * so non-deploy operator commands can ask questions over the same bus the
+   * deploy interview uses — making them headlessly drivable.
+   */
+  interviewRequired: (scope: string, key: string) => `interview.required.${scope}.${key}`,
 } as const;
 
 /**
@@ -182,6 +189,58 @@ export interface EnsureReply {
   acknowledged?: true;
 }
 
+/**
+ * The four shapes a generic interview question can take. The responder
+ * renders by `kind`: `text` is a free-text prompt (with type coercion +
+ * pattern validation), `confirm` is a yes/no, `select` is a single choice
+ * from `options`, `multiselect` is zero-or-more choices from `options`.
+ */
+export type InterviewKind = 'text' | 'confirm' | 'select' | 'multiselect';
+
+/**
+ * Payload for `interview.required.<scope>.<key>` (ISS-0127). The generic
+ * counterpart to `ConfigRequiredPayload`: it carries everything a responder
+ * needs to render any of the four `kind`s, plus a `scope`/`key` pair that
+ * gives the question a stable identity a headless responder can answer by.
+ *
+ * Storage of the answer is always the emitting command's job (mirroring the
+ * deploy families), so responders never need to know what `scope:key` means —
+ * they just render and reply.
+ */
+export interface InterviewRequiredPayload {
+  /** Stable namespace for the question, e.g. `service:proxmox-home-lab`. */
+  scope: string;
+  /** Stable identifier within the scope, e.g. `default_target_node`. */
+  key: string;
+  kind: InterviewKind;
+  message: string;
+  required: boolean;
+  description?: string;
+  /** For `text`/`select`: the value used if the operator just hits Enter. For `confirm`: `'true'` | `'false'`. */
+  defaultValue?: string;
+  /** `text` only — grayed-out hint shown in the input field. */
+  placeholder?: string;
+  /** `select`/`multiselect` only — the choices. */
+  options?: Array<{ value: string; label: string; hint?: string }>;
+  /** `text` only — how to coerce the typed value. Defaults to `'string'`. */
+  type?: 'string' | 'integer' | 'number' | 'boolean';
+  /** `text` only — regex the typed value must match. */
+  pattern?: string;
+  /** Set on re-emits after a previous reply failed validation. */
+  previousError?: string;
+  /** 1-indexed attempt counter. Bounds prevent infinite re-emit loops. */
+  attempt?: number;
+}
+
+/**
+ * Reply to an `interview.required.*` query. `value`'s runtime shape follows
+ * the payload's `kind`: `string` (text/select), `string[]` (multiselect),
+ * `boolean` (confirm), or `number` (text with `type: integer|number`).
+ */
+export interface InterviewReply {
+  value: unknown;
+}
+
 /**
  * Emit a query event on the bus and wait for a responder to reply.
  *
@@ -237,3 +296,176 @@ export async function busInterviewGuarded<TReply>(
   await ensureResponderForInterview(type);
   return busInterview<TReply>(type, payload, ownerBus);
 }
+
+/**
+ * Ask a single generic interview question over the bus and return the
+ * responder's answer (ISS-0127). The generic counterpart to the deploy's
+ * config/secret/ensure interview: any operator command can call this to make
+ * its prompts headlessly drivable instead of calling clack directly.
+ *
+ * The return type is `unknown` because the runtime shape depends on
+ * `payload.kind`; prefer the typed wrappers (`askText`, `askSelect`,
+ * `askMultiselect`, `askConfirm`) at call sites — they narrow it for you.
+ *
+ * Guarded like the deploy families: a non-TTY caller with no responder
+ * listening fails fast instead of hanging forever.
+ */
+export async function askInterview(
+  payload: InterviewRequiredPayload,
+  ownerBus?: Bus,
+): Promise<unknown> {
+  const reply = await busInterviewGuarded<InterviewReply>(
+    EVENT_TYPES.interviewRequired(payload.scope, payload.key),
+    payload,
+    ownerBus,
+  );
+  return reply.value;
+}
+
+/**
+ * Run `fn` with a terminal-responder active when stdin is a TTY (ISS-0127).
+ *
+ * Every operator command that asks questions over the bus must, on a TTY,
+ * run a responder itself to render those questions — `askInterview`'s guard
+ * (`ensureResponderForInterview`) assumes one is already up when stdin is a
+ * TTY (it skips the no-responder check). On a non-TTY run no responder is
+ * started; the headless responder (`events respond --values` / `events
+ * reply`) answers instead, and the guard fails fast if none is listening.
+ *
+ * This is the shared lifecycle every migrated command wraps its interview in,
+ * so the start/close boilerplate lives in exactly one place. The dynamic
+ * import keeps clack out of the non-TTY path's module graph.
+ */
+export async function withInterviewSession<T>(fn: () => Promise<T>): Promise<T> {
+  const responder = process.stdin.isTTY
+    ? (await import('./terminal-responder')).startTerminalResponder()
+    : null;
+  try {
+    return await fn();
+  } finally {
+    responder?.close();
+  }
+}
+
+/**
+ * Ask for a free-text value over the bus. Returns the coerced answer as a
+ * string (the responder coerces `integer`/`number`/`boolean` per `type`, but
+ * the value still arrives as a JSON scalar; callers that want a number should
+ * pass `type` and read it as such — here we narrow to the string form that
+ * the existing `promptText` call sites expect).
+ */
+export async function askText(opts: {
+  scope: string;
+  key: string;
+  message: string;
+  description?: string;
+  defaultValue?: string;
+  placeholder?: string;
+  required?: boolean;
+  type?: 'string' | 'integer' | 'number' | 'boolean';
+  pattern?: string;
+}): Promise<string> {
+  const value = await askInterview({
+    scope: opts.scope,
+    key: opts.key,
+    kind: 'text',
+    message: opts.message,
+    required: opts.required ?? false,
+    description: opts.description,
+    defaultValue: opts.defaultValue,
+    placeholder: opts.placeholder,
+    type: opts.type,
+    pattern: opts.pattern,
+  });
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  throw new Error(
+    `askText(${opts.scope}.${opts.key}): expected a string/number/boolean reply, got ${typeof value}`,
+  );
+}
+
+/**
+ * Ask the operator to pick one of `options` over the bus. Returns the chosen
+ * option's `value`.
+ */
+export async function askSelect(opts: {
+  scope: string;
+  key: string;
+  message: string;
+  options: Array<{ value: string; label: string; hint?: string }>;
+  defaultValue?: string;
+  description?: string;
+}): Promise<string> {
+  const value = await askInterview({
+    scope: opts.scope,
+    key: opts.key,
+    kind: 'select',
+    message: opts.message,
+    required: true,
+    options: opts.options,
+    defaultValue: opts.defaultValue,
+    description: opts.description,
+  });
+  if (typeof value !== 'string') {
+    throw new Error(
+      `askSelect(${opts.scope}.${opts.key}): expected a string reply, got ${typeof value}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Ask the operator to pick zero-or-more of `options` over the bus. Returns the
+ * chosen options' `value`s.
+ */
+export async function askMultiselect(opts: {
+  scope: string;
+  key: string;
+  message: string;
+  options: Array<{ value: string; label: string; hint?: string }>;
+  required?: boolean;
+  description?: string;
+}): Promise<string[]> {
+  const value = await askInterview({
+    scope: opts.scope,
+    key: opts.key,
+    kind: 'multiselect',
+    message: opts.message,
+    required: opts.required ?? false,
+    options: opts.options,
+    description: opts.description,
+  });
+  if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+    throw new Error(
+      `askMultiselect(${opts.scope}.${opts.key}): expected a string[] reply, got ${typeof value}`,
+    );
+  }
+  return value as string[];
+}
+
+/**
+ * Ask a yes/no question over the bus. Returns the operator's boolean answer.
+ */
+export async function askConfirm(opts: {
+  scope: string;
+  key: string;
+  message: string;
+  defaultValue?: boolean;
+  description?: string;
+}): Promise<boolean> {
+  const value = await askInterview({
+    scope: opts.scope,
+    key: opts.key,
+    kind: 'confirm',
+    message: opts.message,
+    required: true,
+    defaultValue: opts.defaultValue === undefined ? undefined : String(opts.defaultValue),
+    description: opts.description,
+  });
+  if (typeof value !== 'boolean') {
+    throw new Error(
+      `askConfirm(${opts.scope}.${opts.key}): expected a boolean reply, got ${typeof value}`,
+    );
+  }
+  return value;
+}

package/src/services/bus-secret-flow.test.ts

@@ -350,7 +350,7 @@ describe('bus-mediated interviewForMissingSecrets', () => {
     const { seen, close } = startTestResponder(
       bus,
       'secret.required.testmod.ddns_passwords',
-      { value: JSON.stringify({ 'lunacycle.net': 'pw1', 'celilo.computer': 'pw2' }) },
+      { value: JSON.stringify({ 'example.net': 'pw1', 'celilo.computer': 'pw2' }) },
       testDb,
     );
 
@@ -380,7 +380,7 @@ describe('bus-mediated interviewForMissingSecrets', () => {
 
     const masterKey = await getOrCreateMasterKey();
     const stored = await readModuleSecretKey('testmod', 'ddns_passwords', testDb, masterKey);
-    expect(stored).toBe(JSON.stringify({ 'lunacycle.net': 'pw1', 'celilo.computer': 'pw2' }));
+    expect(stored).toBe(JSON.stringify({ 'example.net': 'pw1', 'celilo.computer': 'pw2' }));
 
     close();
   });

package/src/services/celilo-mgmt-hooks.test.ts

@@ -18,6 +18,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { skipIntegration } from '../test-utils/integration-guard';
 
 import type { HookContext } from '@celilo/capabilities';
 
@@ -77,7 +78,7 @@ function buildContext(extras: Record<string, unknown>): HookContext {
   } as HookContext;
 }
 
-describe('celilo-mgmt on_backup', () => {
+describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', () => {
   let dir: string;
   let backupDir: string;
   let crossModuleRoot: string;
@@ -214,7 +215,7 @@ describe('celilo-mgmt on_backup', () => {
   });
 });
 
-describe('celilo-mgmt on_restore', () => {
+describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_restore', () => {
   let dir: string;
   let restoreDir: string;
   let crossModuleWriteRoot: string;

package/src/services/deploy-preflight.ts

@@ -29,6 +29,7 @@ import { capabilities, moduleConfigs, modules, secrets } from '../db/schema';
 import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import { buildResolutionContext } from '../variables/context';
 import { E2E_CONFLICT_FIX, runningE2eContainers } from './e2e-guard';
+import { describeCapabilityProblem, findBrokenCapabilityDerivations } from './fleet-checks';
 
 export interface PreflightResult {
   success: boolean;
@@ -232,6 +233,30 @@ export async function runPreflight(
         });
       }
     }
+
+    // 4b. Capability-derived variables resolve to a concrete value. The
+    // scan above only catches values that ARE present-but-templated; a
+    // required `source: capability` var whose chain is broken upstream is
+    // silently DROPPED during derivation (the hasUnresolved guard), so it's
+    // absent from selfConfig entirely and a template `$self:<x>` later dies
+    // with a cryptic "not found". Assert it here against the RESOLVED
+    // capabilities map so the operator gets the named missing link up front
+    // instead of at generate time (ISS-0095 / ISS-0115).
+    for (const problem of findBrokenCapabilityDerivations(
+      moduleId,
+      manifest,
+      context.capabilities,
+    )) {
+      errors.push({
+        category: problem.reason === 'no-provider' ? 'missing-capability' : 'unresolved-template',
+        message: describeCapabilityProblem(problem),
+        variable: problem.variable,
+        suggestion:
+          problem.reason === 'no-provider'
+            ? `Deploy a module that provides '${problem.capability}', then redeploy '${moduleId}'`
+            : `Redeploy '${problem.capability}'s provider so it populates ${problem.capability}.${problem.path}, then redeploy '${moduleId}'`,
+      });
+    }
   } catch (error) {
     // Resolution context may fail — that's informative too
     warnings.push({

package/src/services/deploy-validation.test.ts

@@ -15,14 +15,14 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { type DbClient, getDb } from '../db/client';
 import { modules, secrets } from '../db/schema';
 import type { ModuleManifest } from '../manifest/schema';
 import { findMissingSecrets } from './config-interview';
-import { findMissingRequiredVariables } from './deploy-validation';
+import { findMissingBuildArtifacts, findMissingRequiredVariables } from './deploy-validation';
 
 function manifestWithStringMapSecret(): ModuleManifest {
   return {
@@ -265,8 +265,8 @@ describe('findMissingSecrets (shared)', () => {
     // The terminal-responder reads these off the bus payload to apply
     // input-time regex validation. Without manifest → MissingVariable
     // propagation, the responder never sees them and operators end
-    // up entering invalid keys (e.g. 'www.lunacycle.net' instead of
-    // the apex 'lunacycle.net').
+    // up entering invalid keys (e.g. 'www.example.net' instead of
+    // the apex 'example.net').
     const missing = await findMissingSecrets(
       'testmod',
       {
@@ -293,3 +293,53 @@ describe('findMissingSecrets (shared)', () => {
     expect(missing[0].value_pattern_message).toBe('min 8 chars');
   });
 });
+
+/**
+ * The deploy build-gate: the management server does NOT build modules from
+ * source. A module's declared artifacts must already be present on disk
+ * (shipped in the .netapp at `module package` / `module publish` time). Deploy
+ * verifies them; a missing artifact is a hard error, never a from-source
+ * rebuild on the management box (ISS-0131).
+ */
+describe('findMissingBuildArtifacts (deploy build-gate)', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'build-gate-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function manifestWithArtifacts(artifacts: string[]): ModuleManifest {
+    return {
+      celilo_contract: '1.0',
+      id: 'buildmod',
+      name: 'Build Module',
+      version: '1.0.0',
+      description: 'fixture',
+      build: { command: 'true', artifacts },
+    } as unknown as ModuleManifest;
+  }
+
+  test('returns [] when the module declares no build section', () => {
+    const manifest = { celilo_contract: '1.0', id: 'm', version: '1.0.0' } as ModuleManifest;
+    expect(findMissingBuildArtifacts(manifest, dir)).toEqual([]);
+  });
+
+  test('returns [] when all declared artifacts exist on disk (prebuilt .netapp)', () => {
+    mkdirSync(join(dir, 'dist'), { recursive: true });
+    writeFileSync(join(dir, 'dist', 'server'), 'binary');
+    writeFileSync(join(dir, 'dist', 'index.html'), '<html>');
+    const manifest = manifestWithArtifacts(['dist/server', 'dist/index.html']);
+    expect(findMissingBuildArtifacts(manifest, dir)).toEqual([]);
+  });
+
+  test('returns the missing artifacts when some are absent (no mgmt-server rebuild)', () => {
+    mkdirSync(join(dir, 'dist'), { recursive: true });
+    writeFileSync(join(dir, 'dist', 'server'), 'binary');
+    const manifest = manifestWithArtifacts(['dist/server', 'dist/index.html', 'dist/db.sqlite']);
+    expect(findMissingBuildArtifacts(manifest, dir)).toEqual(['dist/index.html', 'dist/db.sqlite']);
+  });
+});

package/src/services/deploy-validation.ts

@@ -14,14 +14,12 @@ import type { ModuleManifest } from '../manifest/schema';
 import { isPrivilegedCapability } from '../manifest/validate';
 import { generateTemplates } from '../templates/generator';
 import { findMissingSecrets } from './config-interview';
-import { buildModuleFromSource, getModuleBuildStatus, verifyArtifactsExist } from './module-build';
 
 export interface ValidationResult {
   success: boolean;
   error?: string;
   warnings?: string[];
   autoGenerated?: boolean;
-  autoBuilt?: boolean;
   missingVariables?: Array<{
     name: string;
     source: 'user' | 'secret' | 'capability' | 'system';
@@ -41,9 +39,27 @@ export interface ValidationResult {
   }>;
 }
 
+/**
+ * Declared build artifacts that are missing on disk.
+ *
+ * Modules are built when their package is created: `module package` /
+ * `module publish` runs `manifest.build.command` and bakes the declared
+ * artifacts into the .netapp (cross-arch binaries and all). By deploy time —
+ * from the registry in production, or via `celilo package` in e2e — those
+ * artifacts are already on disk, so deploy only VERIFIES them. An empty result
+ * means the module is built; a non-empty result is a hard deploy error, because
+ * the management server does NOT build from source (ISS-0131: a from-source
+ * rebuild on the 3.7 GB management box deadlocked at `bun install`, then
+ * OOM-crashed nx workers, despite the .netapp shipping the binaries).
+ */
+export function findMissingBuildArtifacts(manifest: ModuleManifest, sourcePath: string): string[] {
+  const declared = manifest.build?.artifacts ?? [];
+  return declared.filter((rel) => !existsSync(join(sourcePath, rel)));
+}
+
 /**
  * Validate module is ready for deployment and auto-prepare if needed
- * Policy + Execution function - checks prerequisites and runs generate/build if needed
+ * Policy + Execution function - checks prerequisites and runs generate if needed
  *
  * @param moduleId - Module identifier
  * @param db - Database connection
@@ -54,7 +70,6 @@ export async function validateAndPrepareDeployment(
   db: DbClient,
 ): Promise<ValidationResult> {
   let autoGenerated = false;
-  let autoBuilt = false;
 
   // Check module exists
   const module = await db.select().from(modules).where(eq(modules.id, moduleId)).get();
@@ -107,7 +122,6 @@ export async function validateAndPrepareDeployment(
     return {
       success: true,
       autoGenerated: false,
-      autoBuilt: false,
       missingVariables,
     };
   }
@@ -131,42 +145,19 @@ export async function validateAndPrepareDeployment(
 
   autoGenerated = true;
 
-  // Auto-build if required and not built
-  if (manifest.build) {
-    const buildStatus = await getModuleBuildStatus(moduleId, db);
-    // Cross-check the manifest's declared artifacts against the actual
-    // filesystem in addition to whatever's in the build record. A "success"
-    // record with an empty artifact list (e.g. from a build that exited 0
-    // but produced nothing, or a synthetic record from a partial .netapp
-    // import) would otherwise pass `verifyArtifactsExist([])` trivially and
-    // let the deploy run on without binaries — exactly how Ansible ends up
-    // failing on a missing `src:` file.
-    const declaredArtifacts = manifest.build.artifacts ?? [];
-    const declaredArtifactsOk = declaredArtifacts.every((rel) =>
-      existsSync(join(module.sourcePath, rel)),
-    );
-    const needsBuild =
-      !buildStatus ||
-      buildStatus.status !== 'success' ||
-      !verifyArtifactsExist(buildStatus.artifacts) ||
-      (declaredArtifacts.length > 0 && !declaredArtifactsOk);
-
-    if (needsBuild) {
-      const buildResult = await buildModuleFromSource(moduleId, db);
-      if (!buildResult.success) {
-        return {
-          success: false,
-          error: `Auto-build failed: ${buildResult.error || 'Build failed'}`,
-        };
-      }
-      autoBuilt = true;
-    }
+  // Verify build artifacts are present — the management server does NOT build
+  // modules from source (see findMissingBuildArtifacts / ISS-0131).
+  const missingArtifacts = findMissingBuildArtifacts(manifest, module.sourcePath);
+  if (missingArtifacts.length > 0) {
+    return {
+      success: false,
+      error: `Module '${moduleId}' is missing build artifacts that must ship in its package:\n${missingArtifacts.map((m) => `  - ${m}`).join('\n')}\n\nThe management server does not build modules from source. Build where the module is authored, then republish and update:\n  celilo module publish <path>   (or: celilo module build ${moduleId})\n  celilo module update`,
+    };
   }
 
   return {
     success: true,
     autoGenerated,
-    autoBuilt,
   };
 }
 

package/src/services/dns-internal-records.test.ts

@@ -0,0 +1,126 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { DnsRecordRequest } from '@celilo/capabilities';
+import type { DbClient } from '../db/client';
+import { modules } from '../db/schema';
+import { setupTestDatabase } from '../test-utils/setup-test-db';
+import {
+  listDnsInternalRecords,
+  recordDnsInternalRecord,
+  removeDnsInternalRecord,
+  withDnsInternalLedger,
+} from './dns-internal-records';
+
+describe('dns-internal-records ledger', () => {
+  let dir: string;
+  let dbPath: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'dns-int-'));
+    dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabase(dbPath);
+    // FK targets: provider + consumer modules.
+    for (const id of ['technitium', 'forgejo']) {
+      db.insert(modules)
+        .values({
+          id,
+          name: id,
+          version: '1.0.0',
+          state: 'VERIFIED',
+          manifestData: {},
+          sourcePath: `/src/${id}`,
+        })
+        .run();
+    }
+  });
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  const ctx = () => ({ db, providerModuleId: 'technitium', consumerModuleId: 'forgejo' });
+
+  it('records, lists, and upserts by (provider, host)', () => {
+    recordDnsInternalRecord(db, { ...ctx(), host: 'git-ssh.x', ip: '10.0.20.14' });
+    let rows = listDnsInternalRecords(db);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].ip).toBe('10.0.20.14');
+
+    // Same (provider, host) updates in place — the natIp fix re-registering.
+    recordDnsInternalRecord(db, { ...ctx(), host: 'git-ssh.x', ip: '192.168.0.253' });
+    rows = listDnsInternalRecords(db);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].ip).toBe('192.168.0.253');
+  });
+
+  it('removes a record by (provider, host)', () => {
+    recordDnsInternalRecord(db, { ...ctx(), host: 'a.x', ip: '1.1.1.1' });
+    recordDnsInternalRecord(db, { ...ctx(), host: 'b.x', ip: '2.2.2.2' });
+    removeDnsInternalRecord(db, { providerModuleId: 'technitium', host: 'a.x' });
+    const rows = listDnsInternalRecords(db);
+    expect(rows.map((r) => r.host)).toEqual(['b.x']);
+  });
+
+  describe('withDnsInternalLedger', () => {
+    function fakeProvider() {
+      const calls: Array<['register' | 'delete', DnsRecordRequest]> = [];
+      const iface = {
+        async registerRecord(req: DnsRecordRequest) {
+          calls.push(['register', req]);
+        },
+        async deleteRecord(req: DnsRecordRequest) {
+          calls.push(['delete', req]);
+        },
+      };
+      return { iface, calls };
+    }
+
+    it('records A-record registrations and passes the call through', async () => {
+      const { iface, calls } = fakeProvider();
+      const wrapped = withDnsInternalLedger(iface, ctx());
+      await wrapped.registerRecord({ host: 'git-ssh.x', type: 'A', value: '192.168.0.253' });
+      expect(calls).toHaveLength(1); // underlying provider still called
+      const rows = listDnsInternalRecords(db);
+      expect(rows).toHaveLength(1);
+      expect(rows[0]).toMatchObject({ host: 'git-ssh.x', ip: '192.168.0.253' });
+    });
+
+    it('does NOT ledger non-A records', async () => {
+      const { iface } = fakeProvider();
+      const wrapped = withDnsInternalLedger(iface, ctx());
+      await wrapped.registerRecord({ host: 'mail.x', type: 'MX', value: 'mx.x' });
+      expect(listDnsInternalRecords(db)).toHaveLength(0);
+    });
+
+    it('removes the ledger row on A-record delete', async () => {
+      const { iface } = fakeProvider();
+      const wrapped = withDnsInternalLedger(iface, ctx());
+      await wrapped.registerRecord({ host: 'git-ssh.x', type: 'A', value: '192.168.0.253' });
+      await wrapped.deleteRecord({ host: 'git-ssh.x', type: 'A', value: '192.168.0.253' });
+      expect(listDnsInternalRecords(db)).toHaveLength(0);
+    });
+
+    it('does not write the ledger if the underlying register throws', async () => {
+      const iface = {
+        async registerRecord(): Promise<void> {
+          throw new Error('resolver down');
+        },
+        async deleteRecord(): Promise<void> {},
+      };
+      const wrapped = withDnsInternalLedger(iface, ctx());
+      await expect(
+        wrapped.registerRecord({ host: 'git-ssh.x', type: 'A', value: '1.2.3.4' }),
+      ).rejects.toThrow('resolver down');
+      expect(listDnsInternalRecords(db)).toHaveLength(0);
+    });
+  });
+});