@wildo-ai/wildo-module-client 1.1.1

package/src/__tests__/lockfile-repair.service.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Phase 2 tests for `LockfileRepairService`.
+ *
+ * The service is read-only and produces a structured report.
+ * Tests pin every finding kind:
+ *   - missing lockfile → empty ok-report.
+ *   - malformed envelope → error finding.
+ *   - malformed modules section → error finding.
+ *   - lockfile entry pointing at a missing file → warn finding.
+ *   - lockfile entry with non-sha256 digest → warn finding.
+ */
+
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { WILDO_SAAS_LOCK_RELATIVE_PATH } from '@wildo-ai/platform-config-lib';
+import { LockfileRepairService } from '../services/lockfile-repair.service';
+
+let saasRoot: string;
+let lockPath: string;
+
+beforeEach(async () => {
+  saasRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'wildo-repair-spec-'));
+  lockPath = path.join(saasRoot, WILDO_SAAS_LOCK_RELATIVE_PATH);
+});
+
+afterEach(async () => {
+  await fs.rm(saasRoot, { recursive: true, force: true });
+});
+
+async function writeEnvelope(envelope: unknown): Promise<void> {
+  await fs.mkdir(path.dirname(lockPath), { recursive: true });
+  await fs.writeFile(lockPath, JSON.stringify(envelope, null, 2), 'utf8');
+}
+
+const VALID_DIGEST = 'sha256:' + 'a'.repeat(64);
+
+const validEntry = (overrides: Record<string, unknown> = {}) => ({
+  moduleId: 'acme/billing',
+  registryId: 'wildo',
+  registryUrl: 'https://registry.wildo.ai',
+  domain: 'acme',
+  version: '1.2.3',
+  artifactDigest: VALID_DIGEST,
+  installedAt: '2026-05-05T12:00:00.000Z',
+  files: ['shared-lib/src/modules/acme-billing/index.ts'],
+  source: 'install' as const,
+  ...overrides,
+});
+
+describe('LockfileRepairService.inspect', () => {
+  it('returns ok+empty when the lockfile does not exist', async () => {
+    const report = await LockfileRepairService.inspect(saasRoot);
+    expect(report.ok).toBe(true);
+    expect(report.findings).toEqual([]);
+  });
+
+  it('reports envelope-malformed on top-level Zod failure', async () => {
+    await writeEnvelope({ schemaVersion: 1, generatedAt: '2026', sections: {} });
+    const report = await LockfileRepairService.inspect(saasRoot);
+    expect(report.ok).toBe(false);
+    expect(report.findings[0].kind).toBe('envelope-malformed');
+  });
+
+  it('reports modules-section-malformed when sections.modules fails the section schema', async () => {
+    await writeEnvelope({
+      schemaVersion: 2,
+      generatedAt: '2026-05-05T12:00:00.000Z',
+      sections: { modules: { installed: 'not-an-object' } },
+    });
+    const report = await LockfileRepairService.inspect(saasRoot);
+    expect(report.ok).toBe(false);
+    expect(report.findings[0].kind).toBe('modules-section-malformed');
+  });
+
+  it('reports module-file-missing when an installed entry points at a non-existent file', async () => {
+    await writeEnvelope({
+      schemaVersion: 2,
+      generatedAt: '2026-05-05T12:00:00.000Z',
+      sections: { modules: { installed: { 'acme/billing': validEntry() } } },
+    });
+    const report = await LockfileRepairService.inspect(saasRoot);
+    expect(report.ok).toBe(true); // warnings only
+    expect(report.findings).toHaveLength(1);
+    expect(report.findings[0]).toMatchObject({
+      severity: 'warn',
+      kind: 'module-file-missing',
+      moduleId: 'acme/billing',
+      filePath: 'shared-lib/src/modules/acme-billing/index.ts',
+    });
+  });
+
+  it('does NOT flag files that exist on disk', async () => {
+    const filePath = 'shared-lib/src/modules/acme-billing/index.ts';
+    await fs.mkdir(path.join(saasRoot, path.dirname(filePath)), { recursive: true });
+    await fs.writeFile(path.join(saasRoot, filePath), 'export const x = 1;\n');
+    await writeEnvelope({
+      schemaVersion: 2,
+      generatedAt: '2026-05-05T12:00:00.000Z',
+      sections: { modules: { installed: { 'acme/billing': validEntry() } } },
+    });
+    const report = await LockfileRepairService.inspect(saasRoot);
+    expect(report.findings).toEqual([]);
+  });
+});

package/src/__tests__/module-adopter.service.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Phase 2 tests for `ModuleAdopterService`.
+ *
+ * Adopter is read-only against the host app's source — it walks
+ * declared `boundaries.*` and stages a copy. Tests pin:
+ *   - `discoverModuleFiles` returns only files inside the
+ *     declared boundaries.
+ *   - `adoptToStaging` is idempotent: same source → same digest.
+ *   - emptyBoundaries reports declared paths that contributed zero files.
+ */
+
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ModuleAdopterService } from '../services/module-adopter.service';
+
+let saasRoot: string;
+
+beforeEach(async () => {
+  saasRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'wildo-adopter-spec-'));
+});
+
+afterEach(async () => {
+  await fs.rm(saasRoot, { recursive: true, force: true });
+});
+
+const manifest = {
+  id: 'acme/billing',
+  version: '1.2.3',
+  boundaries: {
+    specifications: [],
+    shared: ['shared-lib/src/modules/acme-billing'],
+    frontend: [],
+    backend: ['backend-api/src/modules/acme-billing'],
+    minions: [],
+    workers: [],
+  },
+};
+
+async function seedFile(rel: string, contents: string): Promise<void> {
+  const abs = path.join(saasRoot, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, contents, 'utf8');
+}
+
+describe('ModuleAdopterService.discoverModuleFiles', () => {
+  it('returns the union of files inside every declared boundary', async () => {
+    await seedFile('shared-lib/src/modules/acme-billing/index.ts', 'a');
+    await seedFile('shared-lib/src/modules/acme-billing/util.ts', 'b');
+    await seedFile('backend-api/src/modules/acme-billing/handler.ts', 'c');
+    await seedFile('app/src/elsewhere.ts', 'd'); // outside boundaries — must not appear
+    const plan = await ModuleAdopterService.discoverModuleFiles(saasRoot, manifest);
+    expect(plan.files).toEqual([
+      path.join('backend-api/src/modules/acme-billing/handler.ts'),
+      path.join('shared-lib/src/modules/acme-billing/index.ts'),
+      path.join('shared-lib/src/modules/acme-billing/util.ts'),
+    ]);
+  });
+
+  it('records empty boundaries when a declared path matches nothing', async () => {
+    // `backend-api/src/modules/acme-billing` has no files on disk
+    await seedFile('shared-lib/src/modules/acme-billing/index.ts', 'a');
+    const plan = await ModuleAdopterService.discoverModuleFiles(saasRoot, manifest);
+    expect(plan.emptyBoundaries).toEqual(['backend']);
+  });
+
+  it('returns an empty plan when the manifest declares no boundaries', async () => {
+    await seedFile('anywhere.ts', 'x');
+    const plan = await ModuleAdopterService.discoverModuleFiles(saasRoot, {
+      id: 'acme/x',
+      version: '0.0.1',
+    });
+    expect(plan.files).toEqual([]);
+    expect(plan.emptyBoundaries).toEqual([]);
+  });
+});
+
+describe('ModuleAdopterService.adoptToStaging', () => {
+  it('produces a stable digest for the same source', async () => {
+    await seedFile('shared-lib/src/modules/acme-billing/a.ts', 'A\n');
+    await seedFile('shared-lib/src/modules/acme-billing/b.ts', 'B\n');
+    const r1 = await ModuleAdopterService.adoptToStaging(saasRoot, manifest);
+    const r2 = await ModuleAdopterService.adoptToStaging(saasRoot, manifest);
+    expect(r1.digest).toBe(r2.digest);
+    expect(r1.staged).toEqual(r2.staged);
+  });
+
+  it('changes the digest when a file mutates between adopt runs', async () => {
+    await seedFile('shared-lib/src/modules/acme-billing/a.ts', 'V1\n');
+    const r1 = await ModuleAdopterService.adoptToStaging(saasRoot, manifest);
+    await seedFile('shared-lib/src/modules/acme-billing/a.ts', 'V2\n');
+    const r2 = await ModuleAdopterService.adoptToStaging(saasRoot, manifest);
+    expect(r1.digest).not.toBe(r2.digest);
+  });
+});

package/src/__tests__/module-packager.service.test.ts

@@ -0,0 +1,258 @@
+/**
+ * Phase 2 tests for `ModulePackagerService`.
+ *
+ * The staging primitive's hard contracts (KD-8 + KD-12) are
+ * verified here:
+ *   - `paths()` returns the canonical staging root.
+ *   - `stageFresh()` removes the destination first (digest
+ *     determinism).
+ *   - `copyFile()` honors `manifest.boundaries`; out-of-boundary
+ *     paths throw `RegistryBoundaryViolationError`.
+ *   - `writeManifest()` validates via Zod and persists JSON.
+ *   - `computeStagingDigest()` is stable across runs and order-
+ *     independent.
+ */
+
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  ModulePackagerService,
+  MODULES_ARTIFACTS_RELATIVE_DIR,
+  getModuleStagingPaths,
+  assertWithinBoundaries,
+} from '../services/module-packager.service';
+
+let saasRoot: string;
+
+beforeEach(async () => {
+  saasRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'wildo-packager-spec-'));
+});
+
+afterEach(async () => {
+  await fs.rm(saasRoot, { recursive: true, force: true });
+});
+
+const baseManifest = (id = 'acme/billing', version = '1.2.3') => ({
+  id,
+  version,
+  description: 'Billing module',
+  boundaries: {
+    specifications: [],
+    shared: ['shared-lib/src/modules/acme-billing'],
+    frontend: [],
+    backend: ['backend-api/src/modules/acme-billing'],
+    minions: [],
+    workers: [],
+  },
+});
+
+async function seedFile(saasRoot: string, rel: string, contents: string): Promise<void> {
+  const abs = path.join(saasRoot, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, contents, 'utf8');
+}
+
+describe('ModulePackagerService.paths', () => {
+  it('rejects module ids without a domain segment', () => {
+    expect(() => getModuleStagingPaths(saasRoot, 'no-slash')).toThrow();
+  });
+
+  it('returns absolute paths under .wildo-saas/generated/modules-artifacts/<id>/', () => {
+    const paths = getModuleStagingPaths(saasRoot, 'acme/billing');
+    expect(paths.stagingRoot.startsWith(saasRoot)).toBe(true);
+    expect(paths.stagingRoot.endsWith('acme/billing')).toBe(true);
+    expect(paths.manifestPath.endsWith('wildo.module.json')).toBe(true);
+    expect(paths.stagingRoot).toContain(MODULES_ARTIFACTS_RELATIVE_DIR);
+  });
+});
+
+describe('ModulePackagerService.stageFresh', () => {
+  it('removes existing staging contents before recreating', async () => {
+    await ModulePackagerService.stageFresh(saasRoot, 'acme/billing');
+    const stagingRoot = path.join(saasRoot, MODULES_ARTIFACTS_RELATIVE_DIR, 'acme/billing');
+    await fs.writeFile(path.join(stagingRoot, 'leftover.txt'), 'old');
+    await ModulePackagerService.stageFresh(saasRoot, 'acme/billing');
+    const entries = await fs.readdir(stagingRoot);
+    expect(entries).toEqual([]);
+  });
+});
+
+describe('assertWithinBoundaries (KD-12)', () => {
+  it('rejects paths that escape the saas root via `..`', () => {
+    expect(() =>
+      assertWithinBoundaries(saasRoot, 'acme/billing', '../../etc/passwd', baseManifest().boundaries),
+    ).toThrow();
+  });
+
+  it('rejects paths outside every declared boundary', () => {
+    expect(() =>
+      assertWithinBoundaries(
+        saasRoot,
+        'acme/billing',
+        'app/src/modules/acme-billing/index.ts',
+        baseManifest().boundaries,
+      ),
+    ).toThrow();
+  });
+
+  it('accepts paths inside a declared boundary', () => {
+    const result = assertWithinBoundaries(
+      saasRoot,
+      'acme/billing',
+      'shared-lib/src/modules/acme-billing/index.ts',
+      baseManifest().boundaries,
+    );
+    expect(result.endsWith('shared-lib/src/modules/acme-billing/index.ts')).toBe(true);
+  });
+
+  it('skips boundary checks when no boundaries are declared (manifest.boundaries undefined)', () => {
+    const result = assertWithinBoundaries(saasRoot, 'acme/billing', 'anywhere.ts', undefined);
+    expect(result.endsWith('anywhere.ts')).toBe(true);
+  });
+});
+
+describe('ModulePackagerService.copyFile', () => {
+  it('copies an in-boundary file into the staging tree at the same relative path', async () => {
+    await seedFile(
+      saasRoot,
+      'shared-lib/src/modules/acme-billing/index.ts',
+      'export const billing = true;\n',
+    );
+    await ModulePackagerService.stageFresh(saasRoot, 'acme/billing');
+    const result = await ModulePackagerService.copyFile({
+      saasRoot,
+      moduleId: 'acme/billing',
+      appRelativePath: 'shared-lib/src/modules/acme-billing/index.ts',
+      manifest: baseManifest(),
+    });
+    const staged = await fs.readFile(result.stagedAbsolute, 'utf8');
+    expect(staged).toBe('export const billing = true;\n');
+  });
+
+  it('rejects out-of-boundary copies', async () => {
+    await seedFile(saasRoot, 'app/src/leak.ts', 'no');
+    await ModulePackagerService.stageFresh(saasRoot, 'acme/billing');
+    await expect(
+      ModulePackagerService.copyFile({
+        saasRoot,
+        moduleId: 'acme/billing',
+        appRelativePath: 'app/src/leak.ts',
+        manifest: baseManifest(),
+      }),
+    ).rejects.toThrow();
+  });
+});
+
+describe('ModulePackagerService.writeManifest', () => {
+  it('rejects an invalid manifest (Zod parse failure) before writing', async () => {
+    await expect(
+      ModulePackagerService.writeManifest({
+        saasRoot,
+        manifest: { id: '', version: 'not-semver' } as never,
+      }),
+    ).rejects.toThrow();
+    const stagingRoot = path.join(saasRoot, MODULES_ARTIFACTS_RELATIVE_DIR);
+    await expect(fs.access(stagingRoot)).rejects.toThrow();
+  });
+
+  it('writes a JSON file matching the validated manifest', async () => {
+    await ModulePackagerService.stageFresh(saasRoot, 'acme/billing');
+    const result = await ModulePackagerService.writeManifest({ saasRoot, manifest: baseManifest() });
+    const raw = await fs.readFile(result.manifestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    expect(parsed.id).toBe('acme/billing');
+    expect(parsed.version).toBe('1.2.3');
+  });
+});
+
+describe('ModulePackagerService.computeStagingDigest', () => {
+  it('produces a stable sha256 digest across runs', async () => {
+    await seedFile(saasRoot, 'shared-lib/src/modules/acme-billing/a.ts', 'a\n');
+    await seedFile(saasRoot, 'shared-lib/src/modules/acme-billing/b.ts', 'b\n');
+    await ModulePackagerService.stageFresh(saasRoot, 'acme/billing');
+    await ModulePackagerService.writeManifest({ saasRoot, manifest: baseManifest() });
+    await ModulePackagerService.copyFile({
+      saasRoot,
+      moduleId: 'acme/billing',
+      appRelativePath: 'shared-lib/src/modules/acme-billing/a.ts',
+      manifest: baseManifest(),
+    });
+    await ModulePackagerService.copyFile({
+      saasRoot,
+      moduleId: 'acme/billing',
+      appRelativePath: 'shared-lib/src/modules/acme-billing/b.ts',
+      manifest: baseManifest(),
+    });
+    const d1 = await ModulePackagerService.computeStagingDigest(saasRoot, 'acme/billing');
+    const d2 = await ModulePackagerService.computeStagingDigest(saasRoot, 'acme/billing');
+    expect(d1).toBe(d2);
+    expect(d1).toMatch(/^sha256:[0-9a-f]{64}$/);
+  });
+
+  it('produces a different digest when a file changes', async () => {
+    await seedFile(saasRoot, 'shared-lib/src/modules/acme-billing/a.ts', 'v1\n');
+    await ModulePackagerService.stageFresh(saasRoot, 'acme/billing');
+    await ModulePackagerService.writeManifest({ saasRoot, manifest: baseManifest() });
+    await ModulePackagerService.copyFile({
+      saasRoot,
+      moduleId: 'acme/billing',
+      appRelativePath: 'shared-lib/src/modules/acme-billing/a.ts',
+      manifest: baseManifest(),
+    });
+    const d1 = await ModulePackagerService.computeStagingDigest(saasRoot, 'acme/billing');
+    // Mutate source + restage.
+    await seedFile(saasRoot, 'shared-lib/src/modules/acme-billing/a.ts', 'v2\n');
+    await ModulePackagerService.stageFresh(saasRoot, 'acme/billing');
+    await ModulePackagerService.writeManifest({ saasRoot, manifest: baseManifest() });
+    await ModulePackagerService.copyFile({
+      saasRoot,
+      moduleId: 'acme/billing',
+      appRelativePath: 'shared-lib/src/modules/acme-billing/a.ts',
+      manifest: baseManifest(),
+    });
+    const d2 = await ModulePackagerService.computeStagingDigest(saasRoot, 'acme/billing');
+    expect(d1).not.toBe(d2);
+  });
+});
+
+/**
+ * 7th-pass C-L1 — root edge case for `isPathInside`. The helper is
+ * invoked indirectly through `assertWithinBoundaries`; we exercise
+ * the degenerate filesystem-root case by pointing `saasRoot` at `/`
+ * and confirming a child path inside `/` is accepted as "within
+ * boundaries" when the manifest declares `boundaries.shared: ['./']`
+ * (relative path that resolves to `/`).
+ *
+ * Vanishingly unlikely in production (containerized SaaS roots are
+ * never literally `/`) but the helper is also reusable for zip-slip
+ * guards where the assumption is weaker — pinning the behavior
+ * prevents a future "tighten startsWith" refactor from rejecting
+ * every child.
+ */
+describe('assertWithinBoundaries — root edge case (C-L1)', () => {
+  it('accepts a child path when saasRoot is the filesystem root', () => {
+    // Use POSIX path.sep as the boundary; the helper resolves
+    // `path.resolve('/', '.')` → `/` and then `isPathInside('/foo', '/')`
+    // → true via the new root special-case.
+    const manifestWithRootBoundary = {
+      ...baseManifest(),
+      boundaries: {
+        specifications: [],
+        shared: ['.'],
+        frontend: [],
+        backend: [],
+        minions: [],
+        workers: [],
+      },
+    };
+    // Run only on POSIX; Windows root is `C:\` and tests run on
+    // POSIX CI.
+    if (path.sep === '/') {
+      expect(() =>
+        assertWithinBoundaries('/', 'acme/billing', 'foo/bar.ts', manifestWithRootBoundary.boundaries),
+      ).not.toThrow();
+    }
+  });
+});

package/src/__tests__/provider-materialization-hook.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Phase 0.5 sanity tests for `runProviderMaterializationHook`.
+ *
+ * The Phase 0.A spike asserted that codegen does not write any
+ * provider runtime artifact directly. These tests are the runtime
+ * shadow of that assertion: invoking the hook from any module-
+ * registry flow must not write provider artifacts and must report
+ * `mode: 'dry-run'` until Phase 5 wires the real shell-out.
+ */
+
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { runProviderMaterializationHook } from '../services/provider-materialization-hook';
+
+let saasRoot: string;
+
+beforeEach(async () => {
+  saasRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'wildo-module-client-hook-spec-'));
+});
+
+afterEach(async () => {
+  await fs.rm(saasRoot, { recursive: true, force: true });
+});
+
+describe('runProviderMaterializationHook (Phase 0.5 dry-run)', () => {
+  it('returns mode:dry-run + performedFsWrite:false when invoked', async () => {
+    const result = await runProviderMaterializationHook({ saasRoot, reason: 'install' });
+    expect(result.invoked).toBe(true);
+    expect(result.mode).toBe('dry-run');
+    expect(result.performedFsWrite).toBe(false);
+  });
+
+  it('does not write any provider runtime artifact under saasRoot', async () => {
+    const result = await runProviderMaterializationHook({ saasRoot, reason: 'smoke' });
+    for (const rel of result.providerJsonRelativePaths) {
+      await expect(fs.access(path.join(saasRoot, rel))).rejects.toThrow();
+    }
+    await expect(fs.access(path.join(saasRoot, result.providerSourceRelativePath))).rejects.toThrow();
+  });
+
+  it('always reports the canonical providerLockSectionPath', async () => {
+    const result = await runProviderMaterializationHook({ saasRoot, reason: 'update' });
+    expect(result.providerLockSectionPath).toBe('sections.providers.runtimeScopes');
+  });
+});

package/src/__tests__/provider-sync-runner.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Phase 2 tests for `runProviderSync`.
+ *
+ * The runner spawns `wildo config sync --domain config` and
+ * classifies failures into `RegistryProviderSyncFailedError`.
+ * We avoid a real `wildo` dependency by providing a stub script
+ * via the `wildoBinPath` override.
+ */
+
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  RegistryProviderSyncFailedError,
+  isRegistryError,
+} from '@wildo-ai/platform-config-lib';
+import { runProviderSync } from '../services/provider-sync-runner';
+
+let saasRoot: string;
+let stubDir: string;
+
+beforeEach(async () => {
+  saasRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'wildo-provider-sync-spec-'));
+  stubDir = await fs.mkdtemp(path.join(os.tmpdir(), 'wildo-provider-sync-stub-'));
+});
+
+afterEach(async () => {
+  await fs.rm(saasRoot, { recursive: true, force: true });
+  await fs.rm(stubDir, { recursive: true, force: true });
+});
+
+async function writeStub(name: string, body: string): Promise<string> {
+  const stubPath = path.join(stubDir, name);
+  await fs.writeFile(stubPath, body, 'utf8');
+  await fs.chmod(stubPath, 0o755);
+  return stubPath;
+}
+
+describe('runProviderSync (dry-run)', () => {
+  it('returns mode:dry-run without spawning anything', async () => {
+    const result = await runProviderSync({ saasRoot, reason: 'install', dryRun: true });
+    expect(result.mode).toBe('dry-run');
+    expect(result.exitCode).toBe(0);
+    expect(result.providerLockSectionPath).toBe('sections.providers.runtimeScopes');
+    expect(result.reason).toBe('install');
+  });
+});
+
+describe('runProviderSync (shell-out — success)', () => {
+  it('returns mode:shell-out and the stub exit code (0)', async () => {
+    const stub = await writeStub('wildo', '#!/bin/sh\nexit 0\n');
+    const result = await runProviderSync({
+      saasRoot,
+      reason: 'install',
+      wildoBinPath: stub,
+      timeoutMs: 5000,
+    });
+    expect(result.mode).toBe('shell-out');
+    expect(result.exitCode).toBe(0);
+  });
+});
+
+describe('runProviderSync (shell-out — failure classification)', () => {
+  async function expectFailureKind(
+    stderrBody: string,
+    expectedKind: 'companion-discovery' | 'runtime-import-reachability' | 'invalid-scope' | 'unknown',
+  ): Promise<void> {
+    const stub = await writeStub(
+      'wildo',
+      `#!/bin/sh\ncat 1>&2 <<'EOF'\n${stderrBody}\nEOF\nexit 1\n`,
+    );
+    let caught: unknown = null;
+    try {
+      await runProviderSync({
+        saasRoot,
+        reason: 'install',
+        wildoBinPath: stub,
+        timeoutMs: 5000,
+      });
+    } catch (err) {
+      caught = err;
+    }
+    expect(isRegistryError(caught)).toBe(true);
+    expect(caught).toBeInstanceOf(RegistryProviderSyncFailedError);
+    expect((caught as RegistryProviderSyncFailedError).failureKind).toBe(expectedKind);
+  }
+
+  it('classifies companion-export failures', async () => {
+    await expectFailureKind(
+      'Error: companion export missing for provider "resend" (DiscoveredProviderCompanionContribution)',
+      'companion-discovery',
+    );
+  });
+
+  it('classifies runtime-import reachability failures', async () => {
+    await expectFailureKind(
+      "Error: Cannot find module '@wildo-ai/auth-stub' from runtimeImport graph",
+      'runtime-import-reachability',
+    );
+  });
+
+  it('classifies invalid-scope failures', async () => {
+    await expectFailureKind(
+      'Error: defineSaaSProviders rejected invalid-scope "frontEnd": expected one of backend|companion|...',
+      'invalid-scope',
+    );
+  });
+
+  it('falls through to "unknown" on unrecognized stderr', async () => {
+    await expectFailureKind('Error: kaboom for unknown reasons', 'unknown');
+  });
+});