ttsc 0.30.4 → 0.31.0

package/src/plugin/internal/source/PluginBuildEnvironmentReadings.ts

@@ -0,0 +1,231 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { SHARE_ENV, Worker } from "node:worker_threads";
+
+import { SidecarEnvironment } from "../../../compiler/internal/sharedHost/SidecarEnvironment";
+import { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
+import { pluginBuildEnvironment } from "./pluginBuildEnvironment";
+
+/**
+ * Share native build-environment observations between synchronous clients and
+ * asynchronous hosts. Variables and pre-read external metadata qualify every
+ * reading; an absent or stale cached reading supplies no authority.
+ *
+ * Cold asynchronous reads run in an exclusively owned worker. Its complete
+ * environment snapshot is passed explicitly to the native reader. Publication
+ * rechecks both current host variables and external witnesses after transfer.
+ * The worker reads the parent's shared environment for native fallback rules;
+ * neither it nor this owner writes that environment. Explicit reader inputs
+ * still use the request snapshot and publication still qualifies that
+ * snapshot.
+ *
+ * @evidence contracts/common.md#principled-implementation Readings pair complete environment identity with the producer's native pre-read witness; cached reuse validates that witness and asynchronous publication rechecks variables/witness after transfer. Synchronous fresh reads publish their paired observations without an extra post-read holds call here; native metadata distinguishability remains a premise.
+ * @evidence contracts/common.md#clear-and-simple-design One owner shares observation records across synchronous reads, cache-only proof and asynchronous preparation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cold preparation performs the same actual native Go/toolchain reading off-thread; failed or stale observations are never replaced by producer-expected state.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes preparation, publication and cache-only authority; members document their separate execution responsibilities.
+ * @evidence contracts/portability.md#os-neutral-implementation Complete environment snapshots use the shared native-name merger; metadata witnesses preserve actual native filesystem and link identity.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Individual members own variable indexing, witness validation and native preparation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The members specify the invalidation and sharing boundaries.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Readings replace existing keys but retain historical directory/environment keys without eviction. One idle worker and its retirement listeners remain process-owned/unreferenced; active work is ref'ed and per-request listeners are removed at settlement. Distinct requests can queue without a population bound/timeout; a stalled request can delay successors. Failed-worker termination is initiated without joining its promise, and this owner does not mutate the shared environment.
+ */
+export namespace PluginBuildEnvironmentReadings {
+  /**
+   * The native digest and first-read path evidence transported by a worker.
+   *
+   * @evidence contracts/common.md#principled-implementation A digest remains paired with every pre-read external-path witness; representation alone grants no current authority.
+   * @evidence contracts/common.md#clear-and-simple-design One transfer record carries the native reading and its validity premises.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The record contains actual observed metadata rather than a producer-expected digest with no evidence.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states the provenance and transfer responsibility of the fields.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This transport type performs no native operation; the witness and reader own identity semantics.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms A record type defines representation; reading and validation members own computation.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The type grants no reuse authority on its own.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The creating request or process memo owns this record's lifetime.
+   */
+  export interface Reading {
+    readonly environment: string;
+    readonly witness: PluginBuildEnvironmentWitness.Record;
+  }
+
+  const readings = new Map<string, Reading>();
+  const pending = new Map<string, Promise<string>>();
+  let worker: Worker | undefined;
+  let queue: Promise<void> = Promise.resolve();
+
+  /**
+   * Return a qualified reading without starting a native subprocess or cold
+   * content/environment preparation. Witness validation still queries native
+   * filesystem/link/ambient-variable state. Undefined requires preparation or
+   * invalidation, rather than a cold fallback.
+   *
+   * @evidence contracts/common.md#principled-implementation Both current full variables and every external-path witness must match before cached authority is returned.
+   * @evidence contracts/common.md#clear-and-simple-design One optional digest boundary distinguishes usable proof from unavailable proof.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A stale or absent reading returns undefined instead of trusting a pathname, source watcher or reported expected digest.
+   * @evidence contracts/common.md#meaningful-documentation The prose explicitly excludes native subprocess and cold-content preparation.
+   * @evidence contracts/portability.md#os-neutral-implementation Native metadata and canonical environment names determine equality without OS-wide casing guesses.
+   * @evidence contracts/performance.md#efficient-algorithms Variable merging/sorting/hashing processes full name/value bytes and directory text. Witness validation queries native path metadata/link spelling and ambient variables, with their path/lookup/text costs; no Go process or SDK content hashing is started here, but V/P counts alone do not bound native work.
+   * @evidence contracts/performance.md#reuse-equivalent-work Only a still-qualified directory/environment reading is shared.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The operation borrows a process-owned record and retains no request history.
+   */
+  export function cached(directory: string): string | undefined {
+    const known = readings.get(key(directory, process.env));
+    return known !== undefined &&
+      PluginBuildEnvironmentWitness.holds(known.witness)
+      ? known.environment
+      : undefined;
+  }
+
+  /**
+   * Read synchronously for clients whose API owns synchronous native work.
+   * Explicit refresh preserves the original fresh-comparison semantics.
+   *
+   * @evidence contracts/common.md#principled-implementation The same native reader constructs a digest paired with its pre-read witness; optional cached reuse validates current variables/metadata. A fresh synchronous reading is published without a separate post-read qualification here and relies on the native reader's premises.
+   * @evidence contracts/common.md#clear-and-simple-design The synchronous boundary shares cached authority and delegates fresh observation to its owning reader.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A requested refresh actually probes the selected native toolchain.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies the synchronous execution owner and explicit refresh meaning.
+   * @evidence contracts/portability.md#os-neutral-implementation Native Go selection and filesystem witnesses remain delegated to the shared reader.
+   * @evidence contracts/performance.md#efficient-algorithms Hits pay complete variable-text indexing and native witness queries. Misses/refresh merge environment values, perform actual toolchain/SDK/content work, then rebuild the full variable-text key for publication; native/path/file/name/value bytes contribute cost beyond invocation count.
+   * @evidence contracts/performance.md#reuse-equivalent-work Synchronous and asynchronous clients share the same qualified readings.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retention belongs to the namespace; this call publishes one replacement record.
+   */
+  export function read(directory: string, refresh = false): string {
+    const known = refresh ? undefined : cached(directory);
+    if (known !== undefined) return known;
+    const env = SidecarEnvironment.merge(process.env);
+    const witness: PluginBuildEnvironmentWitness.Record = new Map();
+    const environment = pluginBuildEnvironment(directory, env, witness);
+    readings.set(key(directory, env), { environment, witness });
+    return environment;
+  }
+
+  /**
+   * Prepare native authority off the host thread, sharing equivalent concurrent
+   * requests. A changed environment or witness during transfer refuses the
+   * reading; the caller's admission/recovery policy owns a fresh attempt.
+   * Worker errors/exits retire and reject; a native-reader error returned in a
+   * normal message rejects the request while retaining that live worker. Later
+   * requests can create a worker after retirement. Refresh bypasses a cached
+   * reading but can still share an equivalent in-flight request.
+   *
+   * @evidence contracts/common.md#principled-implementation Worker results publish only under their exact current variable identity and still-current native pre-read witness; changed or unwitnessable transfer windows reject instead of publishing authority or retrying indefinitely.
+   * @evidence contracts/common.md#clear-and-simple-design Qualified hits return immediately; equivalent misses share one pending promise and exclusive queued worker request.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Go/environment/SDK preparation occurs in the worker rather than blocking the async host or fabricating a digest from compiler output.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains equivalent sharing, freshness refusal and failed-worker recovery.
+   * @evidence contracts/portability.md#os-neutral-implementation Explicit complete environment snapshots and native worker paths preserve host identity and avoid shell commands.
+   * @evidence contracts/performance.md#efficient-algorithms Qualified hits inspect full variable text and native witnesses. Misses key/transfer environment data, serialize native preparation on one warm worker, and reindex variables/validate witness after reply; environment/witness/file/path bytes and queueing contribute cost. Equivalent pending requests share one producer attempt, not an independent native preparation each.
+   * @evidence contracts/performance.md#reuse-equivalent-work Pending identity is directory plus complete variables; the warm worker shares native toolchain memos while published authority still requires fresh witness validation.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Pending identity entries are removed in finally at settlement and per-request worker listeners are removed by the terminal path. Idle worker remains unreferenced with lifetime retirement listeners; worker failure initiates termination without awaiting completion. Distinct queued contexts retain environment/witness/promise data without a population bound or timeout, and a stalled producer blocks later queued work.
+   */
+  export async function prepare(
+    directory: string,
+    refresh = false,
+  ): Promise<string> {
+    const known = refresh ? undefined : cached(directory);
+    if (known !== undefined) return known;
+    const env = SidecarEnvironment.merge(process.env);
+    const identity = key(directory, env);
+    const existing = pending.get(identity);
+    if (existing !== undefined) return existing;
+    const request = (async () => {
+      const reading = await observe(directory, env);
+      if (
+        identity !== key(directory, process.env) ||
+        !PluginBuildEnvironmentWitness.holds(reading.witness)
+      )
+        throw new Error(
+          `ttsc: plugin build environment could not be qualified for ${directory}`,
+        );
+      readings.set(identity, reading);
+      return reading.environment;
+    })();
+    pending.set(identity, request);
+    try {
+      return await request;
+    } finally {
+      if (pending.get(identity) === request) pending.delete(identity);
+    }
+  }
+
+  function key(directory: string, env: NodeJS.ProcessEnv): string {
+    const variables = crypto.createHash("sha256");
+    for (const [name, value] of Object.entries(
+      SidecarEnvironment.merge(env),
+    ).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)))
+      if (value !== undefined)
+        variables.update(`${name.length}:${name}${value.length}:${value}\0`);
+    return `${directory}\0${variables.digest("hex")}`;
+  }
+
+  function observe(
+    directory: string,
+    env: NodeJS.ProcessEnv,
+  ): Promise<Reading> {
+    const request = queue.then(
+      () =>
+        new Promise<Reading>((resolve, reject) => {
+          const current = acquireWorker();
+          current.ref();
+          let settled = false;
+          const release = (reusable: boolean) => {
+            if (settled) return false;
+            settled = true;
+            current.off("message", onMessage);
+            current.off("error", onError);
+            current.off("exit", onExit);
+            if (reusable) current.unref();
+            else {
+              if (worker === current) worker = undefined;
+              void current.terminate();
+            }
+            return true;
+          };
+          const onMessage = (reply: Reading | { thrown: unknown }) => {
+            if (!release(true)) return;
+            if ("thrown" in reply) reject(reply.thrown);
+            else resolve(reply);
+          };
+          const onError = (error: Error) => {
+            if (release(false)) reject(error);
+          };
+          const onExit = (code: number) => {
+            if (release(false))
+              reject(
+                new Error(
+                  `ttsc: build environment worker exited with code ${code} before answering`,
+                ),
+              );
+          };
+          current.on("message", onMessage);
+          current.on("error", onError);
+          current.on("exit", onExit);
+          try {
+            current.postMessage({ directory, env });
+          } catch (error) {
+            release(false);
+            reject(error);
+          }
+        }),
+    );
+    queue = request.then(
+      () => undefined,
+      () => undefined,
+    );
+    return request;
+  }
+
+  function acquireWorker(): Worker {
+    if (worker !== undefined) return worker;
+    const created = new Worker(
+      path.join(__dirname, "pluginBuildEnvironmentWorker.js"),
+      { env: SHARE_ENV },
+    );
+    worker = created;
+    const retire = () => {
+      if (worker === created) worker = undefined;
+    };
+    // Idle death must retire the cached thread without an unhandled error;
+    // active requests additionally own their terminal rejection listeners.
+    created.on("error", retire);
+    created.on("exit", retire);
+    return created;
+  }
+}

package/src/plugin/internal/source/PluginBuildEnvironmentWitness.ts

@@ -0,0 +1,233 @@
+import fs from "node:fs";
+
+import { E2ETrace } from "../../../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.
+ */
+export 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.
+   */
+  export 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.
+   */
+  export function add(
+    witness: Record | undefined,
+    file: string,
+    observed?: fs.BigIntStats,
+  ): void {
+    if (witness === undefined || witness.has(file)) return;
+    witness.set(file, signature(file, observed));
+  }
+
+  /**
+   * 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.
+   */
+  export function addLink(witness: Record | undefined, file: string): void {
+    const key = LINK_PREFIX + file;
+    if (witness === undefined || witness.has(key)) return;
+    witness.set(key, linkSignature(file));
+  }
+
+  /**
+   * 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.
+   */
+  export function addEnvironment(
+    witness: Record | undefined,
+    name: string,
+    value: string | undefined,
+  ): void {
+    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);
+  }
+
+  /**
+   * 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.
+   */
+  export function refuse(witness: Record | undefined, file: string): void {
+    witness?.set(file, UNWITNESSABLE);
+  }
+
+  /**
+   * 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.
+   *
+   * @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.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call must establish current validity; caching that answer would conceal external changes.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Validation retains no handles or additional historical state.
+   */
+  export function holds(witness: Record, observation?: string): boolean {
+    for (const [file, recorded] of witness) {
+      const current = file.startsWith(ENVIRONMENT_PREFIX)
+        ? environmentSignature(file.slice(ENVIRONMENT_PREFIX.length))
+        : file.startsWith(LINK_PREFIX)
+          ? linkSignature(file.slice(LINK_PREFIX.length))
+          : signature(file);
+      if (current !== recorded) {
+        E2ETrace.capabilityResolution(
+          "plugin-build-environment-witness-mismatch",
+          {
+            key: file,
+            recorded,
+            current,
+            refused: recorded === UNWITNESSABLE,
+            observation,
+          },
+        );
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /** 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: string): string {
+    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: string): string {
+    try {
+      const stat = fs.lstatSync(file, { bigint: true });
+      return JSON.stringify([
+        stat.dev.toString(),
+        stat.ino.toString(),
+        stat.size.toString(),
+        stat.mtimeNs.toString(),
+        stat.ctimeNs.toString(),
+        fs.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: string, observed?: fs.BigIntStats): string {
+    try {
+      const stat = observed ?? fs.statSync(file, { bigint: true });
+      return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(
+        ":",
+      );
+    } catch {
+      return "missing";
+    }
+  }
+}

package/src/plugin/internal/source/PluginBuildLockFence.ts

@@ -0,0 +1,26 @@
+/**
+ * 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/src/plugin/internal/source/PluginBuildLockLease.ts

@@ -0,0 +1,31 @@
+/**
+ * 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/src/plugin/internal/source/PluginBuildLockObservation.ts

@@ -0,0 +1,48 @@
+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" };