ttsc 0.30.4 → 0.31.1

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

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginBuildVersions = pluginBuildVersions;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Package-version labels used by plugin build keys (`computeCacheKey`) and
+ * persisted transform identities. These are metadata inputs, not a measurement
+ * of the executable actually selected for an invocation.
+ *
+ * Transform reuse also depends on inputs, plugin sources, build environment and
+ * the producer's declared proofs; these labels alone certify none of them. A
+ * consumer that keeps a transform's output beyond the process that produced it,
+ * as a persisted shared compile of `@ttsc/unplugin` is, names it by these
+ * versions with the rule the build applies instead of a copy of it: ttsc's own
+ * package version, and the version of the `typescript` package the project
+ * resolves, or `"unknown"` when resolution/read/parse fails or its version is
+ * absent. The host label falls back to `"0.0.0"` and is cached even after an
+ * unsuccessful first read. The host installation is assumed stable for the
+ * process lifetime; changing its manifest does not refresh that label.
+ *
+ * @param projectRoot The project base used to resolve
+ *   `typescript/package.json`.
+ * @evidence contracts/common.md#principled-implementation Package-version labels supply the same metadata tuple used by plugin keys; absent/unreadable metadata receives the documented unknown/default label rather than an executable identity certificate.
+ * @evidence contracts/common.md#clear-and-simple-design Host-version and project-version readers are separate because one installation is stable within the process while project resolution varies per call.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Node package resolution determines the actual project dependency; no particular project or fixture version is embedded.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains persisted-output consumers, metadata fallbacks and the process-stable host premise without claiming that version labels establish executable or output equivalence.
+ * @evidence contracts/portability.md#os-neutral-implementation Node createRequire and path APIs locate package metadata using native module resolution without manual separator or case normalization.
+ * @evidence contracts/performance.md#efficient-algorithms Each call performs project package resolution and, when successful, reads/parses its manifest bytes; module search/path work and metadata size are not fixed by one logical manifest lookup. The host manifest is attempted only on the first invocation, including native path and JSON costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work All callers share the host installation's process-stable version; the project compiler version is resolved afresh so different project roots do not share a false identity.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This helper retains one host-version label for the process lifetime, whose text follows its manifest value rather than a fixed byte limit; the helper's retained label count is independent of project count. Native module-resolution caches belong to Node, and synchronous file reads leave no persistent descriptor here.
+ */
+function pluginBuildVersions(projectRoot) {
+    return { tsgo: readTsgoVersion(projectRoot), ttsc: readTtscVersion() };
+}
+let cachedTtscVersion = null;
+function readTtscVersion() {
+    if (cachedTtscVersion !== null)
+        return cachedTtscVersion;
+    try {
+        const file = node_path_1.default.resolve(__dirname, "..", "..", "..", "..", "package.json");
+        const pkg = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+        cachedTtscVersion = pkg.version ?? "0.0.0";
+    }
+    catch {
+        cachedTtscVersion = "0.0.0";
+    }
+    return cachedTtscVersion;
+}
+function readTsgoVersion(projectRoot) {
+    try {
+        const projectRequire = (0, node_module_1.createRequire)(node_path_1.default.join(projectRoot, "package.json"));
+        const pkgPath = projectRequire.resolve("typescript/package.json");
+        const pkg = JSON.parse(node_fs_1.default.readFileSync(pkgPath, "utf8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+//# sourceMappingURL=pluginBuildVersions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginBuildVersions.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/pluginBuildVersions.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,6CAA4C;AAC5C,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,6BAAoC,WAAmB;IAIrD,OAAO,EAAE,IAAI,EAAE,eAAe,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,CAAC;AACzE,CAAC;AAED,IAAI,iBAAiB,GAAkB,IAAI,CAAC;AAE5C,SAAS,eAAe;IACtB,IAAI,iBAAiB,KAAK,IAAI;QAAE,OAAO,iBAAiB,CAAC;IACzD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,mBAAI,CAAC,OAAO,CACvB,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,cAAc,CACf,CAAC;QACF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAEnD,CAAC;QACF,iBAAiB,GAAG,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB,GAAG,OAAO,CAAC;IAC9B,CAAC;IACD,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED,SAAS,eAAe,CAAC,WAAmB;IAC1C,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,IAAA,2BAAa,EAClC,mBAAI,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CACvC,CAAC;QACF,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC;QAClE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAEtD,CAAC;QACF,OAAO,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,41 @@
+import type { IPluginModuleReplaceDirectory } from "./IPluginModuleReplaceDirectory";
+import { SourcePluginWorkspace } from "./SourcePluginWorkspace";
+/**
+ * The local directories outside a plugin's Go module that its `go.mod`
+ * `replace` directives name before the build prepares its scratch sources.
+ *
+ * A `replace` whose target is a filesystem path (Go's rule: absolute, or
+ * beginning with `./` or `../`) makes the build compile that directory as the
+ * replaced module. A target inside the module is copied and keyed with it. An
+ * outside target supplies a separate source population: the cache key digests
+ * it, the load reports its state among `pluginSources`, and a watch observes
+ * it. buildSourcePlugin snapshots and proves that target's copy, then anchors
+ * the replacement to the copy before compiling. A relative target also has to
+ * resolve from the module's own directory, as it does for `go build` there, and
+ * not from the scratch copy the build runs in.
+ *
+ * The directives are read through `go mod edit -json`, Go's own reading of
+ * `go.mod`, not a copy of its grammar. Only the main module's directives count,
+ * as Go ignores the `replace` directives of every other module.
+ *
+ * @param moduleRoot The plugin's Go module root, which holds its `go.mod`.
+ * @param env The build's effective environment.
+ * @param goBinary The Go tool the build runs, or `undefined` to resolve it as
+ *   the build does.
+ * @returns Each replacement outside the module, sorted by module path: the
+ *   replaced module path and version, the target as `go.mod` spells it, and the
+ *   target's absolute path.
+ * @throws On non-ENOENT manifest reads, or when the replace-triggered Go query
+ *   fails or supplies an unusable JSON result. A no-marker manifest skips Go
+ *   parsing here; this is not general go.mod validation.
+ * @evidence contracts/common.md#principled-implementation When the replace marker triggers a query, Go parses its grammar. Unversioned local targets selected outside best-effort root/target spellings are reported, resolving relative paths from the original module; unavailable identity resolution does not certify complete physical containment.
+ * @evidence contracts/common.md#clear-and-simple-design A cheap no-replace scan avoids unnecessary parsing; the common selected-tool/load reader owns Go syntax, and this operation owns current physical containment.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The implementation uses Go's supported mod-edit interface instead of a handwritten grammar or special-casing particular dependency names.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain external versus internal replacement ownership, original-directory resolution and returned spellings; failure behavior is documented.
+ * @evidence contracts/portability.md#os-neutral-implementation Node path and physical-path resolution determine containment; Go local-path syntax accepts native absolute paths and Windows-relative backslashes only on Windows.
+ * @evidence contracts/performance.md#efficient-algorithms Full manifest read/UTF-8 marker scan can skip Go parsing. Otherwise selected-tool reader acquisition and a current manifest read precede a pass over all parsed directives, not only returned ones. Equivalent bytes share Go JSON acquisition only in the supplied fixed-environment load registry; a new syntax record pays native tool/env/capture and full JSON costs; each selected local target uses native best-effort identity resolution, which can traverse ancestors/probe case. Sorting returned module/version strings processes their bytes, with complete manifest/output/path arrays retained transiently and no replacement content digest scan here.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work The optional pinned-tool/load reader or registry shares Go parsing of identical current bytes with package observation and workspace creation. Physical replacement containment is recomputed every call, never borrowed from that syntax memo.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This operation acquires no retained handle; the supplied load registry retains syntax readers until its caller releases the load. Without it the reader is call-owned. Native capture cleanup remains delegated and can fail; current physical identity contexts are call-owned and returned directories do not pin future state.
+ */
+export declare function pluginModuleReplaceDirectories(moduleRoot: string, env: NodeJS.ProcessEnv, goBinary?: string, reader?: SourcePluginWorkspace.GoModReader, readers?: Map<string, SourcePluginWorkspace.GoModReader>): IPluginModuleReplaceDirectory[];

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

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginModuleReplaceDirectories = pluginModuleReplaceDirectories;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const resolvePhysicalPath_1 = require("../../../internal/pathIdentity/resolvePhysicalPath");
+const GoToolResolution_1 = require("./GoToolResolution");
+const SourcePluginWorkspace_1 = require("./SourcePluginWorkspace");
+const resolveGoCompiler_1 = require("./resolveGoCompiler");
+const selectPluginModuleReplaceDirectories_1 = require("./selectPluginModuleReplaceDirectories");
+/**
+ * The local directories outside a plugin's Go module that its `go.mod`
+ * `replace` directives name before the build prepares its scratch sources.
+ *
+ * A `replace` whose target is a filesystem path (Go's rule: absolute, or
+ * beginning with `./` or `../`) makes the build compile that directory as the
+ * replaced module. A target inside the module is copied and keyed with it. An
+ * outside target supplies a separate source population: the cache key digests
+ * it, the load reports its state among `pluginSources`, and a watch observes
+ * it. buildSourcePlugin snapshots and proves that target's copy, then anchors
+ * the replacement to the copy before compiling. A relative target also has to
+ * resolve from the module's own directory, as it does for `go build` there, and
+ * not from the scratch copy the build runs in.
+ *
+ * The directives are read through `go mod edit -json`, Go's own reading of
+ * `go.mod`, not a copy of its grammar. Only the main module's directives count,
+ * as Go ignores the `replace` directives of every other module.
+ *
+ * @param moduleRoot The plugin's Go module root, which holds its `go.mod`.
+ * @param env The build's effective environment.
+ * @param goBinary The Go tool the build runs, or `undefined` to resolve it as
+ *   the build does.
+ * @returns Each replacement outside the module, sorted by module path: the
+ *   replaced module path and version, the target as `go.mod` spells it, and the
+ *   target's absolute path.
+ * @throws On non-ENOENT manifest reads, or when the replace-triggered Go query
+ *   fails or supplies an unusable JSON result. A no-marker manifest skips Go
+ *   parsing here; this is not general go.mod validation.
+ * @evidence contracts/common.md#principled-implementation When the replace marker triggers a query, Go parses its grammar. Unversioned local targets selected outside best-effort root/target spellings are reported, resolving relative paths from the original module; unavailable identity resolution does not certify complete physical containment.
+ * @evidence contracts/common.md#clear-and-simple-design A cheap no-replace scan avoids unnecessary parsing; the common selected-tool/load reader owns Go syntax, and this operation owns current physical containment.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The implementation uses Go's supported mod-edit interface instead of a handwritten grammar or special-casing particular dependency names.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain external versus internal replacement ownership, original-directory resolution and returned spellings; failure behavior is documented.
+ * @evidence contracts/portability.md#os-neutral-implementation Node path and physical-path resolution determine containment; Go local-path syntax accepts native absolute paths and Windows-relative backslashes only on Windows.
+ * @evidence contracts/performance.md#efficient-algorithms Full manifest read/UTF-8 marker scan can skip Go parsing. Otherwise selected-tool reader acquisition and a current manifest read precede a pass over all parsed directives, not only returned ones. Equivalent bytes share Go JSON acquisition only in the supplied fixed-environment load registry; a new syntax record pays native tool/env/capture and full JSON costs; each selected local target uses native best-effort identity resolution, which can traverse ancestors/probe case. Sorting returned module/version strings processes their bytes, with complete manifest/output/path arrays retained transiently and no replacement content digest scan here.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work The optional pinned-tool/load reader or registry shares Go parsing of identical current bytes with package observation and workspace creation. Physical replacement containment is recomputed every call, never borrowed from that syntax memo.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This operation acquires no retained handle; the supplied load registry retains syntax readers until its caller releases the load. Without it the reader is call-owned. Native capture cleanup remains delegated and can fail; current physical identity contexts are call-owned and returned directories do not pin future state.
+ */
+function pluginModuleReplaceDirectories(moduleRoot, env, goBinary, reader, readers) {
+    const root = node_path_1.default.resolve(moduleRoot);
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(node_path_1.default.join(root, "go.mod"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    // Every `replace` directive spells the word, so a file without it has none,
+    // and Go need not be run to read it. A file with it is read by Go itself.
+    if (!text.includes("replace"))
+        return [];
+    const go = goBinary ??
+        GoToolResolution_1.GoToolResolution.resolveGoToolForBuild((0, resolveGoCompiler_1.resolveGoCompiler)(env).binary, env, root);
+    const parsed = (reader ?? SourcePluginWorkspace_1.SourcePluginWorkspace.createGoModReader(go, root, env, readers)).read(root);
+    // Parsed syntax may be shared; physical containment is current native state
+    // and must be recomputed even when these manifest bytes are unchanged.
+    return (0, selectPluginModuleReplaceDirectories_1.selectPluginModuleReplaceDirectories)(root, parsed.directives, resolvePhysicalPath_1.resolvePhysicalPath);
+}
+//# sourceMappingURL=pluginModuleReplaceDirectories.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginModuleReplaceDirectories.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/pluginModuleReplaceDirectories.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B,4FAAyF;AACzF,yDAAsD;AAEtD,mEAAgE;AAChE,2DAAwD;AACxD,iGAA8F;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wCACE,UAAkB,EAClB,GAAsB,EACtB,QAAiB,EACjB,MAA0C,EAC1C,OAAwD;IAExD,MAAM,IAAI,GAAG,mBAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,iBAAE,CAAC,YAAY,CAAC,mBAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAClE,MAAM,KAAK,CAAC;IACd,CAAC;IACD,4EAA4E;IAC5E,0EAA0E;IAC1E,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,CAAC;IACzC,MAAM,EAAE,GACN,QAAQ;QACR,mCAAgB,CAAC,qBAAqB,CACpC,IAAA,qCAAiB,EAAC,GAAG,CAAC,CAAC,MAAM,EAC7B,GAAG,EACH,IAAI,CACL,CAAC;IACJ,MAAM,MAAM,GAAG,CACb,MAAM,IAAI,6CAAqB,CAAC,iBAAiB,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAC1E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,4EAA4E;IAC5E,uEAAuE;IACvE,OAAO,IAAA,2EAAoC,EACzC,IAAI,EACJ,MAAM,CAAC,UAAU,EACjB,yCAAmB,CACpB,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,32 @@
+/**
+ * Whether a path below a plugin source directory can bear on the sources in the
+ * directory's state (`pluginSourceState`), so an observer of the directory as a
+ * subtree must hear it.
+ *
+ * The plugin build passes over every directory it prunes
+ * (`prunesPluginSourceDirectory`: a nested `node_modules`, a repository's
+ * `.git`), so nothing below one moves the state, and an observer that watched
+ * them would re-prove the state, or rebuild, for every write of a package
+ * manager or of Git. `ttsc --watch` and `@ttsc/unplugin`'s observers answer the
+ * question with this one rule. An injected filesystem observer can supply its
+ * path grammar explicitly; native compiler and filesystem callers retain the
+ * current process default.
+ *
+ * @param root The plugin source directory.
+ * @param file The path, absolute.
+ * @param kind `"directory"` for a directory an observer would watch, which is
+ *   passed over when any of its own components is pruned; `"entry"` for the
+ *   path an event names, whose own name may be a file the build reads whatever
+ *   it is called, so only the directories above it are checked.
+ * @param platform The observed path grammar, defaulting to the current process.
+ * @evidence contracts/common.md#principled-implementation Relative containment uses the observed path grammar to reject paths outside the source; omitting the final component for entry events preserves files whose names happen to match pruned directory names.
+ * @evidence contracts/common.md#clear-and-simple-design One kind discriminant separates watched-directory membership from event-entry membership without duplicating path containment logic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The same shared prune predicate controls source observers rather than a local list adjusted to a particular watcher failure.
+ * @evidence contracts/common.md#meaningful-documentation Native parameter comments explain why a directory's own name counts while an event entry's own name may still be a source file.
+ * @evidence contracts/portability.md#os-neutral-implementation Explicit win32/posix grammar follows the observer's filesystem view while native callers default to process.platform; lexical containment establishes neither physical alias identity nor a volume's case capability.
+ * @evidence contracts/performance.md#efficient-algorithms Relative-path construction and one component scan cost O(P) time and O(P) temporary path/component space, without filesystem enumeration.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This is a current path-policy query; watcher and source-state reuse belong to consumers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No watcher or persistent handle is acquired here.
+ */
+export declare function pluginSourceCovers(root: string, file: string, kind: "directory" | "entry", platform?: NodeJS.Platform): boolean;

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

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginSourceCovers = pluginSourceCovers;
+const node_path_1 = __importDefault(require("node:path"));
+const prunesPluginSourceDirectory_1 = require("./prunesPluginSourceDirectory");
+/**
+ * Whether a path below a plugin source directory can bear on the sources in the
+ * directory's state (`pluginSourceState`), so an observer of the directory as a
+ * subtree must hear it.
+ *
+ * The plugin build passes over every directory it prunes
+ * (`prunesPluginSourceDirectory`: a nested `node_modules`, a repository's
+ * `.git`), so nothing below one moves the state, and an observer that watched
+ * them would re-prove the state, or rebuild, for every write of a package
+ * manager or of Git. `ttsc --watch` and `@ttsc/unplugin`'s observers answer the
+ * question with this one rule. An injected filesystem observer can supply its
+ * path grammar explicitly; native compiler and filesystem callers retain the
+ * current process default.
+ *
+ * @param root The plugin source directory.
+ * @param file The path, absolute.
+ * @param kind `"directory"` for a directory an observer would watch, which is
+ *   passed over when any of its own components is pruned; `"entry"` for the
+ *   path an event names, whose own name may be a file the build reads whatever
+ *   it is called, so only the directories above it are checked.
+ * @param platform The observed path grammar, defaulting to the current process.
+ * @evidence contracts/common.md#principled-implementation Relative containment uses the observed path grammar to reject paths outside the source; omitting the final component for entry events preserves files whose names happen to match pruned directory names.
+ * @evidence contracts/common.md#clear-and-simple-design One kind discriminant separates watched-directory membership from event-entry membership without duplicating path containment logic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The same shared prune predicate controls source observers rather than a local list adjusted to a particular watcher failure.
+ * @evidence contracts/common.md#meaningful-documentation Native parameter comments explain why a directory's own name counts while an event entry's own name may still be a source file.
+ * @evidence contracts/portability.md#os-neutral-implementation Explicit win32/posix grammar follows the observer's filesystem view while native callers default to process.platform; lexical containment establishes neither physical alias identity nor a volume's case capability.
+ * @evidence contracts/performance.md#efficient-algorithms Relative-path construction and one component scan cost O(P) time and O(P) temporary path/component space, without filesystem enumeration.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This is a current path-policy query; watcher and source-state reuse belong to consumers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No watcher or persistent handle is acquired here.
+ */
+function pluginSourceCovers(root, file, kind, platform = process.platform) {
+    const paths = platform === "win32" ? node_path_1.default.win32 : node_path_1.default.posix;
+    const relative = paths.relative(root, file);
+    if (relative === "")
+        return true;
+    if (relative === ".." ||
+        relative.startsWith(`..${paths.sep}`) ||
+        paths.isAbsolute(relative))
+        return false;
+    const components = relative.split(paths.sep);
+    if (kind === "entry")
+        components.pop();
+    return !components.some(prunesPluginSourceDirectory_1.prunesPluginSourceDirectory);
+}
+//# sourceMappingURL=pluginSourceCovers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginSourceCovers.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/pluginSourceCovers.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B,+EAA4E;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,4BACE,IAAY,EACZ,IAAY,EACZ,IAA2B,EAC3B,QAAQ,GAAoB,OAAO,CAAC,QAAQ;IAE5C,MAAM,KAAK,GAAG,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,mBAAI,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAI,CAAC,KAAK,CAAC;IAC7D,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACjC,IACE,QAAQ,KAAK,IAAI;QACjB,QAAQ,CAAC,UAAU,CAAC,KAAK,KAAK,CAAC,GAAG,EAAE,CAAC;QACrC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC;QAE1B,OAAO,KAAK,CAAC;IACf,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7C,IAAI,IAAI,KAAK,OAAO;QAAE,UAAU,CAAC,GAAG,EAAE,CAAC;IACvC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,yDAA2B,CAAC,CAAC;AACvD,CAAC"}

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

@@ -0,0 +1,40 @@
+/**
+ * The files of one plugin source directory as a plugin build reads them: a
+ * SHA-256 over the relative path and bytes of every file the build keys its
+ * binary on (`collectPluginSourceFiles`), in sorted order. Each JSON header
+ * gives the relative path and exact following byte length, so file contents
+ * cannot imitate another file's boundary.
+ *
+ * A plugin's binary is keyed on these files. Its transform output can also
+ * depend on runtime inputs that the owning producer must report; this digest
+ * alone does not certify all such dependencies. The cache key folds the digest
+ * of each directory it covers (`computeCacheKey`), and the transform envelope
+ * reports each plugin source directory's state
+ * (`ITtscCompilerTransformation.ISuccess.pluginSources`), this digest together
+ * with the build environment (`pluginSourceState`), so a consumer that caches
+ * the output proves it still holds through the `ttsc/plugin-source` entry
+ * (`pluginSourceStateHolds`) instead of a copy of the rule.
+ *
+ * Content rather than size and modification time: the build reads every byte
+ * anyway, and a consumer's proof must not accept an edit that kept a file's
+ * size within one clock tick. A consumer that proves a source on every delivery
+ * may keep a digest under matching metadata and the observing owner's
+ * separability policy, then hand it to `pluginSourceStateHolds`; that judgment
+ * is the consumer's, which owns a clock reference, and the file list is this
+ * one's. A directory that does not exist has the digest of an empty one, as it
+ * keys the build.
+ *
+ * @param directory The source directory.
+ * @returns The digest, as lowercase hex.
+ * @throws When a listed file cannot be read, as the build itself would.
+ * @evidence contracts/common.md#principled-implementation Sorted relative paths and byte lengths form unambiguous JSON headers followed by exact file bytes; embedded newlines cannot imitate another file boundary, and metadata alone cannot establish source equality.
+ * @evidence contracts/common.md#clear-and-simple-design Selection belongs to collectPluginSourceFiles and this function owns only deterministic content hashing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Source identity uses the build's declared file population rather than expected outputs, fixture names or mtime-only shortcuts.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish content and metadata proofs, state missing-directory behavior and identify lowercase-hex output and read failures.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths are made root-relative and slash-normalized only for digest serialization; filesystem reads retain the original native paths.
+ * @evidence contracts/performance.md#efficient-algorithms Sorted enumeration includes native lookup and path-text-sensitive comparisons; each selected file is read in full and its normalized relative path/JSON length header plus B content bytes are hashed. Each iteration uses one file Buffer with the complete path population and transient serialization; native reads/path/header bytes also contribute costs.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This computes a fresh digest; load-scoped maps and separable metadata proofs own reuse of that digest.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The hash and per-file buffers are call-local; no persistent descriptor or cache is owned here.
+ */
+export declare function pluginSourceDigest(directory: string): string;

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

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginSourceDigest = pluginSourceDigest;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const collectPluginSourceFiles_1 = require("./collectPluginSourceFiles");
+/**
+ * The files of one plugin source directory as a plugin build reads them: a
+ * SHA-256 over the relative path and bytes of every file the build keys its
+ * binary on (`collectPluginSourceFiles`), in sorted order. Each JSON header
+ * gives the relative path and exact following byte length, so file contents
+ * cannot imitate another file's boundary.
+ *
+ * A plugin's binary is keyed on these files. Its transform output can also
+ * depend on runtime inputs that the owning producer must report; this digest
+ * alone does not certify all such dependencies. The cache key folds the digest
+ * of each directory it covers (`computeCacheKey`), and the transform envelope
+ * reports each plugin source directory's state
+ * (`ITtscCompilerTransformation.ISuccess.pluginSources`), this digest together
+ * with the build environment (`pluginSourceState`), so a consumer that caches
+ * the output proves it still holds through the `ttsc/plugin-source` entry
+ * (`pluginSourceStateHolds`) instead of a copy of the rule.
+ *
+ * Content rather than size and modification time: the build reads every byte
+ * anyway, and a consumer's proof must not accept an edit that kept a file's
+ * size within one clock tick. A consumer that proves a source on every delivery
+ * may keep a digest under matching metadata and the observing owner's
+ * separability policy, then hand it to `pluginSourceStateHolds`; that judgment
+ * is the consumer's, which owns a clock reference, and the file list is this
+ * one's. A directory that does not exist has the digest of an empty one, as it
+ * keys the build.
+ *
+ * @param directory The source directory.
+ * @returns The digest, as lowercase hex.
+ * @throws When a listed file cannot be read, as the build itself would.
+ * @evidence contracts/common.md#principled-implementation Sorted relative paths and byte lengths form unambiguous JSON headers followed by exact file bytes; embedded newlines cannot imitate another file boundary, and metadata alone cannot establish source equality.
+ * @evidence contracts/common.md#clear-and-simple-design Selection belongs to collectPluginSourceFiles and this function owns only deterministic content hashing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Source identity uses the build's declared file population rather than expected outputs, fixture names or mtime-only shortcuts.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish content and metadata proofs, state missing-directory behavior and identify lowercase-hex output and read failures.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths are made root-relative and slash-normalized only for digest serialization; filesystem reads retain the original native paths.
+ * @evidence contracts/performance.md#efficient-algorithms Sorted enumeration includes native lookup and path-text-sensitive comparisons; each selected file is read in full and its normalized relative path/JSON length header plus B content bytes are hashed. Each iteration uses one file Buffer with the complete path population and transient serialization; native reads/path/header bytes also contribute costs.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This computes a fresh digest; load-scoped maps and separable metadata proofs own reuse of that digest.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The hash and per-file buffers are call-local; no persistent descriptor or cache is owned here.
+ */
+function pluginSourceDigest(directory) {
+    const hash = node_crypto_1.default.createHash("sha256");
+    for (const file of (0, collectPluginSourceFiles_1.collectPluginSourceFiles)(directory)) {
+        const relative = node_path_1.default.relative(directory, file).split(node_path_1.default.sep).join("/");
+        const contents = node_fs_1.default.readFileSync(file);
+        hash.update(JSON.stringify([relative, contents.length]));
+        hash.update(contents);
+    }
+    return hash.digest("hex");
+}
+//# sourceMappingURL=pluginSourceDigest.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginSourceDigest.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/pluginSourceDigest.ts"],"names":[],"mappings":";;;;;;AAAA,8DAAiC;AACjC,sDAAyB;AACzB,0DAA6B;AAE7B,yEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,4BAAmC,SAAiB;IAClD,MAAM,IAAI,GAAG,qBAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,IAAA,mDAAwB,EAAC,SAAS,CAAC,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,mBAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,mBAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1E,MAAM,QAAQ,GAAG,iBAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC"}

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

@@ -0,0 +1,38 @@
+/**
+ * The metadata signature of exactly the files a plugin source directory's
+ * digest reads (`collectPluginSourceFiles`), each by its path relative to the
+ * directory, and whether every stamp in it is separable, or `undefined` when a
+ * listed file cannot be stated.
+ *
+ * A host that proves a plugin source often may keep the digest it read while
+ * this signature holds still, as git keeps an index entry, and hand it to
+ * `pluginSourceStateHolds` instead of reading every file again: a file added,
+ * removed or renamed changes the selected population, while content-write
+ * detection relies on the owner's reported metadata and separability premises.
+ * The signature itself does not read content or certify arbitrary metadata
+ * restoration. What metadata/separability proves is the host's to answer, since
+ * only the host owns a clock reference on the filesystem it observes
+ * (`evidence`). The file list is ttsc's, so every host signs exactly what the
+ * build keys on: `@ttsc/unplugin` keeps a digest per delivery this way, and the
+ * capability-resolution cache across processes.
+ *
+ * @param directory The plugin source directory, absolute.
+ * @param evidence One file's metadata signature and separability, or
+ *   `undefined` when it cannot be stated.
+ * @evidence contracts/common.md#principled-implementation Each selected file's relative path and caller-supplied metadata enter the signature, while all separability flags must hold; absent metadata rejects the proof rather than pretending an unreadable file is unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design The shared file population stays with ttsc while the observing owner supplies filesystem stamps and its clock-based separability judgment.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The function does not infer safe reuse from a quiet watcher or a convenient timestamp; the consumer must establish each stamp's separability.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains selected population changes and why metadata/separability premises and the evidence callback belong to the observing host, without equating this signature to content observation.
+ * @evidence contracts/portability.md#os-neutral-implementation Native relative path spelling identifies files in this process; actual filesystem stamp precision and case capabilities are supplied by the observing owner.
+ * @evidence contracts/performance.md#efficient-algorithms Sorted enumeration includes native listing/path-text comparison costs. Each file invokes caller evidence and hashes relative-path/metadata-signature JSON bytes; callback cost is the observer's work and cannot be bounded by F alone. This function does not reread file content, but retains the full selected path population during the walk.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This returns the validation signature; the consumer owns the digest and permission to reuse it against that signature.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned signature and separability value survive; the callback's external observation resources remain caller-owned.
+ */
+export declare function pluginSourceFilesSignature(directory: string, evidence: (file: string) => {
+    separable: boolean;
+    signature: string;
+} | undefined): {
+    separable: boolean;
+    signature: string;
+} | undefined;

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

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginSourceFilesSignature = pluginSourceFilesSignature;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_path_1 = __importDefault(require("node:path"));
+const collectPluginSourceFiles_1 = require("./collectPluginSourceFiles");
+/**
+ * The metadata signature of exactly the files a plugin source directory's
+ * digest reads (`collectPluginSourceFiles`), each by its path relative to the
+ * directory, and whether every stamp in it is separable, or `undefined` when a
+ * listed file cannot be stated.
+ *
+ * A host that proves a plugin source often may keep the digest it read while
+ * this signature holds still, as git keeps an index entry, and hand it to
+ * `pluginSourceStateHolds` instead of reading every file again: a file added,
+ * removed or renamed changes the selected population, while content-write
+ * detection relies on the owner's reported metadata and separability premises.
+ * The signature itself does not read content or certify arbitrary metadata
+ * restoration. What metadata/separability proves is the host's to answer, since
+ * only the host owns a clock reference on the filesystem it observes
+ * (`evidence`). The file list is ttsc's, so every host signs exactly what the
+ * build keys on: `@ttsc/unplugin` keeps a digest per delivery this way, and the
+ * capability-resolution cache across processes.
+ *
+ * @param directory The plugin source directory, absolute.
+ * @param evidence One file's metadata signature and separability, or
+ *   `undefined` when it cannot be stated.
+ * @evidence contracts/common.md#principled-implementation Each selected file's relative path and caller-supplied metadata enter the signature, while all separability flags must hold; absent metadata rejects the proof rather than pretending an unreadable file is unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design The shared file population stays with ttsc while the observing owner supplies filesystem stamps and its clock-based separability judgment.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The function does not infer safe reuse from a quiet watcher or a convenient timestamp; the consumer must establish each stamp's separability.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains selected population changes and why metadata/separability premises and the evidence callback belong to the observing host, without equating this signature to content observation.
+ * @evidence contracts/portability.md#os-neutral-implementation Native relative path spelling identifies files in this process; actual filesystem stamp precision and case capabilities are supplied by the observing owner.
+ * @evidence contracts/performance.md#efficient-algorithms Sorted enumeration includes native listing/path-text comparison costs. Each file invokes caller evidence and hashes relative-path/metadata-signature JSON bytes; callback cost is the observer's work and cannot be bounded by F alone. This function does not reread file content, but retains the full selected path population during the walk.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This returns the validation signature; the consumer owns the digest and permission to reuse it against that signature.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned signature and separability value survive; the callback's external observation resources remain caller-owned.
+ */
+function pluginSourceFilesSignature(directory, evidence) {
+    const hash = node_crypto_1.default.createHash("sha256");
+    let separable = true;
+    for (const file of (0, collectPluginSourceFiles_1.collectPluginSourceFiles)(directory)) {
+        const observed = evidence(file);
+        if (observed === undefined)
+            return undefined;
+        hash.update(JSON.stringify([node_path_1.default.relative(directory, file), observed.signature]));
+        separable &&= observed.separable;
+    }
+    return { separable, signature: hash.digest("hex") };
+}
+//# sourceMappingURL=pluginSourceFilesSignature.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginSourceFilesSignature.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/pluginSourceFilesSignature.ts"],"names":[],"mappings":";;;;;;AAAA,8DAAiC;AACjC,0DAA6B;AAE7B,yEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,oCACE,SAAiB,EACjB,QAE0D;IAE1D,MAAM,IAAI,GAAG,qBAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,KAAK,MAAM,IAAI,IAAI,IAAA,mDAAwB,EAAC,SAAS,CAAC,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC7C,IAAI,CAAC,MAAM,CACT,IAAI,CAAC,SAAS,CAAC,CAAC,mBAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC,CACrE,CAAC;QACF,SAAS,KAAK,QAAQ,CAAC,SAAS,CAAC;IACnC,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACtD,CAAC"}

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

@@ -0,0 +1,47 @@
+/**
+ * The state of one plugin source directory as a plugin binary is built from it:
+ * the digest of its sources (`pluginSourceDigest`) together with the
+ * environment a build there is keyed on (`pluginBuildEnvironment`).
+ *
+ * The plugin cache key covers both selected identities (`computeCacheKey`): a
+ * changed `GOFLAGS`, cgo setting, C compiler, or Go toolchain builds another
+ * binary as surely as an edited source file does. The transform envelope
+ * reports this state for directories selected by the loader's pluginSources
+ * policy, which omits installed ttsc directories, and a consumer that keeps the
+ * output beyond its process proves it through the `ttsc/plugin-source` entry,
+ * with no rule of its own. For a plugin's own module root the environment is
+ * the one its build keyed on exactly. For a contributor or an overlay, which
+ * the build reads under the plugin's module root, it is the environment a build
+ * there would take. It is not an assertion that arbitrary directory-local tool
+ * or environment resolution is identical to the host module's resolution.
+ *
+ * Sources are read unless the caller supplies their digest. Under this
+ * process's own environment the environment is read once per directory and set
+ * of variables (`processPluginBuildEnvironment`), and a proof that must not
+ * accept a stale one compares through `pluginSourceStateHolds`, which reads it
+ * again before it refutes a state.
+ *
+ * @param directory The source directory.
+ * @param options.env An effective environment other than this process's, which
+ *   is read fresh.
+ * @param options.sourceDigest The directory's `pluginSourceDigest`, when the
+ *   caller already read it.
+ * @param options.environment The directory's `pluginBuildEnvironment`, when the
+ *   caller already read it, as a plugin build's key does.
+ * @returns The state, as lowercase hex.
+ * @throws When a listed source file cannot be read, as the build itself would.
+ * @evidence contracts/common.md#principled-implementation The state combines source and environment digests because both affect compiled plugin behavior; supplied readings preserve the exact inputs a build already keyed on.
+ * @evidence contracts/common.md#clear-and-simple-design One composition function delegates source selection and environment resolution to their owning implementations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The state is derived from real source/toolchain readings rather than compile output or an assumed stable process environment.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain module-root versus overlay environment meaning and the provenance required for supplied digests.
+ * @evidence contracts/portability.md#os-neutral-implementation Native source and toolchain identity are delegated to the shared filesystem/process readers; the final digest is platform-independent serialized text.
+ * @evidence contracts/performance.md#efficient-algorithms Composition serializes/hashes supplied digest strings whose public inputs are not length-validated; owning generated digests are fixed-width hex. Missing readings delegate native source enumeration/full reads and environment variable/witness/tool/SDK work, without establishing an unmeasured dominant cost ranking.
+ * @evidence contracts/performance.md#reuse-equivalent-work Supplied source/environment strings are trusted producer readings, not independently revalidated here. Process-environment memos require their owner's variable/path witness checks; explicit injected environments are read fresh. Equality inherits the selected-source and native metadata premises.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This function retains no resource or state after returning; process-environment memo lifetime belongs to its separate owner.
+ */
+export declare function pluginSourceState(directory: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    environment?: string;
+    sourceDigest?: string;
+}): string;

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

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginSourceState = pluginSourceState;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const pluginBuildEnvironment_1 = require("./pluginBuildEnvironment");
+const pluginSourceDigest_1 = require("./pluginSourceDigest");
+const processPluginBuildEnvironment_1 = require("./processPluginBuildEnvironment");
+/**
+ * The state of one plugin source directory as a plugin binary is built from it:
+ * the digest of its sources (`pluginSourceDigest`) together with the
+ * environment a build there is keyed on (`pluginBuildEnvironment`).
+ *
+ * The plugin cache key covers both selected identities (`computeCacheKey`): a
+ * changed `GOFLAGS`, cgo setting, C compiler, or Go toolchain builds another
+ * binary as surely as an edited source file does. The transform envelope
+ * reports this state for directories selected by the loader's pluginSources
+ * policy, which omits installed ttsc directories, and a consumer that keeps the
+ * output beyond its process proves it through the `ttsc/plugin-source` entry,
+ * with no rule of its own. For a plugin's own module root the environment is
+ * the one its build keyed on exactly. For a contributor or an overlay, which
+ * the build reads under the plugin's module root, it is the environment a build
+ * there would take. It is not an assertion that arbitrary directory-local tool
+ * or environment resolution is identical to the host module's resolution.
+ *
+ * Sources are read unless the caller supplies their digest. Under this
+ * process's own environment the environment is read once per directory and set
+ * of variables (`processPluginBuildEnvironment`), and a proof that must not
+ * accept a stale one compares through `pluginSourceStateHolds`, which reads it
+ * again before it refutes a state.
+ *
+ * @param directory The source directory.
+ * @param options.env An effective environment other than this process's, which
+ *   is read fresh.
+ * @param options.sourceDigest The directory's `pluginSourceDigest`, when the
+ *   caller already read it.
+ * @param options.environment The directory's `pluginBuildEnvironment`, when the
+ *   caller already read it, as a plugin build's key does.
+ * @returns The state, as lowercase hex.
+ * @throws When a listed source file cannot be read, as the build itself would.
+ * @evidence contracts/common.md#principled-implementation The state combines source and environment digests because both affect compiled plugin behavior; supplied readings preserve the exact inputs a build already keyed on.
+ * @evidence contracts/common.md#clear-and-simple-design One composition function delegates source selection and environment resolution to their owning implementations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The state is derived from real source/toolchain readings rather than compile output or an assumed stable process environment.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain module-root versus overlay environment meaning and the provenance required for supplied digests.
+ * @evidence contracts/portability.md#os-neutral-implementation Native source and toolchain identity are delegated to the shared filesystem/process readers; the final digest is platform-independent serialized text.
+ * @evidence contracts/performance.md#efficient-algorithms Composition serializes/hashes supplied digest strings whose public inputs are not length-validated; owning generated digests are fixed-width hex. Missing readings delegate native source enumeration/full reads and environment variable/witness/tool/SDK work, without establishing an unmeasured dominant cost ranking.
+ * @evidence contracts/performance.md#reuse-equivalent-work Supplied source/environment strings are trusted producer readings, not independently revalidated here. Process-environment memos require their owner's variable/path witness checks; explicit injected environments are read fresh. Equality inherits the selected-source and native metadata premises.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This function retains no resource or state after returning; process-environment memo lifetime belongs to its separate owner.
+ */
+function pluginSourceState(directory, options = {}) {
+    return node_crypto_1.default
+        .createHash("sha256")
+        .update(`source=${options.sourceDigest ?? (0, pluginSourceDigest_1.pluginSourceDigest)(directory)}\n` +
+        `environment=${options.environment ??
+            (options.env === undefined
+                ? (0, processPluginBuildEnvironment_1.processPluginBuildEnvironment)(directory)
+                : (0, pluginBuildEnvironment_1.pluginBuildEnvironment)(directory, options.env))}\n`)
+        .digest("hex");
+}
+//# sourceMappingURL=pluginSourceState.js.map