@caupulican/pi-adaptative 0.81.42 → 0.81.43

package/dist/core/trust-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trust-manager.d.ts","sourceRoot":"","sources":["../../src/core/trust-manager.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,IAAI,CAAC;AAyFlD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA2B1D;AAED,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IAEnC,YAAY,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,EAI7D;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAiBrC;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAarD;CACD","sourcesContent":["import { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join, resolve } from \"node:path\";\nimport lockfile from \"proper-lockfile\";\nimport { CONFIG_DIR_NAME } from \"../config.ts\";\nimport { canonicalizePath, resolvePath } from \"../utils/paths.ts\";\nimport { stateFile } from \"./agent-paths.ts\";\nimport { isWorkerSession } from \"./session-role.ts\";\n\nexport type ProjectTrustDecision = boolean | null;\n\ntype TrustFile = Record<string, boolean | null | undefined>;\n\nconst CONTEXT_FILE_NAMES = [\"AGENTS.md\", \"AGENTS.MD\", \"CLAUDE.md\", \"CLAUDE.MD\", \"GEMINI.md\", \"GEMINI.MD\"];\n\nfunction normalizeCwd(cwd: string): string {\n\treturn canonicalizePath(resolvePath(cwd));\n}\n\nfunction readTrustFile(path: string): TrustFile | undefined {\n\tif (!existsSync(path)) {\n\t\treturn {};\n\t}\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(readFileSync(path, \"utf-8\"));\n\t} catch {\n\t\treturn undefined;\n\t}\n\n\tif (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n\t\tthrow new Error(`Invalid trust store ${path}: expected an object`);\n\t}\n\n\tconst data: TrustFile = {};\n\tfor (const [key, value] of Object.entries(parsed)) {\n\t\tif (value !== true && value !== false && value !== null) {\n\t\t\tthrow new Error(`Invalid trust store ${path}: value for ${JSON.stringify(key)} must be true, false, or null`);\n\t\t}\n\t\tdata[key] = value;\n\t}\n\treturn data;\n}\n\nfunction writeTrustFile(path: string, data: TrustFile): void {\n\tconst sorted: TrustFile = {};\n\tfor (const key of Object.keys(data).sort()) {\n\t\tconst value = data[key];\n\t\tif (value === true || value === false || value === null) {\n\t\t\tsorted[key] = value;\n\t\t}\n\t}\n\tmkdirSync(dirname(path), { recursive: true });\n\twriteFileSync(path, `${JSON.stringify(sorted, null, 2)}\\n`, \"utf-8\");\n}\n\nfunction acquireTrustLockSync(path: string): () => void {\n\tconst trustDir = dirname(path);\n\tmkdirSync(trustDir, { recursive: true });\n\tconst maxAttempts = 10;\n\tconst delayMs = 20;\n\tlet lastError: unknown;\n\n\tfor (let attempt = 1; attempt <= maxAttempts; attempt++) {\n\t\ttry {\n\t\t\treturn lockfile.lockSync(trustDir, { realpath: false, lockfilePath: `${path}.lock` });\n\t\t} catch (error) {\n\t\t\tconst code =\n\t\t\t\ttypeof error === \"object\" && error !== null && \"code\" in error\n\t\t\t\t\t? String((error as { code?: unknown }).code)\n\t\t\t\t\t: undefined;\n\t\t\tif (code !== \"ELOCKED\" || attempt === maxAttempts) {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tlastError = error;\n\t\t\tconst start = Date.now();\n\t\t\twhile (Date.now() - start < delayMs) {\n\t\t\t\t// Sleep synchronously to avoid changing trust store callers to async.\n\t\t\t}\n\t\t}\n\t}\n\n\tif (lastError instanceof Error) {\n\t\tthrow lastError;\n\t}\n\tthrow new Error(\"Failed to acquire trust store lock\");\n}\n\nfunction withTrustFileLock<T>(path: string, fn: () => T): T {\n\tconst release = acquireTrustLockSync(path);\n\ttry {\n\t\treturn fn();\n\t} finally {\n\t\trelease();\n\t}\n}\n\nexport function hasProjectTrustInputs(cwd: string): boolean {\n\tlet currentDir = resolvePath(cwd);\n\tif (existsSync(join(currentDir, CONFIG_DIR_NAME))) {\n\t\treturn true;\n\t}\n\n\tconst root = resolve(\"/\");\n\twhile (true) {\n\t\tfor (const filename of CONTEXT_FILE_NAMES) {\n\t\t\tif (existsSync(join(currentDir, filename))) {\n\t\t\t\treturn true;\n\t\t\t}\n\t\t}\n\t\tif (existsSync(join(currentDir, \".agents\", \"skills\"))) {\n\t\t\treturn true;\n\t\t}\n\n\t\tif (currentDir === root) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst parentDir = resolve(currentDir, \"..\");\n\t\tif (parentDir === currentDir) {\n\t\t\treturn false;\n\t\t}\n\t\tcurrentDir = parentDir;\n\t}\n}\n\nexport class ProjectTrustStore {\n\tprivate trustPath: string;\n\tprivate readonly readOnly: boolean;\n\n\tconstructor(agentDir: string, options?: { readOnly?: boolean }) {\n\t\t// Machine-persisted trust decisions -- state/, not the agentDir root.\n\t\tthis.trustPath = stateFile(resolvePath(agentDir), \"trust.json\");\n\t\tthis.readOnly = options?.readOnly ?? isWorkerSession();\n\t}\n\n\tget(cwd: string): ProjectTrustDecision {\n\t\tif (this.readOnly) {\n\t\t\t// Zero-footprint (worker session): a lock-free read -- no lockfile, no state dir ever\n\t\t\t// created just from reading trust. A torn read (concurrent writer mid-rewrite) reads as\n\t\t\t// invalid JSON, which `readTrustFile` reports as `undefined`, and fails safe to untrusted\n\t\t\t// (null) below, never a crash.\n\t\t\tconst data = readTrustFile(this.trustPath);\n\t\t\tif (!data) return null;\n\t\t\tconst value = data[normalizeCwd(cwd)];\n\t\t\treturn value === true || value === false ? value : null;\n\t\t}\n\t\treturn withTrustFileLock(this.trustPath, () => {\n\t\t\tconst data = readTrustFile(this.trustPath);\n\t\t\tif (!data) return null;\n\t\t\tconst value = data[normalizeCwd(cwd)];\n\t\t\treturn value === true || value === false ? value : null;\n\t\t});\n\t}\n\n\tset(cwd: string, decision: ProjectTrustDecision): void {\n\t\tif (this.readOnly) return;\n\t\twithTrustFileLock(this.trustPath, () => {\n\t\t\tconst data = readTrustFile(this.trustPath);\n\t\t\tif (!data) return;\n\t\t\tconst key = normalizeCwd(cwd);\n\t\t\tif (decision === null) {\n\t\t\t\tdelete data[key];\n\t\t\t} else {\n\t\t\t\tdata[key] = decision;\n\t\t\t}\n\t\t\twriteTrustFile(this.trustPath, data);\n\t\t});\n\t}\n}\n"]}
+{"version":3,"file":"trust-manager.d.ts","sourceRoot":"","sources":["../../src/core/trust-manager.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,IAAI,CAAC;AAwDlD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA2B1D;AAED,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IAEnC,YAAY,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,EAI7D;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAgBrC;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAarD;CACD"}

package/dist/core/trust-manager.js

@@ -1,10 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import lockfile from "proper-lockfile";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { CONFIG_DIR_NAME } from "../config.js";
 import { canonicalizePath, resolvePath } from "../utils/paths.js";
 import { stateFile } from "./agent-paths.js";
 import { isWorkerSession } from "./session-role.js";
+import { acquireFileLockSync, LOW_LATENCY_FILE_LOCK_OPTIONS, writeFileAtomicSync } from "./util/atomic-file.js";
 const CONTEXT_FILE_NAMES = ["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD", "GEMINI.md", "GEMINI.MD"];
 function normalizeCwd(cwd) {
     return canonicalizePath(resolvePath(cwd));
@@ -40,40 +40,10 @@ function writeTrustFile(path, data) {
             sorted[key] = value;
         }
     }
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(sorted, null, 2)}\n`, "utf-8");
-}
-function acquireTrustLockSync(path) {
-    const trustDir = dirname(path);
-    mkdirSync(trustDir, { recursive: true });
-    const maxAttempts = 10;
-    const delayMs = 20;
-    let lastError;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        try {
-            return lockfile.lockSync(trustDir, { realpath: false, lockfilePath: `${path}.lock` });
-        }
-        catch (error) {
-            const code = typeof error === "object" && error !== null && "code" in error
-                ? String(error.code)
-                : undefined;
-            if (code !== "ELOCKED" || attempt === maxAttempts) {
-                throw error;
-            }
-            lastError = error;
-            const start = Date.now();
-            while (Date.now() - start < delayMs) {
-                // Sleep synchronously to avoid changing trust store callers to async.
-            }
-        }
-    }
-    if (lastError instanceof Error) {
-        throw lastError;
-    }
-    throw new Error("Failed to acquire trust store lock");
+    writeFileAtomicSync(path, `${JSON.stringify(sorted, null, 2)}\n`);
 }
 function withTrustFileLock(path, fn) {
-    const release = acquireTrustLockSync(path);
+    const release = acquireFileLockSync(path, LOW_LATENCY_FILE_LOCK_OPTIONS);
     try {
         return fn();
     }
@@ -107,8 +77,6 @@ export function hasProjectTrustInputs(cwd) {
     }
 }
 export class ProjectTrustStore {
-    trustPath;
-    readOnly;
     constructor(agentDir, options) {
         // Machine-persisted trust decisions -- state/, not the agentDir root.
         this.trustPath = stateFile(resolvePath(agentDir), "trust.json");
@@ -117,9 +85,8 @@ export class ProjectTrustStore {
     get(cwd) {
         if (this.readOnly) {
             // Zero-footprint (worker session): a lock-free read -- no lockfile, no state dir ever
-            // created just from reading trust. A torn read (concurrent writer mid-rewrite) reads as
-            // invalid JSON, which `readTrustFile` reports as `undefined`, and fails safe to untrusted
-            // (null) below, never a crash.
+            // created just from reading trust. Writers publish by atomic rename, so a worker sees either
+            // the prior or next complete generation and still fails malformed input safe to untrusted.
             const data = readTrustFile(this.trustPath);
             if (!data)
                 return null;

package/dist/core/trust-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"trust-manager.js","sourceRoot":"","sources":["../../src/core/trust-manager.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join, resolve } from \"node:path\";\nimport lockfile from \"proper-lockfile\";\nimport { CONFIG_DIR_NAME } from \"../config.ts\";\nimport { canonicalizePath, resolvePath } from \"../utils/paths.ts\";\nimport { stateFile } from \"./agent-paths.ts\";\nimport { isWorkerSession } from \"./session-role.ts\";\n\nexport type ProjectTrustDecision = boolean | null;\n\ntype TrustFile = Record<string, boolean | null | undefined>;\n\nconst CONTEXT_FILE_NAMES = [\"AGENTS.md\", \"AGENTS.MD\", \"CLAUDE.md\", \"CLAUDE.MD\", \"GEMINI.md\", \"GEMINI.MD\"];\n\nfunction normalizeCwd(cwd: string): string {\n\treturn canonicalizePath(resolvePath(cwd));\n}\n\nfunction readTrustFile(path: string): TrustFile | undefined {\n\tif (!existsSync(path)) {\n\t\treturn {};\n\t}\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(readFileSync(path, \"utf-8\"));\n\t} catch {\n\t\treturn undefined;\n\t}\n\n\tif (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n\t\tthrow new Error(`Invalid trust store ${path}: expected an object`);\n\t}\n\n\tconst data: TrustFile = {};\n\tfor (const [key, value] of Object.entries(parsed)) {\n\t\tif (value !== true && value !== false && value !== null) {\n\t\t\tthrow new Error(`Invalid trust store ${path}: value for ${JSON.stringify(key)} must be true, false, or null`);\n\t\t}\n\t\tdata[key] = value;\n\t}\n\treturn data;\n}\n\nfunction writeTrustFile(path: string, data: TrustFile): void {\n\tconst sorted: TrustFile = {};\n\tfor (const key of Object.keys(data).sort()) {\n\t\tconst value = data[key];\n\t\tif (value === true || value === false || value === null) {\n\t\t\tsorted[key] = value;\n\t\t}\n\t}\n\tmkdirSync(dirname(path), { recursive: true });\n\twriteFileSync(path, `${JSON.stringify(sorted, null, 2)}\\n`, \"utf-8\");\n}\n\nfunction acquireTrustLockSync(path: string): () => void {\n\tconst trustDir = dirname(path);\n\tmkdirSync(trustDir, { recursive: true });\n\tconst maxAttempts = 10;\n\tconst delayMs = 20;\n\tlet lastError: unknown;\n\n\tfor (let attempt = 1; attempt <= maxAttempts; attempt++) {\n\t\ttry {\n\t\t\treturn lockfile.lockSync(trustDir, { realpath: false, lockfilePath: `${path}.lock` });\n\t\t} catch (error) {\n\t\t\tconst code =\n\t\t\t\ttypeof error === \"object\" && error !== null && \"code\" in error\n\t\t\t\t\t? String((error as { code?: unknown }).code)\n\t\t\t\t\t: undefined;\n\t\t\tif (code !== \"ELOCKED\" || attempt === maxAttempts) {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tlastError = error;\n\t\t\tconst start = Date.now();\n\t\t\twhile (Date.now() - start < delayMs) {\n\t\t\t\t// Sleep synchronously to avoid changing trust store callers to async.\n\t\t\t}\n\t\t}\n\t}\n\n\tif (lastError instanceof Error) {\n\t\tthrow lastError;\n\t}\n\tthrow new Error(\"Failed to acquire trust store lock\");\n}\n\nfunction withTrustFileLock<T>(path: string, fn: () => T): T {\n\tconst release = acquireTrustLockSync(path);\n\ttry {\n\t\treturn fn();\n\t} finally {\n\t\trelease();\n\t}\n}\n\nexport function hasProjectTrustInputs(cwd: string): boolean {\n\tlet currentDir = resolvePath(cwd);\n\tif (existsSync(join(currentDir, CONFIG_DIR_NAME))) {\n\t\treturn true;\n\t}\n\n\tconst root = resolve(\"/\");\n\twhile (true) {\n\t\tfor (const filename of CONTEXT_FILE_NAMES) {\n\t\t\tif (existsSync(join(currentDir, filename))) {\n\t\t\t\treturn true;\n\t\t\t}\n\t\t}\n\t\tif (existsSync(join(currentDir, \".agents\", \"skills\"))) {\n\t\t\treturn true;\n\t\t}\n\n\t\tif (currentDir === root) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst parentDir = resolve(currentDir, \"..\");\n\t\tif (parentDir === currentDir) {\n\t\t\treturn false;\n\t\t}\n\t\tcurrentDir = parentDir;\n\t}\n}\n\nexport class ProjectTrustStore {\n\tprivate trustPath: string;\n\tprivate readonly readOnly: boolean;\n\n\tconstructor(agentDir: string, options?: { readOnly?: boolean }) {\n\t\t// Machine-persisted trust decisions -- state/, not the agentDir root.\n\t\tthis.trustPath = stateFile(resolvePath(agentDir), \"trust.json\");\n\t\tthis.readOnly = options?.readOnly ?? isWorkerSession();\n\t}\n\n\tget(cwd: string): ProjectTrustDecision {\n\t\tif (this.readOnly) {\n\t\t\t// Zero-footprint (worker session): a lock-free read -- no lockfile, no state dir ever\n\t\t\t// created just from reading trust. A torn read (concurrent writer mid-rewrite) reads as\n\t\t\t// invalid JSON, which `readTrustFile` reports as `undefined`, and fails safe to untrusted\n\t\t\t// (null) below, never a crash.\n\t\t\tconst data = readTrustFile(this.trustPath);\n\t\t\tif (!data) return null;\n\t\t\tconst value = data[normalizeCwd(cwd)];\n\t\t\treturn value === true || value === false ? value : null;\n\t\t}\n\t\treturn withTrustFileLock(this.trustPath, () => {\n\t\t\tconst data = readTrustFile(this.trustPath);\n\t\t\tif (!data) return null;\n\t\t\tconst value = data[normalizeCwd(cwd)];\n\t\t\treturn value === true || value === false ? value : null;\n\t\t});\n\t}\n\n\tset(cwd: string, decision: ProjectTrustDecision): void {\n\t\tif (this.readOnly) return;\n\t\twithTrustFileLock(this.trustPath, () => {\n\t\t\tconst data = readTrustFile(this.trustPath);\n\t\t\tif (!data) return;\n\t\t\tconst key = normalizeCwd(cwd);\n\t\t\tif (decision === null) {\n\t\t\t\tdelete data[key];\n\t\t\t} else {\n\t\t\t\tdata[key] = decision;\n\t\t\t}\n\t\t\twriteTrustFile(this.trustPath, data);\n\t\t});\n\t}\n}\n"]}
+{"version":3,"file":"trust-manager.js","sourceRoot":"","sources":["../../src/core/trust-manager.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { CONFIG_DIR_NAME } from \"../config.ts\";\nimport { canonicalizePath, resolvePath } from \"../utils/paths.ts\";\nimport { stateFile } from \"./agent-paths.ts\";\nimport { isWorkerSession } from \"./session-role.ts\";\nimport { acquireFileLockSync, LOW_LATENCY_FILE_LOCK_OPTIONS, writeFileAtomicSync } from \"./util/atomic-file.ts\";\n\nexport type ProjectTrustDecision = boolean | null;\n\ntype TrustFile = Record<string, boolean | null | undefined>;\n\nconst CONTEXT_FILE_NAMES = [\"AGENTS.md\", \"AGENTS.MD\", \"CLAUDE.md\", \"CLAUDE.MD\", \"GEMINI.md\", \"GEMINI.MD\"];\n\nfunction normalizeCwd(cwd: string): string {\n\treturn canonicalizePath(resolvePath(cwd));\n}\n\nfunction readTrustFile(path: string): TrustFile | undefined {\n\tif (!existsSync(path)) {\n\t\treturn {};\n\t}\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(readFileSync(path, \"utf-8\"));\n\t} catch {\n\t\treturn undefined;\n\t}\n\n\tif (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n\t\tthrow new Error(`Invalid trust store ${path}: expected an object`);\n\t}\n\n\tconst data: TrustFile = {};\n\tfor (const [key, value] of Object.entries(parsed)) {\n\t\tif (value !== true && value !== false && value !== null) {\n\t\t\tthrow new Error(`Invalid trust store ${path}: value for ${JSON.stringify(key)} must be true, false, or null`);\n\t\t}\n\t\tdata[key] = value;\n\t}\n\treturn data;\n}\n\nfunction writeTrustFile(path: string, data: TrustFile): void {\n\tconst sorted: TrustFile = {};\n\tfor (const key of Object.keys(data).sort()) {\n\t\tconst value = data[key];\n\t\tif (value === true || value === false || value === null) {\n\t\t\tsorted[key] = value;\n\t\t}\n\t}\n\twriteFileAtomicSync(path, `${JSON.stringify(sorted, null, 2)}\\n`);\n}\n\nfunction withTrustFileLock<T>(path: string, fn: () => T): T {\n\tconst release = acquireFileLockSync(path, LOW_LATENCY_FILE_LOCK_OPTIONS);\n\ttry {\n\t\treturn fn();\n\t} finally {\n\t\trelease();\n\t}\n}\n\nexport function hasProjectTrustInputs(cwd: string): boolean {\n\tlet currentDir = resolvePath(cwd);\n\tif (existsSync(join(currentDir, CONFIG_DIR_NAME))) {\n\t\treturn true;\n\t}\n\n\tconst root = resolve(\"/\");\n\twhile (true) {\n\t\tfor (const filename of CONTEXT_FILE_NAMES) {\n\t\t\tif (existsSync(join(currentDir, filename))) {\n\t\t\t\treturn true;\n\t\t\t}\n\t\t}\n\t\tif (existsSync(join(currentDir, \".agents\", \"skills\"))) {\n\t\t\treturn true;\n\t\t}\n\n\t\tif (currentDir === root) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst parentDir = resolve(currentDir, \"..\");\n\t\tif (parentDir === currentDir) {\n\t\t\treturn false;\n\t\t}\n\t\tcurrentDir = parentDir;\n\t}\n}\n\nexport class ProjectTrustStore {\n\tprivate trustPath: string;\n\tprivate readonly readOnly: boolean;\n\n\tconstructor(agentDir: string, options?: { readOnly?: boolean }) {\n\t\t// Machine-persisted trust decisions -- state/, not the agentDir root.\n\t\tthis.trustPath = stateFile(resolvePath(agentDir), \"trust.json\");\n\t\tthis.readOnly = options?.readOnly ?? isWorkerSession();\n\t}\n\n\tget(cwd: string): ProjectTrustDecision {\n\t\tif (this.readOnly) {\n\t\t\t// Zero-footprint (worker session): a lock-free read -- no lockfile, no state dir ever\n\t\t\t// created just from reading trust. Writers publish by atomic rename, so a worker sees either\n\t\t\t// the prior or next complete generation and still fails malformed input safe to untrusted.\n\t\t\tconst data = readTrustFile(this.trustPath);\n\t\t\tif (!data) return null;\n\t\t\tconst value = data[normalizeCwd(cwd)];\n\t\t\treturn value === true || value === false ? value : null;\n\t\t}\n\t\treturn withTrustFileLock(this.trustPath, () => {\n\t\t\tconst data = readTrustFile(this.trustPath);\n\t\t\tif (!data) return null;\n\t\t\tconst value = data[normalizeCwd(cwd)];\n\t\t\treturn value === true || value === false ? value : null;\n\t\t});\n\t}\n\n\tset(cwd: string, decision: ProjectTrustDecision): void {\n\t\tif (this.readOnly) return;\n\t\twithTrustFileLock(this.trustPath, () => {\n\t\t\tconst data = readTrustFile(this.trustPath);\n\t\t\tif (!data) return;\n\t\t\tconst key = normalizeCwd(cwd);\n\t\t\tif (decision === null) {\n\t\t\t\tdelete data[key];\n\t\t\t} else {\n\t\t\t\tdata[key] = decision;\n\t\t\t}\n\t\t\twriteTrustFile(this.trustPath, data);\n\t\t});\n\t}\n}\n"]}

package/dist/core/util/atomic-file.d.ts

@@ -37,15 +37,34 @@ export interface AtomicFileLockOptions {
      *   the existing execution model rather than introducing a new one.
      */
     retries?: number;
+    /** Initial delay between sync/async acquisition attempts; defaults to 25ms. */
+    minRetryDelayMs?: number;
+    /** Maximum delay between sync/async acquisition attempts; defaults to 500ms. */
+    maxRetryDelayMs?: number;
+    /** Retry-delay multiplier; defaults to 2. Set max=min for a fixed delay. */
+    retryFactor?: number;
     /** Resolve symlinks before locking (proper-lockfile `realpath`); false matches file-store.ts. */
     realpath?: boolean;
     /** Lock staleness window in ms (proper-lockfile `stale`); omitted = proper-lockfile's own default. */
     stale?: number;
+    /** Explicit proper-lockfile directory path; defaults to `${filePath}.lock`. */
+    lockfilePath?: string;
 }
 export interface AtomicFileWriteOptions {
     /** POSIX permission bits applied to the temporary file and inherited by the renamed destination. */
     mode?: number;
 }
+/**
+ * Existing auth/settings/trust paths historically used 10 total attempts separated by 20ms. Keep
+ * that low-latency user-facing policy explicit while routing the mechanism through this module.
+ */
+export declare const LOW_LATENCY_FILE_LOCK_OPTIONS: Readonly<AtomicFileLockOptions>;
+/**
+ * Acquire a synchronous advisory file lock and return its release function. This is the shared
+ * mechanism for coordinators that must hold several locks in a deterministic order before entering
+ * one critical section; callers retain ownership of release ordering and release-error semantics.
+ */
+export declare function acquireFileLockSync(filePath: string, options?: AtomicFileLockOptions): () => void;
 /**
  * Hold an exclusive advisory lock on `filePath` for the duration of `fn` (sync). Always releases,
  * including when `fn` throws.

package/dist/core/util/atomic-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-file.d.ts","sourceRoot":"","sources":["../../../src/core/util/atomic-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiEH,MAAM,WAAW,qBAAqB;IACrC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACtC,oGAAoG;IACpG,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AA2ED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,CAAC,CAcrG;AAED,0GAA0G;AAC1G,wBAAsB,YAAY,CAAC,CAAC,EACnC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAiBZ;AA6BD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAY7G;AAED,wDAAwD;AACxD,wBAAsB,eAAe,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAYf","sourcesContent":["/**\n * Shared atomic-file helper: a single lock+tmp+rename implementation reused by every\n * on-disk store that does a read-modify-write against a JSON/text file. Modeled on the pattern\n * already proven in `memory/providers/file-store.ts` (proper-lockfile advisory lock + write-tmp-\n * then-rename); before this helper existed the pattern was copy-pasted per store, and most copies\n * were missing either the lock, the atomic write, or both.\n *\n * Two call shapes:\n *  - `withFileLock(Sync)` — hold an exclusive advisory lock across an arbitrary read-modify-write\n *    callback. The lock spans BOTH the read and the write, closing the classic RMW race where two\n *    writers each read the old content before either writes back.\n *  - `writeFileAtomic(Sync)` — write-tmp-then-rename. Used INSIDE a `withFileLock` callback (or\n *    standalone, for a pure overwrite that has no read step to race).\n *\n * Sync and async variants are both exported. Most existing stores expose a synchronous public API\n * called from hot, non-async paths (e.g. a per-token-stream perf sample), so the sync variant lets\n * them gain locking without forcing an async ripple through their callers; the async variant is for\n * call sites that are already async.\n */\n\nimport { randomUUID } from \"node:crypto\";\nimport { promises as fsPromises, mkdirSync, renameSync, unlinkSync, writeFileSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport lockfile from \"proper-lockfile\";\n\n/**\n * Bounded rename retry budget for the win32-only transient-rename handling below (see\n * {@link isTransientRenameErrorOnWin32}). Backoff doubles each attempt starting at\n * {@link RENAME_RETRY_MIN_TIMEOUT_MS} and capped at {@link RENAME_RETRY_MAX_TIMEOUT_MS}, mirroring\n * the doubling-backoff shape used for lock acquisition above. With {@link RENAME_RETRY_ATTEMPTS}\n * extra attempts (10, 20, 40, 80, ... capped at 200) the worst-case total wait is ~1.03s\n * (10+20+40+80+160+200+200+200+200 ~= 1110ms across 9 gaps), which comfortably covers the\n * millisecond-scale window Defender/the Windows Search indexer hold a freshly-written file open\n * without FILE_SHARE_DELETE before releasing it.\n */\nconst RENAME_RETRY_ATTEMPTS = 9;\nconst RENAME_RETRY_MIN_TIMEOUT_MS = 10;\nconst RENAME_RETRY_MAX_TIMEOUT_MS = 200;\n\n/**\n * On win32, antivirus (e.g. Windows Defender's real-time scanner) and the Windows Search indexer\n * routinely open a freshly-written file for a brief scan without `FILE_SHARE_DELETE`, which makes a\n * rename over/of that file fail transiently with EPERM/EACCES/EBUSY for a few milliseconds. This is\n * a well-documented platform semantic, not a bug in our write path — it's exactly why the\n * `graceful-fs` package ships its own win32 rename-retry wrapper. POSIX platforms never exhibit this\n * transient (a POSIX rename either succeeds or fails for a real, non-transient reason), so retry is\n * gated strictly to win32 to keep POSIX behavior byte-identical to a bare rename.\n */\nfunction isTransientRenameErrorOnWin32(err: unknown): boolean {\n\tif (process.platform !== \"win32\") return false;\n\tif (typeof err !== \"object\" || err === null) return false;\n\tconst code = (err as { code?: string }).code;\n\treturn code === \"EPERM\" || code === \"EACCES\" || code === \"EBUSY\";\n}\n\n/** Sync counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */\nfunction renameSyncWithRetry(tmpPath: string, filePath: string): void {\n\tfor (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {\n\t\ttry {\n\t\t\trenameSync(tmpPath, filePath);\n\t\t\treturn;\n\t\t} catch (err) {\n\t\t\tif (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS) throw err;\n\t\t\tconst backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);\n\t\t\tblockingSleepMs(backoffMs);\n\t\t}\n\t}\n}\n\n/** Async counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */\nasync function renameWithRetry(tmpPath: string, filePath: string): Promise<void> {\n\tfor (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {\n\t\ttry {\n\t\t\tawait fsPromises.rename(tmpPath, filePath);\n\t\t\treturn;\n\t\t} catch (err) {\n\t\t\tif (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS) throw err;\n\t\t\tconst backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);\n\t\t\tawait new Promise((resolve) => setTimeout(resolve, backoffMs));\n\t\t}\n\t}\n}\n\nexport interface AtomicFileLockOptions {\n\t/**\n\t * Bounded retry attempts while waiting for a lock already held elsewhere. Both variants use a\n\t * SHORT, capped backoff (see {@link RETRY_MIN_TIMEOUT_MS}/{@link RETRY_MAX_TIMEOUT_MS}) — these\n\t * stores' critical sections are sub-millisecond reads+writes of small JSON/text files, so\n\t * contention should clear in milliseconds, not the multi-second-to-31-second worst case\n\t * proper-lockfile's OWN default backoff produces for a bare numeric `retries` (its default\n\t * `minTimeout` is 1000ms with factor 2 — see node_modules/retry/lib/retry.js). Passing a bare\n\t * number straight through would turn brief contention into a multi-second stall on a hot path\n\t * (e.g. a per-token-stream perf sample), so both variants instead build an explicit short-backoff\n\t * `retry` options object.\n\t * - Async (`withFileLock`): forwarded as `{retries, minTimeout, maxTimeout}` to proper-lockfile.\n\t * - Sync (`withFileLockSync`): proper-lockfile's sync API REJECTS `retries > 0` outright (it\n\t *   requires the whole acquire flow to be synchronous — see proper-lockfile/lib/adapter.js\n\t *   `toSyncOptions`, which throws `ESYNC`). So the sync path implements its own bounded retry\n\t *   around single `lockfile.lockSync` attempts, blocking briefly between them (Atomics.wait) —\n\t *   callers are already fully synchronous fs code, so a short blocking wait on contention matches\n\t *   the existing execution model rather than introducing a new one.\n\t */\n\tretries?: number;\n\t/** Resolve symlinks before locking (proper-lockfile `realpath`); false matches file-store.ts. */\n\trealpath?: boolean;\n\t/** Lock staleness window in ms (proper-lockfile `stale`); omitted = proper-lockfile's own default. */\n\tstale?: number;\n}\n\nexport interface AtomicFileWriteOptions {\n\t/** POSIX permission bits applied to the temporary file and inherited by the renamed destination. */\n\tmode?: number;\n}\n\nconst DEFAULT_RETRIES = 10;\nconst DEFAULT_REALPATH = false;\n/**\n * Capped doubling backoff shared by both variants — see {@link AtomicFileLockOptions.retries}.\n * With the current defaults (10 retries, 25ms floor, 500ms cap) the total worst-case contention\n * budget is ~3.3s (25+50+100+200+400+500+500+500+500+500), comfortably over the >= 2s floor this\n * needs to survive a loaded CI runner (e.g. the Windows CI mkdir/rmdir lock-directory churn under\n * two-real-OS-thread contention).\n */\nconst RETRY_MIN_TIMEOUT_MS = 25;\nconst RETRY_MAX_TIMEOUT_MS = 500;\nfunction ensureLockDirSync(filePath: string): void {\n\tmkdirSync(dirname(filePath), { recursive: true });\n}\n\nasync function ensureLockDir(filePath: string): Promise<void> {\n\tawait fsPromises.mkdir(dirname(filePath), { recursive: true });\n}\n\nfunction isLockedError(err: unknown): boolean {\n\tif (typeof err !== \"object\" || err === null) return false;\n\tconst code = (err as { code?: string }).code;\n\tif (code === \"ELOCKED\") return true;\n\t// On win32, mkdir-ing the lock directory can transiently surface EPERM (rather than the\n\t// expected EEXIST) when a previous incarnation of that directory is concurrently being\n\t// rmdir'd by the racing releaser — the mkdir lands mid-teardown and the OS reports \"operation\n\t// not permitted\" instead of \"already exists\". This is contention, not a real permissions\n\t// failure, so treat it identically to ELOCKED: retry with the existing backoff rather than\n\t// letting it escape as fatal. POSIX platforms don't exhibit this transient and keep surfacing\n\t// real EPERM (e.g. an actually unwritable directory) as fatal.\n\tif (code === \"EPERM\" && process.platform === \"win32\") return true;\n\treturn false;\n}\n\n/** Block the calling thread for `ms` without spinning the CPU (Atomics.wait on a private buffer). */\nfunction blockingSleepMs(ms: number): void {\n\tAtomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);\n}\n\n/**\n * Acquire a proper-lockfile sync lock with bounded retry on `ELOCKED` (proper-lockfile's sync API\n * itself forbids `retries > 0`; see {@link AtomicFileLockOptions.retries}).\n *\n * Backoff doubles each attempt (mirroring the `retry` module's own `factor: 2` default that the\n * async path gets for free from proper-lockfile), starting at {@link RETRY_MIN_TIMEOUT_MS} and\n * capped at {@link RETRY_MAX_TIMEOUT_MS}.\n *\n * This is budget PARITY between two implementations of the same lock-acquisition contract, not\n * flake-masking: `options.retries` (a count of RETRIES, i.e. attempts after the first) means the\n * same thing on both paths, so both must make `retries + 1` total acquisition attempts with the\n * same per-gap backoff schedule. The async path gets `retries + 1` attempts for free from the\n * `retry` module (it retries `options.retries` times after its initial attempt); the sync path\n * used to loop exactly `attempts` times total (one fewer gap, and one fewer attempt than the\n * async path for the same `retries` value), which under-budgeted it relative to its async sibling\n * and surfaced as spurious ELOCKED failures under real contention (e.g. two OS threads hammering\n * the same file, or mkdir/rmdir lock-directory churn on a loaded Windows CI runner).\n */\nfunction lockSyncWithRetry(filePath: string, options: AtomicFileLockOptions): () => void {\n\tconst attempts = Math.max(1, options.retries ?? DEFAULT_RETRIES) + 1;\n\tconst lockOptions = { realpath: options.realpath ?? DEFAULT_REALPATH, stale: options.stale };\n\tfor (let attempt = 1; attempt <= attempts; attempt++) {\n\t\ttry {\n\t\t\treturn lockfile.lockSync(filePath, lockOptions);\n\t\t} catch (err) {\n\t\t\tif (!isLockedError(err) || attempt === attempts) throw err;\n\t\t\tconst backoffMs = Math.min(RETRY_MIN_TIMEOUT_MS * 2 ** (attempt - 1), RETRY_MAX_TIMEOUT_MS);\n\t\t\tblockingSleepMs(backoffMs);\n\t\t}\n\t}\n\t// Unreachable (the loop always returns or throws), but keeps the function's return type honest.\n\tthrow new Error(`Failed to acquire lock for ${filePath}`);\n}\n\n/**\n * Hold an exclusive advisory lock on `filePath` for the duration of `fn` (sync). Always releases,\n * including when `fn` throws.\n */\nexport function withFileLockSync<T>(filePath: string, fn: () => T, options?: AtomicFileLockOptions): T {\n\tensureLockDirSync(filePath);\n\tconst release = lockSyncWithRetry(filePath, options ?? {});\n\ttry {\n\t\treturn fn();\n\t} finally {\n\t\t// A lock-cleanup failure must never mask fn()'s result (or replace fn()'s own thrown error) —\n\t\t// by this point fn() has already durably committed or failed on its own terms.\n\t\ttry {\n\t\t\trelease();\n\t\t} catch {\n\t\t\t// best-effort cleanup; a stale lock self-expires via proper-lockfile's `stale` window\n\t\t}\n\t}\n}\n\n/** Async counterpart of {@link withFileLockSync}. Always releases, including when `fn` throws/rejects. */\nexport async function withFileLock<T>(\n\tfilePath: string,\n\tfn: () => Promise<T> | T,\n\toptions?: AtomicFileLockOptions,\n): Promise<T> {\n\tawait ensureLockDir(filePath);\n\tconst release = await lockfile.lock(filePath, {\n\t\trealpath: options?.realpath ?? DEFAULT_REALPATH,\n\t\tretries: {\n\t\t\tretries: options?.retries ?? DEFAULT_RETRIES,\n\t\t\tminTimeout: RETRY_MIN_TIMEOUT_MS,\n\t\t\tmaxTimeout: RETRY_MAX_TIMEOUT_MS,\n\t\t},\n\t\tstale: options?.stale,\n\t});\n\ttry {\n\t\treturn await fn();\n\t} finally {\n\t\t// See {@link withFileLockSync} — cleanup failures must not mask fn()'s outcome.\n\t\tawait release().catch(() => {});\n\t}\n}\n\n/**\n * Write `content` to `filePath` via write-tmp-then-rename (sync); the rename is atomic on the same\n * filesystem, so a concurrent reader never observes a partially-written file. Does NOT itself lock —\n * call from inside {@link withFileLockSync} when the write follows a read that must not race another\n * writer's read+write; call standalone for an unconditional overwrite with no read step.\n */\nfunction temporaryPath(filePath: string): string {\n\treturn `${filePath}.${process.pid}.${randomUUID()}.tmp`;\n}\n\n/** Remove one invocation's temporary path without masking the original write/rename failure. */\nfunction removeTemporaryPathSync(tmpPath: string): void {\n\ttry {\n\t\tunlinkSync(tmpPath);\n\t} catch {\n\t\t// The rename may have consumed the path, or another failure may have prevented its creation.\n\t}\n}\n\nasync function removeTemporaryPath(tmpPath: string): Promise<void> {\n\ttry {\n\t\tawait fsPromises.unlink(tmpPath);\n\t} catch {\n\t\t// The rename may have consumed the path, or another failure may have prevented its creation.\n\t}\n}\n\nexport function writeFileAtomicSync(filePath: string, content: string, options?: AtomicFileWriteOptions): void {\n\tmkdirSync(dirname(filePath), { recursive: true });\n\tconst tmpPath = temporaryPath(filePath);\n\tlet renamed = false;\n\ttry {\n\t\t// `wx` makes a nonce collision harmless: never truncate another writer's temporary file.\n\t\twriteFileSync(tmpPath, content, { encoding: \"utf-8\", flag: \"wx\", mode: options?.mode });\n\t\trenameSyncWithRetry(tmpPath, filePath);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) removeTemporaryPathSync(tmpPath);\n\t}\n}\n\n/** Async counterpart of {@link writeFileAtomicSync}. */\nexport async function writeFileAtomic(\n\tfilePath: string,\n\tcontent: string,\n\toptions?: AtomicFileWriteOptions,\n): Promise<void> {\n\tawait fsPromises.mkdir(dirname(filePath), { recursive: true });\n\tconst tmpPath = temporaryPath(filePath);\n\tlet renamed = false;\n\ttry {\n\t\t// `wx` makes a nonce collision harmless: never truncate another writer's temporary file.\n\t\tawait fsPromises.writeFile(tmpPath, content, { encoding: \"utf-8\", flag: \"wx\", mode: options?.mode });\n\t\tawait renameWithRetry(tmpPath, filePath);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) await removeTemporaryPath(tmpPath);\n\t}\n}\n"]}
+{"version":3,"file":"atomic-file.d.ts","sourceRoot":"","sources":["../../../src/core/util/atomic-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiEH,MAAM,WAAW,qBAAqB;IACrC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACtC,oGAAoG;IACpG,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAcD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,QAAQ,CAAC,qBAAqB,CAIxE,CAAC;AAmEH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,IAAI,CAkBrG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,CAAC,CAarG;AAED,0GAA0G;AAC1G,wBAAsB,YAAY,CAAC,CAAC,EACnC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAmBZ;AA6BD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAY7G;AAED,wDAAwD;AACxD,wBAAsB,eAAe,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/core/util/atomic-file.js

@@ -92,11 +92,23 @@ const DEFAULT_REALPATH = false;
  */
 const RETRY_MIN_TIMEOUT_MS = 25;
 const RETRY_MAX_TIMEOUT_MS = 500;
-function ensureLockDirSync(filePath) {
-    mkdirSync(dirname(filePath), { recursive: true });
+/**
+ * Existing auth/settings/trust paths historically used 10 total attempts separated by 20ms. Keep
+ * that low-latency user-facing policy explicit while routing the mechanism through this module.
+ */
+export const LOW_LATENCY_FILE_LOCK_OPTIONS = Object.freeze({
+    retries: 9,
+    minRetryDelayMs: 20,
+    maxRetryDelayMs: 20,
+});
+function lockDirectory(filePath, lockfilePath) {
+    return dirname(lockfilePath ?? filePath);
 }
-async function ensureLockDir(filePath) {
-    await fsPromises.mkdir(dirname(filePath), { recursive: true });
+function ensureLockDirSync(filePath, lockfilePath) {
+    mkdirSync(lockDirectory(filePath, lockfilePath), { recursive: true });
+}
+async function ensureLockDir(filePath, lockfilePath) {
+    await fsPromises.mkdir(lockDirectory(filePath, lockfilePath), { recursive: true });
 }
 function isLockedError(err) {
     if (typeof err !== "object" || err === null)
@@ -137,9 +149,32 @@ function blockingSleepMs(ms) {
  * and surfaced as spurious ELOCKED failures under real contention (e.g. two OS threads hammering
  * the same file, or mkdir/rmdir lock-directory churn on a loaded Windows CI runner).
  */
-function lockSyncWithRetry(filePath, options) {
-    const attempts = Math.max(1, options.retries ?? DEFAULT_RETRIES) + 1;
-    const lockOptions = { realpath: options.realpath ?? DEFAULT_REALPATH, stale: options.stale };
+function retryCount(options) {
+    const configured = options.retries ?? DEFAULT_RETRIES;
+    return Number.isFinite(configured) ? Math.max(0, Math.floor(configured)) : DEFAULT_RETRIES;
+}
+function retryDelayMs(options, attempt) {
+    const configuredMin = options.minRetryDelayMs ?? RETRY_MIN_TIMEOUT_MS;
+    const minDelay = Number.isFinite(configuredMin) ? Math.max(0, configuredMin) : RETRY_MIN_TIMEOUT_MS;
+    const configuredMax = options.maxRetryDelayMs ?? RETRY_MAX_TIMEOUT_MS;
+    const maxDelay = Number.isFinite(configuredMax) ? Math.max(minDelay, configuredMax) : RETRY_MAX_TIMEOUT_MS;
+    const configuredFactor = options.retryFactor ?? 2;
+    const factor = Number.isFinite(configuredFactor) ? Math.max(1, configuredFactor) : 2;
+    return Math.min(minDelay * factor ** (attempt - 1), maxDelay);
+}
+/**
+ * Acquire a synchronous advisory file lock and return its release function. This is the shared
+ * mechanism for coordinators that must hold several locks in a deterministic order before entering
+ * one critical section; callers retain ownership of release ordering and release-error semantics.
+ */
+export function acquireFileLockSync(filePath, options = {}) {
+    ensureLockDirSync(filePath, options.lockfilePath);
+    const attempts = retryCount(options) + 1;
+    const lockOptions = {
+        lockfilePath: options.lockfilePath,
+        realpath: options.realpath ?? DEFAULT_REALPATH,
+        stale: options.stale,
+    };
     for (let attempt = 1; attempt <= attempts; attempt++) {
         try {
             return lockfile.lockSync(filePath, lockOptions);
@@ -147,8 +182,7 @@ function lockSyncWithRetry(filePath, options) {
         catch (err) {
             if (!isLockedError(err) || attempt === attempts)
                 throw err;
-            const backoffMs = Math.min(RETRY_MIN_TIMEOUT_MS * 2 ** (attempt - 1), RETRY_MAX_TIMEOUT_MS);
-            blockingSleepMs(backoffMs);
+            blockingSleepMs(retryDelayMs(options, attempt));
         }
     }
     // Unreachable (the loop always returns or throws), but keeps the function's return type honest.
@@ -159,8 +193,7 @@ function lockSyncWithRetry(filePath, options) {
  * including when `fn` throws.
  */
 export function withFileLockSync(filePath, fn, options) {
-    ensureLockDirSync(filePath);
-    const release = lockSyncWithRetry(filePath, options ?? {});
+    const release = acquireFileLockSync(filePath, options);
     try {
         return fn();
     }
@@ -177,13 +210,15 @@ export function withFileLockSync(filePath, fn, options) {
 }
 /** Async counterpart of {@link withFileLockSync}. Always releases, including when `fn` throws/rejects. */
 export async function withFileLock(filePath, fn, options) {
-    await ensureLockDir(filePath);
+    await ensureLockDir(filePath, options?.lockfilePath);
     const release = await lockfile.lock(filePath, {
+        lockfilePath: options?.lockfilePath,
         realpath: options?.realpath ?? DEFAULT_REALPATH,
         retries: {
-            retries: options?.retries ?? DEFAULT_RETRIES,
-            minTimeout: RETRY_MIN_TIMEOUT_MS,
-            maxTimeout: RETRY_MAX_TIMEOUT_MS,
+            retries: retryCount(options ?? {}),
+            factor: options?.retryFactor ?? 2,
+            minTimeout: options?.minRetryDelayMs ?? RETRY_MIN_TIMEOUT_MS,
+            maxTimeout: options?.maxRetryDelayMs ?? RETRY_MAX_TIMEOUT_MS,
         },
         stale: options?.stale,
     });

package/dist/core/util/atomic-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-file.js","sourceRoot":"","sources":["../../../src/core/util/atomic-file.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared atomic-file helper: a single lock+tmp+rename implementation reused by every\n * on-disk store that does a read-modify-write against a JSON/text file. Modeled on the pattern\n * already proven in `memory/providers/file-store.ts` (proper-lockfile advisory lock + write-tmp-\n * then-rename); before this helper existed the pattern was copy-pasted per store, and most copies\n * were missing either the lock, the atomic write, or both.\n *\n * Two call shapes:\n *  - `withFileLock(Sync)` — hold an exclusive advisory lock across an arbitrary read-modify-write\n *    callback. The lock spans BOTH the read and the write, closing the classic RMW race where two\n *    writers each read the old content before either writes back.\n *  - `writeFileAtomic(Sync)` — write-tmp-then-rename. Used INSIDE a `withFileLock` callback (or\n *    standalone, for a pure overwrite that has no read step to race).\n *\n * Sync and async variants are both exported. Most existing stores expose a synchronous public API\n * called from hot, non-async paths (e.g. a per-token-stream perf sample), so the sync variant lets\n * them gain locking without forcing an async ripple through their callers; the async variant is for\n * call sites that are already async.\n */\n\nimport { randomUUID } from \"node:crypto\";\nimport { promises as fsPromises, mkdirSync, renameSync, unlinkSync, writeFileSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport lockfile from \"proper-lockfile\";\n\n/**\n * Bounded rename retry budget for the win32-only transient-rename handling below (see\n * {@link isTransientRenameErrorOnWin32}). Backoff doubles each attempt starting at\n * {@link RENAME_RETRY_MIN_TIMEOUT_MS} and capped at {@link RENAME_RETRY_MAX_TIMEOUT_MS}, mirroring\n * the doubling-backoff shape used for lock acquisition above. With {@link RENAME_RETRY_ATTEMPTS}\n * extra attempts (10, 20, 40, 80, ... capped at 200) the worst-case total wait is ~1.03s\n * (10+20+40+80+160+200+200+200+200 ~= 1110ms across 9 gaps), which comfortably covers the\n * millisecond-scale window Defender/the Windows Search indexer hold a freshly-written file open\n * without FILE_SHARE_DELETE before releasing it.\n */\nconst RENAME_RETRY_ATTEMPTS = 9;\nconst RENAME_RETRY_MIN_TIMEOUT_MS = 10;\nconst RENAME_RETRY_MAX_TIMEOUT_MS = 200;\n\n/**\n * On win32, antivirus (e.g. Windows Defender's real-time scanner) and the Windows Search indexer\n * routinely open a freshly-written file for a brief scan without `FILE_SHARE_DELETE`, which makes a\n * rename over/of that file fail transiently with EPERM/EACCES/EBUSY for a few milliseconds. This is\n * a well-documented platform semantic, not a bug in our write path — it's exactly why the\n * `graceful-fs` package ships its own win32 rename-retry wrapper. POSIX platforms never exhibit this\n * transient (a POSIX rename either succeeds or fails for a real, non-transient reason), so retry is\n * gated strictly to win32 to keep POSIX behavior byte-identical to a bare rename.\n */\nfunction isTransientRenameErrorOnWin32(err: unknown): boolean {\n\tif (process.platform !== \"win32\") return false;\n\tif (typeof err !== \"object\" || err === null) return false;\n\tconst code = (err as { code?: string }).code;\n\treturn code === \"EPERM\" || code === \"EACCES\" || code === \"EBUSY\";\n}\n\n/** Sync counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */\nfunction renameSyncWithRetry(tmpPath: string, filePath: string): void {\n\tfor (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {\n\t\ttry {\n\t\t\trenameSync(tmpPath, filePath);\n\t\t\treturn;\n\t\t} catch (err) {\n\t\t\tif (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS) throw err;\n\t\t\tconst backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);\n\t\t\tblockingSleepMs(backoffMs);\n\t\t}\n\t}\n}\n\n/** Async counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */\nasync function renameWithRetry(tmpPath: string, filePath: string): Promise<void> {\n\tfor (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {\n\t\ttry {\n\t\t\tawait fsPromises.rename(tmpPath, filePath);\n\t\t\treturn;\n\t\t} catch (err) {\n\t\t\tif (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS) throw err;\n\t\t\tconst backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);\n\t\t\tawait new Promise((resolve) => setTimeout(resolve, backoffMs));\n\t\t}\n\t}\n}\n\nexport interface AtomicFileLockOptions {\n\t/**\n\t * Bounded retry attempts while waiting for a lock already held elsewhere. Both variants use a\n\t * SHORT, capped backoff (see {@link RETRY_MIN_TIMEOUT_MS}/{@link RETRY_MAX_TIMEOUT_MS}) — these\n\t * stores' critical sections are sub-millisecond reads+writes of small JSON/text files, so\n\t * contention should clear in milliseconds, not the multi-second-to-31-second worst case\n\t * proper-lockfile's OWN default backoff produces for a bare numeric `retries` (its default\n\t * `minTimeout` is 1000ms with factor 2 — see node_modules/retry/lib/retry.js). Passing a bare\n\t * number straight through would turn brief contention into a multi-second stall on a hot path\n\t * (e.g. a per-token-stream perf sample), so both variants instead build an explicit short-backoff\n\t * `retry` options object.\n\t * - Async (`withFileLock`): forwarded as `{retries, minTimeout, maxTimeout}` to proper-lockfile.\n\t * - Sync (`withFileLockSync`): proper-lockfile's sync API REJECTS `retries > 0` outright (it\n\t *   requires the whole acquire flow to be synchronous — see proper-lockfile/lib/adapter.js\n\t *   `toSyncOptions`, which throws `ESYNC`). So the sync path implements its own bounded retry\n\t *   around single `lockfile.lockSync` attempts, blocking briefly between them (Atomics.wait) —\n\t *   callers are already fully synchronous fs code, so a short blocking wait on contention matches\n\t *   the existing execution model rather than introducing a new one.\n\t */\n\tretries?: number;\n\t/** Resolve symlinks before locking (proper-lockfile `realpath`); false matches file-store.ts. */\n\trealpath?: boolean;\n\t/** Lock staleness window in ms (proper-lockfile `stale`); omitted = proper-lockfile's own default. */\n\tstale?: number;\n}\n\nexport interface AtomicFileWriteOptions {\n\t/** POSIX permission bits applied to the temporary file and inherited by the renamed destination. */\n\tmode?: number;\n}\n\nconst DEFAULT_RETRIES = 10;\nconst DEFAULT_REALPATH = false;\n/**\n * Capped doubling backoff shared by both variants — see {@link AtomicFileLockOptions.retries}.\n * With the current defaults (10 retries, 25ms floor, 500ms cap) the total worst-case contention\n * budget is ~3.3s (25+50+100+200+400+500+500+500+500+500), comfortably over the >= 2s floor this\n * needs to survive a loaded CI runner (e.g. the Windows CI mkdir/rmdir lock-directory churn under\n * two-real-OS-thread contention).\n */\nconst RETRY_MIN_TIMEOUT_MS = 25;\nconst RETRY_MAX_TIMEOUT_MS = 500;\nfunction ensureLockDirSync(filePath: string): void {\n\tmkdirSync(dirname(filePath), { recursive: true });\n}\n\nasync function ensureLockDir(filePath: string): Promise<void> {\n\tawait fsPromises.mkdir(dirname(filePath), { recursive: true });\n}\n\nfunction isLockedError(err: unknown): boolean {\n\tif (typeof err !== \"object\" || err === null) return false;\n\tconst code = (err as { code?: string }).code;\n\tif (code === \"ELOCKED\") return true;\n\t// On win32, mkdir-ing the lock directory can transiently surface EPERM (rather than the\n\t// expected EEXIST) when a previous incarnation of that directory is concurrently being\n\t// rmdir'd by the racing releaser — the mkdir lands mid-teardown and the OS reports \"operation\n\t// not permitted\" instead of \"already exists\". This is contention, not a real permissions\n\t// failure, so treat it identically to ELOCKED: retry with the existing backoff rather than\n\t// letting it escape as fatal. POSIX platforms don't exhibit this transient and keep surfacing\n\t// real EPERM (e.g. an actually unwritable directory) as fatal.\n\tif (code === \"EPERM\" && process.platform === \"win32\") return true;\n\treturn false;\n}\n\n/** Block the calling thread for `ms` without spinning the CPU (Atomics.wait on a private buffer). */\nfunction blockingSleepMs(ms: number): void {\n\tAtomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);\n}\n\n/**\n * Acquire a proper-lockfile sync lock with bounded retry on `ELOCKED` (proper-lockfile's sync API\n * itself forbids `retries > 0`; see {@link AtomicFileLockOptions.retries}).\n *\n * Backoff doubles each attempt (mirroring the `retry` module's own `factor: 2` default that the\n * async path gets for free from proper-lockfile), starting at {@link RETRY_MIN_TIMEOUT_MS} and\n * capped at {@link RETRY_MAX_TIMEOUT_MS}.\n *\n * This is budget PARITY between two implementations of the same lock-acquisition contract, not\n * flake-masking: `options.retries` (a count of RETRIES, i.e. attempts after the first) means the\n * same thing on both paths, so both must make `retries + 1` total acquisition attempts with the\n * same per-gap backoff schedule. The async path gets `retries + 1` attempts for free from the\n * `retry` module (it retries `options.retries` times after its initial attempt); the sync path\n * used to loop exactly `attempts` times total (one fewer gap, and one fewer attempt than the\n * async path for the same `retries` value), which under-budgeted it relative to its async sibling\n * and surfaced as spurious ELOCKED failures under real contention (e.g. two OS threads hammering\n * the same file, or mkdir/rmdir lock-directory churn on a loaded Windows CI runner).\n */\nfunction lockSyncWithRetry(filePath: string, options: AtomicFileLockOptions): () => void {\n\tconst attempts = Math.max(1, options.retries ?? DEFAULT_RETRIES) + 1;\n\tconst lockOptions = { realpath: options.realpath ?? DEFAULT_REALPATH, stale: options.stale };\n\tfor (let attempt = 1; attempt <= attempts; attempt++) {\n\t\ttry {\n\t\t\treturn lockfile.lockSync(filePath, lockOptions);\n\t\t} catch (err) {\n\t\t\tif (!isLockedError(err) || attempt === attempts) throw err;\n\t\t\tconst backoffMs = Math.min(RETRY_MIN_TIMEOUT_MS * 2 ** (attempt - 1), RETRY_MAX_TIMEOUT_MS);\n\t\t\tblockingSleepMs(backoffMs);\n\t\t}\n\t}\n\t// Unreachable (the loop always returns or throws), but keeps the function's return type honest.\n\tthrow new Error(`Failed to acquire lock for ${filePath}`);\n}\n\n/**\n * Hold an exclusive advisory lock on `filePath` for the duration of `fn` (sync). Always releases,\n * including when `fn` throws.\n */\nexport function withFileLockSync<T>(filePath: string, fn: () => T, options?: AtomicFileLockOptions): T {\n\tensureLockDirSync(filePath);\n\tconst release = lockSyncWithRetry(filePath, options ?? {});\n\ttry {\n\t\treturn fn();\n\t} finally {\n\t\t// A lock-cleanup failure must never mask fn()'s result (or replace fn()'s own thrown error) —\n\t\t// by this point fn() has already durably committed or failed on its own terms.\n\t\ttry {\n\t\t\trelease();\n\t\t} catch {\n\t\t\t// best-effort cleanup; a stale lock self-expires via proper-lockfile's `stale` window\n\t\t}\n\t}\n}\n\n/** Async counterpart of {@link withFileLockSync}. Always releases, including when `fn` throws/rejects. */\nexport async function withFileLock<T>(\n\tfilePath: string,\n\tfn: () => Promise<T> | T,\n\toptions?: AtomicFileLockOptions,\n): Promise<T> {\n\tawait ensureLockDir(filePath);\n\tconst release = await lockfile.lock(filePath, {\n\t\trealpath: options?.realpath ?? DEFAULT_REALPATH,\n\t\tretries: {\n\t\t\tretries: options?.retries ?? DEFAULT_RETRIES,\n\t\t\tminTimeout: RETRY_MIN_TIMEOUT_MS,\n\t\t\tmaxTimeout: RETRY_MAX_TIMEOUT_MS,\n\t\t},\n\t\tstale: options?.stale,\n\t});\n\ttry {\n\t\treturn await fn();\n\t} finally {\n\t\t// See {@link withFileLockSync} — cleanup failures must not mask fn()'s outcome.\n\t\tawait release().catch(() => {});\n\t}\n}\n\n/**\n * Write `content` to `filePath` via write-tmp-then-rename (sync); the rename is atomic on the same\n * filesystem, so a concurrent reader never observes a partially-written file. Does NOT itself lock —\n * call from inside {@link withFileLockSync} when the write follows a read that must not race another\n * writer's read+write; call standalone for an unconditional overwrite with no read step.\n */\nfunction temporaryPath(filePath: string): string {\n\treturn `${filePath}.${process.pid}.${randomUUID()}.tmp`;\n}\n\n/** Remove one invocation's temporary path without masking the original write/rename failure. */\nfunction removeTemporaryPathSync(tmpPath: string): void {\n\ttry {\n\t\tunlinkSync(tmpPath);\n\t} catch {\n\t\t// The rename may have consumed the path, or another failure may have prevented its creation.\n\t}\n}\n\nasync function removeTemporaryPath(tmpPath: string): Promise<void> {\n\ttry {\n\t\tawait fsPromises.unlink(tmpPath);\n\t} catch {\n\t\t// The rename may have consumed the path, or another failure may have prevented its creation.\n\t}\n}\n\nexport function writeFileAtomicSync(filePath: string, content: string, options?: AtomicFileWriteOptions): void {\n\tmkdirSync(dirname(filePath), { recursive: true });\n\tconst tmpPath = temporaryPath(filePath);\n\tlet renamed = false;\n\ttry {\n\t\t// `wx` makes a nonce collision harmless: never truncate another writer's temporary file.\n\t\twriteFileSync(tmpPath, content, { encoding: \"utf-8\", flag: \"wx\", mode: options?.mode });\n\t\trenameSyncWithRetry(tmpPath, filePath);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) removeTemporaryPathSync(tmpPath);\n\t}\n}\n\n/** Async counterpart of {@link writeFileAtomicSync}. */\nexport async function writeFileAtomic(\n\tfilePath: string,\n\tcontent: string,\n\toptions?: AtomicFileWriteOptions,\n): Promise<void> {\n\tawait fsPromises.mkdir(dirname(filePath), { recursive: true });\n\tconst tmpPath = temporaryPath(filePath);\n\tlet renamed = false;\n\ttry {\n\t\t// `wx` makes a nonce collision harmless: never truncate another writer's temporary file.\n\t\tawait fsPromises.writeFile(tmpPath, content, { encoding: \"utf-8\", flag: \"wx\", mode: options?.mode });\n\t\tawait renameWithRetry(tmpPath, filePath);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) await removeTemporaryPath(tmpPath);\n\t}\n}\n"]}
+{"version":3,"file":"atomic-file.js","sourceRoot":"","sources":["../../../src/core/util/atomic-file.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared atomic-file helper: a single lock+tmp+rename implementation reused by every\n * on-disk store that does a read-modify-write against a JSON/text file. Modeled on the pattern\n * already proven in `memory/providers/file-store.ts` (proper-lockfile advisory lock + write-tmp-\n * then-rename); before this helper existed the pattern was copy-pasted per store, and most copies\n * were missing either the lock, the atomic write, or both.\n *\n * Two call shapes:\n *  - `withFileLock(Sync)` — hold an exclusive advisory lock across an arbitrary read-modify-write\n *    callback. The lock spans BOTH the read and the write, closing the classic RMW race where two\n *    writers each read the old content before either writes back.\n *  - `writeFileAtomic(Sync)` — write-tmp-then-rename. Used INSIDE a `withFileLock` callback (or\n *    standalone, for a pure overwrite that has no read step to race).\n *\n * Sync and async variants are both exported. Most existing stores expose a synchronous public API\n * called from hot, non-async paths (e.g. a per-token-stream perf sample), so the sync variant lets\n * them gain locking without forcing an async ripple through their callers; the async variant is for\n * call sites that are already async.\n */\n\nimport { randomUUID } from \"node:crypto\";\nimport { promises as fsPromises, mkdirSync, renameSync, unlinkSync, writeFileSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport lockfile from \"proper-lockfile\";\n\n/**\n * Bounded rename retry budget for the win32-only transient-rename handling below (see\n * {@link isTransientRenameErrorOnWin32}). Backoff doubles each attempt starting at\n * {@link RENAME_RETRY_MIN_TIMEOUT_MS} and capped at {@link RENAME_RETRY_MAX_TIMEOUT_MS}, mirroring\n * the doubling-backoff shape used for lock acquisition above. With {@link RENAME_RETRY_ATTEMPTS}\n * extra attempts (10, 20, 40, 80, ... capped at 200) the worst-case total wait is ~1.03s\n * (10+20+40+80+160+200+200+200+200 ~= 1110ms across 9 gaps), which comfortably covers the\n * millisecond-scale window Defender/the Windows Search indexer hold a freshly-written file open\n * without FILE_SHARE_DELETE before releasing it.\n */\nconst RENAME_RETRY_ATTEMPTS = 9;\nconst RENAME_RETRY_MIN_TIMEOUT_MS = 10;\nconst RENAME_RETRY_MAX_TIMEOUT_MS = 200;\n\n/**\n * On win32, antivirus (e.g. Windows Defender's real-time scanner) and the Windows Search indexer\n * routinely open a freshly-written file for a brief scan without `FILE_SHARE_DELETE`, which makes a\n * rename over/of that file fail transiently with EPERM/EACCES/EBUSY for a few milliseconds. This is\n * a well-documented platform semantic, not a bug in our write path — it's exactly why the\n * `graceful-fs` package ships its own win32 rename-retry wrapper. POSIX platforms never exhibit this\n * transient (a POSIX rename either succeeds or fails for a real, non-transient reason), so retry is\n * gated strictly to win32 to keep POSIX behavior byte-identical to a bare rename.\n */\nfunction isTransientRenameErrorOnWin32(err: unknown): boolean {\n\tif (process.platform !== \"win32\") return false;\n\tif (typeof err !== \"object\" || err === null) return false;\n\tconst code = (err as { code?: string }).code;\n\treturn code === \"EPERM\" || code === \"EACCES\" || code === \"EBUSY\";\n}\n\n/** Sync counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */\nfunction renameSyncWithRetry(tmpPath: string, filePath: string): void {\n\tfor (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {\n\t\ttry {\n\t\t\trenameSync(tmpPath, filePath);\n\t\t\treturn;\n\t\t} catch (err) {\n\t\t\tif (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS) throw err;\n\t\t\tconst backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);\n\t\t\tblockingSleepMs(backoffMs);\n\t\t}\n\t}\n}\n\n/** Async counterpart of the rename-retry policy; see {@link isTransientRenameErrorOnWin32}. */\nasync function renameWithRetry(tmpPath: string, filePath: string): Promise<void> {\n\tfor (let attempt = 0; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) {\n\t\ttry {\n\t\t\tawait fsPromises.rename(tmpPath, filePath);\n\t\t\treturn;\n\t\t} catch (err) {\n\t\t\tif (!isTransientRenameErrorOnWin32(err) || attempt === RENAME_RETRY_ATTEMPTS) throw err;\n\t\t\tconst backoffMs = Math.min(RENAME_RETRY_MIN_TIMEOUT_MS * 2 ** attempt, RENAME_RETRY_MAX_TIMEOUT_MS);\n\t\t\tawait new Promise((resolve) => setTimeout(resolve, backoffMs));\n\t\t}\n\t}\n}\n\nexport interface AtomicFileLockOptions {\n\t/**\n\t * Bounded retry attempts while waiting for a lock already held elsewhere. Both variants use a\n\t * SHORT, capped backoff (see {@link RETRY_MIN_TIMEOUT_MS}/{@link RETRY_MAX_TIMEOUT_MS}) — these\n\t * stores' critical sections are sub-millisecond reads+writes of small JSON/text files, so\n\t * contention should clear in milliseconds, not the multi-second-to-31-second worst case\n\t * proper-lockfile's OWN default backoff produces for a bare numeric `retries` (its default\n\t * `minTimeout` is 1000ms with factor 2 — see node_modules/retry/lib/retry.js). Passing a bare\n\t * number straight through would turn brief contention into a multi-second stall on a hot path\n\t * (e.g. a per-token-stream perf sample), so both variants instead build an explicit short-backoff\n\t * `retry` options object.\n\t * - Async (`withFileLock`): forwarded as `{retries, minTimeout, maxTimeout}` to proper-lockfile.\n\t * - Sync (`withFileLockSync`): proper-lockfile's sync API REJECTS `retries > 0` outright (it\n\t *   requires the whole acquire flow to be synchronous — see proper-lockfile/lib/adapter.js\n\t *   `toSyncOptions`, which throws `ESYNC`). So the sync path implements its own bounded retry\n\t *   around single `lockfile.lockSync` attempts, blocking briefly between them (Atomics.wait) —\n\t *   callers are already fully synchronous fs code, so a short blocking wait on contention matches\n\t *   the existing execution model rather than introducing a new one.\n\t */\n\tretries?: number;\n\t/** Initial delay between sync/async acquisition attempts; defaults to 25ms. */\n\tminRetryDelayMs?: number;\n\t/** Maximum delay between sync/async acquisition attempts; defaults to 500ms. */\n\tmaxRetryDelayMs?: number;\n\t/** Retry-delay multiplier; defaults to 2. Set max=min for a fixed delay. */\n\tretryFactor?: number;\n\t/** Resolve symlinks before locking (proper-lockfile `realpath`); false matches file-store.ts. */\n\trealpath?: boolean;\n\t/** Lock staleness window in ms (proper-lockfile `stale`); omitted = proper-lockfile's own default. */\n\tstale?: number;\n\t/** Explicit proper-lockfile directory path; defaults to `${filePath}.lock`. */\n\tlockfilePath?: string;\n}\n\nexport interface AtomicFileWriteOptions {\n\t/** POSIX permission bits applied to the temporary file and inherited by the renamed destination. */\n\tmode?: number;\n}\n\nconst DEFAULT_RETRIES = 10;\nconst DEFAULT_REALPATH = false;\n/**\n * Capped doubling backoff shared by both variants — see {@link AtomicFileLockOptions.retries}.\n * With the current defaults (10 retries, 25ms floor, 500ms cap) the total worst-case contention\n * budget is ~3.3s (25+50+100+200+400+500+500+500+500+500), comfortably over the >= 2s floor this\n * needs to survive a loaded CI runner (e.g. the Windows CI mkdir/rmdir lock-directory churn under\n * two-real-OS-thread contention).\n */\nconst RETRY_MIN_TIMEOUT_MS = 25;\nconst RETRY_MAX_TIMEOUT_MS = 500;\n\n/**\n * Existing auth/settings/trust paths historically used 10 total attempts separated by 20ms. Keep\n * that low-latency user-facing policy explicit while routing the mechanism through this module.\n */\nexport const LOW_LATENCY_FILE_LOCK_OPTIONS: Readonly<AtomicFileLockOptions> = Object.freeze({\n\tretries: 9,\n\tminRetryDelayMs: 20,\n\tmaxRetryDelayMs: 20,\n});\n\nfunction lockDirectory(filePath: string, lockfilePath?: string): string {\n\treturn dirname(lockfilePath ?? filePath);\n}\n\nfunction ensureLockDirSync(filePath: string, lockfilePath?: string): void {\n\tmkdirSync(lockDirectory(filePath, lockfilePath), { recursive: true });\n}\n\nasync function ensureLockDir(filePath: string, lockfilePath?: string): Promise<void> {\n\tawait fsPromises.mkdir(lockDirectory(filePath, lockfilePath), { recursive: true });\n}\n\nfunction isLockedError(err: unknown): boolean {\n\tif (typeof err !== \"object\" || err === null) return false;\n\tconst code = (err as { code?: string }).code;\n\tif (code === \"ELOCKED\") return true;\n\t// On win32, mkdir-ing the lock directory can transiently surface EPERM (rather than the\n\t// expected EEXIST) when a previous incarnation of that directory is concurrently being\n\t// rmdir'd by the racing releaser — the mkdir lands mid-teardown and the OS reports \"operation\n\t// not permitted\" instead of \"already exists\". This is contention, not a real permissions\n\t// failure, so treat it identically to ELOCKED: retry with the existing backoff rather than\n\t// letting it escape as fatal. POSIX platforms don't exhibit this transient and keep surfacing\n\t// real EPERM (e.g. an actually unwritable directory) as fatal.\n\tif (code === \"EPERM\" && process.platform === \"win32\") return true;\n\treturn false;\n}\n\n/** Block the calling thread for `ms` without spinning the CPU (Atomics.wait on a private buffer). */\nfunction blockingSleepMs(ms: number): void {\n\tAtomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);\n}\n\n/**\n * Acquire a proper-lockfile sync lock with bounded retry on `ELOCKED` (proper-lockfile's sync API\n * itself forbids `retries > 0`; see {@link AtomicFileLockOptions.retries}).\n *\n * Backoff doubles each attempt (mirroring the `retry` module's own `factor: 2` default that the\n * async path gets for free from proper-lockfile), starting at {@link RETRY_MIN_TIMEOUT_MS} and\n * capped at {@link RETRY_MAX_TIMEOUT_MS}.\n *\n * This is budget PARITY between two implementations of the same lock-acquisition contract, not\n * flake-masking: `options.retries` (a count of RETRIES, i.e. attempts after the first) means the\n * same thing on both paths, so both must make `retries + 1` total acquisition attempts with the\n * same per-gap backoff schedule. The async path gets `retries + 1` attempts for free from the\n * `retry` module (it retries `options.retries` times after its initial attempt); the sync path\n * used to loop exactly `attempts` times total (one fewer gap, and one fewer attempt than the\n * async path for the same `retries` value), which under-budgeted it relative to its async sibling\n * and surfaced as spurious ELOCKED failures under real contention (e.g. two OS threads hammering\n * the same file, or mkdir/rmdir lock-directory churn on a loaded Windows CI runner).\n */\nfunction retryCount(options: AtomicFileLockOptions): number {\n\tconst configured = options.retries ?? DEFAULT_RETRIES;\n\treturn Number.isFinite(configured) ? Math.max(0, Math.floor(configured)) : DEFAULT_RETRIES;\n}\n\nfunction retryDelayMs(options: AtomicFileLockOptions, attempt: number): number {\n\tconst configuredMin = options.minRetryDelayMs ?? RETRY_MIN_TIMEOUT_MS;\n\tconst minDelay = Number.isFinite(configuredMin) ? Math.max(0, configuredMin) : RETRY_MIN_TIMEOUT_MS;\n\tconst configuredMax = options.maxRetryDelayMs ?? RETRY_MAX_TIMEOUT_MS;\n\tconst maxDelay = Number.isFinite(configuredMax) ? Math.max(minDelay, configuredMax) : RETRY_MAX_TIMEOUT_MS;\n\tconst configuredFactor = options.retryFactor ?? 2;\n\tconst factor = Number.isFinite(configuredFactor) ? Math.max(1, configuredFactor) : 2;\n\treturn Math.min(minDelay * factor ** (attempt - 1), maxDelay);\n}\n\n/**\n * Acquire a synchronous advisory file lock and return its release function. This is the shared\n * mechanism for coordinators that must hold several locks in a deterministic order before entering\n * one critical section; callers retain ownership of release ordering and release-error semantics.\n */\nexport function acquireFileLockSync(filePath: string, options: AtomicFileLockOptions = {}): () => void {\n\tensureLockDirSync(filePath, options.lockfilePath);\n\tconst attempts = retryCount(options) + 1;\n\tconst lockOptions = {\n\t\tlockfilePath: options.lockfilePath,\n\t\trealpath: options.realpath ?? DEFAULT_REALPATH,\n\t\tstale: options.stale,\n\t};\n\tfor (let attempt = 1; attempt <= attempts; attempt++) {\n\t\ttry {\n\t\t\treturn lockfile.lockSync(filePath, lockOptions);\n\t\t} catch (err) {\n\t\t\tif (!isLockedError(err) || attempt === attempts) throw err;\n\t\t\tblockingSleepMs(retryDelayMs(options, attempt));\n\t\t}\n\t}\n\t// Unreachable (the loop always returns or throws), but keeps the function's return type honest.\n\tthrow new Error(`Failed to acquire lock for ${filePath}`);\n}\n\n/**\n * Hold an exclusive advisory lock on `filePath` for the duration of `fn` (sync). Always releases,\n * including when `fn` throws.\n */\nexport function withFileLockSync<T>(filePath: string, fn: () => T, options?: AtomicFileLockOptions): T {\n\tconst release = acquireFileLockSync(filePath, options);\n\ttry {\n\t\treturn fn();\n\t} finally {\n\t\t// A lock-cleanup failure must never mask fn()'s result (or replace fn()'s own thrown error) —\n\t\t// by this point fn() has already durably committed or failed on its own terms.\n\t\ttry {\n\t\t\trelease();\n\t\t} catch {\n\t\t\t// best-effort cleanup; a stale lock self-expires via proper-lockfile's `stale` window\n\t\t}\n\t}\n}\n\n/** Async counterpart of {@link withFileLockSync}. Always releases, including when `fn` throws/rejects. */\nexport async function withFileLock<T>(\n\tfilePath: string,\n\tfn: () => Promise<T> | T,\n\toptions?: AtomicFileLockOptions,\n): Promise<T> {\n\tawait ensureLockDir(filePath, options?.lockfilePath);\n\tconst release = await lockfile.lock(filePath, {\n\t\tlockfilePath: options?.lockfilePath,\n\t\trealpath: options?.realpath ?? DEFAULT_REALPATH,\n\t\tretries: {\n\t\t\tretries: retryCount(options ?? {}),\n\t\t\tfactor: options?.retryFactor ?? 2,\n\t\t\tminTimeout: options?.minRetryDelayMs ?? RETRY_MIN_TIMEOUT_MS,\n\t\t\tmaxTimeout: options?.maxRetryDelayMs ?? RETRY_MAX_TIMEOUT_MS,\n\t\t},\n\t\tstale: options?.stale,\n\t});\n\ttry {\n\t\treturn await fn();\n\t} finally {\n\t\t// See {@link withFileLockSync} — cleanup failures must not mask fn()'s outcome.\n\t\tawait release().catch(() => {});\n\t}\n}\n\n/**\n * Write `content` to `filePath` via write-tmp-then-rename (sync); the rename is atomic on the same\n * filesystem, so a concurrent reader never observes a partially-written file. Does NOT itself lock —\n * call from inside {@link withFileLockSync} when the write follows a read that must not race another\n * writer's read+write; call standalone for an unconditional overwrite with no read step.\n */\nfunction temporaryPath(filePath: string): string {\n\treturn `${filePath}.${process.pid}.${randomUUID()}.tmp`;\n}\n\n/** Remove one invocation's temporary path without masking the original write/rename failure. */\nfunction removeTemporaryPathSync(tmpPath: string): void {\n\ttry {\n\t\tunlinkSync(tmpPath);\n\t} catch {\n\t\t// The rename may have consumed the path, or another failure may have prevented its creation.\n\t}\n}\n\nasync function removeTemporaryPath(tmpPath: string): Promise<void> {\n\ttry {\n\t\tawait fsPromises.unlink(tmpPath);\n\t} catch {\n\t\t// The rename may have consumed the path, or another failure may have prevented its creation.\n\t}\n}\n\nexport function writeFileAtomicSync(filePath: string, content: string, options?: AtomicFileWriteOptions): void {\n\tmkdirSync(dirname(filePath), { recursive: true });\n\tconst tmpPath = temporaryPath(filePath);\n\tlet renamed = false;\n\ttry {\n\t\t// `wx` makes a nonce collision harmless: never truncate another writer's temporary file.\n\t\twriteFileSync(tmpPath, content, { encoding: \"utf-8\", flag: \"wx\", mode: options?.mode });\n\t\trenameSyncWithRetry(tmpPath, filePath);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) removeTemporaryPathSync(tmpPath);\n\t}\n}\n\n/** Async counterpart of {@link writeFileAtomicSync}. */\nexport async function writeFileAtomic(\n\tfilePath: string,\n\tcontent: string,\n\toptions?: AtomicFileWriteOptions,\n): Promise<void> {\n\tawait fsPromises.mkdir(dirname(filePath), { recursive: true });\n\tconst tmpPath = temporaryPath(filePath);\n\tlet renamed = false;\n\ttry {\n\t\t// `wx` makes a nonce collision harmless: never truncate another writer's temporary file.\n\t\tawait fsPromises.writeFile(tmpPath, content, { encoding: \"utf-8\", flag: \"wx\", mode: options?.mode });\n\t\tawait renameWithRetry(tmpPath, filePath);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) await removeTemporaryPath(tmpPath);\n\t}\n}\n"]}

package/dist/core/util/bounded-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bounded-file.d.ts","sourceRoot":"","sources":["../../../src/core/util/bounded-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyD,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAW5F,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAQlE;AAkBD,8FAA8F;AAC9F,wBAAgB,6BAA6B,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAc1G;AAED,uEAAuE;AACvE,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBjG;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAehH;AAED,4DAA4D;AAC5D,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB5G","sourcesContent":["import { closeSync, fstatSync, opendirSync, openSync, readSync, type Stats } from \"node:fs\";\nimport { type FileHandle, open as openAsync } from \"node:fs/promises\";\n\nconst READ_CHUNK_BYTES = 64 * 1024;\n\nfunction validateByteLimit(maxBytes: number): void {\n\tif (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {\n\t\tthrow new TypeError(\"Bounded file reads require a non-negative safe-integer byte limit.\");\n\t}\n}\n\n/** Compare the filesystem identity and mutation-sensitive metadata captured around a bounded read. */\nexport function sameFileVersion(left: Stats, right: Stats): boolean {\n\treturn (\n\t\tleft.dev === right.dev &&\n\t\tleft.ino === right.ino &&\n\t\tleft.size === right.size &&\n\t\tleft.mtimeMs === right.mtimeMs &&\n\t\tleft.ctimeMs === right.ctimeMs\n\t);\n}\n\nasync function readFileHandleBounded(fileHandle: FileHandle, maxBytes: number): Promise<Buffer | undefined> {\n\tvalidateByteLimit(maxBytes);\n\tconst chunks: Buffer[] = [];\n\tlet totalBytes = 0;\n\twhile (totalBytes < maxBytes) {\n\t\tconst chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes - totalBytes));\n\t\tconst { bytesRead } = await fileHandle.read(chunk, 0, chunk.length, totalBytes);\n\t\tif (bytesRead === 0) return Buffer.concat(chunks, totalBytes);\n\t\tchunks.push(chunk.subarray(0, bytesRead));\n\t\ttotalBytes += bytesRead;\n\t}\n\tconst overflowProbe = Buffer.allocUnsafe(1);\n\tif ((await fileHandle.read(overflowProbe, 0, 1, totalBytes)).bytesRead > 0) return undefined;\n\treturn Buffer.concat(chunks, totalBytes);\n}\n\n/** Read at most `maxBytes`, then probe one byte so a growing file cannot escape the bound. */\nexport function readFileDescriptorBoundedSync(fileDescriptor: number, maxBytes: number): Buffer | undefined {\n\tvalidateByteLimit(maxBytes);\n\tconst chunks: Buffer[] = [];\n\tlet totalBytes = 0;\n\twhile (totalBytes < maxBytes) {\n\t\tconst chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes - totalBytes));\n\t\tconst bytesRead = readSync(fileDescriptor, chunk, 0, chunk.length, null);\n\t\tif (bytesRead === 0) return Buffer.concat(chunks, totalBytes);\n\t\tchunks.push(chunk.subarray(0, bytesRead));\n\t\ttotalBytes += bytesRead;\n\t}\n\tconst overflowProbe = Buffer.allocUnsafe(1);\n\tif (readSync(fileDescriptor, overflowProbe, 0, 1, null) > 0) return undefined;\n\treturn Buffer.concat(chunks, totalBytes);\n}\n\n/** Bounded, version-stable text read for small durable state files. */\nexport function readBoundedTextFileSync(filePath: string, maxBytes: number, label: string): string {\n\tvalidateByteLimit(maxBytes);\n\tconst fileDescriptor = openSync(filePath, \"r\");\n\ttry {\n\t\tconst before = fstatSync(fileDescriptor);\n\t\tif (!before.isFile()) throw new Error(`${label} is not a regular file.`);\n\t\tif (before.size > maxBytes) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst content = readFileDescriptorBoundedSync(fileDescriptor, maxBytes);\n\t\tif (!content) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst after = fstatSync(fileDescriptor);\n\t\tif (!sameFileVersion(before, after) || content.byteLength !== before.size) {\n\t\t\tthrow new Error(`${label} changed while it was being read.`);\n\t\t}\n\t\treturn content.toString(\"utf-8\");\n\t} finally {\n\t\tcloseSync(fileDescriptor);\n\t}\n}\n\n/**\n * Enumerate a managed directory incrementally. Unlike `readdirSync`, this never allocates an\n * unbounded entry array before the caller can reject a corrupt or hostile directory.\n */\nexport function readBoundedDirectoryNamesSync(directoryPath: string, maxEntries: number, label: string): string[] {\n\tif (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {\n\t\tthrow new TypeError(\"Bounded directory reads require a positive safe-integer entry limit.\");\n\t}\n\tconst directory = opendirSync(directoryPath);\n\ttry {\n\t\tconst names: string[] = [];\n\t\tfor (let entry = directory.readSync(); entry; entry = directory.readSync()) {\n\t\t\tif (names.length === maxEntries) throw new Error(`${label} exceeds its entry limit.`);\n\t\t\tnames.push(entry.name);\n\t\t}\n\t\treturn names;\n\t} finally {\n\t\tdirectory.closeSync();\n\t}\n}\n\n/** Async counterpart of {@link readBoundedTextFileSync}. */\nexport async function readBoundedTextFile(filePath: string, maxBytes: number, label: string): Promise<string> {\n\tvalidateByteLimit(maxBytes);\n\tconst fileHandle = await openAsync(filePath, \"r\");\n\ttry {\n\t\tconst before = await fileHandle.stat();\n\t\tif (!before.isFile()) throw new Error(`${label} is not a regular file.`);\n\t\tif (before.size > maxBytes) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst content = await readFileHandleBounded(fileHandle, maxBytes);\n\t\tif (!content) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst after = await fileHandle.stat();\n\t\tif (!sameFileVersion(before, after) || content.byteLength !== before.size) {\n\t\t\tthrow new Error(`${label} changed while it was being read.`);\n\t\t}\n\t\treturn content.toString(\"utf-8\");\n\t} finally {\n\t\tawait fileHandle.close();\n\t}\n}\n"]}
+{"version":3,"file":"bounded-file.d.ts","sourceRoot":"","sources":["../../../src/core/util/bounded-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyD,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAW5F,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAQlE;AAkBD,8FAA8F;AAC9F,wBAAgB,6BAA6B,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAc1G;AAED,uEAAuE;AACvE,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBjG;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAehH;AAED,4DAA4D;AAC5D,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB5G"}

package/dist/core/util/bounded-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"bounded-file.js","sourceRoot":"","sources":["../../../src/core/util/bounded-file.ts"],"names":[],"mappings":"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","sourcesContent":["import { closeSync, fstatSync, opendirSync, openSync, readSync, type Stats } from \"node:fs\";\nimport { type FileHandle, open as openAsync } from \"node:fs/promises\";\n\nconst READ_CHUNK_BYTES = 64 * 1024;\n\nfunction validateByteLimit(maxBytes: number): void {\n\tif (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {\n\t\tthrow new TypeError(\"Bounded file reads require a non-negative safe-integer byte limit.\");\n\t}\n}\n\n/** Compare the filesystem identity and mutation-sensitive metadata captured around a bounded read. */\nexport function sameFileVersion(left: Stats, right: Stats): boolean {\n\treturn (\n\t\tleft.dev === right.dev &&\n\t\tleft.ino === right.ino &&\n\t\tleft.size === right.size &&\n\t\tleft.mtimeMs === right.mtimeMs &&\n\t\tleft.ctimeMs === right.ctimeMs\n\t);\n}\n\nasync function readFileHandleBounded(fileHandle: FileHandle, maxBytes: number): Promise<Buffer | undefined> {\n\tvalidateByteLimit(maxBytes);\n\tconst chunks: Buffer[] = [];\n\tlet totalBytes = 0;\n\twhile (totalBytes < maxBytes) {\n\t\tconst chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes - totalBytes));\n\t\tconst { bytesRead } = await fileHandle.read(chunk, 0, chunk.length, totalBytes);\n\t\tif (bytesRead === 0) return Buffer.concat(chunks, totalBytes);\n\t\tchunks.push(chunk.subarray(0, bytesRead));\n\t\ttotalBytes += bytesRead;\n\t}\n\tconst overflowProbe = Buffer.allocUnsafe(1);\n\tif ((await fileHandle.read(overflowProbe, 0, 1, totalBytes)).bytesRead > 0) return undefined;\n\treturn Buffer.concat(chunks, totalBytes);\n}\n\n/** Read at most `maxBytes`, then probe one byte so a growing file cannot escape the bound. */\nexport function readFileDescriptorBoundedSync(fileDescriptor: number, maxBytes: number): Buffer | undefined {\n\tvalidateByteLimit(maxBytes);\n\tconst chunks: Buffer[] = [];\n\tlet totalBytes = 0;\n\twhile (totalBytes < maxBytes) {\n\t\tconst chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes - totalBytes));\n\t\tconst bytesRead = readSync(fileDescriptor, chunk, 0, chunk.length, null);\n\t\tif (bytesRead === 0) return Buffer.concat(chunks, totalBytes);\n\t\tchunks.push(chunk.subarray(0, bytesRead));\n\t\ttotalBytes += bytesRead;\n\t}\n\tconst overflowProbe = Buffer.allocUnsafe(1);\n\tif (readSync(fileDescriptor, overflowProbe, 0, 1, null) > 0) return undefined;\n\treturn Buffer.concat(chunks, totalBytes);\n}\n\n/** Bounded, version-stable text read for small durable state files. */\nexport function readBoundedTextFileSync(filePath: string, maxBytes: number, label: string): string {\n\tvalidateByteLimit(maxBytes);\n\tconst fileDescriptor = openSync(filePath, \"r\");\n\ttry {\n\t\tconst before = fstatSync(fileDescriptor);\n\t\tif (!before.isFile()) throw new Error(`${label} is not a regular file.`);\n\t\tif (before.size > maxBytes) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst content = readFileDescriptorBoundedSync(fileDescriptor, maxBytes);\n\t\tif (!content) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst after = fstatSync(fileDescriptor);\n\t\tif (!sameFileVersion(before, after) || content.byteLength !== before.size) {\n\t\t\tthrow new Error(`${label} changed while it was being read.`);\n\t\t}\n\t\treturn content.toString(\"utf-8\");\n\t} finally {\n\t\tcloseSync(fileDescriptor);\n\t}\n}\n\n/**\n * Enumerate a managed directory incrementally. Unlike `readdirSync`, this never allocates an\n * unbounded entry array before the caller can reject a corrupt or hostile directory.\n */\nexport function readBoundedDirectoryNamesSync(directoryPath: string, maxEntries: number, label: string): string[] {\n\tif (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {\n\t\tthrow new TypeError(\"Bounded directory reads require a positive safe-integer entry limit.\");\n\t}\n\tconst directory = opendirSync(directoryPath);\n\ttry {\n\t\tconst names: string[] = [];\n\t\tfor (let entry = directory.readSync(); entry; entry = directory.readSync()) {\n\t\t\tif (names.length === maxEntries) throw new Error(`${label} exceeds its entry limit.`);\n\t\t\tnames.push(entry.name);\n\t\t}\n\t\treturn names;\n\t} finally {\n\t\tdirectory.closeSync();\n\t}\n}\n\n/** Async counterpart of {@link readBoundedTextFileSync}. */\nexport async function readBoundedTextFile(filePath: string, maxBytes: number, label: string): Promise<string> {\n\tvalidateByteLimit(maxBytes);\n\tconst fileHandle = await openAsync(filePath, \"r\");\n\ttry {\n\t\tconst before = await fileHandle.stat();\n\t\tif (!before.isFile()) throw new Error(`${label} is not a regular file.`);\n\t\tif (before.size > maxBytes) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst content = await readFileHandleBounded(fileHandle, maxBytes);\n\t\tif (!content) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst after = await fileHandle.stat();\n\t\tif (!sameFileVersion(before, after) || content.byteLength !== before.size) {\n\t\t\tthrow new Error(`${label} changed while it was being read.`);\n\t\t}\n\t\treturn content.toString(\"utf-8\");\n\t} finally {\n\t\tawait fileHandle.close();\n\t}\n}\n"]}
+{"version":3,"file":"bounded-file.js","sourceRoot":"","sources":["../../../src/core/util/bounded-file.ts"],"names":[],"mappings":"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","sourcesContent":["import { closeSync, fstatSync, opendirSync, openSync, readSync, type Stats } from \"node:fs\";\nimport { type FileHandle, open as openAsync } from \"node:fs/promises\";\n\nconst READ_CHUNK_BYTES = 64 * 1024;\n\nfunction validateByteLimit(maxBytes: number): void {\n\tif (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {\n\t\tthrow new TypeError(\"Bounded file reads require a non-negative safe-integer byte limit.\");\n\t}\n}\n\n/** Compare the filesystem identity and mutation-sensitive metadata captured around a bounded read. */\nexport function sameFileVersion(left: Stats, right: Stats): boolean {\n\treturn (\n\t\tleft.dev === right.dev &&\n\t\tleft.ino === right.ino &&\n\t\tleft.size === right.size &&\n\t\tleft.mtimeMs === right.mtimeMs &&\n\t\tleft.ctimeMs === right.ctimeMs\n\t);\n}\n\nasync function readFileHandleBounded(fileHandle: FileHandle, maxBytes: number): Promise<Buffer | undefined> {\n\tvalidateByteLimit(maxBytes);\n\tconst chunks: Buffer[] = [];\n\tlet totalBytes = 0;\n\twhile (totalBytes < maxBytes) {\n\t\tconst chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes - totalBytes));\n\t\tconst { bytesRead } = await fileHandle.read(chunk, 0, chunk.length, totalBytes);\n\t\tif (bytesRead === 0) return Buffer.concat(chunks, totalBytes);\n\t\tchunks.push(chunk.subarray(0, bytesRead));\n\t\ttotalBytes += bytesRead;\n\t}\n\tconst overflowProbe = Buffer.allocUnsafe(1);\n\tif ((await fileHandle.read(overflowProbe, 0, 1, totalBytes)).bytesRead > 0) return undefined;\n\treturn Buffer.concat(chunks, totalBytes);\n}\n\n/** Read at most `maxBytes`, then probe one byte so a growing file cannot escape the bound. */\nexport function readFileDescriptorBoundedSync(fileDescriptor: number, maxBytes: number): Buffer | undefined {\n\tvalidateByteLimit(maxBytes);\n\tconst chunks: Buffer[] = [];\n\tlet totalBytes = 0;\n\twhile (totalBytes < maxBytes) {\n\t\tconst chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes - totalBytes));\n\t\tconst bytesRead = readSync(fileDescriptor, chunk, 0, chunk.length, null);\n\t\tif (bytesRead === 0) return Buffer.concat(chunks, totalBytes);\n\t\tchunks.push(chunk.subarray(0, bytesRead));\n\t\ttotalBytes += bytesRead;\n\t}\n\tconst overflowProbe = Buffer.allocUnsafe(1);\n\tif (readSync(fileDescriptor, overflowProbe, 0, 1, null) > 0) return undefined;\n\treturn Buffer.concat(chunks, totalBytes);\n}\n\n/** Bounded, version-stable text read for small durable state files. */\nexport function readBoundedTextFileSync(filePath: string, maxBytes: number, label: string): string {\n\tvalidateByteLimit(maxBytes);\n\tconst fileDescriptor = openSync(filePath, \"r\");\n\ttry {\n\t\tconst before = fstatSync(fileDescriptor);\n\t\tif (!before.isFile()) throw new Error(`${label} is not a regular file.`);\n\t\tif (before.size > maxBytes) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst content = readFileDescriptorBoundedSync(fileDescriptor, maxBytes);\n\t\tif (!content) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst after = fstatSync(fileDescriptor);\n\t\tif (!sameFileVersion(before, after) || content.byteLength !== before.size) {\n\t\t\tthrow new Error(`${label} changed while it was being read.`);\n\t\t}\n\t\treturn content.toString(\"utf-8\");\n\t} finally {\n\t\tcloseSync(fileDescriptor);\n\t}\n}\n\n/**\n * Enumerate a managed directory incrementally. Unlike `readdirSync`, this never allocates an\n * unbounded entry array before the caller can reject a corrupt or hostile directory.\n */\nexport function readBoundedDirectoryNamesSync(directoryPath: string, maxEntries: number, label: string): string[] {\n\tif (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {\n\t\tthrow new TypeError(\"Bounded directory reads require a positive safe-integer entry limit.\");\n\t}\n\tconst directory = opendirSync(directoryPath);\n\ttry {\n\t\tconst names: string[] = [];\n\t\tfor (let entry = directory.readSync(); entry; entry = directory.readSync()) {\n\t\t\tif (names.length === maxEntries) throw new Error(`${label} exceeds its entry limit.`);\n\t\t\tnames.push(entry.name);\n\t\t}\n\t\treturn names;\n\t} finally {\n\t\tdirectory.closeSync();\n\t}\n}\n\n/** Async counterpart of {@link readBoundedTextFileSync}. */\nexport async function readBoundedTextFile(filePath: string, maxBytes: number, label: string): Promise<string> {\n\tvalidateByteLimit(maxBytes);\n\tconst fileHandle = await openAsync(filePath, \"r\");\n\ttry {\n\t\tconst before = await fileHandle.stat();\n\t\tif (!before.isFile()) throw new Error(`${label} is not a regular file.`);\n\t\tif (before.size > maxBytes) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst content = await readFileHandleBounded(fileHandle, maxBytes);\n\t\tif (!content) throw new Error(`${label} exceeds its byte limit.`);\n\t\tconst after = await fileHandle.stat();\n\t\tif (!sameFileVersion(before, after) || content.byteLength !== before.size) {\n\t\t\tthrow new Error(`${label} changed while it was being read.`);\n\t\t}\n\t\treturn content.toString(\"utf-8\");\n\t} finally {\n\t\tawait fileHandle.close();\n\t}\n}\n"]}

package/dist/core/util/bounded-jsonl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bounded-jsonl.d.ts","sourceRoot":"","sources":["../../../src/core/util/bounded-jsonl.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACnB;AA6GD,+FAA+F;AAC/F,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAgC5G;AAED,8DAA8D;AAC9D,wBAAsB,qBAAqB,CAC1C,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC,CA2Cf","sourcesContent":["import { appendFileSync, promises as fsPromises, type Stats, statSync } from \"node:fs\";\nimport { withFileLock, withFileLockSync, writeFileAtomic, writeFileAtomicSync } from \"./atomic-file.ts\";\nimport { readBoundedTextFile, readBoundedTextFileSync } from \"./bounded-file.ts\";\n\nexport interface BoundedJsonlLimits {\n\tmaxBytes: number;\n\ttargetBytes: number;\n\tmaxRecords: number;\n}\n\nconst asyncAppendTails = new Map<string, Promise<void>>();\nconst MAX_CACHED_FILES = 128;\n\ninterface JsonlFileState {\n\tstats: Stats;\n\trecordCount: number;\n}\n\nconst fileStates = new Map<string, JsonlFileState>();\n\nfunction sameFileState(left: Stats, right: Stats): boolean {\n\treturn (\n\t\tleft.dev === right.dev &&\n\t\tleft.ino === right.ino &&\n\t\tleft.size === right.size &&\n\t\tleft.mtimeMs === right.mtimeMs &&\n\t\tleft.ctimeMs === right.ctimeMs\n\t);\n}\n\nfunction cachedRecordCount(filePath: string, stats: Stats): number | undefined {\n\tconst cached = fileStates.get(filePath);\n\tif (!cached || !sameFileState(cached.stats, stats)) return undefined;\n\tfileStates.delete(filePath);\n\tfileStates.set(filePath, cached);\n\treturn cached.recordCount;\n}\n\nfunction rememberFileState(filePath: string, stats: Stats, recordCount: number): void {\n\tfileStates.delete(filePath);\n\tfileStates.set(filePath, { stats, recordCount });\n\twhile (fileStates.size > MAX_CACHED_FILES) {\n\t\tconst oldest = fileStates.keys().next().value;\n\t\tif (oldest === undefined) break;\n\t\tfileStates.delete(oldest);\n\t}\n}\n\nfunction recordCount(content: string): number {\n\tlet count = 0;\n\tfor (const line of content.split(\"\\n\")) {\n\t\tif (line.trim().length > 0) count++;\n\t}\n\treturn count;\n}\n\nfunction validateLimits(limits: BoundedJsonlLimits): void {\n\tif (\n\t\t!Number.isSafeInteger(limits.maxBytes) ||\n\t\t!Number.isSafeInteger(limits.targetBytes) ||\n\t\t!Number.isSafeInteger(limits.maxRecords) ||\n\t\tlimits.maxBytes <= 0 ||\n\t\tlimits.targetBytes <= 0 ||\n\t\tlimits.targetBytes > limits.maxBytes ||\n\t\tlimits.maxRecords <= 0\n\t) {\n\t\tthrow new TypeError(\"Bounded JSONL limits require positive integers and targetBytes <= maxBytes.\");\n\t}\n}\n\nfunction retainedContent(content: string, limits: BoundedJsonlLimits): string {\n\tconst lines = content.split(\"\\n\").filter((line) => line.trim().length > 0);\n\tconst retained: string[] = [];\n\tlet retainedBytes = 0;\n\tfor (let index = lines.length - 1; index >= 0 && retained.length < limits.maxRecords; index--) {\n\t\tconst line = lines[index]!;\n\t\tconst lineBytes = Buffer.byteLength(line, \"utf-8\") + 1;\n\t\tif (lineBytes > limits.maxBytes) continue;\n\t\tif (retained.length > 0 && retainedBytes + lineBytes > limits.targetBytes) break;\n\t\tretained.push(line);\n\t\tretainedBytes += lineBytes;\n\t\tif (retainedBytes >= limits.targetBytes) break;\n\t}\n\tretained.reverse();\n\treturn retained.length > 0 ? `${retained.join(\"\\n\")}\\n` : \"\";\n}\n\nfunction serializeLine(value: unknown): string {\n\tconst encoded = JSON.stringify(value);\n\tif (encoded === undefined) throw new TypeError(\"Bounded JSONL records must be JSON-serializable values.\");\n\treturn `${encoded}\\n`;\n}\n\nfunction assertLineFits(line: string, limits: BoundedJsonlLimits): number {\n\tconst bytes = Buffer.byteLength(line, \"utf-8\");\n\tif (bytes > limits.maxBytes) throw new Error(\"Bounded JSONL record exceeds maxBytes.\");\n\treturn bytes;\n}\n\nfunction existingStatsSync(filePath: string): Stats | undefined {\n\ttry {\n\t\treturn statSync(filePath);\n\t} catch (error) {\n\t\tif (typeof error === \"object\" && error !== null && \"code\" in error && error.code === \"ENOENT\") return undefined;\n\t\tthrow error;\n\t}\n}\n\nasync function existingStats(filePath: string): Promise<Stats | undefined> {\n\ttry {\n\t\treturn await fsPromises.stat(filePath);\n\t} catch (error) {\n\t\tif (typeof error === \"object\" && error !== null && \"code\" in error && error.code === \"ENOENT\") return undefined;\n\t\tthrow error;\n\t}\n}\n\n/** Append one JSON record and rotate to the newest low-water tail under one exclusive lock. */\nexport function appendBoundedJsonLineSync(filePath: string, value: unknown, limits: BoundedJsonlLimits): void {\n\tvalidateLimits(limits);\n\tconst line = serializeLine(value);\n\tconst lineBytes = assertLineFits(line, limits);\n\twithFileLockSync(filePath, () => {\n\t\ttry {\n\t\t\tconst before = existingStatsSync(filePath);\n\t\t\tif (!before || before.size > limits.maxBytes) {\n\t\t\t\twriteFileAtomicSync(filePath, line);\n\t\t\t\trememberFileState(filePath, statSync(filePath), 1);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tlet content: string | undefined;\n\t\t\tlet count = cachedRecordCount(filePath, before);\n\t\t\tif (count === undefined) {\n\t\t\t\tcontent = readBoundedTextFileSync(filePath, limits.maxBytes, \"Bounded JSONL file\");\n\t\t\t\tcount = recordCount(content);\n\t\t\t}\n\t\t\tif (before.size + lineBytes <= limits.maxBytes && count + 1 <= limits.maxRecords) {\n\t\t\t\tappendFileSync(filePath, line, \"utf-8\");\n\t\t\t\trememberFileState(filePath, statSync(filePath), count + 1);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tcontent ??= readBoundedTextFileSync(filePath, limits.maxBytes, \"Bounded JSONL file\");\n\t\t\tconst retained = retainedContent(`${content}${line}`, limits);\n\t\t\twriteFileAtomicSync(filePath, retained);\n\t\t\trememberFileState(filePath, statSync(filePath), recordCount(retained));\n\t\t} catch (error) {\n\t\t\tfileStates.delete(filePath);\n\t\t\tthrow error;\n\t\t}\n\t});\n}\n\n/** Async counterpart of {@link appendBoundedJsonLineSync}. */\nexport async function appendBoundedJsonLine(\n\tfilePath: string,\n\tvalue: unknown,\n\tlimits: BoundedJsonlLimits,\n): Promise<void> {\n\tvalidateLimits(limits);\n\tconst line = serializeLine(value);\n\tconst lineBytes = assertLineFits(line, limits);\n\tconst previous = asyncAppendTails.get(filePath) ?? Promise.resolve();\n\tconst operation = previous\n\t\t.catch(() => undefined)\n\t\t.then(async () => {\n\t\t\tawait withFileLock(filePath, async () => {\n\t\t\t\ttry {\n\t\t\t\t\tconst before = await existingStats(filePath);\n\t\t\t\t\tif (!before || before.size > limits.maxBytes) {\n\t\t\t\t\t\tawait writeFileAtomic(filePath, line);\n\t\t\t\t\t\trememberFileState(filePath, await fsPromises.stat(filePath), 1);\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tlet content: string | undefined;\n\t\t\t\t\tlet count = cachedRecordCount(filePath, before);\n\t\t\t\t\tif (count === undefined) {\n\t\t\t\t\t\tcontent = await readBoundedTextFile(filePath, limits.maxBytes, \"Bounded JSONL file\");\n\t\t\t\t\t\tcount = recordCount(content);\n\t\t\t\t\t}\n\t\t\t\t\tif (before.size + lineBytes <= limits.maxBytes && count + 1 <= limits.maxRecords) {\n\t\t\t\t\t\tawait fsPromises.appendFile(filePath, line, \"utf-8\");\n\t\t\t\t\t\trememberFileState(filePath, await fsPromises.stat(filePath), count + 1);\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tcontent ??= await readBoundedTextFile(filePath, limits.maxBytes, \"Bounded JSONL file\");\n\t\t\t\t\tconst retained = retainedContent(`${content}${line}`, limits);\n\t\t\t\t\tawait writeFileAtomic(filePath, retained);\n\t\t\t\t\trememberFileState(filePath, await fsPromises.stat(filePath), recordCount(retained));\n\t\t\t\t} catch (error) {\n\t\t\t\t\tfileStates.delete(filePath);\n\t\t\t\t\tthrow error;\n\t\t\t\t}\n\t\t\t});\n\t\t});\n\tasyncAppendTails.set(filePath, operation);\n\ttry {\n\t\tawait operation;\n\t} finally {\n\t\tif (asyncAppendTails.get(filePath) === operation) asyncAppendTails.delete(filePath);\n\t}\n}\n"]}
+{"version":3,"file":"bounded-jsonl.d.ts","sourceRoot":"","sources":["../../../src/core/util/bounded-jsonl.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACnB;AAmGD,+FAA+F;AAC/F,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAgC5G;AAED,8DAA8D;AAC9D,wBAAsB,qBAAqB,CAC1C,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC,CA2Cf"}

package/dist/core/util/bounded-jsonl.js

@@ -1,19 +1,12 @@
 import { appendFileSync, promises as fsPromises, statSync } from "node:fs";
 import { withFileLock, withFileLockSync, writeFileAtomic, writeFileAtomicSync } from "./atomic-file.js";
-import { readBoundedTextFile, readBoundedTextFileSync } from "./bounded-file.js";
+import { readBoundedTextFile, readBoundedTextFileSync, sameFileVersion } from "./bounded-file.js";
 const asyncAppendTails = new Map();
 const MAX_CACHED_FILES = 128;
 const fileStates = new Map();
-function sameFileState(left, right) {
-    return (left.dev === right.dev &&
-        left.ino === right.ino &&
-        left.size === right.size &&
-        left.mtimeMs === right.mtimeMs &&
-        left.ctimeMs === right.ctimeMs);
-}
 function cachedRecordCount(filePath, stats) {
     const cached = fileStates.get(filePath);
-    if (!cached || !sameFileState(cached.stats, stats))
+    if (!cached || !sameFileVersion(cached.stats, stats))
         return undefined;
     fileStates.delete(filePath);
     fileStates.set(filePath, cached);