ttsc 0.30.3 → 0.31.0

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

@@ -0,0 +1,122 @@
+/**
+ * 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 declare 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;
+    /**
+     * 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): void;
+    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;
+    }
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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[];
+    export {};
+}

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

@@ -0,0 +1,307 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SourcePluginWorkspace = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const OwnedSynchronousProcess_1 = require("../../../internal/OwnedSynchronousProcess");
+const GoSourceInputs_1 = require("./GoSourceInputs");
+const copiesPluginSourceEntry_1 = require("./copiesPluginSourceEntry");
+const SourcePluginAdmission_1 = require("./SourcePluginAdmission");
+const formatGoWorkPath_1 = require("./formatGoWorkPath");
+const spawnGoTool_1 = require("./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.
+ */
+var SourcePluginWorkspace;
+(function (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.
+     */
+    function materialize(source, scratch) {
+        OwnedSynchronousProcess_1.OwnedSynchronousProcess.checkpoint();
+        node_fs_1.default.mkdirSync(scratch, { recursive: true });
+        node_fs_1.default.cpSync(source, scratch, {
+            recursive: true,
+            filter: (input) => {
+                OwnedSynchronousProcess_1.OwnedSynchronousProcess.checkpoint();
+                return (0, copiesPluginSourceEntry_1.copiesPluginSourceEntry)(source, input);
+            },
+        });
+    }
+    SourcePluginWorkspace.materialize = materialize;
+    /**
+     * 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.
+     */
+    function writeGoWork(scratchDir, useDirs, goBinary, pluginName, env, goModReader = createGoModReader(goBinary, pluginName, env)) {
+        validateSourceReplacements(scratchDir, useDirs, goModReader, pluginName);
+        const sourceInfo = goModReader.read(scratchDir);
+        const effectiveUseDirs = sourceInfo.modulePath === TTSC_GO_MODULE_PATH
+            ? useDirs.filter((dir) => {
+                OwnedSynchronousProcess_1.OwnedSynchronousProcess.checkpoint();
+                const modulePath = goModReader.read(dir).modulePath;
+                return (modulePath !== null &&
+                    !SourcePluginAdmission_1.SourcePluginAdmission.isManagedModule(modulePath));
+            })
+            : useDirs;
+        const useLines = ["\t."];
+        for (const dir of effectiveUseDirs) {
+            OwnedSynchronousProcess_1.OwnedSynchronousProcess.checkpoint();
+            useLines.push(`\t${(0, formatGoWorkPath_1.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}`;
+        node_fs_1.default.writeFileSync(node_path_1.default.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 = (0, spawnGoTool_1.spawnGoTool)(goBinary, ["work", "use"], {
+            cwd: scratchDir,
+            encoding: "utf8",
+            env: GoSourceInputs_1.GoSourceInputs.goBuildEnv(goBinary, undefined, env),
+            windowsHide: true,
+        });
+        OwnedSynchronousProcess_1.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}`);
+        }
+    }
+    SourcePluginWorkspace.writeGoWork = writeGoWork;
+    function validateSourceReplacements(scratchDir, useDirs, goModReader, pluginName) {
+        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_1.SourcePluginAdmission.requireSourceReplacements(sourceReplacements, overlayModules, pluginName);
+    }
+    function sourceBuildWorkspaceReplacements(useDirs, goModReader) {
+        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 => ${(0, formatGoWorkPath_1.formatGoWorkPath)(ttscRoot)}`,
+        ];
+    }
+    /**
+     * 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.
+     */
+    function createGoModReader(goBinary, pluginName, env) {
+        const cache = new Map();
+        return {
+            read(dir) {
+                OwnedSynchronousProcess_1.OwnedSynchronousProcess.checkpoint();
+                const resolved = node_path_1.default.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;
+            },
+        };
+    }
+    SourcePluginWorkspace.createGoModReader = createGoModReader;
+    function readGoModInfo(dir, goBinary, pluginName, env) {
+        if (!node_fs_1.default.existsSync(node_path_1.default.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 = node_os_1.default.tmpdir();
+        const result = (0, spawnGoTool_1.spawnGoTool)(goBinary, ["mod", "edit", "-json", node_path_1.default.join(dir, "go.mod")], {
+            cwd,
+            encoding: "utf8",
+            env: GoSourceInputs_1.GoSourceInputs.goBuildEnv(goBinary, undefined, env),
+            windowsHide: true,
+        });
+        OwnedSynchronousProcess_1.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;
+        try {
+            json = JSON.parse(result.stdout);
+        }
+        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() {
+        return {
+            modulePath: null,
+            replacements: [],
+        };
+    }
+    function jsonReplacementToGoModReplacement(replacement) {
+        const modulePath = replacement.Old?.Path;
+        if (modulePath === undefined) {
+            return null;
+        }
+        return {
+            modulePath,
+        };
+    }
+    function collectOverlayModulePaths(dirs, goModReader) {
+        const out = new Set();
+        for (const dir of dirs) {
+            OwnedSynchronousProcess_1.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.
+     */
+    function goSpawnFailureMessage(action, pluginName, goBinary, cwd, error) {
+        if (error.code === "ENOENT" &&
+            !(node_path_1.default.isAbsolute(goBinary) && node_fs_1.default.existsSync(goBinary))) {
+            return goToolchainNotFoundMessage(pluginName);
+        }
+        return `ttsc: ${action} failed to spawn ${goBinary} in ${cwd}: ${error.message}`;
+    }
+    SourcePluginWorkspace.goSpawnFailureMessage = goSpawnFailureMessage;
+    function goToolchainNotFoundMessage(pluginName) {
+        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.
+     */
+    function findTtscOverlayDirs() {
+        const ttscRoot = node_path_1.default.resolve(__dirname, "..", "..", "..", "..");
+        const dirs = [];
+        if (node_fs_1.default.existsSync(node_path_1.default.join(ttscRoot, "go.mod"))) {
+            dirs.push(ttscRoot);
+        }
+        const shimRoot = node_path_1.default.join(ttscRoot, "shim");
+        if (node_fs_1.default.existsSync(shimRoot)) {
+            walkForGoMod(shimRoot, dirs);
+        }
+        dirs.sort();
+        return dirs;
+    }
+    SourcePluginWorkspace.findTtscOverlayDirs = findTtscOverlayDirs;
+    function walkForGoMod(dir, out) {
+        OwnedSynchronousProcess_1.OwnedSynchronousProcess.checkpoint();
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        let hasGoMod = false;
+        for (const entry of entries) {
+            OwnedSynchronousProcess_1.OwnedSynchronousProcess.checkpoint();
+            if (entry.isFile() && entry.name === "go.mod") {
+                hasGoMod = true;
+            }
+        }
+        if (hasGoMod) {
+            out.push(dir);
+        }
+        for (const entry of entries) {
+            OwnedSynchronousProcess_1.OwnedSynchronousProcess.checkpoint();
+            if (!entry.isDirectory())
+                continue;
+            if (GoSourceInputs_1.GoSourceInputs.shouldPruneDirectory(entry.name))
+                continue;
+            walkForGoMod(node_path_1.default.join(dir, entry.name), out);
+        }
+    }
+    const TTSC_GO_MODULE_PATH = "github.com/samchon/ttsc/packages/ttsc";
+})(SourcePluginWorkspace || (exports.SourcePluginWorkspace = SourcePluginWorkspace = {}));
+//# sourceMappingURL=SourcePluginWorkspace.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SourcePluginWorkspace.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/SourcePluginWorkspace.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,sDAAyB;AACzB,0DAA6B;AAE7B,uFAAoF;AACpF,qDAAkD;AAClD,uEAAoE;AACpE,mEAAgE;AAChE,yDAAsD;AACtD,+CAA4C;AAE5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,IAAiB,qBAAqB,CA8ZrC;AA9ZD,WAAiB,qBAAqB;IACpC;;;;;;;;;;;OAWG;IACH,SAAgB,WAAW,CAAC,MAAc,EAAE,OAAe;QACzD,iDAAuB,CAAC,UAAU,EAAE,CAAC;QACrC,iBAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,iBAAE,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE;YACzB,SAAS,EAAE,IAAI;YACf,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;gBAChB,iDAAuB,CAAC,UAAU,EAAE,CAAC;gBACrC,OAAO,IAAA,iDAAuB,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAChD,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAVe,sBAAA,WAAW,cAU1B,CAAA;IAED;;;;;;;;;;;OAWG;IACH,SAAgB,WAAW,CACzB,UAAkB,EAClB,OAA0B,EAC1B,QAAgB,EAChB,UAAkB,EAClB,GAAsB,EACtB,WAAW,GAAgB,iBAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC;QAEvE,0BAA0B,CAAC,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;QACzE,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAChD,MAAM,gBAAgB,GACpB,UAAU,CAAC,UAAU,KAAK,mBAAmB;YAC3C,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE;gBACrB,iDAAuB,CAAC,UAAU,EAAE,CAAC;gBACrC,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC;gBACpD,OAAO,CACL,UAAU,KAAK,IAAI;oBACnB,CAAC,6CAAqB,CAAC,eAAe,CAAC,UAAU,CAAC,CACnD,CAAC;YACJ,CAAC,CAAC;YACJ,CAAC,CAAC,OAAO,CAAC;QACd,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,CAAC;QACzB,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;YACnC,iDAAuB,CAAC,UAAU,EAAE,CAAC;YACrC,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAA,mCAAgB,EAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,YAAY,GAAG,gCAAgC,CACnD,gBAAgB,EAChB,WAAW,CACZ,CAAC;QACF,MAAM,YAAY,GAChB,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QACtE,MAAM,MAAM,GAAG,UAAU,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,YAAY,EAAE,CAAC;QACjE,iBAAE,CAAC,aAAa,CAAC,mBAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACnE,8EAA8E;QAC9E,6EAA6E;QAC7E,6EAA6E;QAC7E,oEAAoE;QACpE,MAAM,OAAO,GAAG,IAAA,yBAAW,EAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE;YACrD,GAAG,EAAE,UAAU;YACf,QAAQ,EAAE,MAAM;YAChB,GAAG,EAAE,+BAAc,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,CAAC;YACxD,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,iDAAuB,CAAC,UAAU,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACb,qBAAqB,CACnB,gDAAgD,UAAU,GAAG,EAC7D,UAAU,EACV,QAAQ,EACR,UAAU,EACV,OAAO,CAAC,KAAK,CACd,CACF,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,sDAAsD,UAAU,cAAc,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,CACjH,CAAC;QACJ,CAAC;IACH,CAAC;IA7De,sBAAA,WAAW,cA6D1B,CAAA;IAED,SAAS,0BAA0B,CACjC,UAAkB,EAClB,OAA0B,EAC1B,WAAwB,EACxB,UAAkB;QAElB,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAChD,IAAI,UAAU,CAAC,UAAU,KAAK,mBAAmB,EAAE,CAAC;YAClD,OAAO;QACT,CAAC;QACD,MAAM,kBAAkB,GAAG,UAAU,CAAC,YAAY,CAAC;QACnD,IAAI,kBAAkB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpC,OAAO;QACT,CAAC;QACD,MAAM,cAAc,GAAG,yBAAyB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACvE,6CAAqB,CAAC,yBAAyB,CAC7C,kBAAkB,EAClB,cAAc,EACd,UAAU,CACX,CAAC;IACJ,CAAC;IAED,SAAS,gCAAgC,CACvC,OAA0B,EAC1B,WAAwB;QAExB,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAC3B,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,KAAK,mBAAmB,CAClE,CAAC;QACF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO;YACL,WAAW,mBAAmB,cAAc,IAAA,mCAAgB,EAAC,QAAQ,CAAC,EAAE;SACzE,CAAC;IACJ,CAAC;IA2DD;;;;;;;;;;;OAWG;IACH,SAAgB,iBAAiB,CAC/B,QAAgB,EAChB,UAAkB,EAClB,GAAsB;QAEtB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;QAC3C,OAAO;YACL,IAAI,CAAC,GAAG;gBACN,iDAAuB,CAAC,UAAU,EAAE,CAAC;gBACrC,MAAM,QAAQ,GAAG,mBAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBACnC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,OAAO,MAAM,CAAC;gBAChB,CAAC;gBACD,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;gBAChE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;gBAC1B,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC;IACJ,CAAC;IAnBe,sBAAA,iBAAiB,oBAmBhC,CAAA;IAED,SAAS,aAAa,CACpB,GAAW,EACX,QAAgB,EAChB,UAAkB,EAClB,GAAsB;QAEtB,IAAI,CAAC,iBAAE,CAAC,UAAU,CAAC,mBAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;YAC7C,OAAO,cAAc,EAAE,CAAC;QAC1B,CAAC;QAED,yEAAyE;QACzE,2EAA2E;QAC3E,4EAA4E;QAC5E,4EAA4E;QAC5E,uCAAuC;QACvC,MAAM,GAAG,GAAG,iBAAE,CAAC,MAAM,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,IAAA,yBAAW,EACxB,QAAQ,EACR,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAClD;YACE,GAAG;YACH,QAAQ,EAAE,MAAM;YAChB,GAAG,EAAE,+BAAc,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,CAAC;YACxD,WAAW,EAAE,IAAI;SAClB,CACF,CAAC;QACF,iDAAuB,CAAC,UAAU,EAAE,CAAC;QACrC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,qBAAqB,CACnB,8BAA8B,UAAU,GAAG,EAC3C,UAAU,EACV,QAAQ,EACR,GAAG,EACH,MAAM,CAAC,KAAK,CACb,CACF,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,oCAAoC,UAAU,cAAc,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,CAC7F,CAAC;QACJ,CAAC;QAED,IAAI,IAAe,CAAC;QACpB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAc,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,oCAAoC,UAAU,4BAC5C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACvD,EAAE,CACH,CAAC;QACJ,CAAC;QAED,OAAO;YACL,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,IAAI;YACrC,YAAY,EAAE,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;iBAC/B,GAAG,CAAC,iCAAiC,CAAC;iBACtC,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,KAAK,IAAI,CAAC;SACjD,CAAC;IACJ,CAAC;IAED,SAAS,cAAc;QACrB,OAAO;YACL,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,EAAE;SACjB,CAAC;IACJ,CAAC;IAED,SAAS,iCAAiC,CACxC,WAAsD;QAEtD,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC;QACzC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO;YACL,UAAU;SACX,CAAC;IACJ,CAAC;IAED,SAAS,yBAAyB,CAChC,IAAuB,EACvB,WAAwB;QAExB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;QAC9B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,iDAAuB,CAAC,UAAU,EAAE,CAAC;YACrC,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC;YACpD,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;gBACxB,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;;;;;;;;OAWG;IACH,SAAgB,qBAAqB,CACnC,MAAc,EACd,UAAkB,EAClB,QAAgB,EAChB,GAAW,EACX,KAAY;QAEZ,IACG,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAClD,CAAC,CAAC,mBAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,iBAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,EACvD,CAAC;YACD,OAAO,0BAA0B,CAAC,UAAU,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,SAAS,MAAM,oBAAoB,QAAQ,OAAO,GAAG,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACnF,CAAC;IAde,sBAAA,qBAAqB,wBAcpC,CAAA;IAED,SAAS,0BAA0B,CAAC,UAAkB;QACpD,OAAO,CACL,0BAA0B,UAAU,mDAAmD;YACvF,mFAAmF;YACnF,4CAA4C,CAC7C,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;OAWG;IACH,SAAgB,mBAAmB;QACjC,MAAM,QAAQ,GAAG,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACjE,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,IAAI,iBAAE,CAAC,UAAU,CAAC,mBAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtB,CAAC;QACD,MAAM,QAAQ,GAAG,mBAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,iBAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC/B,CAAC;QACD,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAZe,sBAAA,mBAAmB,sBAYlC,CAAA;IAED,SAAS,YAAY,CAAC,GAAW,EAAE,GAAa;QAC9C,iDAAuB,CAAC,UAAU,EAAE,CAAC;QACrC,IAAI,OAAoB,CAAC;QACzB,IAAI,CAAC;YACH,OAAO,GAAG,iBAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,iDAAuB,CAAC,UAAU,EAAE,CAAC;YACrC,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC9C,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC;QACD,IAAI,QAAQ,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,iDAAuB,CAAC,UAAU,EAAE,CAAC;YACrC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;gBAAE,SAAS;YACnC,IAAI,+BAAc,CAAC,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC9D,YAAY,CAAC,mBAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAGD,MAAM,mBAAmB,GAAG,uCAAuC,CAAC;AACtE,CAAC,EA9ZgB,qBAAqB,aAArB,qBAAqB,GAArB,qBAAqB,QA8ZrC"}

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

@@ -0,0 +1,35 @@
+import type { PluginBuildLockLease } from "./PluginBuildLockLease";
+/**
+ * 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 declare function acquirePluginBuildLock(lockDir: string): PluginBuildLockLease | null;