ttsc 0.30.4 → 0.31.0

package/lib/plugin/internal/source/PluginBuildLockProtocol.js

@@ -0,0 +1,287 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginBuildLockProtocol = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const SourceNativeRetirement_1 = require("../../../internal/SourceNativeRetirement");
+const retireLockDirectory_1 = require("../../../internal/retireLockDirectory");
+/**
+ * The on-disk layout of the source-plugin build lock and the primitives every
+ * lock operation shares.
+ *
+ * A cold source-plugin build delegates work to `go build`; its duration depends
+ * on the selected inputs and toolchain cache. When a program fans out into many
+ * processes (a `pnpm -r` running suites in parallel, a benchmark, a worker
+ * pool), each inherits the same cold cache and would otherwise build the same
+ * cache key at the same instant. Cooperating v3 consumers serialize build
+ * ownership while waiters observe publication or fail their admission budget;
+ * this does not serialize old-protocol clients.
+ *
+ * V3 lives in `<lockDir>.v3`. A complete generation is published at `current/`
+ * and retired by renaming it to `retired/<generation>`. Holder and observer
+ * records keep that destination reserved while a process can still use its
+ * lease or fence. Persistent roots are not deleted with binary cache entries.
+ * Release alone records task completion in the exact retired generation after
+ * the payload callback ends; timeout retirement cannot supply that witness.
+ *
+ * Old v2 clients use a separate namespace and cannot retire v3 generations. The
+ * pre-v2 legacy protocol held `<lockDir>` itself; its captured fence preserves
+ * the original directory mtime but cannot add atomic cooperation to old
+ * executables that remove and recreate that path.
+ *
+ * @evidence contracts/common.md#principled-implementation Nonempty publication and deterministic retirement destinations establish generation ownership; recorded observers preserve the fencing premise after the original holder dies.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns layout constants, validation and native retirement adapters shared by acquisition, observation, release and reclamation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Protocol-defined filenames and time budgets express supported coordination; v3 is isolated from old clients instead of assuming their unregistered capabilities expired.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain layout, observer-protected history, persistent roots and old-protocol limits; members document their purpose separately from their tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Protocol names remain fixed spelling while path.join and Node filesystem abstractions carry native paths and the rename helper handles observed Windows sharing refusals.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace groups protocol operations; individual functions own their computation strategies.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace is not a cache or in-flight producer; acquisition and observation own their respective sharing decisions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace declaration acquires no resources; its acquisition, retirement and observation operations own their lifetimes.
+ */
+var PluginBuildLockProtocol;
+(function (PluginBuildLockProtocol) {
+    /**
+     * Maximum admission-wait budget for a source-plugin build. Exhaustion fails
+     * the request; it cannot authorize retirement of a live or uncertain holder.
+     */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_WAIT_MS = 600_000;
+    /**
+     * How long one wait of the lock protocol yields: a waiter's poll of the
+     * holder, and a retire's wait for a peer's read of the held generation to end
+     * (`retireLockDirectory`).
+     */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_POLL_MS = 50;
+    /** File inside a generation directory recording the holder's pid and host. */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OWNER_FILE = "owner.json";
+    /** File proving that the recorded holder's payload callback has ended. */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_COMPLETION_FILE = "task-complete";
+    /** Marker file whose exact content proves a directory speaks protocol v3. */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_PROTOCOL_FILE = "protocol-v3";
+    /** File inside a generation directory holding its hex id. */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_GENERATION_FILE = "generation";
+    /** Directory recording the fence of a captured legacy lock. */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_LEGACY_FENCE_DIR = "legacy-generation";
+    /** File inside the legacy fence directory holding its generation and mtime. */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_LEGACY_FENCE_RECORD = "fence.json";
+    /** Directory name of the held v3 generation. */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_CURRENT_DIR = "current";
+    /** Directory holding one tombstone per retired v3 generation. */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_RETIRED_DIR = "retired";
+    /** Directory containing the recorded processes that hold observed fences. */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OBSERVERS_DIR = "observers";
+    const PLUGIN_BUILD_LOCK_V3_SUFFIX = ".v3";
+    /** Exact content of the protocol marker file. */
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_PROTOCOL = "ttsc-plugin-build-lock-v3\n";
+    /**
+     * The persistent v3 coordination path derived from a legacy lock path.
+     *
+     * @evidence contracts/common.md#principled-implementation Appending the version suffix separates new ownership and tombstones from old v2 clients without changing the caller's cache-key identity.
+     * @evidence contracts/common.md#clear-and-simple-design One derivation supplies the same coordination namespace to every lock operation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The suffix is a protocol discriminant, not a machine or consumer-specific pathname exception.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies persistent coordination and its legacy-path input before the tags.
+     * @evidence contracts/portability.md#os-neutral-implementation The suffix changes a path component's spelling without choosing native separators or assuming filesystem case policy.
+     * @evidence contracts/performance.md#efficient-algorithms A single string concatenation costs time and space proportional to the input path length.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Path derivation is not a coordinator of completed or in-flight build work and retains no shared result.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned path carries no acquired handle, task or retained cache state.
+     */
+    function pluginBuildLockProtocolDir(lockDir) {
+        return `${lockDir}${PLUGIN_BUILD_LOCK_V3_SUFFIX}`;
+    }
+    PluginBuildLockProtocol.pluginBuildLockProtocolDir = pluginBuildLockProtocolDir;
+    /**
+     * Whether `lockDir` is a real directory (not a link) whose protocol marker
+     * has exactly the v3 content at its sequential metadata/read observations.
+     * The pathname is not pinned against replacement between them. Read failures
+     * remain an unconfirmed layout.
+     *
+     * @evidence contracts/common.md#principled-implementation lstat rejects a linked root and exact marker content distinguishes this version's filesystem protocol from unrelated directories.
+     * @evidence contracts/common.md#clear-and-simple-design One layout predicate centralizes version recognition without acquiring or retiring ownership.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Recognition reads actual metadata instead of inferring protocol from an OS name or directory suffix alone.
+     * @evidence contracts/common.md#meaningful-documentation Native prose documents observed root kind and marker requirements, sequential replacement limits and inconclusive read failure before the tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Node lstat exposes actual link and directory capabilities; exact marker bytes are protocol identity independent of native path case behavior.
+     * @evidence contracts/performance.md#efficient-algorithms One lstat and one marker read avoid directory enumeration; processing and temporary space include path construction and the marker file's bytes.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Protocol recognition must observe the current pathname because a previously recognized layout can disappear or be replaced.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous predicate retains no open descriptor or background state.
+     */
+    function isPluginBuildLockProtocolV3(lockDir) {
+        try {
+            const stats = node_fs_1.default.lstatSync(lockDir);
+            if (!stats.isDirectory() || stats.isSymbolicLink())
+                return false;
+            return (node_fs_1.default.readFileSync(node_path_1.default.join(lockDir, PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_PROTOCOL_FILE), "utf8") === PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_PROTOCOL);
+        }
+        catch {
+            return false;
+        }
+    }
+    PluginBuildLockProtocol.isPluginBuildLockProtocolV3 = isPluginBuildLockProtocolV3;
+    /**
+     * Retire `generation` if it is still the held v3 one, by renaming `current/`
+     * onto its tombstone. Returns `false` when the lock is already free or held
+     * by another generation; throws only on an unexpected filesystem error.
+     *
+     * Native guards independently prohibit retirement of an unresolved exact
+     * generation, even when its recorded Node owner is absent.
+     *
+     * Its nonempty destination must remain while the recorded holder or any
+     * registered observer can still act. A pre-rename identity read alone would
+     * not close the replacement race. Ordinary synchronous retirement retains its
+     * existing contention retries. Scoped cancellation instead permits the shared
+     * retirement helper's cleanup grace; a continuing refusal propagates as
+     * cleanup failure rather than certifying that this generation was retired.
+     *
+     * @evidence contracts/common.md#principled-implementation A reserved nonempty tombstone makes the rename fail atomically for a stale generation; observer-aware collection preserves that reservation until all recorded capability holders are gone.
+     * @evidence contracts/common.md#clear-and-simple-design The operation validates the token and derives one retirement destination, leaving owner proofs to observation and collection.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Retirement preserves generation history and uses the shared native rename primitive rather than replacing fencing with a racy read followed by recursive removal.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the return/error contract, required tombstone lifetime and the reason a generation read is insufficient before the tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Node path and filesystem operations feed the shared retirement helper. Selected Windows refusals retry after a successful sibling-rename probe; this is a sampled capability, not proof that a peer read caused the original refusal.
+     * @evidence contracts/performance.md#efficient-algorithms Native guard inspection precedes direct generation addressing without historical-generation scans. Each attempt performs path construction and native metadata/rename observations; eligible Windows retries add sibling probes and synchronous poll waits. Ordinary synchronous retries have no attempt-count or elapsed-time bound; scoped cancelled retries use retireLockDirectory's one-second between-attempt cleanup grace, which does not bound native calls or yields.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Retirement changes ownership; its result cannot be memoized across independently racing callers.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Renaming transfers the directory into history; the cooperating collector requires holder/observer absence before removal. Retry-probe deletion is best-effort and may leave empty siblings. A continuing eligible refusal can retain ordinary synchronous work indefinitely; scoped cancellation's cleanup-grace failure propagates through retireLockDirectory and is recorded for the opted-in owner. Native calls and yields can delay observation. This operation installs no asynchronous handle.
+     */
+    function retireV3PluginBuildLock(lockDir, generation) {
+        if (!isPluginBuildLockGeneration(generation))
+            return false;
+        SourceNativeRetirement_1.SourceNativeRetirement.assertReleasable(lockDir, generation);
+        const retiredDir = node_path_1.default.join(lockDir, PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_RETIRED_DIR);
+        try {
+            node_fs_1.default.mkdirSync(retiredDir);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                if (isMissingPathError(error))
+                    return false;
+                throw error;
+            }
+        }
+        return (0, retireLockDirectory_1.retireLockDirectory)(node_path_1.default.join(lockDir, PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_CURRENT_DIR), node_path_1.default.join(retiredDir, generation), () => sleepSync(PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_POLL_MS));
+    }
+    PluginBuildLockProtocol.retireV3PluginBuildLock = retireV3PluginBuildLock;
+    /**
+     * Whether an error proves a path or one of its parents is absent.
+     *
+     * @evidence contracts/common.md#principled-implementation ENOENT and ENOTDIR denote missing path structure, while permission and sharing errors do not establish absence.
+     * @evidence contracts/common.md#clear-and-simple-design One errno predicate keeps path absence separate from contention and other failure policies.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unexpected filesystem failures are not broadened into absence to make lock operations succeed.
+     * @evidence contracts/common.md#meaningful-documentation Native prose names the absence proof boundary before the tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Node errno codes abstract native filesystem error representation; the predicate classifies actual error meaning without an OS-name branch.
+     * @evidence contracts/performance.md#efficient-algorithms Two code comparisons require constant work and allocate no traversal state.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This classification does not coordinate a computation across requests.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate acquires and retains no resources.
+     */
+    function isMissingPathError(error) {
+        const code = error.code;
+        return code === "ENOENT" || code === "ENOTDIR";
+    }
+    PluginBuildLockProtocol.isMissingPathError = isMissingPathError;
+    /**
+     * Whether a native rename failure is treated as destination contention.
+     * EACCES/EPERM require an observed destination, but its existence does not
+     * prove it caused the failure; unrelated permissions can produce those
+     * codes.
+     *
+     * @evidence contracts/common.md#principled-implementation Explicit occupied-destination codes select contention; ambiguous permission codes select the same policy only with observed destination existence. That extra observation is a contention policy rather than a causal permission diagnosis.
+     * @evidence contracts/common.md#clear-and-simple-design One adapter distinguishes destination occupation from other rename failures for protocol initialization and observer publication.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Permission errors alone are not relabeled as a successful peer race, so unexpected failures remain visible.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the native-error classification and the existence observation's causal limit before the tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Node error codes plus an actual destination lookup represent Windows and POSIX rename outcomes through one boundary.
+     * @evidence contracts/performance.md#efficient-algorithms Fixed code comparisons perform at most one native destination existence lookup and no explicit parent scan; lookup costs include the destination path and native filesystem resolution.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Destination occupancy is observed at the failed operation and cannot be cached as a later ownership decision.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The adapter owns no retained handle or task.
+     */
+    function isRenameDestinationOccupied(error, destination) {
+        const code = error.code;
+        if (code === "EEXIST" || code === "ENOTEMPTY") {
+            return true;
+        }
+        return ((code === "EACCES" || code === "EPERM") && node_fs_1.default.existsSync(destination));
+    }
+    PluginBuildLockProtocol.isRenameDestinationOccupied = isRenameDestinationOccupied;
+    /**
+     * Read a captured legacy fence, or null when missing, unreadable or
+     * malformed.
+     *
+     * @evidence contracts/common.md#principled-implementation Validating a 128-bit generation and finite nonnegative mtime preserves the exact identity and age data required for a captured legacy fence.
+     * @evidence contracts/common.md#clear-and-simple-design The reader parses one record and leaves liveness classification and retirement to their owning operations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Invalid metadata remains unconfirmed rather than being coerced to an infinite age or a made-up generation.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes missing, unreadable and malformed records before the nullable reader's tags.
+     * @evidence contracts/portability.md#os-neutral-implementation path.join and Node UTF-8 reads use native paths while generation and millisecond mtime remain platform-independent protocol values.
+     * @evidence contracts/performance.md#efficient-algorithms A single JSON file read and parse costs time and temporary space proportional to that record's bytes.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A fence pathname may move with retirement or disappear, so the caller requires a fresh identity observation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous read returns data without retaining a descriptor or historical cache.
+     */
+    function readLegacyPluginBuildLockFence(fenceDir) {
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(fenceDir, PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_LEGACY_FENCE_RECORD), "utf8"));
+            if (!isPluginBuildLockGeneration(parsed.generation) ||
+                typeof parsed.legacyMtimeMs !== "number" ||
+                !Number.isFinite(parsed.legacyMtimeMs) ||
+                parsed.legacyMtimeMs < 0) {
+                return null;
+            }
+            return {
+                fence: { protocol: "legacy", generation: parsed.generation },
+                legacyMtimeMs: parsed.legacyMtimeMs,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    PluginBuildLockProtocol.readLegacyPluginBuildLockFence = readLegacyPluginBuildLockFence;
+    /**
+     * True for exactly 32 lowercase hexadecimal characters, the generation
+     * format.
+     *
+     * @evidence contracts/common.md#principled-implementation The anchored pattern admits exactly the 128-bit hexadecimal spelling produced by generation creation.
+     * @evidence contracts/common.md#clear-and-simple-design One type predicate centralizes token shape validation without choosing an owner or querying the filesystem.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The pattern is the protocol's explicit grammar rather than a list of expected generation values.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states exact length, case and digit vocabulary before the tags.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This is a pure protocol-string predicate with no native filesystem or process operation.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms A fixed-length anchored hexadecimal pattern avoids parsing arbitrary numeric values or allocating a decoded byte buffer.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Token shape checking coordinates no shared computation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate retains no state or acquired resource.
+     */
+    function isPluginBuildLockGeneration(value) {
+        return typeof value === "string" && /^[0-9a-f]{32}$/.test(value);
+    }
+    PluginBuildLockProtocol.isPluginBuildLockGeneration = isPluginBuildLockGeneration;
+    /**
+     * Block the synchronous thread for ms without polling the clock in a loop.
+     * Protocol callers supply a finite interval. This primitive imposes no
+     * overall retry budget; admission waiters manage one, while ordinary
+     * retirement can retry indefinitely. Scoped cancelled retirement applies its
+     * own between-attempt cleanup grace without interrupting this cleanup yield.
+     *
+     * @evidence contracts/common.md#principled-implementation Atomics.wait suspends the thread on an unchanged shared cell until its supplied timeout, providing the synchronous protocol yield.
+     * @evidence contracts/common.md#clear-and-simple-design The primitive waits once; callers own polling and whether an overall deadline exists.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A standard waiting primitive replaces busy-spinning without a host-specific command or invented completion signal.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states blocking behavior, protocol interval inputs and caller-owned admission/cleanup budgets, distinguishing ordinary retirement retries from scoped cancellation grace.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The JavaScript shared-memory wait performs no filesystem or process-launch boundary operation.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms One shared four-byte cell provides a single blocking wait without repeated clock reads or CPU polling.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Independent protocol waits are scheduling effects rather than reusable completed computation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call starts no timer task or retained worker; its temporary cell becomes collectible after the synchronous wait.
+     */
+    function sleepSync(ms) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    }
+    PluginBuildLockProtocol.sleepSync = sleepSync;
+})(PluginBuildLockProtocol || (exports.PluginBuildLockProtocol = PluginBuildLockProtocol = {}));
+//# sourceMappingURL=PluginBuildLockProtocol.js.map

package/lib/plugin/internal/source/PluginBuildLockProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginBuildLockProtocol.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/PluginBuildLockProtocol.ts"],"names":[],"mappings":"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"}

package/lib/plugin/internal/source/SourceBuildCacheLayout.d.ts

@@ -0,0 +1,183 @@
+import type { ITtscSourceBuildCachePaths } from "./ITtscSourceBuildCachePaths";
+/**
+ * The layout of ttsc's source-plugin cache and the file operations its
+ * maintenance shares.
+ *
+ * The default cache lives inside the workspace, at
+ * `<workspaceRoot>/node_modules/.cache/ttsc`, so removing `node_modules` (or
+ * the repository) reclaims the binaries and default Go objects stored there.
+ * Dedicated or caller-owned Go cache overrides can live elsewhere. This is the
+ * `find-cache-dir` convention (Babel, webpack, ESLint, Nuxt): a disposable
+ * build cache under `node_modules/.cache/<tool>`. ttsc keeps no automatic
+ * global (`~/.cache`) cache, because a machine-wide one would grow across tsgo
+ * and plugin version bumps without an owner to reclaim it. See
+ * `resolveSourceBuildCachePaths` for the override-then-workspace priority.
+ *
+ * @evidence contracts/common.md#principled-implementation Named cache parts separate compiled binaries, Go objects and serialized answers whose owners and retention policies differ.
+ * @evidence contracts/common.md#clear-and-simple-design Shared path names and metadata primitives live together; each collector retains its own selection policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Directory and marker names define the persisted layout, and filesystem mutations use owned entries rather than patching foreign APIs.
+ * @evidence contracts/common.md#meaningful-documentation Native prose locates the workspace cache and explains its disposable lifetime; public constant comments describe their payloads with separated members under the documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path construction, directory-entry inspection and atomic rename are delegated to Node APIs; layout names are protocol components rather than platform separators.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups separately owned operations; grouping itself does not run a traversal.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Layout names do not establish computation identity or validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace has no acquired state; its maintenance operations own reclamation decisions.
+ */
+export declare namespace SourceBuildCacheLayout {
+    /** Directory name the workspace-local cache is placed under. */
+    const NODE_MODULES_DIRNAME = "node_modules";
+    /** Directory name of ttsc's cache root below `node_modules/.cache`. */
+    const TTSC_CACHE_DIRNAME = "ttsc";
+    /** Directory name of ttsc's own Go object cache inside the cache root. */
+    const GO_BUILD_CACHE_DIRNAME = "go-build";
+    /** File inside a plugin cache entry recording when it was last used. */
+    const CACHE_LAST_USED_FILE = ".last-used";
+    /** Directory of the descriptor evaluation answers inside the cache root. */
+    const DESCRIPTOR_CACHE_DIRNAME = "descriptors";
+    /** Directory of the capability-resolution answers inside the cache root. */
+    const CAPABILITY_CACHE_DIRNAME = "capabilities";
+    /** Directory of the ttsx runtime inside the cache root. */
+    const RUNTIME_CACHE_DIRNAME = "ttsx";
+    /**
+     * Directory inside a runtime cache directory that holds one directory per
+     * prepared run, owned by the processes of that run.
+     */
+    const RUNTIME_PROJECT_DIRNAME = "project";
+    /** Directory of the lowered orphan sources inside the cache root. */
+    const ORPHAN_CACHE_DIRNAME = "ttsx-orphan";
+    /**
+     * The parts of the cache root whose entries are single files, each collected
+     * by `pruneCacheFileRoot` and removed by `ttsc clean`.
+     */
+    const CACHE_FILE_DIRNAMES: readonly string[];
+    /**
+     * Run the opportunistic pruning of the plugin cache, of ttsc's Go object
+     * cache, and of the single-file caches (`CACHE_FILE_DIRNAMES`), but only for
+     * the default workspace-local location. A root the caller named through
+     * `cacheDir` or `TTSC_CACHE_DIR` is theirs, and this opportunistic
+     * maintenance skips it. Explicit clean requests follow the separate cleanup
+     * contract.
+     *
+     * @evidence contracts/common.md#principled-implementation Pruning is admitted only for an unoverridden workspace root, and Go objects are admitted only when their provenance is ttsc-cache.
+     * @evidence contracts/common.md#clear-and-simple-design This ownership gate dispatches to dedicated binary, object and file collectors without duplicating their eviction policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Effective environment injection is a supported host boundary; explicit user-owned roots are deliberately protected.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain default-root ownership and why overrides suppress maintenance; prose and tags are visibly separated.
+     * @evidence contracts/portability.md#os-neutral-implementation The gate reads injected environment values with Windows case-insensitive names and uses path-aware collector APIs without separator assumptions.
+     * @evidence contracts/performance.md#efficient-algorithms A fixed ownership branch reads the injected environment; Windows name matching scans its keys and text. Admitted collectors additionally perform native metadata/ownership scans, optional entry sorts and recursive deletion, with path/text and retained-entry costs. Delegated ownership retries can lack a deadline; fixed dispatch count does not bound collector work.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This dispatch does not produce or validate a reusable computation result.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Default binary and answer collectors attempt opportunistic reclamation; explicit roots remain caller-owned. Live or unknown owners, protected entries, failures and future-invocation pacing can retain payloads or ownership records without a finite bound; this dispatch acquires no independent handle.
+     */
+    function maybePruneSourceBuildCaches(paths: ITtscSourceBuildCachePaths, cacheDir: string | undefined, env?: NodeJS.ProcessEnv): void;
+    /**
+     * Apply the opportunistic collector to each single-file part
+     * (`CACHE_FILE_DIRNAMES`) of `root`.
+     *
+     * @evidence contracts/common.md#principled-implementation Each declared answer-cache part receives the same single-file collector independently of binary and runtime directories; that owner decides interval admission, protection and tolerated deletion failure rather than this adapter guaranteeing reclamation.
+     * @evidence contracts/common.md#clear-and-simple-design One loop over the layout's fixed part list centralizes maintenance dispatch.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The part list is the persisted layout contract, not a list of recognized projects or expected answers.
+     * @evidence contracts/common.md#meaningful-documentation The native comment identifies the collected population and references the owning layout constant; tags follow a blank comment line.
+     * @evidence contracts/portability.md#os-neutral-implementation path.join constructs native children; directory checks and deletion policy stay in the collector.
+     * @evidence contracts/performance.md#efficient-algorithms Dispatch visits the fixed part list and constructs native child paths with work proportional to their text. Admitted collectors additionally pay their metadata/filename scans and optional entry sorts; payload population is not bounded by the part count.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A maintenance pass has filesystem effects and cannot be reused merely because it returns void.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Each serialized-answer population receives age/size reclamation, with recent-use protection and failed deletes explicitly allowed to defer reclamation.
+     */
+    function pruneCacheFiles(root: string): void;
+    /**
+     * Record that `root` was selected as a default workspace-local cache root.
+     *
+     * The marker keeps an intentionally empty `node_modules` authoritative after
+     * its first cache write changes its sole payload to `.cache/ttsc`. Creation
+     * is exclusive so concurrent first writers never follow or replace an
+     * existing filesystem entry. The selected root is pinned to its ordinary
+     * physical spelling before publication; default writers use that returned
+     * spelling for their payload too. Metadata checks do not hold a directory
+     * handle that prevents concurrent replacement of the selected path.
+     *
+     * @evidence contracts/common.md#principled-implementation Current ordinary-root metadata and physical spelling precede exclusive marker creation, recording the selected installation boundary. The producer uses the returned spelling; continued root identity requires that the path not be concurrently replaced, rather than a retained directory-handle proof.
+     * @evidence contracts/common.md#clear-and-simple-design Marker publication and existing-entry validation return one physical root for the caller's payload.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The marker represents an actual prior selection and is not fabricated workspace detection for particular consumers.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain first-write placement stability, current root validation and the path-replacement limit before exclusive marker publication.
+     * @evidence contracts/portability.md#os-neutral-implementation Native lstat/realpath observe ordinary-root identity and Node's wx creation refuses an existing marker without OS-based case assumptions; these calls do not freeze parent-directory identity.
+     * @evidence contracts/performance.md#efficient-algorithms Publication uses a fixed number of filesystem operations plus ordinary-root validation; recursive parent creation scales with missing path depth.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation persists installation provenance, not a computed answer whose inputs can be shared.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources At most one marker is retained per root and is reclaimed with that root; synchronous filesystem calls retain no open handle.
+     */
+    function markDefaultWorkspaceCacheRoot(root: string): string;
+    /**
+     * Report whether one collected directory listing is empty or has a marker.
+     *
+     * An empty root is the state after root creation and before marker
+     * publication. One listing avoids combining separate marker and emptiness
+     * probes; it does not freeze directory contents or prove later ownership.
+     *
+     * @evidence contracts/common.md#principled-implementation Emptiness and ordinary-marker admission use the same collected Dirent list, avoiding separate observations. The result is placement evidence at that read, not an atomic filesystem snapshot or continuing ownership guarantee.
+     * @evidence contracts/common.md#clear-and-simple-design Emptiness and marker recognition are derived from the same local array.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The marker is protocol provenance; no project name or fixture-specific filesystem shape is privileged.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains the concurrent publication interval that makes a single snapshot necessary.
+     * @evidence contracts/portability.md#os-neutral-implementation Dirent type checks reject a symbolic marker using native filesystem facts instead of platform labels.
+     * @evidence contracts/performance.md#efficient-algorithms One directory listing and linear marker search retain O(entries) references plus returned filename text; listing and equality costs include the visited names and native filesystem work, with no recursive payload traversal.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The current directory state is queried afresh because marker publication can change its answer.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This query retains no resource beyond its local directory snapshot.
+     */
+    function isEmptyOrMarkedDefaultWorkspaceCacheRoot(root: string): boolean;
+    /**
+     * Resolve the current default plugin cache to an ordinary physical spelling.
+     * Missing root directories are created. Returned spelling avoids following
+     * the caller's original ancestor alias again, but no retained directory
+     * handle prevents later replacement of the physical path.
+     *
+     * @evidence contracts/common.md#principled-implementation lstat rejects an aliased leaf and realpath checks the current root against its observed physical parent. The returned spelling removes the original ancestor alias from later lookups, subject to path identity remaining stable after these non-atomic metadata observations.
+     * @evidence contracts/common.md#clear-and-simple-design This boundary returns a physical spelling or throws; downstream collectors receive no partially validated path state.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Filesystem identity comes from actual entry types and realpath rather than special-cased path strings.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states creation, current physical spelling and the absence of a directory-handle identity pin; the inline comment explains avoidance of the original ancestor alias.
+     * @evidence contracts/portability.md#os-neutral-implementation Native realpath and lstat handle physical paths and links; textual equality here compares resolved parent spellings and does not infer volume case policy from an OS name.
+     * @evidence contracts/performance.md#efficient-algorithms A fixed number of metadata operations performs validation, with path resolution and recursive creation dependent on ancestor depth.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Mutable aliases are validated per invocation rather than memoized without an invalidation witness.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This operation returns a path and retains no handles or root history. Created directories belong to the selected cache owner; their lifetime and eviction remain with that caller's cache policy.
+     */
+    function canonicalPluginCacheRoot(root: string): string;
+    /**
+     * The millisecond timestamp a metadata file records, falling back to its
+     * mtime when content reading fails or trimmed content is empty or nonfinite.
+     * Returns `null` only when content supplies no timestamp and stat also fails.
+     * Numeric text uses JavaScript Number conversion, without an integer, range
+     * or decimal-only admission rule.
+     *
+     * @evidence contracts/common.md#principled-implementation Nonempty finite Number-convertible text supplies the timestamp; failed content reads, blank text and nonfinite values fall back to native mtime, and only failed stat after that absence yields null. This reader does not validate chronology or impose a numeric range.
+     * @evidence contracts/common.md#clear-and-simple-design Content parsing and metadata fallback are two explicit stages with one nullable result.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Number parsing observes actual stored metadata; no known timestamps or cache keys receive special treatment.
+     * @evidence contracts/common.md#meaningful-documentation Native documentation states timestamp units, the fallback and the unavailable outcome, separated from tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Node reads UTF-8 metadata and exposes mtimeMs consistently; no native date string or filesystem case convention is assumed.
+     * @evidence contracts/performance.md#efficient-algorithms The synchronous read decodes the complete metadata, then trimming and Number conversion inspect its text, with temporary storage proportional to read bytes/text and at most one fallback stat. Supplied path work and native reads are additional costs; the reader enforces no metadata-size cap.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current timestamps change on hits and maintenance, so this reader does not cache its answer.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous reads leave no retained handle or history.
+     */
+    function readTimestamp(file: string): number | null;
+    /**
+     * Replace cache metadata without following a pre-existing link or hard link.
+     *
+     * The caller supplies an owned, already selected parent directory. Replacing
+     * its terminal entry does not authorize writes through an arbitrary parent.
+     *
+     * @evidence contracts/common.md#principled-implementation An exclusive sibling staging file is renamed over the target entry, preserving complete publication and avoiding writes through the old inode's aliases.
+     * @evidence contracts/common.md#clear-and-simple-design Creation, publication and unconditional staging cleanup are contained in one try/finally.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Process identity and random bytes give independent sibling-name candidates, with exclusive creation refusing an occupied candidate; this is not a proof that names can never collide. Publication errors propagate rather than fabricate successful metadata.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish terminal-entry replacement from parent ownership, and inline prose explains why rename avoids alias mutation.
+     * @evidence contracts/portability.md#os-neutral-implementation Same-directory rename and exclusive creation use Node's native semantics; failure on locked Windows entries propagates to the owner's policy.
+     * @evidence contracts/performance.md#efficient-algorithms One contents write, one rename and one cleanup include supplied path/name and contents text work, plus fixed-size random sibling-name generation and native filesystem operations. The existing entry's contents are not copied.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each publication changes filesystem state and cannot be shared by equal return values.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Finally attempts removal of the staging candidate after success or failure, without retaining a handle or history. This assumes that independently chosen candidate belongs to this publication; cleanup errors can leave it for the owning cache collector, and no numeric bound on failed leftovers is established here.
+     */
+    function replaceCacheMetadataFile(file: string, contents: string): void;
+}