@celilo/cli 4.0.0 → 4.1.0

package/src/services/machine-interface-zones.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test';
+import type { NetworkZone } from '../db/schema';
+import {
+  applyReclassification,
+  diffInterfaceZones,
+  explainMissingZoneInterface,
+} from './machine-interface-zones';
+
+/** The zone model as it stands today: 10.0.120.0/24 is secure-mgmt. */
+const detect = async (ip: string): Promise<NetworkZone | 'unknown'> => {
+  if (ip.startsWith('10.0.120.')) return 'secure-mgmt';
+  if (ip.startsWith('10.0.10.')) return 'dmz';
+  return 'unknown';
+};
+
+/**
+ * celilo-mgr as celilo#1382 found it: added before `secure-mgmt` existed,
+ * while the detector labelled unmatched subnets `external`.
+ */
+const celiloMgr = [{ name: 'eth0', ipAddress: '10.0.120.10', zone: 'external' }];
+
+describe('diffInterfaceZones', () => {
+  test('reports a label the current zone model disagrees with', async () => {
+    expect(await diffInterfaceZones(celiloMgr, detect)).toEqual([
+      { name: 'eth0', ipAddress: '10.0.120.10', from: 'external', to: 'secure-mgmt' },
+    ]);
+  });
+
+  test('reports nothing when the stored labels already agree', async () => {
+    const current = [{ name: 'eth0', ipAddress: '10.0.120.10', zone: 'secure-mgmt' }];
+    expect(await diffInterfaceZones(current, detect)).toEqual([]);
+  });
+
+  test('reports only the interfaces that changed', async () => {
+    const mixed = [
+      { name: 'eth0', ipAddress: '10.0.120.10', zone: 'external' },
+      { name: 'eth1', ipAddress: '10.0.10.5', zone: 'dmz' },
+    ];
+    const changes = await diffInterfaceZones(mixed, detect);
+    expect(changes.map((c) => c.name)).toEqual(['eth0']);
+  });
+});
+
+describe('applyReclassification', () => {
+  test('writes the new label and leaves the input untouched', async () => {
+    const changes = await diffInterfaceZones(celiloMgr, detect);
+    expect(applyReclassification(celiloMgr, changes)).toEqual([
+      { name: 'eth0', ipAddress: '10.0.120.10', zone: 'secure-mgmt' },
+    ]);
+    expect(celiloMgr[0].zone).toBe('external');
+  });
+});
+
+describe('explainMissingZoneInterface', () => {
+  test('says MISLABELLED, and names the interface, when one would match', async () => {
+    const changes = await diffInterfaceZones(celiloMgr, detect);
+    const message = explainMissingZoneInterface(celiloMgr, 'secure-mgmt', changes);
+    expect(message).toContain('MISLABELLED');
+    expect(message).toContain('eth0');
+    expect(message).toContain('10.0.120.10');
+    expect(message).toContain('machine reclassify');
+  });
+
+  test('says the interface is absent when no relabel would produce one', async () => {
+    const dmzOnly = [{ name: 'eth0', ipAddress: '10.0.10.5', zone: 'dmz' }];
+    const changes = await diffInterfaceZones(dmzOnly, detect);
+    const message = explainMissingZoneInterface(dmzOnly, 'secure-mgmt', changes);
+    expect(message).toContain("has no interface in zone 'secure-mgmt'");
+    expect(message).not.toContain('MISLABELLED');
+    // Names what it DOES hold, so the operator can see why.
+    expect(message).toContain('10.0.10.5');
+  });
+});

package/src/services/machine-interface-zones.ts

@@ -0,0 +1,101 @@
+/**
+ * Re-classify a machine's STORED interface zone labels.
+ *
+ * Interface zones are decided once, at `machine add`, and never revisited
+ * (`machine-add.ts` / `machine-detector.ts` are the only writers). That is fine
+ * until the zone model itself changes — a new zone is added, or a subnet is
+ * declared for one that had none. Every machine added before that change keeps
+ * the label the old model produced, and nothing anywhere says so.
+ *
+ * Measured (celilo#1382): celilo-mgr was added before `secure-mgmt` existed,
+ * while the detector labelled unmatched subnets `external`. Its eth0
+ * (10.0.120.10) was stored as zone `external`. `resolveMachineIdentityAddress`
+ * matches on the stored label, so celilo-mgmt's upgrade failed with "no
+ * non-loopback interface in zone 'secure-mgmt'" — the interface existed, it was
+ * mislabelled. The fix was a hand-edit of the live DB, which is the shape of
+ * problem this module exists to remove.
+ *
+ * The diff is pure over an injected detector so it is testable without a DB.
+ */
+
+import type { NetworkZone } from '../db/schema';
+
+/**
+ * A stored interface row. Deliberately looser than `NetworkInterface`: the
+ * `machines.interfaces` column types `zone` as a plain string, and a stale
+ * label is exactly the case where it may not be a current `NetworkZone`.
+ */
+export interface StoredInterface {
+  name: string;
+  ipAddress: string;
+  zone: string;
+}
+
+/** One interface whose stored label disagrees with the current zone model. */
+export interface ZoneReclassification {
+  name: string;
+  ipAddress: string;
+  /** The label on disk. */
+  from: string;
+  /** What the current zone model says. */
+  to: NetworkZone | 'unknown';
+}
+
+export type ZoneDetector = (ip: string) => Promise<NetworkZone | 'unknown'>;
+
+/**
+ * Which of `interfaces` the current zone model labels differently.
+ *
+ * Returns only the CHANGES: an empty array means the stored labels already
+ * agree with the model, which is what an operator needs to hear.
+ */
+export async function diffInterfaceZones(
+  interfaces: readonly StoredInterface[],
+  detect: ZoneDetector,
+): Promise<ZoneReclassification[]> {
+  const changes: ZoneReclassification[] = [];
+  for (const iface of interfaces) {
+    const to = await detect(iface.ipAddress);
+    if (to !== iface.zone) {
+      changes.push({ name: iface.name, ipAddress: iface.ipAddress, from: iface.zone, to });
+    }
+  }
+  return changes;
+}
+
+/** `interfaces` with the changes applied. Does not mutate the input. */
+export function applyReclassification(
+  interfaces: readonly StoredInterface[],
+  changes: readonly ZoneReclassification[],
+): StoredInterface[] {
+  const byName = new Map(changes.map((c) => [c.name, c]));
+  return interfaces.map((iface) => {
+    const change = byName.get(iface.name);
+    return change ? { ...iface, zone: change.to } : { ...iface };
+  });
+}
+
+/**
+ * Why `resolveMachineIdentityAddress` found nothing for `zone`.
+ *
+ * Distinguishes the two cases that previously read identically. "No interface
+ * in zone X" is true of a machine that genuinely has none AND of one whose
+ * interface is sitting right there under a stale label — and the second is the
+ * common case after a zone-model change, where the remediation is a
+ * re-classification rather than new hardware.
+ */
+export function explainMissingZoneInterface(
+  interfaces: readonly StoredInterface[],
+  zone: NetworkZone,
+  changes: readonly ZoneReclassification[],
+): string {
+  const wouldMatch = changes.filter((c) => c.to === zone);
+  if (wouldMatch.length === 0) {
+    const held = interfaces.map((i) => `${i.name} (${i.ipAddress}, zone ${i.zone})`).join(', ');
+    return `has no interface in zone '${zone}'${held ? ` — it holds ${held}` : ' (no interfaces recorded)'}`;
+  }
+  const named = wouldMatch
+    .map((c) => `${c.name} (${c.ipAddress}, stored as '${c.from}')`)
+    .join(', ');
+  return `has an interface in zone '${zone}' that is MISLABELLED: ${named}. The stored label predates the current zone model. Fix it with: celilo machine reclassify <hostname> --apply`;
+}

package/src/services/module-deploy.stale-provider-guard.test.ts

@@ -0,0 +1,98 @@
+import { 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 type { ModuleManifest } from '../manifest/schema';
+import { staleProviderProjectRefusal } from './module-deploy';
+import { providerConfigVarsPath } from './provider-converge';
+
+// The converge copy of this guard has had a refusal test since celilo#1387
+// (provider-converge.test.ts). The module-deploy copy had none, so nobody had
+// watched it fail — and this guard has already failed in both directions:
+// celilo#1248 refused every provider, celilo#1387 read its own output and
+// refused nothing. Both silent. celilo#1408.
+
+function manifest(caps: string[]): ModuleManifest {
+  return {
+    provides: { capabilities: caps.map((name) => ({ name })) },
+  } as unknown as ModuleManifest;
+}
+
+async function withGenerated(run: (generatedPath: string) => Promise<void>) {
+  const dir = mkdtempSync(join(tmpdir(), 'celilo-stale-guard-'));
+  try {
+    await run(join(dir, 'generated'));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function plantStaleTree(generatedPath: string) {
+  const roles = join(generatedPath, 'ansible', 'roles');
+  mkdirSync(roles, { recursive: true });
+  writeFileSync(join(roles, 'main.yml'), '- name: does not read the new vars\n', 'utf-8');
+}
+
+describe('staleProviderProjectRefusal — the deploy-side guard, watched failing', () => {
+  it('refuses a public_web provider whose generated role predates the converge', async () => {
+    await withGenerated(async (generatedPath) => {
+      plantStaleTree(generatedPath);
+
+      const error = await staleProviderProjectRefusal(
+        'caddy',
+        manifest(['public_web']),
+        generatedPath,
+      );
+
+      expect(error).toContain('predates the provider converge');
+      expect(error).toContain('celilo module upgrade caddy');
+    });
+  });
+
+  it('does not reach its own output: nothing is written, so the scan cannot self-satisfy', async () => {
+    await withGenerated(async (generatedPath) => {
+      plantStaleTree(generatedPath);
+
+      await staleProviderProjectRefusal('caddy', manifest(['public_web']), generatedPath);
+
+      // celilo#1387's bug was write-order: the vars file lands inside the
+      // scanned tree and carries the needle, so a guard that runs after the
+      // write always passes. This guard writes nothing at all.
+      expect(existsSync(providerConfigVarsPath(generatedPath))).toBe(false);
+    });
+  });
+
+  it('passes a tree whose role reads provider_config_files', async () => {
+    await withGenerated(async (generatedPath) => {
+      const roles = join(generatedPath, 'ansible', 'roles');
+      mkdirSync(roles, { recursive: true });
+      writeFileSync(
+        join(roles, 'main.yml'),
+        '- name: place\n  loop: "{{ provider_config_files }}"\n',
+        'utf-8',
+      );
+
+      expect(
+        await staleProviderProjectRefusal('caddy', manifest(['public_web']), generatedPath),
+      ).toBe(undefined);
+    });
+  });
+
+  it('leaves a module that provides no public_web alone, stale tree or not', async () => {
+    await withGenerated(async (generatedPath) => {
+      plantStaleTree(generatedPath);
+
+      expect(
+        await staleProviderProjectRefusal('homebridge', manifest(['dns_internal']), generatedPath),
+      ).toBe(undefined);
+    });
+  });
+
+  it('passes when there is no generated ansible tree to judge', async () => {
+    await withGenerated(async (generatedPath) => {
+      expect(
+        await staleProviderProjectRefusal('caddy', manifest(['public_web']), generatedPath),
+      ).toBe(undefined);
+    });
+  });
+});

package/src/services/module-deploy.ts

@@ -628,6 +628,34 @@ export async function repointDnsPrimaryForProvider(
   );
 }
 
+/**
+ * The refusal above, as its own function so it can be watched failing.
+ *
+ * Returns the operator-facing error when `moduleId` is a public_web provider
+ * whose GENERATED project predates the converge role tasks, and undefined
+ * otherwise. Extracted for celilo#1408: the deploy path that calls it is long
+ * enough that no test had ever reached it, and this guard has already failed in
+ * both directions elsewhere (celilo#1248 refused everything, celilo#1387 read
+ * its own output and refused nothing). Both are silent. Rule 7.6.
+ *
+ * It only READS the tree — nothing is written before or by it, which is what
+ * keeps it from finding its own output the way #1387's copy did.
+ */
+export async function staleProviderProjectRefusal(
+  moduleId: string,
+  manifest: ModuleManifest,
+  generatedPath: string,
+): Promise<string | undefined> {
+  if (!manifest.provides?.capabilities?.some((cap) => cap.name === 'public_web')) return undefined;
+
+  const { ansibleTreeMentions } = await import('./provider-converge');
+  const ansiblePath = join(generatedPath, 'ansible');
+  if (!existsSync(ansiblePath)) return undefined;
+  if (ansibleTreeMentions(ansiblePath, 'provider_config_files')) return undefined;
+
+  return `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.`;
+}
+
 async function deployModuleImpl(
   moduleId: string,
   db: DbClient,
@@ -1491,16 +1519,9 @@ async function deployModuleImpl(
     // 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 { 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,
-        };
-      }
+    const staleRefusal = await staleProviderProjectRefusal(moduleId, manifest, generatedPath);
+    if (staleRefusal) {
+      return { success: false, error: staleRefusal, phases };
     }
 
     try {

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

@@ -21,6 +21,9 @@ function manifest(input: { requires?: string[]; optional?: string[] }): ModuleMa
   } as unknown as ModuleManifest;
 }
 
+/** What the arriving provider registered. Consumers in these tests declare 1.0.0. */
+const provides = (...names: string[]) => names.map((name) => ({ name, version: '1.0.0' }));
+
 const consumer = (
   moduleId: string,
   caps: { requires?: string[]; optional?: string[] },
@@ -29,14 +32,10 @@ const consumer = (
 
 describe('planProviderBackfill', () => {
   it('re-runs consumers of the capabilities the arriving provider actually provides', () => {
-    const plan = planProviderBackfill(
-      'iptables',
-      ['firewall'],
-      [
-        consumer('caddy', { requires: ['firewall'] }),
-        consumer('forgejo', { requires: ['public_web'] }),
-      ],
-    );
+    const plan = planProviderBackfill('iptables', provides('firewall'), [
+      consumer('caddy', { requires: ['firewall'] }),
+      consumer('forgejo', { requires: ['public_web'] }),
+    ]);
 
     expect(plan.map((t) => t.consumerId)).toEqual(['caddy']);
   });
@@ -48,11 +47,9 @@ describe('planProviderBackfill', () => {
    * provider appears. Counting only `requires` would leave it unregistered.
    */
   it('includes an OPTIONAL dependent, not only a required one', () => {
-    const plan = planProviderBackfill(
-      'technitium',
-      ['dns_internal'],
-      [consumer('caddy-internal', { optional: ['dns_internal'] })],
-    );
+    const plan = planProviderBackfill('technitium', provides('dns_internal'), [
+      consumer('caddy-internal', { optional: ['dns_internal'] }),
+    ]);
 
     expect(plan.map((t) => t.consumerId)).toEqual(['caddy-internal']);
     expect(plan[0]?.skip).toBeUndefined();
@@ -61,14 +58,10 @@ describe('planProviderBackfill', () => {
   it('never treats the provider as its own consumer', () => {
     // A module that both provides and requires a capability would otherwise
     // have its on_install run a second time inside the deploy that just ran it.
-    const plan = planProviderBackfill(
-      'caddy',
-      ['public_web'],
-      [
-        consumer('caddy', { requires: ['public_web', 'firewall'] }),
-        consumer('forgejo', { requires: ['public_web'] }),
-      ],
-    );
+    const plan = planProviderBackfill('caddy', provides('public_web'), [
+      consumer('caddy', { requires: ['public_web', 'firewall'] }),
+      consumer('forgejo', { requires: ['public_web'] }),
+    ]);
 
     expect(plan.map((t) => t.consumerId)).toEqual(['forgejo']);
   });
@@ -76,52 +69,75 @@ describe('planProviderBackfill', () => {
   it('skips a consumer in a pre-deploy state, and says so rather than dropping it', () => {
     // Capabilities are registered at IMPORT, not deploy, so an imported module
     // has never resolved anything and has nothing to re-register.
-    const plan = planProviderBackfill(
-      'iptables',
-      ['firewall'],
-      [
-        consumer('imported', { requires: ['firewall'] }, 'IMPORTED'),
-        consumer('validated', { requires: ['firewall'] }, 'VALIDATED'),
-        consumer('configured', { requires: ['firewall'] }, 'CONFIGURED'),
-      ],
-    );
+    const plan = planProviderBackfill('iptables', provides('firewall'), [
+      consumer('imported', { requires: ['firewall'] }, 'IMPORTED'),
+      consumer('validated', { requires: ['firewall'] }, 'VALIDATED'),
+      consumer('configured', { requires: ['firewall'] }, 'CONFIGURED'),
+    ]);
 
     expect(plan.map((t) => t.skip)).toEqual(['not-deployed', 'not-deployed', 'not-deployed']);
   });
 
   it('skips a PAUSED consumer separately from a never-deployed one', () => {
-    const plan = planProviderBackfill(
-      'iptables',
-      ['firewall'],
-      [consumer('paused', { requires: ['firewall'] }, 'PAUSED')],
-    );
+    const plan = planProviderBackfill('iptables', provides('firewall'), [
+      consumer('paused', { requires: ['firewall'] }, 'PAUSED'),
+    ]);
 
     expect(plan[0]?.skip).toBe('paused');
   });
 
   it('names every capability the consumer takes from this provider, once', () => {
-    const plan = planProviderBackfill(
-      'greenwave',
-      ['firewall', 'dhcp_server'],
-      [consumer('caddy', { requires: ['firewall'], optional: ['dhcp_server'] })],
-    );
+    const plan = planProviderBackfill('greenwave', provides('firewall', 'dhcp_server'), [
+      consumer('caddy', { requires: ['firewall'], optional: ['dhcp_server'] }),
+    ]);
 
     expect(plan).toHaveLength(1);
     expect(plan[0]?.capabilityNames).toEqual(['dhcp_server', 'firewall']);
   });
 
+  /**
+   * celilo#1384. An OPTIONAL consumer built against external_web@1.0.0 was
+   * re-run against a provider serving 2.0.0; the hook failed inside
+   * `on_install`, which is only a warning, so nothing published and no surface
+   * said so. A consumer on another major is skipped and REPORTED instead.
+   */
+  it('skips a consumer whose declared version the arriving provider no longer serves', () => {
+    const plan = planProviderBackfill(
+      'generic-cpanel',
+      [{ name: 'external_web', version: '2.0.0' }],
+      [
+        consumer('tango-nexus', { optional: ['external_web'] }),
+        consumer('required-too', { requires: ['external_web'] }),
+      ],
+    );
+
+    expect(plan.map((t) => [t.consumerId, t.skip])).toEqual([
+      ['required-too', 'incompatible'],
+      ['tango-nexus', 'incompatible'],
+    ]);
+  });
+
+  it('re-runs a consumer the provider is merely NEWER in minor than', () => {
+    const plan = planProviderBackfill(
+      'generic-cpanel',
+      [{ name: 'external_web', version: '1.4.0' }],
+      [consumer('tango-nexus', { optional: ['external_web'] })],
+    );
+
+    expect(plan[0]?.skip).toBeUndefined();
+  });
+
   it('is empty for a module that provides nothing', () => {
     expect(
-      planProviderBackfill('forgejo', [], [consumer('caddy', { requires: ['firewall'] })]),
+      planProviderBackfill('forgejo', provides(), [consumer('caddy', { requires: ['firewall'] })]),
     ).toEqual([]);
   });
 
   it('is ordered by consumer id, so a failure is reproducible', () => {
-    const plan = planProviderBackfill(
-      'iptables',
-      ['firewall'],
-      [consumer('zulu', { requires: ['firewall'] }), consumer('alpha', { requires: ['firewall'] })],
-    );
+    const plan = planProviderBackfill('iptables', provides('firewall'), [
+      consumer('zulu', { requires: ['firewall'] }),
+      consumer('alpha', { requires: ['firewall'] }),
+    ]);
 
     expect(plan.map((t) => t.consumerId)).toEqual(['alpha', 'zulu']);
   });

package/src/services/provider-arrival.ts

@@ -27,6 +27,7 @@
  * happened".
  */
 
+import { compareConsumerToProvider } from '@celilo/capabilities';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { capabilities, modules } from '../db/schema';
@@ -36,7 +37,13 @@ import type { HookLogger } from '../hooks/types';
 import { type ModuleManifest, ModuleManifestSchema } from '../manifest/schema';
 import { PRE_DEPLOY_STATES } from './consumer-cleanup';
 
-export type BackfillSkipReason = 'paused' | 'not-deployed';
+export type BackfillSkipReason = 'paused' | 'not-deployed' | 'incompatible';
+
+/** A capability as the arriving provider registered it. */
+export interface ProvidedCapability {
+  name: string;
+  version: string;
+}
 
 export interface BackfillTarget {
   /** The consumer module to re-run. */
@@ -70,23 +77,42 @@ export interface ConsumerCandidate {
  */
 export function planProviderBackfill(
   provider: string,
-  providedCapabilities: Iterable<string>,
+  providedCapabilities: Iterable<ProvidedCapability>,
   candidates: ConsumerCandidate[],
 ): BackfillTarget[] {
-  const provided = new Set(providedCapabilities);
+  const provided = new Map([...providedCapabilities].map((c) => [c.name, c.version]));
   if (provided.size === 0) return [];
 
   const targets: BackfillTarget[] = [];
   for (const candidate of candidates) {
     if (candidate.moduleId === provider) continue;
 
-    const consumed = new Set([
-      ...(candidate.manifest.requires?.capabilities ?? []).map((c) => c.name),
-      ...(candidate.manifest.optional?.capabilities ?? []).map((c) => c.name),
-    ]);
-    const capabilityNames = [...consumed].filter((name) => provided.has(name)).sort();
+    const consumed = new Map<string, string>();
+    for (const c of [
+      ...(candidate.manifest.optional?.capabilities ?? []),
+      ...(candidate.manifest.requires?.capabilities ?? []),
+    ]) {
+      consumed.set(c.name, c.version);
+    }
+    const capabilityNames = [...consumed.keys()].filter((name) => provided.has(name)).sort();
     if (capabilityNames.length === 0) continue;
 
+    // The consumer was built against a contract the arriving provider no
+    // longer speaks. Re-running its `on_install` would call methods that are
+    // gone (celilo#1384: tango-nexus 0.8.0's optional external_web@1.0.0 was
+    // re-run against generic-cpanel's 2.0.0 and failed inside the hook, which
+    // is only a warning — so nothing published and nothing said so).
+    if (
+      capabilityNames.some(
+        (name) =>
+          // biome-ignore lint/style/noNonNullAssertion: name came from `consumed`/`provided`.
+          !compareConsumerToProvider(consumed.get(name)!, provided.get(name)!).compatible,
+      )
+    ) {
+      targets.push({ consumerId: candidate.moduleId, capabilityNames, skip: 'incompatible' });
+      continue;
+    }
+
     if (candidate.state === 'PAUSED') {
       targets.push({ consumerId: candidate.moduleId, capabilityNames, skip: 'paused' });
       continue;
@@ -111,11 +137,11 @@ export function planProviderBackfill(
  */
 export function loadProviderBackfillPlan(provider: string, db: DbClient): BackfillTarget[] {
   const provided = db
-    .select({ capabilityName: capabilities.capabilityName })
+    .select({ capabilityName: capabilities.capabilityName, version: capabilities.version })
     .from(capabilities)
     .where(eq(capabilities.moduleId, provider))
     .all()
-    .map((row) => row.capabilityName);
+    .map((row) => ({ name: row.capabilityName, version: row.version }));
   if (provided.length === 0) return [];
 
   const candidates: ConsumerCandidate[] = [];
@@ -174,6 +200,11 @@ export async function runProviderBackfill(
           `${target.consumerId} is paused, so it was not re-run against the new '${provider}' — it consumes ${target.capabilityNames.join(', ')} and will rebind on its next deploy.`,
         );
       }
+      if (target.skip === 'incompatible') {
+        logger.warn(
+          `${target.consumerId} was NOT re-run against the new '${provider}': it declares ${target.capabilityNames.join(', ')} on a version '${provider}' no longer serves. Rebuild ${target.consumerId} against the provider's current major, then redeploy it.`,
+        );
+      }
       continue;
     }