ttsc 0.30.4 → 0.31.0

package/lib/plugin/internal/load/ProjectPluginEntries.d.ts

@@ -0,0 +1,60 @@
+import type { ITtscProjectPluginConfig } from "../../../structures/ITtscProjectPluginConfig";
+import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITtscParsedProjectConfig";
+/**
+ * The plugin entries a project declares, from its `tsconfig.json` and from the
+ * `ttsc` block of its direct dependencies' manifests.
+ *
+ * Every entry carries the directory its specifier resolves from. A bare package
+ * specifier resolves from the project root, never from the base config an
+ * `extends` chain declared it in. A configured relative entry uses its known
+ * declaring directory, falling back to project root; an automatic relative
+ * marker uses its package directory. Explicit invocation lists use project root
+ * for every entry, rather than recovering declaration provenance.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit entries replace discovery; otherwise inherited relative transforms retain their declaring base while bare packages resolve from the consumer, followed by distinct direct-dependency markers.
+ * @evidence contracts/common.md#clear-and-simple-design Entry extraction owns ordering/provenance and delegates physical package resolution; descriptor execution/building remain outside discovery.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Deduplication compares resolved selection strings plus bare specifier names, avoiding consumer-name exceptions. Best-effort realpath can retain lexical spelling; the index does not certify every physical alias as equivalent.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains declaring-config versus consumer bases and explicit/discovered order; helper comments explain marker validation and deduplication, with tag separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Shared relative-specifier classification accepts both native separator spellings; native dirname and shared resolution preserve actual package roots instead of assuming inherited configs own node_modules.
+ * @evidence contracts/performance.md#efficient-algorithms Configured mapping and a separate transform-index pass precede automatic discovery. Indexed duplicate checks avoid configured-by-automatic cross products, but field/name/path bytes, native nearest-manifest and package resolution, JSON marker parsing and output copying remain delegated costs; index cardinality alone is not a work ceiling.
+ * @evidence contracts/performance.md#reuse-equivalent-work Invocation-local raw/resolved selection Sets share duplicate membership across automatic entries, not a frozen physical-identity proof or cached package lookup. Current package reads are not retained across calls; persistent validated answers belong to descriptor/capability caches.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Discovery collections and returned entries are call-owned; no retained resource or cross-call population is acquired.
+ */
+export declare namespace ProjectPluginEntries {
+    /**
+     * One declared plugin and the directory its specifier resolves from.
+     *
+     * @evidence contracts/common.md#principled-implementation Pairing the selected config value with its resolution base carries explicit/configured or copied dependency-marker provenance without changing plugin-owned payload fields; the type itself does not recover a declaration file.
+     * @evidence contracts/common.md#clear-and-simple-design Two fields carry entry value and provenance directly rather than embedding resolver/build state.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The base is actual declaration/consumer provenance, not a hardcoded package or fixture location.
+     * @evidence contracts/common.md#meaningful-documentation Native member comments identify config preservation and transform resolution base, with blank member/tag spacing following the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation The base is a native directory supplied by discovery; native path resolution remains with the loader and does not require POSIX spelling here.
+     *
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This entry type executes no discovery or resolution algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Provenance data establishes no reusable-answer cache by itself.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The record retains plain caller-owned data rather than handles or a cross-call population.
+     */
+    type ProjectPluginEntry = {
+        /** Directory the plugin's `transform` specifier is resolved against. */
+        baseDir: string;
+        /** Selected explicit/configured value or copied dependency plugin marker. */
+        config: ITtscProjectPluginConfig;
+    };
+    /**
+     * The project's plugin entries in declaration order: `entries` when a caller
+     * passed an explicit list, otherwise the tsconfig's `compilerOptions.plugins`
+     * followed by the plugins its direct dependencies publish automatically.
+     *
+     * @evidence contracts/common.md#principled-implementation Explicit array selection bypasses automatic discovery; inherited relative entries use their declaring directories, while bare entries and automatic dependency lookup use the consuming project's package authority.
+     * @evidence contracts/common.md#clear-and-simple-design One ordered entry operation delegates package lookup and contains the invocation's deduplication state, leaving descriptor evaluation to the loader.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual supported config provenance determines bases, and automatic markers are validated rather than silently repaired into guessed plugin configurations.
+     * @evidence contracts/common.md#meaningful-documentation Native JSDoc states explicit versus discovered ordering; private code comments explain inherited-base choice and invalid-marker diagnostics, with separate tags following the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Shared relative detection and native dirname/shared resolver preserve OS-neutral consumer/declarer bases, including Windows relative config spelling.
+     * @evidence contracts/performance.md#efficient-algorithms Explicit lists map directly; otherwise configured entries are mapped before a separate index pass. Automatic discovery includes native manifest/ancestor queries, dependency-name enumeration, selected target resolution and marker record copies. Set membership avoids duplicate cross products, while full name/path/manifest bytes and native query work remain part of cost.
+     * @evidence contracts/performance.md#reuse-equivalent-work Invocation-local transform identity indexes are reused across every automatic entry, without caching mutable package authority across calls.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The output and Set indexes are invocation-owned and acquire no persistent resource or collection.
+     */
+    function resolvePluginEntries(project: ITtscParsedProjectConfig, entries?: readonly ITtscProjectPluginConfig[]): ProjectPluginEntry[];
+}

package/lib/plugin/internal/load/ProjectPluginEntries.js

@@ -0,0 +1,164 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectPluginEntries = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const PluginPackageResolution_1 = require("./PluginPackageResolution");
+const isRelativePluginSpecifier_1 = require("./isRelativePluginSpecifier");
+/**
+ * The plugin entries a project declares, from its `tsconfig.json` and from the
+ * `ttsc` block of its direct dependencies' manifests.
+ *
+ * Every entry carries the directory its specifier resolves from. A bare package
+ * specifier resolves from the project root, never from the base config an
+ * `extends` chain declared it in. A configured relative entry uses its known
+ * declaring directory, falling back to project root; an automatic relative
+ * marker uses its package directory. Explicit invocation lists use project root
+ * for every entry, rather than recovering declaration provenance.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit entries replace discovery; otherwise inherited relative transforms retain their declaring base while bare packages resolve from the consumer, followed by distinct direct-dependency markers.
+ * @evidence contracts/common.md#clear-and-simple-design Entry extraction owns ordering/provenance and delegates physical package resolution; descriptor execution/building remain outside discovery.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Deduplication compares resolved selection strings plus bare specifier names, avoiding consumer-name exceptions. Best-effort realpath can retain lexical spelling; the index does not certify every physical alias as equivalent.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains declaring-config versus consumer bases and explicit/discovered order; helper comments explain marker validation and deduplication, with tag separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Shared relative-specifier classification accepts both native separator spellings; native dirname and shared resolution preserve actual package roots instead of assuming inherited configs own node_modules.
+ * @evidence contracts/performance.md#efficient-algorithms Configured mapping and a separate transform-index pass precede automatic discovery. Indexed duplicate checks avoid configured-by-automatic cross products, but field/name/path bytes, native nearest-manifest and package resolution, JSON marker parsing and output copying remain delegated costs; index cardinality alone is not a work ceiling.
+ * @evidence contracts/performance.md#reuse-equivalent-work Invocation-local raw/resolved selection Sets share duplicate membership across automatic entries, not a frozen physical-identity proof or cached package lookup. Current package reads are not retained across calls; persistent validated answers belong to descriptor/capability caches.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Discovery collections and returned entries are call-owned; no retained resource or cross-call population is acquired.
+ */
+var ProjectPluginEntries;
+(function (ProjectPluginEntries) {
+    /**
+     * The project's plugin entries in declaration order: `entries` when a caller
+     * passed an explicit list, otherwise the tsconfig's `compilerOptions.plugins`
+     * followed by the plugins its direct dependencies publish automatically.
+     *
+     * @evidence contracts/common.md#principled-implementation Explicit array selection bypasses automatic discovery; inherited relative entries use their declaring directories, while bare entries and automatic dependency lookup use the consuming project's package authority.
+     * @evidence contracts/common.md#clear-and-simple-design One ordered entry operation delegates package lookup and contains the invocation's deduplication state, leaving descriptor evaluation to the loader.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual supported config provenance determines bases, and automatic markers are validated rather than silently repaired into guessed plugin configurations.
+     * @evidence contracts/common.md#meaningful-documentation Native JSDoc states explicit versus discovered ordering; private code comments explain inherited-base choice and invalid-marker diagnostics, with separate tags following the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Shared relative detection and native dirname/shared resolver preserve OS-neutral consumer/declarer bases, including Windows relative config spelling.
+     * @evidence contracts/performance.md#efficient-algorithms Explicit lists map directly; otherwise configured entries are mapped before a separate index pass. Automatic discovery includes native manifest/ancestor queries, dependency-name enumeration, selected target resolution and marker record copies. Set membership avoids duplicate cross products, while full name/path/manifest bytes and native query work remain part of cost.
+     * @evidence contracts/performance.md#reuse-equivalent-work Invocation-local transform identity indexes are reused across every automatic entry, without caching mutable package authority across calls.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The output and Set indexes are invocation-owned and acquire no persistent resource or collection.
+     */
+    function resolvePluginEntries(project, entries) {
+        if (entries !== undefined) {
+            return entries.map((config) => ({
+                baseDir: project.root,
+                config,
+            }));
+        }
+        const configured = project.compilerOptions.plugins.map((config, index) => {
+            // A bare/package plugin specifier (e.g. "typia/lib/transform") must resolve
+            // from the project's own node_modules, not from the tsconfig that declared
+            // it: an `extends`ed base config (a shared `tests/config/tsconfig.json`)
+            // declares the plugin, but the package is installed under the consuming
+            // project. Only a relative specifier ("./plugin") is meaningful relative to
+            // the declaring config's directory. Mirrors discoverPackagePluginEntries.
+            const declaringDir = project.pluginBaseDirs[index];
+            const baseDir = typeof config.transform === "string" &&
+                (0, isRelativePluginSpecifier_1.isRelativePluginSpecifier)(config.transform) &&
+                declaringDir !== undefined
+                ? declaringDir
+                : project.root;
+            return { baseDir, config };
+        });
+        return [
+            ...configured,
+            ...discoverPackagePluginEntries(project, configured),
+        ];
+    }
+    ProjectPluginEntries.resolvePluginEntries = resolvePluginEntries;
+    function discoverPackagePluginEntries(project, configured) {
+        const projectPackageJson = PluginPackageResolution_1.PluginPackageResolution.findNearestPackageJson(project.root);
+        if (projectPackageJson === undefined) {
+            return [];
+        }
+        const projectPackageRoot = node_path_1.default.dirname(projectPackageJson);
+        const projectManifest = PluginPackageResolution_1.PluginPackageResolution.readPackageManifest(projectPackageJson);
+        if (projectManifest === undefined) {
+            return [];
+        }
+        const configuredTransforms = createConfiguredTransformSet(configured);
+        const out = [];
+        for (const name of PluginPackageResolution_1.PluginPackageResolution.directDependencyNames(projectManifest)) {
+            const packageJson = PluginPackageResolution_1.PluginPackageResolution.resolveDependencyPackageJson(name, projectPackageRoot);
+            if (packageJson === undefined) {
+                continue;
+            }
+            const manifest = PluginPackageResolution_1.PluginPackageResolution.readPackageManifest(packageJson);
+            const config = readPackagePluginConfig(name, manifest);
+            if (config === undefined || config.enabled === false) {
+                continue;
+            }
+            const packageRoot = node_path_1.default.dirname(packageJson);
+            const transform = config.transform;
+            if (typeof transform !== "string") {
+                continue;
+            }
+            const baseDir = (0, isRelativePluginSpecifier_1.isRelativePluginSpecifier)(transform)
+                ? packageRoot
+                : projectPackageRoot;
+            const resolved = PluginPackageResolution_1.PluginPackageResolution.resolvePluginRequest(transform, baseDir);
+            if (hasConfiguredTransform(configuredTransforms, transform, resolved)) {
+                continue;
+            }
+            out.push({
+                baseDir,
+                config,
+            });
+            addConfiguredTransform(configuredTransforms, transform, resolved);
+        }
+        return out;
+    }
+    function createConfiguredTransformSet(entries) {
+        const raw = new Set();
+        const resolved = new Set();
+        for (const entry of entries) {
+            const transform = entry.config.transform;
+            if (typeof transform !== "string" || transform.length === 0) {
+                continue;
+            }
+            if (!(0, isRelativePluginSpecifier_1.isRelativePluginSpecifier)(transform)) {
+                raw.add(transform);
+            }
+            try {
+                resolved.add(PluginPackageResolution_1.PluginPackageResolution.resolvePluginRequest(transform, entry.baseDir));
+            }
+            catch {
+                // Keep the normal plugin loading error path for invalid explicit entries.
+            }
+        }
+        return { raw, resolved };
+    }
+    function hasConfiguredTransform(configuredTransforms, transform, resolved) {
+        return (configuredTransforms.resolved.has(resolved) ||
+            (!(0, isRelativePluginSpecifier_1.isRelativePluginSpecifier)(transform) &&
+                configuredTransforms.raw.has(transform)));
+    }
+    function addConfiguredTransform(configuredTransforms, transform, resolved) {
+        if (!(0, isRelativePluginSpecifier_1.isRelativePluginSpecifier)(transform)) {
+            configuredTransforms.raw.add(transform);
+        }
+        configuredTransforms.resolved.add(resolved);
+    }
+    function readPackagePluginConfig(packageName, manifest) {
+        const ttsc = manifest?.ttsc;
+        if (!PluginPackageResolution_1.PluginPackageResolution.isRecord(ttsc) || !("plugin" in ttsc)) {
+            return undefined;
+        }
+        const plugin = ttsc.plugin;
+        if (!PluginPackageResolution_1.PluginPackageResolution.isRecord(plugin) || Array.isArray(plugin)) {
+            throw new Error(`ttsc: package ${JSON.stringify(packageName)} declares invalid "ttsc.plugin"; expected an object`);
+        }
+        if (typeof plugin.transform !== "string" || plugin.transform.length === 0) {
+            throw new Error(`ttsc: package ${JSON.stringify(packageName)} declares invalid "ttsc.plugin.transform"; expected a non-empty string`);
+        }
+        return { ...plugin };
+    }
+})(ProjectPluginEntries || (exports.ProjectPluginEntries = ProjectPluginEntries = {}));
+//# sourceMappingURL=ProjectPluginEntries.js.map

package/lib/plugin/internal/load/ProjectPluginEntries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectPluginEntries.js","sourceRoot":"","sources":["../../../../src/plugin/internal/load/ProjectPluginEntries.ts"],"names":[],"mappings":"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"}

package/lib/plugin/internal/load/RESOLUTION_INPUT_RECORDER_PATH.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The absolute path of the module resolution input recorder
+ * (`driver/resolutioninputs/recorder.cjs`), the one file that owns which inputs
+ * a resolution read.
+ *
+ * The recorder lives beside the Go package that embeds it, so a Go plugin's
+ * config loader and ttsc's own evaluators share it rather than copy it. The
+ * package ships `driver`, so the path holds wherever ttsc is installed. An
+ * evaluator that runs in a clean process of its own requires it by this path.
+ */
+export declare const RESOLUTION_INPUT_RECORDER_PATH: string;
+/** The owning runtime's observation status module, shared with isolated writers. */
+export declare const PLUGIN_INPUT_OBSERVATION_PATH: string;

package/lib/plugin/internal/load/RESOLUTION_INPUT_RECORDER_PATH.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_INPUT_OBSERVATION_PATH = exports.RESOLUTION_INPUT_RECORDER_PATH = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * The absolute path of the module resolution input recorder
+ * (`driver/resolutioninputs/recorder.cjs`), the one file that owns which inputs
+ * a resolution read.
+ *
+ * The recorder lives beside the Go package that embeds it, so a Go plugin's
+ * config loader and ttsc's own evaluators share it rather than copy it. The
+ * package ships `driver`, so the path holds wherever ttsc is installed. An
+ * evaluator that runs in a clean process of its own requires it by this path.
+ */
+exports.RESOLUTION_INPUT_RECORDER_PATH = node_path_1.default.resolve(__dirname, "..", "..", "..", "..", "driver", "resolutioninputs", "recorder.cjs");
+/** The owning runtime's observation status module, shared with isolated writers. */
+exports.PLUGIN_INPUT_OBSERVATION_PATH = node_path_1.default.resolve(__dirname, "..", "..", "..", "launcher", "internal", "runtime", "PluginDescriptorInputObservation.js");
+//# sourceMappingURL=RESOLUTION_INPUT_RECORDER_PATH.js.map

package/lib/plugin/internal/load/RESOLUTION_INPUT_RECORDER_PATH.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RESOLUTION_INPUT_RECORDER_PATH.js","sourceRoot":"","sources":["../../../../src/plugin/internal/load/RESOLUTION_INPUT_RECORDER_PATH.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B;;;;;;;;;GASG;AACU,QAAA,8BAA8B,GAAW,mBAAI,CAAC,OAAO,CAChE,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,kBAAkB,EAClB,cAAc,CACf,CAAC;AAEF,oFAAoF;AACvE,QAAA,6BAA6B,GAAW,mBAAI,CAAC,OAAO,CAC/D,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,UAAU,EACV,UAAU,EACV,SAAS,EACT,qCAAqC,CACtC,CAAC"}

package/lib/plugin/internal/load/collectProjectHostInputs.d.ts

@@ -0,0 +1,16 @@
+import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITtscParsedProjectConfig";
+/**
+ * Return config ancestry and package-discovery manifest inputs, including
+ * missing nearer candidates that could redirect the selected package later.
+ *
+ * @evidence contracts/common.md#principled-implementation Config ancestry, lexical selection and missing config candidates influence selection; automatic discovery additionally observes nearest manifest and dependency search candidates through the selecting root. The project reader separately states whether these config observations are complete.
+ * @evidence contracts/common.md#clear-and-simple-design The collector obtains package resolution from its owner and assembles universal loader inputs, leaving source Program dependencies to the native reference graph.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing candidates are real future selection inputs; farther unconsulted roots are not added as compensating guesses, and explicit plugin lists can avoid automatic discovery.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc identifies ancestry and missing discovery candidates; the private helper explains the selected-root stopping condition, with paragraph/tag separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native resolve/dirname/join and Node createRequire search paths construct OS-neutral host inputs; package-name slash splitting is package-specifier grammar, not filesystem parsing.
+ * @evidence contracts/performance.md#efficient-algorithms Config paths are natively normalized and indexed; discovery additionally walks nearest-manifest ancestors, reads/parses manifest bytes and resolves each direct dependency through Node search roots and physical candidate checks. Candidate generation/query work can repeat before Set deduplication. Final sorting costs depend on unique input count and path-text comparisons; native metadata, path/topology and manifest/name bytes remain part of the cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work The operation assembles one shared universal input population for the load; identical candidate paths are retained once by the Set, while current filesystem resolution is not cached here.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The Set and returned array belong to this call, with no cross-call retention or acquired open resource.
+ */
+export declare function collectProjectHostInputs(project: ITtscParsedProjectConfig, includePluginDiscovery?: boolean): string[];

package/lib/plugin/internal/load/collectProjectHostInputs.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectProjectHostInputs = collectProjectHostInputs;
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const PluginPackageResolution_1 = require("./PluginPackageResolution");
+const moduleResolutionBaseSelects_1 = require("./moduleResolutionBaseSelects");
+/**
+ * Return config ancestry and package-discovery manifest inputs, including
+ * missing nearer candidates that could redirect the selected package later.
+ *
+ * @evidence contracts/common.md#principled-implementation Config ancestry, lexical selection and missing config candidates influence selection; automatic discovery additionally observes nearest manifest and dependency search candidates through the selecting root. The project reader separately states whether these config observations are complete.
+ * @evidence contracts/common.md#clear-and-simple-design The collector obtains package resolution from its owner and assembles universal loader inputs, leaving source Program dependencies to the native reference graph.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing candidates are real future selection inputs; farther unconsulted roots are not added as compensating guesses, and explicit plugin lists can avoid automatic discovery.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc identifies ancestry and missing discovery candidates; the private helper explains the selected-root stopping condition, with paragraph/tag separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native resolve/dirname/join and Node createRequire search paths construct OS-neutral host inputs; package-name slash splitting is package-specifier grammar, not filesystem parsing.
+ * @evidence contracts/performance.md#efficient-algorithms Config paths are natively normalized and indexed; discovery additionally walks nearest-manifest ancestors, reads/parses manifest bytes and resolves each direct dependency through Node search roots and physical candidate checks. Candidate generation/query work can repeat before Set deduplication. Final sorting costs depend on unique input count and path-text comparisons; native metadata, path/topology and manifest/name bytes remain part of the cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work The operation assembles one shared universal input population for the load; identical candidate paths are retained once by the Set, while current filesystem resolution is not cached here.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The Set and returned array belong to this call, with no cross-call retention or acquired open resource.
+ */
+function collectProjectHostInputs(project, includePluginDiscovery = true) {
+    const inputs = new Set([...project.configPaths, ...(project.configInputs ?? [])].map((file) => node_path_1.default.resolve(file)));
+    if (!includePluginDiscovery)
+        return [...inputs].sort();
+    const manifestCandidates = PluginPackageResolution_1.PluginPackageResolution.collectNearestPackageJsonCandidates(project.root);
+    for (const candidate of manifestCandidates)
+        inputs.add(candidate);
+    const manifest = manifestCandidates.find(PluginPackageResolution_1.PluginPackageResolution.existingFile);
+    if (manifest !== undefined) {
+        const projectManifest = PluginPackageResolution_1.PluginPackageResolution.readPackageManifest(manifest);
+        if (projectManifest !== undefined) {
+            const projectRoot = node_path_1.default.dirname(manifest);
+            for (const dependency of PluginPackageResolution_1.PluginPackageResolution.directDependencyNames(projectManifest)) {
+                const dependencyManifest = PluginPackageResolution_1.PluginPackageResolution.resolveDependencyPackageJson(dependency, projectRoot);
+                for (const candidate of collectDependencyManifestCandidates(dependency, manifest, dependencyManifest)) {
+                    inputs.add(candidate);
+                }
+                if (dependencyManifest !== undefined) {
+                    inputs.add(node_path_1.default.resolve(dependencyManifest));
+                }
+            }
+        }
+    }
+    return [...inputs].sort();
+}
+/**
+ * Record package manifests whose later appearance can redirect discovery: the
+ * manifest of each search root's package directory, through the root that
+ * selects the manifest discovery read (`moduleResolutionBaseSelects`), or every
+ * root when none was found.
+ */
+function collectDependencyManifestCandidates(packageName, parentFile, selectedManifest) {
+    const out = [];
+    for (const searchPath of (0, node_module_1.createRequire)(parentFile).resolve.paths(packageName) ?? []) {
+        const packageDirectory = node_path_1.default.join(searchPath, ...packageName.split("/"));
+        out.push(node_path_1.default.join(packageDirectory, "package.json"));
+        if ((0, moduleResolutionBaseSelects_1.moduleResolutionBaseSelects)(packageDirectory, selectedManifest, []))
+            break;
+    }
+    return out;
+}
+//# sourceMappingURL=collectProjectHostInputs.js.map

package/lib/plugin/internal/load/collectProjectHostInputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectProjectHostInputs.js","sourceRoot":"","sources":["../../../../src/plugin/internal/load/collectProjectHostInputs.ts"],"names":[],"mappings":";;;;;;AAAA,6CAA4C;AAC5C,0DAA6B;AAG7B,uEAAoE;AACpE,+EAA4E;AAE5E;;;;;;;;;;;;;GAaG;AACH,kCACE,OAAiC,EACjC,sBAAsB,GAAY,IAAI;IAEtC,MAAM,MAAM,GAAG,IAAI,GAAG,CACpB,CAAC,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACrE,mBAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CACnB,CACF,CAAC;IACF,IAAI,CAAC,sBAAsB;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,MAAM,kBAAkB,GACtB,iDAAuB,CAAC,mCAAmC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,KAAK,MAAM,SAAS,IAAI,kBAAkB;QAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,CACtC,iDAAuB,CAAC,YAAY,CACrC,CAAC;IACF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,eAAe,GACnB,iDAAuB,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACxD,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,WAAW,GAAG,mBAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC3C,KAAK,MAAM,UAAU,IAAI,iDAAuB,CAAC,qBAAqB,CACpE,eAAe,CAChB,EAAE,CAAC;gBACF,MAAM,kBAAkB,GACtB,iDAAuB,CAAC,4BAA4B,CAClD,UAAU,EACV,WAAW,CACZ,CAAC;gBACJ,KAAK,MAAM,SAAS,IAAI,mCAAmC,CACzD,UAAU,EACV,QAAQ,EACR,kBAAkB,CACnB,EAAE,CAAC;oBACF,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBACxB,CAAC;gBACD,IAAI,kBAAkB,KAAK,SAAS,EAAE,CAAC;oBACrC,MAAM,CAAC,GAAG,CAAC,mBAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC;gBAC/C,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,SAAS,mCAAmC,CAC1C,WAAmB,EACnB,UAAkB,EAClB,gBAAoC;IAEpC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,UAAU,IAAI,IAAA,2BAAa,EAAC,UAAU,CAAC,CAAC,OAAO,CAAC,KAAK,CAC9D,WAAW,CACZ,IAAI,EAAE,EAAE,CAAC;QACR,MAAM,gBAAgB,GAAG,mBAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1E,GAAG,CAAC,IAAI,CAAC,mBAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,cAAc,CAAC,CAAC,CAAC;QACtD,IAAI,IAAA,yDAA2B,EAAC,gBAAgB,EAAE,gBAAgB,EAAE,EAAE,CAAC;YACrE,MAAM;IACV,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/lib/plugin/internal/load/composePluginSources.d.ts

@@ -0,0 +1,20 @@
+import type { ITtscPlugin } from "../../../structures/ITtscPlugin";
+import type { ProjectPluginEntries } from "./ProjectPluginEntries";
+/**
+ * Resolve descriptor composition from the original ordered plugin records.
+ *
+ * One-hop redirects inherit source, contributors and host capabilities from
+ * their aggregate without cascading through another redirected descriptor.
+ * Conflicting aggregates, reciprocal cycles and target-owned contributors are
+ * rejected before any Go producer is built. Input records are not mutated.
+ *
+ * @evidence contracts/common.md#principled-implementation Uses original descriptor identities for every alias edge, detects reciprocal cycles and conflicting owners, and copies only the selected aggregate host fields; nontransitive composition cannot read a previously redirected answer.
+ * @evidence contracts/common.md#clear-and-simple-design Pure composition owns redirects while descriptor evaluation and native compilation remain in loadProjectPlugins; the private matcher compares only exact declared name or transform specifier.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No plugin-name exception or guessed source identity permits a redirect; incompatible target contributors and ambiguous aggregate owners fail with their existing diagnostics.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states one-hop inheritance, original-record lookup, nonmutation and rejection before native build; inline comments explain contributor and capability ownership.
+ * @evidence contracts/performance.md#efficient-algorithms For n plugins, a aggregates and at most k aliases per aggregate, initial wrapper construction/filtering costs O(n), including the no-aggregate path's returned copy. Validation scans all aliases, reciprocal-cycle checks perform O(a squared times k) alias comparisons and redirect selection performs O(n times a times k) comparisons. Trimming and string equality additionally depend on alias/name/specifier lengths, and redirected record spreads copy their enumerable fields. Direct scans preserve original-record one-hop selection; the implementation imposes no population bound and does not claim constant-cost string comparisons.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Composition uses this invocation's original descriptors and entry aliases; it owns no completed-answer cache or cross-request sharing.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Initial wrappers for all plugins, the selected aggregate array, matching-reference arrays and redirected shallow records are invocation-local or returned to the caller; shared contributor/capability objects remain borrowed descriptor values. No history or live handle is acquired.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This body compares declared names and transform specifiers as exact aliases and transfers source/contributor/capability values without resolving a path, opening a file or launching a process. Native source identity and building remain loader responsibilities.
+ */
+export declare function composePluginSources(entries: readonly ProjectPluginEntries.ProjectPluginEntry[], plugins: readonly ITtscPlugin[]): ITtscPlugin[];

package/lib/plugin/internal/load/composePluginSources.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composePluginSources = composePluginSources;
+/**
+ * Resolve descriptor composition from the original ordered plugin records.
+ *
+ * One-hop redirects inherit source, contributors and host capabilities from
+ * their aggregate without cascading through another redirected descriptor.
+ * Conflicting aggregates, reciprocal cycles and target-owned contributors are
+ * rejected before any Go producer is built. Input records are not mutated.
+ *
+ * @evidence contracts/common.md#principled-implementation Uses original descriptor identities for every alias edge, detects reciprocal cycles and conflicting owners, and copies only the selected aggregate host fields; nontransitive composition cannot read a previously redirected answer.
+ * @evidence contracts/common.md#clear-and-simple-design Pure composition owns redirects while descriptor evaluation and native compilation remain in loadProjectPlugins; the private matcher compares only exact declared name or transform specifier.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No plugin-name exception or guessed source identity permits a redirect; incompatible target contributors and ambiguous aggregate owners fail with their existing diagnostics.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states one-hop inheritance, original-record lookup, nonmutation and rejection before native build; inline comments explain contributor and capability ownership.
+ * @evidence contracts/performance.md#efficient-algorithms For n plugins, a aggregates and at most k aliases per aggregate, initial wrapper construction/filtering costs O(n), including the no-aggregate path's returned copy. Validation scans all aliases, reciprocal-cycle checks perform O(a squared times k) alias comparisons and redirect selection performs O(n times a times k) comparisons. Trimming and string equality additionally depend on alias/name/specifier lengths, and redirected record spreads copy their enumerable fields. Direct scans preserve original-record one-hop selection; the implementation imposes no population bound and does not claim constant-cost string comparisons.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Composition uses this invocation's original descriptors and entry aliases; it owns no completed-answer cache or cross-request sharing.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Initial wrappers for all plugins, the selected aggregate array, matching-reference arrays and redirected shallow records are invocation-local or returned to the caller; shared contributor/capability objects remain borrowed descriptor values. No history or live handle is acquired.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This body compares declared names and transform specifiers as exact aliases and transfers source/contributor/capability values without resolving a path, opening a file or launching a process. Native source identity and building remain loader responsibilities.
+ */
+function composePluginSources(entries, plugins) {
+    const aggregates = plugins
+        .map((plugin, index) => ({ index, plugin }))
+        .filter(({ plugin }) => Array.isArray(plugin.composes));
+    if (aggregates.length === 0) {
+        return [...plugins];
+    }
+    for (const { plugin } of aggregates) {
+        for (const target of plugin.composes) {
+            if (typeof target !== "string" || target.trim() === "") {
+                throw new Error(`ttsc: plugin "${plugin.name}" has an invalid "composes" target; ` +
+                    `targets must be non-empty plugin names or transform specifiers`);
+            }
+        }
+    }
+    // Composition is intentionally one hop only: A.composes=[B] sends B to A's
+    // binary, but if B.composes=[C] then C uses B's original source and does NOT
+    // cascade to A. Detect cycles (A.composes=[B] && B.composes=[A]) and throw,
+    // otherwise the silent reswap below would mis-route both plugins.
+    for (const { index: i, plugin: a } of aggregates) {
+        for (const { index: j, plugin: b } of aggregates) {
+            if (i === j)
+                continue;
+            const aTransform = entries[i]?.config.transform;
+            const bTransform = entries[j]?.config.transform;
+            const aComposesB = a.composes.some((alias) => matchesPluginAlias(alias, b, bTransform));
+            const bComposesA = b.composes.some((alias) => matchesPluginAlias(alias, a, aTransform));
+            if (aComposesB && bComposesA) {
+                throw new Error(`ttsc: plugin composes cycle detected between "${a.name}" and "${b.name}"; ` +
+                    `each plugin lists the other in its "composes" array — composition is one hop only, not transitive`);
+            }
+        }
+    }
+    return plugins.map((plugin, index) => {
+        const transform = entries[index]?.config.transform;
+        const matchingAggregates = aggregates.filter(({ index: aggregateIndex, plugin: aggregatePlugin }) => aggregateIndex !== index &&
+            aggregatePlugin.composes.some((alias) => matchesPluginAlias(alias, plugin, transform)));
+        if (matchingAggregates.length > 1) {
+            throw new Error(`ttsc: plugin "${plugin.name}" is composed by multiple aggregate plugins; ` +
+                `each plugin entry can be redirected to only one aggregate native host`);
+        }
+        const aggregate = matchingAggregates[0];
+        if (aggregate === undefined) {
+            return plugin;
+        }
+        // A composed plugin's source is rerouted to the aggregate's binary,
+        // so its own `contributors` would link into a different host than
+        // it was authored against. The "one binary" guarantee in the
+        // protocol doc holds only when the composed plugin defers entirely
+        // to the aggregate; reject early instead of silently producing two
+        // diverging binaries.
+        if (plugin.contributors && plugin.contributors.length > 0) {
+            throw new Error(`ttsc: plugin "${plugin.name}" is composed by "${aggregate.plugin.name}" but declares its own "contributors"; ` +
+                `move the contributors onto the aggregate plugin or drop the composes redirect`);
+        }
+        return {
+            ...plugin,
+            source: aggregate.plugin.source,
+            contributors: aggregate.plugin.contributors,
+            // The composed plugin's runtime BINARY is the aggregate's binary,
+            // so the CLI surface (which flags the sidecar parses) is the
+            // aggregate's. Inherit `capabilities` from the aggregate so a
+            // capability the aggregate declares — e.g. threadingArgs — does
+            // not get silently dropped just because the composed entry's own
+            // descriptor omitted it. An absent aggregate declaration is also its
+            // own CLI contract; a redirected library cannot certify the new host.
+            capabilities: aggregate.plugin.capabilities,
+        };
+    });
+}
+function matchesPluginAlias(alias, plugin, transform) {
+    return (alias === plugin.name ||
+        (typeof transform === "string" && alias === transform));
+}
+//# sourceMappingURL=composePluginSources.js.map

package/lib/plugin/internal/load/composePluginSources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composePluginSources.js","sourceRoot":"","sources":["../../../../src/plugin/internal/load/composePluginSources.ts"],"names":[],"mappings":"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"}

package/lib/plugin/internal/load/declaresHostInputReads.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether a descriptor supplies a fingerprint-record declaration covering its
+ * explicit hostInputs, by resolved native path keys.
+ *
+ * An explicit empty record declares no external reads. This shape/key predicate
+ * cannot detect omitted reads or validate fingerprint values; producer honesty,
+ * evaluator observations and cache proof acceptance remain separate premises. A
+ * caught filesystem failure or the observed module graph alone cannot prove the
+ * complete external input set.
+ *
+ * A `hostInputs` entry without a fingerprint is a declared input whose state
+ * the descriptor could not prove, the way the protocol reports contradictory
+ * observations, so it leaves the answer unproven too.
+ *
+ * @evidence contracts/common.md#principled-implementation A record-valued fingerprint declaration is required, including an explicit empty record for no external reads; every declared host input must have a resolved-path key before an evaluation can claim reproducibility.
+ * @evidence contracts/common.md#clear-and-simple-design This predicate establishes the presence/completeness declaration only; fingerprint value validation and state proof remain with descriptor validation and cache readers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Undeclared reads do not gain cache eligibility through a guessed module graph or permission-model workaround; the producer must state its actual external input set.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains the explicit empty declaration, unsupported observation gap and missing-fingerprint refusal in distinct paragraphs under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.resolve compares native input spellings through the same host path semantics; this declaration checker does not require POSIX separators or use OS names to guess filesystem identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The resolved-key Set and normalized path temporaries are call-local; no historical descriptor population, handle or cache lifecycle is owned.
+ * @evidence contracts/performance.md#efficient-algorithms With explicit hostInputs, enumerable fingerprint keys are resolved into a Set and each supplied string is resolved for indexed membership. Key/input counts and complete path text, native normalization, property enumeration and ordinary descriptor accessor work drive cost; the explicit-inputs-absent case skips key materialization.
+ * @evidence contracts/performance.md#reuse-equivalent-work The resolved-key Set is shared by membership checks within this descriptor, while no cross-request cache or reusable producer identity is owned here.
+ */
+export declare function declaresHostInputReads(descriptor: unknown): boolean;

package/lib/plugin/internal/load/declaresHostInputReads.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.declaresHostInputReads = declaresHostInputReads;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Whether a descriptor supplies a fingerprint-record declaration covering its
+ * explicit hostInputs, by resolved native path keys.
+ *
+ * An explicit empty record declares no external reads. This shape/key predicate
+ * cannot detect omitted reads or validate fingerprint values; producer honesty,
+ * evaluator observations and cache proof acceptance remain separate premises. A
+ * caught filesystem failure or the observed module graph alone cannot prove the
+ * complete external input set.
+ *
+ * A `hostInputs` entry without a fingerprint is a declared input whose state
+ * the descriptor could not prove, the way the protocol reports contradictory
+ * observations, so it leaves the answer unproven too.
+ *
+ * @evidence contracts/common.md#principled-implementation A record-valued fingerprint declaration is required, including an explicit empty record for no external reads; every declared host input must have a resolved-path key before an evaluation can claim reproducibility.
+ * @evidence contracts/common.md#clear-and-simple-design This predicate establishes the presence/completeness declaration only; fingerprint value validation and state proof remain with descriptor validation and cache readers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Undeclared reads do not gain cache eligibility through a guessed module graph or permission-model workaround; the producer must state its actual external input set.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains the explicit empty declaration, unsupported observation gap and missing-fingerprint refusal in distinct paragraphs under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.resolve compares native input spellings through the same host path semantics; this declaration checker does not require POSIX separators or use OS names to guess filesystem identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The resolved-key Set and normalized path temporaries are call-local; no historical descriptor population, handle or cache lifecycle is owned.
+ * @evidence contracts/performance.md#efficient-algorithms With explicit hostInputs, enumerable fingerprint keys are resolved into a Set and each supplied string is resolved for indexed membership. Key/input counts and complete path text, native normalization, property enumeration and ordinary descriptor accessor work drive cost; the explicit-inputs-absent case skips key materialization.
+ * @evidence contracts/performance.md#reuse-equivalent-work The resolved-key Set is shared by membership checks within this descriptor, while no cross-request cache or reusable producer identity is owned here.
+ */
+function declaresHostInputReads(descriptor) {
+    if (typeof descriptor !== "object" ||
+        descriptor === null ||
+        Array.isArray(descriptor))
+        return false;
+    const { hostInputHashes, hostInputs } = descriptor;
+    if (typeof hostInputHashes !== "object" ||
+        hostInputHashes === null ||
+        Array.isArray(hostInputHashes))
+        return false;
+    if (hostInputs === undefined)
+        return true;
+    if (!Array.isArray(hostInputs))
+        return false;
+    const fingerprinted = new Set(Object.keys(hostInputHashes).map((file) => node_path_1.default.resolve(file)));
+    return hostInputs.every((input) => typeof input === "string" && fingerprinted.has(node_path_1.default.resolve(input)));
+}
+//# sourceMappingURL=declaresHostInputReads.js.map

package/lib/plugin/internal/load/declaresHostInputReads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declaresHostInputReads.js","sourceRoot":"","sources":["../../../../src/plugin/internal/load/declaresHostInputReads.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,gCAAuC,UAAmB;IACxD,IACE,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QAEzB,OAAO,KAAK,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,UAGvC,CAAC;IACF,IACE,OAAO,eAAe,KAAK,QAAQ;QACnC,eAAe,KAAK,IAAI;QACxB,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC;QAE9B,OAAO,KAAK,CAAC;IACf,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7C,MAAM,aAAa,GAAG,IAAI,GAAG,CAC3B,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,mBAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAC/D,CAAC;IACF,OAAO,UAAU,CAAC,KAAK,CACrB,CAAC,KAAK,EAAE,EAAE,CACR,OAAO,KAAK,KAAK,QAAQ,IAAI,aAAa,CAAC,GAAG,CAAC,mBAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CACtE,CAAC;AACJ,CAAC"}

package/lib/plugin/internal/load/hasProjectPluginEntries.d.ts

@@ -0,0 +1,21 @@
+import type { ITtscProjectPluginConfig } from "../../../structures/ITtscProjectPluginConfig";
+import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITtscParsedProjectConfig";
+/**
+ * Return `true` when the project has at least one enabled plugin entry.
+ *
+ * Used by callers that need to skip plugin-specific work when no plugins are
+ * configured, without evaluating descriptors or building plugin artifacts.
+ * Discovery still resolves the complete entry list before checking presence;
+ * omitted entries can therefore read manifests and resolve native packages.
+ *
+ * @param entries - Explicit entries; `false` always returns `false`.
+ * @evidence contracts/common.md#principled-implementation Explicit false disables all plugin discovery; otherwise the shared entry resolver's enabled-not-false predicate checks the same population the loader would consider.
+ * @evidence contracts/common.md#clear-and-simple-design The presence query delegates config/package selection to its owner instead of reproducing descriptor evaluation or build logic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Enabled selection follows declared configuration, without assuming a known package marker or fabricating absence after a resolver error.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc states why the presence query exists and how explicit false differs from omitted entries; prose/tag separation follows the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation The project-entry resolver owns native config/package resolution; this adapter applies no POSIX parsing or additional path/case normalization to its answer.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This query owns no retained handle or cross-call collection; resolved entry wrappers and discovery indexes are invocation-local, with payloads borrowed from the project or parsed manifests.
+ * @evidence contracts/performance.md#efficient-algorithms Explicit false avoids discovery. Otherwise resolution materializes all entries before an at-most-linear enabled scan; explicit lists allocate one wrapper per entry, while omitted lists additionally incur ancestor, manifest-byte, dependency and native specifier-resolution work delegated to the entry resolver. No fixed project-size bound is imposed.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This fresh presence observation coordinates no reusable producer result across calls; it neither retains package authority nor promises that subsequent loading avoids discovery again.
+ */
+export declare function hasProjectPluginEntries(project: ITtscParsedProjectConfig, entries?: readonly ITtscProjectPluginConfig[] | false): boolean;