ttsc 0.30.3 → 0.31.0

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

@@ -0,0 +1,446 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { OwnedSynchronousProcess } from "../../../internal/OwnedSynchronousProcess";
+import { GoSourceInputs } from "./GoSourceInputs";
+import { copiesPluginSourceEntry } from "./copiesPluginSourceEntry";
+import { SourcePluginAdmission } from "./SourcePluginAdmission";
+import { formatGoWorkPath } from "./formatGoWorkPath";
+import { spawnGoTool } from "./spawnGoTool";
+
+/**
+ * Share generated Go workspace policy between package selection and building.
+ *
+ * Package selection must use the builder's overlays, generated workspace and
+ * selected tool rather than an ancestor go.work found in a source directory.
+ * A load may share installed-overlay manifest records under its pinned tool
+ * and effective environment; each unique scratch is read independently. The
+ * cold build owns a fresh reader over its proven materialized inputs. Go
+ * supplies the workspace's required Go and toolchain directives. These reads
+ * preserve the existing installation/version and sequential-stability limits.
+ *
+ * @evidence contracts/common.md#principled-implementation Shared manifest acquisition, managed replacement admission, overlay filtering and Go-owned workspace version selection keep metadata and compilation under the same workspace policy; callers own source materialization and effective environment.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns the generated workspace and its module reader, overlay discovery and Go launch diagnostics; no second manifest parser or build-tag interpreter is introduced.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual Go mod edit and work use commands interpret manifests; selected tool errors propagate and no static workspace version replaces Go's decision.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains shared policy and caller ownership; private helpers remain part of this operation's review surface.
+ * @evidence contracts/portability.md#os-neutral-implementation Native fs/path operations preserve path spelling and formatGoWorkPath owns Go syntax quoting; subprocesses use the existing native wrapper owner with hidden windows.
+ * @evidence contracts/performance.md#efficient-algorithms Workspace construction scans module and replacement populations; each module reader memoizes absolute directory results within its owning load or materialized build. Overlay discovery recursively scans admitted directories and sorts paths; native Go output and JSON parsing scale with complete bytes.
+ * @evidence contracts/performance.md#reuse-equivalent-work A metadata load shares equivalent installed-overlay observations under one pinned tool/effective environment; unique scratch paths are independent. A materialized build uses its own reader, and no memo crosses a load or changed environment. Metadata and build share policy rather than pretending their independently materialized sources are identical.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Readers retain module records only for their enclosing load or materialized build; command capture cleanup belongs to spawnGoTool and scratch lifetime belongs to the caller. Native commands can mutate Go-owned state and their selected-child completion does not prove arbitrary descendants retired.
+ */
+export namespace SourcePluginWorkspace {
+  /**
+   * Materialize one admitted source root under the native build copy policy.
+   *
+   * @evidence contracts/common.md#principled-implementation The shared source-entry predicate keeps native build and metadata copies under the keyed source policy; callers own root admission and any later digest proof.
+   * @evidence contracts/common.md#clear-and-simple-design One recursive copy owner serves source modules and metadata contexts.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No constraint interpretation or filename exception narrows the admitted copy.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes copying from later input-stability proof.
+   * @evidence contracts/portability.md#os-neutral-implementation Native filesystem operations preserve supported path identity and the shared predicate refuses observed non-root links.
+   * @evidence contracts/performance.md#efficient-algorithms Traverses admitted entries and copies their complete bytes; each entry checks cancellation and the shared naming/kind policy.
+   * @evidence contracts/performance.md#reuse-equivalent-work The caller owns and reuses the resulting scratch; no historical copy cache is retained.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Synchronous copy retains no handle after returning; partial scratch cleanup remains with the enclosing metadata/build owner.
+   */
+  export function materialize(source: string, scratch: string): void {
+    OwnedSynchronousProcess.checkpoint();
+    fs.mkdirSync(scratch, { recursive: true });
+    fs.cpSync(source, scratch, {
+      recursive: true,
+      filter: (input) => {
+        OwnedSynchronousProcess.checkpoint();
+        return copiesPluginSourceEntry(source, input);
+      },
+    });
+  }
+
+  /**
+   * Write the native builder's generated workspace and let Go select its version.
+   *
+   * @evidence contracts/common.md#principled-implementation Actual manifest records drive managed overlay filtering and replacement admission; Go work use supplies required directives.
+   * @evidence contracts/common.md#clear-and-simple-design The writer shares one reader across source/overlay queries and delegates manifest interpretation to Go.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No ancestor workspace or fixed Go version substitutes for this generated workspace; Go errors propagate.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+   * @evidence contracts/portability.md#os-neutral-implementation Native paths use formatGoWorkPath for Go syntax, and subprocess wrappers preserve native execution.
+   * @evidence contracts/performance.md#efficient-algorithms Traverses admitted overlay/replacement records and emits complete workspace text; delegated Go commands process manifests.
+   * @evidence contracts/performance.md#reuse-equivalent-work A supplied reader shares manifest observations with the same prepared-context caller; otherwise a private reader is allocated.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Workspace files belong to the caller's scratch; captures are released by spawnGoTool and module records by the reader's enclosing load.
+   */
+  export function writeGoWork(
+    scratchDir: string,
+    useDirs: readonly string[],
+    goBinary: string,
+    pluginName: string,
+    env: NodeJS.ProcessEnv,
+    goModReader: GoModReader = createGoModReader(goBinary, pluginName, env),
+  ): void {
+    validateSourceReplacements(scratchDir, useDirs, goModReader, pluginName);
+    const sourceInfo = goModReader.read(scratchDir);
+    const effectiveUseDirs =
+      sourceInfo.modulePath === TTSC_GO_MODULE_PATH
+        ? useDirs.filter((dir) => {
+            OwnedSynchronousProcess.checkpoint();
+            const modulePath = goModReader.read(dir).modulePath;
+            return (
+              modulePath !== null &&
+              !SourcePluginAdmission.isManagedModule(modulePath)
+            );
+          })
+        : useDirs;
+    const useLines = ["\t."];
+    for (const dir of effectiveUseDirs) {
+      OwnedSynchronousProcess.checkpoint();
+      useLines.push(`\t${formatGoWorkPath(dir)}`);
+    }
+    const replaceLines = sourceBuildWorkspaceReplacements(
+      effectiveUseDirs,
+      goModReader,
+    );
+    const replaceBlock =
+      replaceLines.length === 0 ? "" : `\n\n${replaceLines.join("\n")}\n`;
+    const goWork = `use (\n${useLines.join("\n")}\n)${replaceBlock}`;
+    fs.writeFileSync(path.join(scratchDir, "go.work"), goWork, "utf8");
+    // The Go tool sets the workspace's `go` directive: `go work use` raises it to
+    // what every listed module declares. A fixed directive rejects a module that
+    // declares a patch release (`go 1.26.0` against `go 1.26`), and a module the
+    // selected toolchain is too old for fails here with Go's own error.
+    const settled = spawnGoTool(goBinary, ["work", "use"], {
+      cwd: scratchDir,
+      encoding: "utf8",
+      env: GoSourceInputs.goBuildEnv(goBinary, undefined, env),
+      windowsHide: true,
+    });
+    OwnedSynchronousProcess.checkpoint();
+    if (settled.error) {
+      throw new Error(
+        goSpawnFailureMessage(
+          `setting the Go workspace version for plugin "${pluginName}"`,
+          pluginName,
+          goBinary,
+          scratchDir,
+          settled.error,
+        ),
+      );
+    }
+    if (settled.status !== 0) {
+      throw new Error(
+        `ttsc: setting the Go workspace version for plugin "${pluginName}" failed:\n${settled.stderr || settled.stdout}`,
+      );
+    }
+  }
+
+  function validateSourceReplacements(
+    scratchDir: string,
+    useDirs: readonly string[],
+    goModReader: GoModReader,
+    pluginName: string,
+  ): void {
+    const sourceInfo = goModReader.read(scratchDir);
+    if (sourceInfo.modulePath === TTSC_GO_MODULE_PATH) {
+      return;
+    }
+    const sourceReplacements = sourceInfo.replacements;
+    if (sourceReplacements.length === 0) {
+      return;
+    }
+    const overlayModules = collectOverlayModulePaths(useDirs, goModReader);
+    SourcePluginAdmission.requireSourceReplacements(
+      sourceReplacements,
+      overlayModules,
+      pluginName,
+    );
+  }
+
+  function sourceBuildWorkspaceReplacements(
+    useDirs: readonly string[],
+    goModReader: GoModReader,
+  ): string[] {
+    const ttscRoot = useDirs.find(
+      (dir) => goModReader.read(dir).modulePath === TTSC_GO_MODULE_PATH,
+    );
+    if (!ttscRoot) {
+      return [];
+    }
+    return [
+      `replace ${TTSC_GO_MODULE_PATH} v0.0.0 => ${formatGoWorkPath(ttscRoot)}`,
+    ];
+  }
+
+  interface GoModReplacement {
+    readonly modulePath: string;
+  }
+
+  interface GoModInfo {
+    readonly modulePath: string | null;
+    readonly replacements: readonly GoModReplacement[];
+  }
+
+  /**
+   * One selected-context manifest reader.
+   *
+   * @evidence contracts/common.md#principled-implementation Records are actual Go observations owned by the selected tool/environment context.
+   * @evidence contracts/common.md#clear-and-simple-design One read method exposes only module identity and replacement policy inputs.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts This type does not certify filesystem stability or manufacture compiler metadata.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+   * @evidence contracts/portability.md#os-neutral-implementation The supplied directory uses native spelling.
+   * @evidence contracts/performance.md#efficient-algorithms This type executes no algorithm.
+   * @evidence contracts/performance.md#reuse-equivalent-work Reuse belongs to createGoModReader and its caller's load scope.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The type acquires no handles; the actual reader owns its record map.
+   */
+  export interface GoModReader {
+    /**
+     * Observe the module at this native directory within the reader context.
+     *
+     * @evidence contracts/common.md#principled-implementation The signature associates a native directory with the selected reader's Go-owned module and replacement observation.
+     * @evidence contracts/common.md#clear-and-simple-design One input and one record expose the manifest policy needed by the workspace writer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The signature supplies no parser, alternate selection policy or stability certificate.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states that the result belongs to the reader context rather than a context-independent directory cache.
+     * @evidence contracts/portability.md#os-neutral-implementation The directory is a native filesystem path; its resolution belongs to the implementing reader.
+     * @evidence contracts/performance.md#efficient-algorithms A method signature executes no algorithm; createGoModReader owns acquisition and parsing.
+     * @evidence contracts/performance.md#reuse-equivalent-work Implementations supply observations within their selected tool/environment scope; this signature establishes no cross-context memo.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The signature acquires no resource; record retention belongs to the reader's enclosing load or materialized build.
+     */
+    read(dir: string): GoModInfo;
+  }
+
+  interface GoModJson {
+    readonly Module?: {
+      readonly Path?: string;
+    };
+    readonly Require?: readonly {
+      readonly Path?: string;
+      readonly Version?: string;
+    }[];
+    readonly Replace?: readonly {
+      readonly Old?: {
+        readonly Path?: string;
+        readonly Version?: string;
+      };
+      readonly New?: {
+        readonly Path?: string;
+        readonly Version?: string;
+      };
+    }[];
+  }
+
+  /**
+   * Read each module once through Go within one selected-tool context.
+   *
+   * @evidence contracts/common.md#principled-implementation Actual go mod edit JSON determines module/replacement identities; missing go.mod returns the existing empty module observation.
+   * @evidence contracts/common.md#clear-and-simple-design An absolute-directory map wraps one manifest acquisition helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No custom Go manifest parser or global context-insensitive memo is introduced.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+   * @evidence contracts/portability.md#os-neutral-implementation Native path resolution and temporary cwd avoid deep Windows working-directory limits; the selected tool handles manifest syntax.
+   * @evidence contracts/performance.md#efficient-algorithms Each distinct directory runs one existence query and at most one Go mod edit plus complete JSON parsing.
+   * @evidence contracts/performance.md#reuse-equivalent-work The caller may share this reader only within one load and the same pinned tool/effective environment; directory results are not cross-load authority.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The map grows with distinct observed directories for its caller's lifetime; process/output capture cleanup remains delegated.
+   */
+  export function createGoModReader(
+    goBinary: string,
+    pluginName: string,
+    env: NodeJS.ProcessEnv,
+  ): GoModReader {
+    const cache = new Map<string, GoModInfo>();
+    return {
+      read(dir) {
+        OwnedSynchronousProcess.checkpoint();
+        const resolved = path.resolve(dir);
+        const cached = cache.get(resolved);
+        if (cached !== undefined) {
+          return cached;
+        }
+        const info = readGoModInfo(resolved, goBinary, pluginName, env);
+        cache.set(resolved, info);
+        return info;
+      },
+    };
+  }
+
+  function readGoModInfo(
+    dir: string,
+    goBinary: string,
+    pluginName: string,
+    env: NodeJS.ProcessEnv,
+  ): GoModInfo {
+    if (!fs.existsSync(path.join(dir, "go.mod"))) {
+      return emptyGoModInfo();
+    }
+
+    // `go mod edit` takes the file as an argument, so the tool runs from the
+    // system temporary directory rather than from `dir`: a copy of an external
+    // source mirrors its absolute path below the build's scratch directory, and
+    // Windows refuses a working directory longer than MAX_PATH even where every
+    // path the build itself opens is fine.
+    const cwd = os.tmpdir();
+    const result = spawnGoTool(
+      goBinary,
+      ["mod", "edit", "-json", path.join(dir, "go.mod")],
+      {
+        cwd,
+        encoding: "utf8",
+        env: GoSourceInputs.goBuildEnv(goBinary, undefined, env),
+        windowsHide: true,
+      },
+    );
+    OwnedSynchronousProcess.checkpoint();
+    if (result.error) {
+      throw new Error(
+        goSpawnFailureMessage(
+          `reading go.mod for plugin "${pluginName}"`,
+          pluginName,
+          goBinary,
+          cwd,
+          result.error,
+        ),
+      );
+    }
+    if (result.status !== 0) {
+      throw new Error(
+        `ttsc: reading go.mod for plugin "${pluginName}" failed:\n${result.stderr || result.stdout}`,
+      );
+    }
+
+    let json: GoModJson;
+    try {
+      json = JSON.parse(result.stdout) as GoModJson;
+    } catch (error) {
+      throw new Error(
+        `ttsc: reading go.mod for plugin "${pluginName}" returned invalid JSON: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+
+    return {
+      modulePath: json.Module?.Path ?? null,
+      replacements: (json.Replace ?? [])
+        .map(jsonReplacementToGoModReplacement)
+        .filter((replacement) => replacement !== null),
+    };
+  }
+
+  function emptyGoModInfo(): GoModInfo {
+    return {
+      modulePath: null,
+      replacements: [],
+    };
+  }
+
+  function jsonReplacementToGoModReplacement(
+    replacement: NonNullable<GoModJson["Replace"]>[number],
+  ): GoModReplacement | null {
+    const modulePath = replacement.Old?.Path;
+    if (modulePath === undefined) {
+      return null;
+    }
+    return {
+      modulePath,
+    };
+  }
+
+  function collectOverlayModulePaths(
+    dirs: readonly string[],
+    goModReader: GoModReader,
+  ): Set<string> {
+    const out = new Set<string>();
+    for (const dir of dirs) {
+      OwnedSynchronousProcess.checkpoint();
+      const modulePath = goModReader.read(dir).modulePath;
+      if (modulePath !== null) {
+        out.add(modulePath);
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Describe a failed Go launch without confusing missing cwd and missing tool.
+   *
+   * @evidence contracts/common.md#principled-implementation ENOENT means missing toolchain only when the selected absolute executable is not present; other failures retain executable/cwd/system error.
+   * @evidence contracts/common.md#clear-and-simple-design One diagnostic adapter serves workspace and build commands.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing cwd is not mislabeled as a missing compiler.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+   * @evidence contracts/portability.md#os-neutral-implementation Native absolute-path/existence checks respect OS path semantics and original error codes.
+   * @evidence contracts/performance.md#efficient-algorithms Fixed error/path checks and diagnostic text construction delegate native lookup costs.
+   * @evidence contracts/performance.md#reuse-equivalent-work Current failure observations are interpreted independently, with no diagnostic cache.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources No native handle or retained failure registry is acquired.
+   */
+  export function goSpawnFailureMessage(
+    action: string,
+    pluginName: string,
+    goBinary: string,
+    cwd: string,
+    error: Error,
+  ): string {
+    if (
+      (error as NodeJS.ErrnoException).code === "ENOENT" &&
+      !(path.isAbsolute(goBinary) && fs.existsSync(goBinary))
+    ) {
+      return goToolchainNotFoundMessage(pluginName);
+    }
+    return `ttsc: ${action} failed to spawn ${goBinary} in ${cwd}: ${error.message}`;
+  }
+
+  function goToolchainNotFoundMessage(pluginName: string): string {
+    return (
+      `ttsc: building plugin "${pluginName}" failed because the Go toolchain was not found. ` +
+      `Reinstall ttsc with optional dependencies so the bundled Go compiler is present, ` +
+      `or set TTSC_GO_BINARY to an absolute path.`
+    );
+  }
+
+  /**
+   * Discover the installed native compiler/shim module overlays.
+   *
+   * @evidence contracts/common.md#principled-implementation Existing ttsc and shim go.mod files enter overlay selection under shared directory pruning policy.
+   * @evidence contracts/common.md#clear-and-simple-design One recursive walker gathers modules and one sort stabilizes ordering.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No guessed list of shim modules replaces current filesystem discovery.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+   * @evidence contracts/portability.md#os-neutral-implementation Native fs/path operations retain platform spelling and directory kinds.
+   * @evidence contracts/performance.md#efficient-algorithms Visits admitted directory entries recursively and sorts discovered module paths; lookup and path-byte costs remain delegated.
+   * @evidence contracts/performance.md#reuse-equivalent-work Each call observes installed layout afresh; contextual module readers separately reuse manifest content observations.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Directory arrays/path strings live only for this call/result; synchronous fs calls retain no open handle.
+   */
+  export function findTtscOverlayDirs(): readonly string[] {
+    const ttscRoot = path.resolve(__dirname, "..", "..", "..", "..");
+    const dirs: string[] = [];
+    if (fs.existsSync(path.join(ttscRoot, "go.mod"))) {
+      dirs.push(ttscRoot);
+    }
+    const shimRoot = path.join(ttscRoot, "shim");
+    if (fs.existsSync(shimRoot)) {
+      walkForGoMod(shimRoot, dirs);
+    }
+    dirs.sort();
+    return dirs;
+  }
+
+  function walkForGoMod(dir: string, out: string[]): void {
+    OwnedSynchronousProcess.checkpoint();
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    let hasGoMod = false;
+    for (const entry of entries) {
+      OwnedSynchronousProcess.checkpoint();
+      if (entry.isFile() && entry.name === "go.mod") {
+        hasGoMod = true;
+      }
+    }
+    if (hasGoMod) {
+      out.push(dir);
+    }
+    for (const entry of entries) {
+      OwnedSynchronousProcess.checkpoint();
+      if (!entry.isDirectory()) continue;
+      if (GoSourceInputs.shouldPruneDirectory(entry.name)) continue;
+      walkForGoMod(path.join(dir, entry.name), out);
+    }
+  }
+
+
+  const TTSC_GO_MODULE_PATH = "github.com/samchon/ttsc/packages/ttsc";
+}

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

@@ -0,0 +1,222 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { E2ETrace } from "../../../internal/E2ETrace";
+import { SourceNativeRetirement } from "../../../internal/SourceNativeRetirement";
+import { isContendedCandidateRename } from "../../../internal/isContendedCandidateRename";
+import type { PluginBuildLockLease } from "./PluginBuildLockLease";
+import { PluginBuildLockProtocol } from "./PluginBuildLockProtocol";
+
+/**
+ * Atomically acquire the current generation in a v3 coordination directory.
+ *
+ * A non-empty candidate is renamed to `current`. Directory rename cannot
+ * replace a non-empty `current`, so exactly one contender wins without an
+ * empty-owner publication window. `null` means admission was unavailable: a
+ * legacy path, contention or a missing rename pathname can produce it. It does
+ * not identify which peer won or prove another producer completed.
+ *
+ * The caller releases the returned lease in finally after its actual payload
+ * callback ends. Its independent completion nonce qualifies that task's marker.
+ * The persistent protocol root and retired identities outlive the binary cache
+ * entry. Old v2 clients use another namespace and do not share this version's
+ * build serialization. Legacy clients also cannot provide a cross-path
+ * compare-and-swap.
+ *
+ * Pending native guards return null so existing same-key bounded waiters
+ * continue without acquiring or stealing. Unknown or malformed guards refuse
+ * admission explicitly. Independent keys and shared Go caches stay concurrent.
+ *
+ * Opt-in diagnostics retain the already-observed destination and v3-layout
+ * decisions when initialization rename fails. They perform no extra filesystem
+ * query and do not classify an unknown layout as a successful peer.
+ *
+ * @evidence contracts/common.md#principled-implementation Publishing a complete nonempty candidate by directory rename gives one v3 contender ownership; another nonempty current cannot be replaced by that rename.
+ * @evidence contracts/common.md#clear-and-simple-design Acquisition owns complete metadata publication and candidate cleanup; the caller owns building and finally release through the returned lease.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A lost publication race returns null; it never force-removes a holder or substitutes uncoordinated success for failed acquisition.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain atomic publication, null, lease cleanup and the actual older-version serialization limits before the tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Node paths and directory operations preserve native naming, reject symlink legacy lock paths and distinguish rename contention through the platform error adapter.
+ * @evidence contracts/performance.md#efficient-algorithms Acquisition scans native guard metadata before a fixed set of lock operations; it neither scans sibling generations nor enumerates processes. Work includes native path construction/resolution, protocol marker bytes and host/PID/generation JSON construction and writes; initialization and attempt cleanup recursively remove their candidate contents.
+ * @evidence contracts/performance.md#reuse-equivalent-work A cache-key lock selects one producer among v3 consumers; binary identity and under-lock publication rechecking remain the build caller's responsibility, not assumptions made by a matching lock path.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Candidates have finally-based removal, which can fail or override the result. Successful return transfers a winning generation to the caller; cleanup failure after publication can leave ownership without a returned lease. Persistent roots remain per historical key for fencing, with no constant historical-key bound here.
+ */
+export function acquirePluginBuildLock(
+  lockDir: string,
+): PluginBuildLockLease | null {
+  // A legacy holder owns the old path. Never publish v3 ownership into that
+  // deletable namespace; wait until the legacy generation is released or
+  // reclaimed, then use the orthogonal persistent v3 directory.
+  if (pluginBuildLockPathExists(lockDir)) {
+    return null;
+  }
+  const protocolDir =
+    PluginBuildLockProtocol.pluginBuildLockProtocolDir(lockDir);
+  SourceNativeRetirement.assertAvailable(protocolDir);
+  if (SourceNativeRetirement.isProtected(protocolDir)) return null;
+  ensurePluginBuildLockProtocol(protocolDir);
+  // Close the initialization window as far as the legacy protocol permits. A
+  // legacy holder that appeared while v3 was initialized still blocks this
+  // acquisition. (A legacy executable cannot provide a true cross-path CAS.)
+  if (pluginBuildLockPathExists(lockDir)) {
+    return null;
+  }
+
+  const generation = crypto.randomBytes(16).toString("hex");
+  const completionNonce = crypto.randomBytes(16).toString("hex");
+  const candidateDir = path.join(protocolDir, `candidate-${generation}`);
+  fs.mkdirSync(candidateDir);
+  try {
+    fs.writeFileSync(
+      path.join(
+        candidateDir,
+        PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_GENERATION_FILE,
+      ),
+      `${generation}\n`,
+      { encoding: "utf8", flag: "wx" },
+    );
+    writePluginBuildLockOwner(candidateDir, generation, completionNonce);
+    try {
+      fs.renameSync(
+        candidateDir,
+        path.join(
+          protocolDir,
+          PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_CURRENT_DIR,
+        ),
+      );
+    } catch (error) {
+      if (
+        PluginBuildLockProtocol.isMissingPathError(error) ||
+        isContendedCandidateRename(error)
+      ) {
+        return null;
+      }
+      throw error;
+    }
+    SourceNativeRetirement.register({
+      fenceRoot: protocolDir,
+      retainedPaths: [lockDir, lockDir.slice(0, -".lock".length)],
+      generation,
+      completionNonce,
+    });
+    return { protocol: "v3", generation, completionNonce };
+  } finally {
+    // The candidate name contains this process's random generation and can
+    // never alias `current` or another contender's candidate.
+    fs.rmSync(candidateDir, { force: true, recursive: true });
+  }
+}
+
+function ensurePluginBuildLockProtocol(protocolDir: string): void {
+  if (PluginBuildLockProtocol.isPluginBuildLockProtocolV3(protocolDir)) {
+    return;
+  }
+
+  const generation = crypto.randomBytes(16).toString("hex");
+  const candidateDir = `${protocolDir}.candidate-${generation}`;
+  fs.mkdirSync(candidateDir);
+  try {
+    fs.mkdirSync(
+      path.join(
+        candidateDir,
+        PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_RETIRED_DIR,
+      ),
+    );
+    fs.writeFileSync(
+      path.join(
+        candidateDir,
+        PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_PROTOCOL_FILE,
+      ),
+      PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_PROTOCOL,
+      { encoding: "utf8", flag: "wx" },
+    );
+    try {
+      fs.renameSync(candidateDir, protocolDir);
+    } catch (error) {
+      const occupied = PluginBuildLockProtocol.isRenameDestinationOccupied(
+        error,
+        protocolDir,
+      );
+      // Preserve the original short-circuit: a missing destination does not
+      // acquire a new layout observation just for diagnostics.
+      const recognized =
+        occupied &&
+        PluginBuildLockProtocol.isPluginBuildLockProtocolV3(protocolDir);
+      if (process.env.TTSC_E2E_TRACE) {
+        try {
+          E2ETrace.capabilityResolution(
+            "plugin-build-lock-protocol-rename-refused",
+            {
+              protocolDir,
+              candidateDir,
+              destinationOccupied: occupied,
+              protocolV3: occupied ? recognized : null,
+              outcome: recognized ? "peer-initialized" : "rethrow",
+              errorName: error instanceof Error ? error.name : null,
+              errorMessage: error instanceof Error ? error.message : null,
+              errorCode:
+                typeof error === "object" &&
+                error !== null &&
+                "code" in error &&
+                typeof error.code === "string"
+                  ? error.code
+                  : null,
+              errorErrno:
+                typeof error === "object" &&
+                error !== null &&
+                "errno" in error &&
+                typeof error.errno === "number"
+                  ? error.errno
+                  : null,
+            },
+          );
+        } catch {
+          // Diagnostics cannot replace either peer acceptance or this error.
+        }
+      }
+      if (recognized) return;
+      throw error;
+    }
+  } finally {
+    fs.rmSync(candidateDir, { force: true, recursive: true });
+  }
+}
+
+function writePluginBuildLockOwner(
+  generationDir: string,
+  generation: string,
+  completionNonce: string,
+): void {
+  fs.writeFileSync(
+    path.join(
+      generationDir,
+      PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OWNER_FILE,
+    ),
+    `${JSON.stringify(
+      {
+        generation,
+        completionNonce,
+        hostname: os.hostname(),
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+}
+
+function pluginBuildLockPathExists(lockDir: string): boolean {
+  try {
+    const stats = fs.lstatSync(lockDir);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+      throw new Error(`ttsc: unsafe plugin build lock path: ${lockDir}`);
+    }
+    return true;
+  } catch (error) {
+    if (PluginBuildLockProtocol.isMissingPathError(error)) return false;
+    throw error;
+  }
+}