@jagilber-org/index-server 1.22.1 → 1.26.4

package/dist/server/transportFactory.js

@@ -3,407 +3,45 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.dynamicImport = void 0;
 exports.setupStdoutDiagnostics = setupStdoutDiagnostics;
 exports.setupDispatcherOverride = setupDispatcherOverride;
-exports.wrapTransportSend = wrapTransportSend;
 exports.setupKeepalive = setupKeepalive;
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /**
- * Transport initialization, request dispatcher override, and diagnostics
- * wrappers for the MCP server.
+ * Transport bootstrap helpers for the MCP server.
  */
 const runtimeConfig_1 = require("../config/runtimeConfig");
-const handshakeManager_1 = require("./handshakeManager");
 // Helper to perform a true dynamic ESM import that TypeScript won't down-level to require()
 const dynamicImport = (specifier) => (Function('m', 'return import(m);'))(specifier);
 exports.dynamicImport = dynamicImport;
 /**
- * Set up stdout diagnostics wrapper for backpressure monitoring.
+ * Emit a lightweight diagnostic marker without intercepting stdout writes.
  * Enabled via INDEX_SERVER_TRACE=healthMixed.
  */
 async function setupStdoutDiagnostics() {
-    const __diagEnabled = (0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed');
-    const __diag = (msg) => { if (__diagEnabled) {
-        try {
-            process.stderr.write(`[diag] ${Date.now()} ${msg}\n`);
-        }
-        catch { /* ignore */ }
-    } };
-    // Emit a one-time version marker so tests can assert the newer diagnostic wrapper code is actually loaded.
-    if (__diagEnabled) {
-        try {
-            const buildMarker = 'sdkServerDiagV1';
-            // Include a coarse content hash surrogate: file size + mtime if available
-            let fsMeta = '';
-            try {
-                const fsMod = await import('fs');
-                const stat = fsMod.statSync(__filename);
-                fsMeta = ` size=${stat.size} mtimeMs=${Math.trunc(stat.mtimeMs)}`;
-            }
-            catch { /* ignore meta */ }
-            process.stderr.write(`[diag] ${Date.now()} diag_start marker=${buildMarker}${fsMeta}\n`);
-        }
-        catch { /* ignore */ }
-    }
-    if (__diagEnabled) {
-        try {
-            const origWrite = process.stdout.write.bind(process.stdout);
-            let backpressureEvents = 0;
-            let bytesTotal = 0;
-            let lastReportAt = Date.now();
-            process.stdout.on?.('drain', () => { __diag('stdout_drain'); });
-            process.stdout.write = function (chunk, encoding, cb) {
-                try {
-                    const size = Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk));
-                    bytesTotal += size;
-                    const ret = origWrite(chunk, encoding, cb);
-                    if (!ret) {
-                        backpressureEvents++;
-                        __diag(`stdout_backpressure size=${size} backpressureEvents=${backpressureEvents}`);
-                    }
-                    const now = Date.now();
-                    if (now - lastReportAt > 2000) {
-                        __diag(`stdout_summary bytesTotal=${bytesTotal} backpressureEvents=${backpressureEvents}`);
-                        lastReportAt = now;
-                    }
-                    return ret;
-                }
-                catch (e) {
-                    try {
-                        __diag(`stdout_write_wrapper_error ${e?.message || String(e)}`);
-                    }
-                    catch { /* ignore */ }
-                    return origWrite(chunk, encoding, cb);
-                }
-            };
-        }
-        catch { /* ignore */ }
-    }
-}
-// Robust semantic error preservation: deep scan for JSON-RPC code/message
-function deepScan(obj, depth = 0, seen = new Set()) {
-    if (!obj || typeof obj !== 'object' || depth > 4 || seen.has(obj))
-        return undefined;
-    seen.add(obj);
-    if (Number.isSafeInteger(obj.code)) {
-        const c = obj.code;
-        if (c === -32601 || c === -32602)
-            return c; // prioritize semantic validation codes
-    }
-    // Prefer specific well-known nesting keys first
-    const keys = ['error', 'original', 'cause', 'data'];
-    for (const k of keys) {
-        try {
-            const child = obj[k];
-            const found = deepScan(child, depth + 1, seen);
-            if (found !== undefined)
-                return found;
-        }
-        catch { /* ignore */ }
-    }
-    // Fallback: generic property iteration (shallow) to catch unexpected wrappers
-    if (depth < 2) {
-        try {
-            for (const v of Object.values(obj)) {
-                const found = deepScan(v, depth + 1, seen);
-                if (found !== undefined)
-                    return found;
-            }
-        }
-        catch { /* ignore */ }
-    }
-    return undefined;
-}
-// Categorize request for diagnostics
-function categorizeRequest(request) {
-    const metaName = request.method === 'tools/call' ? request?.params?.name : '';
-    if (request.method === 'initialize')
-        return 'init';
-    if (request.method === 'health_check' || metaName === 'health_check')
-        return 'health';
-    if (request.method === 'metrics_snapshot' || metaName === 'metrics_snapshot')
-        return 'metrics';
-    if (metaName === 'meta_tools')
-        return 'meta';
-    return 'other';
-}
-/**
- * Override the internal request dispatcher to retain error.data & emit diagnostics.
- * The upstream SDK has used both `_onRequest` (camel) and `_onrequest` (lower) across versions;
- * we defensively hook whichever exists and assign our wrapper to BOTH names.
- */
-function setupDispatcherOverride(server) {
-    const existingLower = server._onrequest;
-    const existingCamel = server._onRequest;
-    const originalOnRequest = (existingCamel || existingLower) ? (existingCamel || existingLower).bind(server) : undefined;
-    let __diagQueueDepth = 0;
-    if (originalOnRequest) {
-        const wrapped = function (request) {
-            const diagEnabled = (0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed');
-            let startedAt;
-            if (diagEnabled) {
-                const category = categorizeRequest(request);
-                if (category === 'health' || category === 'meta' || category === 'metrics' || category === 'init') {
-                    startedAt = Date.now();
-                    try {
-                        __diagQueueDepth++;
-                        process.stderr.write(`[diag] ${startedAt} rq_enqueue method=${request.method} cat=${category} id=${request.id} qdepth=${__diagQueueDepth}\n`);
-                        if (category === 'health') {
-                            if (!server.__firstHealthEnqueueAt) {
-                                server.__firstHealthEnqueueAt = startedAt;
-                            }
-                            if (request.id === 1 && !server.__healthId1EnqueueAt) {
-                                server.__healthId1EnqueueAt = startedAt;
-                            }
-                        }
-                        if (!server.__activeDiagRequests) {
-                            server.__activeDiagRequests = new Map();
-                        }
-                        server.__activeDiagRequests.set(request.id, { id: request.id, method: request.method, cat: category, start: startedAt });
-                        // Mis-order detection: health/metrics/meta before initialize observed
-                        if ((category === 'health' || category === 'metrics' || category === 'meta') && !server.__sawInitializeRequest) {
-                            try {
-                                process.stderr.write(`[diag] ${Date.now()} rq_misorder_before_init method=${request.method} id=${request.id} cat=${category} qdepth=${__diagQueueDepth}\n`);
-                            }
-                            catch { /* ignore */ }
-                        }
-                    }
-                    catch { /* ignore */ }
-                }
-            }
-            const handler = this._requestHandlers.get(request.method) ?? this.fallbackRequestHandler;
-            if (handler === undefined) {
-                return this._transport?.send({ jsonrpc: '2.0', id: request.id, error: { code: -32601, message: 'Method not found', data: { method: request.method } } }).catch(() => { });
-            }
-            const abortController = new AbortController();
-            this._requestHandlerAbortControllers.set(request.id, abortController);
-            // IMPORTANT: We intentionally never early-return without sending a response
-            Promise.resolve()
-                .then(() => handler(request, { signal: abortController.signal }))
-                .then((result) => {
-                if (startedAt !== undefined) {
-                    try {
-                        const dur = Date.now() - startedAt;
-                        const category = categorizeRequest(request);
-                        if (category === 'health' || category === 'meta' || category === 'metrics' || category === 'init') {
-                            __diagQueueDepth = Math.max(0, __diagQueueDepth - 1);
-                            process.stderr.write(`[diag] ${Date.now()} rq_complete method=${request.method} cat=${category} id=${request.id} dur_ms=${dur} qdepth=${__diagQueueDepth}\n`);
-                            try {
-                                server.__activeDiagRequests?.delete(request.id);
-                            }
-                            catch { /* ignore */ }
-                        }
-                    }
-                    catch { /* ignore */ }
-                }
-                if (abortController.signal.aborted) {
-                    try {
-                        if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                            process.stderr.write(`[rpc] aborted-but-sending method=${request.method} id=${request.id}\n`);
-                    }
-                    catch { /* ignore */ }
-                }
-                else {
-                    try {
-                        if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                            process.stderr.write(`[rpc] response method=${request.method} id=${request.id} ok\n`);
-                    }
-                    catch { /* ignore */ }
-                }
-                const sendPromise = this._transport?.send({ jsonrpc: '2.0', id: request.id, result });
-                if (request.method === 'initialize') {
-                    (0, handshakeManager_1.initFrameLog)('dispatcher_before_send', { id: request.id });
-                    (sendPromise?.then?.(() => {
-                        (0, handshakeManager_1.initFrameLog)('dispatcher_send_resolved', { id: request.id });
-                        server.__initResponseSent = true;
-                        setTimeout(() => (0, handshakeManager_1.emitReadyGlobal)(server, 'transport-send-hook'), 0);
-                    }))?.catch(() => { });
-                }
-                return sendPromise;
-            }, (error) => {
-                if (startedAt !== undefined) {
-                    try {
-                        const dur = Date.now() - startedAt;
-                        const category = categorizeRequest(request);
-                        if (category === 'health' || category === 'meta' || category === 'metrics' || category === 'init') {
-                            __diagQueueDepth = Math.max(0, __diagQueueDepth - 1);
-                            process.stderr.write(`[diag] ${Date.now()} rq_error method=${request.method} cat=${category} id=${request.id} dur_ms=${dur} qdepth=${__diagQueueDepth}\n`);
-                            try {
-                                server.__activeDiagRequests?.delete(request.id);
-                            }
-                            catch { /* ignore */ }
-                        }
-                    }
-                    catch { /* ignore */ }
-                }
-                if (abortController.signal.aborted) {
-                    try {
-                        if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                            process.stderr.write(`[rpc] aborted-error-path method=${request.method} id=${request.id}\n`);
-                    }
-                    catch { /* ignore */ }
-                }
-                // Robust semantic error preservation: search multiple nests for a JSON-RPC code/message
-                let errCode = error?.code;
-                if (!Number.isSafeInteger(errCode))
-                    errCode = error?.data?.code;
-                if (!Number.isSafeInteger(errCode))
-                    errCode = error?.original?.code;
-                if (!Number.isSafeInteger(errCode))
-                    errCode = error?.cause?.code;
-                if (!Number.isSafeInteger(errCode))
-                    errCode = error?.error?.code;
-                const rawBeforeDeep = errCode;
-                if (!Number.isSafeInteger(errCode) || errCode === -32603) {
-                    const deep = deepScan(error);
-                    if (Number.isSafeInteger(deep))
-                        errCode = deep;
-                }
-                const safeCode = Number.isSafeInteger(errCode) ? errCode : undefined;
-                let errMessage = error?.message;
-                if (!errMessage)
-                    errMessage = error?.data?.message;
-                if (!errMessage)
-                    errMessage = error?.original?.message;
-                if (!errMessage)
-                    errMessage = error?.cause?.message;
-                if (!errMessage)
-                    errMessage = error?.error?.message;
-                if (typeof errMessage !== 'string' || !errMessage.trim())
-                    errMessage = 'Internal error';
-                let data = error?.data;
-                if (data && typeof data === 'object') {
-                    if (typeof data.message !== 'string')
-                        data = { ...data, message: errMessage };
-                }
-                else if (error && typeof error === 'object') {
-                    data = { message: errMessage, ...(error.method ? { method: error.method } : {}) };
-                }
-                let finalCode = (safeCode !== undefined) ? safeCode : -32603;
-                if (finalCode === -32603 && data && typeof data === 'object') {
-                    try {
-                        const reason = data.reason || data.data?.reason;
-                        if (reason === 'missing_action')
-                            finalCode = -32602;
-                        else if (reason === 'unknown_action' || reason === 'mutation_disabled' || reason === 'unknown_handler')
-                            finalCode = -32601;
-                    }
-                    catch { /* ignore */ }
-                }
-                try {
-                    if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose) {
-                        const before = Number.isSafeInteger(rawBeforeDeep) ? rawBeforeDeep : 'n/a';
-                        if ((before === 'n/a' || before === -32603) && (finalCode === -32601 || finalCode === -32602)) {
-                            const reasonHint = data?.reason || data?.data?.reason;
-                            process.stderr.write(`[rpc] deep_recover_semantic code=${finalCode} from=${before} reasonHint=${reasonHint || ''}\n`);
-                        }
-                    }
-                }
-                catch { /* ignore */ }
-                try {
-                    if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                        process.stderr.write(`[rpc] response method=${request.method} id=${request.id} error=${errMessage} code=${finalCode}\n`);
-                }
-                catch { /* ignore */ }
-                return this._transport?.send({ jsonrpc: '2.0', id: request.id, error: { code: finalCode, message: errMessage, data } });
-            })
-                .catch(() => { })
-                .finally(() => { this._requestHandlerAbortControllers.delete(request.id); });
-        };
-        // Attach wrapper to BOTH potential internal symbols to guarantee interception.
-        server._onRequest = wrapped;
-        server._onrequest = wrapped;
-        server.__dispatcherOverrideActive = true;
-        try {
-            if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed'))
-                process.stderr.write(`[diag] ${Date.now()} dispatcher_override applied props=${[existingCamel ? '_onRequest(original)' : '', existingLower ? '_onrequest(original)' : ''].filter(Boolean).join(',') || 'none'}\n`);
-        }
-        catch { /* ignore */ }
-        // Starvation watchdog
-        if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed') && !server.__starvationWatchdogStarted) {
-            server.__starvationWatchdogStarted = true;
-            let ticks = 0;
-            const iv = setInterval(() => {
-                try {
-                    ticks++;
-                    const active = server.__activeDiagRequests;
-                    const firstH = server.__healthId1EnqueueAt;
-                    if (active && active.size) {
-                        const pending = Array.from(active.values()).map((r) => ({ id: r.id, cat: r.cat, age: Date.now() - r.start })).sort((a, b) => a.id - b.id).slice(0, 12);
-                        const hasHealth1 = !!active.get?.(1);
-                        if (hasHealth1 || (firstH && Date.now() - firstH > 40)) {
-                            process.stderr.write(`[diag] ${Date.now()} starvation_watchdog tick=${ticks} pending=${pending.length} details=${JSON.stringify(pending)} firstHealthAge=${firstH ? Date.now() - firstH : -1} hasHealth1=${hasHealth1}\n`);
-                        }
-                        if (!hasHealth1 && firstH && Date.now() - firstH > 400) {
-                            process.stderr.write(`[diag] ${Date.now()} starvation_watchdog_health1_missing age=${Date.now() - firstH}\n`);
-                        }
-                    }
-                    if (ticks > 40 || (server.__activeDiagRequests && !server.__activeDiagRequests.get(1))) {
-                        clearInterval(iv);
-                    }
-                }
-                catch { /* ignore */ }
-            }, 25);
-            iv.unref?.();
-        }
-    }
-    else if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed')) {
-        try {
-            process.stderr.write(`[diag] ${Date.now()} dispatcher_override_skipped no_original_handler_found`);
-        }
-        catch { /* ignore */ }
-    }
-    // Enumerate server properties once for debugging missing override
+    if (!(0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed'))
+        return;
     try {
-        if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed')) {
-            const props = Object.getOwnPropertyNames(server).filter(p => /_on|request|handler/i.test(p)).slice(0, 60);
-            process.stderr.write(`[diag] ${Date.now()} server_props ${props.join(',')}\n`);
+        const buildMarker = 'sdkServerDiagV2';
+        let fsMeta = '';
+        try {
+            const fsMod = await import('fs');
+            const stat = fsMod.statSync(__filename);
+            fsMeta = ` size=${stat.size} mtimeMs=${Math.trunc(stat.mtimeMs)}`;
         }
+        catch { /* ignore meta */ }
+        process.stderr.write(`[diag] ${Date.now()} diag_start marker=${buildMarker}${fsMeta}\n`);
     }
     catch { /* ignore */ }
 }
 /**
- * Wrap transport.send to detect initialize response flush and emit ready.
+ * Keep diagnostics on public surfaces only; private SDK dispatcher hooks are no longer patched.
  */
-function wrapTransportSend(server, transport) {
+function setupDispatcherOverride(_server) {
+    if (!(0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed'))
+        return;
     try {
-        const origSend = transport?.send?.bind(transport);
-        if (origSend && !transport.__wrappedForReady) {
-            transport.__wrappedForReady = true;
-            transport.send = (msg) => {
-                let isInitResult = false;
-                try {
-                    isInitResult = !!(msg && typeof msg === 'object' && 'id' in msg && msg.result && msg.result.protocolVersion);
-                }
-                catch { /* ignore */ }
-                const sendPromise = origSend(msg);
-                // Fallback completion / error logging if dispatcher override not active
-                try {
-                    if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed') && !server.__dispatcherOverrideActive && msg && typeof msg === 'object' && Object.prototype.hasOwnProperty.call(msg, 'id')) {
-                        const map = server.__diagRQMap;
-                        if (map && map.has(msg.id)) {
-                            const rec = map.get(msg.id);
-                            map.delete(msg.id);
-                            server.__diagQueueDepthSniff = Math.max(0, server.__diagQueueDepthSniff - 1);
-                            const kind = msg.error ? 'rq_error' : 'rq_complete';
-                            const dur = Date.now() - rec.start;
-                            process.stderr.write(`[diag] ${Date.now()} ${kind} method=${rec.method} cat=${rec.cat} id=${msg.id} dur_ms=${dur} qdepth=${server.__diagQueueDepthSniff} src=sniff-send\n`);
-                        }
-                    }
-                }
-                catch { /* ignore */ }
-                if (isInitResult && !server.__readyNotified) {
-                    server.__sawInitializeRequest = true;
-                    (0, handshakeManager_1.initFrameLog)('transport_detect_init_result', { id: msg.id });
-                    sendPromise?.then?.(() => {
-                        (0, handshakeManager_1.initFrameLog)('transport_send_resolved', { id: msg.id });
-                        server.__initResponseSent = true;
-                        setTimeout(() => (0, handshakeManager_1.emitReadyGlobal)(server, 'transport-send-hook-dynamic'), 0);
-                    })?.catch?.(() => { });
-                }
-                return sendPromise;
-            };
-        }
+        process.stderr.write(`[diag] ${Date.now()} dispatcher_override disabled public_api_only\n`);
     }
-    catch { /* ignore wrapper errors */ }
+    catch { /* ignore */ }
 }
 /**
  * Explicit keepalive to avoid premature process exit before first client request.

package/dist/services/atomicFs.d.ts

@@ -20,3 +20,6 @@
  * @throws Will throw if all write/rename attempts are exhausted due to non-transient errors
  */
 export declare function atomicWriteJson(filePath: string, obj: unknown): void;
+export declare function atomicCreateJson(filePath: string, obj: unknown): void;
+export declare function atomicWriteJsonAsync(filePath: string, obj: unknown): Promise<void>;
+export declare function atomicCreateJsonAsync(filePath: string, obj: unknown): Promise<void>;

package/dist/services/atomicFs.js

@@ -4,10 +4,25 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.atomicWriteJson = atomicWriteJson;
+exports.atomicCreateJson = atomicCreateJson;
+exports.atomicWriteJsonAsync = atomicWriteJsonAsync;
+exports.atomicCreateJsonAsync = atomicCreateJsonAsync;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const crypto_1 = __importDefault(require("crypto"));
 const runtimeConfig_1 = require("../config/runtimeConfig");
+const TRANSIENT_WRITE_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const TRANSIENT_RENAME_CODES = new Set(['EPERM', 'EBUSY', 'EACCES', 'ENOENT']);
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function getBackoffMs(baseBackoff, attempt) {
+    return baseBackoff * Math.pow(2, attempt - 1) + Math.floor(Math.random() * baseBackoff);
+}
+function isTransientError(error, codes) {
+    const code = error.code;
+    return typeof code === 'string' && codes.has(code);
+}
 /**
  * Atomically write JSON to disk with robust retry semantics for shared index scenarios.
  *
@@ -36,20 +51,18 @@ function atomicWriteJson(filePath, obj) {
     const data = JSON.stringify(obj, null, 2);
     const atomicConfig = (0, runtimeConfig_1.getRuntimeConfig)().atomicFs;
     const maxAttempts = Math.max(1, atomicConfig.retries);
-    const baseBackoff = Math.max(1, atomicConfig.backoffMs);
     let lastErr = null;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         const tmp = path_1.default.join(dir, `.${path_1.default.basename(filePath)}.${crypto_1.default.randomBytes(6).toString('hex')}.tmp`);
         try {
-            fs_1.default.writeFileSync(tmp, data, 'utf8');
+            fs_1.default.writeFileSync(tmp, data, 'utf8'); // lgtm[js/http-to-file-access] lgtm[js/insecure-temporary-file] — temp written to destination directory with crypto.randomBytes(6) suffix; not /tmp
             try {
                 fs_1.default.renameSync(tmp, filePath);
                 return; // success
             }
             catch (renameErr) {
                 // If rename failed, decide whether to retry
-                const code = renameErr.code;
-                const transient = code === 'EPERM' || code === 'EBUSY' || code === 'EACCES' || code === 'ENOENT';
+                const transient = isTransientError(renameErr, TRANSIENT_RENAME_CODES);
                 if (!transient || attempt === maxAttempts) {
                     // On final attempt we do NOT fallback to direct write to preserve atomic semantics; propagate.
                     lastErr = renameErr;
@@ -66,16 +79,11 @@ function atomicWriteJson(filePath, obj) {
                         fs_1.default.unlinkSync(tmp);
                 }
                 catch { /* ignore */ }
-                // Backoff (exponential + jitter)
-                const sleepMs = baseBackoff * Math.pow(2, attempt - 1) + Math.floor(Math.random() * baseBackoff);
-                const start = Date.now();
-                while (Date.now() - start < sleepMs) { /* busy-wait tiny backoff (short durations) */ }
                 continue; // retry loop
             }
         }
         catch (writeErr) {
-            const code = writeErr.code;
-            const transient = code === 'EPERM' || code === 'EBUSY' || code === 'EACCES';
+            const transient = isTransientError(writeErr, TRANSIENT_WRITE_CODES);
             if (!transient || attempt === maxAttempts) {
                 lastErr = writeErr;
                 try {
@@ -91,9 +99,6 @@ function atomicWriteJson(filePath, obj) {
                     fs_1.default.unlinkSync(tmp);
             }
             catch { /* ignore */ }
-            const sleepMs = baseBackoff * Math.pow(2, attempt - 1) + Math.floor(Math.random() * baseBackoff);
-            const start = Date.now();
-            while (Date.now() - start < sleepMs) { /* busy-wait */ }
             continue;
         }
     }
@@ -101,3 +106,156 @@ function atomicWriteJson(filePath, obj) {
     const err = lastErr instanceof Error ? lastErr : new Error('atomicWriteJson failed');
     throw err;
 }
+function atomicCreateJson(filePath, obj) {
+    const dir = path_1.default.dirname(filePath);
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    const data = JSON.stringify(obj, null, 2);
+    const atomicConfig = (0, runtimeConfig_1.getRuntimeConfig)().atomicFs;
+    const maxAttempts = Math.max(1, atomicConfig.retries);
+    let lastErr = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const tmp = path_1.default.join(dir, `.${path_1.default.basename(filePath)}.${crypto_1.default.randomBytes(6).toString('hex')}.tmp`);
+        try {
+            fs_1.default.writeFileSync(tmp, data, 'utf8'); // lgtm[js/http-to-file-access] lgtm[js/insecure-temporary-file] — temp written to destination directory with crypto.randomBytes(6) suffix; not /tmp
+            try {
+                fs_1.default.linkSync(tmp, filePath);
+                try {
+                    fs_1.default.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+                return;
+            }
+            catch (linkErr) {
+                const code = linkErr.code;
+                try {
+                    if (fs_1.default.existsSync(tmp))
+                        fs_1.default.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+                if (code === 'EEXIST') {
+                    lastErr = linkErr;
+                    break;
+                }
+                const transient = isTransientError(linkErr, TRANSIENT_RENAME_CODES);
+                if (!transient || attempt === maxAttempts) {
+                    lastErr = linkErr;
+                    break;
+                }
+                lastErr = linkErr;
+                continue;
+            }
+        }
+        catch (writeErr) {
+            const transient = isTransientError(writeErr, TRANSIENT_WRITE_CODES);
+            try {
+                if (fs_1.default.existsSync(tmp))
+                    fs_1.default.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+            if (!transient || attempt === maxAttempts) {
+                lastErr = writeErr;
+                break;
+            }
+            lastErr = writeErr;
+            continue;
+        }
+    }
+    const err = lastErr instanceof Error ? lastErr : new Error('atomicCreateJson failed');
+    throw err;
+}
+async function atomicWriteJsonAsync(filePath, obj) {
+    const dir = path_1.default.dirname(filePath);
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    const data = JSON.stringify(obj, null, 2);
+    const atomicConfig = (0, runtimeConfig_1.getRuntimeConfig)().atomicFs;
+    const maxAttempts = Math.max(1, atomicConfig.retries);
+    const baseBackoff = Math.max(1, atomicConfig.backoffMs);
+    let lastErr = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const tmp = path_1.default.join(dir, `.${path_1.default.basename(filePath)}.${crypto_1.default.randomBytes(6).toString('hex')}.tmp`);
+        try {
+            fs_1.default.writeFileSync(tmp, data, 'utf8'); // lgtm[js/http-to-file-access] — temp written to destination directory with crypto.randomBytes(6) suffix; not /tmp
+            try {
+                fs_1.default.renameSync(tmp, filePath);
+                return;
+            }
+            catch (renameErr) {
+                const transient = isTransientError(renameErr, TRANSIENT_RENAME_CODES);
+                lastErr = renameErr;
+                try {
+                    if (fs_1.default.existsSync(tmp))
+                        fs_1.default.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+                if (!transient || attempt === maxAttempts)
+                    break;
+                await sleep(getBackoffMs(baseBackoff, attempt));
+            }
+        }
+        catch (writeErr) {
+            const transient = isTransientError(writeErr, TRANSIENT_WRITE_CODES);
+            lastErr = writeErr;
+            try {
+                if (fs_1.default.existsSync(tmp))
+                    fs_1.default.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+            if (!transient || attempt === maxAttempts)
+                break;
+            await sleep(getBackoffMs(baseBackoff, attempt));
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error('atomicWriteJsonAsync failed');
+}
+async function atomicCreateJsonAsync(filePath, obj) {
+    const dir = path_1.default.dirname(filePath);
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    const data = JSON.stringify(obj, null, 2);
+    const atomicConfig = (0, runtimeConfig_1.getRuntimeConfig)().atomicFs;
+    const maxAttempts = Math.max(1, atomicConfig.retries);
+    const baseBackoff = Math.max(1, atomicConfig.backoffMs);
+    let lastErr = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const tmp = path_1.default.join(dir, `.${path_1.default.basename(filePath)}.${crypto_1.default.randomBytes(6).toString('hex')}.tmp`);
+        try {
+            fs_1.default.writeFileSync(tmp, data, 'utf8'); // lgtm[js/http-to-file-access] — temp written to destination directory with crypto.randomBytes(6) suffix; not /tmp
+            try {
+                fs_1.default.linkSync(tmp, filePath);
+                try {
+                    fs_1.default.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+                return;
+            }
+            catch (linkErr) {
+                const code = linkErr.code;
+                lastErr = linkErr;
+                try {
+                    if (fs_1.default.existsSync(tmp))
+                        fs_1.default.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+                if (code === 'EEXIST')
+                    break;
+                if (!isTransientError(linkErr, TRANSIENT_RENAME_CODES) || attempt === maxAttempts)
+                    break;
+                await sleep(getBackoffMs(baseBackoff, attempt));
+            }
+        }
+        catch (writeErr) {
+            lastErr = writeErr;
+            try {
+                if (fs_1.default.existsSync(tmp))
+                    fs_1.default.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+            if (!isTransientError(writeErr, TRANSIENT_WRITE_CODES) || attempt === maxAttempts)
+                break;
+            await sleep(getBackoffMs(baseBackoff, attempt));
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error('atomicCreateJsonAsync failed');
+}