@celilo/cli 1.6.0 → 1.8.0

package/src/db/dns-internal-cascade-migration.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Migration gate for celilo#1010, over a database that already holds records.
+ *
+ * `0027` rebuilds `dns_internal_records` to drop the foreign key on
+ * `provider_module_id`. A rebuild is copy, drop, rename — the most destructive
+ * shape a migration takes — and it will run on celilo-mgr, which holds the live
+ * internal DNS ledger including the `zone_routable_ip` view overrides the
+ * resolver's split-horizon config is reconciled from.
+ *
+ * Every other test in the suite starts from an empty database and can only prove
+ * the forward invariant. This one builds a database at the schema BEFORE the
+ * change, puts real rows in it, and runs the real migrator over it — the same
+ * shape as `dns-registrations-migration.test.ts`, and for the same reason: the
+ * installed base is where the risk is, and a clean-start suite cannot see it.
+ *
+ * Task 2.6 asks for backup and restore proven before this runs on celilo-mgr.
+ * This is the stronger half of that: it proves the migration PRESERVES the rows,
+ * so a restore is the fallback rather than the plan.
+ */
+
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+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 { findMigrationsFolder } from './client';
+
+/** The last migration before this change — the schema celilo-mgr is on today. */
+const LAST_LEGACY_TAG = '0026_module_integrity_version';
+
+interface JournalEntry {
+  idx: number;
+  version: string;
+  when: number;
+  tag: string;
+  breakpoints: boolean;
+}
+
+/** A migrations folder truncated at `LAST_LEGACY_TAG`, built from the real files. */
+function legacyMigrationsFolder(into: string): string {
+  const source = findMigrationsFolder();
+  const journal = JSON.parse(readFileSync(join(source, 'meta', '_journal.json'), 'utf8')) as {
+    version: string;
+    dialect: string;
+    entries: JournalEntry[];
+  };
+  const cutoff = journal.entries.findIndex((e) => e.tag === LAST_LEGACY_TAG);
+  if (cutoff === -1) throw new Error(`Journal has no entry for ${LAST_LEGACY_TAG}`);
+  const kept = journal.entries.slice(0, cutoff + 1);
+
+  mkdirSync(join(into, 'meta'), { recursive: true });
+  for (const entry of kept) {
+    cpSync(join(source, `${entry.tag}.sql`), join(into, `${entry.tag}.sql`));
+  }
+  writeFileSync(
+    join(into, 'meta', '_journal.json'),
+    JSON.stringify({ ...journal, entries: kept }, null, 2),
+  );
+  return into;
+}
+
+describe('0027 over a database that already holds an internal DNS ledger', () => {
+  let tempDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-dnsint-'));
+    dbPath = join(tempDir, 'legacy.db');
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function openLegacyDatabase(): Database {
+    const sqlite = new Database(dbPath, { create: true });
+    sqlite.run('PRAGMA foreign_keys = ON');
+    migrate(drizzle(sqlite), {
+      migrationsFolder: legacyMigrationsFolder(join(tempDir, 'legacy-migrations')),
+    });
+    return sqlite;
+  }
+
+  function seedModule(sqlite: Database, id: string): void {
+    sqlite.run(
+      'INSERT INTO modules (id, name, source_path, version, manifest_data) VALUES (?, ?, ?, ?, ?)',
+      [id, id, `/srv/${id}`, '1.0.0', JSON.stringify({ id })],
+    );
+  }
+
+  function seedLedger(sqlite: Database): void {
+    seedModule(sqlite, 'technitium');
+    seedModule(sqlite, 'knot-unbound-internal');
+    seedModule(sqlite, 'caddy');
+    seedModule(sqlite, 'forgejo');
+    sqlite.run(
+      'INSERT INTO dns_internal_records (provider_module_id, consumer_module_id, host, ip, zone_routable_ip) VALUES (?, ?, ?, ?, ?)',
+      ['technitium', 'caddy', 'auth.example.org', '192.168.0.253', '10.0.10.14'],
+    );
+    sqlite.run(
+      'INSERT INTO dns_internal_records (provider_module_id, consumer_module_id, host, ip, zone_routable_ip) VALUES (?, ?, ?, ?, NULL)',
+      ['technitium', 'forgejo', 'git.example.org', '192.168.0.253'],
+    );
+  }
+
+  function runCurrentMigrations(sqlite: Database): void {
+    migrate(drizzle(sqlite), { migrationsFolder: findMigrationsFolder() });
+  }
+
+  test('the rebuild carries every row across, values intact', () => {
+    const sqlite = openLegacyDatabase();
+    seedLedger(sqlite);
+
+    runCurrentMigrations(sqlite);
+
+    const rows = sqlite
+      .query<
+        { host: string; ip: string; zone_routable_ip: string | null; provider_module_id: string },
+        []
+      >(
+        'SELECT host, ip, zone_routable_ip, provider_module_id FROM dns_internal_records ORDER BY host',
+      )
+      .all();
+    expect(rows).toHaveLength(2);
+    expect(rows[0]?.host).toBe('auth.example.org');
+    // The override is the value whose loss is silent: the resolver keeps
+    // answering, just with an address in-zone clients cannot route to.
+    expect(rows[0]?.zone_routable_ip).toBe('10.0.10.14');
+    expect(rows[1]?.zone_routable_ip).toBeNull();
+    // Attribution survives; only its ON DELETE action changed.
+    expect(rows[0]?.provider_module_id).toBe('technitium');
+    sqlite.close();
+  });
+
+  test('after migrating, removing the PROVIDER no longer empties the ledger', () => {
+    const sqlite = openLegacyDatabase();
+    seedLedger(sqlite);
+    runCurrentMigrations(sqlite);
+
+    sqlite.run('DELETE FROM modules WHERE id = ?', ['technitium']);
+
+    expect(
+      sqlite.query<{ c: number }, []>('SELECT COUNT(*) AS c FROM dns_internal_records').get()?.c,
+    ).toBe(2);
+    sqlite.close();
+  });
+
+  /**
+   * The behaviour that did NOT change. Dropping a foreign key is an easy way to
+   * lose the one you meant to keep, and nothing else would notice.
+   */
+  test('the consumer cascade still fires after the rebuild', () => {
+    const sqlite = openLegacyDatabase();
+    seedLedger(sqlite);
+    runCurrentMigrations(sqlite);
+
+    sqlite.run('DELETE FROM modules WHERE id = ?', ['caddy']);
+
+    const left = sqlite
+      .query<{ consumer_module_id: string }, []>(
+        'SELECT consumer_module_id FROM dns_internal_records',
+      )
+      .all();
+    expect(left.map((r) => r.consumer_module_id)).toEqual(['forgejo']);
+    sqlite.close();
+  });
+
+  /** The unique index is recreated by the rebuild, not left behind with the old table. */
+  test('the provider+host uniqueness survives the rebuild', () => {
+    const sqlite = openLegacyDatabase();
+    seedLedger(sqlite);
+    runCurrentMigrations(sqlite);
+
+    expect(() =>
+      sqlite.run(
+        'INSERT INTO dns_internal_records (provider_module_id, consumer_module_id, host, ip) VALUES (?, ?, ?, ?)',
+        ['technitium', 'forgejo', 'auth.example.org', '192.168.0.253'],
+      ),
+    ).toThrow();
+    sqlite.close();
+  });
+});

package/src/db/migrate.test.ts

@@ -0,0 +1,147 @@
+/**
+ * The frozen-watermark recurrence gate (celilo#169).
+ *
+ * The state under test is one no correct deploy can produce, so it is seeded
+ * by hand rather than reached: a database written by a celilo from the
+ * imperative hand-list era, where schema changes were applied directly and
+ * `__drizzle_migrations` never recorded them. Its ledger therefore remembers
+ * an old migration while the tables and columns of every later one are already
+ * present.
+ *
+ * That is the carve-out CLAUDE.md draws around seeding state: deploying
+ * anything cannot reproduce this row, because current celilo has recorded
+ * every migration it applied since ISS-0100 made drizzle authoritative. A
+ * suite that starts from an empty database can only ever prove the forward
+ * invariant, and says nothing about the installed base.
+ *
+ * What made it a hazard: drizzle's migrator is watermark-only. It re-runs
+ * every migration newer than the newest ledger row, so the first `ALTER TABLE
+ * ... ADD` dies on `duplicate column name`, the transaction rolls back, and
+ * the throw happens inside `createDbClient` — so EVERY celilo command on that
+ * box fails at database open, not just a migrate. celilo-mgr was remediated by
+ * hand once. This gate is what stops the next one needing a runbook.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type DbClient, createDbClient } from './client';
+import { runMigrationsOn } from './migrate';
+import { findSchemaDrift } from './schema-introspection';
+
+describe('runMigrationsOn — a database from the hand-list era', () => {
+  const paths: string[] = [];
+
+  const freshDb = (): { db: DbClient; path: string } => {
+    const path = join(tmpdir(), `celilo-migrate-test-${Bun.nanoseconds()}.db`);
+    paths.push(path);
+    return { db: createDbClient({ path }), path };
+  };
+
+  afterEach(() => {
+    for (const path of paths.splice(0)) {
+      for (const suffix of ['', '-wal', '-shm']) {
+        rmSync(`${path}${suffix}`, { force: true });
+      }
+    }
+  });
+
+  /**
+   * Freeze the ledger to its oldest entry, leaving the schema fully applied.
+   * This is the hand-list-era shape: the objects exist, the ledger has
+   * forgotten who made them.
+   */
+  const freezeWatermark = (db: DbClient): void => {
+    db.$client.run(
+      'DELETE FROM `__drizzle_migrations` WHERE created_at > (SELECT MIN(created_at) FROM `__drizzle_migrations`)',
+    );
+  };
+
+  const appliedCount = (db: DbClient): number =>
+    db.$client.query<{ c: number }, []>('SELECT COUNT(*) AS c FROM `__drizzle_migrations`').get()
+      ?.c ?? 0;
+
+  test('converges instead of dying on the first already-applied statement', () => {
+    const { db } = freshDb();
+    const migrationCount = appliedCount(db);
+    freezeWatermark(db);
+    expect(appliedCount(db)).toBe(1);
+
+    // Red before the ledger repair: drizzle re-runs 0001 and throws
+    // "duplicate column name: role", leaving the ledger frozen.
+    expect(() => runMigrationsOn(db)).not.toThrow();
+
+    expect(appliedCount(db)).toBe(migrationCount);
+  });
+
+  test('leaves the schema whole, so the drift detector goes green', () => {
+    const { db } = freshDb();
+    freezeWatermark(db);
+
+    runMigrationsOn(db);
+
+    const drift = findSchemaDrift(db.$client);
+    expect(drift.missingTables).toEqual([]);
+    expect(drift.missingColumns).toEqual([]);
+  });
+
+  test('is idempotent — a second pass applies nothing and still converges', () => {
+    const { db } = freshDb();
+    freezeWatermark(db);
+    runMigrationsOn(db);
+    const afterBaseline = appliedCount(db);
+
+    runMigrationsOn(db);
+
+    expect(appliedCount(db)).toBe(afterBaseline);
+  });
+
+  /**
+   * The repair must not become a blanket "assume it already ran". It fires only
+   * where the answer is unambiguous — the declared schema is entirely present,
+   * so every migration plainly did run and the ledger is what is wrong. A
+   * PARTIALLY applied schema is the genuinely hard case, and the one celilo-mgr
+   * was actually in: it carried 0011's column and not 0010's table. Stamping
+   * there would record migrations that never ran and bury the missing schema
+   * for good, so it keeps failing and a human decides.
+   */
+  test('refuses to stamp when the schema is only partly there', () => {
+    const { db } = freshDb();
+    freezeWatermark(db);
+    db.$client.run('DROP TABLE `dns_registrations`');
+
+    expect(() => runMigrationsOn(db)).toThrow();
+    // The ledger is left exactly as found, so the drift is still diagnosable.
+    expect(appliedCount(db)).toBe(1);
+  });
+
+  /**
+   * The path that actually matters. Every celilo command opens the database
+   * through createDbClient, which migrates on open, so a frozen watermark
+   * failed there rather than anywhere an operator could aim a fix at — and
+   * `celilo system migrate`, the command whose whole job is repairing this,
+   * reached its own repair through the same open and died first.
+   */
+  test('repairs on database open, not just when migrate is called by hand', () => {
+    const { db, path } = freshDb();
+    const migrationCount = appliedCount(db);
+    freezeWatermark(db);
+    db.$client.close();
+
+    const reopened = createDbClient({ path });
+
+    expect(appliedCount(reopened)).toBe(migrationCount);
+    expect(findSchemaDrift(reopened.$client).missingTables).toEqual([]);
+  });
+
+  test('a healthy database is untouched by the fallback', () => {
+    const { db } = freshDb();
+    const before = appliedCount(db);
+
+    runMigrationsOn(db);
+
+    expect(appliedCount(db)).toBe(before);
+    expect(findSchemaDrift(db.$client).missingTables).toEqual([]);
+  });
+});

package/src/db/migrate.ts

@@ -1,14 +1,82 @@
+import type { Database } from 'bun:sqlite';
 import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
+import { readMigrationFiles } from 'drizzle-orm/migrator';
 import { type DbClient, closeDb, createDbClient, findMigrationsFolder } from './client';
+import { findSchemaDrift } from './schema-introspection';
+
+/**
+ * Record every migration past the ledger's watermark as applied, running none
+ * of them. Only safe when the caller has already established that the schema
+ * the code declares is entirely present.
+ *
+ * Replaying the statements instead would be wrong, and quietly so. Migrations
+ * are not idempotent: `0021_dns_registration_consumers` rebuilds a table by
+ * copying it aside, `DROP TABLE`-ing the original and renaming the copy over
+ * it. Run that against a schema that is already current and it drops a live
+ * table. Skipping the statements that fail with "already exists" does not save
+ * you either, because `DROP` and `INSERT ... SELECT` do not fail that way.
+ *
+ * So the ledger is corrected and the schema is left alone.
+ */
+function stampLedgerAsApplied(sqlite: Database, migrationsFolder: string): void {
+  const newest = sqlite
+    .query<{ created_at: number }, []>(
+      'SELECT created_at FROM `__drizzle_migrations` ORDER BY created_at DESC LIMIT 1',
+    )
+    .get();
+  const watermark = Number(newest?.created_at ?? 0);
+
+  sqlite.run('BEGIN');
+  try {
+    for (const migration of readMigrationFiles({ migrationsFolder })) {
+      if (migration.folderMillis <= watermark) continue;
+      sqlite.run('INSERT INTO `__drizzle_migrations` ("hash", "created_at") VALUES (?, ?)', [
+        migration.hash,
+        migration.folderMillis,
+      ]);
+    }
+    sqlite.run('COMMIT');
+  } catch (error) {
+    sqlite.run('ROLLBACK');
+    throw error;
+  }
+}
 
 /**
  * Apply pending drizzle migrations to an open DB. Idempotent — drizzle applies
  * only migrations newer than the latest recorded in `__drizzle_migrations`.
  * The single migration mechanism (ISS-0100); createDbClient also calls this
  * shape on open (auto-migrate).
+ *
+ * The stock migrator runs first and handles every database celilo has written
+ * since ISS-0100, so a healthy box takes exactly the path it took before.
+ *
+ * It fails on one database celilo did not write: one from the imperative
+ * hand-list era, where schema changes were applied directly and
+ * `__drizzle_migrations` never recorded them. Its ledger remembers an old
+ * migration while the objects of every later one are already there, and
+ * drizzle — being watermark-only — re-runs them and dies on the first
+ * `ALTER TABLE ... ADD`. The throw happens inside `createDbClient`, so every
+ * celilo command on that box fails at database open. celilo-mgr, the one box
+ * in that state, was remediated by hand (celilo#169); this is so the next one
+ * is not.
+ *
+ * The repair is only attempted when the schema the code declares is ALREADY
+ * COMPLETE, because that is the one case with an unambiguous answer: every
+ * migration has plainly run, so the ledger is what is wrong. A database missing
+ * some of it is the genuinely hard case — celilo-mgr had 0011's column and not
+ * 0010's table — and there is no safe automatic answer, so it keeps failing
+ * with drizzle's own error and a human decides.
  */
 export function runMigrationsOn(db: DbClient): void {
-  migrate(db, { migrationsFolder: findMigrationsFolder() });
+  const migrationsFolder = findMigrationsFolder();
+  try {
+    migrate(db, { migrationsFolder });
+  } catch (error) {
+    const drift = findSchemaDrift(db.$client);
+    if (drift.missingTables.length > 0 || drift.missingColumns.length > 0) throw error;
+    stampLedgerAsApplied(db.$client, migrationsFolder);
+  }
 }
 
 /**

package/src/db/schema.ts

@@ -801,16 +801,33 @@ export const publicDnsEvidence = sqliteTable('public_dns_evidence', {
  *
  * `celilo system doctor` reads this to assert service hostnames resolve to
  * the firewall natIp (LAN-reachable) and not a zone-side container IP that
- * a LAN device can't route to. Rows die with either module via FK cascade.
+ * a LAN device can't route to. Rows die with their CONSUMER via FK cascade, and
+ * NOT with their provider (celilo#1010 — see `providerModuleId`).
  * @owner capability:dns_internal — resolver configuration; migrates to the provider (T6)
  */
 export const dnsInternalRecords = sqliteTable(
   'dns_internal_records',
   {
     id: integer('id').primaryKey({ autoIncrement: true }),
-    providerModuleId: text('provider_module_id')
-      .notNull()
-      .references(() => modules.id, { onDelete: 'cascade' }),
+    /**
+     * The resolver serving this record. A PLAIN column with no foreign key, and
+     * that is the celilo#1010 correction rather than an oversight.
+     *
+     * It used to cascade, so swapping `technitium` for `knot-unbound-internal`
+     * deleted the fleet's entire internal DNS ledger, `zone_routable_ip` view
+     * overrides included. `web_routes` cascades on its consumer only and the two
+     * docblocks claimed to be siblings, so the divergence read as intent and was
+     * not. The claim on a capability-owned table is the CONSUMER
+     * (openspec/changes/capability-owned-tables D3/D8), and `dns_internal`'s
+     * declaration cannot express anything else.
+     *
+     * Attribution is still real and still enforced — it is half
+     * `dns_internal_records_provider_host_idx` — it just no longer decides when a
+     * LIVE record is forgotten. A provider leaving now leaves the ledger for the
+     * next one to reconcile from, which is what stage 1's provider-arrival
+     * backfill assumes. Migration `0027`.
+     */
+    providerModuleId: text('provider_module_id').notNull(),
     consumerModuleId: text('consumer_module_id')
       .notNull()
       .references(() => modules.id, { onDelete: 'cascade' }),

package/src/hooks/capability-loader.test.ts

@@ -29,6 +29,17 @@ export default function registerHost(context) {
 }
 `;
 
+const TEST_DHCP_SERVER_MODULE = `
+export default function createDhcpServer(context) {
+  return {
+    async setDnsServers() {},
+    async getDnsServers() { return [context.config.marker]; },
+    async setDomainName() {},
+    async getDomainName() { return context.config.marker; },
+  };
+}
+`;
+
 describe('Capability Loader', () => {
   let db: DbClient;
   let tempDir: string;
@@ -97,6 +108,50 @@ describe('Capability Loader', () => {
     expect(result.dns_registrar).toBeTruthy();
   });
 
+  test('prefers a provider explicitly scoped to the well-known capability zone', async () => {
+    for (const moduleId of ['upstream-dhcp', 'internal-dhcp']) {
+      const modulePath = join(tempDir, moduleId);
+      const scriptsDir = join(modulePath, 'scripts');
+      mkdirSync(scriptsDir, { recursive: true });
+      writeFileSync(join(scriptsDir, 'dhcp-server-functions.ts'), TEST_DHCP_SERVER_MODULE);
+      db.$client.run(
+        `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('${moduleId}', '${moduleId}', '1.0.0', '${modulePath}', '{}')`,
+      );
+      upsertModuleConfig(db, moduleId, 'marker', moduleId);
+    }
+
+    // Insert the zone-agnostic upstream provider first to prove selection is
+    // policy-driven rather than database-order-driven.
+    db.$client.run(
+      `INSERT INTO capabilities (module_id, capability_name, version, data, zones, registered_at) VALUES ('upstream-dhcp', 'dhcp_server', '1.0.0', '{}', NULL, unixepoch())`,
+    );
+    db.$client.run(
+      `INSERT INTO capabilities (module_id, capability_name, version, data, zones, registered_at) VALUES ('internal-dhcp', 'dhcp_server', '1.0.0', '{}', '["internal"]', unixepoch())`,
+    );
+
+    const result = await loadCapabilityFunctions('dns-consumer', db, noopLogger);
+    const dhcp = result.dhcp_server as { getDomainName(): Promise<string> };
+    expect(await dhcp.getDomainName()).toBe('internal-dhcp');
+  });
+
+  test('falls back to a zone-agnostic provider when no explicit zone provider exists', async () => {
+    const modulePath = join(tempDir, 'upstream-dhcp');
+    const scriptsDir = join(modulePath, 'scripts');
+    mkdirSync(scriptsDir, { recursive: true });
+    writeFileSync(join(scriptsDir, 'dhcp-server-functions.ts'), TEST_DHCP_SERVER_MODULE);
+    db.$client.run(
+      `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('upstream-dhcp', 'upstream-dhcp', '1.0.0', '${modulePath}', '{}')`,
+    );
+    db.$client.run(
+      `INSERT INTO capabilities (module_id, capability_name, version, data, zones, registered_at) VALUES ('upstream-dhcp', 'dhcp_server', '1.0.0', '{}', NULL, unixepoch())`,
+    );
+    upsertModuleConfig(db, 'upstream-dhcp', 'marker', 'upstream-dhcp');
+
+    const result = await loadCapabilityFunctions('dns-consumer', db, noopLogger);
+    const dhcp = result.dhcp_server as { getDomainName(): Promise<string> };
+    expect(await dhcp.getDomainName()).toBe('upstream-dhcp');
+  });
+
   test('injects a read-only web_routes view into the public_web provider own hooks (ISS-0035)', async () => {
     const modulePath = join(tempDir, 'caddy');
     mkdirSync(modulePath, { recursive: true });

package/src/hooks/capability-loader.ts

@@ -27,6 +27,8 @@ import type {
   TrustedSourceStore,
 } from '@celilo/capabilities';
 import { and, eq } from 'drizzle-orm';
+import { selectCapabilityProvider } from '../capabilities/lookup';
+import { WELL_KNOWN_CAPABILITIES } from '../capabilities/well-known';
 import type { DbClient } from '../db/client';
 import {
   NETWORK_ZONES,
@@ -279,7 +281,20 @@ export async function loadCapabilityFunctions(
       continue;
     }
 
-    const capability = allProviders[0];
+    // A well-known capability's required zone is also its runtime selection
+    // context. Prefer a provider that explicitly serves that zone, then fall
+    // back to a zone-agnostic provider. Without this, multiple DHCP providers
+    // (for example an upstream router plus an internal LAN server) are selected
+    // by database insertion order and a consumer can reconfigure the wrong
+    // network boundary.
+    const selectionZone = WELL_KNOWN_CAPABILITIES[capName]?.required_zone;
+    const capability = selectCapabilityProvider(allProviders, selectionZone);
+    if (!capability) {
+      debugLog(
+        `${capName}: no provider serves required zone ${selectionZone ?? '(unspecified)'}, skipping`,
+      );
+      continue;
+    }
     debugLog(`${capName}: found provider module ${capability.moduleId}`);
 
     const providerModule = db

package/src/manifest/template-validator.test.ts

@@ -258,4 +258,51 @@ resource "local_file" "test" {
       expect(errors[0]?.variable).toBe('$self:invalid_var');
     });
   });
+
+  /**
+   * The capability-secret gate at import consumes these, so what happens when
+   * templates cannot be read is a security property rather than a detail. It
+   * has to FAIL CLOSED: an unreadable tree must abort the import, never hand
+   * the gate an empty reference set that reads as "this module references no
+   * secrets". It was already true here — but true by inspection, which is the
+   * weakest way for a security property to be true.
+   */
+  describe('capability references, and failing closed', () => {
+    test('collects $capability: references from templates', async () => {
+      const dir = await mkdtemp(join(tmpdir(), 'celilo-tplrefs-'));
+      try {
+        await mkdir(join(dir, 'terraform'), { recursive: true });
+        await writeFile(
+          join(dir, 'terraform', 'main.tf.tpl'),
+          'acme_dns = "$capability:dns_internal.tsig_key"\nzone = "$capability:dns_internal.dns.domain"\n',
+        );
+        const manifest = createTestManifest({
+          requires: { capabilities: [{ name: 'dns_internal', version: '1.0.0' }] },
+        });
+
+        const result = await validateModuleTemplates(dir, manifest);
+
+        expect(result.capabilityReferences.sort()).toEqual([
+          'dns_internal.dns.domain',
+          'dns_internal.tsig_key',
+        ]);
+      } finally {
+        await rm(dir, { recursive: true, force: true });
+      }
+    });
+
+    test('an unreadable module tree fails, and yields no references', async () => {
+      // A path that does not exist stands in for any read failure. The PAIRING
+      // is the property: success:false travels WITH the empty array, and
+      // `import.ts` returns on !success before the access gate runs, so the
+      // empty set can never be mistaken for "nothing referenced".
+      const result = await validateModuleTemplates(
+        join(tmpdir(), 'celilo-no-such-module-tree-9f3a2b'),
+        createTestManifest(),
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.capabilityReferences).toEqual([]);
+    });
+  });
 });

package/src/manifest/template-validator.ts

@@ -19,6 +19,12 @@ export interface TemplateValidationError {
 export interface TemplateValidationResult {
   success: boolean;
   errors: TemplateValidationError[];
+  /**
+   * `<capability>.<path>` paths the templates reference. The capability-access
+   * check at import consumes these, so a secret referenced only from a template
+   * is refused at import rather than later at generation.
+   */
+  capabilityReferences: string[];
 }
 
 /**
@@ -277,10 +283,16 @@ export async function validateModuleTemplates(
     // Find all .tpl files
     const templateFiles = await findTemplateFiles(modulePath, modulePath);
 
-    // Validate each template file
+    // Validate each template file. Every one is parsed here anyway, so the
+    // capability references fall out of work already being done — no second
+    // walk of the module tree.
+    const capabilityReferences = new Set<string>();
     for (const relativePath of templateFiles) {
       const fullPath = join(modulePath, relativePath);
       const content = await readFile(fullPath, 'utf-8');
+      for (const variable of parseVariables(content)) {
+        if (variable.type === 'capability') capabilityReferences.add(variable.path);
+      }
       const errors = validateTemplateContent(content, manifest, relativePath);
       allErrors.push(...errors);
     }
@@ -288,6 +300,7 @@ export async function validateModuleTemplates(
     return {
       success: allErrors.length === 0,
       errors: allErrors,
+      capabilityReferences: [...capabilityReferences],
     };
   } catch (error) {
     return {
@@ -299,6 +312,10 @@ export async function validateModuleTemplates(
           error: `Failed to validate templates: ${error instanceof Error ? error.message : 'Unknown error'}`,
         },
       ],
+      // Unreadable templates cannot yield references, and import returns on
+      // !success before the access check runs, so this can never reach it as a
+      // silent pass.
+      capabilityReferences: [],
     };
   }
 }