ttsc 0.30.4 → 0.31.0

package/lib/compiler/internal/resolveBinary.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveBinary = resolveBinary;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const SidecarEnvironment_1 = require("./sharedHost/SidecarEnvironment");
 /**
  * Resolve the ttsc helper binary path, or null when unavailable.
  *
@@ -13,12 +14,29 @@ const node_path_1 = __importDefault(require("node:path"));
  *
  * 1. `TTSC_BINARY` env var — must be an absolute path when set.
  * 2. The per-platform npm package `@ttsc/<platform>-<arch>/bin/ttsc[.exe]`.
- * 3. A `ttsc-native[.exe]` sibling of this package's root (dev/CI layout).
+ * 3. `native/ttsc-native[.exe]` inside this package (local Go build layout).
+ *
+ * A relative TTSC_BINARY is ignored; an absolute override is returned without a
+ * filesystem probe so the spawn operation owns its executable error.
+ * Platform-package lookup failures fall through to the local candidate. Local
+ * source/lib realpath errors can propagate instead of returning null, and a
+ * selected existing path is not an executable or ABI compatibility check.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit absolute authority precedes Node's platform-package resolution and then the package-local Go build output, matching the helper binary ownership exported through ttsc/binary.
+ * @evidence contracts/common.md#clear-and-simple-design A single resolver owns precedence for compiler and external helper consumers; the local-path helper separates source/lib layout from installed platform-package lookup.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Platform package names and executable suffixes follow the published package contract; the resolver uses supported require.resolve without replacing foreign resolution methods.
+ * @evidence contracts/common.md#meaningful-documentation Ordered resolution and override behavior are documented separately; the corrected development path matches go:build, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform and architecture select the native package and executable suffix; native path APIs establish the development path, and override lookup follows Windows environment-name identity even in a caller's ordinary object.
+ * @evidence contracts/performance.md#efficient-algorithms Precedence has a fixed branch count, but Windows environment-name lookup scans key bytes, native path normalization processes text, Node package lookup has delegated search costs, and local fallback realpaths the source/lib root before checking candidate existence. No compiler executes merely to select this path.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Environment overrides and development binaries may change between calls; the resolver owns no invalidation protocol beyond Node's own module resolver and introduces no stale path cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Resolution owns no persistent map, descriptor or task and returns only the selected path spelling.
  */
 function resolveBinary(opts = {}) {
     const env = opts.env ?? process.env;
-    if (env.TTSC_BINARY && node_path_1.default.isAbsolute(env.TTSC_BINARY)) {
-        return env.TTSC_BINARY;
+    const explicit = SidecarEnvironment_1.SidecarEnvironment.read(env, "TTSC_BINARY");
+    if (explicit && node_path_1.default.isAbsolute(explicit)) {
+        return explicit;
     }
     try {
         return require.resolve(`@ttsc/${process.platform}-${process.arch}/bin/${process.platform === "win32" ? "ttsc.exe" : "ttsc"}`);
@@ -31,18 +49,15 @@ function resolveBinary(opts = {}) {
         return local;
     return null;
 }
-/**
- * Return the path to the dev-layout `ttsc-native[.exe]` binary adjacent to the
- * package root, or null when the file does not exist.
- */
+/** Return the package-local Go build output, or null when it does not exist. */
 function defaultLocalBinaryPath() {
     const root = packageRootDir();
     const candidate = node_path_1.default.resolve(root, "..", "native", process.platform === "win32" ? "ttsc-native.exe" : "ttsc-native");
     return node_fs_1.default.existsSync(candidate) ? candidate : null;
 }
 /**
- * Return the real, absolute path of the `packages/ttsc` package root by walking
- * two levels up from `__dirname` (which lives in `src/compiler/internal`).
+ * Return the physical src or lib directory above this compiler module. The
+ * local build output is in the sibling native directory of that tree.
  */
 function packageRootDir() {
     const moduleDir = node_path_1.default.resolve(__dirname, "..", "..");

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

@@ -1 +1 @@
-{"version":3,"file":"resolveBinary.js","sourceRoot":"","sources":["../../../src/compiler/internal/resolveBinary.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B;;;;;;;;GAQG;AACH,uBACE,IAAI,GAAgC,EAAE;IAEtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,IAAI,GAAG,CAAC,WAAW,IAAI,mBAAI,CAAC,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QACxD,OAAO,GAAG,CAAC,WAAW,CAAC;IACzB,CAAC;IAED,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CACpB,SAAS,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,QAAQ,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CACtG,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IAED,MAAM,KAAK,GAAG,sBAAsB,EAAE,CAAC;IACvC,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IAExB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAS,sBAAsB;IAC7B,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,mBAAI,CAAC,OAAO,CAC5B,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,aAAa,CACjE,CAAC;IACF,OAAO,iBAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc;IACrB,MAAM,SAAS,GAAG,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACtD,OAAO,iBAAE,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,iBAAE,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;AAC3E,CAAC"}
+{"version":3,"file":"resolveBinary.js","sourceRoot":"","sources":["../../../src/compiler/internal/resolveBinary.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B,wEAAqE;AAErE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,uBACE,IAAI,GAAgC,EAAE;IAEtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,QAAQ,GAAG,uCAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IAC7D,IAAI,QAAQ,IAAI,mBAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CACpB,SAAS,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,QAAQ,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CACtG,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IAED,MAAM,KAAK,GAAG,sBAAsB,EAAE,CAAC;IACvC,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IAExB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAChF,SAAS,sBAAsB;IAC7B,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,mBAAI,CAAC,OAAO,CAC5B,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,aAAa,CACjE,CAAC;IACF,OAAO,iBAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc;IACrB,MAAM,SAAS,GAAG,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACtD,OAAO,iBAAE,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,iBAAE,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;AAC3E,CAAC"}

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

@@ -3,15 +3,30 @@
  *
  * Resolution order:
  *
- * 1. `opts.binary` or `TTSC_TSGO_BINARY` env var — must be an existing absolute
- *    path; returns `{ binary, packageJson: "", packageRoot, version: "custom"
- *    }`.
+ * 1. Select `opts.binary`, or consult `TTSC_TSGO_BINARY` only when it is absent. A
+ *    nonempty override must be an existing absolute path; returns `{ binary,
+ *    packageJson: "", packageRoot, version: "custom" }`.
  * 2. `typescript` resolved from the project `cwd`.
  * 3. `typescript` resolved from `opts.resolveFrom` (for test harnesses and
  *    embedders that anchor to a different directory).
  *
- * Throws a descriptive error when the package or platform binary is missing so
- * callers never have to reason about undefined binary paths.
+ * Throws a descriptive error when the package or platform path is missing.
+ * Manifest read/parse failures can propagate directly. Existence does not
+ * certify a regular executable, native ABI or compiler version compatibility;
+ * this operation selects paths and metadata without executing them. Platform
+ * package resolution is anchored at the chosen TypeScript manifest and can
+ * follow Node's ancestor search, rather than proving both packages occupy one
+ * physical installation or declare matching versions.
+ *
+ * @evidence contracts/common.md#principled-implementation Selected nonempty binary authority precedes project-relative TypeScript lookup; the chosen manifest anchors Node resolution of the platform package. Returned metadata describes the selected TypeScript manifest, without certifying native executable compatibility or matching platform-package versions.
+ * @evidence contracts/common.md#clear-and-simple-design Resolution returns one existing selected path with provenance metadata; package lookup and JSON reading are private helpers rather than independent policy copies in launcher consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Package names and lib/tsc suffixes follow the native TypeScript distribution contract. Missing dependencies remain descriptive errors rather than invented compiler paths or fixture-specific substitutes.
+ * @evidence contracts/common.md#meaningful-documentation Ordered precedence, custom metadata and failures are documented separately, and the fallback anchor member explains its filename semantics following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path APIs validate absolute overrides and select the Windows executable suffix; createRequire anchors resolution to actual package files without shell quoting or OS-derived case policy.
+ * @evidence contracts/performance.md#efficient-algorithms A precedence sequence makes at most two TypeScript resolution attempts, one platform resolution and one manifest parse of M bytes. Node ancestor/package lookup, native existence checks and path text work have delegated costs; Windows environment override selection scans environment keys through SidecarEnvironment. Returned metadata does not retain the full parsed manifest.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Overrides and consumer installations are mutable filesystem authority; this resolver owns no dependency invalidation source that could justify retaining a custom result across calls.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous package reads retain no handles or tasks; returned path and version strings transfer to the caller without a historical metadata table.
  */
 export declare function resolveTsgo(opts?: {
     /** Explicit path to a native `tsc` binary; bypasses package resolution. */
@@ -20,8 +35,8 @@ export declare function resolveTsgo(opts?: {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
     /**
-     * Fallback resolution anchor used when the package is not found at `cwd`.
-     * Useful in test harnesses that install the package into a different tree.
+     * Absolute filename used to anchor fallback resolution when the package is
+     * absent at cwd. Pass a package.json or module filename, not a directory.
      */
     resolveFrom?: string;
 }): {

package/lib/compiler/internal/resolveTsgo.js

@@ -7,24 +7,40 @@ exports.resolveTsgo = resolveTsgo;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_module_1 = require("node:module");
 const node_path_1 = __importDefault(require("node:path"));
+const SidecarEnvironment_1 = require("./sharedHost/SidecarEnvironment");
 /**
  * Resolve the consumer project's native TypeScript (`tsc`) binary and metadata.
  *
  * Resolution order:
  *
- * 1. `opts.binary` or `TTSC_TSGO_BINARY` env var — must be an existing absolute
- *    path; returns `{ binary, packageJson: "", packageRoot, version: "custom"
- *    }`.
+ * 1. Select `opts.binary`, or consult `TTSC_TSGO_BINARY` only when it is absent. A
+ *    nonempty override must be an existing absolute path; returns `{ binary,
+ *    packageJson: "", packageRoot, version: "custom" }`.
  * 2. `typescript` resolved from the project `cwd`.
  * 3. `typescript` resolved from `opts.resolveFrom` (for test harnesses and
  *    embedders that anchor to a different directory).
  *
- * Throws a descriptive error when the package or platform binary is missing so
- * callers never have to reason about undefined binary paths.
+ * Throws a descriptive error when the package or platform path is missing.
+ * Manifest read/parse failures can propagate directly. Existence does not
+ * certify a regular executable, native ABI or compiler version compatibility;
+ * this operation selects paths and metadata without executing them. Platform
+ * package resolution is anchored at the chosen TypeScript manifest and can
+ * follow Node's ancestor search, rather than proving both packages occupy one
+ * physical installation or declare matching versions.
+ *
+ * @evidence contracts/common.md#principled-implementation Selected nonempty binary authority precedes project-relative TypeScript lookup; the chosen manifest anchors Node resolution of the platform package. Returned metadata describes the selected TypeScript manifest, without certifying native executable compatibility or matching platform-package versions.
+ * @evidence contracts/common.md#clear-and-simple-design Resolution returns one existing selected path with provenance metadata; package lookup and JSON reading are private helpers rather than independent policy copies in launcher consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Package names and lib/tsc suffixes follow the native TypeScript distribution contract. Missing dependencies remain descriptive errors rather than invented compiler paths or fixture-specific substitutes.
+ * @evidence contracts/common.md#meaningful-documentation Ordered precedence, custom metadata and failures are documented separately, and the fallback anchor member explains its filename semantics following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path APIs validate absolute overrides and select the Windows executable suffix; createRequire anchors resolution to actual package files without shell quoting or OS-derived case policy.
+ * @evidence contracts/performance.md#efficient-algorithms A precedence sequence makes at most two TypeScript resolution attempts, one platform resolution and one manifest parse of M bytes. Node ancestor/package lookup, native existence checks and path text work have delegated costs; Windows environment override selection scans environment keys through SidecarEnvironment. Returned metadata does not retain the full parsed manifest.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Overrides and consumer installations are mutable filesystem authority; this resolver owns no dependency invalidation source that could justify retaining a custom result across calls.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous package reads retain no handles or tasks; returned path and version strings transfer to the caller without a historical metadata table.
  */
 function resolveTsgo(opts = {}) {
     const env = opts.env ?? process.env;
-    const explicit = opts.binary ?? env.TTSC_TSGO_BINARY;
+    const explicit = opts.binary ?? SidecarEnvironment_1.SidecarEnvironment.read(env, "TTSC_TSGO_BINARY");
     if (explicit) {
         if (!node_path_1.default.isAbsolute(explicit) || !node_fs_1.default.existsSync(explicit)) {
             throw new Error(`ttsc: explicit tsgo binary must be an existing absolute path: ${explicit}`);
@@ -82,9 +98,9 @@ function resolveTsgo(opts = {}) {
     };
 }
 /**
- * Attempt to resolve the `package.json` of `typescript` starting from `from` (a
- * package.json path or directory). Returns `undefined` when the package is not
- * resolvable from that location.
+ * Resolve TypeScript relative to an absolute filename accepted by
+ * createRequire. Returns undefined when the anchor or package cannot be
+ * resolved.
  */
 function resolveTypeScriptPackageJson(from) {
     try {

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

@@ -1 +1 @@
-{"version":3,"file":"resolveTsgo.js","sourceRoot":"","sources":["../../../src/compiler/internal/resolveTsgo.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,6CAA4C;AAC5C,0DAA6B;AAE7B;;;;;;;;;;;;;;GAcG;AACH,qBACE,IAAI,GAWA,EAAE;IAEN,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,gBAAgB,CAAC;IACrD,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC,mBAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,iBAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CACb,iEAAiE,QAAQ,EAAE,CAC5E,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM,EAAE,QAAQ;YAChB,WAAW,EAAE,EAAE;YACf,WAAW,EAAE,mBAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;YACnC,OAAO,EAAE,QAAQ;SAClB,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,mBAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACpD,0CAA0C;IAC1C,uDAAuD;IACvD,IAAI,WAAmB,CAAC;IACxB,WAAW;QACT,4BAA4B,CAAC,mBAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YAC5D,CAAC,IAAI,CAAC,WAAW;gBACf,CAAC,CAAC,4BAA4B,CAAC,IAAI,CAAC,WAAW,CAAC;gBAChD,CAAC,CAAC,SAAS,CAAC;YACd,EAAE,CAAC;IACL,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb;YACE,+BAA+B;YAC/B,kEAAkE;YAClE,uBAAuB;SACxB,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,mBAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,eAAe,GAAG,0BAA0B,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IACrF,MAAM,gBAAgB,GAAG,IAAA,2BAAa,EAAC,WAAW,CAAC,CAAC;IACpD,IAAI,mBAA2B,CAAC;IAChC,IAAI,CAAC;QACH,mBAAmB,GAAG,gBAAgB,CAAC,OAAO,CAC5C,GAAG,eAAe,eAAe,CAClC,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb;YACE,wDAAwD,eAAe,IAAI;YAC3E,0DAA0D;SAC3D,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,mBAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,mBAAI,CAAC,IAAI,CACtB,YAAY,EACZ,KAAK,EACL,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CACjD,CAAC;IACF,IAAI,CAAC,iBAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,0CAA0C,MAAM,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,OAAO;QACL,MAAM;QACN,OAAO,EACL,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;QACrE,WAAW;QACX,WAAW;QACX,mBAAmB;QACnB,OAAO,EACL,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;KACtE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,4BAA4B,CAAC,IAAY;IAChD,IAAI,CAAC;QACH,OAAO,IAAA,2BAAa,EAAC,IAAI,CAAC,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,iEAAiE;AACjE,SAAS,eAAe,CAAC,IAAY;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,iBAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAA4B,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"resolveTsgo.js","sourceRoot":"","sources":["../../../src/compiler/internal/resolveTsgo.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,41 @@
+import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
+import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
+/**
+ * Execute a check with its same-generation input observations, preserving the
+ * selected host, original diagnostics, streams and status.
+ *
+ * The selected native verb must be check before negotiating this check-only
+ * channel. A check-stage descriptor can also serve effectful fix/format verbs;
+ * those retain their original result and never acquire an invented check graph.
+ * An opted-in host writes a private sidecar even when its check fails. Hosts
+ * without that transport run their original command under their existing
+ * descriptor and declared-input contract; omission does not assert complete
+ * driver observations. No check is rerun to infer what the earlier generation
+ * read. Missing metadata after an interrupted failed opted-in check likewise
+ * withholds reuse; missing or malformed successful metadata is a protocol
+ * error, not an empty proof.
+ *
+ * The callback receives only additional transport arguments. This operation
+ * owns their accepted canonical private directory and attempts file and empty
+ * directory removal without recursive deletion. Setup observes ownership before
+ * entering the cleanup boundary, so a setup observation failure can leave the
+ * allocation unclaimed. Cleanup failures retain the original thrown failure or
+ * completed result as their cause. Before reading and removing the artifact,
+ * the parent must still have its captured native identity; a replaced directory
+ * is left untouched and reported as failure. These observations do not provide
+ * an atomic descriptor or ABA guarantee.
+ *
+ * @evidence contracts/common.md#principled-implementation Only an actual check verb with the declared capability negotiates same-generation observations; effectful write verbs retain their own result without being projected as reusable check generations. The selected check generation's sidecar carries driver-observed input states; hosts with a different observation contract keep their original command and declared-input authority without fabricating driver completeness or incompleteness.
+ * @evidence contracts/common.md#clear-and-simple-design The actual verb and descriptor opt-in jointly select one adapter for strict wire decoding and private artifact lifetime; its callback retains command and diagnostic normalization ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Neither a later project-input query nor a separate transform can reconstruct check observations; unknown hosts receive no guessed flag and malformed metadata cannot become a complete empty observation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish failed-check metadata, unavailable transport, protocol errors and cleanup ownership, with body and tags separated according to the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native absolute paths locate the canonical private artifact, and an additional argv element conveys it without shell quoting or platform-specific filename guesses.
+ * @evidence contracts/performance.md#efficient-algorithms One original check callback runs; this adapter adds canonical temp acquisition/native ownership observations, complete sidecar read/JSON decoding and indexed input membership/witness validation. Work and temporary storage follow wire/path bytes and declared inputs plus delegated check runtime; it does not add a second compiler generation or source-content rehash, and supplies no callback timeout or metadata-byte ceiling.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adapter supplies the generation's proof to its cache owner rather than retaining or sharing a completed check itself.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources An accepted post-setup directory/artifact reaches ownership-checked cleanup attempts on success and failure; setup ownership observation occurs before this try/finally and can leave the allocation unclaimed. A replaced parent stays untouched, and ownership/removal failures preserve the primary outcome without certifying release. Wire text and parsed/witness records grow without a metadata-byte ceiling; accepted records transfer to the caller.
+ */
+export declare function runNativeCheckWithObservations(plugin: Pick<ITtscLoadedNativePlugin, "capabilities">, run: (extraArgs: readonly string[]) => TtscBuildResult, 
+/** Actual argv verb; legacy direct callers already represent a check. */
+command?: string): TtscBuildResult;

package/lib/compiler/internal/runNativeCheckWithObservations.js

@@ -0,0 +1,185 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runNativeCheckWithObservations = runNativeCheckWithObservations;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const createCanonicalTempDirectory_1 = require("../../internal/createCanonicalTempDirectory");
+const parseNativeTransformOutput_1 = require("./parseNativeTransformOutput");
+/**
+ * Execute a check with its same-generation input observations, preserving the
+ * selected host, original diagnostics, streams and status.
+ *
+ * The selected native verb must be check before negotiating this check-only
+ * channel. A check-stage descriptor can also serve effectful fix/format verbs;
+ * those retain their original result and never acquire an invented check graph.
+ * An opted-in host writes a private sidecar even when its check fails. Hosts
+ * without that transport run their original command under their existing
+ * descriptor and declared-input contract; omission does not assert complete
+ * driver observations. No check is rerun to infer what the earlier generation
+ * read. Missing metadata after an interrupted failed opted-in check likewise
+ * withholds reuse; missing or malformed successful metadata is a protocol
+ * error, not an empty proof.
+ *
+ * The callback receives only additional transport arguments. This operation
+ * owns their accepted canonical private directory and attempts file and empty
+ * directory removal without recursive deletion. Setup observes ownership before
+ * entering the cleanup boundary, so a setup observation failure can leave the
+ * allocation unclaimed. Cleanup failures retain the original thrown failure or
+ * completed result as their cause. Before reading and removing the artifact,
+ * the parent must still have its captured native identity; a replaced directory
+ * is left untouched and reported as failure. These observations do not provide
+ * an atomic descriptor or ABA guarantee.
+ *
+ * @evidence contracts/common.md#principled-implementation Only an actual check verb with the declared capability negotiates same-generation observations; effectful write verbs retain their own result without being projected as reusable check generations. The selected check generation's sidecar carries driver-observed input states; hosts with a different observation contract keep their original command and declared-input authority without fabricating driver completeness or incompleteness.
+ * @evidence contracts/common.md#clear-and-simple-design The actual verb and descriptor opt-in jointly select one adapter for strict wire decoding and private artifact lifetime; its callback retains command and diagnostic normalization ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Neither a later project-input query nor a separate transform can reconstruct check observations; unknown hosts receive no guessed flag and malformed metadata cannot become a complete empty observation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish failed-check metadata, unavailable transport, protocol errors and cleanup ownership, with body and tags separated according to the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native absolute paths locate the canonical private artifact, and an additional argv element conveys it without shell quoting or platform-specific filename guesses.
+ * @evidence contracts/performance.md#efficient-algorithms One original check callback runs; this adapter adds canonical temp acquisition/native ownership observations, complete sidecar read/JSON decoding and indexed input membership/witness validation. Work and temporary storage follow wire/path bytes and declared inputs plus delegated check runtime; it does not add a second compiler generation or source-content rehash, and supplies no callback timeout or metadata-byte ceiling.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adapter supplies the generation's proof to its cache owner rather than retaining or sharing a completed check itself.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources An accepted post-setup directory/artifact reaches ownership-checked cleanup attempts on success and failure; setup ownership observation occurs before this try/finally and can leave the allocation unclaimed. A replaced parent stays untouched, and ownership/removal failures preserve the primary outcome without certifying release. Wire text and parsed/witness records grow without a metadata-byte ceiling; accepted records transfer to the caller.
+ */
+function runNativeCheckWithObservations(plugin, run, 
+/** Actual argv verb; legacy direct callers already represent a check. */
+command = "check") {
+    if (command !== "check" || plugin.capabilities?.checkObservations !== true)
+        return run([]);
+    const directory = (0, createCanonicalTempDirectory_1.createCanonicalTempDirectory)("ttsc-check-observations-");
+    const ownership = node_fs_1.default.lstatSync(directory);
+    const file = node_path_1.default.join(directory, "observations.json");
+    let completed;
+    let failed = false;
+    let failure;
+    try {
+        completed = run(["--check-observations-json=" + file]);
+        if (completed.processCompletedNormally !== true)
+            return { ...completed, observationsComplete: false };
+        let text;
+        try {
+            assertDirectoryOwnership(directory, ownership);
+            if (!node_fs_1.default.lstatSync(file).isFile())
+                throw new Error("check observation artifact is not an ordinary file");
+            text = node_fs_1.default.readFileSync(file, "utf8");
+        }
+        catch (error) {
+            if (completed.status !== 0 &&
+                error.code === "ENOENT")
+                return { ...completed, observationsComplete: false };
+            throw new Error("ttsc: check observation metadata is unavailable", {
+                cause: new AggregateError([completed, error]),
+            });
+        }
+        try {
+            return { ...completed, ...parseObservations(JSON.parse(text)) };
+        }
+        catch (error) {
+            throw new Error("ttsc: invalid check observation metadata", {
+                cause: new AggregateError([completed, error]),
+            });
+        }
+    }
+    catch (error) {
+        failed = true;
+        failure = error;
+        throw error;
+    }
+    finally {
+        const errors = [];
+        try {
+            assertDirectoryOwnership(directory, ownership);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length === 0) {
+            try {
+                node_fs_1.default.rmSync(file, { force: true });
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            try {
+                node_fs_1.default.rmdirSync(directory);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length !== 0) {
+            const primary = failed ? failure : completed;
+            throw new AggregateError([primary, ...errors], "ttsc: check observation artifact cleanup failed", { cause: primary });
+        }
+    }
+}
+/** Refuse artifact IO or removal through a replaced private directory. */
+function assertDirectoryOwnership(directory, captured) {
+    const current = node_fs_1.default.lstatSync(directory);
+    if (!current.isDirectory() ||
+        current.isSymbolicLink() ||
+        current.dev !== captured.dev ||
+        current.ino !== captured.ino)
+        throw new Error("ttsc: check observation directory ownership changed");
+}
+/** Decode declared native inputs without refreshing producer observations. */
+function parseObservations(value) {
+    if (!isRecord(value) || !Array.isArray(value.hostInputs))
+        throw new Error("expected an observation record and input list");
+    if (value.observationsComplete !== undefined &&
+        value.observationsComplete !== false)
+        throw new Error("observation completeness must be absent or false");
+    const inputs = new Set();
+    for (const input of value.hostInputs) {
+        if (typeof input !== "string" || !node_path_1.default.isAbsolute(input))
+            throw new Error("expected absolute native input paths");
+        inputs.add(node_path_1.default.resolve(input));
+    }
+    const graph = (0, parseNativeTransformOutput_1.parseReferenceGraph)(value.graph);
+    const graphUnavailable = graph === undefined ||
+        (graph.inputHashes === undefined &&
+            graph.inputObservations === undefined &&
+            graph.inputRealpaths === undefined &&
+            graph.inputProofFailures === undefined);
+    return {
+        ...(graph === undefined ? {} : { graph }),
+        ...(graphUnavailable ? { observationsComplete: false } : {}),
+        hostInputs: [...inputs],
+        hostInputHashes: parseWitnesses(value.hostInputHashes, inputs, false),
+        hostInputRealpaths: parseWitnesses(value.hostInputRealpaths, inputs, true),
+        ...(value.observationsComplete === false
+            ? { observationsComplete: false }
+            : {}),
+    };
+}
+/** Retain null witnesses and missing conflicting proofs as distinct states. */
+function parseWitnesses(value, inputs, physical) {
+    if (!isRecord(value))
+        throw new Error("expected an input witness record");
+    const output = {};
+    for (const [file, witness] of Object.entries(value)) {
+        if (!node_path_1.default.isAbsolute(file) || !inputs.has(node_path_1.default.resolve(file)))
+            throw new Error("witness key must identify a declared native input");
+        if (witness !== null &&
+            (typeof witness !== "string" ||
+                (physical
+                    ? !node_path_1.default.isAbsolute(witness)
+                    : !/^[0-9a-f]{64}$/.test(witness))))
+            throw new Error("invalid input witness");
+        const key = node_path_1.default.resolve(file);
+        const normalized = physical && typeof witness === "string" ? node_path_1.default.resolve(witness) : witness;
+        if (Object.prototype.hasOwnProperty.call(output, key) &&
+            output[key] !== normalized)
+            throw new Error("conflicting native input coordinates");
+        output[key] = normalized;
+    }
+    return output;
+}
+/** JSON object records exclude scalar and array payloads. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=runNativeCheckWithObservations.js.map

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

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

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

@@ -1,12 +1,33 @@
 import type { TtscSingleFileEmitOptions } from "../../structures/internal/TtscSingleFileEmitOptions";
+import { CompilerProjectSelection } from "./project/CompilerProjectSelection";
 /**
  * Emit one source file by building its project into a temporary directory.
  *
- * The full project is compiled with `forceListEmittedFiles` so that the emitted
- * file list is available for `resolveEmittedJavaScript`. The temp directory is
- * always cleaned up in the `finally` block, even on error.
+ * The full project is compiled with its `rootDir` pinned, and the output is
+ * selected through the producing build's emitted-source provenance and current
+ * physical source identity. Missing or ambiguous ownership is refused without
+ * source-map or filename-precedence inference. Temp-directory removal in
+ * `finally` is attempted after acquisition, including failure paths. Removal
+ * failure propagates on success and is aggregated with an earlier operation
+ * failure rather than replacing it.
+ *
+ * A launcher-supplied selection shares its project and original compiler argument
+ * cwd with public output planning. Response freshness is checked before native
+ * work and publication; these sequential checks do not pin bytes atomically.
+ * Callers without that record retain explicit config/nearest-file discovery.
  *
  * @returns The transformed JavaScript source text.
- * @throws When the build exits non-zero or no output is produced for the file.
+ * @throws When the build exits non-zero, proves no JavaScript for the requested
+ *   source or cannot establish unique ownership.
+ * @evidence contracts/common.md#principled-implementation The supplied invocation selection or legacy locator establishes one project and compiler argument base; current response observations, effective rootDir precedence and isolated emission preserve that producing invocation; its emitted-source provenance and current physical source identity select the actual written output before optional caller-directed writing.
+ * @evidence contracts/common.md#clear-and-simple-design One operation owns project emission, optional public copy and returned text. A supplied existing selection replaces repeated discovery; delegated option interpretation and provenance retain their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing or ambiguous provenance cannot become ownership through basename, source-map presence or extension precedence; inferred-root pinning addresses the compiler's injected-outDir requirement.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain exact-source selection, missing owned output and temporary lifetime; the private realpath helper describes unavailable identity without a test-specific premise.
+ * @evidence contracts/performance.md#efficient-algorithms A supplied project avoids another discovery; otherwise legacy discovery remains. Sequential response freshness checks and effective-option inspection precede one full project build, followed by publication reobservation. Output enumeration visits directory entries and sorts output paths; provenance indexing resolves native output identities and processes source associations. Only selected output content is read here, with optional caller output writing; path/association/output bytes and delegated native/build costs remain part of this call.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This invocation observes the project's current compiler/plugin effects and owns no valid-generation cache; equivalent build sharing belongs to higher-level runtime owners.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One accepted private output directory reaches removal in finally after success, build failure, lookup failure or output writing; acquisition has its own failure limitations. The index and selected text live until return/throw and transfer text to the caller, without an output-byte ceiling or timeout supplied here. Cleanup failure propagates after success and aggregates with the original failure and cause after an unsuccessful operation, so neither outcome is hidden.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths and filesystem identities use Node APIs, child execution uses argument arrays, and optional output targets resolve from the invocation cwd on each supported host.
  */
-export declare function runSingleFileEmit(options: TtscSingleFileEmitOptions): string;
+export declare function runSingleFileEmit(options: TtscSingleFileEmitOptions, selection?: ReturnType<typeof CompilerProjectSelection.read>): string;