ttsc 0.34.3 → 0.35.0

package/src/compiler/internal/build/RuntimeInputProof.ts

@@ -0,0 +1,346 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import type { ITtscCompilerTransformation } from "../../../structures/ITtscCompilerTransformation";
+import type { TtscBuildResult } from "../../../structures/internal/TtscBuildResult";
+
+/**
+ * Replay the compiler and native input witnesses of a completed runtime build.
+ * Read predicates keep their original text or raw-byte codec; absence, entry
+ * kind, physical target and directory membership remain independent predicates.
+ * Failed or unsupported observations withhold reuse.
+ *
+ * @evidence contracts/common.md#principled-implementation Replay compares generation witnesses with current existence, stat, decoded text, physical identity and directory membership. Native version-one file, optional-file, entry and directory codecs use explicit tags, raw file/link bytes and sorted nul-delimited records. Compiler text strips UTF-8 BOM or decodes even UTF-16LE/BE bytes before SHA-256; host directory presence uses its separate domain marker.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace separates result admission, declared host inputs, compiler predicates and the native version-one codec. Private physical/absence and SHA-256 helpers serve the codecs without merging their meanings.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown codecs, failed reads and producer proof failures decline admission. Only ENOENT/ENOTDIR prove absence; other physical-resolution errors remain unavailable. Following stat classifies compiler views while lstat retains native link kinds; only the producer private output subtree is excluded.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies generation proof, codec ownership and refusal semantics; private helper comments identify query, byte, decoded-text and null/error boundaries.
+ * @evidence contracts/portability.md#os-neutral-implementation Native stat, lstat and realpath retain actual kinds, targets and spellings without case assumptions. POSIX directory names/link targets stay raw bytes, Windows names follow the producer UTF-8 codec, and compiler directory entries sort by UTF-8 bytes.
+ * @evidence contracts/performance.md#efficient-algorithms Replay visits recorded predicates and their bytes or immediate directory entries rather than unrelated trees. Hashing and BOM decoding cost O(bytes), including a big-endian copy; directory codecs cost O(N log N) sorting plus encoded bytes and link queries. Physical resolution follows native path/link traversal.
+ * @evidence contracts/performance.md#reuse-equivalent-work Every retained predicate is observed anew to authorize completed-result reuse. Host capture and admission share the producer codec; no path memo, watcher silence or historical hash independently grants authority.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Read buffers, decoded text, paths and sorted directory members are call-local and have no proof-reader byte or entry cap. Synchronous calls retain no handle, watcher, process or historical population; only returned proof values escape.
+ */
+export namespace RuntimeInputProof {
+  /**
+   * Validate result-level host witnesses and every reported compiler predicate.
+   * The caller independently proves the selected compiler, project membership
+   * and plugin selection; an absent graph alone grants no completeness.
+   *
+   * @evidence contracts/common.md#principled-implementation Explicit incomplete observations and any graph failure reject reuse; host paths require both content and physical witnesses, and rich compiler predicates are replayed under their own codec.
+   * @evidence contracts/common.md#clear-and-simple-design One admission pass delegates individual compiler observations and native codecs.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing witness fields never become an empty successful observation, and only the caller-owned private output subtree is excluded.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies result admission and the caller's separate completeness obligations.
+   * @evidence contracts/portability.md#os-neutral-implementation Native path resolution anchors producer-relative graph keys, and current physical paths come from native realpath.
+   * @evidence contracts/performance.md#efficient-algorithms Input and predicate populations drive replay; each read hashes its actual bytes and directories sort immediate entry records.
+   * @evidence contracts/performance.md#reuse-equivalent-work Generation witnesses, rather than an identity-key match, decide whether a completed build remains reusable.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Temporary path and predicate records are invocation-owned without retained handles or history.
+   */
+  export function holds(
+    result: TtscBuildResult,
+    projectRoot: string,
+    emitDir: string,
+  ): boolean {
+    if (
+      result.observationsComplete === false ||
+      Object.keys(result.graph?.inputProofFailures ?? {}).length !== 0
+    )
+      return false;
+    try {
+      for (const file of result.hostInputs ?? []) {
+        const [currentPhysical, hash] = observeHostInput(file);
+        if (
+          !Object.hasOwn(result.hostInputHashes ?? {}, file) ||
+          !Object.hasOwn(result.hostInputRealpaths ?? {}, file) ||
+          currentPhysical !== result.hostInputRealpaths![file] ||
+          hash !== result.hostInputHashes![file]
+        )
+          return false;
+      }
+      const graph = result.graph;
+      for (const [name, observed] of Object.entries(
+        graph?.inputObservations ?? {},
+      )) {
+        const file = path.resolve(projectRoot, name);
+        const relative = path.relative(emitDir, file);
+        if (
+          relative === "" ||
+          (!path.isAbsolute(relative) &&
+            relative !== ".." &&
+            !relative.startsWith(".." + path.sep))
+        )
+          continue;
+        if (!observationHolds(file, observed)) return false;
+      }
+      for (const [name, expected] of Object.entries(graph?.inputHashes ?? {})) {
+        if (Object.hasOwn(graph?.inputObservations ?? {}, name)) continue;
+        const file = path.resolve(projectRoot, name);
+        if (physical(file) !== graph?.inputRealpaths?.[name]) return false;
+        let current: string | null = null;
+        try {
+          if (fs.statSync(file).isFile())
+            current = textHash(fs.readFileSync(file));
+        } catch (error) {
+          if (!missing(error)) return false;
+        }
+        if (current !== expected) return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Observe a declared host input under its existing raw-file or directory-kind
+   * codec. Descriptor resolution can declare directories as presence inputs;
+   * those are distinct from compiler source reads and directory enumeration.
+   * Native identity and metadata bracket the observation. Missing paths carry
+   * null witnesses, while unavailable or changing observations throw.
+   *
+   * @evidence contracts/common.md#principled-implementation Raw file bytes and the existing ttsc:host-input:directory domain marker reproduce the descriptor/native host-input contract, with physical identity and full native metadata checked before and after.
+   * @evidence contracts/common.md#clear-and-simple-design One observer supplies the same declared-host codec to input capture and retained-result admission, independently of compiler text and enumeration predicates.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only ENOENT/ENOTDIR establish absence; unsupported entry kinds, read failures and changing witnesses refuse reuse instead of becoming empty content.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes directory presence from directory membership, states the producer codec and explains failure semantics.
+   * @evidence contracts/portability.md#os-neutral-implementation Native following stat, realpath and byte reads retain actual host links and physical spellings without OS-name or separator guesses.
+   * @evidence contracts/performance.md#efficient-algorithms File observations hash their complete byte buffer and bracket native metadata; directory presence hashes a fixed marker without scanning members.
+   * @evidence contracts/performance.md#reuse-equivalent-work Capture and admission share the producer's codec, but every invocation observes current witnesses and retains no path-only truth.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Read buffers and stat records are call-local; synchronous filesystem calls leave no retained handle or watcher.
+   */
+  export function observeHostInput(
+    file: string,
+  ): readonly [string | null, string | null] {
+    const beforePhysical = physical(file);
+    let before: fs.BigIntStats;
+    try {
+      before = fs.statSync(file, { bigint: true });
+    } catch (error) {
+      if (!missing(error)) throw error;
+      if (beforePhysical !== null || physical(file) !== null)
+        throw new Error("Host input changed during absence observation.");
+      return [null, null];
+    }
+    if (!before.isFile() && !before.isDirectory())
+      throw new Error("Unsupported runtime host input kind.");
+    const hash = before.isDirectory()
+      ? digest("ttsc:host-input:directory\0")
+      : digest(fs.readFileSync(file));
+    const after = fs.statSync(file, { bigint: true });
+    const signature = (stat: fs.BigIntStats): string =>
+      [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
+    if (
+      signature(before) !== signature(after) ||
+      beforePhysical !== physical(file)
+    )
+      throw new Error("Host input changed during observation.");
+    return [beforePhysical, hash];
+  }
+
+  /** Compare one compiler query record with the corresponding current queries. */
+  function observationHolds(
+    file: string,
+    observed: ITtscCompilerTransformation.IInputObservation,
+  ): boolean {
+    for (const predicate of observed.nativePredicates ?? [])
+      if (
+        predicate.version !== 1 ||
+        !predicate.identityStable ||
+        physical(file) !== predicate.realpath ||
+        nativeDigest(file, predicate.kind) !== predicate.digest
+      )
+        return false;
+    let kind: "file" | "directory" | "missing" = "missing";
+    try {
+      const stat = fs.statSync(file);
+      kind = stat.isDirectory() ? "directory" : "file";
+    } catch (error) {
+      if (!missing(error)) return false;
+    }
+    if (
+      observed.fileExists !== undefined &&
+      observed.fileExists !== (kind === "file")
+    )
+      return false;
+    if (
+      observed.directoryExists !== undefined &&
+      observed.directoryExists !== (kind === "directory")
+    )
+      return false;
+    if (observed.stat !== undefined && observed.stat !== kind) return false;
+    if (observed.readFile !== undefined) {
+      let hash: string | null = null;
+      try {
+        if (kind !== "directory") hash = textHash(fs.readFileSync(file));
+      } catch {
+        /* Compiler read failed. */
+      }
+      if (
+        observed.readFile.ok ? hash !== observed.readFile.hash : hash !== null
+      )
+        return false;
+    }
+    if (observed.realpath !== undefined) {
+      const current = physical(file);
+      if (
+        observed.realpath.ok
+          ? current !== observed.realpath.path
+          : current !== null
+      )
+        return false;
+    }
+    if (observed.accessibleEntries !== undefined) {
+      const directories: string[] = [];
+      const files: string[] = [];
+      let entries: fs.Dirent[] = [];
+      try {
+        entries = fs.readdirSync(file, { withFileTypes: true });
+      } catch {
+        /* Compiler enumeration returns an empty view. */
+      }
+      for (const entry of entries) {
+        try {
+          const stat = entry.isSymbolicLink()
+            ? fs.statSync(path.join(file, entry.name))
+            : entry;
+          if (stat.isDirectory()) directories.push(entry.name);
+          else if (stat.isFile()) files.push(entry.name);
+        } catch {
+          /* Compiler enumeration omits inaccessible link targets. */
+        }
+      }
+      const compare = (a: string, b: string): number =>
+        Buffer.compare(Buffer.from(a), Buffer.from(b));
+      if (
+        JSON.stringify({
+          directories: directories.sort(compare),
+          files: files.sort(compare),
+        }) !== JSON.stringify(observed.accessibleEntries)
+      )
+        return false;
+    }
+    return true;
+  }
+
+  /**
+   * Reproduce native version-one file, optional-file, entry and directory
+   * bytes.
+   */
+  function nativeDigest(file: string, kind: string): string {
+    if (kind === "file") return digest(fs.readFileSync(file));
+    if (kind === "optional-file") {
+      try {
+        return fs.statSync(file).isFile()
+          ? digest(
+              Buffer.concat([Buffer.from("file\0"), fs.readFileSync(file)]),
+            )
+          : digest("missing\0");
+      } catch (error) {
+        if (missing(error)) return digest("missing\0");
+        throw error;
+      }
+    }
+    if (kind === "entry") {
+      try {
+        const entry = fs.lstatSync(file);
+        return entry.isSymbolicLink()
+          ? digest(
+              Buffer.concat([
+                Buffer.from("symlink\0"),
+                fs.readlinkSync(file, { encoding: "buffer" }),
+              ]),
+            )
+          : digest(
+              (entry.isDirectory()
+                ? "directory"
+                : entry.isFile()
+                  ? "file"
+                  : "other") + "\0",
+            );
+      } catch (error) {
+        if (missing(error)) return digest("missing\0");
+        throw error;
+      }
+    }
+    if (kind !== "directory") throw new Error("unsupported native input codec");
+    const records: Buffer[] = [];
+    const names =
+      process.platform === "win32"
+        ? fs.readdirSync(file).map((name) => Buffer.from(name))
+        : fs.readdirSync(file, { encoding: "buffer" });
+    for (const name of names) {
+      const target =
+        process.platform === "win32"
+          ? path.join(file, name.toString())
+          : Buffer.concat([Buffer.from(file + path.sep), name]);
+      const entry = fs.lstatSync(target);
+      const entryKind = entry.isDirectory()
+        ? "directory"
+        : entry.isFile()
+          ? "file"
+          : entry.isSymbolicLink()
+            ? "symlink"
+            : "other";
+      const link = entry.isSymbolicLink()
+        ? fs.readlinkSync(target, { encoding: "buffer" })
+        : Buffer.alloc(0);
+      records.push(
+        Buffer.concat([name, Buffer.from("\0" + entryKind + "\0"), link]),
+      );
+    }
+    records.sort(Buffer.compare);
+    return digest(
+      Buffer.concat(
+        records.flatMap((record, index) =>
+          index === 0 ? [record] : [Buffer.from([0]), record],
+        ),
+      ),
+    );
+  }
+
+  /** Hash compiler-decoded text, retaining the BOM and UTF-16 producer policy. */
+  function textHash(bytes: Buffer): string {
+    if (
+      bytes.length >= 2 &&
+      ((bytes[0] === 0xff && bytes[1] === 0xfe) ||
+        (bytes[0] === 0xfe && bytes[1] === 0xff))
+    ) {
+      const text = Buffer.from(
+        bytes.subarray(2, 2 + Math.floor((bytes.length - 2) / 2) * 2),
+      );
+      if (bytes[0] === 0xfe) text.swap16();
+      return digest(Buffer.from(text.toString("utf16le"), "utf8"));
+    }
+    return digest(
+      bytes.length >= 3 &&
+        bytes[0] === 0xef &&
+        bytes[1] === 0xbb &&
+        bytes[2] === 0xbf
+        ? bytes.subarray(3)
+        : bytes,
+    );
+  }
+
+  /** Obtain a current physical coordinate, with null only for native absence. */
+  function physical(file: string): string | null {
+    try {
+      return fs.realpathSync.native(file);
+    } catch (error) {
+      if (missing(error)) return null;
+      throw error;
+    }
+  }
+
+  /** Classify only native absent-path errors. */
+  function missing(error: unknown): boolean {
+    return (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    );
+  }
+
+  /** SHA-256 of supplied text or raw bytes. */
+  function digest(bytes: string | Buffer): string {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+  }
+}

package/src/compiler/internal/build/TsgoArguments.ts

@@ -195,11 +195,12 @@ export namespace TsgoArguments {
   /**
    * The forwarded-tsgo payload for a native `build`/`check` emit invocation.
    *
-   * The sidecar builds its Program in-process, so the pinned `rootDir` has to
-   * travel the same channel every other tsgo option takes to it — the host flag
-   * set does not declare `--rootDir`, and `filterHostArgs` would strip it.
+   * The sidecar builds its Program in-process, so runtime source-map defaults
+   * and the pinned `rootDir` travel the same channel as other tsgo options —
+   * the host flag set does not declare `--rootDir`, and `filterHostArgs` would
+   * strip it.
    *
-   * @evidence contracts/common.md#principled-implementation The same private layout root used by direct builds is placed in the sidecar compiler-option channel, preserving declared/composite containment while avoiding a new ordinary config-directory restriction without a new host flag.
+   * @evidence contracts/common.md#principled-implementation The same private layout root and forced runtime source-map default used by direct builds precede user arguments in the sidecar compiler-option channel, preserving explicit overrides and declared/composite containment without a new host flag.
    * @evidence contracts/common.md#clear-and-simple-design Root pinning stays in one helper and general payload ordering/serialization stays in createNativeTsgoArgs.
    * @evidence contracts/common.md#prohibited-implementation-shortcuts The supported environment payload carries compiler options instead of injecting unknown flags into strict foreign host parsers.
    * @evidence contracts/common.md#meaningful-documentation Native prose explains why rootDir travels with compiler options rather than through the host flag set.
@@ -215,7 +216,12 @@ export namespace TsgoArguments {
   ): string | undefined {
     return createNativeTsgoArgs(
       options,
-      pinnedRootDirArgs(execution, options),
+      [
+        ...(options.forceRuntimeSourceMap === true
+          ? ["--sourceMap", "true"]
+          : []),
+        ...pinnedRootDirArgs(execution, options),
+      ],
       false,
     );
   }

package/src/compiler/internal/build/runBuild.ts

@@ -2,6 +2,8 @@ import type { TtscBuildResult } from "../../../structures/internal/TtscBuildResu
 import { BuildExecution } from "./BuildExecution";
 import { BuildTiming } from "./BuildTiming";
 import type { RunBuildOptions } from "./RunBuildOptions";
+import { RuntimeBuildCache } from "./RuntimeBuildCache";
+import { RuntimeBuildInputs } from "./RuntimeBuildInputs";
 import { WatchInputPublication } from "./WatchInputPublication";
 
 /**
@@ -21,7 +23,7 @@ import { WatchInputPublication } from "./WatchInputPublication";
  * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes returned exit failures from thrown setup/launch errors and explains the project-free branch.
  * @evidence contracts/portability.md#os-neutral-implementation Execution selection and spawning use the shared native path/process boundaries with cwd and separate argv, rather than constructing a shell command here.
  * @evidence contracts/performance.md#efficient-algorithms Timing creation and terminal selection make their own flag projections before the selected preparation/execution path. Delegated configuration, plugin, native/provenance and diagnostic work follows its actual input/report sizes; timing formatting scans ledger labels and output. No measured dominance or duration/output ceiling is established by this wrapper.
- * @evidence contracts/performance.md#reuse-equivalent-work A resolved execution context is carried through preparation and execution, so this build does not reload its plugin selection between phases.
+ * @evidence contracts/performance.md#reuse-equivalent-work A resolved execution context is carried through preparation and execution without another plugin load; private runtime requests delegate verified completed-emission reuse to RuntimeBuildCache with current input and producer proofs.
  * @evidence contracts/performance.md#bound-retention-and-release-resources The ledger and execution state are build-owned, while returned output/proof/diagnostic records transfer to the caller; no resident handle or historical build is stored here. Delegated native/probe/artifact acquisition and cleanup may be best effort, and thrown setup can precede some cleanup boundaries. This wrapper supplies no duration/output bound or descendant-release certification.
  */
 export function runBuild(options: RunBuildOptions = {}): TtscBuildResult {
@@ -36,8 +38,8 @@ export function runBuild(options: RunBuildOptions = {}): TtscBuildResult {
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Awaiting changes only publication completion, preserves compiler/plugin selection and project-free terminal behavior, and sends publication failure through existing setup and cleanup rather than bypassing a pending baseline.
  * @evidence contracts/common.md#meaningful-documentation Entry prose states the publication barrier, order before compilation and internal callers' obligation to complete the sequence and deliver rejection.
  * @evidence contracts/portability.md#os-neutral-implementation BuildExecution retains native cwd, path identity and argument-array ownership across suspension; the namespace adds no independent native boundary.
- * @evidence contracts/performance.md#efficient-algorithms Each selected terminal, context, discovery, preparation and compile phase runs once; each publication adds one await and constant sequence state.
- * @evidence contracts/performance.md#reuse-equivalent-work One resolved execution context serves preparation and compilation without reloading plugins; the namespace retains no completed build or in-flight cache.
+ * @evidence contracts/performance.md#efficient-algorithms Each selected terminal, context, discovery and preparation phase runs once; eligible runtime requests add native source/configuration queries and content proofs before restoring or compiling. Each publication adds one await and constant sequence state.
+ * @evidence contracts/performance.md#reuse-equivalent-work One resolved execution context serves preparation and compilation without reloading plugins; the delegated runtime store reuses completed bytes only under current equal input snapshots and valid producer witnesses, with ordinary compilation on any miss.
  * @evidence contracts/performance.md#bound-retention-and-release-resources The invocation owns its sequence, ledger, context and current handoff while callbacks settle. Selected results transfer to the caller, delegated resource ownership and cleanup stay unchanged, and no resident history is retained.
  */
 export namespace runBuild {
@@ -72,14 +74,27 @@ export namespace runBuild {
       execution,
       setupStartedAt,
     );
-    const result =
-      prepared.result ??
+    const build = () =>
       BuildExecution.runPreparedBuild(
         options,
         timing,
         execution,
         prepared.buildOptions,
       );
+    const proof =
+      prepared.result === undefined
+        ? RuntimeBuildInputs.create(prepared.buildOptions, execution)
+        : undefined;
+    const result =
+      prepared.result ??
+      (proof === undefined
+        ? build()
+        : RuntimeBuildCache.run({
+            directory: options.runtimeCacheDir,
+            emitDir: options.isolateOutputsTo!,
+            ...proof,
+            build,
+          }));
     return BuildTiming.appendTimingOutput(result, timing);
   }
 }

package/src/compiler/internal/runNativeCheckWithObservations.ts

@@ -7,36 +7,40 @@ import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult"
 import { parseReferenceGraph } from "./parseNativeTransformOutput";
 
 /**
- * Execute a check with its same-generation input observations, preserving the
- * selected host, original diagnostics, streams and status.
+ * Execute a check or opted-in build with 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
+ * The selected native verb must be check, or build with the separate
+ * emitObservations capability, before negotiating its generation 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.
+ * withholds reuse. Missing or malformed successful check metadata is a protocol
+ * error. Build metadata is optional cache evidence: unavailable setup, records
+ * or cleanup retain the original build result with incomplete observations, so
+ * loss of caching cannot turn a fresh successful emit into failure.
  *
  * 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.
+ * completed check 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 withholds build reuse or reports check
+ * 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#principled-implementation Actual check and build verbs negotiate independent declared observation capabilities; fix/format verbs retain their own result. Build witness IO/protocol failures preserve the one original build with incomplete observations, while checks retain their strict metadata contract. Legacy hosts keep their original command without fabricated completeness.
  * @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.
+ * @evidence contracts/performance.md#efficient-algorithms One original check or build 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 producer 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.
  *
@@ -48,17 +52,32 @@ export function runNativeCheckWithObservations(
   /** Actual argv verb; legacy direct callers already represent a check. */
   command: string = "check",
 ): TtscBuildResult {
-  if (command !== "check" || plugin.capabilities?.checkObservations !== true)
+  const emitting =
+    command === "build" && plugin.capabilities?.emitObservations === true;
+  if (
+    !emitting &&
+    (command !== "check" || plugin.capabilities?.checkObservations !== true)
+  )
     return run([]);
 
-  const directory = createCanonicalTempDirectory("ttsc-check-observations-");
-  const ownership = fs.lstatSync(directory);
+  let directory: string;
+  let ownership: fs.Stats;
+  try {
+    directory = createCanonicalTempDirectory("ttsc-check-observations-");
+    ownership = fs.lstatSync(directory);
+  } catch (error) {
+    if (emitting) return { ...run([]), observationsComplete: false };
+    throw error;
+  }
   const file = path.join(directory, "observations.json");
   let completed: TtscBuildResult | undefined;
   let failed = false;
   let failure: unknown;
   try {
-    completed = run(["--check-observations-json=" + file]);
+    completed = run([
+      (emitting ? "--emit-observations-json=" : "--check-observations-json=") +
+        file,
+    ]);
     if (completed.processCompletedNormally !== true)
       return { ...completed, observationsComplete: false };
     let text: string;
@@ -68,6 +87,7 @@ export function runNativeCheckWithObservations(
         throw new Error("check observation artifact is not an ordinary file");
       text = fs.readFileSync(file, "utf8");
     } catch (error) {
+      if (emitting) return { ...completed, observationsComplete: false };
       if (
         completed.status !== 0 &&
         (error as NodeJS.ErrnoException).code === "ENOENT"
@@ -80,6 +100,7 @@ export function runNativeCheckWithObservations(
     try {
       return { ...completed, ...parseObservations(JSON.parse(text)) };
     } catch (error) {
+      if (emitting) return { ...completed, observationsComplete: false };
       throw new Error("ttsc: invalid check observation metadata", {
         cause: new AggregateError([completed, error]),
       });
@@ -108,6 +129,8 @@ export function runNativeCheckWithObservations(
       }
     }
     if (errors.length !== 0) {
+      if (emitting && completed !== undefined && !failed)
+        return { ...completed, observationsComplete: false };
       const primary = failed ? failure : completed;
       throw new AggregateError(
         [primary, ...errors],

package/src/flags/FLAG_SCHEMA.ts

@@ -352,6 +352,13 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
   // -------------------------------------------------------------------------
   // ttsx-specific options.
   // -------------------------------------------------------------------------
+  {
+    name: "--no-cache",
+    kind: "boolean",
+    subcommands: ["ttsx"],
+    consumedBy: ["launcher"],
+    description: "Disable persistent runtime project emit reuse.",
+  },
   {
     name: "--require",
     aliases: ["-r"],

package/src/launcher/internal/parseTtsxCLI.ts

@@ -120,6 +120,7 @@ export function parseTtsxCLI(argv: readonly string[]) {
     checkers: getNumber(result, "--checkers"),
     cwd: getString(result, "--cwd"),
     entry,
+    noCache: getBoolean(result, "--no-cache") === true,
     noPlugins: getBoolean(result, "--no-plugins") === true,
     passthrough: postEntryArgs,
     preload,

package/src/launcher/internal/prepareExecution.ts

@@ -65,6 +65,9 @@ export function prepareExecution(
 
     /** Internal cache key for more than one checked entry in this process. */
     runtimeCacheKey?: string;
+
+    /** False bypasses persistent project emits while keeping normal execution. */
+    runtimeCache?: boolean;
   } = {},
 ): {
   /** Claimed runtime generation whose cleanup ownership transfers to the caller. */
@@ -383,6 +386,15 @@ function createProjectContext(
     runtimeCacheKey,
     processDir,
     pluginCacheDir: explicitCacheDir === undefined ? undefined : cacheDir,
+    runtimeBuildCacheDir:
+      options.runtimeCache === false ||
+      env.TTSX_DISABLE_CACHE === "1" ||
+      env.TTSC_PLUGIN_DESCRIPTOR_LOAD === "1"
+        ? undefined
+        : path.join(
+            cacheRoot,
+            SourceBuildCacheLayout.RUNTIME_BUILD_CACHE_DIRNAME,
+          ),
     orphanCacheDir: path.join(
       cacheRoot,
       SourceBuildCacheLayout.ORPHAN_CACHE_DIRNAME,
@@ -527,6 +539,7 @@ function buildProject(
     emit: true,
     env: options.env,
     cacheDir: context.pluginCacheDir,
+    runtimeCacheDir: context.runtimeBuildCacheDir,
     outDir: context.emitDir,
     // Every output this build writes stays in ttsx's private directory: a
     // declared `declarationDir`, `tsBuildInfoFile`, or `outFile`, and any

package/src/launcher/internal/runTtsx.ts

@@ -110,6 +110,7 @@ async function run(
     cacheDir: resolveCacheDir(cwd, parsed.cacheDir),
     checkers: parsed.checkers,
     cwd,
+    env: parsed.noCache ? { TTSX_DISABLE_CACHE: "1" } : undefined,
     passthrough: parsed.tsgoFlags,
     // `--no-plugins` builds the entry's owning project with plugin
     // discovery and loading disabled. ttsc's own config loaders use it
@@ -121,6 +122,7 @@ async function run(
     // tsconfig deliberately does not satisfy.
     plugins: parsed.noPlugins ? false : undefined,
     project: parsed.project,
+    runtimeCache: !parsed.noCache,
     singleThreaded: parsed.singleThreaded,
   });
   await settleSignals();
@@ -159,6 +161,7 @@ function printHelp(): void {
       "  -P, --project <file>   Use an explicit tsconfig.json",
       "  --cwd <dir>            Resolve entry/project relative to this directory",
       "  --cache-dir <dir>      Override the runner and source-plugin cache root",
+      "  --no-cache             Disable persistent runtime project emit reuse",
       "  --binary <path>        Use an explicit tsgo binary",
       "  --no-plugins           Build the project without ttsc plugins",
       "  -r, --require <module> Preload a module before the entrypoint",
@@ -244,6 +247,7 @@ async function runJavaScriptEntry(
   ];
   const env: NodeJS.ProcessEnv = {
     ...process.env,
+    ...(parsed.noCache ? { TTSX_DISABLE_CACHE: "1" } : {}),
     // ttsc's own helpers run with what the user passed (#1740).
     ...TtsxNodeOptions.give(
       process.env,
@@ -329,6 +333,7 @@ async function runPreparedEntry(
     ];
     const runtimeEnv: NodeJS.ProcessEnv = {
       ...process.env,
+      ...(parsed.noCache ? { TTSX_DISABLE_CACHE: "1" } : {}),
       // ttsc's own helpers run with what the user passed (#1740).
       ...TtsxNodeOptions.give(
         process.env,