ttsc 0.30.4 → 0.31.1

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

@@ -0,0 +1,159 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { createFilesystemPathIdentityContext } from "../../../internal/pathIdentity/createFilesystemPathIdentityContext";
+import { PluginBuildLockOwner } from "./PluginBuildLockOwner";
+import { PluginBuildLockProtocol } from "./PluginBuildLockProtocol";
+
+/** Process-owned read reservations, one per returned binary cache key. */
+const reservations = new Map<string, string>();
+
+/**
+ * Register reader reservations for returned executable paths until their
+ * consumer process ends. Cooperating collectors preserve these records;
+ * external deletion or replacement is not prevented by a token. Registration
+ * and collection both run under the cache key's build lease. Reservations are
+ * readers, not build generations: other readers can share the same executable
+ * without holding that exclusive lease during execution.
+ *
+ * @evidence contracts/common.md#principled-implementation Per-key publication serializes with deletion while independent reader records preserve concurrent consumers through process lifetime.
+ * @evidence contracts/common.md#clear-and-simple-design Registration, local reuse and collector liveness share one reservation representation, separate from builder-generation completion.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual native process absence authorizes collection; recency, elapsed time and completed builds do not establish that returned paths are unused.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the exclusive registration premise and distinguishes reader lifetime from producer completion.
+ * @evidence contracts/portability.md#os-neutral-implementation Native directory metadata, hostname and signal-zero process observations supply ownership without OS-specific lifetime assumptions.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Member operations own registration and inspection work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work holds and retain own process-local reservation reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources retain owns reservation lifetime and release.
+ */
+export namespace PluginBinaryUse {
+  /**
+   * Register this process under the key lease before its binary is returned.
+   * One record serves repeated acquisitions of this same key until exit.
+   *
+   * @evidence contracts/common.md#principled-implementation Caller-held key ownership serializes reader publication with GC; hostname/PID-qualified records share one current-process reader across module instances without authorizing deletion by PID age.
+   * @evidence contracts/common.md#clear-and-simple-design One reservation per physical key avoids per-call reader generations; process facts reuse the shared owner parser and liveness policy.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Publication failures throw rather than returning an unprotected path; no exit callback pretends the process has ended while later callbacks may still consume its binary.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states registration timing, held-lease premise and repeated-key reuse.
+   * @evidence contracts/portability.md#os-neutral-implementation Node mkdir, lstat and UTF-8 owner records preserve native filesystem behavior; no shell or OS-wide case folding supplies ownership.
+   * @evidence contracts/performance.md#efficient-algorithms A first key performs native identity resolution (after the initial holds query), scans U reader entries and owner JSON/path/hostname bytes, and writes one host/PID record. Dead-token removal also traverses their stored directory contents. Repeated keys still resolve identity and check token existence, without scanning unrelated keys; identity resolution includes its delegated native path and case-policy observations.
+   * @evidence contracts/performance.md#reuse-equivalent-work A live process reuses one reader token for the same key, while other processes publish their own independent tokens.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources One token and map entry remain per distinct physical key until process death; there is no constant key-count bound. Later admission or GC collects proven-dead tokens, while live, remote or unknown ownership is retained without an age bound; no native handle or exit hook remains installed.
+   */
+  export function retain(cacheDir: string): void {
+    if (holds(cacheDir)) return;
+    const identity = createFilesystemPathIdentityContext().resolve(cacheDir);
+    const root = path.join(identity.path, ".binary-users");
+    fs.mkdirSync(root, { recursive: true });
+    const stats = fs.lstatSync(root);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+      throw new Error(`ttsc: invalid plugin binary reader directory: ${root}`);
+    }
+    hasLiveOwners(identity.path);
+    const owner = { hostname: os.hostname(), pid: process.pid };
+    const token = path.join(
+      root,
+      crypto
+        .createHash("sha256")
+        .update(JSON.stringify([owner.hostname.toLowerCase(), owner.pid]))
+        .digest("hex"),
+    );
+    if (fs.existsSync(token)) {
+      const previous = PluginBuildLockOwner.read(token);
+      const stats = fs.lstatSync(token);
+      if (
+        !stats.isDirectory() ||
+        stats.isSymbolicLink() ||
+        previous?.pid !== owner.pid ||
+        previous.hostname.toLowerCase() !== owner.hostname.toLowerCase()
+      ) {
+        throw new Error(
+          `ttsc: invalid plugin binary reader ownership: ${token}`,
+        );
+      }
+      reservations.set(identity.key, token);
+      return;
+    }
+    fs.mkdirSync(token);
+    try {
+      fs.writeFileSync(
+        path.join(token, PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OWNER_FILE),
+        JSON.stringify(owner),
+        { flag: "wx", encoding: "utf8" },
+      );
+    } catch (error) {
+      try {
+        fs.rmSync(token, { recursive: true, force: true });
+      } catch {}
+      throw error;
+    }
+    reservations.set(identity.key, token);
+  }
+
+  /**
+   * Whether the pathname of this process's previously published reader token
+   * still exists. This permits local reuse under the cooperating cache-owner
+   * premise; existence alone does not revalidate its kind, record or
+   * incarnation.
+   *
+   * @evidence contracts/common.md#principled-implementation Only a pathname previously recorded by retain authorizes local reuse, and an absent pathname requires acquisition again. This existence query assumes cache ownership prevents external token replacement; it does not reread ownership or pin an incarnation.
+   * @evidence contracts/common.md#clear-and-simple-design One process map and native existence observation answer the previously-owned-token question without interpreting other consumers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A recent use timestamp or matching binary filename cannot supply a missing reader reservation.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes previously published pathname existence from revalidation of token ownership.
+   * @evidence contracts/portability.md#os-neutral-implementation Node observes the token path directly without platform-specific process enumeration.
+   * @evidence contracts/performance.md#efficient-algorithms Delegated native cache-entry identity resolution includes path text and case-policy observations; one expected-constant map lookup and a token existence check avoid reader population scans. Hashing the identity key also depends on its string length.
+   * @evidence contracts/performance.md#reuse-equivalent-work A repeated key reuses its process-owned token until it is absent or the process ends.
+   *
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources retain owns the token and map lifetime; this query acquires no handle.
+   */
+  export function holds(cacheDir: string): boolean {
+    const key = createFilesystemPathIdentityContext().resolve(cacheDir).key;
+    const token = reservations.get(key);
+    return token !== undefined && fs.existsSync(token);
+  }
+
+  /**
+   * Preserve any live or unprovable reader while holding the deletion lease.
+   * Only proven absent local processes authorize removal of their records.
+   *
+   * @evidence contracts/common.md#principled-implementation The caller's key lease excludes concurrent registration, and shared native liveness proves local absence; malformed, remote or unreadable ownership preserves the payload.
+   * @evidence contracts/common.md#clear-and-simple-design One conservative reader scan shares the existing process-owner parser rather than treating producer completion as reader completion.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown ownership and linked/nonordinary reservation directories never authorize deletion; age and recency are not substituted for liveness.
+   * @evidence contracts/common.md#meaningful-documentation Native prose defines held-deletion-lease timing and exact absence requirements.
+   * @evidence contracts/portability.md#os-neutral-implementation Native lstat directory kinds and the shared hostname/signal-zero process boundary supply conservative reclamation evidence.
+   * @evidence contracts/performance.md#efficient-algorithms A scan visits U reader entries, their paths and JSON/hostname bytes, with at most one native liveness probe per valid record. Recursive deletion adds the contents of each dead token directory. Live owners do not stop scanning, but a native failure ends the scan conservatively, so later dead tokens may remain.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Reader population and liveness must be freshly observed under the collector's lease.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Proven-dead tokens are removed; failed deletion preserves the payload. The scan holds no process or filesystem handle after its synchronous calls.
+   */
+  export function hasLiveOwners(cacheDir: string): boolean {
+    const root = path.join(cacheDir, ".binary-users");
+    try {
+      let stats: fs.Stats;
+      try {
+        stats = fs.lstatSync(root);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+        return true;
+      }
+      if (!stats.isDirectory() || stats.isSymbolicLink()) return true;
+      let protectedOwner = false;
+      for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.isSymbolicLink()) {
+          protectedOwner = true;
+          continue;
+        }
+        const token = path.join(root, entry.name);
+        const owner = PluginBuildLockOwner.read(token);
+        if (owner === null || !PluginBuildLockOwner.gone(owner)) {
+          protectedOwner = true;
+        } else fs.rmSync(token, { recursive: true, force: true });
+      }
+      return protectedOwner;
+    } catch {
+      return true;
+    }
+  }
+}

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

@@ -0,0 +1,34 @@
+import type { PluginBuildLockFence } from "./PluginBuildLockFence";
+
+/**
+ * Outcome of one waiting session on another process's plugin build lock.
+ *
+ * - `published`: the binary pathname was observed to exist; the caller owns
+ *   cache-key trust and reader admission before reuse, not this existence
+ *   test.
+ * - `released`: the inspector supplied a released handoff and the following
+ *   binary existence check was false. Retry ordinary acquisition without
+ *   reporting or removing a holder; a successor may already have appeared.
+ * - `abandoned`: the inspector supplied an abandoned-owner observation; the
+ *   caller may report and retire precisely the attached generation.
+ *
+ * The fence permits retirement only of the generation this wait observed;
+ * wait-budget expiry throws without returning a retirement capability.
+ *
+ * @evidence contracts/common.md#principled-implementation The discriminated union distinguishes published reuse, ordinary reacquisition and fenced retirement; only retirement carries the reason and exact observed-generation capability.
+ * @evidence contracts/common.md#clear-and-simple-design Three outcomes expose the caller's next action without optional reason/fence fields on unrelated states.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Elapsed time never supplies an abandoned result; a bounded-wait failure leaves the potentially active task's ownership intact.
+ * @evidence contracts/common.md#meaningful-documentation Native bullets explain acquisition/retirement consequences and distinguish timeout failure from a returned abandonment capability, with blank separation before tags.
+ * @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.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export type PluginBinaryWaitResult =
+  | { outcome: "published" }
+  | { outcome: "released" }
+  | {
+      outcome: "abandoned";
+      reason: string;
+      fence: PluginBuildLockFence;
+    };

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

@@ -0,0 +1,273 @@
+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;
+  }
+
+  /**
+   * Qualify a batch in one synchronous observation transaction. Shared SDK
+   * paths and the complete variable identity are read once, even when several
+   * plugin directories use them. Missing readings remain explicitly missing.
+   *
+   * WARNING (#1712): this map belongs only to the following synchronous proof.
+   * Never retain it across an await, delivery, build boundary or publication. A
+   * process-permanent positive witness would miss changed Go tools and GOENV
+   * files (#1516); independently checking it in every helper instead multiplies
+   * a thousands-file GOROOT scan by modules and proof layers.
+   *
+   * @evidence contracts/common.md#principled-implementation One current variable snapshot and native path observation are compared against each reading's own expected witness; conflicting expected states cannot both pass.
+   * @evidence contracts/common.md#clear-and-simple-design One batch operation owns shared validation without changing synchronous reads or native worker publication boundaries.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Undefined is retained for absent or stale authority; no positive verdict survives this explicit observation transaction.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs state scope, missing semantics and the performance/correctness regressions prevented by the lifetime restriction.
+   * @evidence contracts/portability.md#os-neutral-implementation Existing native witness keys preserve filesystem, link and ambient-variable distinctions; no platform case assumption is added.
+   * @evidence contracts/performance.md#efficient-algorithms Full variables are indexed once; each distinct witnessed path is queried once while each reading compares its own witness entries. Work is proportional to variable bytes, total witness entries and unique native dependencies rather than repeated native SDK scans.
+   * @evidence contracts/performance.md#reuse-equivalent-work Only current native observations within this synchronous batch are shared; the returned digests do not authorize reuse after another asynchronous boundary.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The native observation map is call-local and the digest map transfers to its immediate proof caller; no handle or historical registry is acquired.
+   */
+  export function cachedAll(
+    directories: Iterable<string>,
+  ): ReadonlyMap<string, string | undefined> {
+    let variables: string | undefined;
+    const current = new Map<string, string>();
+    const result = new Map<string, string | undefined>();
+    for (const directory of directories) {
+      if (result.has(directory)) continue;
+      const known = readings.get(
+        directory + (variables ??= key("", process.env)),
+      );
+      result.set(
+        directory,
+        known !== undefined &&
+          PluginBuildEnvironmentWitness.holds(known.witness, undefined, current)
+          ? known.environment
+          : undefined,
+      );
+    }
+    return result;
+  }
+
+  /**
+   * 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;
+  }
+}