@celilo/cli 3.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^5.0.0",
+    "@celilo/capabilities": "^5.1.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.13.0",
     "@celilo/event-bus": "^0.6.0",

package/src/hooks/capability-loader.ts

@@ -23,6 +23,7 @@ import type {
   DnsRegistrarCapability,
   HookLogger,
   PortForwardStore,
+  ProviderConvergeView,
   RouteOps,
   RouteReadView,
   TrustedSourceStore,
@@ -654,7 +655,7 @@ export async function loadCapabilityFunctions(
         // exact "served but silently unreachable" anti-pattern.
         convergeStaticContent: async () => {
           const { convergeStaticContent } = await import('../services/static-content-converge');
-          const result = await convergeStaticContent(db, provider.moduleId);
+          const result = await convergeStaticContent(db, provider.moduleId, consumingModuleId);
           if (!result.success) {
             throw new Error(result.error ?? 'static-content converge failed');
           }
@@ -721,6 +722,53 @@ export async function loadCapabilityFunctions(
       };
       result.web_routes = routeView;
       debugLog(`web_routes: read-only route view injected for provider ${consumingModuleId}`);
+
+      // The provider renders its own config; celilo makes the host match by
+      // running that provider's own role. The lookup is deliberately per
+      // module: core used to plan the whole fleet's sites and throw when one
+      // module had no built site, which stopped every other site converging
+      // (celilo#1383). See openspec/changes/providers-converge-declared-state.
+      const providerModuleId = provider.moduleId;
+      const providerConverge: ProviderConvergeView = {
+        resolveConsumerSite: async (moduleId: string) => {
+          const { resolveModuleStateWebRoot, resolveModuleWebRoot } = await import(
+            '../module/web-root'
+          );
+          const sourceDir = resolveModuleWebRoot(moduleId, db);
+          if (!sourceDir) {
+            return { unavailable: `module '${moduleId}' is not installed` };
+          }
+          if (!existsSync(sourceDir)) {
+            return {
+              unavailable: `no built site at ${sourceDir} — a module that serves a static site ships it at <module root>/site/dist`,
+            };
+          }
+          const stateWebRoot = resolveModuleStateWebRoot(moduleId, db);
+          const overlayDir =
+            stateWebRoot && existsSync(stateWebRoot) ? { overlayDir: stateWebRoot } : {};
+          return { sourceDir, ...overlayDir };
+        },
+        converge: async (artifacts) => {
+          const { convergeProviderConfig } = await import('../services/provider-converge');
+          const { resolveStaticContentRetention } = await import(
+            '../services/static-content-converge'
+          );
+          const result = await convergeProviderConfig(db, providerModuleId, {
+            ...artifacts,
+            // Operator config, resolved here rather than in the provider: the
+            // module never carries the number (design D10 of
+            // capability-owned-tables).
+            retention: resolveStaticContentRetention(db, providerModuleId),
+          });
+          return {
+            success: result.success,
+            ...(result.error ? { error: result.error } : {}),
+            unresolved: result.unresolved,
+          };
+        },
+      };
+      result.provider_converge = providerConverge;
+      debugLog(`provider_converge: injected for provider ${consumingModuleId}`);
     }
   } else {
     debugLog('public_web: not registered in DB, skipping');

package/src/policy/capability-shape-baseline.ts

@@ -143,4 +143,10 @@ export const CAPABILITY_SHAPE_BASELINE: Readonly<Record<string, CapabilityShape>
     requests:
       '[{kind:"interface",members:[{name:"converge",optional:false,type:"Promise<void>"},{name:"withdrawConsumer",optional:false,type:"Promise<void>"}],name:"FirewallProviderView"}]',
   },
+  provider_converge: {
+    version: '1.0.0',
+    hash: '1d828d70433ce4a15a73072883abad0c2acfef92c059bf40432b792722eb7d97',
+    requests:
+      '[{kind:"alias",members:[{name:"_self",optional:false,type:"{\\n    sourceDir: string;\\n    overlayDir?: string;\\n} | {\\n    unavailable: string;\\n}"}],name:"ConsumerSiteResolution"},{kind:"interface",members:[{name:"content",optional:false,type:"string"},{name:"path",optional:false,type:"string"}],name:"ProviderConfigFile"},{kind:"interface",members:[{name:"converge",optional:false,type:"Promise<{\\n    success: boolean;\\n    error?: string;\\n    unresolved: string[];\\n}>"},{name:"resolveConsumerSite",optional:false,type:"Promise<ConsumerSiteResolution>"}],name:"ProviderConvergeView"},{kind:"interface",members:[{name:"contentHash",optional:false,type:"string"},{name:"hostnames",optional:false,type:"string[]"},{name:"moduleId",optional:false,type:"string"},{name:"overlayDir",optional:true,type:"string"},{name:"slug",optional:false,type:"string"},{name:"sourceDir",optional:false,type:"string"}],name:"ProviderSiteRequest"}]',
+  },
 };

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

@@ -99,6 +99,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 4,
     why: 'PERMANENT — a provider VIEW, not a module-provided capability. The name was registered so it stops being invisible to audits (celilo#1007); these references predate that and are framework plumbing, not core branching on a provider',
   },
+  {
+    file: 'apps/celilo/src/hooks/capability-loader.ts',
+    capability: 'provider_converge',
+    count: 2,
+    why: 'PERMANENT — a provider VIEW, not a module-provided capability. Core injects the generic converge every provider renders through; naming it is framework plumbing, not core branching on a provider (providers-converge-declared-state)',
+  },
   {
     file: 'apps/celilo/src/db/schema.ts',
     capability: 'web_routes',
@@ -129,6 +135,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'PERMANENT — a contract declaration with no implementation; this is the package doing its job',
   },
+  {
+    file: 'packages/capabilities/src/capability-contract.ts',
+    capability: 'provider_converge',
+    count: 1,
+    why: 'PERMANENT — a contract declaration with no implementation; this is the package doing its job',
+  },
   {
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'dhcp_server',
@@ -466,6 +478,11 @@ export const SERVICE_FILENAME_BASELINE: readonly ServiceFilenameRow[] = [
     capability: 'cross_module_read',
     why: 'PERMANENT — cross_module_read is a framework privilege, not a module capability',
   },
+  {
+    file: 'apps/celilo/src/services/provider-converge.ts',
+    capability: 'provider_converge',
+    why: 'PERMANENT — provider_converge is a framework-granted view, not a module capability, and this service IS the generic mechanism it grants: it carries what a provider rendered and runs that provider own role. Naming it for one provider is what the scan exists to catch; naming it for the mechanism is the fix the scan asks for (providers-converge-declared-state)',
+  },
   {
     file: 'apps/celilo/src/services/dns-internal-records.ts',
     capability: 'dns_internal',

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

@@ -0,0 +1,209 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { parse as parseYaml } from 'yaml';
+import type { DbClient } from '../db/client';
+import { modules } from '../db/schema';
+import { setupTestDatabaseAt } from '../test-utils/database';
+import { resetTestDbPath } from '../test-utils/db-path';
+import {
+  type ProviderArtifacts,
+  convergeProviderConfig,
+  providerConfigVarsPath,
+  providerConfigVarsYaml,
+  recordUnresolvedConsumers,
+} from './provider-converge';
+
+const HASH = 'a'.repeat(64);
+
+function artifacts(overrides: Partial<ProviderArtifacts> = {}): ProviderArtifacts {
+  return {
+    files: [{ path: '/etc/caddy/Caddyfile', content: 'peterbanka.org {\n\ttls internal\n}\n' }],
+    sites: [
+      {
+        slug: 'peterbanka-org',
+        moduleId: 'peterbanka-org',
+        contentHash: HASH,
+        hostnames: ['peterbanka.org'],
+        sourceDir: '/var/celilo/modules/peterbanka-org/site/dist',
+      },
+    ],
+    unresolved: [],
+    retention: 5,
+    ...overrides,
+  };
+}
+
+describe('providerConfigVarsYaml — the provider renders, celilo carries', () => {
+  it('carries each rendered file so the role can place it verbatim', () => {
+    const vars = parseYaml(providerConfigVarsYaml(artifacts()));
+
+    expect(vars.provider_config_files).toEqual([
+      { path: '/etc/caddy/Caddyfile', content: 'peterbanka.org {\n\ttls internal\n}\n' },
+    ]);
+  });
+
+  it('carries the sites under the variable the static-content role already reads', () => {
+    const vars = parseYaml(providerConfigVarsYaml(artifacts()));
+
+    expect(vars.static_release_retention).toBe(5);
+    expect(vars.static_releases).toEqual([
+      {
+        slug: 'peterbanka-org',
+        content_hash: HASH,
+        hostnames: ['peterbanka.org'],
+        source_dir: '/var/celilo/modules/peterbanka-org/site/dist',
+      },
+    ]);
+  });
+
+  it('omits overlay_dir when there is none, so the role guard reads a clean variable', () => {
+    const withOverlay = artifacts({
+      sites: [
+        { ...artifacts().sites[0], overlayDir: '/var/celilo/modules/peterbanka-org/state/site' },
+      ],
+    });
+
+    expect(parseYaml(providerConfigVarsYaml(artifacts())).static_releases[0].overlay_dir).toBe(
+      undefined,
+    );
+    expect(parseYaml(providerConfigVarsYaml(withOverlay)).static_releases[0].overlay_dir).toBe(
+      '/var/celilo/modules/peterbanka-org/state/site',
+    );
+  });
+
+  it("one consumer the provider could not render does not remove another's site", () => {
+    const partial = artifacts({
+      unresolved: [
+        { moduleId: 'byoi', reason: 'no built site at /var/celilo/modules/byoi/site/dist' },
+      ],
+    });
+
+    const vars = parseYaml(providerConfigVarsYaml(partial));
+
+    expect(vars.static_releases.map((r: { slug: string }) => r.slug)).toEqual(['peterbanka-org']);
+  });
+
+  it('is deterministic, so an unchanged desired state writes an unchanged file', () => {
+    expect(providerConfigVarsYaml(artifacts())).toBe(providerConfigVarsYaml(artifacts()));
+  });
+});
+
+describe('providerConfigVarsPath — lands in the generated inventory', () => {
+  it('writes into the auto-loaded group_vars directory', () => {
+    expect(providerConfigVarsPath('/tmp/generated')).toBe(
+      '/tmp/generated/ansible/inventory/group_vars/all/provider_config.yml',
+    );
+  });
+});
+
+describe('recordUnresolvedConsumers — the failure belongs to the consumer', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'provider-converge-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabaseAt(dbPath);
+
+    for (const id of ['caddy', 'byoi', 'peterbanka-org']) {
+      db.insert(modules)
+        .values({
+          id,
+          name: id,
+          version: '1.0.0',
+          manifestData: {},
+          sourcePath: join(dir, 'modules', id),
+          state: 'VERIFIED',
+        })
+        .onConflictDoNothing()
+        .run();
+    }
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    resetTestDbPath();
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  function stateOf(id: string) {
+    return db.select().from(modules).where(eq(modules.id, id)).get();
+  }
+
+  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' },
+    ]);
+
+    const byoi = stateOf('byoi');
+    expect(byoi?.state).toBe('ERROR');
+    expect(byoi?.errorMessage).toContain('no built site');
+  });
+
+  it('leaves the provider and every other consumer alone', () => {
+    recordUnresolvedConsumers(db, 'caddy', [{ moduleId: 'byoi', reason: 'no built site' }]);
+
+    expect(stateOf('caddy')?.state).toBe('VERIFIED');
+    expect(stateOf('peterbanka-org')?.state).toBe('VERIFIED');
+  });
+
+  it('returns the modules it recorded, so the converge can report them', () => {
+    const recorded = recordUnresolvedConsumers(db, 'caddy', [
+      { moduleId: 'byoi', reason: 'no built site' },
+    ]);
+
+    expect(recorded).toEqual(['byoi']);
+  });
+
+  it('records the consumer even when the converge cannot run at all', async () => {
+    const result = await convergeProviderConfig(db, 'not-installed-provider', {
+      files: [],
+      sites: [],
+      unresolved: [{ moduleId: 'byoi', reason: 'no built site' }],
+      retention: 5,
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('not installed');
+    // The consumer's fault is recorded whatever happens to the provider run:
+    // the two failures are unrelated and the operator needs both.
+    expect(result.unresolved).toEqual(['byoi']);
+    expect(stateOf('byoi')?.state).toBe('ERROR');
+  });
+
+  it('refuses a generated project that predates the converge, naming the redeploy', async () => {
+    const generated = join(dir, 'modules', 'caddy', 'generated', 'ansible', 'roles');
+    mkdirSync(generated, { recursive: true });
+    writeFileSync(join(generated, 'main.yml'), '- name: does not read the new vars\n', 'utf-8');
+
+    const result = await convergeProviderConfig(db, 'caddy', artifacts());
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('predates the provider converge');
+    expect(result.error).toContain('celilo module deploy caddy');
+    // Nothing was written: the guard scans the tree for the variable name, and
+    // the vars file would land inside that tree carrying it. Writing first
+    // makes the guard find its own output and pass forever (celilo#1248).
+    expect(result.varsPath).toBe(undefined);
+    expect(existsSync(providerConfigVarsPath(join(dir, 'modules', 'caddy', 'generated')))).toBe(
+      false,
+    );
+  });
+
+  it('ignores a module that is not installed rather than inventing a row', () => {
+    const recorded = recordUnresolvedConsumers(db, 'caddy', [
+      { moduleId: 'never-installed', reason: 'no built site' },
+    ]);
+
+    expect(recorded).toEqual([]);
+    expect(stateOf('never-installed')).toBe(undefined);
+  });
+});

package/src/services/provider-converge.ts

@@ -0,0 +1,241 @@
+/**
+ * The provider converge (openspec/changes/providers-converge-declared-state).
+ *
+ * A provider renders its own config from the rows it declares, and celilo makes
+ * the host match by running that provider's own Ansible role. One writer on the
+ * box, one path from declared state to a running config.
+ *
+ * Generalised from `static-content-converge.ts`, which already does this for
+ * static site content: desired state into the provider's generated inventory,
+ * then a tag-scoped `executeAnsible`. The difference is who decides what the
+ * desired state is. There, core walks every route row in the fleet and throws
+ * when any one module's site is missing (celilo#1383 — two out-of-tree modules
+ * with no `site/dist` made the public ingress undeployable). Here the provider
+ * hands over what it rendered, and a consumer it could not render is recorded
+ * against that consumer.
+ */
+
+import { existsSync, rmSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { 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';
+
+/** One file the provider wants on its host, rendered by the provider. */
+export interface ProviderConfigFile {
+  /** Absolute path on the provider host. */
+  path: string;
+  /** The rendered contents. */
+  content: string;
+}
+
+/** A consumer's site the provider host must carry. */
+export interface ProviderSite {
+  slug: string;
+  moduleId: string;
+  contentHash: string;
+  hostnames: string[];
+  sourceDir: string;
+  overlayDir?: string;
+}
+
+/** A consumer the provider could not render, and why. */
+export interface UnresolvedConsumer {
+  moduleId: string;
+  reason: string;
+}
+
+/** Everything the provider rendered for one converge. */
+export interface ProviderArtifacts {
+  files: ProviderConfigFile[];
+  sites: ProviderSite[];
+  unresolved: UnresolvedConsumer[];
+  retention: number;
+}
+
+/**
+ * Where the provider's desired state lands inside its generated project.
+ *
+ * `group_vars/all/` is the existing auto-load directory — the same one
+ * `static_content.yml` uses — so no playbook change is needed to read it.
+ */
+export function providerConfigVarsPath(generatedPath: string): string {
+  return join(generatedPath, 'ansible', 'inventory', 'group_vars', 'all', 'provider_config.yml');
+}
+
+/**
+ * Render the vars file. Presentation function (Rule 10.1) — deterministic YAML,
+ * so an unchanged desired state writes a byte-identical file and the role's
+ * config task reports no change.
+ *
+ * `static_releases` keeps its name: the role tasks that converge `/srv/www`
+ * already read it, and renaming a working variable to match a new writer would
+ * be churn with a live-site failure mode.
+ */
+export function providerConfigVarsYaml(artifacts: ProviderArtifacts): string {
+  const vars = {
+    provider_config_files: artifacts.files.map((file) => ({
+      path: file.path,
+      content: file.content,
+    })),
+    static_release_retention: artifacts.retention,
+    static_releases: artifacts.sites.map((site) => ({
+      slug: site.slug,
+      content_hash: site.contentHash,
+      hostnames: site.hostnames,
+      source_dir: site.sourceDir,
+      // Absent when there is no overlay, so the role's `when:` guard reads a
+      // clean variable rather than an empty string a copy task would choke on.
+      ...(site.overlayDir ? { overlay_dir: site.overlayDir } : {}),
+    })),
+  };
+  const header =
+    '# Desired provider state, generated by celilo (providers-converge-declared-state).\n' +
+    '# Hand edits are overwritten by the next converge.\n';
+  return `${header}${stringifyYaml(vars, { lineWidth: 0, sortMapEntries: true })}`;
+}
+
+/**
+ * Record each consumer the provider could not render, against that consumer.
+ *
+ * The provider is not at fault for a consumer that ships no built site, and the
+ * fleet is not at fault either: before this, one such module threw in core's
+ * plan and no site converged at all (celilo#1383). The state has to be honest
+ * about which module is broken (celilo#1363), so the row says ERROR and carries
+ * the reason the provider gave.
+ *
+ * A module that is not installed is skipped rather than inserted: celilo cannot
+ * record a state for something it does not have.
+ */
+export function recordUnresolvedConsumers(
+  db: DbClient,
+  providerModuleId: string,
+  unresolved: UnresolvedConsumer[],
+): string[] {
+  const recorded: string[] = [];
+
+  for (const consumer of unresolved) {
+    const existing = db.select().from(modules).where(eq(modules.id, consumer.moduleId)).get();
+    if (!existing) continue;
+
+    db.update(modules)
+      .set({
+        state: 'ERROR',
+        errorMessage: `'${providerModuleId}' could not serve this module: ${consumer.reason}`,
+        updatedAt: new Date(),
+      })
+      .where(eq(modules.id, consumer.moduleId))
+      .run();
+    recorded.push(consumer.moduleId);
+  }
+
+  return recorded;
+}
+
+/** What one converge did, for the caller to report. */
+export interface ProviderConvergeResult {
+  success: boolean;
+  error?: string;
+  /** The written vars file, absolute — for logs and tests. */
+  varsPath?: string;
+  /** Consumers recorded in ERROR because the provider could not render them. */
+  unresolved: string[];
+}
+
+/**
+ * The tags a converge runs. The provider's whole playbook re-runs package
+ * installation and service enablement, which a route change has no business
+ * touching; these two cover the file placement and `/srv/www`.
+ */
+const CONVERGE_TAGS = ['provider_config', 'static_content'];
+
+/**
+ * Plan, write, converge: make the provider's host match what the provider
+ * rendered.
+ *
+ * `generatedPath` is rendered on demand when it is missing, because a
+ * successful deploy deletes the generated tree by design (D4 of
+ * control-plane-stops-building-modules) and generation is fast and local.
+ */
+export async function convergeProviderConfig(
+  db: DbClient,
+  providerModuleId: string,
+  artifacts: ProviderArtifacts,
+  options?: { tags?: string[] },
+): Promise<ProviderConvergeResult> {
+  const unresolved = recordUnresolvedConsumers(db, providerModuleId, artifacts.unresolved);
+
+  const module = db.select().from(modules).where(eq(modules.id, providerModuleId)).get();
+  if (!module) {
+    return {
+      success: false,
+      error: `Provider module '${providerModuleId}' is not installed`,
+      unresolved,
+    };
+  }
+
+  const generatedPath = join(module.sourcePath, 'generated');
+  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:
+          `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.`,
+        unresolved,
+      };
+    }
+  }
+
+  // A generated project that predates the converge role tasks would read the
+  // new vars file and place nothing, so the desired state would be written and
+  // silently never applied. The variable appearing nowhere in the tree is the
+  // tell. Generic string check — core names no module.
+  //
+  // CHECKED BEFORE THE VARS ARE WRITTEN, and the order is the whole point: the
+  // vars file lands inside the tree being scanned and contains the variable
+  // name, so a guard that runs after the write finds its own output and can
+  // never fail. That is celilo#1248's bug — a check that cannot reach its
+  // subject — reintroduced by write order rather than by path.
+  const ansiblePath = join(generatedPath, 'ansible');
+  if (existsSync(ansiblePath) && !ansibleTreeMentions(ansiblePath, 'provider_config_files')) {
+    return {
+      success: false,
+      error: `The generated project for '${providerModuleId}' predates the provider converge (its role never reads provider_config_files). Redeploy the provider (\`celilo module deploy ${providerModuleId}\`) to regenerate it, then retry.`,
+      unresolved,
+    };
+  }
+
+  const varsPath = providerConfigVarsPath(generatedPath);
+  await mkdir(join(varsPath, '..'), { recursive: true });
+  await writeFile(varsPath, providerConfigVarsYaml(artifacts), 'utf-8');
+
+  const { executeAnsible } = await import('./deploy-ansible');
+  const result = await executeAnsible(generatedPath, { tags: options?.tags ?? CONVERGE_TAGS });
+  if (!result.success) {
+    return {
+      success: false,
+      error: `Provider converge failed on ${providerModuleId}: ${result.error ?? 'unknown error'}`,
+      varsPath,
+      unresolved,
+    };
+  }
+
+  // The converge rendered the tree, used it, and is done with it: desired state
+  // is rebuilt from the declared rows every time and never kept as a record
+  // (design D5). On the failure paths above the tree stays for inspection.
+  rmSync(generatedPath, { recursive: true, force: true });
+  return { success: true, varsPath, unresolved };
+}

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

@@ -152,6 +152,45 @@ describe('planStaticContent — the declared release set (D10 task 4.1)', () =>
 
     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', () => {

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

@@ -32,6 +32,7 @@ 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 {
@@ -133,7 +134,7 @@ export function resolveStaticContentRetention(db: DbClient, providerModuleId: st
  * cannot express, so it fails here with both rows named rather than silently
  * converging one of them.
  */
-export function planStaticContent(db: DbClient): StaticRelease[] {
+export function planStaticContent(db: DbClient, publishingModuleId?: string): StaticRelease[] {
   const rows = db
     .select()
     .from(webRoutes)
@@ -147,6 +148,14 @@ export function planStaticContent(db: DbClient): StaticRelease[] {
     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))];
@@ -157,6 +166,7 @@ export function planStaticContent(db: DbClient): StaticRelease[] {
     }
     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) {
@@ -201,9 +211,13 @@ export function planStaticContent(db: DbClient): StaticRelease[] {
  * 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): StaticContentPlan {
+export function buildStaticContentPlan(
+  db: DbClient,
+  providerModuleId: string,
+  publishingModuleId?: string,
+): StaticContentPlan {
   return {
-    releases: planStaticContent(db),
+    releases: planStaticContent(db, publishingModuleId),
     retention: resolveStaticContentRetention(db, providerModuleId),
   };
 }
@@ -246,10 +260,11 @@ export async function writeStaticContentVars(
   db: DbClient,
   providerModuleId: string,
   generatedPath: string,
+  publishingModuleId?: string,
 ): Promise<StaticContentConvergeResult> {
   const varsPath = staticContentVarsPath(generatedPath);
 
-  const plan = buildStaticContentPlan(db, providerModuleId);
+  const plan = buildStaticContentPlan(db, providerModuleId, publishingModuleId);
 
   await mkdir(join(varsPath, '..'), { recursive: true });
   await writeFile(varsPath, staticContentVarsYaml(plan), 'utf-8');
@@ -303,6 +318,7 @@ export function ansibleTreeMentions(dir: string, needle: string): boolean {
 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) {
@@ -336,7 +352,12 @@ export async function convergeStaticContent(
     }
   }
 
-  const written = await writeStaticContentVars(db, providerModuleId, generatedPath);
+  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