@celilo/cli 3.1.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/cli/commands/publish/workspace.ts

@@ -405,9 +405,18 @@ export async function executeWorkspace(input: ExecuteWorkspaceInput): Promise<Pu
     // order, so this should be a no-op — but it catches operator typos
     // and any external `bun publish` invocation that bypasses the
     // ordered loop.
+    // Hand the guard the receipts for everything THIS RUN already
+    // published. npm's registry is eventually-consistent (measured 90s
+    // and 300s for two packages published two seconds apart), so without
+    // this the guard refuses to publish a package whose dependency the
+    // same run published successfully seconds earlier — celilo#1377.
     const checkResult = spawnSync('bun', [join(REPO_ROOT, 'scripts/check-publishable.ts'), pkg], {
       cwd: REPO_ROOT,
       stdio: 'inherit',
+      env: {
+        ...process.env,
+        CELILO_PUBLISHED_THIS_RUN: published.map((p) => `${p.name}@${p.version}`).join(','),
+      },
     });
     if (checkResult.status !== 0) {
       restorePackageJson(pkg, pkgJsonOriginal);

package/src/hooks/capability-loader.ts

@@ -80,6 +80,51 @@ import { loadHookConfigMap } from './load-hook-config';
  * upstream-chain wiring takes a second factory argument (`upstreamFirewall`)
  * that doesn't fit the `defineCapabilityFunction` shape.
  */
+/**
+ * Make the public_web provider re-render and converge, and insist it happened.
+ *
+ * Both triggers that change what the provider must serve come through here: a
+ * route registered or withdrawn, and a static site published. They used to be
+ * two different mechanisms — an event for routes, a direct core-side content
+ * converge for publishes — which is how a publish could converge content
+ * against a config the provider had not re-rendered. One path now
+ * (providers-converge-declared-state, design D6).
+ *
+ * Authoritative (ISS-0081): a change the provider never reconciled is a
+ * FAILURE, not a warning. These used to be logger.warn while the call returned
+ * success anyway, so a consumer could report "ready" while caddy never learned
+ * the hostname — no site block, no cert, TLS internal_error for clients.
+ */
+async function requireProviderReconcile(consumingModuleId: string, what: string): Promise<void> {
+  const reconcile = await emitWebRoutesChangedAndWait(consumingModuleId);
+
+  if (reconcile.noDispatcher) {
+    throw new Error(
+      `public_web ${what} for ${consumingModuleId} was persisted but NOT delivered to the provider (caddy): no event dispatcher is running, so caddy never reconciled and the hostname has no site block or cert. Run this through \`celilo module deploy\` (which runs the dispatcher) rather than a bare hook.`,
+    );
+  }
+  if (reconcile.timedOut) {
+    throw new Error(
+      `public_web reconcile for ${consumingModuleId} (${what}) did not finish within the deadline (${reconcile.succeeded} ok, ${reconcile.failed} failed of ${reconcile.events} change event(s)) — caddy did not confirm the change is live.`,
+    );
+  }
+  if (reconcile.failed > 0) {
+    throw new Error(
+      `public_web reconcile for ${consumingModuleId} (${what}): ${reconcile.failed} delivery(ies) failed — caddy could not apply the change, so the hostname is not served as declared.`,
+    );
+  }
+  // ISS-0087: a change WAS persisted and the dispatcher IS alive, yet ZERO
+  // providers reconciled it (no subscriber consumed routes_changed). That
+  // would otherwise report success for something nobody applied. `events === 0`
+  // means nothing changed (benign); `events > 0 && succeeded === 0` means it
+  // changed and nobody served it — a failure.
+  if (reconcile.events > 0 && reconcile.succeeded === 0) {
+    throw new Error(
+      `public_web ${what} for ${consumingModuleId} changed (${reconcile.events} event(s)) but NO provider reconciled it — caddy has no reconcile_routes subscription on the bus, so the change is persisted yet never served. Ensure a public_web provider (caddy) is deployed and subscribed.`,
+    );
+  }
+}
+
 export const CAPABILITY_MODULE_MAP: Record<string, { script: string; legacyFactoryName: string }> =
   {
     dns_registrar: {
@@ -646,19 +691,26 @@ export async function loadCapabilityFunctions(
         caddyModuleId: provider.moduleId,
         dnsManagedDomains,
         dnsRegistrarModuleId,
-        // Design D10: the bytes move through the provider's Ansible converge,
-        // not a hand-built ssh tar pipe. Core implements it over
-        // executeAnsible against the provider's generated project (task 4.3);
-        // awaited with everything else, so a publish returns only once the
-        // host matches. A failure here fails the deploy loudly — a publish
+        // The bytes move through the provider's Ansible converge, not a
+        // hand-built ssh tar pipe (design D10). What changed in
+        // providers-converge-declared-state is WHO decides what to converge:
+        // core used to plan the whole fleet's release set here and throw when
+        // any one module had no built site (celilo#1383). Now the publish
+        // makes the PROVIDER re-render from the declared rows — the same path
+        // a route change takes — so content and config converge together and a
+        // broken consumer costs only its own site.
+        //
+        // The field keeps its name: it is passed into `createPublicWeb` inside
+        // the CONSUMER's bundled copy of @celilo/capabilities, and a module
+        // running an older bundle calls `deps.convergeStaticContent()` by that
+        // name. Renaming it here would leave that call undefined on every
+        // module that has not reinstalled.
+        //
+        // Awaited, so a publish returns only once the host matches: a publish
         // that reports ready while the host never received the bytes is the
         // exact "served but silently unreachable" anti-pattern.
         convergeStaticContent: async () => {
-          const { convergeStaticContent } = await import('../services/static-content-converge');
-          const result = await convergeStaticContent(db, provider.moduleId, consumingModuleId);
-          if (!result.success) {
-            throw new Error(result.error ?? 'static-content converge failed');
-          }
+          await requireProviderReconcile(consumingModuleId, 'static publish');
         },
         // ISS-0035: register_route/unregister_routes emit this coarse signal
         // instead of SSHing caddy; the caddy provider's reconcile_routes
@@ -667,37 +719,7 @@ export async function loadCapabilityFunctions(
         // the consuming module's health_check runs right after and would
         // otherwise race the async reconcile.
         onRoutesChanged: async () => {
-          const reconcile = await emitWebRoutesChangedAndWait(consumingModuleId);
-          // Authoritative (ISS-0081): a route the provider (caddy) never
-          // reconciled is a deploy FAILURE, not a warning. These used to be
-          // logger.warn while register_route returned success anyway, so a
-          // consumer could report "ready" while caddy never learned the
-          // hostname — no site block, no cert, TLS internal_error for clients.
-          if (reconcile.noDispatcher) {
-            throw new Error(
-              `public_web route for ${consumingModuleId} was persisted but NOT delivered to the provider (caddy): no event dispatcher is running, so caddy never reconciled and the hostname has no site block or cert. Run this through \`celilo module deploy\` (which runs the dispatcher) rather than a bare hook.`,
-            );
-          }
-          if (reconcile.timedOut) {
-            throw new Error(
-              `public_web reconcile for ${consumingModuleId} did not finish within the deadline (${reconcile.succeeded} ok, ${reconcile.failed} failed of ${reconcile.events} change event(s)) — caddy did not confirm the route is live.`,
-            );
-          }
-          if (reconcile.failed > 0) {
-            throw new Error(
-              `public_web reconcile for ${consumingModuleId}: ${reconcile.failed} delivery(ies) failed — caddy could not apply the route, so the hostname is not served.`,
-            );
-          }
-          // ISS-0087: a route WAS registered and the dispatcher IS alive, yet ZERO
-          // providers reconciled it (no subscriber consumed routes_changed). That
-          // registers a route nobody applied and would otherwise report success.
-          // `events === 0` means no routes changed (benign); `events > 0 &&
-          // succeeded === 0` means the route changed but nobody served it — a failure.
-          if (reconcile.events > 0 && reconcile.succeeded === 0) {
-            throw new Error(
-              `public_web route for ${consumingModuleId} changed (${reconcile.events} event(s)) but NO provider reconciled it — caddy has no reconcile_routes subscription on the bus, so the route is persisted yet never served (no site block, no cert). Ensure a public_web provider (caddy) is deployed and subscribed.`,
-            );
-          }
+          await requireProviderReconcile(consumingModuleId, 'route change');
         },
       });
       debugLog(`public_web: loaded via framework implementation for ${consumingModuleId}`);
@@ -734,6 +756,22 @@ export async function loadCapabilityFunctions(
           const { resolveModuleStateWebRoot, resolveModuleWebRoot } = await import(
             '../module/web-root'
           );
+
+          // Pause preserves state (module-pause spec), so a paused module's
+          // site is not re-converged. Leaving it out of the provider's site
+          // list is exactly that: the role converges only the slugs it is
+          // given and prunes nothing else, so the release already on the box
+          // stays, and the module's routes still render into the config.
+          //
+          // This is where d04a2bb7's paused filter went when core's fleet-wide
+          // plan was deleted. It moved rather than vanished, and it moved to
+          // the per-module lookup, which is the only place that can answer for
+          // one module without walking the rest.
+          const { isModulePaused } = await import('../services/module-pause');
+          if (isModulePaused(db, moduleId)) {
+            return { unavailable: `module '${moduleId}' is paused — its site is left as it is` };
+          }
+
           const sourceDir = resolveModuleWebRoot(moduleId, db);
           if (!sourceDir) {
             return { unavailable: `module '${moduleId}' is not installed` };
@@ -749,9 +787,8 @@ export async function loadCapabilityFunctions(
           return { sourceDir, ...overlayDir };
         },
         converge: async (artifacts) => {
-          const { convergeProviderConfig } = await import('../services/provider-converge');
-          const { resolveStaticContentRetention } = await import(
-            '../services/static-content-converge'
+          const { convergeProviderConfig, resolveStaticContentRetention } = await import(
+            '../services/provider-converge'
           );
           const result = await convergeProviderConfig(db, providerModuleId, {
             ...artifacts,

package/src/policy/module-business-baseline.ts

@@ -514,10 +514,4 @@ export const PROVIDER_LITERAL_BASELINE: readonly ProviderLiteralRow[] = [
     count: 3,
     why: "X8 — the Caddyfile generator knows caddy's on-disk asset layout (#940)",
   },
-  {
-    file: 'apps/celilo/src/services/static-content-converge.ts',
-    literal: '/srv/www',
-    count: 1,
-    why: "D10 (capability-owned-tables stage 4): the converge's slug-collision error names the on-disk release path an operator must fix. The role under modules/caddy owns the real path handling; this is message text, not path logic.",
-  },
 ];

package/src/services/module-deploy.ts

@@ -1474,19 +1474,33 @@ 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.
+    // A public_web provider's deploy no longer plans the fleet's static content
+    // here. Core used to walk every declared route row, resolve every module's
+    // built site, and throw for the whole deploy when any one of them was
+    // missing — celilo#1383, where two out-of-tree modules made the public
+    // ingress undeployable. The provider now renders its own desired state in
+    // its hook and hands it to the converge, which runs the same role tasks
+    // (providers-converge-declared-state, design D4/D6). on_install runs
+    // immediately after this play, so /srv/www still converges on a rebuilt
+    // host — through one path instead of two.
+    //
+    // A provider whose role predates that converge would deploy cleanly and
+    // then never converge its static content again: core no longer writes the
+    // release set, and the old role has no task that reads what the provider
+    // rendered. Nothing would report it — the deploy succeeds, the publish
+    // succeeds, and /srv/www silently stops tracking what is declared. So the
+    // version skew is refused here, by the same tree scan the converge itself
+    // uses, and the message names the upgrade that fixes it.
     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 };
+      const { ansibleTreeMentions } = await import('./provider-converge');
+      const ansiblePath = join(generatedPath, 'ansible');
+      if (existsSync(ansiblePath) && !ansibleTreeMentions(ansiblePath, 'provider_config_files')) {
+        return {
+          success: false,
+          error: `The installed version of '${moduleId}' predates the provider converge: its role never reads provider_config_files, so celilo would deploy it and then have no way to place the config or the sites it renders. Upgrade it first (\`celilo module upgrade ${moduleId}\`), then deploy.`,
+          phases,
+        };
       }
-      log.success('Static-content release set written to the inventory');
     }
 
     try {

package/src/services/provider-converge.test.ts

@@ -138,6 +138,22 @@ describe('recordUnresolvedConsumers — the failure belongs to the consumer', ()
     return db.select().from(modules).where(eq(modules.id, id)).get();
   }
 
+  it('leaves a PAUSED consumer paused — a provider cannot render it by design', () => {
+    db.update(modules).set({ state: 'PAUSED' }).where(eq(modules.id, 'byoi')).run();
+
+    const recorded = recordUnresolvedConsumers(db, 'caddy', [
+      { moduleId: 'byoi', reason: "module 'byoi' is paused — its site is left as it is" },
+    ]);
+
+    // Pause preserves state, and that includes the module's own recorded
+    // state. A paused module is unresolvable on EVERY converge, so marking it
+    // ERROR here would mean an operator could not pause a module without the
+    // next publish reporting it failed.
+    expect(recorded).toEqual([]);
+    expect(stateOf('byoi')?.state).toBe('PAUSED');
+    expect(stateOf('byoi')?.errorMessage ?? null).toBeNull();
+  });
+
   it('records the consumer in ERROR with the reason it could not be rendered', () => {
     recordUnresolvedConsumers(db, 'caddy', [
       { moduleId: 'byoi', reason: 'no built site at /var/celilo/modules/byoi/site/dist' },

package/src/services/provider-converge.ts

@@ -15,14 +15,22 @@
  * against that consumer.
  */
 
-import { existsSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { eq } from 'drizzle-orm';
+import { and, eq } from 'drizzle-orm';
 import { stringify as stringifyYaml } from 'yaml';
 import type { DbClient } from '../db/client';
-import { modules } from '../db/schema';
-import { ansibleTreeMentions } from './static-content-converge';
+import { moduleConfigs, modules } from '../db/schema';
+import { parseStoredConfigValue } from './module-config';
+
+/**
+ * Retention when the operator has not set one. Mirrors the manifest default
+ * declared on the provider module (`static_release_retention`); the manifest
+ * is the operator-facing source of truth, this only covers a provider whose
+ * manifest predates the variable.
+ */
+const DEFAULT_STATIC_RELEASE_RETENTION = 5;
 
 /** One file the provider wants on its host, rendered by the provider. */
 export interface ProviderConfigFile {
@@ -121,6 +129,14 @@ export function recordUnresolvedConsumers(
     const existing = db.select().from(modules).where(eq(modules.id, consumer.moduleId)).get();
     if (!existing) continue;
 
+    // A PAUSED module is not broken, and pause preserves state — including the
+    // module's own recorded state. A provider legitimately cannot render a
+    // paused consumer (its site is deliberately left alone), so this path is
+    // reached on every converge while any module is paused; writing ERROR
+    // there would mean an operator could not pause a module without the next
+    // publish marking it failed.
+    if (existing.state === 'PAUSED') continue;
+
     db.update(modules)
       .set({
         state: 'ERROR',
@@ -239,3 +255,89 @@ export async function convergeProviderConfig(
   rmSync(generatedPath, { recursive: true, force: true });
   return { success: true, varsPath, unresolved };
 }
+
+/**
+ * Resolve the retention count for the provider module.
+ *
+ * Operator config first (`static_release_retention` module config), then the
+ * manifest's declared default, then the constant above. ONE resolution — the
+ * role reads the variable bare and never carries a literal.
+ */
+export function resolveStaticContentRetention(db: DbClient, providerModuleId: string): number {
+  const configRow = db
+    .select()
+    .from(moduleConfigs)
+    .where(
+      and(
+        eq(moduleConfigs.moduleId, providerModuleId),
+        eq(moduleConfigs.key, 'static_release_retention'),
+      ),
+    )
+    .get();
+  if (configRow) {
+    const parsed = parseStoredConfigValue(configRow);
+    const count = typeof parsed === 'number' ? parsed : Number.parseInt(String(parsed), 10);
+    if (Number.isInteger(count) && count >= 1) return count;
+    throw new Error(
+      `static_release_retention for ${providerModuleId} must be a positive integer, got: ${String(parsed)}`,
+    );
+  }
+
+  const module = db.select().from(modules).where(eq(modules.id, providerModuleId)).get();
+  if (module) {
+    const manifest = module.manifestData as {
+      variables?: { owns?: Array<{ name?: string; default?: unknown }> };
+    } | null;
+    const declared = manifest?.variables?.owns?.find((v) => v?.name === 'static_release_retention');
+    const fallback = typeof declared?.default === 'number' ? declared.default : undefined;
+    if (typeof fallback === 'number' && Number.isInteger(fallback) && fallback >= 1)
+      return fallback;
+  }
+
+  return DEFAULT_STATIC_RELEASE_RETENTION;
+}
+
+/**
+ * Build the release set from the declared `web_routes` rows.
+ *
+ * Pure: reads the DB, decides nothing on the host (Rule 10.4). Grouping is by
+ * slug, NOT by route — one slug is one release directory, and a slug can span
+ * hostnames (lunacycle's two routes, both at `/`). A group that spans modules
+ * or disagrees with itself about the hash is a contradiction the converge
+ * cannot express, so it fails here with both rows named rather than silently
+ * converging one of them.
+ */
+
+/**
+ * Whether any text file in a generated Ansible tree mentions `needle`.
+ *
+ * Scans the TREE rather than `playbook.yml`, because a provider's converge
+ * belongs in one of its role's task files and a generated `playbook.yml` is a
+ * thin hosts/vars/roles stanza that names no variable at all. caddy is the
+ * worked example: `static_releases` appears in
+ * `roles/caddy/tasks/static-content.yml`, `.../main.yml.tpl` and
+ * `.../converge-release.yml`, and zero times in its playbook.
+ *
+ * @psbanka - 2026-09: this used to read `ansible/playbook.yml` alone, which
+ * could not reach the string it was looking for. The guard below therefore
+ * refused EVERY provider that had the converge support, and its remedy told the
+ * operator to redeploy — which regenerates the same thin playbook and cannot
+ * help. Guard and role tasks landed in the same commit (1fd3595e), so it had
+ * never once passed, and it held three e2e suites red where nobody was looking.
+ * celilo#1248.
+ */
+export function ansibleTreeMentions(dir: string, needle: string): boolean {
+  if (!existsSync(dir)) return false;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (ansibleTreeMentions(full, needle)) return true;
+      continue;
+    }
+    // Text only. A generated tree can carry static assets, and reading those
+    // as utf-8 to look for a variable name is waste at best.
+    if (!/\.(ya?ml|j2|tpl|cfg|ini|conf)$/.test(entry.name)) continue;
+    if (readFileSync(full, 'utf-8').includes(needle)) return true;
+  }
+  return false;
+}

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

@@ -1,516 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import {
-  cpSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join, resolve } 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 { resetTestDbPath } from '../test-utils/db-path';
-import {
-  ansibleTreeMentions,
-  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();
-    resetTestDbPath();
-    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/);
-  });
-
-  function pause(moduleId: string) {
-    db.update(modules).set({ state: 'PAUSED' }).where(eq(modules.id, moduleId)).run();
-  }
-
-  it("a paused module's slug is left alone, even one that would throw, and the rest converge (celilo#1383)", () => {
-    insertRoute({ slug: 'lunacycle', moduleId: 'lunacycle', hostname: 'lunacycle.net' });
-    insertRoute({
-      slug: 'lunacycle',
-      moduleId: 'lunacycle',
-      hostname: 'www.lunacycle.net',
-      contentHash: HASH2,
-    });
-    rmSync(join(dir, 'modules', 'lunacycle', 'site', 'dist'), { recursive: true, force: true });
-    insertRoute({
-      slug: 'hello-foo',
-      moduleId: 'hello-foo',
-      hostname: 'www.example.com',
-      path: '/foo',
-    });
-    pause('lunacycle');
-
-    expect(planStaticContent(db).map((r) => r.slug)).toEqual(['hello-foo']);
-  });
-
-  it('a paused module that is publishing (an unpause redeploy) still converges its own slug', () => {
-    insertRoute({ slug: 'lunacycle', moduleId: 'lunacycle', hostname: 'lunacycle.net' });
-    pause('lunacycle');
-
-    expect(planStaticContent(db, 'lunacycle').map((r) => r.slug)).toEqual(['lunacycle']);
-  });
-
-  it('a slug shared by a paused and an active module is still a contradiction', () => {
-    insertRoute({ slug: 'about', moduleId: 'lunacycle', hostname: 'a.example.com' });
-    insertRoute({ slug: 'about', moduleId: 'hello-foo', hostname: 'b.example.com' });
-    pause('lunacycle');
-
-    expect(() => planStaticContent(db)).toThrow(/claimed by 2 modules/);
-  });
-});
-
-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();
-    resetTestDbPath();
-    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('the state web overlay (celilo#1265)', () => {
-  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);
-    writeSite('lunacycle', '<html>luna</html>');
-    db.insert(modules)
-      .values({
-        id: 'lunacycle',
-        name: 'Lunacycle',
-        version: '1.0.0',
-        manifestData: {},
-        sourcePath: join(dir, 'modules', 'lunacycle'),
-      })
-      .onConflictDoNothing()
-      .run();
-  });
-
-  afterEach(() => {
-    db.$client.close();
-    resetTestDbPath();
-    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 }) {
-    db.insert(webRoutes)
-      .values({
-        slug: route.slug,
-        moduleId: route.moduleId,
-        type: 'static',
-        path: '/',
-        hostname: route.hostname,
-        websocket: false,
-        contentHash: HASH1,
-      })
-      .run();
-  }
-
-  it('a release with a state overlay carries its directory; one without does not', () => {
-    insertRoute({ slug: 'lunacycle', moduleId: 'lunacycle', hostname: 'lunacycle.net' });
-
-    // No overlay in state: the release names no overlay_dir, and the converge
-    // role has nothing second to copy.
-    const bare = planStaticContent(db);
-    expect(bare).toHaveLength(1);
-    expect(bare[0]?.overlayDir).toBeUndefined();
-    expect(staticContentVarsYaml({ retention: 1, releases: bare })).not.toContain('overlay_dir');
-
-    // The hook wrote generated files into `<module>/state/site`: the converge
-    // must copy them over the release, or a rebuilt host loses the file.
-    const overlay = join(dir, 'modules', 'lunacycle', 'state', 'site');
-    mkdirSync(overlay, { recursive: true });
-    writeFileSync(join(overlay, 'ca.crt'), '---CERT---', 'utf-8');
-
-    const overlaid = planStaticContent(db);
-    expect(overlaid[0]?.overlayDir).toBe(overlay);
-    const yaml = staticContentVarsYaml({ retention: 1, releases: overlaid });
-    expect(yaml).toContain('overlay_dir:');
-  });
-});
-
-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();
-    resetTestDbPath();
-    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);
-  });
-});
-
-describe('the stale-project guard reaches the whole generated tree (celilo#1248)', () => {
-  let dir: string;
-
-  beforeEach(() => {
-    dir = mkdtempSync(join(tmpdir(), 'static-guard-reach-'));
-  });
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-  });
-
-  it('sees a converge that lives in a role task file, not in playbook.yml', () => {
-    // Mirror DERIVED from the real module, never hand-written: a hand-built
-    // tree would give confident reach data about a world that does not exist,
-    // which is the same bug one level up.
-    const real = resolve(import.meta.dir, '../../../..', 'modules/caddy/ansible');
-    cpSync(real, join(dir, 'ansible'), { recursive: true });
-
-    // The premise this guards. caddy's playbook is a thin hosts/vars/roles
-    // stanza; if it ever DOES name static_releases, this test stops proving
-    // anything and should be re-derived rather than deleted.
-    const playbook = readFileSync(join(dir, 'ansible/playbook.yml.tpl'), 'utf-8');
-    expect(playbook).not.toContain('static_releases');
-
-    expect(ansibleTreeMentions(join(dir, 'ansible'), 'static_releases')).toBe(true);
-  });
-
-  it('still refuses a project that mentions the var nowhere', () => {
-    // A pre-converge generated project. Hand-built deliberately, and it has to
-    // be: no deploy on today's code can produce a tree without the role tasks,
-    // so this legacy shape is the fixture and not a shortcut.
-    mkdirSync(join(dir, 'ansible/roles/caddy/tasks'), { recursive: true });
-    writeFileSync(
-      join(dir, 'ansible/playbook.yml'),
-      '---\n- hosts: caddy\n  roles:\n    - caddy\n',
-    );
-    writeFileSync(
-      join(dir, 'ansible/roles/caddy/tasks/main.yml'),
-      '---\n- name: install\n  debug: {}\n',
-    );
-
-    expect(ansibleTreeMentions(join(dir, 'ansible'), 'static_releases')).toBe(false);
-  });
-
-  it('ignores non-text files rather than reading assets as utf-8', () => {
-    mkdirSync(join(dir, 'ansible/files'), { recursive: true });
-    writeFileSync(join(dir, 'ansible/files/logo.png'), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
-    writeFileSync(join(dir, 'ansible/site.yml'), 'vars:\n  static_releases: []\n');
-
-    expect(ansibleTreeMentions(join(dir, 'ansible'), 'static_releases')).toBe(true);
-    expect(ansibleTreeMentions(join(dir, 'ansible'), 'PNG')).toBe(false);
-  });
-});

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

@@ -1,390 +0,0 @@
-/**
- * The static-content converge (openspec/changes/capability-owned-tables,
- * stage 4 / design D10).
- *
- * `/srv/www` on the public_web provider stops being whatever the last
- * hand-built ssh upload left there and becomes convergent state: every
- * declared static route's release directory exists, `/srv/www/<slug>` points
- * at the current one through an atomic symlink swap, and everything past the
- * retention count is pruned. One Ansible converge makes the host match.
- *
- * Two callers, one code path:
- *  - the `public_web` capability's publish (`convergeStaticContent` callback
- *    injected by capability-loader), which runs the whole converge including
- *    `executeAnsible`, so a publish returns only once the host matches; and
- *  - the provider's OWN deploy (module-deploy), which writes the same release
- *    set into its generated inventory and lets the deploy's existing
- *    `executeAnsible` run the same role tasks — that is how a rebuilt host
- *    recovers with no consumer involvement (design D10, task 4.5).
- *
- * The desired state is the declared `web_routes` release set plus the source
- * directory core derived from `modules.source_path`. Nothing here writes into
- * a module tree: reading a module's web root is safe, writing is what breaks
- * `module verify` (celilo#1018, deliberately left to that thread).
- */
-
-import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { and, eq, isNotNull } from 'drizzle-orm';
-import { stringify as stringifyYaml } from 'yaml';
-import type { DbClient } from '../db/client';
-import { moduleConfigs, modules, webRoutes } from '../db/schema';
-import { resolveModuleStateWebRoot, resolveModuleWebRoot } from '../module/web-root';
-import { parseStoredConfigValue } from './module-config';
-import { listPausedModules } from './module-pause';
-
-/** One content-hashed release the provider host must serve. */
-export interface StaticRelease {
-  /** The `/srv/www/<slug>` key. Independent of hostname on purpose. */
-  slug: string;
-  /** Content hash of the release — the release directory's suffix. */
-  contentHash: string;
-  /** Every FQDN served by this slug's routes (a slug spans hostnames). */
-  hostnames: string[];
-  /** Absolute celilo-mgr path core derived: `<module source_path>/site/dist`. */
-  sourceDir: string;
-  /**
-   * Absolute path to `<module source_path>/state/site` (celilo#1265), present
-   * ONLY when that directory exists. The role copies it over the release
-   * after the web root, so a hook-generated file wins over a built one. A
-   * module with no generated site content has no overlay and no row.
-   */
-  overlayDir?: string;
-}
-
-export interface StaticContentPlan {
-  releases: StaticRelease[];
-  /** How many release directories to keep per slug after a converge. */
-  retention: number;
-}
-
-/**
- * Retention when the operator has not set one. Mirrors the manifest default
- * declared on the provider module (`static_release_retention`); the manifest
- * is the operator-facing source of truth, this only covers a provider whose
- * manifest predates the variable.
- */
-const DEFAULT_STATIC_RELEASE_RETENTION = 5;
-
-export interface StaticContentConvergeResult {
-  success: boolean;
-  error?: string;
-  /** The written vars file, repo-absolute — for logs and tests. */
-  varsPath?: string;
-}
-
-/**
- * Where the converge's desired state lands inside the provider's generated
- * project. `group_vars/all/` is the existing auto-load directory (it already
- * holds `secrets.yml`), so no playbook change is needed to read it.
- */
-export function staticContentVarsPath(generatedPath: string): string {
-  return join(generatedPath, 'ansible', 'inventory', 'group_vars', 'all', 'static_content.yml');
-}
-
-/**
- * Resolve the retention count for the provider module.
- *
- * Operator config first (`static_release_retention` module config), then the
- * manifest's declared default, then the constant above. ONE resolution — the
- * role reads the variable bare and never carries a literal.
- */
-export function resolveStaticContentRetention(db: DbClient, providerModuleId: string): number {
-  const configRow = db
-    .select()
-    .from(moduleConfigs)
-    .where(
-      and(
-        eq(moduleConfigs.moduleId, providerModuleId),
-        eq(moduleConfigs.key, 'static_release_retention'),
-      ),
-    )
-    .get();
-  if (configRow) {
-    const parsed = parseStoredConfigValue(configRow);
-    const count = typeof parsed === 'number' ? parsed : Number.parseInt(String(parsed), 10);
-    if (Number.isInteger(count) && count >= 1) return count;
-    throw new Error(
-      `static_release_retention for ${providerModuleId} must be a positive integer, got: ${String(parsed)}`,
-    );
-  }
-
-  const module = db.select().from(modules).where(eq(modules.id, providerModuleId)).get();
-  if (module) {
-    const manifest = module.manifestData as {
-      variables?: { owns?: Array<{ name?: string; default?: unknown }> };
-    } | null;
-    const declared = manifest?.variables?.owns?.find((v) => v?.name === 'static_release_retention');
-    const fallback = typeof declared?.default === 'number' ? declared.default : undefined;
-    if (typeof fallback === 'number' && Number.isInteger(fallback) && fallback >= 1)
-      return fallback;
-  }
-
-  return DEFAULT_STATIC_RELEASE_RETENTION;
-}
-
-/**
- * Build the release set from the declared `web_routes` rows.
- *
- * Pure: reads the DB, decides nothing on the host (Rule 10.4). Grouping is by
- * slug, NOT by route — one slug is one release directory, and a slug can span
- * hostnames (lunacycle's two routes, both at `/`). A group that spans modules
- * or disagrees with itself about the hash is a contradiction the converge
- * cannot express, so it fails here with both rows named rather than silently
- * converging one of them.
- */
-export function planStaticContent(db: DbClient, publishingModuleId?: string): StaticRelease[] {
-  const rows = db
-    .select()
-    .from(webRoutes)
-    .where(and(eq(webRoutes.type, 'static'), isNotNull(webRoutes.contentHash)))
-    .all();
-
-  const bySlug = new Map<string, typeof rows>();
-  for (const row of rows) {
-    const group = bySlug.get(row.slug) ?? [];
-    group.push(row);
-    bySlug.set(row.slug, group);
-  }
-
-  // A paused module's site is left exactly as it is — pause preserves state
-  // (module-pause spec) — so its slug is neither converged nor validated. The
-  // exception is the module publishing right now: an unpause redeploy runs
-  // on_install while the module is still PAUSED (executeUnpause clears the
-  // pause only after the redeploy succeeds). celilo#1383.
-  const paused = new Set(listPausedModules(db).map((m) => m.id));
-  if (publishingModuleId) paused.delete(publishingModuleId);
-
-  const releases: StaticRelease[] = [];
-  for (const [slug, group] of bySlug) {
-    const moduleIds = [...new Set(group.map((r) => r.moduleId))];
-    if (moduleIds.length > 1) {
-      throw new Error(
-        `Static route slug "${slug}" is claimed by ${moduleIds.length} modules (${moduleIds.join(', ')}). The slug is the release key — /srv/www/${slug} cannot serve two release sets. Fix the colliding modules' registered paths.`,
-      );
-    }
-    const moduleId = moduleIds[0];
-    if (!moduleId) continue;
-    if (paused.has(moduleId)) continue;
-
-    const hashes = [...new Set(group.map((r) => r.contentHash))];
-    if (hashes.length > 1) {
-      throw new Error(
-        `Static route slug "${slug}" (module ${moduleId}) holds ${hashes.length} content hashes (${hashes.join(', ')}) — rows sharing a slug must share a release. Re-publish the module so every row carries the current hash.`,
-      );
-    }
-    const contentHash = hashes[0];
-    if (!contentHash) continue;
-
-    const sourceDir = resolveModuleWebRoot(moduleId, db);
-    if (!sourceDir) {
-      throw new Error(
-        `Static route slug "${slug}" belongs to module "${moduleId}", which is not installed — its release has no source to converge from.`,
-      );
-    }
-    if (!existsSync(sourceDir)) {
-      throw new Error(
-        `Static route slug "${slug}": no built site at ${sourceDir}. A module that serves a static site ships it at <module root>/site/dist. Redeploy the module.`,
-      );
-    }
-
-    // Present only when the module's hook actually wrote an overlay —
-    // otherwise the vars file would name a directory that does not exist
-    // and the role's copy task would have nothing to copy from.
-    const stateWebRoot = resolveModuleStateWebRoot(moduleId, db);
-    const overlayDir = stateWebRoot && existsSync(stateWebRoot) ? stateWebRoot : undefined;
-    releases.push({
-      slug,
-      contentHash,
-      hostnames: [...new Set(group.map((r) => r.hostname))].sort(),
-      sourceDir,
-      ...(overlayDir ? { overlayDir } : {}),
-    });
-  }
-
-  releases.sort((a, b) => a.slug.localeCompare(b.slug));
-  return releases;
-}
-
-/**
- * The full desired state: the release set plus the retention count resolved
- * for THIS provider module. The unit the vars file and the tests speak in.
- */
-export function buildStaticContentPlan(
-  db: DbClient,
-  providerModuleId: string,
-  publishingModuleId?: string,
-): StaticContentPlan {
-  return {
-    releases: planStaticContent(db, publishingModuleId),
-    retention: resolveStaticContentRetention(db, providerModuleId),
-  };
-}
-
-/**
- * Render the vars file. Presentation function (Rule 10.1) — deterministic
- * YAML, keyed by slug, carrying what 4.1 names: slug, content_hash, the
- * hostnames served, and the source directory core derived.
- */
-export function staticContentVarsYaml(plan: StaticContentPlan): string {
-  const vars = {
-    static_release_retention: plan.retention,
-    static_releases: plan.releases.map((r) => ({
-      slug: r.slug,
-      content_hash: r.contentHash,
-      hostnames: r.hostnames,
-      source_dir: r.sourceDir,
-      // Absent when there is no overlay, so the role's `when:` guard reads a
-      // clean variable — not an empty string a copy task would choke on.
-      ...(r.overlayDir ? { overlay_dir: r.overlayDir } : {}),
-    })),
-  };
-  const header =
-    '# Desired static-content state, generated by celilo (capability-owned-tables D10).\n' +
-    '# Hand edits are overwritten by the next converge. K = static_release_retention.\n';
-  return `${header}${stringifyYaml(vars, { lineWidth: 0, sortMapEntries: true })}`;
-}
-
-/**
- * Plan the release set and write it into the provider's generated inventory.
- *
- * The shared half of both converge triggers: the capability's callback adds
- * `executeAnsible` after this, and the provider's own deploy already runs it.
- * Nothing inspects verbatim role assets any more — the staleness pre-flight
- * retired with the ephemeral generated tree (D5 of
- * control-plane-stops-building-modules), so an injected vars file cannot read
- * as a stale generation because nothing reads staleness.
- */
-export async function writeStaticContentVars(
-  db: DbClient,
-  providerModuleId: string,
-  generatedPath: string,
-  publishingModuleId?: string,
-): Promise<StaticContentConvergeResult> {
-  const varsPath = staticContentVarsPath(generatedPath);
-
-  const plan = buildStaticContentPlan(db, providerModuleId, publishingModuleId);
-
-  await mkdir(join(varsPath, '..'), { recursive: true });
-  await writeFile(varsPath, staticContentVarsYaml(plan), 'utf-8');
-  return { success: true, varsPath };
-}
-
-/**
- * The full converge: plan, write the desired state, run Ansible against the
- * provider's generated project.
- *
- * `generatedPath` must already exist — it is the project the provider's last
- * deploy generated. If the project predates the converge role tasks, the
- * written state would be read by nothing and the transfer would silently
- * never happen, so the playbook is checked for the converge's own variable
- * first and a stale project fails loudly with the redeploy that fixes it.
- */
-/**
- * Whether any text file in a generated Ansible tree mentions `needle`.
- *
- * Scans the TREE rather than `playbook.yml`, because a provider's converge
- * belongs in one of its role's task files and a generated `playbook.yml` is a
- * thin hosts/vars/roles stanza that names no variable at all. caddy is the
- * worked example: `static_releases` appears in
- * `roles/caddy/tasks/static-content.yml`, `.../main.yml.tpl` and
- * `.../converge-release.yml`, and zero times in its playbook.
- *
- * @psbanka - 2026-09: this used to read `ansible/playbook.yml` alone, which
- * could not reach the string it was looking for. The guard below therefore
- * refused EVERY provider that had the converge support, and its remedy told the
- * operator to redeploy — which regenerates the same thin playbook and cannot
- * help. Guard and role tasks landed in the same commit (1fd3595e), so it had
- * never once passed, and it held three e2e suites red where nobody was looking.
- * celilo#1248.
- */
-export function ansibleTreeMentions(dir: string, needle: string): boolean {
-  if (!existsSync(dir)) return false;
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (ansibleTreeMentions(full, needle)) return true;
-      continue;
-    }
-    // Text only. A generated tree can carry static assets, and reading those
-    // as utf-8 to look for a variable name is waste at best.
-    if (!/\.(ya?ml|j2|tpl|cfg|ini|conf)$/.test(entry.name)) continue;
-    if (readFileSync(full, 'utf-8').includes(needle)) return true;
-  }
-  return false;
-}
-
-export async function convergeStaticContent(
-  db: DbClient,
-  providerModuleId: string,
-  publishingModuleId?: string,
-): Promise<StaticContentConvergeResult> {
-  const module = db.select().from(modules).where(eq(modules.id, providerModuleId)).get();
-  if (!module) {
-    return { success: false, error: `Provider module '${providerModuleId}' is not installed` };
-  }
-  const generatedPath = join(module.sourcePath, 'generated');
-  // D4 (control-plane-stops-building-modules): the generated project is
-  // ephemeral, so a successful provider deploy deletes it and nothing is
-  // persisted for this converge to read. Render it here, on demand, from the
-  // signed payload plus resolved config — generation is fast and local. A
-  // render failure fails loudly with the deploy-once remedy, same as the old
-  // missing-project refusal did; a tree that predates the converge support is
-  // still refused by the static_releases check below.
-  if (!existsSync(generatedPath)) {
-    const { generateTemplates } = await import('../templates/generator');
-    const rendered = await generateTemplates({
-      moduleId: providerModuleId,
-      modulePath: module.sourcePath,
-      outputPath: generatedPath,
-      db,
-      skipVariableValidation: false,
-    });
-    if (!rendered.success) {
-      return {
-        success: false,
-        error:
-          `public_web provider '${providerModuleId}' has no generated deploy project at ${generatedPath} ` +
-          `and rendering one failed: ${rendered.error ?? 'unknown error'}. ` +
-          `Run \`celilo module deploy ${providerModuleId}\` once, then retry the publish.`,
-      };
-    }
-  }
-
-  const written = await writeStaticContentVars(
-    db,
-    providerModuleId,
-    generatedPath,
-    publishingModuleId,
-  );
-
-  // A generated project that predates the converge role tasks would read the
-  // new vars file and converge nothing. `static_releases` appearing nowhere in
-  // the project is the tell. Generic string check — core names no module.
-  const ansiblePath = join(generatedPath, 'ansible');
-  if (existsSync(ansiblePath) && !ansibleTreeMentions(ansiblePath, 'static_releases')) {
-    return {
-      success: false,
-      error: `The generated project for '${providerModuleId}' predates the static-content converge (its playbook never reads static_releases). Redeploy the provider (\`celilo module deploy ${providerModuleId}\`) to regenerate it, then retry the publish.`,
-    };
-  }
-
-  const { executeAnsible } = await import('./deploy-ansible');
-  // Tag-scoped: the full playbook re-templates the bootstrap Caddyfile, which
-  // would replace the real config the provider's reconcile wrote and reload
-  // caddy into serving nothing. A publish converge touches /srv/www only.
-  const result = await executeAnsible(generatedPath, { tags: ['static_content'] });
-  if (!result.success) {
-    return {
-      success: false,
-      error: `Static-content converge failed on ${providerModuleId}: ${result.error ?? 'unknown error'}`,
-      varsPath: written.varsPath,
-    };
-  }
-  // D4: the converge rendered the tree, used it, and is done with it. The same
-  // no-secrets-at-rest rule the deploy follows applies here; on the failure
-  // paths above the tree stays for inspection.
-  rmSync(generatedPath, { recursive: true, force: true });
-  return { success: true, varsPath: written.varsPath };
-}