ttsc 0.30.4 → 0.31.0

package/lib/internal/resolveNodeBinary.js

@@ -1,157 +1,27 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.javascriptRuntimeCapabilities = javascriptRuntimeCapabilities;
 exports.resolveNodeBinary = resolveNodeBinary;
-const node_child_process_1 = __importDefault(require("node:child_process"));
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-const captureProcessOutput_1 = require("../compiler/internal/captureProcessOutput");
-const spawnSyncResilient_1 = require("./spawnSyncResilient");
-const runtimeCapabilityCache = new Map();
-/** Probe an interpreter instead of inferring its identity from the host. */
-function javascriptRuntimeCapabilities(runtime, env, cwd) {
-    const effectiveEnv = { ...process.env, ...env };
-    const cacheKey = runtimeCapabilityCacheKey(runtime, effectiveEnv);
-    const beforeIdentity = runtimeExecutableIdentity(runtime);
-    if (cacheKey !== undefined && beforeIdentity !== undefined) {
-        const cached = runtimeCapabilityCache.get(cacheKey);
-        if (cached?.identity === beforeIdentity)
-            return { ...cached.capabilities };
-        runtimeCapabilityCache.delete(cacheKey);
-    }
-    const args = [
-        "-e",
-        `const Module = require("node:module"); process.stdout.write(JSON.stringify({ bun: typeof globalThis.Bun === "object", executable: process.execPath, registerHooks: typeof Module.registerHooks === "function" }));`,
-    ];
-    const options = {
-        cwd,
-        encoding: "utf8",
-        env: effectiveEnv,
-        timeout: 30_000,
-        windowsHide: true,
-    };
-    let result = node_child_process_1.default.spawnSync(runtime, args, options);
-    if (process.platform !== "win32" && (0, spawnSyncResilient_1.isSpawnSyncFdExhaustion)(result.error)) {
-        const capture = (0, captureProcessOutput_1.captureProcessOutput)();
-        try {
-            const retried = (0, spawnSyncResilient_1.spawnSyncWithLowDescriptors)(runtime, args, options, {
-                stderr: capture.stderrPath,
-                stdout: capture.stdoutPath,
-            });
-            const stdout = capture.read("stdout", "utf8");
-            const stderr = capture.read("stderr", "utf8");
-            result = {
-                ...retried,
-                output: [null, stdout, stderr],
-                stderr,
-                stdout,
-            };
-        }
-        finally {
-            capture.dispose();
-        }
-    }
-    let capabilities = {
-        bun: false,
-        registerHooks: false,
-    };
-    if (result.status === 0) {
-        try {
-            const parsed = JSON.parse(result.stdout);
-            capabilities = {
-                bun: parsed.bun === true,
-                ...(typeof parsed.executable === "string" &&
-                    node_path_1.default.isAbsolute(parsed.executable)
-                    ? { executable: node_path_1.default.resolve(parsed.executable) }
-                    : {}),
-                registerHooks: parsed.registerHooks === true,
-            };
-        }
-        catch {
-            // An incompatible executable is not a Node runtime candidate.
-        }
-    }
-    // Cache successful absolute candidates only when the child reports that same
-    // executable and both its lexical link and physical target retain the same
-    // filesystem identity. Relative/bare commands and wrappers can resolve
-    // differently by cwd/PATH/environment, negative probes can become valid later,
-    // and NODE_OPTIONS can load mutable user code, so none of those states are
-    // memoized. This removes a process spawn from the common path without
-    // authorizing a replaced or redirected runtime in a long-lived host.
-    const afterIdentity = runtimeExecutableIdentity(runtime);
-    if (cacheKey !== undefined &&
-        capabilities.executable !== undefined &&
-        beforeIdentity !== undefined &&
-        beforeIdentity === afterIdentity &&
-        sameRuntimeExecutable(runtime, capabilities.executable)) {
-        runtimeCapabilityCache.set(cacheKey, {
-            capabilities: { ...capabilities },
-            identity: afterIdentity,
-        });
-    }
-    return capabilities;
-}
-/** True when a probe ran the candidate itself rather than a mutable wrapper. */
-function sameRuntimeExecutable(candidate, executable) {
-    try {
-        const candidateStats = node_fs_1.default.statSync(candidate, { bigint: true });
-        const executableStats = node_fs_1.default.statSync(executable, { bigint: true });
-        return ((candidateStats.ino !== 0n &&
-            candidateStats.dev === executableStats.dev &&
-            candidateStats.ino === executableStats.ino) ||
-            node_fs_1.default.realpathSync.native(candidate) === node_fs_1.default.realpathSync.native(executable));
-    }
-    catch {
-        return false;
-    }
-}
-/** Stable cache key only for an absolute runtime with no preload authority. */
-function runtimeCapabilityCacheKey(runtime, env) {
-    if (!node_path_1.default.isAbsolute(runtime) || env.NODE_OPTIONS?.trim())
-        return undefined;
-    return node_path_1.default.resolve(runtime);
-}
-/** Identity of an executable spelling and the physical file it selects. */
-function runtimeExecutableIdentity(runtime) {
-    if (!node_path_1.default.isAbsolute(runtime))
-        return undefined;
-    try {
-        const lexical = node_fs_1.default.lstatSync(runtime, { bigint: true });
-        const physicalPath = node_fs_1.default.realpathSync.native(runtime);
-        const physical = node_fs_1.default.statSync(physicalPath, { bigint: true });
-        return [
-            physicalPath,
-            lexical.dev,
-            lexical.ino,
-            lexical.mode,
-            lexical.size,
-            lexical.mtimeNs,
-            lexical.ctimeNs,
-            physical.dev,
-            physical.ino,
-            physical.mode,
-            physical.size,
-            physical.mtimeNs,
-            physical.ctimeNs,
-        ].join("\0");
-    }
-    catch {
-        return undefined;
-    }
-}
+const SidecarEnvironment_1 = require("../compiler/internal/sharedHost/SidecarEnvironment");
+const javascriptRuntimeCapabilities_1 = require("./javascriptRuntimeCapabilities");
 /**
  * Locate a real Node runtime for ttsx and native JavaScript config loaders.
  *
  * Bun can directly evaluate a descriptor, but it does not implement the
  * synchronous `module.registerHooks` contract used by those loaders.
+ *
+ * @evidence contracts/common.md#principled-implementation Ordered candidates are accepted only after an actual runtime probe reports non-Bun registerHooks support and its absolute executable; names alone do not establish the loader capability.
+ * @evidence contracts/common.md#clear-and-simple-design Candidate precedence and duplicate suppression remain here, while the shared probe owns launch, capability parsing and freshness policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The node spelling is a supported final discovery candidate, not an assumed successful runtime; incompatible candidates are skipped without patching modules or globals.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the consumer and the required synchronous hook capability, while the selection loop makes precedence apparent without redundant prose.
+ * @evidence contracts/portability.md#os-neutral-implementation Executable discovery reads injected Windows environment names case-insensitively, measures candidates through native spawning and returns the child's absolute executable.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Candidate references and seen spellings are invocation-local and become reclaimable after return. The delegated synchronous probe owns child/capture cleanup and its persistent capability map; the four-candidate list does not bound that historical map, which has no eviction policy.
+ * @evidence contracts/performance.md#efficient-algorithms At most four candidate slots are inspected with first-usable short-circuiting and exact-spelling deduplication. Environment-key/spelling work and delegated executable-byte identity, environment merge, native probing/parsing or descriptor-exhaustion retry costs dominate; four slots do not bound executable bytes, output text or native work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Exact duplicate spellings share one candidate probe within this call. The probe owner additionally reuses stable absolute same-executable capabilities only while byte/link/target identity and no-preload authority hold; relative, wrapper, changed and unproven failed candidates need fresh observation.
  */
 function resolveNodeBinary(env = process.env, cwd = process.cwd()) {
     const candidates = [
-        env.TTSC_NODE_BINARY,
-        process.env.TTSC_NODE_BINARY,
+        SidecarEnvironment_1.SidecarEnvironment.read(env, "TTSC_NODE_BINARY"),
+        SidecarEnvironment_1.SidecarEnvironment.read(process.env, "TTSC_NODE_BINARY"),
         process.execPath,
         "node",
     ];
@@ -162,7 +32,7 @@ function resolveNodeBinary(env = process.env, cwd = process.cwd()) {
         if (seen.has(candidate))
             continue;
         seen.add(candidate);
-        const capabilities = javascriptRuntimeCapabilities(candidate, env, cwd);
+        const capabilities = (0, javascriptRuntimeCapabilities_1.javascriptRuntimeCapabilities)(candidate, env, cwd);
         if (!capabilities.bun &&
             capabilities.registerHooks &&
             capabilities.executable !== undefined) {

package/lib/internal/resolveNodeBinary.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveNodeBinary.js","sourceRoot":"","sources":["../../src/internal/resolveNodeBinary.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolveNodeBinary.js","sourceRoot":"","sources":["../../src/internal/resolveNodeBinary.ts"],"names":[],"mappings":";;;AAAA,2FAAwF;AACxF,mFAAgF;AAEhF;;;;;;;;;;;;;;GAcG;AACH,2BACE,GAAG,GAAsB,OAAO,CAAC,GAAG,EACpC,GAAG,GAAW,OAAO,CAAC,GAAG,EAAE;IAE3B,MAAM,UAAU,GAAG;QACjB,uCAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC;QAChD,uCAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,kBAAkB,CAAC;QACxD,OAAO,CAAC,QAAQ;QAChB,MAAM;KACP,CAAC;IACF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QACjE,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,SAAS;QAClC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpB,MAAM,YAAY,GAAG,IAAA,6DAA6B,EAAC,SAAS,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QACxE,IACE,CAAC,YAAY,CAAC,GAAG;YACjB,YAAY,CAAC,aAAa;YAC1B,YAAY,CAAC,UAAU,KAAK,SAAS,EACrC,CAAC;YACD,OAAO,YAAY,CAAC,UAAU,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/lib/internal/resolveSafeCacheCleanupTargets.d.ts

@@ -1,15 +1,34 @@
-import { type FilesystemPathIdentityOperations } from "./projectInputPathIdentity";
-export interface SafeCacheCleanupTarget {
-    exists: boolean;
-    path: string;
-    requestedPath: string;
-}
+import type { SafeCacheCleanupTarget } from "./SafeCacheCleanupTarget";
+import { type FilesystemPathIdentityOperations } from "./pathIdentity/FilesystemPathIdentityOperations";
 /**
  * Resolve one cache-clean transaction to physical deletion targets.
  *
- * Every target is proved before the caller removes the first one. Existing
+ * Every target is checked before the caller removes the first one. Existing
  * aliases are pinned to their physical spelling, while a missing suffix keeps
  * the identity of its nearest existing parent. Identity errors other than a
  * genuinely missing path fail closed.
+ *
+ * Candidates overlapping protected directories are omitted from deletion. This
+ * preserves caller-owned caches even when another cleanup selector names their
+ * ancestor or descendant; uncertain case or Unicode overlap also preserves a
+ * candidate instead of authorizing deletion.
+ *
+ * Native-retirement guards in selected trees or their enclosing resource roots
+ * refuse the entire transaction before deletion. Terminal links retain their
+ * unlink-only semantics and do not traverse a guarded destination.
+ *
+ * The plan contains observed path spellings, not held directory handles or an
+ * atomic namespace snapshot. Pinning an ancestor alias does not prevent later
+ * replacement of the selected physical parent or terminal entry; callers must
+ * preserve that ownership boundary while using the returned plan.
+ *
+ * @evidence contracts/common.md#principled-implementation Every requested target is physically pinned and validated before return; roots and project-containing directories fail closed, while bidirectional overlap preserves caller-protected directories and unrelated candidates remain eligible.
+ * @evidence contracts/common.md#clear-and-simple-design One transaction owns identity proof, terminal-link deletion semantics and protected overlap policy for API and CLI consumers; deletion itself remains with the caller after all candidates are resolved.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Protection follows native identities rather than special cache names; aliases are resolved through supported primitives and unexpected identity errors cannot authorize deletion.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain validation-before-deletion, failure behavior and protected preservation; inline comments describe why ancestors are pinned and terminal links remain links.
+ * @evidence contracts/portability.md#os-neutral-implementation The shared native resolver handles physical aliases, volume roots and actual directory case policy; Node lstat identifies terminal links, while unknown missing suffix policy preserves spellings rather than asserting case-variant identity.
+ * @evidence contracts/performance.md#efficient-algorithms Resolving the project, P protected paths and C candidates requires path/ancestor observations independently of the overlap loop. Candidate/project checks and at most two comparisons per protected path add O(C(P+1)D) component comparisons for depth D, plus path text and delegated native realpath/stat/case-probe work; selected directory trees are scanned for native guards before the transaction returns; case probes can scan observed directory entries. Context memoization shares equivalent observations within this call; no cross-run index is built for this cleanup set.
+ * @evidence contracts/performance.md#reuse-equivalent-work All candidate and protected paths share one identity context, so equivalent ancestor realpath and case queries reuse the same transaction observations; deletion results themselves are not cached across mutable filesystem states.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Context maps retain observed identities, ancestors and case facts for this call, growing with distinct queried paths/ancestors and their text; protected identities use O(P) references and returned targets at most O(C). No directory handle is held; the context becomes reclaimable after return, while the caller owns retained plan strings and later deletion under a preserved namespace boundary.
  */
-export declare function resolveSafeCacheCleanupTargets(projectRoot: string, cacheDirectories: readonly string[], operations?: Partial<FilesystemPathIdentityOperations>): SafeCacheCleanupTarget[];
+export declare function resolveSafeCacheCleanupTargets(projectRoot: string, cacheDirectories: readonly string[], operations?: Partial<FilesystemPathIdentityOperations>, protectedDirectories?: readonly string[]): SafeCacheCleanupTarget[];

package/lib/internal/resolveSafeCacheCleanupTargets.js

@@ -6,44 +6,77 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveSafeCacheCleanupTargets = resolveSafeCacheCleanupTargets;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const projectInputPathIdentity_1 = require("./projectInputPathIdentity");
+const SourceNativeRetirement_1 = require("./SourceNativeRetirement");
+const createFilesystemPathIdentityContext_1 = require("./pathIdentity/createFilesystemPathIdentityContext");
+const resolveFilesystemPath_1 = require("./pathIdentity/resolveFilesystemPath");
 /**
  * Resolve one cache-clean transaction to physical deletion targets.
  *
- * Every target is proved before the caller removes the first one. Existing
+ * Every target is checked before the caller removes the first one. Existing
  * aliases are pinned to their physical spelling, while a missing suffix keeps
  * the identity of its nearest existing parent. Identity errors other than a
  * genuinely missing path fail closed.
+ *
+ * Candidates overlapping protected directories are omitted from deletion. This
+ * preserves caller-owned caches even when another cleanup selector names their
+ * ancestor or descendant; uncertain case or Unicode overlap also preserves a
+ * candidate instead of authorizing deletion.
+ *
+ * Native-retirement guards in selected trees or their enclosing resource roots
+ * refuse the entire transaction before deletion. Terminal links retain their
+ * unlink-only semantics and do not traverse a guarded destination.
+ *
+ * The plan contains observed path spellings, not held directory handles or an
+ * atomic namespace snapshot. Pinning an ancestor alias does not prevent later
+ * replacement of the selected physical parent or terminal entry; callers must
+ * preserve that ownership boundary while using the returned plan.
+ *
+ * @evidence contracts/common.md#principled-implementation Every requested target is physically pinned and validated before return; roots and project-containing directories fail closed, while bidirectional overlap preserves caller-protected directories and unrelated candidates remain eligible.
+ * @evidence contracts/common.md#clear-and-simple-design One transaction owns identity proof, terminal-link deletion semantics and protected overlap policy for API and CLI consumers; deletion itself remains with the caller after all candidates are resolved.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Protection follows native identities rather than special cache names; aliases are resolved through supported primitives and unexpected identity errors cannot authorize deletion.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain validation-before-deletion, failure behavior and protected preservation; inline comments describe why ancestors are pinned and terminal links remain links.
+ * @evidence contracts/portability.md#os-neutral-implementation The shared native resolver handles physical aliases, volume roots and actual directory case policy; Node lstat identifies terminal links, while unknown missing suffix policy preserves spellings rather than asserting case-variant identity.
+ * @evidence contracts/performance.md#efficient-algorithms Resolving the project, P protected paths and C candidates requires path/ancestor observations independently of the overlap loop. Candidate/project checks and at most two comparisons per protected path add O(C(P+1)D) component comparisons for depth D, plus path text and delegated native realpath/stat/case-probe work; selected directory trees are scanned for native guards before the transaction returns; case probes can scan observed directory entries. Context memoization shares equivalent observations within this call; no cross-run index is built for this cleanup set.
+ * @evidence contracts/performance.md#reuse-equivalent-work All candidate and protected paths share one identity context, so equivalent ancestor realpath and case queries reuse the same transaction observations; deletion results themselves are not cached across mutable filesystem states.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Context maps retain observed identities, ancestors and case facts for this call, growing with distinct queried paths/ancestors and their text; protected identities use O(P) references and returned targets at most O(C). No directory handle is held; the context becomes reclaimable after return, while the caller owns retained plan strings and later deletion under a preserved namespace boundary.
  */
-function resolveSafeCacheCleanupTargets(projectRoot, cacheDirectories, operations = {}) {
-    const identities = (0, projectInputPathIdentity_1.createFilesystemPathIdentityContext)(operations);
+function resolveSafeCacheCleanupTargets(projectRoot, cacheDirectories, operations = {}, protectedDirectories = []) {
+    const identities = (0, createFilesystemPathIdentityContext_1.createFilesystemPathIdentityContext)(operations);
     const lstat = operations.lstat ?? node_fs_1.default.lstatSync;
     const project = identities.resolve(projectRoot);
-    return cacheDirectories.map((cacheDirectory) => {
-        const requestedCache = (0, projectInputPathIdentity_1.resolveFilesystemPath)(cacheDirectory);
+    const protectedIdentities = protectedDirectories.map((directory) => identities.resolve(directory));
+    const targets = [];
+    for (const cacheDirectory of cacheDirectories) {
+        const requestedCache = (0, resolveFilesystemPath_1.resolveFilesystemPath)(cacheDirectory);
         // Fix every mutable alias ancestor before inspecting the terminal entry.
         // All later identity checks and deletion paths use this physical-parent
-        // candidate, so a concurrent retarget cannot move ownership mid-proof.
+        // candidate rather than following the original lexical ancestor again.
+        // No held handle prevents replacement of that physical namespace itself.
         const pinnedCache = node_path_1.default.join(identities.resolve(node_path_1.default.dirname(requestedCache)).path, node_path_1.default.basename(requestedCache));
         const cache = identities.resolve(pinnedCache);
         if (requestedCache === node_path_1.default.parse(requestedCache).root ||
             cache.path === node_path_1.default.parse(cache.path).root) {
             throw new Error(`ttsc: refusing to clean cache directory ${JSON.stringify(requestedCache)} because filesystem roots are never valid cache directories`);
         }
-        if ((0, projectInputPathIdentity_1.isFilesystemPathIdentityWithin)(cache.key, project.key)) {
+        if (identities.lexicalIsWithin(cache.path, project.path)) {
             throw new Error(`ttsc: refusing to clean cache directory ${JSON.stringify(requestedCache)} because it equals or contains project root ${JSON.stringify(project.path)}; choose a dedicated cache directory`);
         }
+        if (protectedIdentities.some((protectedDirectory) => identities.lexicalIsWithin(protectedDirectory.path, cache.path) ||
+            identities.lexicalIsWithin(cache.path, protectedDirectory.path)))
+            continue;
         const status = lstatIfPresent(pinnedCache, lstat);
         // Recursive rm removes a terminal symlink or junction itself rather than
         // following it. Preserve that behavior while pinning any mutable alias in
         // its ancestors to the physical parent selected by this transaction.
         const deletionPath = status?.isSymbolicLink() ? pinnedCache : cache.path;
-        return {
+        SourceNativeRetirement_1.SourceNativeRetirement.assertCleanable(deletionPath);
+        targets.push({
             exists: status !== undefined,
             path: deletionPath,
             requestedPath: requestedCache,
-        };
-    });
+        });
+    }
+    return targets;
 }
 function lstatIfPresent(location, lstat) {
     try {

package/lib/internal/resolveSafeCacheCleanupTargets.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveSafeCacheCleanupTargets.js","sourceRoot":"","sources":["../../src/internal/resolveSafeCacheCleanupTargets.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B,yEAKoC;AAQpC;;;;;;;GAOG;AACH,wCACE,WAAmB,EACnB,gBAAmC,EACnC,UAAU,GAA8C,EAAE;IAE1D,MAAM,UAAU,GAAG,IAAA,8DAAmC,EAAC,UAAU,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,iBAAE,CAAC,SAAS,CAAC;IAC/C,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAChD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,cAAc,EAAE,EAAE;QAC7C,MAAM,cAAc,GAAG,IAAA,gDAAqB,EAAC,cAAc,CAAC,CAAC;QAC7D,yEAAyE;QACzE,wEAAwE;QACxE,uEAAuE;QACvE,MAAM,WAAW,GAAG,mBAAI,CAAC,IAAI,CAC3B,UAAU,CAAC,OAAO,CAAC,mBAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,EACrD,mBAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAC9B,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC9C,IACE,cAAc,KAAK,mBAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,IAAI;YAClD,KAAK,CAAC,IAAI,KAAK,mBAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAC1C,CAAC;YACD,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,6DAA6D,CACvI,CAAC;QACJ,CAAC;QACD,IAAI,IAAA,yDAA8B,EAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,+CAA+C,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,sCAAsC,CAC3L,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,cAAc,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QAClD,yEAAyE;QACzE,0EAA0E;QAC1E,qEAAqE;QACrE,MAAM,YAAY,GAAG,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;QACzE,OAAO;YACL,MAAM,EAAE,MAAM,KAAK,SAAS;YAC5B,IAAI,EAAE,YAAY;YAClB,aAAa,EAAE,cAAc;SAC9B,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,cAAc,CACrB,QAAgB,EAChB,KAA6D;IAE7D,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IACE,KAAK,YAAY,KAAK;YACtB,MAAM,IAAI,KAAK;YACf,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,EACrD,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"resolveSafeCacheCleanupTargets.js","sourceRoot":"","sources":["../../src/internal/resolveSafeCacheCleanupTargets.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAG7B,qEAAkE;AAElE,4GAAyG;AACzG,gFAA6E;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wCACE,WAAmB,EACnB,gBAAmC,EACnC,UAAU,GAA8C,EAAE,EAC1D,oBAAoB,GAAsB,EAAE;IAE5C,MAAM,UAAU,GAAG,IAAA,yEAAmC,EAAC,UAAU,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,iBAAE,CAAC,SAAS,CAAC;IAC/C,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,mBAAmB,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CACjE,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAC9B,CAAC;IACF,MAAM,OAAO,GAA6B,EAAE,CAAC;IAC7C,KAAK,MAAM,cAAc,IAAI,gBAAgB,EAAE,CAAC;QAC9C,MAAM,cAAc,GAAG,IAAA,6CAAqB,EAAC,cAAc,CAAC,CAAC;QAC7D,yEAAyE;QACzE,wEAAwE;QACxE,uEAAuE;QACvE,yEAAyE;QACzE,MAAM,WAAW,GAAG,mBAAI,CAAC,IAAI,CAC3B,UAAU,CAAC,OAAO,CAAC,mBAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,EACrD,mBAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAC9B,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC9C,IACE,cAAc,KAAK,mBAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,IAAI;YAClD,KAAK,CAAC,IAAI,KAAK,mBAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAC1C,CAAC;YACD,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,6DAA6D,CACvI,CAAC;QACJ,CAAC;QACD,IAAI,UAAU,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,+CAA+C,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,sCAAsC,CAC3L,CAAC;QACJ,CAAC;QACD,IACE,mBAAmB,CAAC,IAAI,CACtB,CAAC,kBAAkB,EAAE,EAAE,CACrB,UAAU,CAAC,eAAe,CAAC,kBAAkB,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;YAC/D,UAAU,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAClE;YAED,SAAS;QACX,MAAM,MAAM,GAAG,cAAc,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QAClD,yEAAyE;QACzE,0EAA0E;QAC1E,qEAAqE;QACrE,MAAM,YAAY,GAAG,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;QACzE,+CAAsB,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC;YACX,MAAM,EAAE,MAAM,KAAK,SAAS;YAC5B,IAAI,EAAE,YAAY;YAClB,aAAa,EAAE,cAAc;SAC9B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,cAAc,CACrB,QAAgB,EAChB,KAA6D;IAE7D,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IACE,KAAK,YAAY,KAAK;YACtB,MAAM,IAAI,KAAK;YACf,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,EACrD,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/lib/internal/restoreCompilerError.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Restore compiler-error transport while retaining shared and circular data.
+ *
+ * The serializer supplies a finite data graph with JSON-pointer reference
+ * markers. All nodes are allocated before their fields are connected, so
+ * forward references and circular causes require no recursive restoration.
+ * Literal-object envelopes distinguish source metadata from generated markers;
+ * their bodies remain data even when they have a marker's exact field shape.
+ * Tagged exceptional values and accessor descriptions remain descriptions; this
+ * receiver does not execute accessors or manufacture their values.
+ *
+ * @evidence contracts/common.md#principled-implementation Allocating the serialized graph before linking its fields preserves shared causes and aggregate members instead of turning reference markers into unrelated errors. Exact marker shapes and identified literal bodies keep user metadata distinct from generated references. The root and Error-shaped causes or aggregate members acquire Error prototypes; ordinary outcome objects retain their data representation.
+ * @evidence contracts/common.md#clear-and-simple-design One iterative discovery, allocation and linking sequence shares a source-node map and the serializer's pointer spellings.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual reference targets supply error data; messages do not guess ownership or replace unresolved native outcomes. Exceptional-value and accessor tags remain explicit diagnostic data.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains finite serialized inputs, forward/circular references and preserved tagged descriptions.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Restoration handles structured data only and performs no native filesystem or process operation.
+ * @evidence contracts/performance.md#efficient-algorithms Iterative discovery and field linking visit serialized nodes and fields once, with pointer text and property data contributing their actual bytes. The explicit worklist avoids call-stack growth on nested aggregates and cycles.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A source-node map preserves identities within this one received graph; it shares no failure or compiler result across requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Maps and worklists belong to this invocation; the caller owns the returned error graph and its shared or circular references. No global error history or native resource is retained.
+ */
+export declare function restoreCompilerError(value: unknown): Error;

package/lib/internal/restoreCompilerError.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restoreCompilerError = restoreCompilerError;
+/**
+ * Restore compiler-error transport while retaining shared and circular data.
+ *
+ * The serializer supplies a finite data graph with JSON-pointer reference
+ * markers. All nodes are allocated before their fields are connected, so
+ * forward references and circular causes require no recursive restoration.
+ * Literal-object envelopes distinguish source metadata from generated markers;
+ * their bodies remain data even when they have a marker's exact field shape.
+ * Tagged exceptional values and accessor descriptions remain descriptions; this
+ * receiver does not execute accessors or manufacture their values.
+ *
+ * @evidence contracts/common.md#principled-implementation Allocating the serialized graph before linking its fields preserves shared causes and aggregate members instead of turning reference markers into unrelated errors. Exact marker shapes and identified literal bodies keep user metadata distinct from generated references. The root and Error-shaped causes or aggregate members acquire Error prototypes; ordinary outcome objects retain their data representation.
+ * @evidence contracts/common.md#clear-and-simple-design One iterative discovery, allocation and linking sequence shares a source-node map and the serializer's pointer spellings.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual reference targets supply error data; messages do not guess ownership or replace unresolved native outcomes. Exceptional-value and accessor tags remain explicit diagnostic data.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains finite serialized inputs, forward/circular references and preserved tagged descriptions.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Restoration handles structured data only and performs no native filesystem or process operation.
+ * @evidence contracts/performance.md#efficient-algorithms Iterative discovery and field linking visit serialized nodes and fields once, with pointer text and property data contributing their actual bytes. The explicit worklist avoids call-stack growth on nested aggregates and cycles.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A source-node map preserves identities within this one received graph; it shares no failure or compiler result across requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Maps and worklists belong to this invocation; the caller owns the returned error graph and its shared or circular references. No global error history or native resource is retained.
+ */
+function restoreCompilerError(value) {
+    if (value === null || typeof value !== "object")
+        return new Error(String(value));
+    const paths = new Map();
+    const fields = new Map();
+    const literals = new Map();
+    const literalBodies = new Set();
+    const references = new Map();
+    const pending = [{ input: value, pointer: "" }];
+    while (pending.length !== 0) {
+        const { input, pointer } = pending.pop();
+        paths.set(pointer, input);
+        if (fields.has(input))
+            continue;
+        const properties = Object.getOwnPropertyDescriptors(input);
+        fields.set(input, properties);
+        const body = properties.$ttscProperties?.value;
+        const keys = Object.keys(properties);
+        if (!literalBodies.has(input) &&
+            !Array.isArray(input) &&
+            keys.length === 2 &&
+            properties.$ttscValue?.value === "object" &&
+            body !== null &&
+            typeof body === "object" &&
+            !Array.isArray(body)) {
+            literals.set(input, body);
+            literalBodies.add(body);
+        }
+        if (!literalBodies.has(input) &&
+            !Array.isArray(input) &&
+            keys.length === 1 &&
+            typeof properties.$ttscReference?.value === "string")
+            references.set(input, properties.$ttscReference.value);
+        for (const [name, property] of Object.entries(properties)) {
+            if (!("value" in property) ||
+                property.value === null ||
+                typeof property.value !== "object")
+                continue;
+            pending.push({
+                input: property.value,
+                pointer: `${pointer}/${name.replaceAll("~", "~0").replaceAll("/", "~1")}`,
+            });
+        }
+    }
+    const target = (input) => {
+        const literal = literals.get(input);
+        if (literal !== undefined)
+            return literal;
+        if (literalBodies.has(input) || Array.isArray(input))
+            return input;
+        const reference = references.get(input);
+        if (reference === undefined)
+            return input;
+        const referenced = paths.get(reference);
+        return referenced === undefined
+            ? input
+            : (literals.get(referenced) ?? referenced);
+    };
+    const errors = new Set();
+    const aggregateArrays = new Set();
+    const errorNodes = [target(value)];
+    while (errorNodes.length !== 0) {
+        const error = errorNodes.pop();
+        if (errors.has(error))
+            continue;
+        errors.add(error);
+        const properties = fields.get(error);
+        const aggregate = properties.errors?.value;
+        const members = aggregate !== null && typeof aggregate === "object"
+            ? target(aggregate)
+            : aggregate;
+        if (Array.isArray(members) && !aggregateArrays.has(members)) {
+            aggregateArrays.add(members);
+            for (const [name, descriptor] of Object.entries(fields.get(members))) {
+                // Array members are canonical indices, not holes or custom metadata.
+                const index = Number(name);
+                if (!Number.isInteger(index) ||
+                    index < 0 ||
+                    index >= 0xffffffff ||
+                    String(index) !== name ||
+                    !("value" in descriptor))
+                    continue;
+                const member = descriptor.value;
+                if (member === null || typeof member !== "object")
+                    continue;
+                const candidate = target(member);
+                const candidateFields = fields.get(candidate);
+                if (typeof candidateFields?.name?.value === "string" &&
+                    typeof candidateFields?.message?.value === "string")
+                    errorNodes.push(candidate);
+            }
+        }
+        const cause = properties.cause;
+        if (cause &&
+            "value" in cause &&
+            cause.value !== null &&
+            typeof cause.value === "object") {
+            const candidate = target(cause.value);
+            const candidateFields = fields.get(candidate);
+            if (typeof candidateFields?.name?.value === "string" &&
+                typeof candidateFields?.message?.value === "string")
+                errorNodes.push(candidate);
+        }
+    }
+    const restored = new Map();
+    for (const [input, properties] of fields) {
+        if (target(input) !== input)
+            continue;
+        const aggregate = properties.errors?.value;
+        const members = aggregate !== null && typeof aggregate === "object"
+            ? target(aggregate)
+            : aggregate;
+        restored.set(input, errors.has(input)
+            ? Array.isArray(members)
+                ? new AggregateError([], properties.message?.value)
+                : new Error(properties.message?.value ?? String(input))
+            : Array.isArray(input)
+                ? new Array(properties.length?.value)
+                : {});
+    }
+    for (const [input, properties] of fields) {
+        if (target(input) !== input)
+            continue;
+        const output = restored.get(input);
+        for (const [name, property] of Object.entries(properties)) {
+            if (Array.isArray(output) && name === "length")
+                continue;
+            const item = "value" in property ? property.value : undefined;
+            Object.defineProperty(output, name, "value" in property
+                ? {
+                    ...property,
+                    value: item !== null && typeof item === "object"
+                        ? restored.get(target(item))
+                        : item,
+                }
+                : property);
+        }
+    }
+    return restored.get(target(value));
+}
+//# sourceMappingURL=restoreCompilerError.js.map

package/lib/internal/restoreCompilerError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restoreCompilerError.js","sourceRoot":"","sources":["../../src/internal/restoreCompilerError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8BAAqC,KAAc;IACjD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAC7C,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8C,CAAC;IACrE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,MAAM,OAAO,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;IAChD,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,EAAG,CAAC;QAC1C,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC1B,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QAChC,MAAM,UAAU,GAAG,MAAM,CAAC,yBAAyB,CAAC,KAAK,CAAC,CAAC;QAC3D,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QAC9B,MAAM,IAAI,GAAG,UAAU,CAAC,eAAe,EAAE,KAAK,CAAC;QAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACrC,IACE,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;YACzB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACrB,IAAI,CAAC,MAAM,KAAK,CAAC;YACjB,UAAU,CAAC,UAAU,EAAE,KAAK,KAAK,QAAQ;YACzC,IAAI,KAAK,IAAI;YACb,OAAO,IAAI,KAAK,QAAQ;YACxB,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EACpB,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC1B,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,IACE,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;YACzB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACrB,IAAI,CAAC,MAAM,KAAK,CAAC;YACjB,OAAO,UAAU,CAAC,cAAc,EAAE,KAAK,KAAK,QAAQ;YAEpD,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACzD,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC1D,IACE,CAAC,CAAC,OAAO,IAAI,QAAQ,CAAC;gBACtB,QAAQ,CAAC,KAAK,KAAK,IAAI;gBACvB,OAAO,QAAQ,CAAC,KAAK,KAAK,QAAQ;gBAElC,SAAS;YACX,OAAO,CAAC,IAAI,CAAC;gBACX,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,OAAO,EAAE,GAAG,OAAO,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE;aAC1E,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,KAAa,EAAU,EAAE;QACvC,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,OAAO,CAAC;QAC1C,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACnE,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAC1C,MAAM,UAAU,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACxC,OAAO,UAAU,KAAK,SAAS;YAC7B,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,CAAC;IAC/C,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1C,MAAM,UAAU,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnC,OAAO,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAG,CAAC;QAChC,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QAChC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClB,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC;QACtC,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC;QAC3C,MAAM,OAAO,GACX,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ;YACjD,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;YACnB,CAAC,CAAC,SAAS,CAAC;QAChB,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5D,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC7B,KAAK,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC,EAAE,CAAC;gBACtE,qEAAqE;gBACrE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC3B,IACE,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;oBACxB,KAAK,GAAG,CAAC;oBACT,KAAK,IAAI,UAAU;oBACnB,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI;oBACtB,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC;oBAExB,SAAS;gBACX,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC;gBAChC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;oBAAE,SAAS;gBAC5D,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;gBACjC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBAC9C,IACE,OAAO,eAAe,EAAE,IAAI,EAAE,KAAK,KAAK,QAAQ;oBAChD,OAAO,eAAe,EAAE,OAAO,EAAE,KAAK,KAAK,QAAQ;oBAEnD,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;QAC/B,IACE,KAAK;YACL,OAAO,IAAI,KAAK;YAChB,KAAK,CAAC,KAAK,KAAK,IAAI;YACpB,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,EAC/B,CAAC;YACD,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACtC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC9C,IACE,OAAO,eAAe,EAAE,IAAI,EAAE,KAAK,KAAK,QAAQ;gBAChD,OAAO,eAAe,EAAE,OAAO,EAAE,KAAK,KAAK,QAAQ;gBAEnD,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,KAAK,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,MAAM,EAAE,CAAC;QACzC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK;YAAE,SAAS;QACtC,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC;QAC3C,MAAM,OAAO,GACX,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ;YACjD,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;YACnB,CAAC,CAAC,SAAS,CAAC;QAChB,QAAQ,CAAC,GAAG,CACV,KAAK,EACL,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;YACf,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;gBACtB,CAAC,CAAC,IAAI,cAAc,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC;gBACnD,CAAC,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBACpB,CAAC,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC;gBACrC,CAAC,CAAC,EAAE,CACT,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,MAAM,EAAE,CAAC;QACzC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK;YAAE,SAAS;QACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC;QACpC,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,IAAI,KAAK,QAAQ;gBAAE,SAAS;YACzD,MAAM,IAAI,GAAG,OAAO,IAAI,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;YAC9D,MAAM,CAAC,cAAc,CACnB,MAAM,EACN,IAAI,EACJ,OAAO,IAAI,QAAQ;gBACjB,CAAC,CAAC;oBACE,GAAG,QAAQ;oBACX,KAAK,EACH,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;wBACvC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;wBAC5B,CAAC,CAAC,IAAI;iBACX;gBACH,CAAC,CAAC,QAAQ,CACb,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAU,CAAC;AAC9C,CAAC"}

package/lib/internal/retireLockDirectory.d.ts

@@ -0,0 +1,45 @@
+import type { RetireLockDirectoryOperations } from "./RetireLockDirectoryOperations";
+/**
+ * Free a held lock generation by renaming its directory onto its tombstone, the
+ * one operation both build-lock protocols retire a generation with.
+ *
+ * Windows access or busy refusals can occur while peers read the holder's
+ * record inside the held generation. The error alone does not identify the
+ * cause or duration. The policy samples a newly created empty sibling rename
+ * between the same parents rather than using a time window. A successful probe
+ * establishes that this sampled sibling move succeeded. Under the protocol's
+ * caller-owned generation premise this permits a retry after `yieldToPeers`. It
+ * does not prove that source-specific permissions or attributes allow the held
+ * directory to move. Ordinary work has no retry deadline. Once scoped
+ * cancellation is observed, cleanup permits one second of further contention:
+ * this leaves the request owner's shutdown budget for other releases while
+ * allowing transient readers to yield. Expiry reports the last real refusal as
+ * the cause of cleanup failure, never successful retirement. An opted-in owner
+ * also receives that failure through its scope when a legacy caller catches the
+ * thrown exception. Native calls and the caller's yield can exceed that
+ * between-attempt grace. When the probe is refused too, the original retirement
+ * refusal is thrown; the probe failure does not prove a particular permission
+ * or sharing cause.
+ *
+ * @param source The held generation's directory.
+ * @param destination Its tombstone, which a successor's retire can never reuse.
+ * @param yieldToPeers Waits once, by the protocol's own polling interval.
+ * @param operations Filesystem and platform primitives; the real filesystem and
+ *   `process.platform` by default, injectable so the Windows-only probe
+ *   branches can be exercised on any host.
+ * @returns `true` when the generation was retired; `false` when `source` is
+ *   reported missing or `destination` is observed occupied. Those outcomes are
+ *   treated as peer progress, without proving which actor changed the paths.
+ * @throws When the rename fails for any other reason.
+ * @evidence contracts/common.md#principled-implementation Renaming the held generation to its unique tombstone is the ownership transition; reported missing or occupied paths are treated as peer progress. A successful Windows sibling probe permits retry under caller-owned generation assumptions but cannot identify the original refusal's cause or rule out source-specific restrictions. Scoped cancelled cleanup stops retry admission after one second and preserves the last real refusal as failure cause; reporting it to the explicit owner preserves that failure across legacy outcome conversion.
+ * @evidence contracts/common.md#clear-and-simple-design One retirement loop delegates missing/occupied classification and native peer-contention probing to private helpers; polling timing remains with the lock protocol caller, and one optional operations argument is the only seam, defaulting to the real filesystem and platform.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Windows retry addresses supported peer reads beneath the held generation rather than overriding filesystem methods; the source-specific restriction uncertainty remains explicit instead of being described as a proved peer cause. The injectable operations are a typed boundary that must report real native results and codes, not a replacement of foreign filesystem methods.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain tombstone ownership, supported contention, probe limits, ordinary unbounded retries and the cancelled-cleanup admission grace; outcome and yield meanings remain separately documented.
+ * @evidence contracts/portability.md#os-neutral-implementation Node rename and errno classification carry native behavior; only Windows access/busy refusals invoke the sibling probe, selected by the operations' platform value (the process platform by default), and POSIX unrelated failures propagate.
+ * @evidence contracts/performance.md#efficient-algorithms Each attempt performs one retirement rename and at most one sibling probe with a fixed-length random suffix. Path strings scale with source/destination text; native existence, allocation, rename and removal work and the supplied yield callback are delegated costs. Ordinary retries have no cap; cancelled retries check a one-second monotonic grace between native attempts and yields; no explicit directory enumeration occurs unless delegated recursive probe cleanup needs it.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A rename and its contention observations are mutable ownership effects; replaying a previous result would not retire the current generation.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The operation retires one caller-held generation and attempts to remove each temporary probe; a refused probe removal leaves that empty sibling directory behind without changing the retry decision, ordinary repeated contention can retain the call indefinitely, while scoped cancelled cleanup fails after its between-attempt grace with the last refusal as cause. Native calls/yields are not hard bounded; protocol cleanup owns the retired tombstone.
+ */
+export declare function retireLockDirectory(source: string, destination: string, yieldToPeers: () => void, operations?: RetireLockDirectoryOperations): boolean;