@celilo/cli 0.4.0-alpha.1 → 0.4.1

package/src/services/restore-from-file.ts

@@ -16,13 +16,18 @@
  * of the restore the hook itself cannot do (live DB is open).
  */
 
+import { Database } from 'bun:sqlite';
 import { execSync } from 'node:child_process';
 import {
   chmodSync,
+  closeSync,
   copyFileSync,
+  cpSync,
   existsSync,
   mkdirSync,
+  openSync,
   readFileSync,
+  readSync,
   readdirSync,
   rmSync,
   writeFileSync,
@@ -30,7 +35,7 @@ import {
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { eq } from 'drizzle-orm';
-import { getDbPath, getMasterKeyPath } from '../config/paths';
+import { getDbPath, getMasterKeyPath, getModuleStoragePath } from '../config/paths';
 import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { modules } from '../db/schema';
@@ -61,6 +66,8 @@ export interface RestoreFromFileResult {
   masterKeyApplied?: boolean;
   /** Was the fleet SSH keypair restored to <dataDir>/.ssh/? */
   sshKeyApplied?: boolean;
+  /** How many module source dirs were laid down at the target's modules dir. */
+  moduleSourcesApplied?: number;
 }
 
 export interface RestoreFromFileOptions {
@@ -233,21 +240,32 @@ export async function restoreFromArtifactFile(
       }
     }
 
-    // 7. Apply staged system files (celilo.db + master.key).
-    //    These were staged by celilo-mgmt's on_restore at
-    //    restore_dir/system/. The live process has the DB open, so
-    //    this swap must happen AFTER the hook returns (which is now).
+    // 7. Complete the operation BEFORE swapping the DB. The swap
+    //    (applyStagedSystemFiles) is the final, irreversible step: it closes
+    //    the live DB and overwrites celilo.db with the artifact's. Marking the
+    //    operation complete writes to module_operations — if done AFTER the
+    //    swap it reopens the freshly-staged artifact DB in THIS process and
+    //    throws SQLITE_IOERR (a fresh process opens the same file fine; it's a
+    //    same-process post-swap reopen artifact). The operation row lives in
+    //    the pre-swap DB the swap discards anyway, so completing it here —
+    //    while that DB is still open — is correct and avoids the reopen.
+    //    Nothing in-process must touch the DB after the swap; migrateRestoredDb
+    //    (the CLI's next step) is best-effort and tolerates a reopen failure.
+    completeOperation(opId);
+
+    // 8. Apply staged system files (celilo.db + master.key + fleet SSH key).
+    //    Staged by celilo-mgmt's on_restore at restore_dir/system/. The live
+    //    process had the DB open, so this swap happens AFTER the hook returns.
     const systemStaging = join(restoreDataDir, 'system');
     const apply = applyStagedSystemFiles(systemStaging);
 
-    completeOperation(opId);
-
     return {
       success: true,
       crossModuleApplied,
       systemDbApplied: apply.dbApplied,
       masterKeyApplied: apply.keyApplied,
       sshKeyApplied: apply.sshApplied,
+      moduleSourcesApplied: apply.moduleSourcesApplied,
     };
   } finally {
     try {
@@ -262,6 +280,61 @@ export interface StagedSystemApplyResult {
   dbApplied: boolean;
   keyApplied: boolean;
   sshApplied: boolean;
+  /** How many module source dirs were laid down at the target's modules dir. */
+  moduleSourcesApplied: number;
+}
+
+/** Cheap check for the SQLite file magic without reading the whole DB. */
+function looksLikeSqlite(path: string): boolean {
+  let fd: number;
+  try {
+    fd = openSync(path, 'r');
+  } catch {
+    return false;
+  }
+  try {
+    const buf = Buffer.alloc(16);
+    readSync(fd, buf, 0, 16, 0);
+    // Magic header is "SQLite format 3" (15 bytes) + a NUL terminator.
+    return buf.subarray(0, 15).toString('utf-8') === 'SQLite format 3' && buf[15] === 0;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Recompute every module's source_path to THIS box's modules dir, on the
+ * STAGED DB file (pre-swap). The artifact carries the SOURCE box's absolute
+ * source_path (e.g. macOS `~/Library/Application Support/celilo/modules/<id>`),
+ * which doesn't exist on a different box/OS — so a restored DB references module
+ * code at a dead path and no deploy can generate. By construction (import.ts)
+ * source_path is always `${dataDir}/modules/<id>`, so it's safe to recompute for
+ * the target; a no-op when the paths already match (same-OS restore).
+ *
+ * Done on the staged file (a fresh connection that's about to be swapped in),
+ * never the live DB, so there's no post-swap in-process reopen (ISS-0037). The
+ * PRAGMA forces commits into the main file (no -wal sibling) so the copy below
+ * captures the rewrite; the live DB re-enters WAL when celilo reopens it.
+ */
+function rewriteStagedModuleSourcePaths(stagedDbPath: string): void {
+  // Tolerate non-SQLite staged files: some callers/tests stage placeholder
+  // bytes to exercise the file-copy path. A real artifact DB always opens
+  // with the "SQLite format 3\0" magic header — skip anything that doesn't
+  // (a valid-header-but-corrupt DB still surfaces by throwing below).
+  if (!looksLikeSqlite(stagedDbPath)) return;
+
+  const moduleStorageBase = getModuleStoragePath();
+  const staged = new Database(stagedDbPath);
+  try {
+    staged.query('PRAGMA journal_mode = DELETE').run();
+    const rows = staged.query('SELECT id FROM modules').all() as Array<{ id: string }>;
+    const update = staged.query('UPDATE modules SET source_path = ? WHERE id = ?');
+    for (const { id } of rows) {
+      update.run(join(moduleStorageBase, id), id);
+    }
+  } finally {
+    staged.close();
+  }
 }
 
 /**
@@ -281,14 +354,16 @@ export function applyStagedSystemFiles(systemStagingDir: string): StagedSystemAp
   let dbApplied = false;
   let keyApplied = false;
   let sshApplied = false;
+  let moduleSourcesApplied = 0;
 
   if (!existsSync(systemStagingDir)) {
-    return { dbApplied, keyApplied, sshApplied };
+    return { dbApplied, keyApplied, sshApplied, moduleSourcesApplied };
   }
 
   const stagedDb = join(systemStagingDir, 'celilo.db');
   const stagedKey = join(systemStagingDir, 'master.key');
   const stagedSsh = join(systemStagingDir, 'ssh');
+  const stagedModuleSrc = join(systemStagingDir, 'module_src');
 
   // master.key first: it's not load-bearing for the running process
   // (already in memory if the daemon's running). Safe to swap before
@@ -319,9 +394,31 @@ export function applyStagedSystemFiles(systemStagingDir: string): StagedSystemAp
     sshApplied = true;
   }
 
+  // Module SOURCE code → lay down at THIS box's modules dir so the restored
+  // box has the code for EVERY module (incl. non-registry ones like lunacycle).
+  // on_backup captured each module's source; without this the restored DB
+  // references modules whose code isn't on disk and no deploy can generate.
+  // The artifact carries no generated/ subtree, so any existing generated/
+  // under a module dir (e.g. restored TF state) is preserved by the merge.
+  if (existsSync(stagedModuleSrc)) {
+    const moduleStorageBase = getModuleStoragePath();
+    mkdirSync(moduleStorageBase, { recursive: true });
+    for (const entry of readdirSync(stagedModuleSrc, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      cpSync(join(stagedModuleSrc, entry.name), join(moduleStorageBase, entry.name), {
+        recursive: true,
+      });
+      moduleSourcesApplied += 1;
+    }
+  }
+
   // celilo.db: must close the live DB connection before replacing
   // the file or SQLite gets confused (macOS holds a vnode handle).
   if (existsSync(stagedDb)) {
+    // Reconcile module source_paths to THIS box on the staged file BEFORE the
+    // swap (and before closeDb) — fixes cross-host / cross-OS restores. See
+    // rewriteStagedModuleSourcePaths.
+    rewriteStagedModuleSourcePaths(stagedDb);
     closeDb();
     const livePath = getDbPath();
     mkdirSync(join(livePath, '..'), { recursive: true });
@@ -338,7 +435,7 @@ export function applyStagedSystemFiles(systemStagingDir: string): StagedSystemAp
     dbApplied = true;
   }
 
-  return { dbApplied, keyApplied, sshApplied };
+  return { dbApplied, keyApplied, sshApplied, moduleSourcesApplied };
 }
 
 /**

package/src/services/storage-providers/s3.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Recurrence gate for ISS-0016: the S3 provider's upload() must send a
+ * self-describing, replayable Buffer body — NOT a one-shot Node read stream.
+ *
+ * The original bug passed `createReadStream(localPath)` as PutObject Body with
+ * no ContentLength; AWS SDK v3 fell back to aws-chunked streaming and failed
+ * with "The request body terminated unexpectedly" (and couldn't replay the
+ * stream across S3's retries/redirects). The verify path used a string body
+ * (length known) and so never exercised the broken path — every real S3 backup
+ * silently failed. These tests upload a REAL on-disk file and assert the body
+ * is a Buffer, so a regression back to a stream is caught here.
+ *
+ * No live S3 / MinIO harness exists, so we intercept S3Client.prototype.send
+ * and inspect the command the provider builds.
+ */
+
+import { type Mock, afterEach, describe, expect, it, spyOn } from 'bun:test';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { type S3StorageConfig, createS3StorageProvider } from './s3';
+
+const CONFIG: S3StorageConfig = {
+  bucket: 'test-bucket',
+  region: 'us-east-1',
+  endpoint: 'http://localhost:9000',
+  accessKeyId: 'test-key',
+  secretAccessKey: 'test-secret',
+};
+
+describe('s3 storage provider (ISS-0016)', () => {
+  let dir: string | undefined;
+  // biome-ignore lint/suspicious/noExplicitAny: send() is heavily overloaded; the test only reads .input.
+  let sendSpy: Mock<(command: any) => Promise<unknown>> | undefined;
+
+  afterEach(() => {
+    sendSpy?.mockRestore();
+    sendSpy = undefined;
+    if (dir) {
+      rmSync(dir, { recursive: true, force: true });
+      dir = undefined;
+    }
+  });
+
+  it('uploads a real on-disk file as a self-describing Buffer body, not a stream', async () => {
+    dir = mkdtempSync(join(tmpdir(), 's3-upload-'));
+    const file = join(dir, 'envelope.tar.gz');
+    // A multi-KB real file — the case that broke against live S3.
+    const bytes = Buffer.from('celilo backup envelope payload — '.repeat(2000));
+    writeFileSync(file, bytes);
+
+    // biome-ignore lint/suspicious/noExplicitAny: capturing the built command.
+    const sent: any[] = [];
+    sendSpy = spyOn(S3Client.prototype, 'send').mockImplementation(async (command: unknown) => {
+      sent.push(command);
+      return {};
+    });
+
+    const provider = createS3StorageProvider(CONFIG);
+    await provider.upload(file, 'celilo-mgmt/2026/envelope.tar.gz');
+
+    expect(sent).toHaveLength(1);
+    const command = sent[0];
+    expect(command).toBeInstanceOf(PutObjectCommand);
+
+    const body = command.input.Body;
+    // The regression gate: a Node read stream (the original bug) is not a Buffer.
+    expect(Buffer.isBuffer(body)).toBe(true);
+    expect(body instanceof Readable).toBe(false);
+    // Self-describing length == the whole file: the SDK derives ContentLength
+    // and can replay the body across retries/redirects.
+    expect(body.length).toBe(bytes.length);
+    expect(Buffer.compare(body, bytes)).toBe(0);
+    // Key is prefixed with the backup namespace.
+    expect(command.input.Key).toBe('celilo-backups/celilo-mgmt/2026/envelope.tar.gz');
+    expect(command.input.Bucket).toBe('test-bucket');
+  });
+
+  it('downloads a multi-chunk response body to disk intact (short-read safe)', async () => {
+    dir = mkdtempSync(join(tmpdir(), 's3-download-'));
+    const out = join(dir, 'restored.bin');
+    const chunks = [Buffer.from('chunk-1-'), Buffer.from('chunk-2-'), Buffer.from('chunk-3')];
+    const expected = Buffer.concat(chunks);
+
+    sendSpy = spyOn(S3Client.prototype, 'send').mockImplementation(async (command: unknown) => {
+      expect(command).toBeInstanceOf(GetObjectCommand);
+      const body = new Readable({ read() {} });
+      // Push several chunks separately to model short reads over the wire.
+      for (const chunk of chunks) body.push(chunk);
+      body.push(null);
+      return { Body: body };
+    });
+
+    const provider = createS3StorageProvider(CONFIG);
+    await provider.download('celilo-mgmt/2026/envelope.tar.gz', out);
+
+    expect(readFileSync(out)).toEqual(expected);
+  });
+});

package/src/templates/generator.test.ts

@@ -9,6 +9,7 @@ import {
   discoverTemplateFiles,
   generateTemplates,
   getOutputFilename,
+  injectProxmoxLxcDns,
   isTemplateFile,
   readTemplateFiles,
   writeGeneratedFiles,
@@ -633,4 +634,80 @@ resource "proxmox_lxc" "container" {
       }
     });
   });
+
+  describe('injectProxmoxLxcDns', () => {
+    const LXC = [
+      'resource "proxmox_lxc" "caddy" {',
+      '  target_node  = "pve"',
+      '  start        = true',
+      '  network {',
+      '    bridge = "vmbr0"',
+      '  }',
+      '}',
+    ].join('\n');
+
+    test('injects nameserver + lifecycle when a nameserver is computable', () => {
+      const out = injectProxmoxLxcDns(LXC, true);
+      expect(out).toContain('  nameserver = "$self:lxc_nameserver"');
+      expect(out).toContain('  lifecycle {');
+      expect(out).toContain('    ignore_changes = [nameserver]');
+      // Injected immediately after the opening line, before author attributes.
+      const lines = out.split('\n');
+      expect(lines[0]).toBe('resource "proxmox_lxc" "caddy" {');
+      expect(lines[1]).toBe('  nameserver = "$self:lxc_nameserver"');
+      expect(lines[2]).toBe('  lifecycle {');
+      // Author's attributes and nested blocks are untouched.
+      expect(out).toContain('  target_node  = "pve"');
+      expect(out).toContain('  network {');
+    });
+
+    test('injects lifecycle only (no nameserver) when none is computable', () => {
+      const out = injectProxmoxLxcDns(LXC, false);
+      expect(out).not.toContain('nameserver = "$self:lxc_nameserver"');
+      expect(out).toContain('  lifecycle {');
+      expect(out).toContain('    ignore_changes = [nameserver]');
+    });
+
+    test('is idempotent — already-injected content is returned unchanged', () => {
+      const once = injectProxmoxLxcDns(LXC, true);
+      const twice = injectProxmoxLxcDns(once, true);
+      expect(twice).toBe(once);
+    });
+
+    test('does not double-inject nameserver when the template already has one', () => {
+      // A stale copied module (or an author-set nameserver) — injecting a second
+      // would be a terraform "Attribute redefined" error.
+      const stale = [
+        'resource "proxmox_lxc" "caddy" {',
+        '  target_node  = "pve"',
+        '  nameserver   = "$self:lxc_nameserver"',
+        '  start        = true',
+        '}',
+      ].join('\n');
+      const out = injectProxmoxLxcDns(stale, true);
+      // Exactly one nameserver attribute survives.
+      expect(out.match(/nameserver\s*=/g)?.length).toBe(1);
+      // The lifecycle guard is still added.
+      expect(out).toContain('ignore_changes = [nameserver]');
+    });
+
+    test('leaves non-proxmox_lxc resources untouched', () => {
+      const vm = ['resource "proxmox_vm" "build" {', '  cores = 4', '}'].join('\n');
+      expect(injectProxmoxLxcDns(vm, true)).toBe(vm);
+    });
+
+    test('injects into every proxmox_lxc block in a multi-resource file', () => {
+      const two = `${LXC}\n\n${LXC.replace('"caddy"', '"forgejo"')}`;
+      const out = injectProxmoxLxcDns(two, true);
+      expect(out.match(/ignore_changes = \[nameserver\]/g)?.length).toBe(2);
+    });
+
+    test('matches the indentation of the resource opening line', () => {
+      const indented = ['  resource "proxmox_lxc" "x" {', '    cores = 1', '  }'].join('\n');
+      const out = injectProxmoxLxcDns(indented, true);
+      expect(out).toContain('    nameserver = "$self:lxc_nameserver"');
+      expect(out).toContain('    lifecycle {');
+      expect(out).toContain('      ignore_changes = [nameserver]');
+    });
+  });
 });

package/src/templates/generator.ts

@@ -126,6 +126,67 @@ export function getOutputFilename(templateFilename: string): string {
   return result;
 }
 
+/**
+ * Inject framework-owned DNS-at-birth into every `proxmox_lxc` resource.
+ *
+ * An LXC's nameserver is infrastructure celilo owns — like vmid, target_ip, and
+ * inventory — not something a module author hand-writes. Authors declare zero
+ * DNS terraform; this stamps it onto each `proxmox_lxc` block at generate time.
+ * For every block it emits:
+ *
+ *   - `nameserver = "$self:lxc_nameserver"` — only when a nameserver is
+ *     computable (`hasNameserver`). The first LXC, deployed before any
+ *     `dns_internal` provider exists, has no value: it inherits the Proxmox
+ *     node default and the `dns-client-config` aspect repairs resolv.conf
+ *     post-deploy.
+ *   - `lifecycle { ignore_changes = [nameserver] }` — always. Existing LXCs
+ *     were born without a nameserver, so setting one is an in-place UPDATE the
+ *     terraform-safety guard (create-only, see terraform-safety.ts) rejects.
+ *     `ignore_changes` makes nameserver birth-only: terraform sets it at create
+ *     and never diffs it again, so the guard never trips on a redeploy. The
+ *     aspect owns the live resolv.conf from then on (terraform = birth DNS,
+ *     aspect = ongoing DNS). See v2/LXC_INTERNAL_DNS.md.
+ *
+ * Anchored on the resource's opening line — it never brace-matches the nested
+ * rootfs/network/features blocks, so it's robust to attribute order/formatting.
+ * Idempotent at file granularity: a `.tf` that already declares
+ * `ignore_changes = [nameserver]` (re-run, or an author who opted in) is
+ * returned untouched.
+ *
+ * Policy function (Rule 10.1) - pure string transformation, no I/O.
+ *
+ * @param content - Raw terraform template content (pre variable-resolution)
+ * @param hasNameserver - Whether `$self:lxc_nameserver` resolves to a value
+ * @returns Content with DNS injected into each proxmox_lxc resource
+ */
+export function injectProxmoxLxcDns(content: string, hasNameserver: boolean): string {
+  // Already injected (idempotent) or author opted into the lifecycle — done.
+  if (content.includes('ignore_changes = [nameserver]')) {
+    return content;
+  }
+
+  // A template that still carries a `nameserver = …` attribute — a stale copied
+  // module from before the per-template lines were reverted, or an author who
+  // set it by hand — already supplies the value. Injecting a second `nameserver`
+  // is a terraform "Attribute redefined" error. So skip the value line when one
+  // exists and just add the lifecycle guard (the load-bearing part). Both cases
+  // converge on exactly one nameserver + ignore_changes.
+  const alreadyHasNameserver = /^[ \t]*nameserver[ \t]*=/m.test(content);
+
+  const openLineRe = /^([ \t]*)resource\s+"proxmox_lxc"\s+"[^"]+"\s*\{[ \t]*$/gm;
+  return content.replace(openLineRe, (openLine, indent: string) => {
+    const inner = `${indent}  `;
+    const injected = [openLine];
+    if (hasNameserver && !alreadyHasNameserver) {
+      injected.push(`${inner}nameserver = "$self:lxc_nameserver"`);
+    }
+    injected.push(`${inner}lifecycle {`);
+    injected.push(`${inner}  ignore_changes = [nameserver]`);
+    injected.push(`${inner}}`);
+    return injected.join('\n');
+  });
+}
+
 /**
  * Discover template files in directory recursively
  *
@@ -833,9 +894,15 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
     } else {
       // Template files (.tpl, .j2) - apply variable resolution
       const isAnsibleTemplate = template.targetPath.includes('ansible/');
+      // Framework-owned DNS-at-birth: stamp nameserver + ignore_changes onto
+      // every proxmox_lxc resource before resolution (terraform files only).
+      const content =
+        !isAnsibleTemplate && template.targetPath.endsWith('.tf')
+          ? injectProxmoxLxcDns(template.content, Boolean(context.selfConfig.lxc_nameserver))
+          : template.content;
       const result = isAnsibleTemplate
-        ? await convertSecretsToJinja(template.content, context, db)
-        : await resolveTemplate(template.content, context, db);
+        ? await convertSecretsToJinja(content, context, db)
+        : await resolveTemplate(content, context, db);
 
       if (!result.success) {
         resolutionErrors.push({

package/src/variables/context.ts

@@ -471,6 +471,40 @@ export async function buildResolutionContext(
     systemConfigMap[row.key] = row.value;
   }
 
+  // LXC nameserver list (v2/LXC_INTERNAL_DNS.md). Proxmox's `nameserver` is a
+  // space-separated primary/secondary list. Compose it so every celilo-built
+  // LXC boots with a working resolver — before Ansible's apt update, and
+  // independent of which Proxmox node it lands on (the nodes' DNS defaults
+  // diverge): the internal dns_internal resolver first (it recurses, so it
+  // also answers external names), then the public resolvers as fallback.
+  // Bootstrap (no dns_internal provider registered yet — e.g. the DNS module's
+  // own LXC) → public only, so apt still works. Injected as
+  // $self:lxc_nameserver, mirroring how inventory.* are auto-derived; the
+  // proxmox_lxc terraform template drops it straight into `nameserver`.
+  {
+    const publicDns: string[] = [];
+    for (const key of ['dns.primary', 'dns.fallback']) {
+      const raw = systemConfigMap[key];
+      if (raw) {
+        for (const part of raw.split(',')) {
+          const ip = part.trim();
+          if (ip) publicDns.push(ip);
+        }
+      }
+    }
+    const dnsInternal = capabilitiesMap.dns_internal as { server?: { ip?: unknown } } | undefined;
+    // The dns_internal capability advertises the provider's address, which may
+    // carry a CIDR suffix (technitium's server.ip resolves from target_ip,
+    // e.g. "192.168.0.151/24"). A nameserver must be a bare IP — strip it.
+    const rawInternalIp =
+      typeof dnsInternal?.server?.ip === 'string' ? dnsInternal.server.ip : undefined;
+    const internalIp = rawInternalIp ? rawInternalIp.split('/')[0] : undefined;
+    const nameservers = internalIp ? [internalIp, ...publicDns] : publicDns;
+    if (nameservers.length > 0) {
+      selfConfig.lxc_nameserver = nameservers.join(' ');
+    }
+  }
+
   // Fetch system secrets (for $system_secret: variables)
   const systemSecretsMap: Record<string, string> = {};
   try {

package/src/variables/lxc-nameserver.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { existsSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { type DbClient, createDbClient } from '../db/client';
+import { capabilities, moduleConfigs, modules, systemConfig } from '../db/schema';
+import { buildResolutionContext } from './context';
+
+const TEST_DB_PATH = './test-lxc-nameserver.db';
+
+/**
+ * Coverage for the generate-time `lxc_nameserver` composition
+ * (v2/LXC_INTERNAL_DNS.md): proxmox_lxc templates read `$self:lxc_nameserver`,
+ * a space-separated primary/secondary list = internal dns_internal resolver
+ * first (CIDR stripped), then the public dns.primary/dns.fallback resolvers;
+ * public-only when no dns_internal provider is registered (bootstrap).
+ */
+describe('lxc_nameserver composition', () => {
+  let db: DbClient;
+
+  beforeEach(() => {
+    db = createDbClient({ path: TEST_DB_PATH });
+    db.insert(modules)
+      .values({
+        id: 'consumer',
+        name: 'consumer',
+        version: '1.0.0',
+        manifestData: { requires: { machine: { zone: 'app' } } },
+        sourcePath: '/tmp/consumer',
+      })
+      .run();
+    db.insert(moduleConfigs)
+      .values({ moduleId: 'consumer', key: 'hostname', value: 'consumer', valueJson: '"consumer"' })
+      .run();
+    for (const [key, value] of [
+      ['dns.primary', '1.1.1.1'],
+      ['dns.fallback', '1.0.0.1,8.8.8.8'],
+    ]) {
+      db.insert(systemConfig).values({ key, value }).run();
+    }
+  });
+
+  afterEach(async () => {
+    db.$client.close();
+    for (const suffix of ['', '-shm', '-wal']) {
+      const p = `${TEST_DB_PATH}${suffix}`;
+      if (existsSync(p)) await rm(p);
+    }
+  });
+
+  function registerInternalDns(ip: string): void {
+    db.insert(modules)
+      .values({
+        id: 'dns-provider',
+        name: 'dns-provider',
+        version: '1.0.0',
+        manifestData: {},
+        sourcePath: '/tmp/dns',
+      })
+      .run();
+    db.insert(capabilities)
+      .values({
+        moduleId: 'dns-provider',
+        capabilityName: 'dns_internal',
+        version: '1.0.0',
+        data: { server: { ip } },
+      })
+      .run();
+  }
+
+  test('internal resolver first (CIDR stripped) + public fallback', async () => {
+    registerInternalDns('192.168.0.151/24');
+    const ctx = await buildResolutionContext('consumer', db);
+    expect(ctx.selfConfig.lxc_nameserver).toBe('192.168.0.151 1.1.1.1 1.0.0.1 8.8.8.8');
+  });
+
+  test('bootstrap: no dns_internal provider → public resolvers only', async () => {
+    const ctx = await buildResolutionContext('consumer', db);
+    expect(ctx.selfConfig.lxc_nameserver).toBe('1.1.1.1 1.0.0.1 8.8.8.8');
+  });
+
+  test('already-bare internal IP is passed through unchanged', async () => {
+    registerInternalDns('10.0.20.30');
+    const ctx = await buildResolutionContext('consumer', db);
+    expect(ctx.selfConfig.lxc_nameserver).toBe('10.0.20.30 1.1.1.1 1.0.0.1 8.8.8.8');
+  });
+});