@evomap/evolver-mcp 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/proxyClient.d.ts

@@ -13,6 +13,7 @@ export interface ProxyFetch {
 export interface EvolverProxyClientOptions {
     baseUrl: string;
     token: string;
+    expectedHubMode?: 'public' | 'private';
     fetchFn?: ProxyFetch;
     reloadSettings?: () => EvolverProxyClientOptions | undefined;
 }
@@ -23,13 +24,29 @@ export interface ProxySearchArgs {
     category?: string;
     gene?: string;
     limit?: number;
+    expectedHubMode?: 'public' | 'private';
+}
+export interface ProxyRecipeSearchArgs {
+    q?: string;
+    limit?: number;
+    cursor?: string;
+    sort?: string;
+    expectedHubMode?: 'public' | 'private';
+}
+export interface ProxyRecipeExpressArgs {
+    recipeId: string;
+    inputPayload?: Record<string, unknown>;
+    expectedHubMode?: 'public' | 'private';
 }
 export interface ProxyFetchArgs {
     assetId?: string;
     assetIds?: string[];
+    expectedHubMode?: 'public' | 'private';
 }
 export interface ProxyAssetBundle {
     assets: unknown[];
+    expected_hub_mode?: 'public' | 'private';
+    compose_recipe?: boolean;
 }
 export interface ProxyReuseResultArgs {
     assetId: string;
@@ -40,6 +57,7 @@ export interface ProxyReuseResultArgs {
     tokensSaved?: number;
     timeSavedSeconds?: number;
     reason?: string;
+    expectedHubMode?: 'public' | 'private';
 }
 export interface ProxyAgentSearchArgs {
     query?: string;
@@ -59,26 +77,35 @@ export declare class EvolverProxyClient {
     private baseUrl;
     private token;
     private readonly fetchFn;
+    private readonly expectedHubMode?;
     private readonly reloadSettings;
     constructor(opts: EvolverProxyClientOptions);
     status(opts?: {
         signal?: AbortSignal;
     }): Promise<unknown>;
     search(args: ProxySearchArgs): Promise<unknown>;
+    searchRecipes(args: ProxyRecipeSearchArgs): Promise<unknown>;
+    expressRecipe(args: ProxyRecipeExpressArgs): Promise<unknown>;
     fetchAsset(args: ProxyFetchArgs): Promise<unknown>;
     searchAgents(args: ProxyAgentSearchArgs): Promise<unknown>;
     getAgentProfile(agentId: string, timeoutMs?: number): Promise<unknown>;
     discoverAgentsForTask(args: ProxyAgentDiscoverArgs): Promise<unknown>;
     submitAsset(asset: unknown): Promise<unknown>;
+    submitAssetBundle(bundle: ProxyAssetBundle): Promise<unknown>;
     /** Pre-publish dry-run: the hub runs its quality + content-safety gate but stores nothing and charges no credits. */
     validateAsset(asset: unknown): Promise<unknown>;
     validateAssetBundle(bundle: ProxyAssetBundle): Promise<unknown>;
     distillConversation(input: unknown): Promise<unknown>;
     recordReuseResult(args: ProxyReuseResultArgs): Promise<unknown>;
+    private modeBoundBody;
     call(method: string, path: string, body?: unknown, opts?: {
         signal?: AbortSignal;
     }): Promise<unknown>;
+    private verifyExpectedHubMode;
+    private verifyReloadedHubMode;
+    private acceptResult;
     private callOnce;
+    private connectionSnapshot;
     private reloadFromSettings;
     private proxyError;
 }

package/dist/proxyClient.js

@@ -1,14 +1,17 @@
 import { lstatSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 export class EvolverProxyClient {
     baseUrl;
     token;
     fetchFn;
+    expectedHubMode;
     reloadSettings;
     constructor(opts) {
         this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
         this.token = opts.token;
+        this.expectedHubMode = opts.expectedHubMode;
         this.fetchFn = opts.fetchFn ?? globalFetch;
         this.reloadSettings = opts.reloadSettings;
     }
@@ -16,6 +19,7 @@ export class EvolverProxyClient {
         return this.call('GET', '/proxy/status', undefined, opts);
     }
     search(args) {
+        const expectedHubMode = args.expectedHubMode ?? this.expectedHubMode;
         return this.call('POST', '/asset/search', {
             ...(args.text ? { text: args.text } : {}),
             ...(args.signalsAny && args.signalsAny.length > 0 ? { signals: args.signalsAny } : {}),
@@ -23,12 +27,33 @@ export class EvolverProxyClient {
             ...(args.category ? { category: args.category } : {}),
             ...(args.gene ? { gene: args.gene } : {}),
             ...(args.limit !== undefined ? { limit: args.limit } : {}),
+            ...(expectedHubMode ? { expected_hub_mode: expectedHubMode } : {}),
+        });
+    }
+    searchRecipes(args) {
+        const expectedHubMode = args.expectedHubMode ?? this.expectedHubMode;
+        return this.call('POST', '/recipe/search', {
+            ...(args.q ? { q: args.q } : {}),
+            ...(args.limit !== undefined ? { limit: args.limit } : {}),
+            ...(args.cursor ? { cursor: args.cursor } : {}),
+            ...(args.sort ? { sort: args.sort } : {}),
+            ...(expectedHubMode ? { expected_hub_mode: expectedHubMode } : {}),
+        });
+    }
+    expressRecipe(args) {
+        const expectedHubMode = args.expectedHubMode ?? this.expectedHubMode;
+        return this.call('POST', '/recipe/express', {
+            recipe_id: args.recipeId,
+            ...(args.inputPayload ? { input_payload: args.inputPayload } : {}),
+            ...(expectedHubMode ? { expected_hub_mode: expectedHubMode } : {}),
         });
     }
     fetchAsset(args) {
+        const expectedHubMode = args.expectedHubMode ?? this.expectedHubMode;
         return this.call('POST', '/asset/fetch', {
             ...(args.assetId ? { asset_id: args.assetId } : {}),
             ...(args.assetIds ? { asset_ids: args.assetIds } : {}),
+            ...(expectedHubMode ? { expected_hub_mode: expectedHubMode } : {}),
         });
     }
     searchAgents(args) {
@@ -45,19 +70,27 @@ export class EvolverProxyClient {
         });
     }
     submitAsset(asset) {
-        return this.call('POST', '/asset/submit', { assets: [asset] });
+        // MCP publishing remains durable and outage-tolerant; the bare route is reserved for V1 synchronous callers.
+        return this.call('POST', '/asset/submit?mode=async', this.modeBoundBody({
+            assets: [asset],
+            request_id: randomUUID(),
+        }));
+    }
+    submitAssetBundle(bundle) {
+        return this.call('POST', '/asset/submit', this.modeBoundBody(bundle));
     }
     /** Pre-publish dry-run: the hub runs its quality + content-safety gate but stores nothing and charges no credits. */
     validateAsset(asset) {
         return this.validateAssetBundle({ assets: [asset] });
     }
     validateAssetBundle(bundle) {
-        return this.call('POST', '/asset/validate', bundle);
+        return this.call('POST', '/asset/validate', this.modeBoundBody(bundle));
     }
     distillConversation(input) {
-        return this.call('POST', '/conversation/distill', input);
+        return this.call('POST', '/conversation/distill', this.modeBoundBody(input));
     }
     recordReuseResult(args) {
+        const expectedHubMode = args.expectedHubMode ?? this.expectedHubMode;
         return this.call('POST', '/asset/reuse-result', {
             asset_id: args.assetId,
             outcome: args.outcome,
@@ -65,43 +98,84 @@ export class EvolverProxyClient {
             ...(args.traceId ? { trace_id: args.traceId } : {}),
             ...(args.timeSavedSeconds !== undefined ? { time_saved_seconds: args.timeSavedSeconds } : {}),
             ...(args.reason ? { reason: args.reason } : {}),
+            ...(expectedHubMode ? { expected_hub_mode: expectedHubMode } : {}),
         });
     }
+    modeBoundBody(input) {
+        if (!this.expectedHubMode || !input || typeof input !== 'object' || Array.isArray(input))
+            return input;
+        const body = input;
+        return { ...body, expected_hub_mode: body['expected_hub_mode'] ?? this.expectedHubMode };
+    }
     async call(method, path, body, opts = {}) {
+        let connection = this.connectionSnapshot();
         try {
-            const result = await this.callOnce(method, path, body, opts);
+            if (path !== '/proxy/status' && this.expectedHubMode === 'private') {
+                await this.verifyExpectedHubMode(connection, opts);
+            }
+            const result = await this.callOnce(method, path, body, opts, connection);
             if (result.ok)
-                return result.parsed;
+                return this.acceptResult(result, path);
             if (result.status === 401 && this.reloadFromSettings()) {
-                const retry = await this.callOnce(method, path, body, opts);
+                connection = this.connectionSnapshot();
+                await this.verifyReloadedHubMode(path, connection, opts);
+                const retry = await this.callOnce(method, path, body, opts, connection);
                 if (retry.ok)
-                    return retry.parsed;
+                    return this.acceptResult(retry, path);
                 throw this.proxyError(retry, path);
             }
             throw this.proxyError(result, path);
         }
         catch (err) {
             if (this.reloadFromSettings()) {
-                const retry = await this.callOnce(method, path, body, opts);
+                connection = this.connectionSnapshot();
+                await this.verifyReloadedHubMode(path, connection, opts);
+                const retry = await this.callOnce(method, path, body, opts, connection);
                 if (retry.ok)
-                    return retry.parsed;
+                    return this.acceptResult(retry, path);
                 throw this.proxyError(retry, path);
             }
             throw err;
         }
     }
-    async callOnce(method, path, body, opts) {
-        const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+    async verifyExpectedHubMode(connection, opts) {
+        // A proxy can restart on the same loopback URL with the same operator-supplied token. Verify every private
+        // operation against the same immutable connection snapshot used for its payload. This prevents a concurrent
+        // settings reload from moving the payload to an endpoint that the status probe never verified.
+        const result = await this.callOnce('GET', '/proxy/status', undefined, opts, connection);
+        if (!result.ok)
+            throw this.proxyError(result, '/proxy/status');
+        this.acceptResult(result, '/proxy/status');
+    }
+    async verifyReloadedHubMode(path, connection, opts) {
+        if (path !== '/proxy/status' && this.expectedHubMode === 'private') {
+            await this.verifyExpectedHubMode(connection, opts);
+        }
+    }
+    acceptResult(result, path) {
+        if (path === '/proxy/status' && this.expectedHubMode === 'private') {
+            const status = recordValue(result.parsed);
+            if (status['hub_mode'] !== 'private')
+                throw new Error('proxy_hub_mode_mismatch');
+        }
+        return result.parsed;
+    }
+    async callOnce(method, path, body, opts, connection) {
+        const res = await this.fetchFn(`${connection.baseUrl}${path}`, {
             method,
             headers: {
-                authorization: `Bearer ${this.token}`,
+                authorization: `Bearer ${connection.token}`,
                 'content-type': 'application/json',
+                ...(this.expectedHubMode ? { 'x-evomap-expected-hub-mode': this.expectedHubMode } : {}),
             },
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
             ...(opts.signal ? { signal: opts.signal } : {}),
         });
         return { ok: res.ok, status: res.status, parsed: await res.json() };
     }
+    connectionSnapshot() {
+        return { baseUrl: this.baseUrl, token: this.token };
+    }
     reloadFromSettings() {
         const next = this.reloadSettings?.();
         if (!next)
@@ -133,38 +207,46 @@ function agentDirectoryBody(args) {
     };
 }
 export function proxyClientFromEnv(env = process.env) {
+    const expectedHubMode = expectedHubModeFromEnv(env);
+    if (!expectedHubMode)
+        return undefined;
     const token = env['EVOLVER_IPC_TOKEN']?.trim();
     if (!token)
-        return proxyClientFromSettings(env, env === process.env);
-    const explicitUrl = env['EVOLVER_PROXY_URL']?.trim();
-    const port = env['EVOLVER_IPC_PORT']?.trim() || env['EVOMAP_PROXY_PORT']?.trim() || '19820';
-    return new EvolverProxyClient({ baseUrl: explicitUrl || `http://127.0.0.1:${port}`, token });
+        return proxyClientFromSettings(env, env === process.env, undefined, expectedHubMode);
+    const baseUrl = proxyBaseUrlFromEnv(env);
+    return baseUrl ? new EvolverProxyClient({ baseUrl, token, expectedHubMode }) : undefined;
 }
 export async function reachableProxyClientFromEnv(env = process.env, opts = {}) {
+    const expectedHubMode = expectedHubModeFromEnv(env);
+    if (!expectedHubMode)
+        return undefined;
     const token = env['EVOLVER_IPC_TOKEN']?.trim();
     if (token) {
-        const explicitUrl = env['EVOLVER_PROXY_URL']?.trim();
-        const port = env['EVOLVER_IPC_PORT']?.trim() || env['EVOMAP_PROXY_PORT']?.trim() || '19820';
-        return new EvolverProxyClient({ baseUrl: explicitUrl || `http://127.0.0.1:${port}`, token, ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}) });
+        const baseUrl = proxyBaseUrlFromEnv(env);
+        return baseUrl ? new EvolverProxyClient({ baseUrl, token, expectedHubMode, ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}) }) : undefined;
     }
-    const client = proxyClientFromSettings(env, env === process.env, opts.fetchFn);
+    const client = proxyClientFromSettings(env, env === process.env, opts.fetchFn, expectedHubMode);
     if (!client)
         return undefined;
     return await proxyClientReachable(client, opts.timeoutMs ?? 250) ? client : undefined;
 }
-function proxyClientFromSettings(env, allowDefaultHome, fetchFn) {
+function proxyClientFromSettings(env, allowDefaultHome, fetchFn, expectedHubMode = 'public') {
     const settings = readProxySettings(env, allowDefaultHome);
     return settings ? new EvolverProxyClient({
         ...settings,
+        expectedHubMode,
         ...(fetchFn ? { fetchFn } : {}),
         reloadSettings: () => readProxySettings(env, allowDefaultHome),
     }) : undefined;
 }
+function expectedHubModeFromEnv(env) {
+    const value = env['EVOMAP_HUB_MODE']?.trim().toLowerCase() || 'public';
+    return value === 'public' || value === 'private' ? value : undefined;
+}
 function readProxySettings(env, allowDefaultHome) {
-    const homeDir = env['HOME']?.trim() || (allowDefaultHome ? homedir() : '');
-    if (!homeDir)
+    const settingsPath = resolveProxySettingsPath(env, allowDefaultHome);
+    if (!settingsPath)
         return undefined;
-    const settingsPath = join(homeDir, '.evolver', 'settings.json');
     try {
         if (!lstatSync(settingsPath).isFile())
             return undefined;
@@ -180,11 +262,23 @@ function readProxySettings(env, allowDefaultHome) {
         return undefined;
     }
 }
+function resolveProxySettingsPath(env, allowDefaultHome) {
+    const explicit = env['EVOLVER_PROXY_SETTINGS_FILE']?.trim();
+    if (explicit)
+        return explicit;
+    const settingsDir = env['EVOLVER_SETTINGS_DIR']?.trim();
+    if (settingsDir)
+        return join(settingsDir, 'settings.json');
+    const homeDir = env['HOME']?.trim() || (allowDefaultHome ? homedir() : '');
+    return homeDir ? join(homeDir, '.evolver', 'settings.json') : undefined;
+}
 function isLoopbackHttpUrl(raw) {
     try {
         const url = new URL(raw);
         if (url.protocol !== 'http:' && url.protocol !== 'https:')
             return false;
+        if (url.username || url.password || url.search || url.hash || (url.pathname && url.pathname !== '/'))
+            return false;
         const hostname = url.hostname.toLowerCase();
         return hostname === '127.0.0.1'
             || hostname === 'localhost'
@@ -195,6 +289,19 @@ function isLoopbackHttpUrl(raw) {
         return false;
     }
 }
+function proxyBaseUrlFromEnv(env) {
+    const explicitUrl = env['EVOLVER_PROXY_URL']?.trim();
+    if (explicitUrl)
+        return isLoopbackHttpUrl(explicitUrl) ? explicitUrl : undefined;
+    const rawPort = env['EVOLVER_IPC_PORT']?.trim() || env['EVOMAP_PROXY_PORT']?.trim() || '19820';
+    if (!/^\d+$/.test(rawPort))
+        return undefined;
+    const port = Number(rawPort);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535)
+        return undefined;
+    const baseUrl = `http://127.0.0.1:${port}`;
+    return isLoopbackHttpUrl(baseUrl) ? baseUrl : undefined;
+}
 function recordValue(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
@@ -205,7 +312,9 @@ async function proxyClientReachable(client, timeoutMs) {
         await client.status({ signal: controller.signal });
         return true;
     }
-    catch {
+    catch (error) {
+        if (error instanceof Error && error.message === 'proxy_hub_mode_mismatch')
+            throw error;
         return false;
     }
     finally {
@@ -214,5 +323,5 @@ async function proxyClientReachable(client, timeoutMs) {
     }
 }
 async function globalFetch(url, init) {
-    return fetch(url, init);
+    return fetch(url, { ...init, redirect: 'error' });
 }

package/dist/sharedFileCommit.d.ts

@@ -0,0 +1,20 @@
+import { linkSync } from 'node:fs';
+export interface SharedFileCommitOptions {
+    path: string;
+    expectedRaw: string | undefined;
+    nextRaw: string | undefined;
+    mode?: number;
+    beforeCommitForTest?: () => void;
+    afterValidateForTest?: () => void;
+    afterDisplaceForTest?: (displacedPath: string) => void;
+    beforePublishForTest?: () => void;
+    linkForTest?: typeof linkSync;
+}
+export declare class SharedFileConflictError extends Error {
+    readonly recoveryPath?: string | undefined;
+    constructor(path: string, recoveryPath?: string | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** Commits only if the target bytes still match the caller's snapshot. */
+export declare function commitSharedFile(options: SharedFileCommitOptions): void;

package/dist/sharedFileCommit.js

@@ -0,0 +1,256 @@
+import { chmodSync, closeSync, constants as fsConstants, copyFileSync, existsSync, linkSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+export class SharedFileConflictError extends Error {
+    recoveryPath;
+    constructor(path, recoveryPath, options) {
+        super(recoveryPath
+            ? `Shared config changed during commit: ${path}; conflicting bytes preserved at ${recoveryPath}`
+            : `Shared config changed during commit: ${path}`, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.recoveryPath = recoveryPath;
+        this.name = 'SharedFileConflictError';
+    }
+}
+function tempPath(path, label) {
+    return join(dirname(path), `.${basename(path)}.evolver-${label}-${process.pid}-${randomUUID()}`);
+}
+function writePrepared(path, raw, mode) {
+    const fd = openSync(path, 'wx', mode);
+    try {
+        writeFileSync(fd, raw, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+    chmodSync(path, mode);
+}
+function removeIfPresent(path) {
+    if (!path)
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+function publishNoClobber(source, target, linkFile = linkSync) {
+    try {
+        linkFile(source, target);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'EPERM' && code !== 'EACCES' && code !== 'ENOTSUP' && code !== 'EOPNOTSUPP' && code !== 'EXDEV') {
+            throw error;
+        }
+        copyFileSync(source, target, fsConstants.COPYFILE_EXCL);
+    }
+}
+function snapshotNoClobber(source, snapshot, linkFile = linkSync) {
+    try {
+        linkFile(source, snapshot);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'EPERM' && code !== 'EACCES' && code !== 'ENOTSUP' && code !== 'EOPNOTSUPP' && code !== 'EXDEV') {
+            throw error;
+        }
+        copyFileSync(source, snapshot, fsConstants.COPYFILE_EXCL);
+    }
+}
+function restoreNoClobber(displaced, target, linkFile = linkSync) {
+    try {
+        publishNoClobber(displaced, target, linkFile);
+        unlinkSync(displaced);
+        return undefined;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EEXIST')
+            return displaced;
+        if (code === 'EPERM' || code === 'EACCES' || code === 'ENOTSUP' || code === 'EOPNOTSUPP' || code === 'EXDEV') {
+            try {
+                copyFileSync(displaced, target, fsConstants.COPYFILE_EXCL);
+                unlinkSync(displaced);
+                return undefined;
+            }
+            catch (copyError) {
+                if (copyError.code === 'EEXIST')
+                    return displaced;
+                throw new AggregateError([err, copyError], `Unable to restore shared config at ${target}`);
+            }
+        }
+        throw err;
+    }
+}
+function fileVersion(path) {
+    const stat = statSync(path, { bigint: true });
+    return {
+        dev: stat.dev,
+        ino: stat.ino,
+        size: stat.size,
+        mtimeNs: stat.mtimeNs,
+        ctimeNs: stat.ctimeNs,
+    };
+}
+function sameFileVersion(left, right) {
+    return left.dev === right.dev
+        && left.ino === right.ino
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs;
+}
+/** Commits only if the target bytes still match the caller's snapshot. */
+export function commitSharedFile(options) {
+    const mode = options.mode ?? 0o600;
+    const prepared = options.nextRaw === undefined ? undefined : tempPath(options.path, 'next');
+    const displaced = options.expectedRaw === undefined ? undefined : tempPath(options.path, 'previous');
+    const movedLive = options.expectedRaw === undefined ? undefined : tempPath(options.path, 'live');
+    let preserveDisplaced = false;
+    let preserveMovedLive = false;
+    let liveWasMoved = false;
+    let published = false;
+    try {
+        if (prepared)
+            writePrepared(prepared, options.nextRaw, mode);
+        options.beforeCommitForTest?.();
+        if (options.expectedRaw === undefined) {
+            if (!prepared)
+                return;
+            try {
+                publishNoClobber(prepared, options.path, options.linkForTest);
+            }
+            catch (err) {
+                if (err.code === 'EEXIST') {
+                    throw new SharedFileConflictError(options.path);
+                }
+                throw err;
+            }
+            return;
+        }
+        // Validate while the live path is still present. The no-clobber publish below then limits the unavoidable
+        // crash-only missing-path interval to the two adjacent metadata operations.
+        let versionBeforeRead;
+        let actualRaw;
+        let validatedVersion;
+        try {
+            versionBeforeRead = fileVersion(options.path);
+            actualRaw = readFileSync(options.path, 'utf8');
+            validatedVersion = fileVersion(options.path);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                throw new SharedFileConflictError(options.path);
+            }
+            throw err;
+        }
+        if (actualRaw !== options.expectedRaw) {
+            throw new SharedFileConflictError(options.path);
+        }
+        if (!sameFileVersion(versionBeforeRead, validatedVersion)) {
+            throw new SharedFileConflictError(options.path);
+        }
+        options.afterValidateForTest?.();
+        snapshotNoClobber(options.path, displaced, options.linkForTest);
+        try {
+            const liveAfterSnapshot = fileVersion(options.path);
+            if (readFileSync(options.path, 'utf8') !== options.expectedRaw
+                || liveAfterSnapshot.dev !== validatedVersion.dev
+                || liveAfterSnapshot.ino !== validatedVersion.ino
+                || liveAfterSnapshot.size !== validatedVersion.size
+                || liveAfterSnapshot.mtimeNs !== validatedVersion.mtimeNs) {
+                throw new SharedFileConflictError(options.path);
+            }
+            options.afterDisplaceForTest?.(displaced);
+            const liveBeforePublish = fileVersion(options.path);
+            if (!sameFileVersion(liveAfterSnapshot, liveBeforePublish)
+                || readFileSync(options.path, 'utf8') !== options.expectedRaw
+                || readFileSync(displaced, 'utf8') !== options.expectedRaw) {
+                throw new SharedFileConflictError(options.path);
+            }
+            options.beforePublishForTest?.();
+            renameSync(options.path, movedLive);
+            liveWasMoved = true;
+            if (readFileSync(movedLive, 'utf8') !== options.expectedRaw) {
+                const recoveryPath = restoreNoClobber(movedLive, options.path, options.linkForTest);
+                liveWasMoved = recoveryPath !== undefined;
+                preserveMovedLive = recoveryPath !== undefined;
+                throw new SharedFileConflictError(options.path, recoveryPath);
+            }
+            if (prepared) {
+                publishNoClobber(prepared, options.path);
+                removeIfPresent(prepared);
+            }
+            else {
+                unlinkSync(movedLive);
+                liveWasMoved = false;
+            }
+            if (prepared) {
+                unlinkSync(movedLive);
+                liveWasMoved = false;
+            }
+            published = true;
+            removeIfPresent(displaced);
+        }
+        catch (error) {
+            if (!published) {
+                if (liveWasMoved && movedLive !== undefined) {
+                    const recoveryPath = restoreNoClobber(movedLive, options.path, options.linkForTest);
+                    liveWasMoved = recoveryPath !== undefined;
+                    preserveMovedLive = recoveryPath !== undefined;
+                    if (recoveryPath !== undefined) {
+                        removeIfPresent(displaced);
+                        throw new SharedFileConflictError(options.path, recoveryPath, { cause: error });
+                    }
+                }
+                removeIfPresent(displaced);
+                if (error instanceof SharedFileConflictError)
+                    throw error;
+                throw new SharedFileConflictError(options.path, undefined, { cause: error });
+            }
+            let recoveryPath;
+            try {
+                if (prepared && existsSync(options.path)) {
+                    try {
+                        if (readFileSync(options.path, 'utf8') === options.nextRaw)
+                            removeIfPresent(options.path);
+                    }
+                    catch {
+                        // Preserve a concurrent replacement and expose the snapshot as recoveryPath.
+                    }
+                }
+                recoveryPath = restoreNoClobber(displaced, options.path, options.linkForTest);
+                preserveDisplaced = recoveryPath !== undefined;
+            }
+            catch (restoreError) {
+                preserveDisplaced = true;
+                throw new Error(`Shared config commit failed for ${options.path}; original bytes preserved at ${displaced}`, { cause: new AggregateError([error, restoreError]) });
+            }
+            throw new SharedFileConflictError(options.path, recoveryPath, { cause: error });
+        }
+    }
+    finally {
+        if (!preserveDisplaced && displaced && existsSync(displaced)) {
+            if (!existsSync(options.path)) {
+                const recoveryPath = restoreNoClobber(displaced, options.path, options.linkForTest);
+                preserveDisplaced = recoveryPath !== undefined;
+            }
+            else {
+                // Keep a displaced file only when it is the sole recovery copy of concurrent bytes.
+                try {
+                    const displacedRaw = readFileSync(displaced, 'utf8');
+                    if (displacedRaw === options.expectedRaw)
+                        removeIfPresent(displaced);
+                }
+                catch {
+                    // Preserve an unreadable displaced file instead of masking the primary result.
+                }
+            }
+        }
+        removeIfPresent(prepared);
+        if (!preserveMovedLive && movedLive && existsSync(movedLive)) {
+            removeIfPresent(movedLive);
+        }
+    }
+}