ttsc 0.30.3 → 0.31.0

package/lib/internal/retireLockDirectory.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retireLockDirectory = retireLockDirectory;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const OwnedSynchronousProcess_1 = require("./OwnedSynchronousProcess");
+/**
+ * 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.
+ */
+function retireLockDirectory(source, destination, yieldToPeers, operations = FILESYSTEM_OPERATIONS) {
+    let cancelledAt;
+    try {
+        for (;;) {
+            try {
+                operations.renameSync(source, destination);
+                return true;
+            }
+            catch (error) {
+                if (isMissingPath(error) || isOccupied(error, destination, operations))
+                    return false;
+                if (!isHeldByPeer(error, source, destination, operations))
+                    throw error;
+                if (OwnedSynchronousProcess_1.OwnedSynchronousProcess.cancelled()) {
+                    cancelledAt ??= performance.now();
+                    if (performance.now() - cancelledAt >= CANCELLED_CLEANUP_GRACE_MS)
+                        throw new Error(`ttsc: unable to retire lock generation ${source} after ` +
+                            `${CANCELLED_CLEANUP_GRACE_MS}ms of cancelled cleanup contention`, { cause: error });
+                }
+            }
+            yieldToPeers();
+        }
+    }
+    catch (error) {
+        if (OwnedSynchronousProcess_1.OwnedSynchronousProcess.cancelled())
+            OwnedSynchronousProcess_1.OwnedSynchronousProcess.reportFailure(error);
+        throw error;
+    }
+}
+const CANCELLED_CLEANUP_GRACE_MS = 1_000;
+function isMissingPath(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+ * Whether a failed rename means the destination already exists. Windows reports
+ * an occupied directory destination as `EACCES` or `EPERM`, so those count only
+ * when the destination is actually present.
+ */
+function isOccupied(error, destination, operations) {
+    const code = error.code;
+    if (code === "EEXIST" || code === "ENOTEMPTY")
+        return true;
+    return ((code === "EACCES" || code === "EPERM") &&
+        operations.existsSync(destination));
+}
+/**
+ * Whether this refusal qualifies for retry after a successful sibling probe.
+ * The result does not identify a peer or exclude source-specific restrictions.
+ */
+function isHeldByPeer(error, source, destination, operations) {
+    if (operations.platform !== "win32")
+        return false;
+    const code = error.code;
+    if (code !== "EPERM" && code !== "EACCES" && code !== "EBUSY")
+        return false;
+    if (!operations.existsSync(source))
+        return false;
+    const nonce = node_crypto_1.default.randomBytes(8).toString("hex");
+    const probe = `${source}.probe-${nonce}`;
+    const moved = `${destination}.probe-${nonce}`;
+    try {
+        operations.mkdirSync(probe);
+    }
+    catch {
+        return false;
+    }
+    try {
+        operations.renameSync(probe, moved);
+    }
+    catch {
+        removeProbe(probe, operations);
+        return false;
+    }
+    removeProbe(moved, operations);
+    return true;
+}
+/**
+ * Remove a probe directory without letting its removal decide the retry. The
+ * probe records whether its sampled sibling rename succeeded, so a transient
+ * refusal to delete the empty directory (an indexer or scanner holding it on
+ * Windows) leaves that directory behind rather than turning an eligible retry
+ * into a thrown failure.
+ */
+function removeProbe(directory, operations) {
+    try {
+        operations.rmSync(directory, { force: true, recursive: true });
+    }
+    catch {
+        // The probe is an empty sibling of the lock; its answer is already known.
+    }
+}
+const FILESYSTEM_OPERATIONS = {
+    renameSync: node_fs_1.default.renameSync,
+    mkdirSync: (location) => node_fs_1.default.mkdirSync(location),
+    rmSync: node_fs_1.default.rmSync,
+    existsSync: node_fs_1.default.existsSync,
+    platform: process.platform,
+};
+//# sourceMappingURL=retireLockDirectory.js.map

package/lib/internal/retireLockDirectory.js.map

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

package/lib/internal/runHoldingLock.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Run the work a held build lock protects, then release the lock without
+ * letting the release replace the work's outcome.
+ *
+ * A release that throws from a `finally` block replaced whatever the work
+ * produced: a build that had published its binary failed, and a build that had
+ * failed reported the release's error instead of its own. The work's value is
+ * returned and its error is thrown as they were. A release that still fails
+ * goes to `onReleaseFailure`. This adapter does not establish whether release
+ * completed; the caller's lock protocol owns any later abandoned-generation
+ * recovery.
+ *
+ * @param work Synchronous work under the lock. Returning a Promise does not
+ *   extend lock ownership until that Promise settles.
+ * @param release Frees the lock.
+ * @param onReleaseFailure Receives a release's error, which it must not throw.
+ * @returns What `work` returned.
+ * @throws What `work` threw.
+ * @evidence contracts/common.md#principled-implementation Both synchronous success and failure attempt release before preserving the original outcome; the release reporter must not throw, and asynchronous work is outside this lock-lifetime contract.
+ * @evidence contracts/common.md#clear-and-simple-design One outcome branch and a shared release-reporting helper expose the ownership transition without wrapping successful results in another protocol.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Real release failures are reported rather than converted into a fabricated build failure or success; no foreign release method is replaced.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain outcome preservation and abandoned-generation recovery; parameter prose makes synchronous ownership and the nonthrowing reporter premise explicit.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This adapter sequences one opaque synchronous work callback and one release; the computation strategy belongs to their owners.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Executing held work and releasing a lock are effectful ownership transitions and cannot be shared by matching callback identities.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The caller transfers a held lock for the synchronous callback lifetime; release is attempted on either outcome, and an unconfirmed release leaves recovery to the caller's lock-generation protocol rather than certifying that ownership ended.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This adapter preserves opaque callback outcomes and sequences release/reporting without interpreting a native path or error code; the supplied lock callbacks own filesystem identity, platform refusals and recovery.
+ */
+export declare function runHoldingLock<T>(work: () => T, release: () => void, onReleaseFailure: (error: unknown) => void): T;

package/lib/internal/runHoldingLock.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHoldingLock = runHoldingLock;
+/**
+ * Run the work a held build lock protects, then release the lock without
+ * letting the release replace the work's outcome.
+ *
+ * A release that throws from a `finally` block replaced whatever the work
+ * produced: a build that had published its binary failed, and a build that had
+ * failed reported the release's error instead of its own. The work's value is
+ * returned and its error is thrown as they were. A release that still fails
+ * goes to `onReleaseFailure`. This adapter does not establish whether release
+ * completed; the caller's lock protocol owns any later abandoned-generation
+ * recovery.
+ *
+ * @param work Synchronous work under the lock. Returning a Promise does not
+ *   extend lock ownership until that Promise settles.
+ * @param release Frees the lock.
+ * @param onReleaseFailure Receives a release's error, which it must not throw.
+ * @returns What `work` returned.
+ * @throws What `work` threw.
+ * @evidence contracts/common.md#principled-implementation Both synchronous success and failure attempt release before preserving the original outcome; the release reporter must not throw, and asynchronous work is outside this lock-lifetime contract.
+ * @evidence contracts/common.md#clear-and-simple-design One outcome branch and a shared release-reporting helper expose the ownership transition without wrapping successful results in another protocol.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Real release failures are reported rather than converted into a fabricated build failure or success; no foreign release method is replaced.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain outcome preservation and abandoned-generation recovery; parameter prose makes synchronous ownership and the nonthrowing reporter premise explicit.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This adapter sequences one opaque synchronous work callback and one release; the computation strategy belongs to their owners.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Executing held work and releasing a lock are effectful ownership transitions and cannot be shared by matching callback identities.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The caller transfers a held lock for the synchronous callback lifetime; release is attempted on either outcome, and an unconfirmed release leaves recovery to the caller's lock-generation protocol rather than certifying that ownership ended.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This adapter preserves opaque callback outcomes and sequences release/reporting without interpreting a native path or error code; the supplied lock callbacks own filesystem identity, platform refusals and recovery.
+ */
+function runHoldingLock(work, release, onReleaseFailure) {
+    let result;
+    try {
+        result = work();
+    }
+    catch (error) {
+        releaseReporting(release, onReleaseFailure);
+        throw error;
+    }
+    releaseReporting(release, onReleaseFailure);
+    return result;
+}
+function releaseReporting(release, onReleaseFailure) {
+    try {
+        release();
+    }
+    catch (error) {
+        onReleaseFailure(error);
+    }
+}
+//# sourceMappingURL=runHoldingLock.js.map

package/lib/internal/runHoldingLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runHoldingLock.js","sourceRoot":"","sources":["../../src/internal/runHoldingLock.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBACE,IAAa,EACb,OAAmB,EACnB,gBAA0C;IAE1C,IAAI,MAAS,CAAC;IACd,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,EAAE,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;QAC5C,MAAM,KAAK,CAAC;IACd,CAAC;IACD,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IAC5C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,gBAAgB,CACvB,OAAmB,EACnB,gBAA0C;IAE1C,IAAI,CAAC;QACH,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/lib/internal/runtimeExecutableIdentity.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Fingerprint an absolute executable's spelling, target and actual bytes.
+ *
+ * A changed link, file, or read failure yields no reusable identity. Metadata
+ * brackets the streamed read; it is not used to reuse an earlier content hash.
+ * Concurrent writes that evade every filesystem observation remain outside this
+ * snapshot guarantee.
+ *
+ * @evidence contracts/common.md#principled-implementation The identity joins lexical-link metadata, the selected physical file metadata and SHA-256 of that opened file; matching metadata alone cannot authorize reuse after bytes change. Descriptor and pathname observations must still agree after reading.
+ * @evidence contracts/common.md#clear-and-simple-design This one native owner supplies the same content proof to runtime capability and plugin caches; callers decide whether their other inputs permit reuse.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported Node filesystem and crypto APIs inspect the actual candidate; no fixture identity, foreign mutation or metadata-only shortcut substitutes for content.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains absolute-path scope, failure meaning, hash freshness and the remaining concurrent-mutation limitation, with separate prose and tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native realpath and bigint stat preserve link/target identity on supported hosts; absolute paths use native platform semantics, and unreadable or non-regular targets cannot be reused.
+ * @evidence contracts/performance.md#efficient-algorithms A sequential read hashes B bytes with one 64 KiB buffer instead of a complete executable allocation. Native path/realpath/stat observations and serialized physical spelling/metadata add text/lookup costs; B and spelling lengths have no quota here. Returned identity storage includes the physical path as well as the fixed-length digest.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation establishes whether later work is equivalent; retaining a digest by metadata would reproduce the stale-byte defect it must prevent.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One descriptor and one fixed buffer belong to this synchronous call; finally attempts closure after read/observation failures as well as success. A close failure returns no identity but cannot confirm native release. Returned path/metadata/digest text transfers to the caller and no helper history survives. Opt-in opened/closed/close-failed observations carry one trace-only call id and actual descriptor, PID/thread and already observed physical identity. The existing finally performs the single close; no observer retries it or converts an unavailable identity to success. An observed close is release of this Node descriptor, not proof that an OS image lock or another actor has released the executable.
+ */
+export declare function runtimeExecutableIdentity(runtime: string): string | undefined;

package/lib/internal/runtimeExecutableIdentity.js

@@ -0,0 +1,171 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeExecutableIdentity = runtimeExecutableIdentity;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_worker_threads_1 = require("node:worker_threads");
+const E2ETrace_1 = require("./E2ETrace");
+/**
+ * Fingerprint an absolute executable's spelling, target and actual bytes.
+ *
+ * A changed link, file, or read failure yields no reusable identity. Metadata
+ * brackets the streamed read; it is not used to reuse an earlier content hash.
+ * Concurrent writes that evade every filesystem observation remain outside this
+ * snapshot guarantee.
+ *
+ * @evidence contracts/common.md#principled-implementation The identity joins lexical-link metadata, the selected physical file metadata and SHA-256 of that opened file; matching metadata alone cannot authorize reuse after bytes change. Descriptor and pathname observations must still agree after reading.
+ * @evidence contracts/common.md#clear-and-simple-design This one native owner supplies the same content proof to runtime capability and plugin caches; callers decide whether their other inputs permit reuse.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported Node filesystem and crypto APIs inspect the actual candidate; no fixture identity, foreign mutation or metadata-only shortcut substitutes for content.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains absolute-path scope, failure meaning, hash freshness and the remaining concurrent-mutation limitation, with separate prose and tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native realpath and bigint stat preserve link/target identity on supported hosts; absolute paths use native platform semantics, and unreadable or non-regular targets cannot be reused.
+ * @evidence contracts/performance.md#efficient-algorithms A sequential read hashes B bytes with one 64 KiB buffer instead of a complete executable allocation. Native path/realpath/stat observations and serialized physical spelling/metadata add text/lookup costs; B and spelling lengths have no quota here. Returned identity storage includes the physical path as well as the fixed-length digest.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation establishes whether later work is equivalent; retaining a digest by metadata would reproduce the stale-byte defect it must prevent.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One descriptor and one fixed buffer belong to this synchronous call; finally attempts closure after read/observation failures as well as success. A close failure returns no identity but cannot confirm native release. Returned path/metadata/digest text transfers to the caller and no helper history survives. Opt-in opened/closed/close-failed observations carry one trace-only call id and actual descriptor, PID/thread and already observed physical identity. The existing finally performs the single close; no observer retries it or converts an unavailable identity to success. An observed close is release of this Node descriptor, not proof that an OS image lock or another actor has released the executable.
+ */
+function runtimeExecutableIdentity(runtime) {
+    if (!node_path_1.default.isAbsolute(runtime))
+        return undefined;
+    const startedAt = new Date().toISOString();
+    let descriptor;
+    let traceLease;
+    let stage = "lexical-stat";
+    const unavailable = (reason, expected, observed, observations) => {
+        E2ETrace_1.E2ETrace.capabilityResolution("runtime-executable-identity-unavailable", {
+            runtime,
+            stage,
+            reason,
+            expected,
+            observed,
+            expectedAtimeNs: observations === undefined
+                ? undefined
+                : String(observations.before.atimeNs),
+            observedAtimeNs: observations === undefined
+                ? undefined
+                : String(observations.after.atimeNs),
+            expectedBirthtimeNs: observations === undefined
+                ? undefined
+                : String(observations.before.birthtimeNs),
+            observedBirthtimeNs: observations === undefined
+                ? undefined
+                : String(observations.after.birthtimeNs),
+        });
+        return undefined;
+    };
+    try {
+        const lexical = node_fs_1.default.lstatSync(runtime, { bigint: true });
+        stage = "physical-realpath";
+        const physicalPath = node_fs_1.default.realpathSync.native(runtime);
+        stage = "physical-stat";
+        const physical = node_fs_1.default.statSync(physicalPath, { bigint: true });
+        if (!physical.isFile())
+            return unavailable("not-regular", undefined, fileIdentity(physical));
+        stage = "open";
+        descriptor = node_fs_1.default.openSync(physicalPath, "r");
+        if (process.env.TTSC_E2E_TRACE) {
+            traceLease = {
+                callId: String(++identityTraceOrdinal),
+                runtime,
+                physicalPath,
+                descriptor,
+                pid: process.pid,
+                threadId: node_worker_threads_1.threadId,
+                dev: String(physical.dev),
+                ino: String(physical.ino),
+            };
+            E2ETrace_1.E2ETrace.capabilityResolution("runtime-executable-identity-opened", traceLease);
+        }
+        stage = "opened-stat";
+        const opened = node_fs_1.default.fstatSync(descriptor, { bigint: true });
+        if (fileIdentity(opened) !== fileIdentity(physical))
+            return unavailable("opened-file-changed", fileIdentity(physical), fileIdentity(opened));
+        const hash = node_crypto_1.default.createHash("sha256");
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let remaining = opened.size;
+        stage = "read";
+        while (remaining > 0n) {
+            const requested = remaining > BigInt(buffer.length) ? buffer.length : Number(remaining);
+            const length = node_fs_1.default.readSync(descriptor, buffer, 0, requested, null);
+            if (length === 0)
+                return unavailable("premature-eof", String(opened.size), String(opened.size - remaining));
+            hash.update(buffer.subarray(0, length));
+            remaining -= BigInt(length);
+        }
+        stage = "post-read-opened-stat";
+        const afterOpened = node_fs_1.default.fstatSync(descriptor, { bigint: true });
+        if (fileIdentity(afterOpened) !== fileIdentity(opened))
+            return unavailable("opened-file-changed-during-read", fileIdentity(opened), fileIdentity(afterOpened), { before: opened, after: afterOpened });
+        stage = "post-read-realpath";
+        const afterPath = node_fs_1.default.realpathSync.native(runtime);
+        if (afterPath !== physicalPath)
+            return unavailable("physical-target-changed", physicalPath, afterPath);
+        stage = "post-read-lexical-stat";
+        const afterLexical = node_fs_1.default.lstatSync(runtime, { bigint: true });
+        if (fileIdentity(afterLexical) !== fileIdentity(lexical))
+            return unavailable("lexical-file-changed-during-read", fileIdentity(lexical), fileIdentity(afterLexical));
+        stage = "post-read-physical-stat";
+        const afterPhysical = node_fs_1.default.statSync(physicalPath, { bigint: true });
+        if (fileIdentity(afterPhysical) !== fileIdentity(physical))
+            return unavailable("physical-file-changed-during-read", fileIdentity(physical), fileIdentity(afterPhysical));
+        const digest = hash.digest("hex");
+        E2ETrace_1.E2ETrace.capabilityResolution("runtime-executable-identity-observed", {
+            runtime,
+            physicalPath,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            lexical: fileIdentity(lexical),
+            physical: fileIdentity(physical),
+            digest,
+            openedAtimeNs: String(opened.atimeNs),
+            afterOpenedAtimeNs: String(afterOpened.atimeNs),
+            openedBirthtimeNs: String(opened.birthtimeNs),
+            afterOpenedBirthtimeNs: String(afterOpened.birthtimeNs),
+        });
+        return [
+            physicalPath,
+            fileIdentity(lexical),
+            fileIdentity(physical),
+            digest,
+        ].join("\0");
+    }
+    catch (error) {
+        return unavailable("filesystem-error", undefined, error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                node_fs_1.default.closeSync(descriptor);
+                if (traceLease !== undefined)
+                    E2ETrace_1.E2ETrace.capabilityResolution("runtime-executable-identity-closed", traceLease);
+            }
+            catch (error) {
+                if (traceLease !== undefined)
+                    E2ETrace_1.E2ETrace.capabilityResolution("runtime-executable-identity-close-failed", {
+                        ...traceLease,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                stage = "close";
+                return unavailable("descriptor-close-error", undefined, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+}
+// Trace-only ordinal distinguishes sequential uses of a reused descriptor.
+let identityTraceOrdinal = 0;
+/** Bigint metadata distinguishes file replacement and observed writes. */
+function fileIdentity(stat) {
+    return [
+        stat.dev,
+        stat.ino,
+        stat.mode,
+        stat.size,
+        stat.mtimeNs,
+        stat.ctimeNs,
+    ].join("\0");
+}
+//# sourceMappingURL=runtimeExecutableIdentity.js.map

package/lib/internal/runtimeExecutableIdentity.js.map

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

package/lib/internal/serializeCompilerError.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Describe a thrown value without dropping Error causes or aggregate failures.
+ *
+ * Error name, message and stack are explicit because they are not enumerable.
+ * Plain outcome objects and arrays retain enumerable string-keyed data.
+ * Repeated objects use a JSON-pointer reference marker, making cycles in a
+ * finite observed graph finite without duplicating shared outcome trees. Source
+ * objects shaped like reference or literal-object envelopes are escaped under
+ * `$ttscProperties`, keeping their data distinct from generated markers. Values
+ * JSON cannot express use a tagged description. Accessor descriptors are not
+ * invoked to read their values. Reflection can execute Proxy traps and expose
+ * changing objects, so arbitrary reflective behavior has no deadline or fixed
+ * graph-size guarantee. Failed reflective inspection, such as a revoked Proxy,
+ * is marked rather than replacing the compiler's exception. Internal slots of
+ * foreign classes are not projected into ordinary data.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit Error fields preserve exception meaning while recursively retaining cause, aggregate errors and ordinary outcome data. Pointer markers distinguish repeated references, literal envelopes escape colliding source shapes, and tagged values describe JSON-inexpressible primitives without dropping fields.
+ * @evidence contracts/common.md#clear-and-simple-design One traversal owns API and worker failure transport, with private property and scalar helpers; compiler status classification remains separate from serialization.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Available causal data is preserved rather than replaced with only the outer message; literal marker-shaped metadata is escaped rather than prohibited or reinterpreted. Traversal marks accessor descriptors instead of invoking getters and does not patch Error serialization. Proxy reflection may execute traps or fail, with inspection failures explicitly marked rather than inventing outcome data.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the retained Error/outcome fields, finite reference representation, exceptional scalars and accessor policy with separate acknowledgments.
+ * @evidence contracts/performance.md#efficient-algorithms For a finite observed graph, an explicit stack visits V distinct objects and E reflected owned fields once, with P prototype observations for inherited Error text, scalar/text conversion and pointer spelling costs. O(V+E+P) structural work excludes arbitrary Proxy-trap execution; shared subtrees are not expanded again and traversal does not recurse on the JavaScript call stack. Descriptor collections and pending outputs scale with the observed graph and text.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each failure graph belongs to one outcome; sharing an earlier serialization would require immutable graph inputs that arbitrary thrown values do not guarantee.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Seen-object and work-stack state belongs to one traversal and scales with distinct observed objects, fields and pointer text. On completion it becomes reclaimable while the caller owns the returned description; no global exception history is retained. Arbitrary reflective behavior can prevent completion or keep exposing new objects, and this traversal imposes no deadline or population cap.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation serializeCompilerError computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+export declare function serializeCompilerError(error: unknown): unknown;

package/lib/internal/serializeCompilerError.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeCompilerError = serializeCompilerError;
+/**
+ * Describe a thrown value without dropping Error causes or aggregate failures.
+ *
+ * Error name, message and stack are explicit because they are not enumerable.
+ * Plain outcome objects and arrays retain enumerable string-keyed data.
+ * Repeated objects use a JSON-pointer reference marker, making cycles in a
+ * finite observed graph finite without duplicating shared outcome trees. Source
+ * objects shaped like reference or literal-object envelopes are escaped under
+ * `$ttscProperties`, keeping their data distinct from generated markers. Values
+ * JSON cannot express use a tagged description. Accessor descriptors are not
+ * invoked to read their values. Reflection can execute Proxy traps and expose
+ * changing objects, so arbitrary reflective behavior has no deadline or fixed
+ * graph-size guarantee. Failed reflective inspection, such as a revoked Proxy,
+ * is marked rather than replacing the compiler's exception. Internal slots of
+ * foreign classes are not projected into ordinary data.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit Error fields preserve exception meaning while recursively retaining cause, aggregate errors and ordinary outcome data. Pointer markers distinguish repeated references, literal envelopes escape colliding source shapes, and tagged values describe JSON-inexpressible primitives without dropping fields.
+ * @evidence contracts/common.md#clear-and-simple-design One traversal owns API and worker failure transport, with private property and scalar helpers; compiler status classification remains separate from serialization.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Available causal data is preserved rather than replaced with only the outer message; literal marker-shaped metadata is escaped rather than prohibited or reinterpreted. Traversal marks accessor descriptors instead of invoking getters and does not patch Error serialization. Proxy reflection may execute traps or fail, with inspection failures explicitly marked rather than inventing outcome data.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the retained Error/outcome fields, finite reference representation, exceptional scalars and accessor policy with separate acknowledgments.
+ * @evidence contracts/performance.md#efficient-algorithms For a finite observed graph, an explicit stack visits V distinct objects and E reflected owned fields once, with P prototype observations for inherited Error text, scalar/text conversion and pointer spelling costs. O(V+E+P) structural work excludes arbitrary Proxy-trap execution; shared subtrees are not expanded again and traversal does not recurse on the JavaScript call stack. Descriptor collections and pending outputs scale with the observed graph and text.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each failure graph belongs to one outcome; sharing an earlier serialization would require immutable graph inputs that arbitrary thrown values do not guarantee.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Seen-object and work-stack state belongs to one traversal and scales with distinct observed objects, fields and pointer text. On completion it becomes reclaimable while the caller owns the returned description; no global exception history is retained. Arbitrary reflective behavior can prevent completion or keep exposing new objects, and this traversal imposes no deadline or population cap.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation serializeCompilerError computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+function serializeCompilerError(error) {
+    const seen = new WeakMap();
+    const pending = [];
+    const describe = (value, pointer) => {
+        if (value === null || typeof value !== "object")
+            return describeScalar(value);
+        const previous = seen.get(value);
+        if (previous !== undefined)
+            return { $ttscReference: previous };
+        seen.set(value, pointer);
+        let output;
+        try {
+            output = Array.isArray(value)
+                ? new Array(Object.getOwnPropertyDescriptor(value, "length").value)
+                : {};
+        }
+        catch {
+            return { $ttscValue: "uninspectable-object" };
+        }
+        pending.push({ input: value, output, pointer });
+        return output;
+    };
+    const result = describe(error, "");
+    while (pending.length !== 0) {
+        const { input, output, pointer } = pending.pop();
+        let fields;
+        let isError;
+        let destination = output;
+        let fieldPointer = pointer;
+        try {
+            fields = Object.getOwnPropertyDescriptors(input);
+            isError = input instanceof Error;
+            const keys = Object.keys(fields).filter((key) => fields[key].enumerable);
+            if (!isError &&
+                !Array.isArray(input) &&
+                ((keys.length === 1 && keys[0] === "$ttscReference") ||
+                    (keys.length === 2 &&
+                        keys.includes("$ttscValue") &&
+                        keys.includes("$ttscProperties")))) {
+                destination = {};
+                Object.assign(output, {
+                    $ttscValue: "object",
+                    $ttscProperties: destination,
+                });
+                fieldPointer = `${pointer}/$ttscProperties`;
+            }
+            if (isError) {
+                // Built-in names may be inherited; own Error data overrides them below.
+                const stack = errorDataField(input, "stack");
+                Object.assign(destination, {
+                    message: errorDataField(input, "message") ?? "",
+                    name: errorDataField(input, "name") ?? "Error",
+                    ...(stack === undefined ? {} : { stack }),
+                });
+            }
+        }
+        catch {
+            Object.assign(output, { $ttscValue: "uninspectable-object" });
+            continue;
+        }
+        for (const [key, descriptor] of Object.entries(fields)) {
+            if (!descriptor.enumerable &&
+                !(isError &&
+                    ["message", "name", "stack", "cause", "errors"].includes(key)))
+                continue;
+            const value = "value" in descriptor
+                ? describe(descriptor.value, `${fieldPointer}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`)
+                : { $ttscValue: "accessor" };
+            Object.defineProperty(destination, key, {
+                configurable: true,
+                enumerable: true,
+                value,
+                writable: true,
+            });
+        }
+    }
+    return result;
+}
+/** Read inherited Error data without evaluating a user-defined accessor. */
+function errorDataField(error, key) {
+    const visited = new WeakSet();
+    let current = error;
+    while (current !== null && !visited.has(current)) {
+        visited.add(current);
+        const descriptor = Object.getOwnPropertyDescriptor(current, key);
+        if (descriptor !== undefined)
+            return "value" in descriptor && typeof descriptor.value === "string"
+                ? descriptor.value
+                : undefined;
+        current = Object.getPrototypeOf(current);
+    }
+    return undefined;
+}
+/** Preserve JSON scalars and explicitly describe values outside that domain. */
+function describeScalar(value) {
+    if (value === undefined)
+        return { $ttscValue: "undefined" };
+    if (typeof value === "bigint")
+        return { $ttscValue: "bigint", value: String(value) };
+    if (typeof value === "symbol")
+        return { $ttscValue: "symbol", value: String(value) };
+    if (typeof value === "function")
+        return { $ttscValue: "function" };
+    if (typeof value === "number" && !Number.isFinite(value))
+        return { $ttscValue: "number", value: String(value) };
+    return value;
+}
+//# sourceMappingURL=serializeCompilerError.js.map