ttsc 0.30.4 → 0.31.1

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

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+/**
+ * Native path metadata and ambient lookup variables actually observed while
+ * reading a plugin build environment.
+ *
+ * The environment digest reads the Go tool, the file `go env -w` writes, the
+ * executables the C toolchain commands name, and GOROOT
+ * (`hashPluginBuildEnvironment`). Their metadata, taken before their content is
+ * read, is what a later observer compares: a process keeping its reading
+ * (`processPluginBuildEnvironment`), and a build proving the toolchain it ran
+ * is the one its key read. Change time can reveal a write even when size and
+ * modification time are restored.
+ *
+ * This witnesses native metadata and link target names, not a second byte
+ * comparison. Its change detection assumes the filesystem distinguishes
+ * contributing edits in the captured identity and timestamps; an edit that
+ * reproduces the entire metadata signature is outside the proof this record
+ * supplies. Native executable lookup variables are recorded at the lookup,
+ * because a shared worker can observe a transient parent value between the
+ * request and final snapshots.
+ *
+ * @evidence contracts/common.md#principled-implementation Pre-read identity and write metadata witness external dependencies not carried by variables under the documented metadata-distinguishability premise; a refused dependency makes the complete reading unusable.
+ * @evidence contracts/common.md#clear-and-simple-design Record construction, refusal and validation share one metadata representation; the caller owns the reading and its lifetime.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Validation inspects real paths instead of replacing filesystem behavior or accepting a stable pathname as proof of unchanged contents.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain provenance, replacement detection and both consuming boundaries; member documentation states refusal and validation meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation Node bigint stat follows the content reader's targets, while lstat and readlink separately witness link identity and target spelling; no platform name supplies case or identity policy.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace defines the record and operations; add and holds own observation/validation processing.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Consumers own environment reuse; the namespace itself retains no reading.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Witness maps are created and released by callers, not retained by this namespace.
+ */
+export declare namespace PluginBuildEnvironmentWitness {
+    /**
+     * Each witnessed path's metadata when it was first read. Link observations
+     * use qualified internal keys so link spelling and followed target state
+     * remain separate dependencies.
+     *
+     * @evidence contracts/common.md#principled-implementation Capture operations preserve first observations in this map, with explicit refusal replacing a value by an unusable sentinel. The mutable Map type itself does not prevent arbitrary caller overwrites or validate provenance.
+     * @evidence contracts/common.md#clear-and-simple-design The record carries only dependencies and their signatures; witness operations own interpretation and consumers own retention.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The representation stores observed native state rather than predeclared expected results.
+     * @evidence contracts/common.md#meaningful-documentation The native description identifies first-read provenance, which is the nonobvious meaning of this otherwise ordinary map.
+     * @evidence contracts/portability.md#os-neutral-implementation Keys preserve readers' native path spellings with disjoint internal link qualifiers; values contain Node metadata and observed target spelling, not a guessed filesystem case policy.
+     *
+     * @evidenceExclude contracts/performance.md#efficient-algorithms The map type supplies a representation; capture and validation operations choose their algorithms.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The record does not decide whether consumers may reuse an environment reading.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Record lifetime belongs to the creating consumer; the type does not retain its own instances.
+     */
+    type Record = Map<string, string>;
+    /**
+     * Record `file`'s metadata before reading it, unless already recorded.
+     * `observed` reuses a stat the caller just took before the same read.
+     *
+     * @evidence contracts/common.md#principled-implementation First-write retention keeps the earliest metadata even when a path contributes more than once; caller-provided metadata is from the same pre-read observation.
+     * @evidence contracts/common.md#clear-and-simple-design Optional output makes one reader usable with or without a witness and leaves signature encoding in one helper.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Observation uses native stat state; absent witnessing does not alter the content read or fake validity.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states first-observation semantics and the provenance required for the optional stat, with a blank line before tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Metadata comes from Node bigint stat for the actual path; callers can reuse precisely that native observation.
+     * @evidence contracts/performance.md#efficient-algorithms Map membership/set processes path keys; an unseen dependency without supplied metadata performs native stat/path lookup, then formats bigint fields. Native/key/numeric-text costs remain despite expected constant-time map indexing; supplied stat provenance is a caller premise.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated dependencies reuse the first signature and a caller's pre-read stat avoids repeating the equivalent syscall.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns the witness map and its release; this operation adds one dependency without retaining another handle.
+     */
+    function add(witness: Record | undefined, file: string, observed?: fs.BigIntStats): void;
+    /**
+     * Witness a link itself before following it, including a missing target.
+     * Target metadata remains a separate observation through add.
+     *
+     * @evidence contracts/common.md#principled-implementation First-observation retention records native link metadata and target spelling separately from followed-target state. A successfully observed changed spelling changes this witness; unavailable lstat/readlink yields the helper's missing marker, which does not distinguish every failure cause.
+     * @evidence contracts/common.md#clear-and-simple-design Qualified keys keep link and target observations in the same caller-owned record, and holds dispatches to their respective native observations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A link's existence does not certify its target; native lstat and readlink preserve missing-target and retargeting distinctions without replacing filesystem operations.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes the link observation from add's target observation and states pre-follow timing.
+     * @evidence contracts/portability.md#os-neutral-implementation Node lstat and readlink inspect the native link or junction and its target spelling without an OS-based case or existence assumption.
+     * @evidence contracts/performance.md#efficient-algorithms Qualified-key construction/map indexing process path text; an unseen link uses native lstat/readlink and serializes bigint/target spelling. Native component/link lookup and all numeric/path/target bytes contribute work; no file content is read.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated link observations retain their first signature in this record rather than replacing evidence of a race.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns the record; the operation retains no native handle.
+     */
+    function addLink(witness: Record | undefined, file: string): void;
+    /**
+     * Retain an ambient native lookup variable at the exact lookup that used it.
+     * A different repeated observation refuses the reading. A captured transient
+     * value can reveal an ABA interval hidden by initial/final snapshots; a value
+     * never observed here is not detected by this record.
+     *
+     * @evidence contracts/common.md#principled-implementation First observed native lookup inputs remain paired with the digest and are compared with current host inputs before publication and reuse.
+     * @evidence contracts/common.md#clear-and-simple-design Disjoint environment keys share the existing caller-owned witness and validation boundary.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual observed variables qualify native selection without writing the parent's shared environment or inventing a tool identity.
+     * @evidence contracts/common.md#meaningful-documentation The prose distinguishes lookup-time authority from request and final snapshots.
+     * @evidence contracts/portability.md#os-neutral-implementation Native executable selection supplies the variable value it observed; holds uses lowercase-name matching on Windows and direct name lookup elsewhere, without writing host variables.
+     * @evidence contracts/performance.md#efficient-algorithms Name qualification/map indexing and JSON serialization process supplied name/value bytes on every observation, including repeats. Equal observations keep the first value; a different value sets the refusal sentinel, with no native subprocess or file-content read here.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated equal observations reuse the first signature; a different observation refuses the complete reading.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns and releases the record; this operation retains no process or environment handle.
+     */
+    function addEnvironment(witness: Record | undefined, name: string, value: string | undefined): void;
+    /**
+     * Record `file` as a path whose state could not be witnessed, so the record
+     * never holds and nothing kept under it is reused.
+     *
+     * @evidence contracts/common.md#principled-implementation The refusal sentinel cannot equal a metadata signature, so an incomplete environment never passes holds.
+     * @evidence contracts/common.md#clear-and-simple-design One sentinel uses the existing record format rather than adding a parallel error collection.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An unreadable dependency refuses reuse rather than substituting an assumed valid reading.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the effect on every consumer of the record, not merely the stored value.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This operation stores a sentinel and performs no native path lookup.
+     * @evidence contracts/performance.md#efficient-algorithms An optional supplied-map write processes the key and replaces its value with a fixed sentinel; it performs no native observation, content scan or separate dependency traversal.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work It invalidates a witness rather than sharing a computation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Record lifetime belongs to the caller.
+     */
+    function refuse(witness: Record | undefined, file: string): void;
+    /**
+     * Whether every native path and ambient variable still matches its
+     * observation. The existing private opt-in trace retains the first actual
+     * mismatch without repeating its lookup or changing the refusal. An optional
+     * observation label separates preparation and build epochs in that trace; it
+     * does not change validation or authorize publication. A supplied native
+     * observation map belongs to one synchronous batch only; never reuse it after
+     * an await, delivery, environment mutation or publication boundary.
+     *
+     * @evidence contracts/common.md#principled-implementation Universal comparison requires every dependency to match its pre-read signature and immediately rejects a refused or changed path.
+     * @evidence contracts/common.md#clear-and-simple-design Validation uses the same signature helper as capture, keeping identity and timestamp policy in one place.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts All dependencies are inspected; a quiet parent or unchanged VERSION cannot stand in for nested SDK inputs.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the universal unchanged-metadata condition and tags remain separated from it.
+     * @evidence contracts/portability.md#os-neutral-implementation Validation reads actual Node metadata using the same link-following semantics as capture.
+     * @evidence contracts/performance.md#efficient-algorithms Validation iterates dependencies until mismatch and performs native stat/link queries or ambient-variable serialization. Windows environment matching enumerates names and lowercases text per witnessed variable, so P alone does not bound that work. Native path/link/name/value/numeric bytes contribute cost; file content is not read and unavailable native observations share the helper's missing marker. An enabled private trace serializes the first mismatch's already-computed text through its existing bounded sink.
+     *
+     * @evidence contracts/performance.md#reuse-equivalent-work A caller-owned synchronous batch may share current native observations, comparing each witness against its own expected state; ordinary calls and all later observation phases establish new validity.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Validation retains no handles or additional historical state.
+     */
+    function holds(witness: Record, observation?: string, currentReadings?: Map<string, string>): boolean;
+}

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

@@ -0,0 +1,215 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginBuildEnvironmentWitness = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const E2ETrace_1 = require("../../../internal/E2ETrace");
+/**
+ * Native path metadata and ambient lookup variables actually observed while
+ * reading a plugin build environment.
+ *
+ * The environment digest reads the Go tool, the file `go env -w` writes, the
+ * executables the C toolchain commands name, and GOROOT
+ * (`hashPluginBuildEnvironment`). Their metadata, taken before their content is
+ * read, is what a later observer compares: a process keeping its reading
+ * (`processPluginBuildEnvironment`), and a build proving the toolchain it ran
+ * is the one its key read. Change time can reveal a write even when size and
+ * modification time are restored.
+ *
+ * This witnesses native metadata and link target names, not a second byte
+ * comparison. Its change detection assumes the filesystem distinguishes
+ * contributing edits in the captured identity and timestamps; an edit that
+ * reproduces the entire metadata signature is outside the proof this record
+ * supplies. Native executable lookup variables are recorded at the lookup,
+ * because a shared worker can observe a transient parent value between the
+ * request and final snapshots.
+ *
+ * @evidence contracts/common.md#principled-implementation Pre-read identity and write metadata witness external dependencies not carried by variables under the documented metadata-distinguishability premise; a refused dependency makes the complete reading unusable.
+ * @evidence contracts/common.md#clear-and-simple-design Record construction, refusal and validation share one metadata representation; the caller owns the reading and its lifetime.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Validation inspects real paths instead of replacing filesystem behavior or accepting a stable pathname as proof of unchanged contents.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain provenance, replacement detection and both consuming boundaries; member documentation states refusal and validation meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation Node bigint stat follows the content reader's targets, while lstat and readlink separately witness link identity and target spelling; no platform name supplies case or identity policy.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace defines the record and operations; add and holds own observation/validation processing.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Consumers own environment reuse; the namespace itself retains no reading.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Witness maps are created and released by callers, not retained by this namespace.
+ */
+var PluginBuildEnvironmentWitness;
+(function (PluginBuildEnvironmentWitness) {
+    /**
+     * Record `file`'s metadata before reading it, unless already recorded.
+     * `observed` reuses a stat the caller just took before the same read.
+     *
+     * @evidence contracts/common.md#principled-implementation First-write retention keeps the earliest metadata even when a path contributes more than once; caller-provided metadata is from the same pre-read observation.
+     * @evidence contracts/common.md#clear-and-simple-design Optional output makes one reader usable with or without a witness and leaves signature encoding in one helper.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Observation uses native stat state; absent witnessing does not alter the content read or fake validity.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states first-observation semantics and the provenance required for the optional stat, with a blank line before tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Metadata comes from Node bigint stat for the actual path; callers can reuse precisely that native observation.
+     * @evidence contracts/performance.md#efficient-algorithms Map membership/set processes path keys; an unseen dependency without supplied metadata performs native stat/path lookup, then formats bigint fields. Native/key/numeric-text costs remain despite expected constant-time map indexing; supplied stat provenance is a caller premise.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated dependencies reuse the first signature and a caller's pre-read stat avoids repeating the equivalent syscall.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns the witness map and its release; this operation adds one dependency without retaining another handle.
+     */
+    function add(witness, file, observed) {
+        if (witness === undefined || witness.has(file))
+            return;
+        witness.set(file, signature(file, observed));
+    }
+    PluginBuildEnvironmentWitness.add = add;
+    /**
+     * Witness a link itself before following it, including a missing target.
+     * Target metadata remains a separate observation through add.
+     *
+     * @evidence contracts/common.md#principled-implementation First-observation retention records native link metadata and target spelling separately from followed-target state. A successfully observed changed spelling changes this witness; unavailable lstat/readlink yields the helper's missing marker, which does not distinguish every failure cause.
+     * @evidence contracts/common.md#clear-and-simple-design Qualified keys keep link and target observations in the same caller-owned record, and holds dispatches to their respective native observations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A link's existence does not certify its target; native lstat and readlink preserve missing-target and retargeting distinctions without replacing filesystem operations.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes the link observation from add's target observation and states pre-follow timing.
+     * @evidence contracts/portability.md#os-neutral-implementation Node lstat and readlink inspect the native link or junction and its target spelling without an OS-based case or existence assumption.
+     * @evidence contracts/performance.md#efficient-algorithms Qualified-key construction/map indexing process path text; an unseen link uses native lstat/readlink and serializes bigint/target spelling. Native component/link lookup and all numeric/path/target bytes contribute work; no file content is read.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated link observations retain their first signature in this record rather than replacing evidence of a race.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns the record; the operation retains no native handle.
+     */
+    function addLink(witness, file) {
+        const key = LINK_PREFIX + file;
+        if (witness === undefined || witness.has(key))
+            return;
+        witness.set(key, linkSignature(file));
+    }
+    PluginBuildEnvironmentWitness.addLink = addLink;
+    /**
+     * Retain an ambient native lookup variable at the exact lookup that used it.
+     * A different repeated observation refuses the reading. A captured transient
+     * value can reveal an ABA interval hidden by initial/final snapshots; a value
+     * never observed here is not detected by this record.
+     *
+     * @evidence contracts/common.md#principled-implementation First observed native lookup inputs remain paired with the digest and are compared with current host inputs before publication and reuse.
+     * @evidence contracts/common.md#clear-and-simple-design Disjoint environment keys share the existing caller-owned witness and validation boundary.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual observed variables qualify native selection without writing the parent's shared environment or inventing a tool identity.
+     * @evidence contracts/common.md#meaningful-documentation The prose distinguishes lookup-time authority from request and final snapshots.
+     * @evidence contracts/portability.md#os-neutral-implementation Native executable selection supplies the variable value it observed; holds uses lowercase-name matching on Windows and direct name lookup elsewhere, without writing host variables.
+     * @evidence contracts/performance.md#efficient-algorithms Name qualification/map indexing and JSON serialization process supplied name/value bytes on every observation, including repeats. Equal observations keep the first value; a different value sets the refusal sentinel, with no native subprocess or file-content read here.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated equal observations reuse the first signature; a different observation refuses the complete reading.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns and releases the record; this operation retains no process or environment handle.
+     */
+    function addEnvironment(witness, name, value) {
+        if (witness === undefined)
+            return;
+        const key = ENVIRONMENT_PREFIX + name;
+        const recorded = JSON.stringify([value ?? null]);
+        if (witness.has(key) && witness.get(key) !== recorded)
+            witness.set(key, UNWITNESSABLE);
+        else if (!witness.has(key))
+            witness.set(key, recorded);
+    }
+    PluginBuildEnvironmentWitness.addEnvironment = addEnvironment;
+    /**
+     * Record `file` as a path whose state could not be witnessed, so the record
+     * never holds and nothing kept under it is reused.
+     *
+     * @evidence contracts/common.md#principled-implementation The refusal sentinel cannot equal a metadata signature, so an incomplete environment never passes holds.
+     * @evidence contracts/common.md#clear-and-simple-design One sentinel uses the existing record format rather than adding a parallel error collection.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An unreadable dependency refuses reuse rather than substituting an assumed valid reading.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the effect on every consumer of the record, not merely the stored value.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This operation stores a sentinel and performs no native path lookup.
+     * @evidence contracts/performance.md#efficient-algorithms An optional supplied-map write processes the key and replaces its value with a fixed sentinel; it performs no native observation, content scan or separate dependency traversal.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work It invalidates a witness rather than sharing a computation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Record lifetime belongs to the caller.
+     */
+    function refuse(witness, file) {
+        witness?.set(file, UNWITNESSABLE);
+    }
+    PluginBuildEnvironmentWitness.refuse = refuse;
+    /**
+     * Whether every native path and ambient variable still matches its
+     * observation. The existing private opt-in trace retains the first actual
+     * mismatch without repeating its lookup or changing the refusal. An optional
+     * observation label separates preparation and build epochs in that trace; it
+     * does not change validation or authorize publication. A supplied native
+     * observation map belongs to one synchronous batch only; never reuse it after
+     * an await, delivery, environment mutation or publication boundary.
+     *
+     * @evidence contracts/common.md#principled-implementation Universal comparison requires every dependency to match its pre-read signature and immediately rejects a refused or changed path.
+     * @evidence contracts/common.md#clear-and-simple-design Validation uses the same signature helper as capture, keeping identity and timestamp policy in one place.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts All dependencies are inspected; a quiet parent or unchanged VERSION cannot stand in for nested SDK inputs.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the universal unchanged-metadata condition and tags remain separated from it.
+     * @evidence contracts/portability.md#os-neutral-implementation Validation reads actual Node metadata using the same link-following semantics as capture.
+     * @evidence contracts/performance.md#efficient-algorithms Validation iterates dependencies until mismatch and performs native stat/link queries or ambient-variable serialization. Windows environment matching enumerates names and lowercases text per witnessed variable, so P alone does not bound that work. Native path/link/name/value/numeric bytes contribute cost; file content is not read and unavailable native observations share the helper's missing marker. An enabled private trace serializes the first mismatch's already-computed text through its existing bounded sink.
+     *
+     * @evidence contracts/performance.md#reuse-equivalent-work A caller-owned synchronous batch may share current native observations, comparing each witness against its own expected state; ordinary calls and all later observation phases establish new validity.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Validation retains no handles or additional historical state.
+     */
+    function holds(witness, observation, currentReadings) {
+        for (const [file, recorded] of witness) {
+            let current = currentReadings?.get(file);
+            if (current === undefined) {
+                current = file.startsWith(ENVIRONMENT_PREFIX)
+                    ? environmentSignature(file.slice(ENVIRONMENT_PREFIX.length))
+                    : file.startsWith(LINK_PREFIX)
+                        ? linkSignature(file.slice(LINK_PREFIX.length))
+                        : signature(file);
+                currentReadings?.set(file, current);
+            }
+            if (current !== recorded) {
+                E2ETrace_1.E2ETrace.capabilityResolution("plugin-build-environment-witness-mismatch", {
+                    key: file,
+                    recorded,
+                    current,
+                    refused: recorded === UNWITNESSABLE,
+                    observation,
+                });
+                return false;
+            }
+        }
+        return true;
+    }
+    PluginBuildEnvironmentWitness.holds = holds;
+    /** A recorded state no signature equals. */
+    const UNWITNESSABLE = "unwitnessable";
+    /** NUL cannot occur in a native pathname, so this qualification is disjoint. */
+    const LINK_PREFIX = "\0link:";
+    const ENVIRONMENT_PREFIX = "\0environment:";
+    function environmentSignature(name) {
+        const actualName = process.platform === "win32"
+            ? Object.keys(process.env).find((key) => key.toLowerCase() === name.toLowerCase())
+            : name;
+        return JSON.stringify([
+            actualName === undefined ? null : (process.env[actualName] ?? null),
+        ]);
+    }
+    /** Observe the link before its target, under the same metadata premise. */
+    function linkSignature(file) {
+        try {
+            const stat = node_fs_1.default.lstatSync(file, { bigint: true });
+            return JSON.stringify([
+                stat.dev.toString(),
+                stat.ino.toString(),
+                stat.size.toString(),
+                stat.mtimeNs.toString(),
+                stat.ctimeNs.toString(),
+                node_fs_1.default.readlinkSync(file),
+            ]);
+        }
+        catch {
+            return "missing";
+        }
+    }
+    /**
+     * The metadata a replacement moves: identity, size, and modification and
+     * change times, following links; `missing` when the native stat is
+     * unavailable.
+     */
+    function signature(file, observed) {
+        try {
+            const stat = observed ?? node_fs_1.default.statSync(file, { bigint: true });
+            return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
+        }
+        catch {
+            return "missing";
+        }
+    }
+})(PluginBuildEnvironmentWitness || (exports.PluginBuildEnvironmentWitness = PluginBuildEnvironmentWitness = {}));
+//# sourceMappingURL=PluginBuildEnvironmentWitness.js.map

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

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

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

@@ -0,0 +1,25 @@
+/**
+ * Opaque identity of one observed lock generation.
+ *
+ * Returned by {@link inspectPluginBuildLock} and consumed by
+ * {@link reclaimPluginBuildLock}, carrying the generation and protocol the
+ * waiter observed. A v3 observer is recorded inside that generation so its
+ * tombstone remains while the observing process can still use the fence,
+ * preventing a stale fence from retiring a successor. Legacy fences cannot
+ * provide that guarantee against old executables that delete their lock path.
+ *
+ * @evidence contracts/common.md#principled-implementation Protocol and generation distinguish a captured legacy fence from an observer-protected v3 retirement identity.
+ * @evidence contracts/common.md#clear-and-simple-design The token contains no mutable pathname observation; inspection owns registration and reclamation owns retirement.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The fence retains the observed generation rather than substituting a successor's current identity after a delay.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs identify producer, consumer and observer lifetime; member comments explain protocol and generation separately from tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Tokens use protocol discriminants and hexadecimal identity; callers derive native paths through the protocol adapter rather than embedding filesystem syntax in the token.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type PluginBuildLockFence = {
+    /** Which lock protocol held the observed generation. */
+    protocol: "legacy" | "v3";
+    /** The 128-bit hex id of the observed generation. */
+    generation: string;
+};

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=PluginBuildLockFence.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PluginBuildLockFence.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/PluginBuildLockFence.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,29 @@
+/**
+ * Ownership token returned only to the process that acquired the v3 lock.
+ *
+ * Produced by {@link acquirePluginBuildLock} and consumed by
+ * {@link releasePluginBuildLock}. Release retires this generation and no other,
+ * so a holder whose lock was reclaimed cannot release its successor. The token
+ * remains valid only in its original coordination namespace.
+ *
+ * Its completion nonce authorizes the acquiring process to record actual task
+ * completion after its payload callback has ended, including an already retired
+ * generation. Expiring a wait budget does not end that callback.
+ *
+ * @evidence contracts/common.md#principled-implementation The protocol and random generation identify the holder's retirement destination; a separate nonce qualifies its actual task-completion witness, without representing legacy or old v2 acquisition.
+ * @evidence contracts/common.md#clear-and-simple-design The token carries ownership identity while acquisition, finally release and tombstone collection own the lifecycle decisions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Release uses the recorded generation rather than deleting whichever holder currently occupies a shared pathname.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names producer, consumer, protocol and namespace lifetime; properties have separate useful comments without checklist tags.
+ * @evidence contracts/portability.md#os-neutral-implementation The generation is protocol spelling independent of native separators; the v3 discriminant isolates the filesystem namespace from old v2 reclaimers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type PluginBuildLockLease = {
+    /** Always "v3": acquisition never grants an older protocol's ownership. */
+    protocol: "v3";
+    /** The 128-bit hex id of the held generation. */
+    generation: string;
+    /** The acquiring task's 128-bit completion publication capability. */
+    completionNonce: string;
+};

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=PluginBuildLockLease.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PluginBuildLockLease.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/PluginBuildLockLease.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,42 @@
+import type { PluginBuildLockFence } from "./PluginBuildLockFence";
+/**
+ * One observation of a plugin build lock directory's state.
+ *
+ * - `active`: the lock exists and its owner is alive (or cannot be disproven:
+ *   another host or unconfirmed owner metadata). Keep waiting within the
+ *   caller's admission budget.
+ * - `abandoned`: the lock has a qualified, provably absent same-host owner. The
+ *   returned fence permits an attempt to retire that observed generation.
+ * - `released`: observation found a released or unavailable handoff and carries
+ *   no fence. V3 coordination roots persist independently of `current`; these
+ *   sequential observations do not guarantee that no successor exists by
+ *   return. This is never an infinitely old abandoned lock.
+ *
+ * A v3 active or abandoned result records the observer before returning its
+ * fence. Reclamation is still a separate action that may lose a retirement
+ * race.
+ *
+ * @evidence contracts/common.md#principled-implementation The discriminated union requires a fence for occupied generations and omits it for absence, separating liveness labels from retirement authority.
+ * @evidence contracts/common.md#clear-and-simple-design Each state carries only its relevant diagnostic description and token; observation does not itself retire ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Released is represented explicitly rather than an infinite age that could manufacture abandonment after a normal handoff.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains all three states, persistent-root absence and the observation/reclamation distinction before its tags.
+ * @evidence contracts/portability.md#os-neutral-implementation The states represent filesystem observations independently of OS errno wording; occupied states carry the protocol distinction needed for native retirement.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type PluginBuildLockObservation = {
+    state: "active";
+    /** The diagnostic label of the observed holder. */
+    owner: string;
+    /** The captured identity; a timeout alone cannot authorize retirement. */
+    fence: PluginBuildLockFence;
+} | {
+    state: "abandoned";
+    /** The qualified process-absence grounds for reclamation. */
+    reason: string;
+    /** The generation whose retirement may be attempted. */
+    fence: PluginBuildLockFence;
+} | {
+    state: "released";
+};

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=PluginBuildLockObservation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PluginBuildLockObservation.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/PluginBuildLockObservation.ts"],"names":[],"mappings":""}