ttsc 0.30.4 → 0.31.0

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

@@ -0,0 +1,29 @@
+import type { ITtscPlugin } from "../../../structures/ITtscPlugin";
+import type { ITtscProjectPluginConfig } from "../../../structures/ITtscProjectPluginConfig";
+import { NativeSourcePackages } from "../source/NativeSourcePackages";
+/**
+ * Resolve the Go module and Go-owned proposed native kind of a source.
+ *
+ * Nested transform proposals preserve admitted source layout under the generic
+ * host's root manifests, with the tool pinned at the original module. Root and
+ * check sources retain their own manifests. The loader must confirm executable
+ * proposals in their full owning module and linked proposals inside each chosen
+ * actual host; this adapter cannot choose that host. Go errors and empty
+ * production-file selections are terminal.
+ *
+ * @evidence contracts/common.md#principled-implementation Real source admission and module discovery precede actual prospective-context Go metadata; only an error-free production package proposes executable or linked ownership, while final actual-context admission belongs to the loader/build.
+ * @evidence contracts/common.md#clear-and-simple-design Source/module admission and selected package observation have separate owners; callers may supply this load's batched observation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No lexical scanner, filename exception or partial constraint parser substitutes for the selected Go tool.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes Go-owned package selection and erroneous-name rejection.
+ * @evidence contracts/portability.md#os-neutral-implementation Native module/path and effective-environment owners preserve platform identity; Go interprets target selection.
+ * @evidence contracts/performance.md#efficient-algorithms Module discovery is bounded; a missing supplied observation delegates contextual copy/workspace setup and one metadata command, without dependency compilation.
+ * @evidence contracts/performance.md#reuse-equivalent-work Loader-supplied observations batch equivalent packages within one load; direct calls reobserve current inputs and retain no cross-load cache.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Delegated metadata scratch has retirement-aware cleanup; returned module/kind strings transfer to the caller and no source handle is retained here.
+ */
+export declare function resolveNativeSource(source: string, plugin: ITtscPlugin, config: ITtscProjectPluginConfig, index: number, options?: {
+    env?: NodeJS.ProcessEnv;
+    observation?: NativeSourcePackages.Package;
+}): {
+    kind: "executable" | "linked";
+    moduleRoot: string;
+};

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

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveNativeSource = resolveNativeSource;
+const SidecarEnvironment_1 = require("../../../compiler/internal/sharedHost/SidecarEnvironment");
+const NativeSourcePackages_1 = require("../source/NativeSourcePackages");
+const resolvePluginGoModule_1 = require("../source/resolvePluginGoModule");
+const pluginLabel_1 = require("./pluginLabel");
+const requirePluginSource_1 = require("./requirePluginSource");
+/**
+ * Resolve the Go module and Go-owned proposed native kind of a source.
+ *
+ * Nested transform proposals preserve admitted source layout under the generic
+ * host's root manifests, with the tool pinned at the original module. Root and
+ * check sources retain their own manifests. The loader must confirm executable
+ * proposals in their full owning module and linked proposals inside each chosen
+ * actual host; this adapter cannot choose that host. Go errors and empty
+ * production-file selections are terminal.
+ *
+ * @evidence contracts/common.md#principled-implementation Real source admission and module discovery precede actual prospective-context Go metadata; only an error-free production package proposes executable or linked ownership, while final actual-context admission belongs to the loader/build.
+ * @evidence contracts/common.md#clear-and-simple-design Source/module admission and selected package observation have separate owners; callers may supply this load's batched observation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No lexical scanner, filename exception or partial constraint parser substitutes for the selected Go tool.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes Go-owned package selection and erroneous-name rejection.
+ * @evidence contracts/portability.md#os-neutral-implementation Native module/path and effective-environment owners preserve platform identity; Go interprets target selection.
+ * @evidence contracts/performance.md#efficient-algorithms Module discovery is bounded; a missing supplied observation delegates contextual copy/workspace setup and one metadata command, without dependency compilation.
+ * @evidence contracts/performance.md#reuse-equivalent-work Loader-supplied observations batch equivalent packages within one load; direct calls reobserve current inputs and retain no cross-load cache.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Delegated metadata scratch has retirement-aware cleanup; returned module/kind strings transfer to the caller and no source handle is retained here.
+ */
+function resolveNativeSource(source, plugin, config, index, options) {
+    const label = (0, pluginLabel_1.pluginLabel)(plugin, config, index);
+    (0, requirePluginSource_1.requirePluginSource)(source, label);
+    const { moduleRoot } = (0, resolvePluginGoModule_1.resolvePluginGoModule)(source, label);
+    const observation = options?.observation ?? NativeSourcePackages_1.NativeSourcePackages.propose([
+        { source, label, ownModule: plugin.stage === "check" },
+    ], SidecarEnvironment_1.SidecarEnvironment.merge(options?.env ?? process.env))[0].observation;
+    return { kind: NativeSourcePackages_1.NativeSourcePackages.kind(observation, label), moduleRoot };
+}
+//# sourceMappingURL=resolveNativeSource.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveNativeSource.js","sourceRoot":"","sources":["../../../../src/plugin/internal/load/resolveNativeSource.ts"],"names":[],"mappings":";;;AAAA,iGAA8F;AAG9F,yEAAsE;AACtE,2EAAwE;AACxE,+CAA4C;AAC5C,+DAA4D;AAE5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,6BACE,MAAc,EACd,MAAmB,EACnB,MAAgC,EAChC,KAAa,EACb,OAAiF;IAEjF,MAAM,KAAK,GAAG,IAAA,yBAAW,EAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACjD,IAAA,yCAAmB,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACnC,MAAM,EAAE,UAAU,EAAE,GAAG,IAAA,6CAAqB,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5D,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,2CAAoB,CAAC,OAAO,CAAC;QACvE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,KAAK,KAAK,OAAO,EAAE;KACvD,EAAE,uCAAkB,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,CAAC;IAC1E,OAAO,EAAE,IAAI,EAAE,2CAAoB,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;AAC7E,CAAC"}

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

@@ -0,0 +1,22 @@
+import type { ITtscPlugin } from "../../../structures/ITtscPlugin";
+/**
+ * Validate contributor records before native host compilation.
+ *
+ * The source preflight requires an immediate regular filename ending in .go but
+ * not _test.go. It does not parse package syntax, build constraints or platform
+ * suffixes; actual Go compilation owns buildability.
+ *
+ * @evidence contracts/common.md#principled-implementation Ordered record checks establish unique accepted names, absolute observed source directories and a regular non-test .go filename before best-effort physical normalization. These checks do not certify Go package buildability or freeze filesystem identity.
+ * @evidence contracts/common.md#clear-and-simple-design One traversal owns contributor admission; a private directory predicate isolates regular non-test filename discovery.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The actual loader now calls this unchanged guard; unit callers do not replace contributor compilation or transport assertions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes filename preflight from actual buildability; returned source strings use best-effort native realpath and can retain original spelling on failure.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.isAbsolute, fs.stat, readdir and resolveRealPath preserve platform path and physical-source distinctions rather than using POSIX string heuristics.
+ * @evidence contracts/performance.md#efficient-algorithms Each contributor is checked with indexed seen-name membership and one direct directory listing, without recursive payload scans. Name regex/hash and path/entry text, native existence/stat/realpath operations and complete immediate-entry materialization contribute cost; record count alone does not bound that work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Within one request the seen-name set avoids repeated name searches; filesystem admission is reobserved because callers may mutate contributor source between requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Name sets and directory listings are invocation-local; returned ordered records transfer to the caller. Their bytes grow with accepted records and names/paths, while a listing materializes all immediate entries; no population ceiling or historical cache is owned here and synchronous filesystem APIs retain no open handle.
+ */
+export declare function validatePluginContributors(plugin: ITtscPlugin): readonly {
+    name: string;
+    source: string;
+}[] | undefined;

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

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePluginContributors = validatePluginContributors;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const PluginPackageResolution_1 = require("./PluginPackageResolution");
+/**
+ * Validate contributor records before native host compilation.
+ *
+ * The source preflight requires an immediate regular filename ending in .go but
+ * not _test.go. It does not parse package syntax, build constraints or platform
+ * suffixes; actual Go compilation owns buildability.
+ *
+ * @evidence contracts/common.md#principled-implementation Ordered record checks establish unique accepted names, absolute observed source directories and a regular non-test .go filename before best-effort physical normalization. These checks do not certify Go package buildability or freeze filesystem identity.
+ * @evidence contracts/common.md#clear-and-simple-design One traversal owns contributor admission; a private directory predicate isolates regular non-test filename discovery.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The actual loader now calls this unchanged guard; unit callers do not replace contributor compilation or transport assertions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes filename preflight from actual buildability; returned source strings use best-effort native realpath and can retain original spelling on failure.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.isAbsolute, fs.stat, readdir and resolveRealPath preserve platform path and physical-source distinctions rather than using POSIX string heuristics.
+ * @evidence contracts/performance.md#efficient-algorithms Each contributor is checked with indexed seen-name membership and one direct directory listing, without recursive payload scans. Name regex/hash and path/entry text, native existence/stat/realpath operations and complete immediate-entry materialization contribute cost; record count alone does not bound that work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Within one request the seen-name set avoids repeated name searches; filesystem admission is reobserved because callers may mutate contributor source between requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Name sets and directory listings are invocation-local; returned ordered records transfer to the caller. Their bytes grow with accepted records and names/paths, while a listing materializes all immediate entries; no population ceiling or historical cache is owned here and synchronous filesystem APIs retain no open handle.
+ */
+function validatePluginContributors(plugin) {
+    const contributors = plugin.contributors;
+    if (contributors === undefined)
+        return undefined;
+    if (!Array.isArray(contributors)) {
+        throw new Error(`ttsc: plugin "${plugin.name}" "contributors" must be an array of { name, source } entries`);
+    }
+    if (contributors.length === 0)
+        return undefined;
+    const seen = new Set();
+    const out = [];
+    for (const [index, entry] of contributors.entries()) {
+        if (typeof entry !== "object" || entry === null) {
+            throw new Error(`ttsc: plugin "${plugin.name}" contributors[${index}] must be an object`);
+        }
+        const { name, source } = entry;
+        if (typeof name !== "string" || !CONTRIBUTOR_NAME_PATTERN.test(name)) {
+            throw new Error(`ttsc: plugin "${plugin.name}" contributors[${index}].name must match /^[a-z][a-z0-9_]*$/; ` +
+                `got ${JSON.stringify(name)}`);
+        }
+        if (seen.has(name)) {
+            throw new Error(`ttsc: plugin "${plugin.name}" contributors[${index}] duplicate name ${JSON.stringify(name)}`);
+        }
+        seen.add(name);
+        if (typeof source !== "string" || source.length === 0) {
+            throw new Error(`ttsc: plugin "${plugin.name}" contributors[${index}].source must be a non-empty string`);
+        }
+        if (!node_path_1.default.isAbsolute(source)) {
+            throw new Error(`ttsc: plugin "${plugin.name}" contributors[${index}].source must be an absolute path; ` +
+                `got ${JSON.stringify(source)}`);
+        }
+        if (!node_fs_1.default.existsSync(source) || !node_fs_1.default.statSync(source).isDirectory()) {
+            throw new Error(`ttsc: plugin "${plugin.name}" contributors[${index}].source must be an existing directory: ${source}`);
+        }
+        // Reject a directory lacking a regular non-test Go filename before
+        // native host compilation can attribute a failure to scratch paths.
+        // Filename admission does not certify package syntax or build constraints.
+        if (!hasBuildableGoSource(source)) {
+            throw new Error(`ttsc: plugin "${plugin.name}" contributors[${index}].source must contain at least one non-test ".go" file: ${source}`);
+        }
+        out.push({ name, source: PluginPackageResolution_1.PluginPackageResolution.resolveRealPath(source) });
+    }
+    return out;
+}
+const CONTRIBUTOR_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+function hasBuildableGoSource(dir) {
+    // This immediate filename preflight is narrower than actual Go admission.
+    // Ignored filename prefixes, build constraints and syntax remain compiler-owned.
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    return entries.some((entry) => entry.isFile() &&
+        entry.name.endsWith(".go") &&
+        !entry.name.endsWith("_test.go"));
+}
+//# sourceMappingURL=validatePluginContributors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validatePluginContributors.js","sourceRoot":"","sources":["../../../../src/plugin/internal/load/validatePluginContributors.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAG7B,uEAAoE;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,oCACE,MAAmB;IAEnB,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IACzC,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACjD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,IAAI,+DAA+D,CAC5F,CAAC;IACJ,CAAC;IACD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAuC,EAAE,CAAC;IACnD,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,IAAI,kBAAkB,KAAK,qBAAqB,CACzE,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,KAA6C,CAAC;QACvE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACrE,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,IAAI,kBAAkB,KAAK,yCAAyC;gBAC1F,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAChC,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,IAAI,kBAAkB,KAAK,oBAAoB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAC9F,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,IAAI,kBAAkB,KAAK,qCAAqC,CACzF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,mBAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,IAAI,kBAAkB,KAAK,qCAAqC;gBACtF,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAClC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,iBAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YACjE,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,IAAI,kBAAkB,KAAK,2CAA2C,MAAM,EAAE,CACvG,CAAC;QACJ,CAAC;QACD,mEAAmE;QACnE,oEAAoE;QACpE,2EAA2E;QAC3E,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,IAAI,kBAAkB,KAAK,2DAA2D,MAAM,EAAE,CACvH,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,iDAAuB,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,wBAAwB,GAAG,mBAAmB,CAAC;AAErD,SAAS,oBAAoB,CAAC,GAAW;IACvC,0EAA0E;IAC1E,iFAAiF;IACjF,IAAI,OAAoB,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,GAAG,iBAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CACjB,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,MAAM,EAAE;QACd,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAC1B,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CACnC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,14 @@
+import type { ITtscPlugin } from "../../../structures/ITtscPlugin";
+/**
+ * Require a nonempty string source on a plugin descriptor.
+ *
+ * @evidence contracts/common.md#principled-implementation The actual loader accepts only nonempty string source identity; absent, empty and nonstring values retain the same authored diagnostic.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate distinguishes source presence before path resolution and native admission.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The production loader calls this source-field guard before native path admission; no expected descriptor value or test-side implementation replaces that operation.
+ * @evidence contracts/common.md#meaningful-documentation The headline identifies the accepted descriptor field and the rejected boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources validatePluginSource acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidence contracts/performance.md#efficient-algorithms Source admission checks property type and string length without scanning source contents or resolving paths. Property reads retain ordinary descriptor object semantics; this guard does not bound user-defined accessor work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work No expensive shared producer, reusable-answer identity or cross-request state is coordinated by this source-field guard.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation validatePluginSource computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+export declare function validatePluginSource(plugin: ITtscPlugin): void;

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

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePluginSource = validatePluginSource;
+/**
+ * Require a nonempty string source on a plugin descriptor.
+ *
+ * @evidence contracts/common.md#principled-implementation The actual loader accepts only nonempty string source identity; absent, empty and nonstring values retain the same authored diagnostic.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate distinguishes source presence before path resolution and native admission.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The production loader calls this source-field guard before native path admission; no expected descriptor value or test-side implementation replaces that operation.
+ * @evidence contracts/common.md#meaningful-documentation The headline identifies the accepted descriptor field and the rejected boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources validatePluginSource acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidence contracts/performance.md#efficient-algorithms Source admission checks property type and string length without scanning source contents or resolving paths. Property reads retain ordinary descriptor object semantics; this guard does not bound user-defined accessor work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work No expensive shared producer, reusable-answer identity or cross-request state is coordinated by this source-field guard.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation validatePluginSource computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+function validatePluginSource(plugin) {
+    if (typeof plugin.source !== "string" || plugin.source.length === 0) {
+        throw new Error(`ttsc: plugin must declare source`);
+    }
+}
+//# sourceMappingURL=validatePluginSource.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validatePluginSource.js","sourceRoot":"","sources":["../../../../src/plugin/internal/load/validatePluginSource.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH,8BAAqC,MAAmB;IACtD,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,36 @@
+/**
+ * Visit the candidates of the package a `#` import resolved into, in every
+ * search root from the importer up to the one that selected it.
+ *
+ * A package's `imports` may map a `#` specifier to a bare package, which Node
+ * looks up through the ordinary `node_modules` search from the importer. A
+ * nearer copy of that package, a nested install or a moved workspace package,
+ * would be selected instead, so the candidates the lookup found missing in the
+ * nearer roots are inputs of whatever the importer evaluated. The package is
+ * named by the resolved module itself, by the directory after its last
+ * `node_modules`, or by the linked entry of a search root it lies in, so Node's
+ * `imports` algorithm is not copied. A target inside the importer's own
+ * package, or one no search root selects, visits nothing. Expansion also visits
+ * possible manifest target spellings; this conservative input population can
+ * exceed the spellings the completed Node resolver used.
+ *
+ * The rule is the resolution input recorder's
+ * (`RESOLUTION_INPUT_RECORDER_PATH`).
+ *
+ * @param parent The importer, a path or a file URL.
+ * @param resolved The module the resolution selected, a path or a file URL.
+ * @param extensions The extensions the evaluator's resolution probes.
+ * @param witnesses What `observeImportSearchRoots` took before the resolution,
+ *   or `undefined` when the caller observes nothing itself.
+ * @param visit Receives each candidate, and whether its search root moved since
+ *   `witnesses`, which leaves the candidate without proof.
+ * @evidence contracts/common.md#principled-implementation The selected target identifies the bare package a hash-import reached; nearer roots' candidates remain inputs and changed pre-resolution root witnesses prevent claiming stable proof.
+ * @evidence contracts/common.md#clear-and-simple-design A shared visitor emits candidates through the caller callback instead of duplicating imports resolution or retaining a second candidate population.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual selected targets and supplied probe extensions drive the recorder's exported visitor; this adapter neither modifies Node nor guesses one known package's missing paths.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains selected-root bounds, linked packages, witness timing and the moved flag in separated prose and parameter entries under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path/file-URL vocabulary and linked physical selection are handled by the shared recorder; this adapter forwards them without slash-only parsing or blanket case conversion.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Witnesses are borrowed; delegated root/candidate arrays, manifest values and base deduplication are query-local, while emitted records belong to the callback. This adapter retains no watcher, handle or cross-query population.
+ * @evidence contracts/performance.md#efficient-algorithms Delegation includes importer-manifest ancestor search, lexical/physical selected-path lookup, root/name candidate scans and possible linked/scoped directory listings with native identity queries. Candidate expansion recursively reads/parses manifest target values with a normalized-base Set; path/extension/manifest bytes, root/entry counts and callback work drive cost, not merely the final selected-root prefix.
+ * @evidence contracts/performance.md#reuse-equivalent-work One delegated base Set prevents duplicate expansion across manifest targets, and supplied witnesses retain the earlier root observation for movement checks. No mutable filesystem lookup answer is reused across resolution windows.
+ */
+export declare function visitImportMappedCandidates(parent: string | undefined, resolved: string | undefined, extensions: readonly string[], witnesses: ReadonlyMap<string, string | undefined> | undefined, visit: (file: string, moved: boolean) => void): void;

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

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visitImportMappedCandidates = visitImportMappedCandidates;
+const RESOLUTION_INPUT_RECORDER_PATH_1 = require("./RESOLUTION_INPUT_RECORDER_PATH");
+/**
+ * Visit the candidates of the package a `#` import resolved into, in every
+ * search root from the importer up to the one that selected it.
+ *
+ * A package's `imports` may map a `#` specifier to a bare package, which Node
+ * looks up through the ordinary `node_modules` search from the importer. A
+ * nearer copy of that package, a nested install or a moved workspace package,
+ * would be selected instead, so the candidates the lookup found missing in the
+ * nearer roots are inputs of whatever the importer evaluated. The package is
+ * named by the resolved module itself, by the directory after its last
+ * `node_modules`, or by the linked entry of a search root it lies in, so Node's
+ * `imports` algorithm is not copied. A target inside the importer's own
+ * package, or one no search root selects, visits nothing. Expansion also visits
+ * possible manifest target spellings; this conservative input population can
+ * exceed the spellings the completed Node resolver used.
+ *
+ * The rule is the resolution input recorder's
+ * (`RESOLUTION_INPUT_RECORDER_PATH`).
+ *
+ * @param parent The importer, a path or a file URL.
+ * @param resolved The module the resolution selected, a path or a file URL.
+ * @param extensions The extensions the evaluator's resolution probes.
+ * @param witnesses What `observeImportSearchRoots` took before the resolution,
+ *   or `undefined` when the caller observes nothing itself.
+ * @param visit Receives each candidate, and whether its search root moved since
+ *   `witnesses`, which leaves the candidate without proof.
+ * @evidence contracts/common.md#principled-implementation The selected target identifies the bare package a hash-import reached; nearer roots' candidates remain inputs and changed pre-resolution root witnesses prevent claiming stable proof.
+ * @evidence contracts/common.md#clear-and-simple-design A shared visitor emits candidates through the caller callback instead of duplicating imports resolution or retaining a second candidate population.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual selected targets and supplied probe extensions drive the recorder's exported visitor; this adapter neither modifies Node nor guesses one known package's missing paths.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains selected-root bounds, linked packages, witness timing and the moved flag in separated prose and parameter entries under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path/file-URL vocabulary and linked physical selection are handled by the shared recorder; this adapter forwards them without slash-only parsing or blanket case conversion.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Witnesses are borrowed; delegated root/candidate arrays, manifest values and base deduplication are query-local, while emitted records belong to the callback. This adapter retains no watcher, handle or cross-query population.
+ * @evidence contracts/performance.md#efficient-algorithms Delegation includes importer-manifest ancestor search, lexical/physical selected-path lookup, root/name candidate scans and possible linked/scoped directory listings with native identity queries. Candidate expansion recursively reads/parses manifest target values with a normalized-base Set; path/extension/manifest bytes, root/entry counts and callback work drive cost, not merely the final selected-root prefix.
+ * @evidence contracts/performance.md#reuse-equivalent-work One delegated base Set prevents duplicate expansion across manifest targets, and supplied witnesses retain the earlier root observation for movement checks. No mutable filesystem lookup answer is reused across resolution windows.
+ */
+function visitImportMappedCandidates(parent, resolved, extensions, witnesses, visit) {
+    RECORDER.visitImportMappedCandidates(parent, resolved, extensions, witnesses, visit);
+}
+/** The recorder, loaded once as a module of its own. */
+const RECORDER = require(RESOLUTION_INPUT_RECORDER_PATH_1.RESOLUTION_INPUT_RECORDER_PATH);
+//# sourceMappingURL=visitImportMappedCandidates.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visitImportMappedCandidates.js","sourceRoot":"","sources":["../../../../src/plugin/internal/load/visitImportMappedCandidates.ts"],"names":[],"mappings":";;;AAAA,qFAAkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qCACE,MAA0B,EAC1B,QAA4B,EAC5B,UAA6B,EAC7B,SAA8D,EAC9D,KAA6C;IAE7C,QAAQ,CAAC,2BAA2B,CAClC,MAAM,EACN,QAAQ,EACR,UAAU,EACV,SAAS,EACT,KAAK,CACN,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,+DAA8B,CAQtD,CAAC"}

package/lib/plugin/internal/pluginDescriptorFailureReason.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Read the failure envelope the descriptor shim writes to its result file when
+ * it stops on an error it can name.
+ *
+ * This is the other half of classifying how the evaluation ended, which is why
+ * it lives beside {@link pluginDescriptorProcessFailure} rather than at the call
+ * site: the status says that it failed, and this says why.
+ *
+ * Only a well-formed envelope is honoured. A real descriptor never carries this
+ * key, and every other shape — an absent file, a shim that died before writing,
+ * a half-written result, a descriptor written before a later non-zero exit —
+ * leaves the process status to speak for itself.
+ *
+ * @evidence contracts/common.md#principled-implementation Parsing the named error-envelope field yields trimmed human context only for a string; unreadable or invalid output contributes no invented reason to the already-known process failure.
+ * @evidence contracts/common.md#clear-and-simple-design One file adapter supplies failure context while the process classifier independently owns launch/signal/status interpretation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The reserved envelope key is a shim protocol field, not a known-error-text special case or retry that masks descriptor failure.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains accepted envelope and rejected partial/missing shapes, with separate purpose and failure paragraphs under the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The file text/parsed object are invocation-local and become reclaimable when references are discarded; returned reason text transfers to the caller without retained helper history or an open descriptor.
+ * @evidence contracts/performance.md#efficient-algorithms A synchronous UTF-8 file read and JSON.parse process output bytes/parsed structure before trimming a string field. Text/tree/trim work and temporary storage are uncapped by this adapter; absence of an explicit loop does not make parsing constant-cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adapter reads the current evaluation result file; it defines no cross-evaluation identity or coordinator for sharing historical result text.
+ * @evidence contracts/portability.md#os-neutral-implementation The loader output path is passed to fs.readFileSync exactly as given, and any read or parse failure yields an empty reason, so no separator, case or platform assumption is made.
+ */
+export declare function pluginDescriptorFailureReason(outputPath: string): string;

package/lib/plugin/internal/pluginDescriptorFailureReason.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginDescriptorFailureReason = pluginDescriptorFailureReason;
+const node_fs_1 = __importDefault(require("node:fs"));
+/**
+ * Read the failure envelope the descriptor shim writes to its result file when
+ * it stops on an error it can name.
+ *
+ * This is the other half of classifying how the evaluation ended, which is why
+ * it lives beside {@link pluginDescriptorProcessFailure} rather than at the call
+ * site: the status says that it failed, and this says why.
+ *
+ * Only a well-formed envelope is honoured. A real descriptor never carries this
+ * key, and every other shape — an absent file, a shim that died before writing,
+ * a half-written result, a descriptor written before a later non-zero exit —
+ * leaves the process status to speak for itself.
+ *
+ * @evidence contracts/common.md#principled-implementation Parsing the named error-envelope field yields trimmed human context only for a string; unreadable or invalid output contributes no invented reason to the already-known process failure.
+ * @evidence contracts/common.md#clear-and-simple-design One file adapter supplies failure context while the process classifier independently owns launch/signal/status interpretation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The reserved envelope key is a shim protocol field, not a known-error-text special case or retry that masks descriptor failure.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains accepted envelope and rejected partial/missing shapes, with separate purpose and failure paragraphs under the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The file text/parsed object are invocation-local and become reclaimable when references are discarded; returned reason text transfers to the caller without retained helper history or an open descriptor.
+ * @evidence contracts/performance.md#efficient-algorithms A synchronous UTF-8 file read and JSON.parse process output bytes/parsed structure before trimming a string field. Text/tree/trim work and temporary storage are uncapped by this adapter; absence of an explicit loop does not make parsing constant-cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adapter reads the current evaluation result file; it defines no cross-evaluation identity or coordinator for sharing historical result text.
+ * @evidence contracts/portability.md#os-neutral-implementation The loader output path is passed to fs.readFileSync exactly as given, and any read or parse failure yields an empty reason, so no separator, case or platform assumption is made.
+ */
+function pluginDescriptorFailureReason(outputPath) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(outputPath, "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return "";
+        const message = parsed
+            .__ttscLoaderError;
+        return typeof message === "string" ? message.trim() : "";
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=pluginDescriptorFailureReason.js.map

package/lib/plugin/internal/pluginDescriptorFailureReason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginDescriptorFailureReason.js","sourceRoot":"","sources":["../../../src/plugin/internal/pluginDescriptorFailureReason.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AAEzB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,uCAA8C,UAAkB;IAC9D,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,iBAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;QACxE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,EAAE,CAAC;QAC7D,MAAM,OAAO,GAAI,MAA0C;aACxD,iBAAiB,CAAC;QACrB,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/lib/plugin/internal/pluginDescriptorProcessFailure.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Classify the ways the isolated TypeScript descriptor evaluator can stop.
+ *
+ * The ttsx loader routes any child stdout/stderr directly to the parent's
+ * stderr; a failed process need not have printed a diagnostic. This classifier
+ * formats the reported error, signal or nonzero status without proving a
+ * signal's origin or collecting the child's stream bytes.
+ *
+ * It sets no deadline or output ceiling. Request/error text and the returned
+ * Error still occupy memory; descriptor output-file parsing and process
+ * lifetime remain with the loader.
+ *
+ * @evidence contracts/common.md#principled-implementation Launch error, signal and nonzero status are classified in causal order from the child-process result; only a zero-status run without either earlier failure has no process error.
+ * @evidence contracts/common.md#clear-and-simple-design The classifier returns an error without owning spawning, streamed diagnostics or descriptor decoding, keeping those responsibilities with the loader.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No descriptor-name exception, fixed runtime deadline or output threshold replaces the actual process result.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains the already-streamed child output and remaining process-level information; separate paragraphs and a blank line before tags follow the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The classifier acquires no child or stream; a returned Error transfers to the caller and no helper-owned history is retained.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed precedence chain formats at most one Error. Request and reported-message text affect allocation/formatting; text length is uncapped and no child-output population is collected here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work One supplied result is classified without coordinating completed or in-flight evaluations.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Formats the process result's error, signal and exit status into a message; it reads no file and builds no path.
+ */
+export declare function pluginDescriptorProcessFailure(result: DescriptorProcessResult, request: string): Error | undefined;
+interface DescriptorProcessResult {
+    error?: Error;
+    signal: NodeJS.Signals | null;
+    status: number | null;
+}
+export {};

package/lib/plugin/internal/pluginDescriptorProcessFailure.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginDescriptorProcessFailure = pluginDescriptorProcessFailure;
+/**
+ * Classify the ways the isolated TypeScript descriptor evaluator can stop.
+ *
+ * The ttsx loader routes any child stdout/stderr directly to the parent's
+ * stderr; a failed process need not have printed a diagnostic. This classifier
+ * formats the reported error, signal or nonzero status without proving a
+ * signal's origin or collecting the child's stream bytes.
+ *
+ * It sets no deadline or output ceiling. Request/error text and the returned
+ * Error still occupy memory; descriptor output-file parsing and process
+ * lifetime remain with the loader.
+ *
+ * @evidence contracts/common.md#principled-implementation Launch error, signal and nonzero status are classified in causal order from the child-process result; only a zero-status run without either earlier failure has no process error.
+ * @evidence contracts/common.md#clear-and-simple-design The classifier returns an error without owning spawning, streamed diagnostics or descriptor decoding, keeping those responsibilities with the loader.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No descriptor-name exception, fixed runtime deadline or output threshold replaces the actual process result.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains the already-streamed child output and remaining process-level information; separate paragraphs and a blank line before tags follow the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The classifier acquires no child or stream; a returned Error transfers to the caller and no helper-owned history is retained.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed precedence chain formats at most one Error. Request and reported-message text affect allocation/formatting; text length is uncapped and no child-output population is collected here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work One supplied result is classified without coordinating completed or in-flight evaluations.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Formats the process result's error, signal and exit status into a message; it reads no file and builds no path.
+ */
+function pluginDescriptorProcessFailure(result, request) {
+    if (result.error) {
+        return new Error(`ttsc: failed to launch ttsx for plugin descriptor "${request}": ${result.error.message}`);
+    }
+    if (result.signal) {
+        return new Error(`ttsc: plugin descriptor "${request}" evaluation through ttsx was killed by signal ${result.signal}.`);
+    }
+    if (result.status !== 0) {
+        return new Error(`ttsc: plugin descriptor "${request}" evaluation through ttsx failed with exit code ${String(result.status)}`);
+    }
+    return undefined;
+}
+//# sourceMappingURL=pluginDescriptorProcessFailure.js.map

package/lib/plugin/internal/pluginDescriptorProcessFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginDescriptorProcessFailure.js","sourceRoot":"","sources":["../../../src/plugin/internal/pluginDescriptorProcessFailure.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wCACE,MAA+B,EAC/B,OAAe;IAEf,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,IAAI,KAAK,CACd,sDAAsD,OAAO,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAC1F,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,IAAI,KAAK,CACd,4BAA4B,OAAO,kDAAkD,MAAM,CAAC,MAAM,GAAG,CACtG,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,KAAK,CACd,4BAA4B,OAAO,mDAAmD,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAC9G,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/lib/plugin/internal/readCapabilityResolution.d.ts

@@ -0,0 +1,42 @@
+import type { ITtscCapabilityResolutionEntry } from "./ITtscCapabilityResolutionEntry";
+/**
+ * Read the recorded answer for a project, or `null` when there is none that is
+ * still true.
+ *
+ * Fail-closed by construction: every path that cannot prove the entry — a
+ * missing file, a parse failure, a format bump, a moved input, a plugin source
+ * or build environment the binary was not keyed on, a binary that is gone —
+ * returns `null`, and `null` means "walk the project properly". A cache that
+ * guessed here would answer "no plugin declares this capability" for a project
+ * that had just configured one, which is a wrong answer indistinguishable from
+ * the correct answer for the common case.
+ *
+ * Proving a plugin source consults the process's environment observation;
+ * `pluginSourceStateHolds` refreshes that observation on mismatch. A hit avoids
+ * descriptor evaluation/discovery but still checks source/build state. Source
+ * bytes can be skipped only when a recorded digest, matching signature and
+ * fresh separability evidence are available; unavailable evidence also causes a
+ * content read, even without a known metadata change. These sequential checks
+ * rely on producer declarations and native metadata semantics. Binary presence
+ * is checked with existsSync, not a binary content hash or an
+ * executable-lifetime claim.
+ *
+ * @evidence contracts/common.md#principled-implementation Shape/version, both host-input snapshots, every plugin source's build state and binary presence must all hold before returning the recorded answer; any unproved premise yields null for real project discovery.
+ * @evidence contracts/common.md#clear-and-simple-design One reader owns entry acceptance while shared format, source-build proof and input-observation helpers own their distinct identities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An old executable's existence alone cannot prove current plugin behavior; malformed, raced or incompatible inputs cause normal discovery rather than guessed negative capability answers.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains fail-closed absence and which work a hit avoids versus still proves; private helpers explain metadata and bidirectional comparison premises, following the documentation skill's paragraph/tag separation.
+ * @evidence contracts/portability.md#os-neutral-implementation Native fs and shared path/realpath observers preserve input spelling/physical projections and query binary presence. Metadata acceleration requires matching device-clock witnesses without inferring precision or case from an OS name; binary contents are not independently identified here.
+ * @evidence contracts/performance.md#efficient-algorithms Full entry read/JSON/shape/map checks, host file hashes and realpaths precede source population/signature walks and binary presence queries. Signature reuse avoids source-content reads only under recorded digest/separation premises; other cases hash content, and mismatched state can refresh build environment. Delegated authority/root/executable observation, probe operations and path/key/numeric/record/file bytes contribute native work and transient storage.
+ * @evidence contracts/performance.md#reuse-equivalent-work One project/version entry can answer every capability while its recorded hash/physical/source-build projections pass the sequential checks. Metadata acceleration assumes native write/stamp semantics and producer completeness; unavailable observations refuse reuse, without claiming atomic or complete-world identity.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Parsed entry data transfers to the caller. Usage refresh and transient clock-probe removal are attempted by their owners and can skip/fail; default pruning has its own interval/protection/failure policy, while explicit roots remain caller-owned. This reader imposes no entry/input/output byte ceiling.
+ */
+export declare function readCapabilityResolution(options: {
+    /** Invocation directory included in the shared cache-entry identity. */
+    cwd: string;
+    /** Selected project config identity, as supplied to capability discovery. */
+    tsconfig: string;
+    /** Ttsc product version, paired with the cache format revision. */
+    version: string;
+    /** Environment selecting the cache root; ambient process env when omitted. */
+    env?: NodeJS.ProcessEnv;
+}): ITtscCapabilityResolutionEntry | null;