@wildo-ai/wildo-module-client 1.1.1

package/dist/esm/services/provider-materialization-hook.js

@@ -0,0 +1,33 @@
+/**
+ * `runProviderMaterializationHook` — Phase 0.5 dry-run hook.
+ *
+ * Phase 2 superseded this by `runProviderSync` (the real
+ * `wildo config sync --domain config` shell-out with classified
+ * failure surfaces). This file is kept as a thin
+ * `dryRun: true` forwarder so the Phase 0.5 lockfile-smoke
+ * command and any external caller continue to work unchanged.
+ *
+ * @deprecated Phase 2+ flows MUST call `runProviderSync` directly.
+ *   This forwarder will be removed once Wonder Todos's
+ *   `lockfile-smoke` command is rewritten in the Phase 4 CLI
+ *   read-flow series.
+ */
+import { runProviderSync } from './provider-sync-runner.js';
+export async function runProviderMaterializationHook(input) {
+    const result = await runProviderSync({
+        saasRoot: input.saasRoot,
+        reason: input.reason,
+        log: input.log,
+        dryRun: true,
+    });
+    return {
+        invoked: true,
+        mode: result.mode,
+        performedFsWrite: false,
+        providerJsonRelativePaths: result.providerJsonRelativePaths,
+        providerSourceRelativePath: result.providerSourceRelativePath,
+        providerLockSectionPath: result.providerLockSectionPath,
+        reason: result.reason,
+    };
+}
+//# sourceMappingURL=provider-materialization-hook.js.map

package/dist/esm/services/provider-materialization-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-materialization-hook.js","sourceRoot":"","sources":["../../../../src/services/provider-materialization-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAmBzD,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,KAAuC;IAEvC,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;QACnC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,IAAI;KACb,CAAC,CAAC;IACH,OAAO;QACL,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,gBAAgB,EAAE,KAAK;QACvB,yBAAyB,EAAE,MAAM,CAAC,yBAAyB;QAC3D,0BAA0B,EAAE,MAAM,CAAC,0BAA0B;QAC7D,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;QACvD,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * `runProviderMaterializationHook` — Phase 0.5 dry-run hook.\n *\n * Phase 2 superseded this by `runProviderSync` (the real\n * `wildo config sync --domain config` shell-out with classified\n * failure surfaces). This file is kept as a thin\n * `dryRun: true` forwarder so the Phase 0.5 lockfile-smoke\n * command and any external caller continue to work unchanged.\n *\n * @deprecated Phase 2+ flows MUST call `runProviderSync` directly.\n *   This forwarder will be removed once Wonder Todos's\n *   `lockfile-smoke` command is rewritten in the Phase 4 CLI\n *   read-flow series.\n */\n\nimport { PROVIDER_LOCK_SECTION_PATH } from '@wildo-ai/platform-config-lib';\nimport { runProviderSync } from './provider-sync-runner';\nimport type { RegistryClientLogger } from './types';\n\nexport interface ProviderMaterializationHookInput {\n  saasRoot: string;\n  reason: 'install' | 'update' | 'remove' | 'adopt' | 'smoke';\n  log?: RegistryClientLogger;\n}\n\nexport interface ProviderMaterializationHookResult {\n  invoked: true;\n  mode: 'dry-run' | 'shell-out';\n  performedFsWrite: false;\n  providerJsonRelativePaths: readonly string[];\n  providerSourceRelativePath: string;\n  providerLockSectionPath: typeof PROVIDER_LOCK_SECTION_PATH;\n  reason: ProviderMaterializationHookInput['reason'];\n}\n\nexport async function runProviderMaterializationHook(\n  input: ProviderMaterializationHookInput,\n): Promise<ProviderMaterializationHookResult> {\n  const result = await runProviderSync({\n    saasRoot: input.saasRoot,\n    reason: input.reason,\n    log: input.log,\n    dryRun: true,\n  });\n  return {\n    invoked: true,\n    mode: result.mode,\n    performedFsWrite: false,\n    providerJsonRelativePaths: result.providerJsonRelativePaths,\n    providerSourceRelativePath: result.providerSourceRelativePath,\n    providerLockSectionPath: result.providerLockSectionPath,\n    reason: result.reason,\n  };\n}\n"]}

package/dist/esm/services/provider-sync-runner.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `runProviderSync` — Phase 2 real shell-out to
+ * `wildo config sync --domain config`.
+ *
+ * Module-registry install/update/remove/adopt flows mutate app
+ * source. When that source changes provider implementations,
+ * provider companion exports, or provider scopes, the
+ * provider-runtime delivery layer must regenerate its outputs
+ * (KD-18). The canonical command is owned by the provider
+ * workstream — module-registry MUST delegate, not fork.
+ *
+ * Phase 0.5 / 1 shipped a no-op `runProviderMaterializationHook`
+ * that recorded intent. Phase 2 replaces it with a real
+ * `child_process.spawn`-based runner that:
+ *   - resolves the `wildo` CLI binary from the saas root's
+ *     `node_modules/.bin/wildo` (the workspace's own version);
+ *   - shells `wildo config sync --domain config` in the saas root;
+ *   - times out at the operator-configurable budget;
+ *   - classifies stderr-tail patterns into the
+ *     `RegistryProviderSyncFailedError.failureKind` discriminator
+ *     (`companion-discovery` / `runtime-import-reachability` /
+ *     `invalid-scope` / `unknown`) so callers report repairable
+ *     failures with first-class UX rather than generic install
+ *     noise (`module-registry-analysis.md` / Provider Migration
+ *     WIP Seams §1).
+ *
+ * Hard contract (KD-18): the runner NEVER writes provider runtime
+ * artifacts itself. It only invokes the provider workstream's
+ * canonical command. Tests assert no provider artifact is touched
+ * by this code path.
+ */
+import { PROVIDER_LOCK_SECTION_PATH } from '@wildo-ai/platform-config-lib';
+import type { RegistryClientLogger } from './types';
+export interface ProviderSyncRunnerInput {
+    /** Absolute path to the SaaS application root. */
+    saasRoot: string;
+    /** Reason for the call — drives diagnostic copy. */
+    reason: 'install' | 'update' | 'remove' | 'adopt' | 'smoke';
+    /** Optional logger. Defaults to no-op. */
+    log?: RegistryClientLogger;
+    /**
+     * Override the wildo CLI binary path. Defaults to
+     * `<saasRoot>/node_modules/.bin/wildo`. Phase 2 tests override
+     * this to point at a stub script.
+     */
+    wildoBinPath?: string;
+    /**
+     * Maximum wall-time before SIGTERM. Default 120s — provider sync
+     * can be heavy on first run (artifact generation + cleanup),
+     * but every additional second is operator-visible.
+     */
+    timeoutMs?: number;
+    /**
+     * If true, do NOT actually shell out — log the intent and
+     * resolve as `mode: 'dry-run'`. Used by the Phase 0.5 smoke
+     * command which intentionally cannot rely on a working
+     * `wildo` binary in the smoke sandbox.
+     */
+    dryRun?: boolean;
+}
+export interface ProviderSyncRunnerResult {
+    invoked: true;
+    /**
+     * `'shell-out'` when the runner spawned `wildo config sync`.
+     * `'dry-run'` when `dryRun: true` was passed (smoke flow).
+     */
+    mode: 'shell-out' | 'dry-run';
+    /** Exit code reported by the wildo binary (0 on success). */
+    exitCode: number | null;
+    /** Wall-clock duration (ms). */
+    durationMs: number;
+    /** Reason that was passed in. */
+    reason: ProviderSyncRunnerInput['reason'];
+    /** Provider-output paths the canonical sync would refresh. */
+    providerJsonRelativePaths: readonly string[];
+    /** Source module the Node-runtime consumes. */
+    providerSourceRelativePath: string;
+    /** Provider lock section the materializer owns end-to-end. */
+    providerLockSectionPath: typeof PROVIDER_LOCK_SECTION_PATH;
+}
+/**
+ * Run the canonical provider-sync command. Throws
+ * `RegistryProviderSyncFailedError` (with classified `failureKind`)
+ * when the spawned process exits non-zero or fails to start.
+ */
+export declare function runProviderSync(input: ProviderSyncRunnerInput): Promise<ProviderSyncRunnerResult>;
+//# sourceMappingURL=provider-sync-runner.d.ts.map

package/dist/esm/services/provider-sync-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-sync-runner.d.ts","sourceRoot":"","sources":["../../../../src/services/provider-sync-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,EACL,0BAA0B,EAI3B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAIpD,MAAM,WAAW,uBAAuB;IACtC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;IAC5D,0CAA0C;IAC1C,GAAG,CAAC,EAAE,oBAAoB,CAAC;IAC3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,IAAI,CAAC;IACd;;;OAGG;IACH,IAAI,EAAE,WAAW,GAAG,SAAS,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,MAAM,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC1C,8DAA8D;IAC9D,yBAAyB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,+CAA+C;IAC/C,0BAA0B,EAAE,MAAM,CAAC;IACnC,8DAA8D;IAC9D,uBAAuB,EAAE,OAAO,0BAA0B,CAAC;CAC5D;AA+ID;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,wBAAwB,CAAC,CAuDnC"}

package/dist/esm/services/provider-sync-runner.js

@@ -0,0 +1,207 @@
+/**
+ * `runProviderSync` — Phase 2 real shell-out to
+ * `wildo config sync --domain config`.
+ *
+ * Module-registry install/update/remove/adopt flows mutate app
+ * source. When that source changes provider implementations,
+ * provider companion exports, or provider scopes, the
+ * provider-runtime delivery layer must regenerate its outputs
+ * (KD-18). The canonical command is owned by the provider
+ * workstream — module-registry MUST delegate, not fork.
+ *
+ * Phase 0.5 / 1 shipped a no-op `runProviderMaterializationHook`
+ * that recorded intent. Phase 2 replaces it with a real
+ * `child_process.spawn`-based runner that:
+ *   - resolves the `wildo` CLI binary from the saas root's
+ *     `node_modules/.bin/wildo` (the workspace's own version);
+ *   - shells `wildo config sync --domain config` in the saas root;
+ *   - times out at the operator-configurable budget;
+ *   - classifies stderr-tail patterns into the
+ *     `RegistryProviderSyncFailedError.failureKind` discriminator
+ *     (`companion-discovery` / `runtime-import-reachability` /
+ *     `invalid-scope` / `unknown`) so callers report repairable
+ *     failures with first-class UX rather than generic install
+ *     noise (`module-registry-analysis.md` / Provider Migration
+ *     WIP Seams §1).
+ *
+ * Hard contract (KD-18): the runner NEVER writes provider runtime
+ * artifacts itself. It only invokes the provider workstream's
+ * canonical command. Tests assert no provider artifact is touched
+ * by this code path.
+ */
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { PROVIDER_LOCK_SECTION_PATH, PROVIDER_RUNTIME_ARTIFACT_RELATIVE_PATHS, PROVIDER_RUNTIME_GENERATED_MODULE_RELATIVE_PATH, RegistryProviderSyncFailedError, } from '@wildo-ai/platform-config-lib';
+const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * Provider artifact paths sourced from the canonical
+ * `PROVIDER_RUNTIME_ARTIFACT_RELATIVE_PATHS` constant in
+ * `platform-config-lib`. Refactored on 2026-05-06 to import the
+ * single source of truth instead of duplicating the literal paths
+ * here — the artifacts moved from `.wildo-saas/providers/` to
+ * `.wildo-saas/generated/providers/` and any duplication would
+ * silently drift.
+ */
+const PROVIDER_JSON_RELATIVE_PATHS = Object.values(PROVIDER_RUNTIME_ARTIFACT_RELATIVE_PATHS);
+const PROVIDER_SOURCE_RELATIVE_PATH = PROVIDER_RUNTIME_GENERATED_MODULE_RELATIVE_PATH;
+/**
+ * Classify a `wildo config sync` failure based on its stderr tail.
+ * The matchers mirror the failure modes the provider workstream
+ * surfaces today; new modes get a new branch + a new
+ * discriminator value (out of `RegistryProviderSyncFailedError`).
+ */
+function classifyStderr(stderr) {
+    const tail = stderr.slice(-2000);
+    // Companion-export discovery failure — the provider sync walks
+    // each owner package's `./companion` export to discover provider
+    // contributions. A package whose export contract is broken
+    // surfaces a "companion export" / "DiscoveredProviderCompanionContribution"
+    // error.
+    if (/companion[- ]export|DiscoveredProviderCompanionContribution|companion-discovery/i.test(tail)) {
+        return 'companion-discovery';
+    }
+    // Runtime-import reachability — the materializer can't resolve a
+    // contributed `runtimeImport` against the owning runtime package
+    // graph. Typical messages mention `runtimeImport`, `Cannot find
+    // module`, or `MODULE_NOT_FOUND`.
+    if (/runtimeImport|MODULE_NOT_FOUND|Cannot find module|cannot resolve/i.test(tail)) {
+        return 'runtime-import-reachability';
+    }
+    // Scope validation — `defineSaaSProviders({ scopes })` rejects
+    // malformed scope inputs ahead of materialization.
+    if (/defineSaaSProviders|invalid[- ]scope|providers\.scopes/i.test(tail)) {
+        return 'invalid-scope';
+    }
+    return 'unknown';
+}
+async function resolveWildoBin(input) {
+    if (input.wildoBinPath)
+        return input.wildoBinPath;
+    const candidate = path.join(input.saasRoot, 'node_modules', '.bin', 'wildo');
+    try {
+        await fs.access(candidate);
+        return candidate;
+    }
+    catch {
+        // Fall back to PATH-resolved `wildo`. spawn will raise ENOENT
+        // if it's not on PATH either, surfaced as
+        // `RegistryProviderSyncFailedError(failureKind: 'unknown')`.
+        return 'wildo';
+    }
+}
+/**
+ * Grace window between SIGTERM and SIGKILL. A well-behaved
+ * `wildo config sync` should react to SIGTERM in well under a
+ * second — the grace exists for tools that need to flush a buffer
+ * or release a file lock. After the window we escalate to SIGKILL
+ * so a hung child cannot pin the parent forever.
+ */
+const SIGKILL_GRACE_MS = 5_000;
+function runWildoConfigSync(binPath, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        const startedAt = Date.now();
+        const child = spawn(binPath, ['config', 'sync', '--domain', 'config'], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stderr = '';
+        let signaled = false;
+        let killTimer;
+        child.stderr?.on('data', (b) => {
+            // Cap captured stderr so a runaway sync can't OOM the parent.
+            stderr += b.toString();
+            if (stderr.length > 16_384)
+                stderr = stderr.slice(-16_384);
+        });
+        const termTimer = setTimeout(() => {
+            // Soft-kill first; record so the caller can synthesize a
+            // diagnostic message that distinguishes a TERM-induced exit
+            // from a normal one.
+            signaled = true;
+            stderr += `\n[provider-sync] timeout ${timeoutMs}ms exceeded — sent SIGTERM.`;
+            child.kill('SIGTERM');
+            // Escalate to SIGKILL if the child doesn't react within the
+            // grace window. Without this a child stuck in a syscall (or
+            // deliberately ignoring SIGTERM) would leave the parent
+            // blocked on the spawn promise forever.
+            killTimer = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null) {
+                    stderr += `\n[provider-sync] SIGTERM grace ${SIGKILL_GRACE_MS}ms exceeded — escalating to SIGKILL.`;
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch {
+                        /* swallow — best-effort escalation */
+                    }
+                }
+            }, SIGKILL_GRACE_MS);
+        }, timeoutMs);
+        child.on('exit', (code) => {
+            clearTimeout(termTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            resolve({
+                exitCode: code,
+                stderr,
+                durationMs: Date.now() - startedAt,
+                signaled,
+            });
+        });
+        child.on('error', (err) => {
+            clearTimeout(termTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            resolve({
+                exitCode: null,
+                stderr: stderr + `\n[spawn error] ${err.message}`,
+                durationMs: Date.now() - startedAt,
+                signaled,
+            });
+        });
+    });
+}
+/**
+ * Run the canonical provider-sync command. Throws
+ * `RegistryProviderSyncFailedError` (with classified `failureKind`)
+ * when the spawned process exits non-zero or fails to start.
+ */
+export async function runProviderSync(input) {
+    const log = input.log;
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const baseResult = {
+        invoked: true,
+        reason: input.reason,
+        providerJsonRelativePaths: PROVIDER_JSON_RELATIVE_PATHS,
+        providerSourceRelativePath: PROVIDER_SOURCE_RELATIVE_PATH,
+        providerLockSectionPath: PROVIDER_LOCK_SECTION_PATH,
+    };
+    if (input.dryRun) {
+        log?.info?.(`[registry] post-${input.reason} provider sync (dry-run): would shell ` +
+            `\`wildo config sync --domain config\` in ${input.saasRoot}.`);
+        return { ...baseResult, mode: 'dry-run', exitCode: 0, durationMs: 0 };
+    }
+    const binPath = await resolveWildoBin(input);
+    log?.info?.(`[registry] post-${input.reason} provider sync: spawning ` +
+        `${binPath} config sync --domain config (cwd=${input.saasRoot}, timeout=${timeoutMs}ms)`);
+    const { exitCode, stderr, durationMs, signaled } = await runWildoConfigSync(binPath, input.saasRoot, timeoutMs);
+    if (exitCode === 0) {
+        log?.success?.(`[registry] provider sync succeeded in ${durationMs}ms.`);
+        return { ...baseResult, mode: 'shell-out', exitCode, durationMs };
+    }
+    // H5: distinguish a timeout-signaled exit from a generic non-zero
+    // exit. `classifyStderr` runs regex against the appended
+    // `[provider-sync] timeout ... SIGTERM/SIGKILL` lines but those
+    // tails match no failure-mode regex — so prior to this branch
+    // operators saw `failureKind: 'unknown'` for a hard timeout. The
+    // typed error now carries the discriminator + a hint to either
+    // raise the timeout or investigate the wedge.
+    const failureKind = signaled ? 'timeout' : classifyStderr(stderr);
+    log?.error?.(`[registry] provider sync failed (${failureKind}, exit=${exitCode}, ${durationMs}ms).`);
+    const messageSuffix = failureKind === 'timeout'
+        ? `Wall-clock exceeded ${timeoutMs}ms; child was sent SIGTERM (then SIGKILL after grace). ` +
+            'Either raise `timeoutMs` for legitimately heavy syncs or investigate why the sync wedged.'
+        : 'Run `wildo config sync --domain config` manually to inspect.';
+    throw new RegistryProviderSyncFailedError(`Post-${input.reason} provider sync failed (${failureKind}). ${messageSuffix}`, failureKind, stderr.slice(-1024));
+}
+//# sourceMappingURL=provider-sync-runner.js.map

package/dist/esm/services/provider-sync-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-sync-runner.js","sourceRoot":"","sources":["../../../../src/services/provider-sync-runner.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `runProviderSync` — Phase 2 real shell-out to\n * `wildo config sync --domain config`.\n *\n * Module-registry install/update/remove/adopt flows mutate app\n * source. When that source changes provider implementations,\n * provider companion exports, or provider scopes, the\n * provider-runtime delivery layer must regenerate its outputs\n * (KD-18). The canonical command is owned by the provider\n * workstream — module-registry MUST delegate, not fork.\n *\n * Phase 0.5 / 1 shipped a no-op `runProviderMaterializationHook`\n * that recorded intent. Phase 2 replaces it with a real\n * `child_process.spawn`-based runner that:\n *   - resolves the `wildo` CLI binary from the saas root's\n *     `node_modules/.bin/wildo` (the workspace's own version);\n *   - shells `wildo config sync --domain config` in the saas root;\n *   - times out at the operator-configurable budget;\n *   - classifies stderr-tail patterns into the\n *     `RegistryProviderSyncFailedError.failureKind` discriminator\n *     (`companion-discovery` / `runtime-import-reachability` /\n *     `invalid-scope` / `unknown`) so callers report repairable\n *     failures with first-class UX rather than generic install\n *     noise (`module-registry-analysis.md` / Provider Migration\n *     WIP Seams §1).\n *\n * Hard contract (KD-18): the runner NEVER writes provider runtime\n * artifacts itself. It only invokes the provider workstream's\n * canonical command. Tests assert no provider artifact is touched\n * by this code path.\n */\n\nimport { spawn } from 'node:child_process';\nimport { promises as fs } from 'node:fs';\nimport * as path from 'node:path';\nimport {\n  PROVIDER_LOCK_SECTION_PATH,\n  PROVIDER_RUNTIME_ARTIFACT_RELATIVE_PATHS,\n  PROVIDER_RUNTIME_GENERATED_MODULE_RELATIVE_PATH,\n  RegistryProviderSyncFailedError,\n} from '@wildo-ai/platform-config-lib';\nimport type { RegistryClientLogger } from './types';\n\nconst DEFAULT_TIMEOUT_MS = 120_000;\n\nexport interface ProviderSyncRunnerInput {\n  /** Absolute path to the SaaS application root. */\n  saasRoot: string;\n  /** Reason for the call — drives diagnostic copy. */\n  reason: 'install' | 'update' | 'remove' | 'adopt' | 'smoke';\n  /** Optional logger. Defaults to no-op. */\n  log?: RegistryClientLogger;\n  /**\n   * Override the wildo CLI binary path. Defaults to\n   * `<saasRoot>/node_modules/.bin/wildo`. Phase 2 tests override\n   * this to point at a stub script.\n   */\n  wildoBinPath?: string;\n  /**\n   * Maximum wall-time before SIGTERM. Default 120s — provider sync\n   * can be heavy on first run (artifact generation + cleanup),\n   * but every additional second is operator-visible.\n   */\n  timeoutMs?: number;\n  /**\n   * If true, do NOT actually shell out — log the intent and\n   * resolve as `mode: 'dry-run'`. Used by the Phase 0.5 smoke\n   * command which intentionally cannot rely on a working\n   * `wildo` binary in the smoke sandbox.\n   */\n  dryRun?: boolean;\n}\n\nexport interface ProviderSyncRunnerResult {\n  invoked: true;\n  /**\n   * `'shell-out'` when the runner spawned `wildo config sync`.\n   * `'dry-run'` when `dryRun: true` was passed (smoke flow).\n   */\n  mode: 'shell-out' | 'dry-run';\n  /** Exit code reported by the wildo binary (0 on success). */\n  exitCode: number | null;\n  /** Wall-clock duration (ms). */\n  durationMs: number;\n  /** Reason that was passed in. */\n  reason: ProviderSyncRunnerInput['reason'];\n  /** Provider-output paths the canonical sync would refresh. */\n  providerJsonRelativePaths: readonly string[];\n  /** Source module the Node-runtime consumes. */\n  providerSourceRelativePath: string;\n  /** Provider lock section the materializer owns end-to-end. */\n  providerLockSectionPath: typeof PROVIDER_LOCK_SECTION_PATH;\n}\n\n/**\n * Provider artifact paths sourced from the canonical\n * `PROVIDER_RUNTIME_ARTIFACT_RELATIVE_PATHS` constant in\n * `platform-config-lib`. Refactored on 2026-05-06 to import the\n * single source of truth instead of duplicating the literal paths\n * here — the artifacts moved from `.wildo-saas/providers/` to\n * `.wildo-saas/generated/providers/` and any duplication would\n * silently drift.\n */\nconst PROVIDER_JSON_RELATIVE_PATHS = Object.values(\n  PROVIDER_RUNTIME_ARTIFACT_RELATIVE_PATHS,\n) as readonly string[];\n\nconst PROVIDER_SOURCE_RELATIVE_PATH = PROVIDER_RUNTIME_GENERATED_MODULE_RELATIVE_PATH;\n\n/**\n * Classify a `wildo config sync` failure based on its stderr tail.\n * The matchers mirror the failure modes the provider workstream\n * surfaces today; new modes get a new branch + a new\n * discriminator value (out of `RegistryProviderSyncFailedError`).\n */\nfunction classifyStderr(\n  stderr: string,\n): 'companion-discovery' | 'runtime-import-reachability' | 'invalid-scope' | 'unknown' {\n  const tail = stderr.slice(-2000);\n  // Companion-export discovery failure — the provider sync walks\n  // each owner package's `./companion` export to discover provider\n  // contributions. A package whose export contract is broken\n  // surfaces a \"companion export\" / \"DiscoveredProviderCompanionContribution\"\n  // error.\n  if (\n    /companion[- ]export|DiscoveredProviderCompanionContribution|companion-discovery/i.test(tail)\n  ) {\n    return 'companion-discovery';\n  }\n  // Runtime-import reachability — the materializer can't resolve a\n  // contributed `runtimeImport` against the owning runtime package\n  // graph. Typical messages mention `runtimeImport`, `Cannot find\n  // module`, or `MODULE_NOT_FOUND`.\n  if (\n    /runtimeImport|MODULE_NOT_FOUND|Cannot find module|cannot resolve/i.test(tail)\n  ) {\n    return 'runtime-import-reachability';\n  }\n  // Scope validation — `defineSaaSProviders({ scopes })` rejects\n  // malformed scope inputs ahead of materialization.\n  if (\n    /defineSaaSProviders|invalid[- ]scope|providers\\.scopes/i.test(tail)\n  ) {\n    return 'invalid-scope';\n  }\n  return 'unknown';\n}\n\nasync function resolveWildoBin(input: ProviderSyncRunnerInput): Promise<string> {\n  if (input.wildoBinPath) return input.wildoBinPath;\n  const candidate = path.join(input.saasRoot, 'node_modules', '.bin', 'wildo');\n  try {\n    await fs.access(candidate);\n    return candidate;\n  } catch {\n    // Fall back to PATH-resolved `wildo`. spawn will raise ENOENT\n    // if it's not on PATH either, surfaced as\n    // `RegistryProviderSyncFailedError(failureKind: 'unknown')`.\n    return 'wildo';\n  }\n}\n\n/**\n * Grace window between SIGTERM and SIGKILL. A well-behaved\n * `wildo config sync` should react to SIGTERM in well under a\n * second — the grace exists for tools that need to flush a buffer\n * or release a file lock. After the window we escalate to SIGKILL\n * so a hung child cannot pin the parent forever.\n */\nconst SIGKILL_GRACE_MS = 5_000;\n\nfunction runWildoConfigSync(\n  binPath: string,\n  cwd: string,\n  timeoutMs: number,\n): Promise<{ exitCode: number | null; stderr: string; durationMs: number; signaled: boolean }> {\n  return new Promise((resolve) => {\n    const startedAt = Date.now();\n    const child = spawn(binPath, ['config', 'sync', '--domain', 'config'], {\n      cwd,\n      stdio: ['ignore', 'pipe', 'pipe'],\n    });\n    let stderr = '';\n    let signaled = false;\n    let killTimer: NodeJS.Timeout | undefined;\n    child.stderr?.on('data', (b: Buffer) => {\n      // Cap captured stderr so a runaway sync can't OOM the parent.\n      stderr += b.toString();\n      if (stderr.length > 16_384) stderr = stderr.slice(-16_384);\n    });\n    const termTimer = setTimeout(() => {\n      // Soft-kill first; record so the caller can synthesize a\n      // diagnostic message that distinguishes a TERM-induced exit\n      // from a normal one.\n      signaled = true;\n      stderr += `\\n[provider-sync] timeout ${timeoutMs}ms exceeded — sent SIGTERM.`;\n      child.kill('SIGTERM');\n      // Escalate to SIGKILL if the child doesn't react within the\n      // grace window. Without this a child stuck in a syscall (or\n      // deliberately ignoring SIGTERM) would leave the parent\n      // blocked on the spawn promise forever.\n      killTimer = setTimeout(() => {\n        if (child.exitCode === null && child.signalCode === null) {\n          stderr += `\\n[provider-sync] SIGTERM grace ${SIGKILL_GRACE_MS}ms exceeded — escalating to SIGKILL.`;\n          try {\n            child.kill('SIGKILL');\n          } catch {\n            /* swallow — best-effort escalation */\n          }\n        }\n      }, SIGKILL_GRACE_MS);\n    }, timeoutMs);\n    child.on('exit', (code) => {\n      clearTimeout(termTimer);\n      if (killTimer) clearTimeout(killTimer);\n      resolve({\n        exitCode: code,\n        stderr,\n        durationMs: Date.now() - startedAt,\n        signaled,\n      });\n    });\n    child.on('error', (err) => {\n      clearTimeout(termTimer);\n      if (killTimer) clearTimeout(killTimer);\n      resolve({\n        exitCode: null,\n        stderr: stderr + `\\n[spawn error] ${err.message}`,\n        durationMs: Date.now() - startedAt,\n        signaled,\n      });\n    });\n  });\n}\n\n/**\n * Run the canonical provider-sync command. Throws\n * `RegistryProviderSyncFailedError` (with classified `failureKind`)\n * when the spawned process exits non-zero or fails to start.\n */\nexport async function runProviderSync(\n  input: ProviderSyncRunnerInput,\n): Promise<ProviderSyncRunnerResult> {\n  const log = input.log;\n  const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const baseResult = {\n    invoked: true as const,\n    reason: input.reason,\n    providerJsonRelativePaths: PROVIDER_JSON_RELATIVE_PATHS,\n    providerSourceRelativePath: PROVIDER_SOURCE_RELATIVE_PATH,\n    providerLockSectionPath: PROVIDER_LOCK_SECTION_PATH,\n  };\n\n  if (input.dryRun) {\n    log?.info?.(\n      `[registry] post-${input.reason} provider sync (dry-run): would shell ` +\n      `\\`wildo config sync --domain config\\` in ${input.saasRoot}.`,\n    );\n    return { ...baseResult, mode: 'dry-run', exitCode: 0, durationMs: 0 };\n  }\n\n  const binPath = await resolveWildoBin(input);\n  log?.info?.(\n    `[registry] post-${input.reason} provider sync: spawning ` +\n    `${binPath} config sync --domain config (cwd=${input.saasRoot}, timeout=${timeoutMs}ms)`,\n  );\n  const { exitCode, stderr, durationMs, signaled } = await runWildoConfigSync(\n    binPath,\n    input.saasRoot,\n    timeoutMs,\n  );\n\n  if (exitCode === 0) {\n    log?.success?.(`[registry] provider sync succeeded in ${durationMs}ms.`);\n    return { ...baseResult, mode: 'shell-out', exitCode, durationMs };\n  }\n\n  // H5: distinguish a timeout-signaled exit from a generic non-zero\n  // exit. `classifyStderr` runs regex against the appended\n  // `[provider-sync] timeout ... SIGTERM/SIGKILL` lines but those\n  // tails match no failure-mode regex — so prior to this branch\n  // operators saw `failureKind: 'unknown'` for a hard timeout. The\n  // typed error now carries the discriminator + a hint to either\n  // raise the timeout or investigate the wedge.\n  const failureKind = signaled ? ('timeout' as const) : classifyStderr(stderr);\n  log?.error?.(\n    `[registry] provider sync failed (${failureKind}, exit=${exitCode}, ${durationMs}ms).`,\n  );\n  const messageSuffix = failureKind === 'timeout'\n    ? `Wall-clock exceeded ${timeoutMs}ms; child was sent SIGTERM (then SIGKILL after grace). ` +\n      'Either raise `timeoutMs` for legitimately heavy syncs or investigate why the sync wedged.'\n    : 'Run `wildo config sync --domain config` manually to inspect.';\n  throw new RegistryProviderSyncFailedError(\n    `Post-${input.reason} provider sync failed (${failureKind}). ${messageSuffix}`,\n    failureKind,\n    stderr.slice(-1024),\n  );\n}\n"]}

package/dist/esm/services/registry-companion-client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `RegistryCompanionClient` — HTTP client for the local dev
+ * companion's registry routes.
+ *
+ * Distinct from `RegistryServerClient` (which talks to the central
+ * `platform-module-registry` server). The companion client targets
+ * `/api/companion/registry/*` on `http://localhost:<companion-port>`
+ * for AST/source mutations the CLI delegates to the companion
+ * (KD-6).
+ *
+ * Phase 2 ships the four mutation routes as method calls; the
+ * companion controller (under
+ * `platform/factory/wildo-dev-companion/src/companion-api/controllers/`)
+ * implements them with the actual ts-morph + filesystem work in
+ * Phase 5+.
+ */
+import { type RegistryInstallRequest, type RegistryPublishRequest, type RegistryRemoveRequest, type RegistryRouteResult, type RegistryUpdateRequest } from '@wildo-ai/platform-config-lib';
+export interface RegistryCompanionClientOptions {
+    baseUrl: string;
+    timeoutMs?: number;
+}
+export declare const RegistryCompanionClient: {
+    /**
+     * Liveness probe against `/health` (the same endpoint the
+     * dev-supervisor monitors). Used by `wildo registry ping`.
+     */
+    readonly ping: (options: RegistryCompanionClientOptions) => Promise<boolean>;
+    /**
+     * Ask the companion to install a module: download bytes, copy
+     * source, mutate `wildo.saas.config.ts > moduleRegistries` +
+     * the three `modules-registry.*.ts` files, refresh
+     * `sections.modules`, run provider sync.
+     */
+    readonly install: (options: RegistryCompanionClientOptions, request: RegistryInstallRequest) => Promise<RegistryRouteResult>;
+    readonly update: (options: RegistryCompanionClientOptions, request: RegistryUpdateRequest) => Promise<RegistryRouteResult>;
+    readonly remove: (options: RegistryCompanionClientOptions, request: RegistryRemoveRequest) => Promise<RegistryRouteResult>;
+    readonly publish: (options: RegistryCompanionClientOptions, request: RegistryPublishRequest) => Promise<RegistryRouteResult>;
+};
+//# sourceMappingURL=registry-companion-client.d.ts.map

package/dist/esm/services/registry-companion-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-companion-client.d.ts","sourceRoot":"","sources":["../../../../src/services/registry-companion-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAKL,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC3B,MAAM,+BAA+B,CAAC;AAMvC,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA2CD,eAAO,MAAM,uBAAuB;IAClC;;;OAGG;6BACiB,8BAA8B,KAAG,OAAO,CAAC,OAAO,CAAC;IAcrE;;;;;OAKG;gCAEQ,8BAA8B,WAC9B,sBAAsB,KAC9B,OAAO,CAAC,mBAAmB,CAAC;+BAMpB,8BAA8B,WAC9B,qBAAqB,KAC7B,OAAO,CAAC,mBAAmB,CAAC;+BAMpB,8BAA8B,WAC9B,qBAAqB,KAC7B,OAAO,CAAC,mBAAmB,CAAC;gCAMpB,8BAA8B,WAC9B,sBAAsB,KAC9B,OAAO,CAAC,mBAAmB,CAAC;CAIvB,CAAC"}

package/dist/esm/services/registry-companion-client.js

@@ -0,0 +1,109 @@
+/**
+ * `RegistryCompanionClient` — HTTP client for the local dev
+ * companion's registry routes.
+ *
+ * Distinct from `RegistryServerClient` (which talks to the central
+ * `platform-module-registry` server). The companion client targets
+ * `/api/companion/registry/*` on `http://localhost:<companion-port>`
+ * for AST/source mutations the CLI delegates to the companion
+ * (KD-6).
+ *
+ * Phase 2 ships the four mutation routes as method calls; the
+ * companion controller (under
+ * `platform/factory/wildo-dev-companion/src/companion-api/controllers/`)
+ * implements them with the actual ts-morph + filesystem work in
+ * Phase 5+.
+ */
+import { REGISTRY_COMPANION_ROUTES, RegistryMalformedPayloadError, RegistryRouteResultSchema, RegistryUnexpectedStatusError, } from '@wildo-ai/platform-config-lib';
+import { fetchWithTimeout, joinUrl } from './_http-client.js';
+import { formatZodIssuesAsSingleLine } from './_zod-issue-formatting.js';
+const DIAGNOSTIC_LABEL = 'Companion registry';
+async function postJson(options, routePath, body) {
+    const url = joinUrl(options.baseUrl, routePath);
+    const res = await fetchWithTimeout(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        timeoutMs: options.timeoutMs,
+        diagnosticLabel: DIAGNOSTIC_LABEL,
+    });
+    if (!res.ok) {
+        // 3rd-pass M5: typed `RegistryUnexpectedStatusError` instead of
+        // bare `new Error(...)` so callers can `isRegistryError(err)` and
+        // discriminate by status code without re-parsing message text.
+        // The companion deliberately reuses the same error vocabulary
+        // as `RegistryServerClient` since the wire shape (status + URL +
+        // action) is identical even though the lane is different.
+        throw new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, `companion ${routePath}`);
+    }
+    // 6th-pass M3: typed JSON-parse — a misconfigured proxy returning
+    // HTML at 2xx would otherwise throw a bare `SyntaxError` that
+    // bypasses the typed-error contract.
+    try {
+        return (await res.json());
+    }
+    catch (err) {
+        throw new RegistryMalformedPayloadError(options.baseUrl, `companion ${routePath}`, `response is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export const RegistryCompanionClient = {
+    /**
+     * Liveness probe against `/health` (the same endpoint the
+     * dev-supervisor monitors). Used by `wildo registry ping`.
+     */
+    async ping(options) {
+        const url = joinUrl(options.baseUrl, '/health');
+        try {
+            const res = await fetchWithTimeout(url, {
+                method: 'GET',
+                timeoutMs: options.timeoutMs,
+                diagnosticLabel: DIAGNOSTIC_LABEL,
+            });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    },
+    /**
+     * Ask the companion to install a module: download bytes, copy
+     * source, mutate `wildo.saas.config.ts > moduleRegistries` +
+     * the three `modules-registry.*.ts` files, refresh
+     * `sections.modules`, run provider sync.
+     */
+    async install(options, request) {
+        const raw = await postJson(options, REGISTRY_COMPANION_ROUTES.install, request);
+        return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.install, raw);
+    },
+    async update(options, request) {
+        const raw = await postJson(options, REGISTRY_COMPANION_ROUTES.update, request);
+        return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.update, raw);
+    },
+    async remove(options, request) {
+        const raw = await postJson(options, REGISTRY_COMPANION_ROUTES.remove, request);
+        return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.remove, raw);
+    },
+    async publish(options, request) {
+        const raw = await postJson(options, REGISTRY_COMPANION_ROUTES.publish, request);
+        return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.publish, raw);
+    },
+};
+/**
+ * M5: thin wrapper around `RegistryRouteResultSchema.parse(raw)` that
+ * converts a Zod parse failure into the typed
+ * `RegistryMalformedPayloadError` instead of letting a bare `ZodError`
+ * bubble up. Keeps the typed-handler contract aligned with
+ * `RegistryServerClient`.
+ */
+function parseCompanionResult(baseUrl, routePath, raw) {
+    const parsed = RegistryRouteResultSchema.safeParse(raw);
+    if (!parsed.success) {
+        // 7th-pass C-L2: format the issues array for operator
+        // readability instead of using Zod 4's JSON-stringified
+        // `error.message`.
+        const detail = formatZodIssuesAsSingleLine(parsed.error);
+        throw new RegistryMalformedPayloadError(baseUrl, `companion ${routePath}`, detail);
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=registry-companion-client.js.map

package/dist/esm/services/registry-companion-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-companion-client.js","sourceRoot":"","sources":["../../../../src/services/registry-companion-client.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `RegistryCompanionClient` — HTTP client for the local dev\n * companion's registry routes.\n *\n * Distinct from `RegistryServerClient` (which talks to the central\n * `platform-module-registry` server). The companion client targets\n * `/api/companion/registry/*` on `http://localhost:<companion-port>`\n * for AST/source mutations the CLI delegates to the companion\n * (KD-6).\n *\n * Phase 2 ships the four mutation routes as method calls; the\n * companion controller (under\n * `platform/factory/wildo-dev-companion/src/companion-api/controllers/`)\n * implements them with the actual ts-morph + filesystem work in\n * Phase 5+.\n */\n\nimport {\n  REGISTRY_COMPANION_ROUTES,\n  RegistryMalformedPayloadError,\n  RegistryRouteResultSchema,\n  RegistryUnexpectedStatusError,\n  type RegistryInstallRequest,\n  type RegistryPublishRequest,\n  type RegistryRemoveRequest,\n  type RegistryRouteResult,\n  type RegistryUpdateRequest,\n} from '@wildo-ai/platform-config-lib';\nimport { fetchWithTimeout, joinUrl } from './_http-client';\nimport { formatZodIssuesAsSingleLine } from './_zod-issue-formatting';\n\nconst DIAGNOSTIC_LABEL = 'Companion registry';\n\nexport interface RegistryCompanionClientOptions {\n  baseUrl: string;\n  timeoutMs?: number;\n}\n\nasync function postJson<R>(\n  options: RegistryCompanionClientOptions,\n  routePath: string,\n  body: unknown,\n): Promise<R> {\n  const url = joinUrl(options.baseUrl, routePath);\n  const res = await fetchWithTimeout(url, {\n    method: 'POST',\n    headers: { 'content-type': 'application/json' },\n    body: JSON.stringify(body),\n    timeoutMs: options.timeoutMs,\n    diagnosticLabel: DIAGNOSTIC_LABEL,\n  });\n  if (!res.ok) {\n    // 3rd-pass M5: typed `RegistryUnexpectedStatusError` instead of\n    // bare `new Error(...)` so callers can `isRegistryError(err)` and\n    // discriminate by status code without re-parsing message text.\n    // The companion deliberately reuses the same error vocabulary\n    // as `RegistryServerClient` since the wire shape (status + URL +\n    // action) is identical even though the lane is different.\n    throw new RegistryUnexpectedStatusError(\n      options.baseUrl,\n      res.status,\n      res.statusText,\n      `companion ${routePath}`,\n    );\n  }\n  // 6th-pass M3: typed JSON-parse — a misconfigured proxy returning\n  // HTML at 2xx would otherwise throw a bare `SyntaxError` that\n  // bypasses the typed-error contract.\n  try {\n    return (await res.json()) as R;\n  } catch (err) {\n    throw new RegistryMalformedPayloadError(\n      options.baseUrl,\n      `companion ${routePath}`,\n      `response is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,\n    );\n  }\n}\n\nexport const RegistryCompanionClient = {\n  /**\n   * Liveness probe against `/health` (the same endpoint the\n   * dev-supervisor monitors). Used by `wildo registry ping`.\n   */\n  async ping(options: RegistryCompanionClientOptions): Promise<boolean> {\n    const url = joinUrl(options.baseUrl, '/health');\n    try {\n      const res = await fetchWithTimeout(url, {\n        method: 'GET',\n        timeoutMs: options.timeoutMs,\n        diagnosticLabel: DIAGNOSTIC_LABEL,\n      });\n      return res.ok;\n    } catch {\n      return false;\n    }\n  },\n\n  /**\n   * Ask the companion to install a module: download bytes, copy\n   * source, mutate `wildo.saas.config.ts > moduleRegistries` +\n   * the three `modules-registry.*.ts` files, refresh\n   * `sections.modules`, run provider sync.\n   */\n  async install(\n    options: RegistryCompanionClientOptions,\n    request: RegistryInstallRequest,\n  ): Promise<RegistryRouteResult> {\n    const raw = await postJson<unknown>(options, REGISTRY_COMPANION_ROUTES.install, request);\n    return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.install, raw);\n  },\n\n  async update(\n    options: RegistryCompanionClientOptions,\n    request: RegistryUpdateRequest,\n  ): Promise<RegistryRouteResult> {\n    const raw = await postJson<unknown>(options, REGISTRY_COMPANION_ROUTES.update, request);\n    return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.update, raw);\n  },\n\n  async remove(\n    options: RegistryCompanionClientOptions,\n    request: RegistryRemoveRequest,\n  ): Promise<RegistryRouteResult> {\n    const raw = await postJson<unknown>(options, REGISTRY_COMPANION_ROUTES.remove, request);\n    return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.remove, raw);\n  },\n\n  async publish(\n    options: RegistryCompanionClientOptions,\n    request: RegistryPublishRequest,\n  ): Promise<RegistryRouteResult> {\n    const raw = await postJson<unknown>(options, REGISTRY_COMPANION_ROUTES.publish, request);\n    return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.publish, raw);\n  },\n} as const;\n\n/**\n * M5: thin wrapper around `RegistryRouteResultSchema.parse(raw)` that\n * converts a Zod parse failure into the typed\n * `RegistryMalformedPayloadError` instead of letting a bare `ZodError`\n * bubble up. Keeps the typed-handler contract aligned with\n * `RegistryServerClient`.\n */\nfunction parseCompanionResult(\n  baseUrl: string,\n  routePath: string,\n  raw: unknown,\n): RegistryRouteResult {\n  const parsed = RegistryRouteResultSchema.safeParse(raw);\n  if (!parsed.success) {\n    // 7th-pass C-L2: format the issues array for operator\n    // readability instead of using Zod 4's JSON-stringified\n    // `error.message`.\n    const detail = formatZodIssuesAsSingleLine(parsed.error);\n    throw new RegistryMalformedPayloadError(\n      baseUrl,\n      `companion ${routePath}`,\n      detail,\n    );\n  }\n  return parsed.data;\n}\n"]}

package/dist/esm/services/registry-lockfile.service.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `RegistryLockfileService` — section-scoped reader/writer for the
+ * `sections.modules` slice of `wildo-saas.lock.json` (KD-4).
+ *
+ * Phase 1 graduates the locking + atomic-write primitives into
+ * `@wildo-ai/platform-config-lib` (validated by the Phase 0.B
+ * contention spike). This service is a thin wrapper around
+ * `withLockfileSectionMutate` that pre-binds the `modules` section
+ * key + schema, so module-registry callers cannot accidentally
+ * touch sibling sections.
+ *
+ * Hard contracts (KD-4 / KD-15 / KD-18):
+ *   - Mutates ONLY `sections.modules`. The shared library preserves
+ *     `sections.providers`, `sections.i18n`, and every unknown
+ *     `sections.*` payload verbatim — no defensive logic needed
+ *     here.
+ *   - Never writes `.wildo-saas/generated/providers/*.runtime-providers.generated.json`
+ *     or `src/generated/wildo-provider-runtime.generated.ts` —
+ *     those are produced by the provider materialization workflow.
+ *   - Never mutates `sections.providers.runtimeScopes`.
+ */
+import { type RegistryModulesLockSection, type RegistryModulesLockEntry } from '@wildo-ai/platform-config-lib';
+export declare const RegistryLockfileService: {
+    /**
+     * Read the current `sections.modules` payload (or an empty section
+     * when missing). Unsynchronized — callers needing read-after-write
+     * coherence should read INSIDE `mutate`.
+     */
+    readonly read: (saasRoot: string) => Promise<RegistryModulesLockSection>;
+    /**
+     * Run `mutator` against the current `sections.modules` payload
+     * under an OS-level lock + atomic-write commit. The mutator can
+     * either mutate-in-place or return a new value; either way the
+     * result is re-validated against `RegistryModulesLockSectionSchema`
+     * before commit.
+     */
+    readonly mutate: (saasRoot: string, mutator: (current: RegistryModulesLockSection) => RegistryModulesLockSection | void | Promise<RegistryModulesLockSection | void>) => Promise<RegistryModulesLockSection>;
+    /** Convenience helper used by Phase 5+ install flow. */
+    readonly upsertEntry: (saasRoot: string, entry: RegistryModulesLockEntry) => Promise<void>;
+    /**
+     * Find every other lockfile entry whose `files[]` claims any of the
+     * given paths. Used by `update`/`remove` to skip deletes that would
+     * silently pull files out from under modules that own them too
+     * (cross-module file overlap).
+     *
+     * Returns a `Map<relPath, owners[]>` where `owners` excludes
+     * `excludeModuleId`. Empty array → uniquely owned by the excluded
+     * module, safe to delete.
+     */
+    readonly findFileOwners: (args: {
+        saasRoot: string;
+        paths: readonly string[];
+        excludeModuleId: string;
+    }) => Promise<Map<string, string[]>>;
+};
+//# sourceMappingURL=registry-lockfile.service.d.ts.map

package/dist/esm/services/registry-lockfile.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-lockfile.service.d.ts","sourceRoot":"","sources":["../../../../src/services/registry-lockfile.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAIL,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC9B,MAAM,+BAA+B,CAAC;AAevC,eAAO,MAAM,uBAAuB;IAClC;;;;OAIG;8BACkB,MAAM,KAAG,OAAO,CAAC,0BAA0B,CAAC;IAOjE;;;;;;OAMG;gCAES,MAAM,WACP,CACP,OAAO,EAAE,0BAA0B,KAEjC,0BAA0B,GAC1B,IAAI,GACJ,OAAO,CAAC,0BAA0B,GAAG,IAAI,CAAC,KAC7C,OAAO,CAAC,0BAA0B,CAAC;IAYtC,wDAAwD;qCAC5B,MAAM,SAAS,wBAAwB,KAAG,OAAO,CAAC,IAAI,CAAC;IAOnF;;;;;;;;;OASG;oCACwB;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;KACzB,KAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAgB1B,CAAC"}