ttsc 0.30.4 → 0.31.1

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

@@ -0,0 +1,153 @@
+/**
+ * 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 shares early replacement watch, package and build manifest records under
+ * its pinned tool and effective environment; identical current bytes in
+ * independently proven scratch inputs share their Go parse. A moved native tool
+ * clears that reader's syntax memo, and a toolchain retry starts a new reader
+ * scope. Each caller has a diagnostic view over the shared native reader state;
+ * one plugin cannot inherit another plugin's failure label (#1720). 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 reader reads current manifest bytes and memoizes equivalent Go syntax within its pinned native tool/load. 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 Metadata and materialized builds share Go parsing only for identical current manifest bytes under the same pinned tool/effective environment. Independent materialization/content proof remains with each caller; tool movement clears syntax reuse and retries start another scope.
+ * @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[];
+        readonly directives: NonNullable<GoModJson["Replace"]>;
+    }
+    /**
+     * 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.
+         * The optional diagnostic owner overrides the creating caller's label only;
+         * it changes no selected-tool, environment or byte-content authority.
+         *
+         * @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 A directory and optional diagnostic label expose manifest policy without treating the label as native cache authority.
+         * @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 selected-context result ownership and the optional caller label, which changes failure attribution only.
+         * @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, diagnosticPlugin?: 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 current manifest bytes and share identical Go parses within one pinned
+     * selected-tool/load context, including copied scratch modules. An optional
+     * registry shares native reader state from the first watch query onward; its
+     * owner must keep one fixed effective environment and discard it on retry.
+     * Caller views share that native state and syntax, while each default
+     * diagnostic label remains with its current caller.
+     *
+     * @evidence contracts/common.md#principled-implementation Actual go mod edit JSON determines module/replacement identities; current bytes, selected/dispatched-tool metadata and Go's environment-file witness qualify reuse under the existing metadata-distinguishability premise. Environment values are copied at reader creation. Missing go.mod returns the existing empty module observation, and moving tool/manifest inputs cannot publish a parsed record.
+     * @evidence contracts/common.md#clear-and-simple-design One factory acquires load-owned native reader state by selected tool; a thin caller view forwards its diagnostic label without duplicating the byte-content map. Current reads and post-parse byte/tool comparisons qualify insertion.
+     * @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 Reader acquisition performs a selected-tool registry lookup; every nonmissing read qualifies tool/environment metadata and reads current manifest bytes. A cold or stale witness first observes the selected launcher; an unavailable or nonfile launcher skips optional environment acquisition and permits only the actual uncached parse attempt. An observed file lends its same pre-read stat to the witness before acquiring current Go values and GOENV evidence through the common reader, without a GOROOT walk. Only complete native GOENV/GOROOT locations qualify syntax sharing; a dispatched tool is witnessed before parsing. Unavailable native environment acquisition disables syntax sharing while preserving actual parse success or failure. Each distinct byte string that earns stable successful syntax in that tool epoch runs Go mod edit and complete JSON parsing once, then rechecks bytes/tool metadata before caching; copied manifests share that parse. Failed queries remain uncached and report the current caller's diagnostic label.
+     * @evidence contracts/performance.md#reuse-equivalent-work The caller may share this reader only within one load and the same pinned tool/effective environment; parsed syntax is not cross-load or native containment authority. Caller views share native state while preserving failure attribution; diagnostic labels are not syntax cache inputs.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The map retains distinct manifest bytes and parsed syntax for its caller's load/build lifetime; process/output capture cleanup remains delegated.
+     */
+    export function createGoModReader(goBinary: string, pluginName: string, env: NodeJS.ProcessEnv, readers?: Map<string, GoModReader>): 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,394 @@
+"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 GoEnvironmentReading_1 = require("./GoEnvironmentReading");
+const GoSourceInputs_1 = require("./GoSourceInputs");
+const PluginBuildEnvironmentWitness_1 = require("./PluginBuildEnvironmentWitness");
+const SourcePluginAdmission_1 = require("./SourcePluginAdmission");
+const copiesPluginSourceEntry_1 = require("./copiesPluginSourceEntry");
+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 shares early replacement watch, package and build manifest records under
+ * its pinned tool and effective environment; identical current bytes in
+ * independently proven scratch inputs share their Go parse. A moved native tool
+ * clears that reader's syntax memo, and a toolchain retry starts a new reader
+ * scope. Each caller has a diagnostic view over the shared native reader state;
+ * one plugin cannot inherit another plugin's failure label (#1720). 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 reader reads current manifest bytes and memoizes equivalent Go syntax within its pinned native tool/load. 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 Metadata and materialized builds share Go parsing only for identical current manifest bytes under the same pinned tool/effective environment. Independent materialization/content proof remains with each caller; tool movement clears syntax reuse and retries start another scope.
+ * @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 current manifest bytes and share identical Go parses within one pinned
+     * selected-tool/load context, including copied scratch modules. An optional
+     * registry shares native reader state from the first watch query onward; its
+     * owner must keep one fixed effective environment and discard it on retry.
+     * Caller views share that native state and syntax, while each default
+     * diagnostic label remains with its current caller.
+     *
+     * @evidence contracts/common.md#principled-implementation Actual go mod edit JSON determines module/replacement identities; current bytes, selected/dispatched-tool metadata and Go's environment-file witness qualify reuse under the existing metadata-distinguishability premise. Environment values are copied at reader creation. Missing go.mod returns the existing empty module observation, and moving tool/manifest inputs cannot publish a parsed record.
+     * @evidence contracts/common.md#clear-and-simple-design One factory acquires load-owned native reader state by selected tool; a thin caller view forwards its diagnostic label without duplicating the byte-content map. Current reads and post-parse byte/tool comparisons qualify insertion.
+     * @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 Reader acquisition performs a selected-tool registry lookup; every nonmissing read qualifies tool/environment metadata and reads current manifest bytes. A cold or stale witness first observes the selected launcher; an unavailable or nonfile launcher skips optional environment acquisition and permits only the actual uncached parse attempt. An observed file lends its same pre-read stat to the witness before acquiring current Go values and GOENV evidence through the common reader, without a GOROOT walk. Only complete native GOENV/GOROOT locations qualify syntax sharing; a dispatched tool is witnessed before parsing. Unavailable native environment acquisition disables syntax sharing while preserving actual parse success or failure. Each distinct byte string that earns stable successful syntax in that tool epoch runs Go mod edit and complete JSON parsing once, then rechecks bytes/tool metadata before caching; copied manifests share that parse. Failed queries remain uncached and report the current caller's diagnostic label.
+     * @evidence contracts/performance.md#reuse-equivalent-work The caller may share this reader only within one load and the same pinned tool/effective environment; parsed syntax is not cross-load or native containment authority. Caller views share native state while preserving failure attribution; diagnostic labels are not syntax cache inputs.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The map retains distinct manifest bytes and parsed syntax for its caller's load/build lifetime; process/output capture cleanup remains delegated.
+     */
+    function createGoModReader(goBinary, pluginName, env, readers) {
+        const existing = readers?.get(goBinary);
+        if (existing !== undefined)
+            return {
+                read: (dir, diagnosticPlugin = pluginName) => existing.read(dir, diagnosticPlugin),
+            };
+        // WARNING (#1712): parse identical bytes once in this pinned tool/load
+        // context, including early replacement watch projection and copied scratch
+        // manifests. The optional registry belongs to one fixed effective environment
+        // and one load; it is never shared with a toolchain retry. Always read current bytes;
+        // a pathname or metadata-only memo misses manifest edits. Never promote
+        // this map to a process cache: tool/environment epochs change Go authority.
+        // Fixed variable strings do not freeze GOENV or a dispatched Go executable.
+        // Requalify their actual native evidence before every syntax hit; missing
+        // environment authority permits a fresh parse only, never positive reuse.
+        // WARNING (#1720): diagnostic names are per caller, not a syntax/cache input.
+        // Shared views must forward their current label to every failed native read.
+        const cache = new Map();
+        const environment = { ...env };
+        let toolWitness;
+        const reader = {
+            read(dir, diagnosticPlugin = pluginName) {
+                OwnedSynchronousProcess_1.OwnedSynchronousProcess.checkpoint();
+                const resolved = node_path_1.default.resolve(dir);
+                const manifest = node_path_1.default.join(resolved, "go.mod");
+                let bytes;
+                try {
+                    bytes = node_fs_1.default.readFileSync(manifest);
+                }
+                catch (error) {
+                    if (error.code === "ENOENT")
+                        return emptyGoModInfo();
+                    throw error;
+                }
+                if (toolWitness === undefined ||
+                    !PluginBuildEnvironmentWitness_1.PluginBuildEnvironmentWitness.holds(toolWitness)) {
+                    cache.clear();
+                    const witness = new Map();
+                    let launcher;
+                    try {
+                        launcher = node_fs_1.default.statSync(goBinary, { bigint: true });
+                    }
+                    catch {
+                        // Unavailable metadata cannot qualify optional syntax reuse.
+                    }
+                    if (launcher?.isFile() === true)
+                        PluginBuildEnvironmentWitness_1.PluginBuildEnvironmentWitness.add(witness, goBinary, launcher);
+                    // GOENV can change toolchain selection without changing env strings.
+                    // Share its existing native discovery owner; do not scan GOROOT here.
+                    // Do not launch a missing/unobservable tool twice just to learn that
+                    // optional cache qualification is unavailable (#1712). The actual
+                    // mod-edit attempt below still owns its current failure or success.
+                    const observed = launcher?.isFile() === true
+                        ? GoEnvironmentReading_1.GoEnvironmentReading.read(goBinary, node_os_1.default.tmpdir(), environment, ["GOROOT"], witness)
+                        : undefined;
+                    if (typeof observed?.GOROOT === "string" &&
+                        node_path_1.default.isAbsolute(observed.GOROOT))
+                        PluginBuildEnvironmentWitness_1.PluginBuildEnvironmentWitness.add(witness, node_path_1.default.join(observed.GOROOT, "bin", process.platform === "win32" ? "go.exe" : "go"));
+                    const complete = typeof observed?.GOROOT === "string" &&
+                        node_path_1.default.isAbsolute(observed.GOROOT) &&
+                        typeof observed.GOENV === "string" &&
+                        (observed.GOENV === "off" || node_path_1.default.isAbsolute(observed.GOENV));
+                    toolWitness =
+                        complete && PluginBuildEnvironmentWitness_1.PluginBuildEnvironmentWitness.holds(witness)
+                            ? witness
+                            : undefined;
+                }
+                // UTF-8 decoding is lossy for malformed input. Only identical bytes
+                // can share Go syntax, even when Go serializes two inputs identically.
+                const byteKey = bytes.toString("base64");
+                const cached = cache.get(byteKey);
+                if (cached !== undefined) {
+                    return cached;
+                }
+                const info = readGoModInfo(resolved, goBinary, diagnosticPlugin, environment);
+                if (!node_fs_1.default.readFileSync(manifest).equals(bytes))
+                    throw new Error(`ttsc: go.mod changed while Go was reading ${manifest}`);
+                if (toolWitness !== undefined &&
+                    !PluginBuildEnvironmentWitness_1.PluginBuildEnvironmentWitness.holds(toolWitness))
+                    throw new Error(`ttsc: Go tool or environment changed while reading ${manifest}`);
+                // An unavailable environment observation can still execute a fresh Go
+                // parse, but it cannot authorize sharing that result on another call.
+                if (toolWitness !== undefined)
+                    cache.set(byteKey, info);
+                return info;
+            },
+        };
+        readers?.set(goBinary, reader);
+        return reader;
+    }
+    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,
+            directives: json.Replace ?? [],
+            replacements: (json.Replace ?? [])
+                .map(jsonReplacementToGoModReplacement)
+                .filter((replacement) => replacement !== null),
+        };
+    }
+    function emptyGoModInfo() {
+        return {
+            modulePath: null,
+            directives: [],
+            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":"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"}

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;