ttsc 0.30.4 → 0.31.1

package/lib/plugin/internal/readCapabilityResolution.js

@@ -0,0 +1,158 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCapabilityResolution = readCapabilityResolution;
+const node_fs_1 = __importDefault(require("node:fs"));
+const CapabilityResolutionFormat_1 = require("./CapabilityResolutionFormat");
+const hashHostInputPaths_1 = require("./load/hashHostInputPaths");
+const realpathHostInputPaths_1 = require("./load/realpathHostInputPaths");
+const pluginSourceFilesSignature_1 = require("./source/pluginSourceFilesSignature");
+const pluginSourceStateHolds_1 = require("./source/pluginSourceStateHolds");
+const recordCacheFileUse_1 = require("./source/recordCacheFileUse");
+/**
+ * Read the recorded answer for a project, or `null` when there is none that is
+ * still true.
+ *
+ * Fail-closed by construction: every path that cannot prove the entry — a
+ * missing file, a parse failure, a format bump, a moved input, a plugin source
+ * or build environment the binary was not keyed on, a binary that is gone —
+ * returns `null`, and `null` means "walk the project properly". A cache that
+ * guessed here would answer "no plugin declares this capability" for a project
+ * that had just configured one, which is a wrong answer indistinguishable from
+ * the correct answer for the common case.
+ *
+ * Proving a plugin source consults the process's environment observation;
+ * `pluginSourceStateHolds` refreshes that observation on mismatch. A hit avoids
+ * descriptor evaluation/discovery but still checks source/build state. Source
+ * bytes can be skipped only when a recorded digest, matching signature and
+ * fresh separability evidence are available; unavailable evidence also causes a
+ * content read, even without a known metadata change. These sequential checks
+ * rely on producer declarations and native metadata semantics. Binary presence
+ * is checked with existsSync, not a binary content hash or an
+ * executable-lifetime claim.
+ *
+ * @evidence contracts/common.md#principled-implementation Shape/version, both host-input snapshots, every plugin source's build state and binary presence must all hold before returning the recorded answer; any unproved premise yields null for real project discovery.
+ * @evidence contracts/common.md#clear-and-simple-design One reader owns entry acceptance while shared format, source-build proof and input-observation helpers own their distinct identities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An old executable's existence alone cannot prove current plugin behavior; malformed, raced or incompatible inputs cause normal discovery rather than guessed negative capability answers.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains fail-closed absence and which work a hit avoids versus still proves; private helpers explain metadata and bidirectional comparison premises, following the documentation skill's paragraph/tag separation.
+ * @evidence contracts/portability.md#os-neutral-implementation Native fs and shared path/realpath observers preserve input spelling/physical projections and query binary presence. Metadata acceleration requires matching device-clock witnesses without inferring precision or case from an OS name; binary contents are not independently identified here.
+ * @evidence contracts/performance.md#efficient-algorithms Full entry read/JSON/shape/map checks, host file hashes and realpaths precede source population/signature walks and binary presence queries. Signature reuse avoids source-content reads only under recorded digest/separation premises; other cases hash content, and mismatched state can refresh build environment. Delegated authority/root/executable observation, probe operations and path/key/numeric/record/file bytes contribute native work and transient storage.
+ * @evidence contracts/performance.md#reuse-equivalent-work One project/version entry can answer every capability while its recorded hash/physical/source-build projections pass the sequential checks. Metadata acceleration assumes native write/stamp semantics and producer completeness; unavailable observations refuse reuse, without claiming atomic or complete-world identity.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Parsed entry data transfers to the caller. Usage refresh and transient clock-probe removal are attempted by their owners and can skip/fail; default pruning has its own interval/protection/failure policy, while explicit roots remain caller-owned. This reader imposes no entry/input/output byte ceiling.
+ */
+function readCapabilityResolution(options) {
+    const file = CapabilityResolutionFormat_1.CapabilityResolutionFormat.resolutionFile(options);
+    if (file === null)
+        return null;
+    let entry;
+    try {
+        entry = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!isEntry(entry) ||
+        entry.version !== CapabilityResolutionFormat_1.CapabilityResolutionFormat.formatVersion(options.version))
+        return null;
+    // An entry recording nothing proves nothing. Discovery always reads at least
+    // the project's own manifest, so an empty input set is a malformed entry
+    // rather than a project with no inputs.
+    if (entry.hostInputs.length === 0)
+        return null;
+    if (!sameMap(entry.hostInputHashes, (0, hashHostInputPaths_1.hashHostInputPaths)(entry.hostInputs)) ||
+        !sameMap(entry.hostInputRealpaths, (0, realpathHostInputPaths_1.realpathHostInputPaths)(entry.hostInputs)))
+        return null;
+    // What each binary path was keyed on, proven by the build's own rule: a
+    // module root, linked package, or contributor that moved, or another build
+    // environment, names a binary the build would no longer produce, while the
+    // old one still exists.
+    const sources = Object.entries(entry.pluginSources);
+    const evidence = sources.some(([, source]) => source.signature !== undefined)
+        ? CapabilityResolutionFormat_1.CapabilityResolutionFormat.sourceEvidence(CapabilityResolutionFormat_1.CapabilityResolutionFormat.clockReference(file))
+        : undefined;
+    for (const [directory, source] of sources)
+        if (!pluginSourceProven(directory, source, evidence))
+            return null;
+    for (const plugin of entry.plugins)
+        if (!node_fs_1.default.existsSync(plugin.binary))
+            return null;
+    (0, recordCacheFileUse_1.recordCacheFileUse)(file);
+    return entry;
+}
+/**
+ * Whether a plugin source still holds its recorded state; unreadable is no.
+ *
+ * The recorded digest stands in for reading the files while their metadata
+ * signature is the recorded one and every stamp is separable from a reference
+ * minted now: after a clock rollback a write can land in a recorded stamp's
+ * tick, which only a fresh reference rules out. The build environment is proven
+ * either way.
+ */
+function pluginSourceProven(directory, source, evidence) {
+    try {
+        const now = source.signature === undefined || evidence === undefined
+            ? undefined
+            : (0, pluginSourceFilesSignature_1.pluginSourceFilesSignature)(directory, evidence);
+        return (0, pluginSourceStateHolds_1.pluginSourceStateHolds)(directory, source.state, now !== undefined &&
+            now.separable &&
+            now.signature === source.signature &&
+            source.digest !== undefined
+            ? { sourceDigest: source.digest }
+            : {});
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether the parsed value has every field the validation reads. */
+function isEntry(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const entry = value;
+    return (typeof entry.version === "string" &&
+        Array.isArray(entry.hostInputs) &&
+        entry.hostInputs.every((input) => typeof input === "string") &&
+        isRecord(entry.hostInputHashes) &&
+        isRecord(entry.hostInputRealpaths) &&
+        isRecord(entry.pluginSources) &&
+        Object.values(entry.pluginSources).every(isPluginSource) &&
+        typeof entry.manifest === "string" &&
+        (entry.projectContext === null ||
+            typeof entry.projectContext === "string") &&
+        Array.isArray(entry.plugins) &&
+        entry.plugins.every((plugin) => typeof plugin === "object" &&
+            plugin !== null &&
+            typeof plugin.binary === "string" &&
+            isRecord(plugin.capabilities)));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether a recorded plugin source has a state, and a digest with its signature
+ * or neither.
+ */
+function isPluginSource(value) {
+    if (!isRecord(value) || typeof value.state !== "string")
+        return false;
+    return value.digest === undefined && value.signature === undefined
+        ? true
+        : typeof value.digest === "string" && typeof value.signature === "string";
+}
+/**
+ * Whether two snapshots describe the same state.
+ *
+ * Compared both ways: an input that has appeared is as much a change as one
+ * that has moved, and a recorded key the fresh snapshot lacks means the two
+ * were taken over different input sets.
+ */
+function sameMap(recorded, current) {
+    const keys = Object.keys(recorded);
+    if (keys.length !== Object.keys(current).length)
+        return false;
+    return keys.every((key) => Object.prototype.hasOwnProperty.call(current, key) &&
+        recorded[key] === current[key]);
+}
+//# sourceMappingURL=readCapabilityResolution.js.map

package/lib/plugin/internal/readCapabilityResolution.js.map

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

package/lib/plugin/internal/receiveCapabilityFailure.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Receive a worker failure while preserving separately reported ownership loss.
+ *
+ * Only the worker's task-local cleanup ledger and original retirement promises
+ * authorize ownershipFailed. Ordinary discovery errors reject their caller but
+ * do not poison terminal cleanup. A marked failure remains in the parent's
+ * shutdown ledger even when that caller was already cancelled or ignores it.
+ *
+ * @evidence contracts/common.md#principled-implementation The worker's explicit ownership classification is retained independently of request rejection; ordinary discovery failure and native/resource cleanup failure remain distinct.
+ * @evidence contracts/common.md#clear-and-simple-design One receiver restores the existing serialized error representation and transfers marked failures to the supplied owner ledger before returning the same error.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Error names and message text do not guess cleanup status; a cleanup error named AbortError still retains failure authority.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the worker's classification authority and the parent shutdown consequence, including already cancelled callers.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This receiver handles structured worker messages and original error data without native process or filesystem operations.
+ * @evidence contracts/performance.md#efficient-algorithms Error restoration follows the serialized aggregate tree and property bytes; one marked result invokes one retention callback, whose cost belongs to its owner.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each worker reply is independent failure evidence rather than a reusable discovery result.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Returned and retained references identify the same restored error; the parent owns its shutdown ledger lifetime, and this receiver acquires no native resource.
+ */
+export declare function receiveCapabilityFailure(reply: {
+    thrown?: unknown;
+    ownershipFailed?: boolean;
+}, retain: (error: Error) => void): Error;

package/lib/plugin/internal/receiveCapabilityFailure.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.receiveCapabilityFailure = receiveCapabilityFailure;
+const restoreCompilerError_1 = require("../../internal/restoreCompilerError");
+/**
+ * Receive a worker failure while preserving separately reported ownership loss.
+ *
+ * Only the worker's task-local cleanup ledger and original retirement promises
+ * authorize ownershipFailed. Ordinary discovery errors reject their caller but
+ * do not poison terminal cleanup. A marked failure remains in the parent's
+ * shutdown ledger even when that caller was already cancelled or ignores it.
+ *
+ * @evidence contracts/common.md#principled-implementation The worker's explicit ownership classification is retained independently of request rejection; ordinary discovery failure and native/resource cleanup failure remain distinct.
+ * @evidence contracts/common.md#clear-and-simple-design One receiver restores the existing serialized error representation and transfers marked failures to the supplied owner ledger before returning the same error.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Error names and message text do not guess cleanup status; a cleanup error named AbortError still retains failure authority.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the worker's classification authority and the parent shutdown consequence, including already cancelled callers.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This receiver handles structured worker messages and original error data without native process or filesystem operations.
+ * @evidence contracts/performance.md#efficient-algorithms Error restoration follows the serialized aggregate tree and property bytes; one marked result invokes one retention callback, whose cost belongs to its owner.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each worker reply is independent failure evidence rather than a reusable discovery result.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Returned and retained references identify the same restored error; the parent owns its shutdown ledger lifetime, and this receiver acquires no native resource.
+ */
+function receiveCapabilityFailure(reply, retain) {
+    const error = (0, restoreCompilerError_1.restoreCompilerError)(reply.thrown);
+    if (reply.ownershipFailed === true)
+        retain(error);
+    return error;
+}
+//# sourceMappingURL=receiveCapabilityFailure.js.map

package/lib/plugin/internal/receiveCapabilityFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receiveCapabilityFailure.js","sourceRoot":"","sources":["../../../src/plugin/internal/receiveCapabilityFailure.ts"],"names":[],"mappings":";;;AAAA,8EAA2E;AAE3E;;;;;;;;;;;;;;;;GAgBG;AACH,kCACE,KAAsD,EACtD,MAA8B;IAE9B,MAAM,KAAK,GAAG,IAAA,2CAAoB,EAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACjD,IAAI,KAAK,CAAC,eAAe,KAAK,IAAI;QAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,KAAK,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,42 @@
+/**
+ * Default retention thresholds for plugin binaries (`prunePluginCacheRoot`) and
+ * single-file descriptor, capability and orphan-lowering answers
+ * (`pruneCacheFileRoot`).
+ *
+ * The caches are content-keyed, so a project that bumps tsgo or a plugin many
+ * times leaves one stale entry per superseded key. Eligible collections are
+ * normally spaced one day per part, attempt eviction after 30 unused days and,
+ * past a 2 GiB threshold, prune oldest entries toward 80% of it. Protected
+ * entries, live or uncertain owners and failed deletions can defer eviction
+ * without a finite size or age bound. An over-budget marker makes a retry
+ * eligible after the protection window; collection still depends on a later
+ * invocation. Collectors stay within their selected cache part rather than
+ * discovering global cache locations. The Go object cache has its own policy in
+ * `pruneGoBuildCacheRoot`.
+ *
+ * @evidence contracts/common.md#principled-implementation Age, size and protection thresholds describe reclaimable cache storage, not the semantic validity of an answer.
+ * @evidence contracts/common.md#clear-and-simple-design One policy namespace keeps binary and single-file collectors on the same units and defaults.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The durations, byte budgets and marker spelling are product retention policy, not consumer-specific answers.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes thresholds from hard bounds and explains retry behavior; documented constants are separated by blank lines under the documentation guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This namespace defines eligibility thresholds and retry pacing but owns no cache storage or eviction task; the collectors own protection, failed deletion and historical coordination-state lifetimes, with no guaranteed size or age bound.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace holds constants and implements no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace holds constants only, so it has no computation to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Defines durations, byte budgets and a marker file name only; no path is built or resolved in this namespace.
+ */
+export declare namespace CachePrunePolicy {
+    /**
+     * Normal interval between successful collections; over-budget retries can be
+     * earlier.
+     */
+    const GC_INTERVAL_MS: number;
+    /** Unused age after which an entry is eligible for collection. */
+    const ENTRY_MAX_AGE_MS: number;
+    /** Size of one part that triggers least-recently-used eviction. */
+    const MAX_BYTES: number;
+    /** Size least-recently-used eviction prunes toward. */
+    const TARGET_BYTES: number;
+    /** Recent-use window considered by each collector's protection policy. */
+    const PROTECTED_AGE_MS: number;
+    /** Name of the file recording when a part was last collected. */
+    const GC_MARKER_FILE = ".gc-last-run";
+}

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachePrunePolicy = void 0;
+/**
+ * Default retention thresholds for plugin binaries (`prunePluginCacheRoot`) and
+ * single-file descriptor, capability and orphan-lowering answers
+ * (`pruneCacheFileRoot`).
+ *
+ * The caches are content-keyed, so a project that bumps tsgo or a plugin many
+ * times leaves one stale entry per superseded key. Eligible collections are
+ * normally spaced one day per part, attempt eviction after 30 unused days and,
+ * past a 2 GiB threshold, prune oldest entries toward 80% of it. Protected
+ * entries, live or uncertain owners and failed deletions can defer eviction
+ * without a finite size or age bound. An over-budget marker makes a retry
+ * eligible after the protection window; collection still depends on a later
+ * invocation. Collectors stay within their selected cache part rather than
+ * discovering global cache locations. The Go object cache has its own policy in
+ * `pruneGoBuildCacheRoot`.
+ *
+ * @evidence contracts/common.md#principled-implementation Age, size and protection thresholds describe reclaimable cache storage, not the semantic validity of an answer.
+ * @evidence contracts/common.md#clear-and-simple-design One policy namespace keeps binary and single-file collectors on the same units and defaults.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The durations, byte budgets and marker spelling are product retention policy, not consumer-specific answers.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes thresholds from hard bounds and explains retry behavior; documented constants are separated by blank lines under the documentation guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This namespace defines eligibility thresholds and retry pacing but owns no cache storage or eviction task; the collectors own protection, failed deletion and historical coordination-state lifetimes, with no guaranteed size or age bound.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace holds constants and implements no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace holds constants only, so it has no computation to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Defines durations, byte budgets and a marker file name only; no path is built or resolved in this namespace.
+ */
+var CachePrunePolicy;
+(function (CachePrunePolicy) {
+    /**
+     * Normal interval between successful collections; over-budget retries can be
+     * earlier.
+     */
+    CachePrunePolicy.GC_INTERVAL_MS = 24 * 60 * 60 * 1000;
+    /** Unused age after which an entry is eligible for collection. */
+    CachePrunePolicy.ENTRY_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+    /** Size of one part that triggers least-recently-used eviction. */
+    CachePrunePolicy.MAX_BYTES = 2 * 1024 * 1024 * 1024;
+    /** Size least-recently-used eviction prunes toward. */
+    CachePrunePolicy.TARGET_BYTES = Math.floor(CachePrunePolicy.MAX_BYTES * 0.8);
+    /** Recent-use window considered by each collector's protection policy. */
+    CachePrunePolicy.PROTECTED_AGE_MS = 60 * 60 * 1000;
+    /** Name of the file recording when a part was last collected. */
+    CachePrunePolicy.GC_MARKER_FILE = ".gc-last-run";
+})(CachePrunePolicy || (exports.CachePrunePolicy = CachePrunePolicy = {}));
+//# sourceMappingURL=CachePrunePolicy.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CachePrunePolicy.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/CachePrunePolicy.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,IAAiB,gBAAgB,CAqBhC;AArBD,WAAiB,gBAAgB;IAC/B;;;OAGG;IACU,+BAAc,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAElD,kEAAkE;IACrD,iCAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAEzD,mEAAmE;IACtD,0BAAS,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAEhD,uDAAuD;IAC1C,6BAAY,GAAG,IAAI,CAAC,KAAK,CAAC,0BAAS,GAAG,GAAG,CAAC,CAAC;IAExD,0EAA0E;IAC7D,iCAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE/C,iEAAiE;IACpD,+BAAc,GAAG,cAAc,CAAC;AAC/C,CAAC,EArBgB,gBAAgB,aAAhB,gBAAgB,GAAhB,gBAAgB,QAqBhC"}

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

@@ -0,0 +1,159 @@
+/**
+ * Coordination between Go builds that use ttsc's own Go object cache and the
+ * opportunistic pruning of that cache.
+ *
+ * Coordinated build and admitted maintenance attempts publish records in
+ * private cache directories and attempt heartbeat startup. Pruning skips the
+ * cohort a live build may still read, and an abandoned record expires after a
+ * grace period (one hour for builds, one minute for maintenance). Byte-read
+ * failure still permits age-based expiry when metadata is readable; unknown age
+ * or failed clock-skew repair defers pruning conservatively. This is
+ * opportunistic coordination rather than an absolute proof that every abandoned
+ * record can be reclaimed.
+ *
+ * Scoped native boundaries add independent guards: their exact build leases
+ * survive age/PID-based collection until qualified closure. Shared cache guards
+ * prevent eviction and clean without serializing independent builders.
+ * Maintenance freshness remains separate so an old maintenance record cannot
+ * block concurrent builds indefinitely under an unrelated native guard.
+ *
+ * Age-based expiry for unguarded records assumes a running task can keep its
+ * heartbeat fresh. A prolonged suspension or failed heartbeat after startup can
+ * outlast the grace; elapsed time alone does not prove that its Go process has
+ * ended.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact scoped native guards supersede build-lease expiry until certified closure while shared Go admission remains concurrent. Published completion and refreshed mtimes implement task policy: build grace is one hour and maintenance grace one minute. Unknown metadata age defers pruning, while unreadable bytes can still expire by observed age; grace expiry is not process-absence proof after heartbeat failure.
+ * @evidence contracts/common.md#clear-and-simple-design Root validation, task publication and collection form one coordination boundary used by builders and maintenance.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Time windows are documented coordination policy; worker/process alternatives address actual synchronous-build and native spawn constraints rather than known fixtures.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains lease purpose and conservative unreadable/clock-skew limits; function and member comments describe release and startup outcomes.
+ * @evidence contracts/portability.md#os-neutral-implementation Native filesystem metadata and Node worker/process APIs provide the boundary without assuming an OS's case policy.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups member-owned processing strategies and performs no scan itself.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Namespace membership establishes no computed-result identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Actual records and workers are owned by create/finish operations rather than the namespace declaration.
+ */
+export declare namespace GoBuildCacheCoordination {
+    /** Directory of the cache holding one record per running Go build. */
+    const GO_BUILD_CACHE_LEASE_DIR = ".ttsc-build-leases";
+    /** Directory of the cache holding one record per running maintenance pass. */
+    const GO_BUILD_CACHE_MAINTENANCE_DIR = ".ttsc-maintenance";
+    /**
+     * Create the owned Go cache and return its observed physical directory
+     * spelling.
+     *
+     * The leaf may be user-controlled inside `node_modules/.cache`; accepting a
+     * symlink or junction there would let LRU deletion escape into an arbitrary
+     * two-hex directory. Returning the canonical spelling also keeps the build,
+     * leases, and maintenance address that spelling if an ancestor alias moves.
+     * These sequential observations do not retain a directory handle or prevent
+     * later physical-path replacement.
+     *
+     * @evidence contracts/common.md#principled-implementation lstat rejects aliased leaves and physical parent validation confines the returned Go root to its resolved parent before deletion or builds use it.
+     * @evidence contracts/common.md#clear-and-simple-design Validation returns one physical spelling or throws, so consumers do not carry partially safe paths.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Native filesystem facts establish ownership boundaries, not guessed cache names or foreign API mutation.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain project-controlled leaf risk, ancestor-alias spelling resolution and the absence of a retained directory handle.
+     * @evidence contracts/portability.md#os-neutral-implementation Native realpath/lstat preserve actual identity; no Windows-name check supplies volume case semantics.
+     * @evidence contracts/performance.md#efficient-algorithms Fixed metadata calls validate the leaf; path resolution and recursive creation scale with ancestor depth.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Mutable aliases are checked per operation rather than cached without an invalidation witness.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Validation opens no persistent handle and owns no cache entries.
+     */
+    function canonicalGoBuildCacheRoot(root: string): string;
+    /**
+     * One published build or maintenance record, owned by this process.
+     *
+     * @evidence contracts/common.md#principled-implementation Record identity and lifecycle callbacks represent the same owned task; completion cannot be mistaken for another task's lease.
+     * @evidence contracts/common.md#clear-and-simple-design The interface exposes only its published path, startup and terminal release.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The callbacks are explicit ownership operations, not mutation of external worker APIs.
+     * @evidence contracts/common.md#meaningful-documentation Member prose explains terminal completion, startup failure and synchronous-build purpose with blank-separated fields.
+     * @evidence contracts/portability.md#os-neutral-implementation The path denotes a native coordination file while callbacks hide worker versus process startup differences.
+     *
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This interface declares an ownership capability and chooses no algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The interface is not a computed-result coordinator.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Actual acquisition and release are performed by the factory and callbacks, not this type declaration.
+     */
+    interface GoBuildCacheCoordinationRecord {
+        /** Path of the record file. */
+        file: string;
+        /**
+         * Request heartbeat shutdown, attempt to mark the record complete, then
+         * attempt deletion. Synchronous finish does not join shutdown; an explicit
+         * worker scope tracks actual exit/close and termination failures for its
+         * asynchronous owner to join. Ordinary failures may leave a task or file. A
+         * successful completion write prevents a failed delete from leaving the
+         * task active; if both writes and deletion fail, stale-timeout handling
+         * remains the collector's fallback.
+         *
+         * @evidence contracts/common.md#principled-implementation The terminal callback requests refresher shutdown and attempts complete-state publication before removal; only successful publication records completion if deletion fails, and actual termination remains tracked for an opted-in asynchronous owner rather than joined by this synchronous callback.
+         * @evidence contracts/common.md#clear-and-simple-design Release is one idempotent operation and prevents later heartbeat restart.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts Completion persistence addresses a real failed-unlink state rather than simulating successful cleanup.
+         * @evidence contracts/common.md#meaningful-documentation Native prose states ordering and its failure consequence, separated from tags.
+         * @evidence contracts/portability.md#os-neutral-implementation Native worker termination and file removal failures are encapsulated by the owning callback.
+         * @evidence contracts/performance.md#efficient-algorithms Release performs task-control and guard metadata checks before atomic record cleanup, without scanning cache object contents; costs include stored path and host/PID metadata bytes and native filesystem resolution.
+         *
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work This callback closes one owned task, not a reusable computation.
+         *
+         * @evidence contracts/performance.md#bound-retention-and-release-resources Finish requests worker termination or child kill, then attempts completion publication/removal only when native closure permits it; unresolved boundaries retain the exact lease and original cleanup callback until qualified recovery. Opted-in scope owners join tracked exit/close and receive termination failures; ordinary synchronous callers do not join. Failed removal is marked complete only if publication succeeds; otherwise age/uncertainty policy may retain the record, and terminal state prevents another cleanup attempt through this capability.
+         */
+        finish: () => void;
+        /**
+         * Keep the record fresh from a background refresher while this thread
+         * blocks in a synchronous build. Successful startup is reused; failed
+         * startup can be attempted again. Returns `false` when no mechanism could
+         * initialize during readiness checks (the record then relies on age
+         * policy). Repeated calls reuse the startup-acknowledged capability without
+         * proving the refresher is still healthy. Finished records cannot be
+         * restarted. Explicit worker scopes keep attempted refreshers referenced
+         * until actual exit/close is joined by their asynchronous owner; ordinary
+         * callers retain the unreferenced synchronous behavior.
+         *
+         * @evidence contracts/common.md#principled-implementation Initialization acknowledgement is required before the callback reports an independently refreshing task; a completed record has no restart capability.
+         * @evidence contracts/common.md#clear-and-simple-design Lazy initialization stores one acknowledged refresher capability per unfinished record, separately from terminal finish state.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts Worker and low-descriptor child paths support actual runtime capability differences, not fixture-specific outcomes.
+         * @evidence contracts/common.md#meaningful-documentation Native prose names synchronous-build purpose, acknowledged-capability reuse, retryable initialization failure and terminal-state behavior.
+         * @evidence contracts/portability.md#os-neutral-implementation Node workers or the current Node executable provide native background work without shell command quoting.
+         * @evidence contracts/performance.md#efficient-algorithms Repeated starts reuse the stored startup-acknowledged capability. First startup attempts a worker and, if unavailable, a Node child; timed readiness waits have a grace per mechanism, while construction/native file observations add their own duration. Child script/argument bytes and readiness-path checks contribute to startup cost.
+         *
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work Reusing a heartbeat capability is lifecycle ownership, not equivalent build-result reuse.
+         *
+         * @evidence contracts/performance.md#bound-retention-and-release-resources One successful refresher capability is stored per record; failed worker termination may overlap child fallback. Startup/finish track actual worker exit, termination requests and child close for an opted-in owner to join; ordinary synchronous callers do not join, and ready-file deletion is best-effort. A later failed refresher is not recreated by repeating start; record expiry follows the declared freshness policy.
+         */
+        startHeartbeat: () => boolean;
+    }
+    /**
+     * Publish an `active` record for this process in the coordination directory
+     * `directoryName` of the cache at `root`.
+     *
+     * @evidence contracts/common.md#principled-implementation A random process-qualified record distinguishes concurrent tasks, atomic metadata publishes active/complete states and terminal finish prevents restart.
+     * @evidence contracts/common.md#clear-and-simple-design Returned callbacks close over exactly one record, heartbeat and terminal flag rather than a global task registry.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Random uniqueness and completion-before-unlink address real concurrent publication and cleanup failures; no consumer identity is privileged.
+     * @evidence contracts/common.md#meaningful-documentation Native type/member comments describe ownership and release semantics while the factory identifies the publication location.
+     * @evidence contracts/portability.md#os-neutral-implementation Native path, hostname and atomic entry publication identify the local task without assuming PID meaning on another host.
+     * @evidence contracts/performance.md#efficient-algorithms Publication validates native coordination paths and atomically writes one host/PID/status record, with path/JSON-byte costs. Startup is lazy and shares the stored capability; it includes worker construction or child launch/readiness observations rather than just record writes.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A task lease is not a cached build answer; producer identity and lock sharing belong to the build owner.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller receives one record and lazy refresher capability and must call finish after its synchronous task. Termination and actual exit/close are tracked for opted-in owners to join after synchronous work; ordinary callers request termination without joining. Failed startup can overlap fallback; scoped unknown native closure retains the exact lease without age expiry, while unguarded failed completion/removal follows age/uncertainty policy. This factory imposes no cross-task population bound.
+     */
+    function createGoBuildCacheCoordinationRecord(root: string, directoryName: string): GoBuildCacheCoordinationRecord;
+    /**
+     * The live records of one coordination directory at `now`. Completed and
+     * age-policy-stale records have deletion attempted; inaccessible metadata is
+     * retained when its age cannot be established safely. Exact native-guarded
+     * build generations are retained independently of status and age. Maintenance
+     * records retain their ordinary freshness policy so unrelated guards cannot
+     * block independent shared-cache builds indefinitely.
+     *
+     * @evidence contracts/common.md#principled-implementation Exact native-guarded build generations override status and age; for unguarded records complete status overrides age, and stale ordinary records have removal attempted. Unknown metadata age or far-future clock observations preserve possible work, while unreadable content alone does not prevent age-based expiry.
+     * @evidence contracts/common.md#clear-and-simple-design One snapshot feeds a liveness helper and best-effort removal, returning only the protected paths.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts PID lifetime is not substituted for task lifetime; actual task status and heartbeat age drive selection.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes completed/stale reclamation from inaccessible metadata retention.
+     * @evidence contracts/portability.md#os-neutral-implementation Native Dirents select ordinary files and sequential lstat/realpath checks validate the coordination directory's observed spelling; no directory handle prevents later replacement.
+     * @evidence contracts/performance.md#efficient-algorithms One native-guard snapshot and generation Set membership avoid repeating a guard scan for each lease; one coordination listing and per-selected-record JSON/mtime reads scale with guard and record counts, path strings and metadata bytes, with arrays retaining entry/path text. Future-clock rebasing can add atomic metadata writes, and stale/complete cleanup adds native removals; directory validation adds native resolution without scanning unrelated cache payloads.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Liveness is time-sensitive and filesystem-mutating collection is not memoized.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Unguarded completed and stale records are reclaimed; exact native guards retain build records until qualified closure without age expiry. Unknown metadata or failed deletion can also retain records beyond ordinary grace.
+     */
+    function collectLiveGoBuildCacheCoordinationRecords(root: string, directoryName: string, now: number): string[];
+}