@celilo/cli 1.13.0 → 2.0.0

package/src/services/module-deploy.ts

@@ -46,6 +46,7 @@ import {
   runProviderBackfill,
 } from './provider-arrival';
 import { checkProxmoxReachable, formatProxmoxUnreachableError } from './proxmox-preflight';
+import { remoteAccessPolicy } from './remote-access';
 import { LOCAL_MACHINE_IP, deleteTemporarySshKey, writeTemporarySshKey } from './ssh-key-manager';
 import { buildTerraformEnvForService } from './terraform-env';
 
@@ -720,6 +721,7 @@ async function deployModuleImpl(
             capabilities: capabilityFunctions,
             requiredCapabilities: manifest.requires.capabilities.map((c) => c.name),
             systems: getModuleSystems(moduleId, db),
+            remoteAccess: remoteAccessPolicy(moduleId, db),
           },
         );
 
@@ -858,6 +860,7 @@ async function deployModuleImpl(
                 capabilities: capFns,
                 requiredCapabilities: (manifest.requires?.capabilities ?? []).map((c) => c.name),
                 systems: getModuleSystems(moduleId, db),
+                remoteAccess: remoteAccessPolicy(moduleId, db),
               },
             };
           },
@@ -1159,6 +1162,7 @@ async function deployModuleImpl(
             capabilities: capFunctions,
             requiredCapabilities: providerManifest.requires.capabilities.map((c) => c.name),
             systems: getModuleSystems(capRecord.moduleId, db),
+            remoteAccess: remoteAccessPolicy(capRecord.moduleId, db),
           },
         );
 
@@ -1308,6 +1312,21 @@ async function deployModuleImpl(
       }
     }
 
+    // The provider's own deploy runs the static-content converge alongside
+    // everything else (design D10, task 4.5): the release set is written into
+    // the generated inventory, the playbook's static_content-tagged tasks
+    // converge /srv/www, and a rebuilt host recovers with no consumer
+    // involvement. Same plan + writer the publish-time converge uses — one
+    // code path, two callers.
+    if (manifest.provides?.capabilities?.some((cap) => cap.name === 'public_web')) {
+      const { writeStaticContentVars } = await import('./static-content-converge');
+      const staticVars = await writeStaticContentVars(db, moduleId, generatedPath);
+      if (!staticVars.success) {
+        return { success: false, error: staticVars.error, phases };
+      }
+      log.success('Static-content release set written to the inventory');
+    }
+
     try {
       const ansibleResult = await executeAnsible(generatedPath, {
         noInteractive: !process.stdout.isTTY,
@@ -1412,6 +1431,7 @@ async function deployModuleImpl(
                 capabilities: capFns,
                 requiredCapabilities: manifest.requires.capabilities.map((c) => c.name),
                 systems: getModuleSystems(moduleId, db),
+                remoteAccess: remoteAccessPolicy(moduleId, db),
               },
             };
           },

package/src/services/remote-access.test.ts

@@ -0,0 +1,139 @@
+/**
+ * D12's reachability policy (hook-process-boundary stage 3, tasks 5.1b/5.2).
+ *
+ * The rules under test, in the order they short-circuit:
+ *   1. a request on the module's OWN credential is allowed — the credential is
+ *      the scope;
+ *   2. an explicit non-root user is allowed — the fleet key's authority is
+ *      root on fleet systems, and a non-root account trusts it only where an
+ *      operator installed it (the cPanel bootstrap);
+ *   3. otherwise the target must be a system the module or one of its
+ *      instances provisioned, and a refusal names the module, the target, and
+ *      the capability route.
+ */
+
+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, moduleInstances, moduleSystems, modules } from '../db/schema';
+import { remoteAccessPolicy } from './remote-access';
+
+const TEST_DB_PATH = './test-remote-access.db';
+
+function seedModule(db: DbClient, id: string): void {
+  db.insert(modules)
+    .values({
+      id,
+      name: id,
+      version: '1.0.0',
+      manifestData: {},
+      sourcePath: `/tmp/${id}`,
+      state: 'VERIFIED',
+    })
+    .run();
+}
+
+function seedSystem(db: DbClient, moduleId: string, ipv4Address: string, hostname: string): void {
+  db.insert(moduleSystems)
+    .values({
+      moduleId,
+      name: 'main',
+      hostname,
+      ipv4Address,
+      zone: 'dmz',
+      infraType: 'machine',
+      updatedAt: new Date(),
+    })
+    .run();
+}
+
+describe('remoteAccessPolicy', () => {
+  let db: DbClient;
+
+  beforeEach(() => {
+    db = createDbClient({ path: TEST_DB_PATH });
+    seedModule(db, 'caddy');
+    seedSystem(db, 'caddy', '10.0.10.10', 'www');
+    seedModule(db, 'homebridge');
+    seedSystem(db, 'homebridge', '10.0.30.7', 'homebridge');
+    db.insert(capabilities)
+      .values({ moduleId: 'caddy', capabilityName: 'public_web', version: '1.0.0', data: {} })
+      .run();
+  });
+
+  afterEach(async () => {
+    db.$client.close();
+    for (const suffix of ['', '-shm', '-wal']) {
+      const p = `${TEST_DB_PATH}${suffix}`;
+      if (existsSync(p)) await rm(p);
+    }
+  });
+
+  test("allows the module's own system", () => {
+    const policy = remoteAccessPolicy('caddy', db);
+    expect(policy.checkTarget({ ipv4_address: '10.0.10.10' }, false)).toEqual({ allowed: true });
+  });
+
+  test("allows an instance's system, one level deep", () => {
+    seedModule(db, 'forgejo-runner-abc123def456');
+    db.insert(moduleInstances)
+      .values({
+        moduleId: 'forgejo-runner-abc123def456',
+        parentId: 'homebridge',
+        submodule: 'runner',
+        instanceKey: 'lab',
+        state: 'ready',
+      })
+      .run();
+    seedSystem(db, 'forgejo-runner-abc123def456', '10.0.30.9', 'runner-lab');
+
+    const policy = remoteAccessPolicy('homebridge', db);
+    expect(policy.checkTarget({ ipv4_address: '10.0.30.9' }, false)).toEqual({ allowed: true });
+  });
+
+  test("refuses another module's system, naming module, target and the capability route", () => {
+    const verdict = remoteAccessPolicy('homebridge', db).checkTarget(
+      { ipv4_address: '10.0.10.10' },
+      false,
+    );
+    expect(verdict.allowed).toBe(false);
+    if (verdict.allowed) throw new Error('unreachable');
+    expect(verdict.message).toContain("Module 'homebridge'");
+    expect(verdict.message).toContain('10.0.10.10');
+    expect(verdict.message).toContain("belongs to module 'caddy'");
+    expect(verdict.message).toContain('public_web');
+  });
+
+  test('refuses an address no deployed system has, with the generic guidance', () => {
+    const verdict = remoteAccessPolicy('homebridge', db).checkTarget(
+      { ipv4_address: '203.0.113.50' },
+      false,
+    );
+    expect(verdict.allowed).toBe(false);
+    if (verdict.allowed) throw new Error('unreachable');
+    expect(verdict.message).toContain("Module 'homebridge'");
+    expect(verdict.message).toContain('203.0.113.50');
+    expect(verdict.message).toContain('capability');
+  });
+
+  test('allows any target when the request carries its own credential', () => {
+    const policy = remoteAccessPolicy('homebridge', db);
+    expect(policy.checkTarget({ ipv4_address: '10.0.10.10' }, true)).toEqual({ allowed: true });
+  });
+
+  test('allows an explicit non-root user (the off-fleet account case)', () => {
+    const policy = remoteAccessPolicy('generic-cpanel-hosting-provider', db);
+    expect(
+      policy.checkTarget({ ipv4_address: '198.51.100.7', user: 'peba-hosting' }, false),
+    ).toEqual({ allowed: true });
+  });
+
+  test("an explicit 'root' user gets no such pass", () => {
+    const verdict = remoteAccessPolicy('homebridge', db).checkTarget(
+      { ipv4_address: '10.0.10.10', user: 'root' },
+      false,
+    );
+    expect(verdict.allowed).toBe(false);
+  });
+});

package/src/services/remote-access.ts

@@ -0,0 +1,98 @@
+/**
+ * D12's reachability policy: which remote targets a module may reach with the
+ * FLEET credential (openspec/changes/hook-process-boundary, stage 3).
+ *
+ * The rule: a module may reach the systems it provisioned — its own and its
+ * instances' (`ownedSystemModuleIds`, one indexed query because ownership is
+ * one level deep) — and reaches everything else through capabilities. The
+ * mount set is derived from the hook context; the reachable set is derived
+ * from the same identity.
+ *
+ * Two carve-outs, both following from "scoped by the CREDENTIAL":
+ *
+ *   - A request carrying the module's OWN credential (an identity key, or
+ *     `installAuthorizedKey`'s password) is not riding the fleet key at all.
+ *     The credential is the scope: it works exactly where its holder was
+ *     given access, which celilo neither grants nor needs to police.
+ *   - An explicit NON-ROOT user. The fleet key's authority is root on the
+ *     systems celilo provisions — that is the only place celilo installs it.
+ *     A non-root account trusts it only where an operator deliberately put it
+ *     there (the cPanel bootstrap installs it into an unprivileged hosting
+ *     account), and refusing those would break every off-fleet provider while
+ *     protecting nothing the key actually unlocks. The residual — an operator
+ *     who installed the fleet key as root on an OFF-fleet box — is refused
+ *     until that target carries its own identity, and design D12 records it.
+ *
+ * **Attribution (D12, task 5.1b).** A policy is built for the module that
+ * PERFORMS the operation, never the one that asked for it. For a hook that is
+ * the hook's module — the nine `invokeHook` call sites construct it with the
+ * id they are invoking. A capability provider's internal transport belongs to
+ * the provider's module; providers run in celilo's own process today (design
+ * D10), so their transport does not cross the remote-ops broker, and the one
+ * hand-built-ssh provider site (`public_web`'s upload) is being replaced by
+ * an Ansible converge under `openspec/changes/capability-owned-tables`
+ * (celilo#1014). If provider transport is ever brokered, it takes a policy
+ * built with the PROVIDER's id from this same function — neither "the calling
+ * module's systems" nor an exemption.
+ *
+ * Policy function (Rule 10.1) — decides; the remote-ops broker enforces.
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { capabilities, moduleSystems } from '../db/schema';
+import type { RemoteAccessPolicy } from '../hooks/remote-broker';
+import { getModuleSystems } from './deployed-systems';
+import { ownedSystemModuleIds } from './module-instances';
+
+/** Build the policy one hook run's remote operations are checked against. */
+export function remoteAccessPolicy(moduleId: string, db: DbClient): RemoteAccessPolicy {
+  return {
+    moduleId,
+    checkTarget(target, hasOwnCredential) {
+      if (hasOwnCredential) return { allowed: true };
+      if (target.user !== undefined && target.user !== 'root') return { allowed: true };
+
+      // Queried per call rather than snapshotted at invoke time, so a system
+      // recorded mid-run (a provider arrival) is visible to the next check.
+      const owned = ownedSystemModuleIds(moduleId, db).flatMap((id) => getModuleSystems(id, db));
+      if (owned.some((system) => system.ipv4_address === target.ipv4_address)) {
+        return { allowed: true };
+      }
+
+      return { allowed: false, message: refusalMessage(moduleId, target.ipv4_address, db) };
+    },
+  };
+}
+
+/**
+ * Name the module, the target, and the capability route (task 5.2). The owner
+ * lookup is best-effort colour: the refusal stands whether or not celilo can
+ * say whose system it is.
+ */
+function refusalMessage(moduleId: string, ipv4Address: string, db: DbClient): string {
+  const preamble = `Module '${moduleId}' may not reach ${ipv4Address}: it is not a system this module (or one of its instances) provisioned.`;
+  const guidance =
+    'A hook reaches its own systems via ctx.systems and everything else through a capability (hook-process-boundary, design D12).';
+
+  const owner = db
+    .select()
+    .from(moduleSystems)
+    .where(eq(moduleSystems.ipv4Address, ipv4Address))
+    .get();
+  if (!owner) return `${preamble} ${guidance}`;
+
+  const provided = db
+    .select({ capabilityName: capabilities.capabilityName })
+    .from(capabilities)
+    .where(eq(capabilities.moduleId, owner.moduleId))
+    .all()
+    .map((row) => row.capabilityName);
+
+  const route =
+    provided.length > 0
+      ? `Reach it through a capability it provides ('${provided.join("', '")}').`
+      : "Reach it through a capability, never by SSH from another module's hook.";
+
+  return `${preamble} That system ('${owner.hostname}') belongs to module '${owner.moduleId}'. ${route}`;
+}

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

@@ -32,7 +32,7 @@ import {
   rmSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { getDbPath, getMasterKeyPath, getModuleStoragePath } from '../config/paths';
 import { closeDb, getDb } from '../db/client';
@@ -47,12 +47,14 @@ import { decryptFileToFile } from './backup-cipher';
 import { assertCompatibleSchema, parseManifest } from './backup-manifest';
 import { applyCrossModuleWriteRoot, moduleHasCrossModuleRead } from './cross-module-read';
 import { getModuleSystems } from './deployed-systems';
+import { getFleetSshDir } from './fleet-key';
 import {
   completeOperation,
   failOperation,
   refuseIfInFlight,
   startOperation,
 } from './module-operations';
+import { remoteAccessPolicy } from './remote-access';
 
 export interface RestoreFromFileResult {
   success: boolean;
@@ -215,7 +217,11 @@ export async function restoreFromArtifactFile(
       {},
       {},
       logger,
-      { debug: false, systems: getModuleSystems(mod.id, db) },
+      {
+        debug: false,
+        systems: getModuleSystems(mod.id, db),
+        remoteAccess: remoteAccessPolicy(mod.id, db),
+      },
     );
     if (!hookResult.success) {
       const errMsg = hookResult.error ?? 'on_restore hook failed';
@@ -376,10 +382,10 @@ export function applyStagedSystemFiles(systemStagingDir: string): StagedSystemAp
   // managed machines; the DB only carries the public half, so without the
   // private half on disk the restored box can't authenticate to the fleet.
   if (existsSync(stagedSsh)) {
-    // The fleet key lives next to the DB (on_install writes it to
-    // dirname(db_path)/.ssh), so follow the DB's location — not getDataDir()
-    // — in case CELILO_DB_PATH points somewhere custom.
-    const liveSshDir = join(dirname(getDbPath()), '.ssh');
+    // One helper, shared with the minting side, so restore and mint cannot
+    // drift to different directories. See getFleetSshDir for why it follows
+    // the DB rather than getDataDir().
+    const liveSshDir = getFleetSshDir();
     mkdirSync(liveSshDir, { recursive: true, mode: 0o700 });
     chmodSync(liveSshDir, 0o700);
     for (const entry of readdirSync(stagedSsh)) {

package/src/services/static-content-converge.test.ts

@@ -0,0 +1,338 @@
+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 { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { moduleConfigs, modules, webRoutes } from '../db/schema';
+import { setupTestDatabaseAt } from '../test-utils/database';
+import {
+  buildStaticContentPlan,
+  planStaticContent,
+  resolveStaticContentRetention,
+  staticContentVarsPath,
+  staticContentVarsYaml,
+  writeStaticContentVars,
+} from './static-content-converge';
+
+const HASH1 = 'a'.repeat(64);
+const HASH2 = 'b'.repeat(64);
+
+describe('planStaticContent — the declared release set (D10 task 4.1)', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'static-converge-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabaseAt(dbPath);
+
+    // Two installed modules with real web roots on disk.
+    writeSite('lunacycle', '<html>luna</html>');
+    writeSite('hello-foo', '<html>foo</html>');
+    db.insert(modules)
+      .values({
+        id: 'lunacycle',
+        name: 'Lunacycle',
+        version: '1.0.0',
+        manifestData: {},
+        sourcePath: join(dir, 'modules', 'lunacycle'),
+      })
+      .onConflictDoNothing()
+      .run();
+    db.insert(modules)
+      .values({
+        id: 'hello-foo',
+        name: 'Hello Foo',
+        version: '0.1.2',
+        manifestData: {},
+        sourcePath: join(dir, 'modules', 'hello-foo'),
+      })
+      .onConflictDoNothing()
+      .run();
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  function writeSite(moduleId: string, html: string): string {
+    const webRoot = join(dir, 'modules', moduleId, 'site', 'dist');
+    mkdirSync(webRoot, { recursive: true });
+    writeFileSync(join(webRoot, 'index.html'), html, 'utf-8');
+    return webRoot;
+  }
+
+  function insertRoute(route: {
+    slug: string;
+    moduleId: string;
+    hostname: string;
+    path?: string;
+    type?: 'static' | 'reverse_proxy';
+    contentHash?: string | null;
+  }) {
+    db.insert(webRoutes)
+      .values({
+        slug: route.slug,
+        moduleId: route.moduleId,
+        type: route.type ?? 'static',
+        path: route.path ?? '/',
+        hostname: route.hostname,
+        websocket: false,
+        contentHash: route.contentHash ?? HASH1,
+      })
+      .run();
+  }
+
+  it('groups by slug across hostnames and derives the source dir', () => {
+    insertRoute({ slug: 'lunacycle', moduleId: 'lunacycle', hostname: 'lunacycle.net' });
+    insertRoute({
+      slug: 'lunacycle',
+      moduleId: 'lunacycle',
+      hostname: 'www.example.com',
+      path: '/x',
+    });
+    insertRoute({
+      slug: 'hello-foo',
+      moduleId: 'hello-foo',
+      hostname: 'www.example.com',
+      path: '/foo',
+    });
+
+    const releases = planStaticContent(db);
+
+    // Reverse-proxy rows and rows without a hash are not releases.
+    expect(releases).toHaveLength(2);
+    const luna = releases.find((r) => r.slug === 'lunacycle');
+    expect(luna?.hostnames).toEqual(['lunacycle.net', 'www.example.com']);
+    expect(luna?.sourceDir).toBe(join(dir, 'modules', 'lunacycle', 'site', 'dist'));
+    expect(luna?.contentHash).toBe(HASH1);
+  });
+
+  it('a slug claimed by two modules is a contradiction, not a merge', () => {
+    insertRoute({ slug: 'about', moduleId: 'lunacycle', hostname: 'a.example.com' });
+    insertRoute({ slug: 'about', moduleId: 'hello-foo', hostname: 'b.example.com' });
+
+    expect(() => planStaticContent(db)).toThrow(/claimed by 2 modules/);
+  });
+
+  it('rows sharing a slug must share a hash', () => {
+    insertRoute({ slug: 'lunacycle', moduleId: 'lunacycle', hostname: 'lunacycle.net' });
+    insertRoute({
+      slug: 'lunacycle',
+      moduleId: 'lunacycle',
+      hostname: 'www.example.com',
+      path: '/x',
+      contentHash: HASH2,
+    });
+
+    expect(() => planStaticContent(db)).toThrow(/content hashes/);
+  });
+
+  it('a missing web root fails loudly instead of converging an empty release', () => {
+    insertRoute({ slug: 'lunacycle', moduleId: 'lunacycle', hostname: 'lunacycle.net' });
+    rmSync(join(dir, 'modules', 'lunacycle', 'site', 'dist'), { recursive: true, force: true });
+
+    expect(() => planStaticContent(db)).toThrow(/no built site/);
+  });
+});
+
+describe('resolveStaticContentRetention — operator config with a default', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'static-retention-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    db = await setupTestDatabaseAt(join(dir, 'celilo.db'));
+    db.insert(modules)
+      .values({
+        id: 'caddy',
+        name: 'Caddy',
+        version: '2.3.8',
+        manifestData: {
+          variables: { owns: [{ name: 'static_release_retention', default: 5 }] },
+        },
+        sourcePath: join(dir, 'modules', 'caddy'),
+      })
+      .onConflictDoNothing()
+      .run();
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it('operator config wins over the manifest default', () => {
+    db.insert(moduleConfigs)
+      .values({ moduleId: 'caddy', key: 'static_release_retention', value: '2', valueJson: '2' })
+      .run();
+    expect(resolveStaticContentRetention(db, 'caddy')).toBe(2);
+  });
+
+  it('falls back to the manifest default, then the constant', () => {
+    expect(resolveStaticContentRetention(db, 'caddy')).toBe(5);
+
+    db.update(modules).set({ manifestData: {} }).where(eq(modules.id, 'caddy')).run();
+    expect(resolveStaticContentRetention(db, 'caddy')).toBe(5);
+  });
+
+  it('rejects a retention that cannot keep the current release', () => {
+    db.insert(moduleConfigs)
+      .values({ moduleId: 'caddy', key: 'static_release_retention', value: '0', valueJson: '0' })
+      .run();
+    expect(() => resolveStaticContentRetention(db, 'caddy')).toThrow(/positive integer/);
+  });
+});
+
+describe('staticContentVarsYaml — deterministic desired state', () => {
+  it('carries slug, content_hash, hostnames and the derived source dir, keyed by slug', () => {
+    const yaml = staticContentVarsYaml({
+      retention: 3,
+      releases: [
+        {
+          slug: 'hello-foo',
+          contentHash: HASH2,
+          hostnames: ['www.example.com'],
+          sourceDir: '/data/modules/hello-foo/site/dist',
+        },
+        {
+          slug: 'lunacycle',
+          contentHash: HASH1,
+          hostnames: ['lunacycle.net', 'www.example.com'],
+          sourceDir: '/data/modules/lunacycle/site/dist',
+        },
+      ],
+    });
+
+    expect(yaml).toContain('static_release_retention: 3');
+    expect(yaml).toContain('slug: lunacycle');
+    expect(yaml).toContain(`content_hash: ${HASH1}`);
+    expect(yaml).toContain('source_dir: /data/modules/lunacycle/site/dist');
+    // Deterministic: same input, same bytes — the idempotence of the WRITE
+    // depends on it.
+    expect(yaml).toBe(
+      staticContentVarsYaml({
+        retention: 3,
+        releases: [
+          {
+            slug: 'hello-foo',
+            contentHash: HASH2,
+            hostnames: ['www.example.com'],
+            sourceDir: '/data/modules/hello-foo/site/dist',
+          },
+          {
+            slug: 'lunacycle',
+            contentHash: HASH1,
+            hostnames: ['lunacycle.net', 'www.example.com'],
+            sourceDir: '/data/modules/lunacycle/site/dist',
+          },
+        ],
+      }),
+    );
+  });
+});
+
+describe('writeStaticContentVars — lands in the generated inventory', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'static-vars-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    db = await setupTestDatabaseAt(join(dir, 'celilo.db'));
+    mkdirSync(join(dir, 'modules', 'caddy', 'site', 'dist'), { recursive: true });
+    writeFileSync(
+      join(dir, 'modules', 'caddy', 'site', 'dist', 'index.html'),
+      '<html>caddy</html>',
+      'utf-8',
+    );
+    db.insert(modules)
+      .values({
+        id: 'caddy',
+        name: 'Caddy',
+        version: '2.3.8',
+        manifestData: {},
+        sourcePath: join(dir, 'modules', 'caddy'),
+      })
+      .onConflictDoNothing()
+      .run();
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it('writes the vars file and never writes into a module tree (task 4.7)', async () => {
+    db.insert(webRoutes)
+      .values({
+        slug: 'caddy',
+        moduleId: 'caddy',
+        type: 'static',
+        path: '/',
+        hostname: 'www.example.com',
+        websocket: false,
+        contentHash: HASH1,
+      })
+      .run();
+
+    const moduleTreeBefore = readFileSync(
+      join(dir, 'modules', 'caddy', 'site', 'dist', 'index.html'),
+      'utf-8',
+    );
+    const result = await writeStaticContentVars(
+      db,
+      'caddy',
+      join(dir, 'modules', 'caddy', 'generated'),
+    );
+
+    expect(result.success).toBe(true);
+    const varsPath = staticContentVarsPath(join(dir, 'modules', 'caddy', 'generated'));
+    expect(existsSync(varsPath)).toBe(true);
+    expect(readFileSync(varsPath, 'utf-8')).toContain('slug: caddy');
+
+    // Task 4.7: the converge path is read-only over the module tree. The
+    // clientConfig write into it is celilo#1018 and belongs to that thread —
+    // THIS path must not add a second writer.
+    expect(readFileSync(join(dir, 'modules', 'caddy', 'site', 'dist', 'index.html'), 'utf-8')).toBe(
+      moduleTreeBefore,
+    );
+  });
+
+  it('buildStaticContentPlan carries the resolved retention alongside the releases', async () => {
+    db.insert(webRoutes)
+      .values({
+        slug: 'caddy',
+        moduleId: 'caddy',
+        type: 'static',
+        path: '/',
+        hostname: 'www.example.com',
+        websocket: false,
+        contentHash: HASH1,
+      })
+      .run();
+
+    const plan = buildStaticContentPlan(db, 'caddy');
+    expect(plan.retention).toBe(5);
+    expect(plan.releases).toHaveLength(1);
+  });
+});