@celilo/cli 1.7.0 → 1.9.0

package/src/services/module-instances.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type DbClient, createDbClient } from '../db/client';
+import { deriveInstanceModuleId, ownedSystemModuleIds } from './module-instances';
+
+describe('deriveInstanceModuleId', () => {
+  test('is deterministic, so an instantiate is safe to retry', () => {
+    const a = deriveInstanceModuleId('byoi', 'lab', 'sub-abc123');
+    const b = deriveInstanceModuleId('byoi', 'lab', 'sub-abc123');
+    expect(a).toBe(b);
+  });
+
+  test('produces a valid kebab-case module id from an opaque key', () => {
+    // celilo never interprets the key, so it may be anything at all.
+    const id = deriveInstanceModuleId('byoi', 'lab', 'Sally Smith <sally@example.com> 🎉');
+    expect(id).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/);
+    expect(id.startsWith('byoi-lab-')).toBe(true);
+  });
+
+  test('two parents using the same key get different ids', () => {
+    expect(deriveInstanceModuleId('byoi', 'lab', 'shared-key')).not.toBe(
+      deriveInstanceModuleId('forgejo', 'lab', 'shared-key'),
+    );
+  });
+
+  test('one parent reusing a key across two submodules gets different ids', () => {
+    expect(deriveInstanceModuleId('forgejo', 'runner', 'proj-1')).not.toBe(
+      deriveInstanceModuleId('forgejo', 'builder', 'proj-1'),
+    );
+  });
+
+  // Without a separator in the hash input, ("a", "b-c") and ("a-b", "c") hash
+  // the same string. The kind of ambiguity that never shows up until it does.
+  test('a hyphen moving between parent and submodule changes the id', () => {
+    expect(deriveInstanceModuleId('a', 'b-c', 'k')).not.toBe(
+      deriveInstanceModuleId('a-b', 'c', 'k'),
+    );
+  });
+
+  test('a different key changes the id', () => {
+    expect(deriveInstanceModuleId('byoi', 'lab', 'one')).not.toBe(
+      deriveInstanceModuleId('byoi', 'lab', 'two'),
+    );
+  });
+});
+
+describe('module_instances storage', () => {
+  let root: string;
+  let db: DbClient;
+
+  const addModule = (id: string) =>
+    db.$client.run(
+      "INSERT INTO modules (id,name,version,manifest_data,source_path) VALUES (?,?,'1.0.0','{}','/tmp/'||?)",
+      [id, id, id],
+    );
+
+  const addInstance = (parent: string, submodule: string, key: string) => {
+    const id = deriveInstanceModuleId(parent, submodule, key);
+    addModule(id);
+    db.$client.run(
+      'INSERT INTO module_instances (module_id,parent_id,submodule,instance_key) VALUES (?,?,?,?)',
+      [id, parent, submodule, key],
+    );
+    return id;
+  };
+
+  const instanceCount = () =>
+    (db.$client.query('SELECT count(*) n FROM module_instances').get() as { n: number }).n;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'celilo-instances-'));
+    db = createDbClient({ path: join(root, 'celilo.db') });
+    for (const id of ['byoi', 'forgejo']) addModule(id);
+  });
+
+  afterEach(async () => {
+    db.$client.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test('identity is the triple, not the key alone', () => {
+    const columns = db.$client
+      .query("PRAGMA index_info('module_instances_identity_idx')")
+      .all() as Array<{ name: string }>;
+    expect(columns.map((c) => c.name)).toEqual(['parent_id', 'submodule', 'instance_key']);
+  });
+
+  test('two parents may use the same instance key', () => {
+    addInstance('byoi', 'lab', 'shared');
+    expect(() => addInstance('forgejo', 'lab', 'shared')).not.toThrow();
+    expect(instanceCount()).toBe(2);
+  });
+
+  test('one parent cannot reuse a key for the same submodule', () => {
+    addInstance('byoi', 'lab', 'dup');
+    expect(() =>
+      db.$client.run(
+        'INSERT INTO module_instances (module_id,parent_id,submodule,instance_key) VALUES (?,?,?,?)',
+        ['byoi-lab-other', 'byoi', 'lab', 'dup'],
+      ),
+    ).toThrow(/UNIQUE constraint failed/);
+  });
+
+  // A row must never outlive the parent it names.
+  test('removing a parent removes its instance rows and leaves other parents alone', () => {
+    addInstance('byoi', 'lab', 'a');
+    addInstance('forgejo', 'runner', 'b');
+    expect(instanceCount()).toBe(2);
+
+    db.$client.run("DELETE FROM modules WHERE id='byoi'");
+
+    expect(
+      db.$client.query('SELECT parent_id FROM module_instances').all() as Array<{
+        parent_id: string;
+      }>,
+    ).toEqual([{ parent_id: 'forgejo' }]);
+  });
+
+  test('an instance defaults to pending with no failure recorded', () => {
+    addInstance('byoi', 'lab', 'fresh');
+    const row = db.$client
+      .query('SELECT state, failure_reason, retryable FROM module_instances')
+      .get() as { state: string; failure_reason: string | null; retryable: number | null };
+    expect(row.state).toBe('pending');
+    expect(row.failure_reason).toBeNull();
+    expect(row.retryable).toBeNull();
+  });
+});
+
+describe('ownedSystemModuleIds', () => {
+  let root: string;
+  let db: DbClient;
+
+  const addModule = (id: string) =>
+    db.$client.run(
+      "INSERT INTO modules (id,name,version,manifest_data,source_path) VALUES (?,?,'1.0.0','{}','/tmp/'||?)",
+      [id, id, id],
+    );
+
+  const addInstance = (parent: string, submodule: string, key: string) => {
+    const id = deriveInstanceModuleId(parent, submodule, key);
+    addModule(id);
+    db.$client.run(
+      'INSERT INTO module_instances (module_id,parent_id,submodule,instance_key) VALUES (?,?,?,?)',
+      [id, parent, submodule, key],
+    );
+    return id;
+  };
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'celilo-owned-'));
+    db = createDbClient({ path: join(root, 'celilo.db') });
+    for (const id of ['forgejo', 'caddy']) addModule(id);
+  });
+
+  afterEach(async () => {
+    db.$client.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  // The state of every fleet until submodules ship, and the reason this is
+  // correct on its own rather than merely inert: an empty table gives every
+  // module itself, so a caller reaches only what it provisioned.
+  test('with no instances in existence, a module owns exactly itself', () => {
+    expect(ownedSystemModuleIds('caddy', db)).toEqual(['caddy']);
+    expect(ownedSystemModuleIds('forgejo', db)).toEqual(['forgejo']);
+  });
+
+  test('a parent gets itself and every instance it owns', () => {
+    const a = addInstance('forgejo', 'runner', 'proj-1');
+    const b = addInstance('forgejo', 'runner', 'proj-2');
+
+    const owned = ownedSystemModuleIds('forgejo', db);
+
+    expect(owned).toContain('forgejo');
+    expect(owned).toContain(a);
+    expect(owned).toContain(b);
+    expect(owned).toHaveLength(3);
+  });
+
+  test("a parent does not reach another parent's instances", () => {
+    addInstance('forgejo', 'runner', 'proj-1');
+    expect(ownedSystemModuleIds('caddy', db)).toEqual(['caddy']);
+  });
+
+  // Ownership is one level deep by construction, so the answer terminates
+  // without anyone reasoning about depth.
+  test('an instance owns nobody, so the answer is one level and terminates', () => {
+    const instance = addInstance('forgejo', 'runner', 'proj-1');
+    expect(ownedSystemModuleIds(instance, db)).toEqual([instance]);
+  });
+
+  test('a module that does not exist owns only the name it was asked about', () => {
+    expect(ownedSystemModuleIds('never-installed', db)).toEqual(['never-installed']);
+  });
+});

package/src/services/module-instances.ts

@@ -0,0 +1,96 @@
+/**
+ * Instance identity (openspec/changes/submodules, D2 and D4).
+ *
+ * A parent module addresses the instances it owns by an opaque key it chose.
+ * celilo addresses them by a `modules.id`, because an instance IS a module row,
+ * and that is what lets every reader keyed on `moduleId` keep working. This
+ * file is the single place those two names meet, so the mapping cannot drift.
+ *
+ * The rest of the submodules mechanism (the symlink farm an instance's install
+ * is, the deploy-worker capability, the lifecycle) is not here. This is the
+ * identity and the ownership question, landed ahead of it because
+ * `hook-process-boundary` stage 3 needs `ownedSystemModuleIds` and nothing else
+ * from that change.
+ */
+
+import { createHash } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { moduleInstances } from '../db/schema';
+
+/**
+ * Bits of hash in a derived instance id, as hex characters.
+ *
+ * 12 hex characters is 48 bits, so a birthday collision needs on the order of
+ * 16 million instances of ONE submodule under ONE parent. A fleet runs tens.
+ * Short enough to read in `celilo module list`, long enough that nobody has to
+ * think about it.
+ */
+const INSTANCE_ID_HASH_CHARS = 12;
+
+/**
+ * The `modules.id` an instance runs as.
+ *
+ * Derived rather than supplied, for two reasons. The parent's key is opaque and
+ * may be anything (D2 forbids celilo interpreting it), while `modules.id` must
+ * be kebab-case. And identity is the TRIPLE of parent, submodule and key, so
+ * the first two have to be inside the hash, or two parents using the same key
+ * would collide.
+ *
+ * Deterministic: the same triple always yields the same id, which is what makes
+ * an instantiate safe to retry.
+ */
+export function deriveInstanceModuleId(
+  parentId: string,
+  submodule: string,
+  instanceKey: string,
+): string {
+  // The separator matters. Hashing the concatenation alone would let
+  // ("a", "b-c") and ("a-b", "c") collide, which is the kind of ambiguity that
+  // never shows up until it does.
+  const digest = createHash('sha256')
+    .update(`${parentId} ${submodule} ${instanceKey}`)
+    .digest('hex')
+    .slice(0, INSTANCE_ID_HASH_CHARS);
+
+  return `${parentId}-${submodule}-${digest}`;
+}
+
+/**
+ * Every module id whose systems `moduleId` transitively owns: itself, plus each
+ * of its instances.
+ *
+ * This is the allow-list behind D12 of `openspec/changes/hook-process-boundary`
+ * ("a module may reach the systems it provisioned, or that its submodules
+ * provisioned"). Feed it to `getModuleSystems` per id, or use it directly as an
+ * `IN (...)` set.
+ *
+ * NOT RECURSIVE, and that is a property of the model rather than a shortcut.
+ * Nesting is refused when a parent is imported: a submodule may not declare
+ * submodules of its own, so ownership is exactly one level deep by
+ * construction. A parent owns instances, and an instance owns nothing. So this
+ * is one indexed lookup on `module_instances_parent_idx` rather than a walk,
+ * which is what makes it cheap enough to run at hook-invocation time.
+ *
+ * A recursive walk that happens to terminate and one that cannot recurse are
+ * different things, and only the second is safe to call per invocation without
+ * reasoning about depth.
+ *
+ * An instance asking gets only itself, which is correct: an instance provisions
+ * its own systems and owns nobody else's.
+ *
+ * Correct with no instances in existence, which is the state of every fleet
+ * until submodules ship: the table is empty, so every module gets `[itself]`,
+ * and a caller reaches only the systems it provisioned. That is the answer the
+ * allow-list wants today, and it picks up submodule behaviour later with no
+ * second edit.
+ */
+export function ownedSystemModuleIds(moduleId: string, db: DbClient): string[] {
+  const instances = db
+    .select({ moduleId: moduleInstances.moduleId })
+    .from(moduleInstances)
+    .where(eq(moduleInstances.parentId, moduleId))
+    .all();
+
+  return [moduleId, ...instances.map((row) => row.moduleId)];
+}

package/src/services/module-journal.test.ts

@@ -20,7 +20,7 @@ import { join } from 'node:path';
 import { type RunResult, type Runner, createMockRunner } from '@celilo/capabilities';
 import type { DbClient } from '../db/client';
 import { moduleSystems, modules } from '../db/schema';
-import { setupTestDatabase } from '../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../test-utils/database';
 import { planJournalRead, readModuleJournal } from './module-journal';
 
 /**
@@ -64,7 +64,7 @@ let db: DbClient;
 
 beforeEach(async () => {
   dir = mkdtempSync(join(tmpdir(), 'module-journal-'));
-  db = await setupTestDatabase(join(dir, 'celilo.db'));
+  db = await setupTestDatabaseAt(join(dir, 'celilo.db'));
 });
 
 afterEach(() => {

package/src/services/module-subscriptions.test.ts

@@ -9,7 +9,7 @@ import { closeDb, getDb } from '../db/client';
 import { ModuleManifestSchema } from '../manifest/schema';
 import { ModuleSubscriptionSchema } from '../manifest/schema';
 import type { ModuleManifest } from '../manifest/schema';
-import { setupTestDatabase as migrateDbFile } from '../test-utils/setup-test-db';
+import { setupTestDatabaseAt as migrateDbFile } from '../test-utils/database';
 import {
   registerModuleSubscriptions,
   resolveSubscription,

package/src/services/module-validator/capability-versions.test.ts

@@ -5,6 +5,7 @@
  */
 
 import { describe, expect, test } from 'bun:test';
+import { CAPABILITY_CONTRACT_VERSIONS } from '@celilo/capabilities';
 import { validateCapabilityVersions } from './capability-versions';
 
 describe('validateCapabilityVersions', () => {
@@ -31,7 +32,11 @@ describe('validateCapabilityVersions', () => {
     expect(errors).toHaveLength(1);
     expect(errors[0]).toContain('provides[public_web]');
     expect(errors[0]).toContain('1.0.0');
-    expect(errors[0]).toContain('3.1.0');
+    // Read from the registry, not pinned to today's number. The assertion is
+    // "the message names the RUNTIME version so the author knows what to move
+    // to"; a literal here turns a behaviour test into a version tracker that
+    // goes red on every legitimate bump, which is what happened at 3.1.0 → 3.2.0.
+    expect(errors[0]).toContain(CAPABILITY_CONTRACT_VERSIONS.public_web);
   });
 
   test('error when provides[X].version is newer than runtime', () => {

package/src/services/port-forwards.test.ts

@@ -6,8 +6,9 @@ import type { PortForwardStore } from '@celilo/capabilities';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { portForwards } from '../db/schema';
-import { setupTestDatabase } from '../test-utils/setup-test-db';
-import { buildPortForwardStore, deletePortForwardsForModule } from './port-forwards';
+import { setupTestDatabaseAt } from '../test-utils/database';
+import { deleteClaimedRows } from './capability-table-rows';
+import { buildPortForwardStore } from './port-forwards';
 
 const FW = '192.168.0.254';
 const CADDY = { internalIp: '10.0.20.5', protocol: 'TCP' as const, description: 'caddy' };
@@ -21,7 +22,7 @@ describe('port-forward store', () => {
     dir = mkdtempSync(join(tmpdir(), 'pf-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     store = buildPortForwardStore(db, 'caddy');
   });
   afterEach(() => {
@@ -113,7 +114,10 @@ describe('port-forward store', () => {
     other.replace(FW, { ...CADDY, description: 'also 443' }, [443]);
     expect(store.list(FW)).toHaveLength(2);
 
-    deletePortForwardsForModule(db, 'caddy');
+    // Through the GENERIC declaration-driven path, which replaced
+    // `deletePortForwardsForModule`. The property is unchanged; what changed is
+    // that core no longer names this capability's table to clear it.
+    deleteClaimedRows(db, 'caddy');
 
     const left = store.list(FW);
     expect(left).toHaveLength(1);

package/src/services/port-forwards.ts

@@ -99,14 +99,3 @@ export function buildPortForwardStore(db: DbClient, registeredBy: string): PortF
     },
   };
 }
-
-/**
- * Drop every forward a departing module owns, across every firewall.
- *
- * `registered_by` is plain text rather than a FK, so unlike `web_routes` these
- * rows do NOT die with the `modules` row — core deletes them explicitly, AFTER
- * the provider has converged without them (D4).
- */
-export function deletePortForwardsForModule(db: DbClient, moduleId: string): void {
-  db.delete(portForwards).where(eq(portForwards.registeredBy, moduleId)).run();
-}

package/src/services/trusted-sources.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import type { DbClient } from '../db/client';
 import { systemConfig } from '../db/schema';
 import { loadTrustedSubnets } from '../hooks/capability-loader';
-import { setupTestDatabase } from '../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../test-utils/database';
 import {
   buildTrustedSourceStore,
   composeTrustedSubnets,
@@ -26,7 +26,7 @@ describe('trusted-source store', () => {
     dir = mkdtempSync(join(tmpdir(), 'ts-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
   });
   afterEach(() => {
     db.$client.close();
@@ -138,7 +138,7 @@ describe('the render input excludes registrations; the reporting view includes t
     dir = mkdtempSync(join(tmpdir(), 'ts-render-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     db.insert(systemConfig).values({ key: 'network.internal.subnet', value: CONTROL_PLANE }).run();
     buildTrustedSourceStore(db, 'wireguard').replace(FW, {
       subnets: [VPN],

package/src/services/trusted-sources.ts

@@ -68,11 +68,6 @@ export function buildTrustedSourceStore(db: DbClient, registeredBy: string): Tru
   };
 }
 
-/** Drop every trusted source a departing module owns, across every firewall. */
-export function deleteTrustedSourcesForModule(db: DbClient, moduleId: string): void {
-  db.delete(trustedSources).where(eq(trustedSources.registeredBy, moduleId)).run();
-}
-
 /** Where a trusted subnet came from — reach into every tier must be attributable. */
 export type TrustedSubnetOrigin = 'derived-control-plane' | 'registered' | 'operator-override';
 

package/src/templates/ingress-ip.test.ts

@@ -58,8 +58,30 @@ const removeModule = async (moduleId: string): Promise<void> => {
   db.$client.prepare('DELETE FROM module_configs WHERE module_id = ?').run(moduleId);
 };
 
+/**
+ * Every module these tests name, as a real row. `module_configs` carries a
+ * foreign key onto `modules`, so without the parent the config write
+ * `ensureIngressIps` performs is rejected and the function reports failure —
+ * which is what happens in production too, and never happened here while the
+ * test helper ran with foreign keys off (celilo#1074).
+ *
+ * Worth knowing WHICH tests that would have broken. Only some: "two modules get
+ * two different addresses" fails loudly, but "REUSES the same address on a
+ * second generate" compares one unwritten value to another and passes. So a
+ * repair that chased the red would have left this file's central guard asserting
+ * `undefined === undefined`.
+ */
+const NAMED_MODULES = ['technitium', 'knot-unbound-internal', 'caddy', 'caddy-internal'];
+
 beforeEach(async () => {
   db = await setupTestDatabase();
+  for (const id of NAMED_MODULES) {
+    db.$client
+      .prepare(
+        'INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES (?, ?, ?, ?, ?)',
+      )
+      .run(id, id, '1.0.0', `/test/${id}`, '{}');
+  }
   db.$client
     .prepare('INSERT OR REPLACE INTO system_config (key, value) VALUES (?, ?)')
     .run('network.internal.subnet', '10.226.1.0/24');
@@ -78,6 +100,13 @@ describe('ensureIngressIps', () => {
     // every time the module is regenerated, and nothing reports a problem.
     await ensureIngressIps('technitium', wantsIngress, db);
     const first = storedIp('technitium');
+    // Assert the read SUCCEEDED before comparing two of them. Without this the
+    // test passes whenever BOTH reads fail the same way, which is exactly what
+    // happened when foreign keys were switched on and the config write this
+    // depends on started being rejected (celilo#1074): `undefined` equals
+    // `undefined`, and the file's central guard stayed green while proving
+    // nothing.
+    expect(first).toBeDefined();
 
     await ensureIngressIps('technitium', wantsIngress, db);
     const second = storedIp('technitium');
@@ -88,6 +117,7 @@ describe('ensureIngressIps', () => {
   test('stays stable across many generates, not just two', async () => {
     await ensureIngressIps('technitium', wantsIngress, db);
     const first = storedIp('technitium');
+    expect(first).toBeDefined();
 
     for (let i = 0; i < 5; i++) {
       await ensureIngressIps('technitium', wantsIngress, db);
@@ -179,6 +209,7 @@ describe('releasing ingress IPs on module removal', () => {
     // one address per install/remove cycle until it runs out.
     await ensureIngressIps('technitium', wantsIngress, db);
     const first = storedIp('technitium');
+    expect(first).toBeDefined();
 
     await removeModule('technitium');
     await ensureIngressIps('technitium', wantsIngress, db);

package/src/test-utils/database.ts

@@ -11,7 +11,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { drizzle } from 'drizzle-orm/bun-sqlite';
 import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
-import { type DbClient, findMigrationsFolder } from '../db/client';
+import { type DbClient, createDbClient, findMigrationsFolder } from '../db/client';
 import * as schema from '../db/schema';
 
 /**
@@ -31,6 +31,10 @@ import * as schema from '../db/schema';
  */
 export async function setupTestDatabase(): Promise<DbClient> {
   const sqlite = new Database(':memory:');
+  // Matches `createDbClient` (db/client.ts). SQLite defaults this OFF per
+  // connection, so without it every `onDelete: 'cascade'` in the schema is
+  // enforced in production and inert in the suite (celilo#1074).
+  sqlite.run('PRAGMA foreign_keys = ON');
   const db = drizzle(sqlite, { schema });
   const migrationsFolder = findMigrationsFolder();
   await migrate(db, { migrationsFolder });
@@ -60,6 +64,8 @@ export async function setupTestDatabaseFile(): Promise<{
   const tempDir = await mkdtemp(join(tmpdir(), 'celilo-test-'));
   const dbPath = join(tempDir, 'test.db');
   const sqlite = new Database(dbPath);
+  // See setupTestDatabase — celilo#1074.
+  sqlite.run('PRAGMA foreign_keys = ON');
   const db = drizzle(sqlite, { schema });
   const migrationsFolder = findMigrationsFolder();
   await migrate(db, { migrationsFolder });
@@ -72,6 +78,30 @@ export async function setupTestDatabaseFile(): Promise<{
   return { db, path: dbPath, cleanup };
 }
 
+/**
+ * Create a test database at a path the CALLER chooses.
+ *
+ * The other two helpers pick the location — memory, or a temp directory they
+ * own. This one exists for tests that must hand the same path to something
+ * else, typically a spawned CLI through `CELILO_DB_PATH`.
+ *
+ * It was a second module, `test-utils/setup-test-db.ts`, exporting a function
+ * ALSO called `setupTestDatabase` and another also called
+ * `cleanupTestDatabase`, with different arities and — until celilo#1074 —
+ * opposite foreign-key semantics. Which contract a test was under depended
+ * entirely on which file its import line named, and nothing at the call site
+ * showed it. One caller had already aliased the import to `migrateDbFile` to
+ * make it readable. The two colliding names are gone rather than renamed: there
+ * is no longer a wrong one to pick.
+ *
+ * @param testDbPath - Where to create the database file
+ */
+export async function setupTestDatabaseAt(testDbPath: string): Promise<DbClient> {
+  const db = createDbClient({ path: testDbPath });
+  await migrate(db, { migrationsFolder: findMigrationsFolder() });
+  return db;
+}
+
 /**
  * Clean up test database
  *

package/src/variables/context.ts

@@ -593,16 +593,81 @@ async function assembleResolutionContext(
         }
       }
     }
-    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(' ');
+    type ResolverEndpoint = {
+      server?: { ip?: unknown; internal_ip?: unknown };
+      /** Zones the provider's base-module aspect owns ongoing DNS for (D5d). */
+      aspect?: { covered_zones?: unknown };
+    };
+    const dnsInternal = capabilitiesMap.dns_internal as ResolverEndpoint | undefined;
+    const dnsSecondary = capabilitiesMap.dns_internal_secondary as ResolverEndpoint | undefined;
+
+    // A nameserver must be a bare IP. The advertised address may carry a CIDR
+    // suffix (technitium's server.ip resolves from target_ip, e.g.
+    // "192.168.0.151/24"), so strip it.
+    const bareIp = (value: unknown): string | undefined =>
+      typeof value === 'string' && value.length > 0 ? value.split('/')[0] : undefined;
+
+    const targetZone = module?.manifestData
+      ? getSingularSystemSpec(module.manifestData as ModuleManifest)?.zone
+      : undefined;
+
+    // `internal` cannot route into the resolvers' own (dmz) subnet, so it uses
+    // the ingress addresses the firewall DNATs. Every other zone reaches them
+    // directly.
+    const endpointFor = (resolver: ResolverEndpoint | undefined): string | undefined =>
+      targetZone === 'internal'
+        ? (bareIp(resolver?.server?.internal_ip) ?? bareIp(resolver?.server?.ip))
+        : bareIp(resolver?.server?.ip);
+
+    const primaryIp = endpointFor(dnsInternal);
+    const secondaryIp = endpointFor(dnsSecondary);
+
+    // Whether the DEPLOYED provider's base-module aspect covers this system's
+    // zone, which is what decides if the public entries may go (design D5d).
+    //
+    // The predicate is aspect COVERAGE, not routing. Routing is why a zone goes
+    // uncovered — `external` and the planned `quarantine` hold systems that
+    // cannot reach a resolver inside the perimeter. Coverage is why the birth
+    // list is PERMANENT: terraform injects
+    // `lifecycle { ignore_changes = [nameserver] }`, so it cannot correct the
+    // value afterwards even in principle, and a zone no aspect covers has no
+    // owner for ongoing DNS at all. Keying on coverage therefore handles a
+    // future excluded zone with no change here, and fails safe on an accidental
+    // omission — where keeping the public entries is the lesser harm until the
+    // array is fixed.
+    // The provider DECLARES its coverage in the capability data. Core could
+    // instead find the provider's module row and read
+    // `base_module_aspect.applicable_zones` off its manifest, which would be
+    // one source of truth rather than two — but that means core naming a
+    // capability in order to find its provider, which is the pattern the
+    // module-business gate exists to stop, and its advice is exactly this: let
+    // the provider declare the behaviour. A manifest test holds the declared
+    // list and the aspect's own `applicable_zones` together so they cannot
+    // drift.
+    const aspectZones = dnsInternal?.aspect?.covered_zones;
+    const zoneIsAspectCovered =
+      targetZone !== undefined && Array.isArray(aspectZones) && aspectZones.includes(targetZone);
+
+    // Both halves are required. A pair with no aspect covering this zone is the
+    // `external` case: two addresses it cannot route to and nothing else, which
+    // does not tighten anything, it takes DNS away. A primary with no secondary
+    // is D5a: removing the fallback and shipping a secondary are ONE decision,
+    // because otherwise every resolver redeploy blanks fleet DNS.
+    const dropPublicResolvers =
+      primaryIp !== undefined && secondaryIp !== undefined && zoneIsAspectCovered;
+
+    // The uncovered branch is main's composition unchanged: the primary, then
+    // the public resolvers. The secondary is deliberately NOT added to it — in
+    // a zone that cannot route to the resolvers, a second unreachable address
+    // buys nothing but another timeout before the public entries answer.
+    const nameservers = dropPublicResolvers
+      ? [primaryIp, secondaryIp]
+      : primaryIp
+        ? [primaryIp, ...publicDns]
+        : publicDns;
+    const unique = [...new Set(nameservers)];
+    if (unique.length > 0) {
+      selfConfig.lxc_nameserver = unique.join(' ');
     }
   }