ttsc 0.30.4 → 0.31.1

package/lib/compiler/internal/findNearestGoMod.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.findNearestGoMod = findNearestGoMod;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Walk up the directory tree from `from` looking for a `go.mod` file. Stops
+ * after `maxDepth` hops so callers can bound the search to a known
+ * neighbourhood of the plugin source directory.
+ *
+ * Returns the absolute path to the first `go.mod` found, or `null` when no
+ * `go.mod` exists within the depth limit or filesystem root is reached first.
+ * Only stat-observed regular files qualify; a directory named go.mod is not
+ * module metadata. The caller supplies a nonnegative integer parent limit (the
+ * maintained plugin caller uses 3). Other native stat errors propagate; a
+ * returned path is an observation, not a held identity or parsed module.
+ *
+ * @evidence contracts/common.md#principled-implementation Searching the starting directory then at most maxDepth parents implements the plugin module's nearest-owner rule; regular-file status distinguishes metadata from an identically named directory.
+ * @evidence contracts/common.md#clear-and-simple-design One bounded ancestry walk owns module discovery, while the caller owns plugin-source validation and interpretation of the resulting module root.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The search follows module ancestry and an explicit supported depth, without guessing a module from a particular plugin name or fixture layout.
+ * @evidence contracts/common.md#meaningful-documentation The native comment defines inclusive starting-directory search, parent limit, absence and file-kind requirements in separated prose following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path resolution and parent traversal handle platform roots; stat follows filesystem symlinks to actual regular module files without an OS-derived case assumption.
+ * @evidence contracts/performance.md#efficient-algorithms For the caller-supplied nonnegative integer limit, at most maxDepth plus one metadata probes occur, fewer at a filesystem root. Path resolution/join/parent text and native stat lookup costs accompany those probes; one current path avoids retaining all ancestors and no recursive source scan is performed.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Nearby go.mod files can appear or disappear; this query has no watcher or dependency identity authorizing persistent cross-request reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous walk owns no retained descriptors or historical state and transfers its nullable path result to the caller.
+ */
+function findNearestGoMod(from, maxDepth) {
+    let current = node_path_1.default.resolve(from);
+    let depth = 0;
+    while (true) {
+        const candidate = node_path_1.default.join(current, "go.mod");
+        if (node_fs_1.default.statSync(candidate, { throwIfNoEntry: false })?.isFile()) {
+            return candidate;
+        }
+        if (depth >= maxDepth)
+            return null;
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+        depth += 1;
+    }
+}
+//# sourceMappingURL=findNearestGoMod.js.map

package/lib/compiler/internal/findNearestGoMod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findNearestGoMod.js","sourceRoot":"","sources":["../../../src/compiler/internal/findNearestGoMod.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,0BACE,IAAY,EACZ,QAAgB;IAEhB,IAAI,OAAO,GAAG,mBAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,SAAS,GAAG,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC/C,IAAI,iBAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;YAChE,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,KAAK,IAAI,QAAQ;YAAE,OAAO,IAAI,CAAC;QACnC,MAAM,MAAM,GAAG,mBAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC;QACpC,OAAO,GAAG,MAAM,CAAC;QACjB,KAAK,IAAI,CAAC,CAAC;IACb,CAAC;AACH,CAAC"}

package/lib/compiler/internal/isOutsideRelativePath.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Return `true` when a relative path escapes its base directory — i.e. starts
+ * with `..` or is an absolute path. Used by callers that need to guard against
+ * path traversal before building output keys or spawning subprocesses.
+ *
+ * The input must be a native relative-path result such as path.relative, not an
+ * unnormalized user path or URL; embedded parent segments are not parsed.
+ *
+ * @evidence contracts/common.md#principled-implementation A normalized native relative result escapes through a leading parent component or an absolute different-root result; component boundaries prevent treating a name like ..notes as traversal.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate classifies path.relative results; normalization and filesystem identity remain the producing caller's responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification follows native path semantics without special-casing project names or converting a URL into a filesystem identity.
+ * @evidence contracts/common.md#meaningful-documentation The added input premise distinguishes this predicate from a general sanitizer, with separated paragraphs following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.sep and path.isAbsolute interpret native separators and different-drive results; protocol slash syntax and physical identity are deliberately outside this lexical predicate.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources isOutsideRelativePath acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidence contracts/performance.md#efficient-algorithms Exact-parent and fixed leading-component comparisons avoid splitting or normalizing the whole path. Native absolute classification is delegated to path.isAbsolute; the predicate makes no filesystem calls and does not claim constant work merely from a fixed number of expressions.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This call-local lexical predicate does not coordinate or retain completed work across consumers; its producer owns path normalization and any shared identity state.
+ */
+export declare function isOutsideRelativePath(relative: string): boolean;

package/lib/compiler/internal/isOutsideRelativePath.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOutsideRelativePath = isOutsideRelativePath;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Return `true` when a relative path escapes its base directory — i.e. starts
+ * with `..` or is an absolute path. Used by callers that need to guard against
+ * path traversal before building output keys or spawning subprocesses.
+ *
+ * The input must be a native relative-path result such as path.relative, not an
+ * unnormalized user path or URL; embedded parent segments are not parsed.
+ *
+ * @evidence contracts/common.md#principled-implementation A normalized native relative result escapes through a leading parent component or an absolute different-root result; component boundaries prevent treating a name like ..notes as traversal.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate classifies path.relative results; normalization and filesystem identity remain the producing caller's responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification follows native path semantics without special-casing project names or converting a URL into a filesystem identity.
+ * @evidence contracts/common.md#meaningful-documentation The added input premise distinguishes this predicate from a general sanitizer, with separated paragraphs following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.sep and path.isAbsolute interpret native separators and different-drive results; protocol slash syntax and physical identity are deliberately outside this lexical predicate.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources isOutsideRelativePath acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidence contracts/performance.md#efficient-algorithms Exact-parent and fixed leading-component comparisons avoid splitting or normalizing the whole path. Native absolute classification is delegated to path.isAbsolute; the predicate makes no filesystem calls and does not claim constant work merely from a fixed number of expressions.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This call-local lexical predicate does not coordinate or retain completed work across consumers; its producer owns path normalization and any shared identity state.
+ */
+function isOutsideRelativePath(relative) {
+    return (relative === ".." ||
+        relative.startsWith(`..${node_path_1.default.sep}`) ||
+        node_path_1.default.isAbsolute(relative));
+}
+//# sourceMappingURL=isOutsideRelativePath.js.map

package/lib/compiler/internal/isOutsideRelativePath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isOutsideRelativePath.js","sourceRoot":"","sources":["../../../src/compiler/internal/isOutsideRelativePath.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B;;;;;;;;;;;;;;;;GAgBG;AACH,+BAAsC,QAAgB;IACpD,OAAO,CACL,QAAQ,KAAK,IAAI;QACjB,QAAQ,CAAC,UAAU,CAAC,KAAK,mBAAI,CAAC,GAAG,EAAE,CAAC;QACpC,mBAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAC1B,CAAC;AACJ,CAAC"}

package/lib/compiler/internal/outputText.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Convert captured output to UTF-8 text; absent output becomes an empty string.
+ *
+ * @param value Already decoded text, captured bytes or absent output.
+ * @returns Existing text unchanged, UTF-8 decoded bytes or empty text.
+ * @evidence contracts/common.md#principled-implementation Nullish outputs denote no captured bytes; existing strings retain their decoded meaning and Buffers use Node's UTF-8 decoder.
+ * @evidence contracts/common.md#clear-and-simple-design One narrowing branch distinguishes absence from an already decoded string and raw bytes; no process policy belongs to this accessor.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Empty text follows the nullish capture representation and never replaces a nonempty Buffer or a filesystem error.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence explains absence and the decoding choice without repeating the union type, following the documentation skill.
+ * @evidence contracts/performance.md#efficient-algorithms Nullish/string branches do not decode; a Buffer branch delegates one UTF-8 decode with work and returned text storage proportional to supplied bytes.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Transfers text to its caller without an independent descriptor, task or historical retained output table.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This decoding accessor owns no capture lifecycle or cache; mutable Buffer inputs and caller-selected output generations supply no coordinated equivalence authority here.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation outputText computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+export declare function outputText(value: string | Buffer | null | undefined): string;

package/lib/compiler/internal/outputText.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.outputText = outputText;
+/**
+ * Convert captured output to UTF-8 text; absent output becomes an empty string.
+ *
+ * @param value Already decoded text, captured bytes or absent output.
+ * @returns Existing text unchanged, UTF-8 decoded bytes or empty text.
+ * @evidence contracts/common.md#principled-implementation Nullish outputs denote no captured bytes; existing strings retain their decoded meaning and Buffers use Node's UTF-8 decoder.
+ * @evidence contracts/common.md#clear-and-simple-design One narrowing branch distinguishes absence from an already decoded string and raw bytes; no process policy belongs to this accessor.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Empty text follows the nullish capture representation and never replaces a nonempty Buffer or a filesystem error.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence explains absence and the decoding choice without repeating the union type, following the documentation skill.
+ * @evidence contracts/performance.md#efficient-algorithms Nullish/string branches do not decode; a Buffer branch delegates one UTF-8 decode with work and returned text storage proportional to supplied bytes.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Transfers text to its caller without an independent descriptor, task or historical retained output table.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This decoding accessor owns no capture lifecycle or cache; mutable Buffer inputs and caller-selected output generations supply no coordinated equivalence authority here.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation outputText computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+function outputText(value) {
+    if (value == null) {
+        return "";
+    }
+    return typeof value === "string" ? value : value.toString("utf8");
+}
+//# sourceMappingURL=outputText.js.map

package/lib/compiler/internal/outputText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputText.js","sourceRoot":"","sources":["../../../src/compiler/internal/outputText.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;GAcG;AACH,oBAA2B,KAAyC;IAClE,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACpE,CAAC"}

package/lib/compiler/internal/packageRootDir.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Walk up the directory tree from `__dirname` until a directory that contains
+ * both `package.json` and `go.mod` exists. Within the shipped package this
+ * selects the build root passed to `buildNativeCompiler` for `cmd/ttsc`;
+ * existence checks do not parse those entries or validate the command tree.
+ *
+ * Uses `fs.realpathSync.native` when available to produce the physical anchor
+ * passed to the Go build. It does not model every Go toolchain path
+ * convention.
+ *
+ * Throws when the shipped package metadata and Go module cannot be found,
+ * indicating an incomplete installation rather than a missing Go workspace.
+ * Native realpath errors propagate if the selected anchor cannot be resolved.
+ *
+ * @evidence contracts/common.md#principled-implementation Upward ancestry stops at the package's paired npm and Go metadata, matching the root required to locate cmd/ttsc; realpath returns the physical build anchor.
+ * @evidence contracts/common.md#clear-and-simple-design Root discovery owns one metadata predicate and one ancestry walk rather than relying on the compiler module's source-versus-lib depth.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The root is discovered from shipped metadata rather than a consumer fixture path or an assumed workspace layout.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the build consumer, physical-path choice and actual incomplete-installation failure, in paragraphs following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.resolve, join and dirname use native path syntax, and realpath obtains physical identity without deriving case policy from an OS name.
+ * @evidence contracts/performance.md#efficient-algorithms D visited ancestors incur at most two existence checks each plus native path joins/dirname work proportional to traversed text lengths. The selected root incurs one realpath operation with delegated filesystem costs; parent equality terminates the walk without directory enumeration. Invocation-local path storage depends on path length rather than a fixed string count bounding bytes.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This discovery does not own a stable installed-metadata identity or invalidation source; retaining a result across filesystem changes would turn a fresh root query into stale authority.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous metadata checks retain no handles, history or tasks; the returned physical string transfers to the caller.
+ */
+export declare function packageRootDir(): string;

package/lib/compiler/internal/packageRootDir.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageRootDir = packageRootDir;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Walk up the directory tree from `__dirname` until a directory that contains
+ * both `package.json` and `go.mod` exists. Within the shipped package this
+ * selects the build root passed to `buildNativeCompiler` for `cmd/ttsc`;
+ * existence checks do not parse those entries or validate the command tree.
+ *
+ * Uses `fs.realpathSync.native` when available to produce the physical anchor
+ * passed to the Go build. It does not model every Go toolchain path
+ * convention.
+ *
+ * Throws when the shipped package metadata and Go module cannot be found,
+ * indicating an incomplete installation rather than a missing Go workspace.
+ * Native realpath errors propagate if the selected anchor cannot be resolved.
+ *
+ * @evidence contracts/common.md#principled-implementation Upward ancestry stops at the package's paired npm and Go metadata, matching the root required to locate cmd/ttsc; realpath returns the physical build anchor.
+ * @evidence contracts/common.md#clear-and-simple-design Root discovery owns one metadata predicate and one ancestry walk rather than relying on the compiler module's source-versus-lib depth.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The root is discovered from shipped metadata rather than a consumer fixture path or an assumed workspace layout.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the build consumer, physical-path choice and actual incomplete-installation failure, in paragraphs following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.resolve, join and dirname use native path syntax, and realpath obtains physical identity without deriving case policy from an OS name.
+ * @evidence contracts/performance.md#efficient-algorithms D visited ancestors incur at most two existence checks each plus native path joins/dirname work proportional to traversed text lengths. The selected root incurs one realpath operation with delegated filesystem costs; parent equality terminates the walk without directory enumeration. Invocation-local path storage depends on path length rather than a fixed string count bounding bytes.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This discovery does not own a stable installed-metadata identity or invalidation source; retaining a result across filesystem changes would turn a fresh root query into stale authority.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous metadata checks retain no handles, history or tasks; the returned physical string transfers to the caller.
+ */
+function packageRootDir() {
+    let current = node_path_1.default.resolve(__dirname);
+    while (true) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(current, "package.json")) &&
+            node_fs_1.default.existsSync(node_path_1.default.join(current, "go.mod"))) {
+            return node_fs_1.default.realpathSync.native?.(current) ?? node_fs_1.default.realpathSync(current);
+        }
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current) {
+            throw new Error("ttsc: package root not found for native compiler build");
+        }
+        current = parent;
+    }
+}
+//# sourceMappingURL=packageRootDir.js.map

package/lib/compiler/internal/packageRootDir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageRootDir.js","sourceRoot":"","sources":["../../../src/compiler/internal/packageRootDir.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IACE,IAAI,OAAO,GAAG,mBAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACtC,OAAO,IAAI,EAAE,CAAC;QACZ,IACE,iBAAE,CAAC,UAAU,CAAC,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;YACjD,iBAAE,CAAC,UAAU,CAAC,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,EAC3C,CAAC;YACD,OAAO,iBAAE,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,iBAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,MAAM,GAAG,mBAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC"}

package/lib/compiler/internal/parseNativeTransformOutput.d.ts

@@ -0,0 +1,88 @@
+import type { ITtscCompilerDiagnostic } from "../../structures/ITtscCompilerDiagnostic";
+import type { ITtscCompilerTransformation } from "../../structures/ITtscCompilerTransformation";
+/**
+ * Parse the JSON envelope written by the native transform host to stdout.
+ *
+ * The `typescript` field must be a `Record<string, string>`. Any other shape is
+ * treated as a protocol error with a specific source-shape message. JSON parse
+ * errors instead report the captured stderr, or stdout when stderr is empty.
+ *
+ * The optional `dependencies`, `dependenciesComplete`, `graph`, `sourceMaps`,
+ * and `volatile` fields (see `ITtscCompilerTransformation`) are forwarded when
+ * well-formed; entries that do not match the expected shape are dropped rather
+ * than failing the transform. The fields are advisory invalidation metadata,
+ * not output.
+ *
+ * Source-keyed records retain literal keys, including names inherited by
+ * ordinary JavaScript objects, as enumerable own data properties.
+ *
+ * Dropping a malformed `dependenciesComplete` member is the safe direction on
+ * purpose: an unlisted file keeps the sound host-owned bound, so a garbled
+ * declaration costs over-invalidation, never a stale output.
+ *
+ * Observation limits have a stricter protocol: completeness is only explicit
+ * false, and per-input reasons require absolute native paths and the supported
+ * unavailable reason. Invalid limit metadata fails instead of becoming an
+ * exemption; omission asserts no completeness.
+ *
+ * @evidence contracts/common.md#principled-implementation Required source output is decoded as an object of strings; advisory members are retained only by their declared shape with literal source keys stored as own data properties, while malformed observation exemptions fail rather than authorize reuse.
+ * @evidence contracts/common.md#clear-and-simple-design This decoder owns the wire shape independently of process execution and proof revalidation; private helpers validate the distinct optional sections.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing or malformed source output is never synthesized; omission of optional metadata cannot create observation authority.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish source-shape errors from JSON error context and explain advisory filtering, literal source-key retention and stricter observation limits; returned fields distinguish source text from producer claims.
+ * @evidence contracts/portability.md#os-neutral-implementation Host proof paths use native path.isAbsolute and path.resolve; graph keys retain compiler spellings. Decoding opens no file or process and applies no platform case folding.
+ * @evidence contracts/performance.md#efficient-algorithms JSON decoding and bounded section scans take time and request space linear in envelope bytes, keys and list members; Object.keys emptiness checks add linear scans without changing that bound, and predicate consistency checks inspect fixed fields without rereading directory-list members.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each captured producer response is independently decoded; the function retains no result or validity proof for later requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Decoded records are request-owned and transfer to the caller; no response history, watcher or native handle survives in the decoder.
+ */
+export declare function parseNativeTransformOutput(
+/** Captured standard output containing the native JSON envelope. */
+stdout: string, 
+/** Captured standard error used when no JSON response can be decoded. */
+stderr: string): {
+    /** Advisory per-file dependency lists. */
+    dependencies?: Record<string, string[]>;
+    /** Files the producer declares dependency-complete. */
+    dependenciesComplete?: string[];
+    /** Diagnostic entries reported by the native response. */
+    diagnostics: ITtscCompilerDiagnostic[];
+    /** Advisory compiler graph and its recorded witnesses. */
+    graph?: ITtscCompilerTransformation.IReferenceGraph;
+    /** Raw-content or unavailable-state host witnesses. */
+    hostInputHashes?: Record<string, string | null>;
+    /** Native physical-target or unavailable-state host witnesses. */
+    hostInputRealpaths?: Record<string, string | null>;
+    /** Explicit reports that host observation was unavailable. */
+    hostInputProofFailures?: Record<string, "observation-unavailable">;
+    /** Host input paths whose proof must be checked by the caller. */
+    hostInputs?: string[];
+    /** Explicit false withdraws complete observation authority. */
+    observationsComplete?: false;
+    /** Validated maps for returned TypeScript source texts. */
+    sourceMaps?: Record<string, ITtscCompilerTransformation.ISourceMap>;
+    /** Required transformed TypeScript source texts. */
+    typescript: Record<string, string>;
+    /** Producer-selected sources unsuitable for stable reuse. */
+    volatile?: string[];
+};
+/**
+ * Normalize the optional `graph` envelope section with the same tolerance as
+ * `dependencies`: non-object sections are dropped, empty source keys and edge
+ * entries that are not arrays are dropped, and non-string list members are
+ * filtered. Empty arrays remain as graph nodes because leaf membership binds
+ * compiler input proof. A section carrying nothing usable collapses to
+ * `undefined`.
+ *
+ * Optional resolver-input members are left off when empty. A consumer that
+ * narrows on their declared optional types therefore sees the same shape from
+ * the decoded envelope and the wire.
+ *
+ * @evidence contracts/common.md#principled-implementation Normalized adjacency preserves leaf membership while optional resolver, content, physical and predicate reports retain their distinct proof meanings. Malformed predicate reports carry explicit failures; decoding supplies observations rather than current-state or completeness authority.
+ * @evidence contracts/common.md#clear-and-simple-design One graph decoder composes the existing list, map and predicate decoders and omits absent optional channels. Native capture and later generation validation remain separate owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No source read, new Program or guessed witness repairs unavailable data. Empty unusable sections remain absent, conflicting predicate observations remain failures, and the compiler case policy comes only from an actual boolean report.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state tolerant graph normalization, leaf retention and optional channel shapes, separating wire decoding from behavioral acceptance.
+ * @evidence contracts/performance.md#efficient-algorithms Decoding enumerates the supplied graph maps and lists, copies accepted members and normalizes predicate records. Work includes their field/path/value bytes and delegated native-path text checks, with temporary entry arrays and output maps proportional to accepted and inspected populations; no payload ceiling is imposed here.
+ * @evidence contracts/performance.md#reuse-equivalent-work Each call decodes its supplied wire record without retaining a previous answer. Recorded witnesses transfer unchanged in meaning to the generation consumer, which separately proves whether the actual inputs still match.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Temporary enumeration arrays and parsed maps are call-owned; the returned DTO transfers to its caller without a historical cache, descriptor or task. The input wire value remains caller-owned and no byte or member cap is added.
+ * @evidence contracts/portability.md#os-neutral-implementation Logical graph keys retain compiler protocol spelling; delegated physical/predicate decoding uses native path validation, and reported case policy is preserved rather than inferred from the OS. Decoding performs no filesystem observation or fixture-specific path substitution.
+ */
+export declare function parseReferenceGraph(value: unknown): ITtscCompilerTransformation.IReferenceGraph | undefined;