@celilo/cli 3.0.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "3.0.0",
+  "version": "4.0.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/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

@@ -23,6 +23,7 @@ import type {
   DnsRegistrarCapability,
   HookLogger,
   PortForwardStore,
+  ProviderConvergeView,
   RouteOps,
   RouteReadView,
   TrustedSourceStore,
@@ -79,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: {
@@ -645,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);
-          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
@@ -666,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}`);
@@ -721,6 +744,68 @@ 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'
+          );
+
+          // 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` };
+          }
+          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, resolveStaticContentRetention } = await import(
+            '../services/provider-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',
@@ -497,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

@@ -0,0 +1,225 @@
+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('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' },
+    ]);
+
+    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);
+  });
+});