@celilo/cli 0.26.0 → 0.27.0

package/CELILO_CORE_MODULES.md

@@ -27,7 +27,7 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 - **knot-unbound-internal** — split-horizon internal DNS via Knot (authoritative) + Unbound (recursive); lightweight, plain apt, no .NET. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/knot-unbound-internal/base-module-aspect/`).
 - **technitium** — internal split-horizon DNS resolver + authoritative server (web UI + HTTP API); heavier alternative to knot-unbound. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/technitium/base-module-aspect/`).
 - **namecheap** — public DNS A-record management via Namecheap Dynamic DNS API (HTTP, no browser automation). A caller supplies a NAME and nothing else: the address is the source IP of celilo's own update, re-derived on every assert. Registering `<domain>` also claims `www.<domain>` and vice versa (best effort, reported back as `outputs.companion_fqdn` so the framework's `public_dns` check watches it — Namecheap answers `ErrCount 0` for `www` updates it does not apply). DDNS passwords are keyed by the **registrable domain**, never the FQDN. **provides:** `dns_registrar`.
-- **wireguard** — owns the admin WireGuard tunnel on the firewall host: interface, listen port, peers (as records), and client subnet are module config rather than hand-maintained state. Exposes the listen port and **registers the client subnet as a trusted source**, so VPN reach into the managed zones is in the firewall registry and every converge re-emits it. **REQUIRES the `control-plane-vpn` network and READS its range** (`requires.networks`; `client_subnet` is a `source: system` derive of `network.control-plane-vpn.subnet`). It does not write that network and has no way to — celilo owns the namespace, and the deploy will not reach any hook until the network is defined, asking for a range if one is missing. So `wg0` is attributable the moment it exists. This replaces a declare-before-you-create ordering inside `on_install`, which could only narrow the window and not close it: a consumer that captured config before the hook started could not see a value the hook wrote, whatever order it wrote it in, and that is exactly what left `wg0` unattributable (celilo#759). `health_check` still asserts the declaration matches what the tunnel serves — what it catches now is divergence, celilo's network having changed since the module resolved its config. That same key is what the internal resolver's split-horizon view consumes. Adopts a running tunnel in place (existing key retained; `wg syncconf`, never `wg-quick down`) because that tunnel is the operator's recovery path. **Adoption is a one-time IMPORT and it ENDS.** The marker is `registered_peers` — celilo's own config key, separate from the operator's `peers` so a machine can never rewrite what an operator typed. While that key has never been written the tunnel is not yet celilo's; the deploy that writes it (even as `[]`) CLAIMS the tunnel, importing whatever `[Peer]` blocks are running, and from then on the render is closed-world (`peers` ∪ `registered_peers`) with a `[Peer]` on the box in neither reported as drift by `on_install` and by `health_check`'s `unknown_peers`. An ABSENT `peers` declaration and a declared-EMPTY one are deliberately different (no `default: []` on either variable): they used to be the same value, so the module read every empty list as "adopt what is running", the last peer could not be revoked, and a hand-added peer rode along on every deploy unreported (celilo#765). On a tunnel celilo has not yet claimed, a declared-empty `peers` is REFUSED rather than obeyed — celilo's own variable-default seeding wrote a real `peers = []` row for every install of the previous version that never set one, so on the installed base an empty list cannot be told from a stored default, and obeying it would `wg syncconf` the admin tunnel down to zero peers. **requires:** `firewall` (and the provider must support trusted-source registration — `iptables` does; the ISP-router drivers `greenwave` and `axon` do not).
+- **wireguard** — owns the admin WireGuard tunnel on the firewall host: interface, listen port, peers (as records), and client subnet are module config rather than hand-maintained state. Exposes the listen port and **registers the client subnet as a trusted source**, so VPN reach into the managed zones is in the firewall registry and every converge re-emits it. **REQUIRES the `control-plane-vpn` network and READS its range** (`requires.networks`; `client_subnet` is a `source: system` derive of `network.control-plane-vpn.subnet`). It does not write that network and has no way to — celilo owns the namespace, and the deploy will not reach any hook until the network is defined, asking for a range if one is missing. So `wg0` is attributable the moment it exists. This replaces a declare-before-you-create ordering inside `on_install`, which could only narrow the window and not close it: a consumer that captured config before the hook started could not see a value the hook wrote, whatever order it wrote it in, and that is exactly what left `wg0` unattributable (celilo#759). `health_check` still asserts the declaration matches what the tunnel serves — what it catches now is divergence, celilo's network having changed since the module resolved its config. That same key is what the internal resolver's split-horizon view consumes. Adopts a running tunnel in place (existing key retained; `wg syncconf`, never `wg-quick down`) because that tunnel is the operator's recovery path. **Adoption is a one-time IMPORT and it ENDS.** The marker is `registered_peers` — celilo's own config key, separate from the operator's `peers` so a machine can never rewrite what an operator typed. While that key has never been written the tunnel is not yet celilo's; the deploy that writes it (even as `[]`) CLAIMS the tunnel, importing whatever `[Peer]` blocks are running, and from then on the render is closed-world (`peers` ∪ `registered_peers`) with a `[Peer]` on the box in neither reported as drift by `on_install` and by `health_check`'s `unknown_peers`. An ABSENT `peers` declaration and a declared-EMPTY one are deliberately different (no `default: []` on either variable): they used to be the same value, so the module read every empty list as "adopt what is running", the last peer could not be revoked, and a hand-added peer rode along on every deploy unreported (celilo#765). On a tunnel celilo has not yet claimed, a declared-empty `peers` is REFUSED rather than obeyed — celilo's own variable-default seeding wrote a real `peers = []` row for every install of the previous version that never set one, so on the installed base an empty list cannot be told from a stored default, and obeying it would `wg syncconf` the admin tunnel down to zero peers. **PROVIDES `control_plane_vpn`** so another module can enrol clients without an operator editing YAML: `registerClient` / `revokeClient` write to `registered_peers` — the same key the adoption claim uses — and `getEndpoint` reads the server's public key LIVE off the host rather than storing a copy that could be republished after the key changed. `client_pool` is the range a consumer may allocate from, a strict subset of the client subnet, and `validate_config` REFUSES any operator-declared peer inside it: the two allocators cannot see each other, so the range is divided rather than negotiated, and that check is the only place a bad division is caught. ⚠️ Granting this capability grants fleet-wide reach — the tunnel's client subnet is a registered trusted source, so every client enrolled through it reaches every managed zone. **requires:** `firewall` (and the provider must support trusted-source registration — `iptables` does; the ISP-router drivers `greenwave` and `axon` do not).
 
 ## Public edge (ingress / identity)
 

package/CELILO_SUBSYSTEMS.md

@@ -60,6 +60,8 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 | `registry_publish` | `packages/capabilities/src/registry-publish.ts` | celilo-registry |
 | `notification` | `packages/capabilities/src/notification.ts` (`send`, optional `receive`) | signal (planned) — transports are ordinary modules, both self-hosted and credential-only |
 | `cross_module_read` | `packages/capabilities/src/cross-module-read.ts` | framework (read other modules' capability data) |
+| `control_plane_vpn` | `packages/capabilities/src/control-plane-vpn.ts` (`registerClient`, `revokeClient`, `listClients`, `getEndpoint`). **Its state is NOT in a celilo table** — registrations live in the PROVIDER's own module config under `registered_peers`, kept separate from the operator's `peers` so a machine can never rewrite what an operator typed, and so `revokeClient` structurally cannot reach a declared peer. Do not go looking for a `vpn_clients` table; there isn't one and that is deliberate. Addresses are allocated by the CONSUMER from `client_pool` — celilo's IPAM deliberately does not cover VPN clients. ⚠️ Every client registered here reaches every managed zone: the tunnel's client subnet is a registered trusted source. | wireguard |
+| `private_web` | `packages/capabilities/src/private-web.ts` (`publishStaticSite`, `registerReverseProxy`, `unregisterRoutes`, `getCaCertificate`). **Fleet-only HTTP ingress** — internal DNS, an internally-issued certificate, and no public exposure. A SIBLING of `public_web` rather than a flag on it, because `public_web` treats an unreachable route as a deploy failure and publishes a public record to prevent one. Reuses `public_web`'s request types so a consumer can write `private_web ?? public_web` and call through the union without branching. | caddy-internal (planned) |
 
 ### In-fleet (`public_web`) vs off-fleet (`external_web`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,9 +58,9 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^1.3.0",
+    "@celilo/capabilities": "^1.5.0",
     "@celilo/cli-display": "^0.2.0",
-    "@celilo/core": "^0.8.0",
+    "@celilo/core": "^0.8.1",
     "@celilo/event-bus": "^0.6.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/src/__integration__/container-services-cli.integration.test.ts

@@ -151,7 +151,6 @@ describe('Container Services and Machine Pool CLI Integration', () => {
         sshUser: 'ubuntu',
         sshKeyEncrypted: JSON.stringify(sshKey),
         hardware: { cpu_cores: 4, memory_mb: 4096, disk_gb: 128 },
-        assignedModuleIds: [],
         createdAt: new Date(),
         updatedAt: new Date(),
       });
@@ -187,7 +186,6 @@ describe('Container Services and Machine Pool CLI Integration', () => {
           sshUser: 'root',
           sshKeyEncrypted: JSON.stringify(sshKey),
           hardware: { cpu_cores: 2, memory_mb: 2048, disk_gb: 64 },
-          assignedModuleIds: [],
           createdAt: new Date(),
           updatedAt: new Date(),
         },
@@ -199,7 +197,6 @@ describe('Container Services and Machine Pool CLI Integration', () => {
           sshUser: 'ubuntu',
           sshKeyEncrypted: JSON.stringify(sshKey),
           hardware: { cpu_cores: 4, memory_mb: 4096, disk_gb: 128 },
-          assignedModuleIds: [],
           createdAt: new Date(),
           updatedAt: new Date(),
         },
@@ -232,7 +229,6 @@ describe('Container Services and Machine Pool CLI Integration', () => {
         sshUser: 'root',
         sshKeyEncrypted: JSON.stringify(sshKey),
         hardware: { cpu_cores: 2, memory_mb: 2048, disk_gb: 64 },
-        assignedModuleIds: [],
         createdAt: new Date(),
         updatedAt: new Date(),
       });

package/src/ansible/dependencies.test.ts

@@ -1,309 +1,253 @@
-import { describe, expect, it } from 'bun:test';
+/**
+ * celilo#524. `verifyCollectionIntegrity` is a supply-chain check that could
+ * not report a failure: three independent paths returned "integrity verified"
+ * for a tampered collection, and no constructible input reached the failure
+ * return. The file had no tests at all.
+ *
+ * These build real broken collections on disk — the same three the issue's
+ * break-and-watch constructed — rather than mocking the filesystem. A mock
+ * would assert my belief about what `readFile` does; a real directory asserts
+ * what the function does.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { createHash } from 'node:crypto';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import {
-  type CollectionRequirement,
-  type VersionConstraint,
-  compareVersions,
-  formatConstraints,
-  intersectConstraints,
-  mergeAnsibleRequirements,
-  parseSemanticVersion,
-  parseVersionConstraint,
-  satisfiesConstraint,
-  satisfiesConstraints,
+  type InstalledCollection,
+  reportIntegrity,
+  verifyCollectionIntegrity,
 } from './dependencies';
 
-describe('parseSemanticVersion', () => {
-  it('parses valid semantic version', () => {
-    const version = parseSemanticVersion('8.5.2');
-    expect(version).toEqual({ major: 8, minor: 5, patch: 2 });
-  });
+const NAME = 'community.general';
+const [NAMESPACE, COLLECTION] = NAME.split('.');
 
-  it('throws on invalid version', () => {
-    expect(() => parseSemanticVersion('8.5')).toThrow('Invalid semantic version');
-    expect(() => parseSemanticVersion('8')).toThrow('Invalid semantic version');
-    expect(() => parseSemanticVersion('v8.5.2')).toThrow('Invalid semantic version');
-  });
-});
+const sha256 = (content: string) => createHash('sha256').update(content).digest('hex');
 
-describe('compareVersions', () => {
-  it('compares major versions', () => {
-    const v8 = { major: 8, minor: 0, patch: 0 };
-    const v9 = { major: 9, minor: 0, patch: 0 };
-    expect(compareVersions(v8, v9)).toBeLessThan(0);
-    expect(compareVersions(v9, v8)).toBeGreaterThan(0);
-    expect(compareVersions(v8, v8)).toBe(0);
-  });
+describe('verifyCollectionIntegrity', () => {
+  let root: string;
+  let dir: string;
+  let info: InstalledCollection;
 
-  it('compares minor versions when major equal', () => {
-    const v8_0 = { major: 8, minor: 0, patch: 0 };
-    const v8_5 = { major: 8, minor: 5, patch: 0 };
-    expect(compareVersions(v8_0, v8_5)).toBeLessThan(0);
-    expect(compareVersions(v8_5, v8_0)).toBeGreaterThan(0);
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'celilo-galaxy-'));
+    dir = join(root, NAMESPACE, COLLECTION);
+    mkdirSync(dir, { recursive: true });
+    info = { name: NAME, version: { major: 1, minor: 0, patch: 0 }, path: root };
   });
 
-  it('compares patch versions when major and minor equal', () => {
-    const v8_5_0 = { major: 8, minor: 5, patch: 0 };
-    const v8_5_2 = { major: 8, minor: 5, patch: 2 };
-    expect(compareVersions(v8_5_0, v8_5_2)).toBeLessThan(0);
-    expect(compareVersions(v8_5_2, v8_5_0)).toBeGreaterThan(0);
+  afterEach(() => {
+    try {
+      rmSync(root, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
   });
-});
 
-describe('parseVersionConstraint', () => {
-  it('parses >= constraint', () => {
-    const constraints = parseVersionConstraint('>=8.0.0');
-    expect(constraints).toEqual([
-      {
-        operator: '>=',
-        version: { major: 8, minor: 0, patch: 0 },
-      },
-    ]);
-  });
-
-  it('parses == constraint', () => {
-    const constraints = parseVersionConstraint('==8.5.0');
-    expect(constraints).toEqual([
-      {
-        operator: '==',
-        version: { major: 8, minor: 5, patch: 0 },
-      },
-    ]);
-  });
+  /** Write a coherent, genuinely intact collection. */
+  function writeGoodCollection(): void {
+    const payload = '- name: do a thing\n';
+    writeFileSync(join(dir, 'plugins.yml'), payload);
 
-  it('parses range constraint', () => {
-    const constraints = parseVersionConstraint('>=8.0.0,<10.0.0');
-    expect(constraints).toHaveLength(2);
-    expect(constraints[0]).toEqual({
-      operator: '>=',
-      version: { major: 8, minor: 0, patch: 0 },
-    });
-    expect(constraints[1]).toEqual({
-      operator: '<',
-      version: { major: 10, minor: 0, patch: 0 },
+    const filesJson = JSON.stringify({
+      files: [{ name: 'plugins.yml', ftype: 'file', chksum_sha256: sha256(payload) }],
     });
-  });
-
-  it('throws on invalid constraint', () => {
-    expect(() => parseVersionConstraint('invalid')).toThrow('Invalid version constraint');
-    expect(() => parseVersionConstraint('>8')).toThrow('Invalid version constraint');
-  });
-});
-
-describe('satisfiesConstraint', () => {
-  it('checks >= constraint', () => {
-    const constraint: VersionConstraint = {
-      operator: '>=',
-      version: { major: 8, minor: 0, patch: 0 },
-    };
-
-    expect(satisfiesConstraint({ major: 9, minor: 0, patch: 0 }, constraint)).toBe(true);
-    expect(satisfiesConstraint({ major: 8, minor: 0, patch: 0 }, constraint)).toBe(true);
-    expect(satisfiesConstraint({ major: 7, minor: 9, patch: 9 }, constraint)).toBe(false);
-  });
-
-  it('checks == constraint', () => {
-    const constraint: VersionConstraint = {
-      operator: '==',
-      version: { major: 8, minor: 5, patch: 0 },
-    };
-
-    expect(satisfiesConstraint({ major: 8, minor: 5, patch: 0 }, constraint)).toBe(true);
-    expect(satisfiesConstraint({ major: 8, minor: 5, patch: 1 }, constraint)).toBe(false);
-    expect(satisfiesConstraint({ major: 9, minor: 0, patch: 0 }, constraint)).toBe(false);
-  });
-
-  it('checks < constraint', () => {
-    const constraint: VersionConstraint = {
-      operator: '<',
-      version: { major: 10, minor: 0, patch: 0 },
-    };
-
-    expect(satisfiesConstraint({ major: 9, minor: 9, patch: 9 }, constraint)).toBe(true);
-    expect(satisfiesConstraint({ major: 10, minor: 0, patch: 0 }, constraint)).toBe(false);
-    expect(satisfiesConstraint({ major: 11, minor: 0, patch: 0 }, constraint)).toBe(false);
-  });
-});
-
-describe('satisfiesConstraints', () => {
-  it('checks multiple constraints', () => {
-    const constraints = parseVersionConstraint('>=8.0.0,<10.0.0');
-
-    expect(satisfiesConstraints({ major: 8, minor: 0, patch: 0 }, constraints)).toBe(true);
-    expect(satisfiesConstraints({ major: 9, minor: 5, patch: 2 }, constraints)).toBe(true);
-    expect(satisfiesConstraints({ major: 7, minor: 9, patch: 9 }, constraints)).toBe(false);
-    expect(satisfiesConstraints({ major: 10, minor: 0, patch: 0 }, constraints)).toBe(false);
-  });
-});
-
-describe('intersectConstraints', () => {
-  it('returns empty array for empty input', () => {
-    expect(intersectConstraints([])).toEqual([]);
-  });
-
-  it('returns single constraint set unchanged', () => {
-    const constraints = parseVersionConstraint('>=8.0.0');
-    expect(intersectConstraints([constraints])).toEqual(constraints);
-  });
-
-  it('merges compatible minimums (takes highest)', () => {
-    const c1 = parseVersionConstraint('>=8.0.0');
-    const c2 = parseVersionConstraint('>=9.0.0');
-
-    const result = intersectConstraints([c1, c2]);
-    expect(result).toEqual([{ operator: '>=', version: { major: 9, minor: 0, patch: 0 } }]);
-  });
-
-  it('finds range overlap', () => {
-    const c1 = parseVersionConstraint('>=8.0.0,<10.0.0');
-    const c2 = parseVersionConstraint('>=9.0.0,<11.0.0');
-
-    const result = intersectConstraints([c1, c2]);
-    expect(result).toHaveLength(2);
-    expect(result?.[0]).toEqual({ operator: '>=', version: { major: 9, minor: 0, patch: 0 } });
-    expect(result?.[1]).toEqual({ operator: '<', version: { major: 10, minor: 0, patch: 0 } });
-  });
-
-  it('detects conflicting ranges', () => {
-    const c1 = parseVersionConstraint('>=8.0.0,<9.0.0');
-    const c2 = parseVersionConstraint('>=9.0.0,<10.0.0');
-
-    const result = intersectConstraints([c1, c2]);
-    expect(result).toBeNull(); // No overlap
-  });
-
-  it('handles exact pins matching', () => {
-    const c1 = parseVersionConstraint('==8.5.0');
-    const c2 = parseVersionConstraint('==8.5.0');
-
-    const result = intersectConstraints([c1, c2]);
-    expect(result).toEqual([{ operator: '==', version: { major: 8, minor: 5, patch: 0 } }]);
-  });
-
-  it('detects conflicting exact pins', () => {
-    const c1 = parseVersionConstraint('==8.5.0');
-    const c2 = parseVersionConstraint('==9.0.0');
-
-    const result = intersectConstraints([c1, c2]);
-    expect(result).toBeNull();
-  });
-
-  it('checks exact pin against bounds', () => {
-    const c1 = parseVersionConstraint('==8.5.0');
-    const c2 = parseVersionConstraint('>=8.0.0,<9.0.0');
-
-    const result = intersectConstraints([c1, c2]);
-    expect(result).toEqual([{ operator: '==', version: { major: 8, minor: 5, patch: 0 } }]);
-  });
-
-  it('detects exact pin outside bounds', () => {
-    const c1 = parseVersionConstraint('==10.0.0');
-    const c2 = parseVersionConstraint('>=8.0.0,<9.0.0');
-
-    const result = intersectConstraints([c1, c2]);
-    expect(result).toBeNull();
-  });
-});
-
-describe('mergeAnsibleRequirements', () => {
-  it('merges compatible requirements', () => {
-    const requirements: CollectionRequirement[] = [
-      {
-        name: 'community.general',
-        constraints: parseVersionConstraint('>=8.0.0'),
-        moduleId: 'module-a',
-      },
-      {
-        name: 'community.general',
-        constraints: parseVersionConstraint('>=9.0.0'),
-        moduleId: 'module-b',
-      },
+    writeFileSync(join(dir, 'FILES.json'), filesJson);
+    writeFileSync(
+      join(dir, 'MANIFEST.json'),
+      JSON.stringify({
+        collection_info: { namespace: NAMESPACE, name: COLLECTION, version: '1.0.0' },
+        file_manifest_file: {
+          name: 'FILES.json',
+          ftype: 'file',
+          chksum_type: 'sha256',
+          chksum_sha256: sha256(filesJson),
+        },
+      }),
+    );
+  }
+
+  test('an intact collection verifies, and says how many files it checked', async () => {
+    writeGoodCollection();
+    const outcome = await verifyCollectionIntegrity(info);
+    expect(outcome.status).toBe('verified');
+    expect(outcome.status === 'verified' && outcome.filesChecked).toBeGreaterThan(0);
+  });
+
+  // ── The three cases from the issue. Each returned `true` before. ──────────
+
+  test('A: an unparseable MANIFEST.json is unverifiable, not verified', async () => {
+    writeGoodCollection();
+    writeFileSync(join(dir, 'MANIFEST.json'), '{ this is not json');
+
+    const outcome = await verifyCollectionIntegrity(info);
+    expect(outcome.status).toBe('unverifiable');
+    // Rule 6.2: the exception path used to claim it logged and did not.
+    expect(outcome.status === 'unverifiable' && outcome.reason.length).toBeGreaterThan(0);
+  });
+
+  test('B: a MANIFEST.json with no FILES.json checksum is unverifiable', async () => {
+    writeGoodCollection();
+    writeFileSync(
+      join(dir, 'MANIFEST.json'),
+      JSON.stringify({
+        collection_info: { namespace: NAMESPACE, name: COLLECTION, version: '1.0.0' },
+        // `file_manifest_file` stripped — the one field an attacker shipping a
+        // tampered collection fully controls. It used to switch the check off.
+      }),
+    );
+
+    const outcome = await verifyCollectionIntegrity(info);
+    expect(outcome.status).toBe('unverifiable');
+    expect(outcome.status === 'unverifiable' && outcome.reason).toContain('no FILES.json checksum');
+  });
+
+  test('C: every listed file missing from disk is unverifiable, not a pass', async () => {
+    writeGoodCollection();
+    rmSync(join(dir, 'plugins.yml'));
+
+    const outcome = await verifyCollectionIntegrity(info);
+    expect(outcome.status).toBe('unverifiable');
+    // Verifying zero files is not verifying.
+    expect(outcome.status === 'unverifiable' && outcome.reason).toContain('present on disk');
+  });
+
+  // ── Refutation is distinct from ignorance ────────────────────────────────
+
+  test('a modified file is a MISMATCH, not merely unverifiable', async () => {
+    writeGoodCollection();
+    writeFileSync(join(dir, 'plugins.yml'), '- name: do something ELSE\n');
+
+    const outcome = await verifyCollectionIntegrity(info);
+    expect(outcome.status).toBe('mismatch');
+    expect(outcome.status === 'mismatch' && outcome.detail).toContain('plugins.yml');
+  });
+
+  test('a tampered FILES.json is a MISMATCH', async () => {
+    writeGoodCollection();
+    // Rewrite FILES.json so it no longer matches the checksum in MANIFEST.json —
+    // what re-pointing a file at different content looks like.
+    writeFileSync(
+      join(dir, 'FILES.json'),
+      JSON.stringify({
+        files: [{ name: 'plugins.yml', ftype: 'file', chksum_sha256: sha256('something else') }],
+      }),
+    );
+
+    const outcome = await verifyCollectionIntegrity(info);
+    expect(outcome.status).toBe('mismatch');
+    expect(outcome.status === 'mismatch' && outcome.detail).toContain('FILES.json');
+  });
+
+  test('a missing FILES.json is unverifiable, and is not confused with a mismatch', async () => {
+    writeGoodCollection();
+    rmSync(join(dir, 'FILES.json'));
+
+    const outcome = await verifyCollectionIntegrity(info);
+    expect(outcome.status).toBe('unverifiable');
+  });
+
+  test('a collection with no checksummed files is unverifiable', async () => {
+    writeGoodCollection();
+    const filesJson = JSON.stringify({ files: [{ name: 'roles', ftype: 'dir' }] });
+    writeFileSync(join(dir, 'FILES.json'), filesJson);
+    writeFileSync(
+      join(dir, 'MANIFEST.json'),
+      JSON.stringify({
+        collection_info: { namespace: NAMESPACE, name: COLLECTION, version: '1.0.0' },
+        file_manifest_file: {
+          name: 'FILES.json',
+          ftype: 'file',
+          chksum_type: 'sha256',
+          chksum_sha256: sha256(filesJson),
+        },
+      }),
+    );
+
+    const outcome = await verifyCollectionIntegrity(info);
+    expect(outcome.status).toBe('unverifiable');
+  });
+
+  /**
+   * The recurrence gate proper. Every way this function can fail to establish
+   * integrity must be distinguishable from success — a single `status` compared
+   * against 'verified' is what a caller will actually write, and it must be
+   * false for all of them.
+   */
+  test('no broken collection is EVER reported as verified', async () => {
+    const breakages: Array<[string, () => void]> = [
+      ['unparseable manifest', () => writeFileSync(join(dir, 'MANIFEST.json'), 'nope')],
+      [
+        'no files checksum',
+        () =>
+          writeFileSync(
+            join(dir, 'MANIFEST.json'),
+            JSON.stringify({
+              collection_info: { namespace: NAMESPACE, name: COLLECTION, version: '1.0.0' },
+            }),
+          ),
+      ],
+      ['files missing', () => rmSync(join(dir, 'plugins.yml'))],
+      ['manifest missing', () => rmSync(join(dir, 'MANIFEST.json'))],
+      ['files.json missing', () => rmSync(join(dir, 'FILES.json'))],
+      ['content modified', () => writeFileSync(join(dir, 'plugins.yml'), 'tampered\n')],
     ];
 
-    const result = mergeAnsibleRequirements(requirements);
+    for (const [label, breakIt] of breakages) {
+      rmSync(dir, { recursive: true, force: true });
+      mkdirSync(dir, { recursive: true });
+      writeGoodCollection();
+      breakIt();
 
-    expect(result.success).toBe(true);
-    expect(result.resolved).toHaveLength(1);
-    expect(result.resolved[0].name).toBe('community.general');
-    expect(result.resolved[0].satisfiesAll).toBe(true);
-    expect(formatConstraints(result.resolved[0].constraints)).toBe('>=9.0.0');
-  });
-
-  it('detects conflicts', () => {
-    const requirements: CollectionRequirement[] = [
-      {
-        name: 'community.general',
-        constraints: parseVersionConstraint('>=8.0.0,<9.0.0'),
-        moduleId: 'module-a',
-        reason: 'Uses old API',
-      },
-      {
-        name: 'community.general',
-        constraints: parseVersionConstraint('>=9.0.0'),
-        moduleId: 'module-b',
-        reason: 'Requires new features',
-      },
-    ];
-
-    const result = mergeAnsibleRequirements(requirements);
-
-    expect(result.success).toBe(false);
-    expect(result.conflicts).toHaveLength(1);
-    expect(result.conflicts?.[0].collection).toBe('community.general');
-    expect(result.conflicts?.[0].requirements).toHaveLength(2);
-    expect(result.conflicts?.[0].requirements[0].moduleId).toBe('module-a');
-    expect(result.conflicts?.[0].requirements[1].moduleId).toBe('module-b');
-  });
-
-  it('handles multiple collections', () => {
-    const requirements: CollectionRequirement[] = [
-      {
-        name: 'community.general',
-        constraints: parseVersionConstraint('>=8.0.0'),
-        moduleId: 'module-a',
-      },
-      {
-        name: 'ansible.posix',
-        constraints: parseVersionConstraint('>=1.5.0'),
-        moduleId: 'module-a',
-      },
-      {
-        name: 'community.general',
-        constraints: parseVersionConstraint('>=9.0.0'),
-        moduleId: 'module-b',
-      },
-    ];
-
-    const result = mergeAnsibleRequirements(requirements);
-
-    expect(result.success).toBe(true);
-    expect(result.resolved).toHaveLength(2);
-
-    const general = result.resolved.find((r) => r.name === 'community.general');
-    const posix = result.resolved.find((r) => r.name === 'ansible.posix');
-
-    expect(general).toBeDefined();
-    // biome-ignore lint/style/noNonNullAssertion: checked with toBeDefined() above
-    expect(formatConstraints(general!.constraints)).toBe('>=9.0.0');
-
-    expect(posix).toBeDefined();
-    // biome-ignore lint/style/noNonNullAssertion: checked with toBeDefined() above
-    expect(formatConstraints(posix!.constraints)).toBe('>=1.5.0');
+      const outcome = await verifyCollectionIntegrity(info);
+      expect(`${label}: ${outcome.status}`).not.toBe(`${label}: verified`);
+    }
   });
 });
 
-describe('formatConstraints', () => {
-  it('formats single constraint', () => {
-    const constraints = parseVersionConstraint('>=8.0.0');
-    expect(formatConstraints(constraints)).toBe('>=8.0.0');
-  });
-
-  it('formats range constraint', () => {
-    const constraints = parseVersionConstraint('>=8.0.0,<10.0.0');
-    expect(formatConstraints(constraints)).toBe('>=8.0.0,<10.0.0');
-  });
-
-  it('formats exact pin', () => {
-    const constraints = parseVersionConstraint('==8.5.0');
-    expect(formatConstraints(constraints)).toBe('==8.5.0');
+/**
+ * celilo#524, policy half. A refuted collection now REFUSES the import; an
+ * uncheckable one warns.
+ *
+ * Refusing is cheap exactly here: `installCollectionsForModule` is called only
+ * from `module/import.ts`, and nothing installs collections in the deploy path,
+ * so a false positive means "this module did not import" rather than "the fleet
+ * stopped deploying". No module row exists yet either, so there is nothing left
+ * half-created — which is why this is an import refusal and not an ERROR state.
+ */
+describe('reportIntegrity — what each outcome does to the import', () => {
+  test('a MISMATCH refuses, and the message says what and why', () => {
+    const refusal = reportIntegrity('community.general', {
+      status: 'mismatch',
+      detail: 'plugins.yml does not match its checksum',
+    });
+    expect(refusal).toBeTruthy();
+    expect(refusal).toContain('community.general');
+    expect(refusal).toContain('plugins.yml does not match its checksum');
+    // The operator needs to know this is refutation, not a missing checksum.
+    expect(refusal).toContain('corruption or tampering');
+  });
+
+  /**
+   * The distinction that keeps this from becoming a false-positive machine. A
+   * collection shipping no `file_manifest_file` is telling you about its
+   * publisher, not about tampering — blocking on it would refuse ordinary
+   * collections forever, which is how a check gets disabled wholesale.
+   */
+  test('an UNVERIFIABLE outcome does NOT refuse', () => {
+    expect(
+      reportIntegrity('community.general', {
+        status: 'unverifiable',
+        reason: 'MANIFEST.json declares no FILES.json checksum',
+      }),
+    ).toBeNull();
+  });
+
+  test('a verified collection refuses nothing', () => {
+    expect(
+      reportIntegrity('community.general', { status: 'verified', filesChecked: 5 }),
+    ).toBeNull();
   });
 });