ttsc 0.34.3 → 0.36.0

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/compiler/internal/sharedHost/inheritedSidecarEnv.ts

@@ -1,3 +1,4 @@
+import { CompilationSnapshot } from "../CompilationSnapshot";
 import { SidecarEnvironment } from "./SidecarEnvironment";
 import { clearInheritedSemanticConfigPath } from "./clearInheritedSemanticConfigPath";
 import { clearInheritedTsgoArgs } from "./clearInheritedTsgoArgs";
@@ -6,7 +7,8 @@ import { publishLinkedTransformPlugins } from "./publishLinkedTransformPlugins";
 /**
  * Merge inherited and caller environments with native variable-name identity,
  * then clear per-invocation payloads this lane never published: forwarded tsgo
- * arguments, semantic config ownership and the linked-plugin manifest.
+ * arguments, compilation snapshot, semantic config ownership and the
+ * linked-plugin manifest.
  *
  * Use it at every spawn whose child can reach `driver.LoadProgram` — the
  * `api-compile` / `api-transform` hosts, and the plugin loader, whose `ttsx`
@@ -40,6 +42,11 @@ export function inheritedSidecarEnv(
   );
   clearInheritedTsgoArgs(env, callerEnv);
   clearInheritedSemanticConfigPath(env, callerEnv);
+  SidecarEnvironment.write(
+    env,
+    CompilationSnapshot.ENV,
+    SidecarEnvironment.read(callerEnv, CompilationSnapshot.ENV),
+  );
   publishLinkedTransformPlugins(env, callerEnv, []);
   return env;
 }

package/src/compiler/internal/transformProjectInMemory.ts

@@ -11,6 +11,7 @@ import type { ITtscCompilerTransformation } from "../../structures/ITtscCompiler
 import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
 import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
+import { CompilationSnapshot } from "./CompilationSnapshot";
 import { appendBuildOutput, mergeCheckGraphs } from "./build/appendBuildOutput";
 import { normalizeBuildOutput } from "./build/normalizeBuildOutput";
 import { buildNativeCompiler } from "./buildNativeCompiler";
@@ -60,10 +61,10 @@ import { spawnNative } from "./spawnNative";
  * @evidence contracts/common.md#clear-and-simple-design One router composes built-in and plugin-backed transforms; envelope parsers, environment construction, proof merging and negative-only observation limits have separate shared helpers.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing input proof cannot be repaired by a postcompile baseline; conventional deferred config reads accept only the actual native consumer's proof, while malformed required TypeScript output is a protocol error.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe transform lanes and stage ordering; separated result members distinguish output, advisory graph/dependency data, evaluation witnesses and unstable source markers under documentation guidance.
- * @evidence contracts/performance.md#efficient-algorithms Stage filtering, declared-input Sets and proof maps scale with plugin/input counts; merged paths are sorted with path-text comparison costs. Each stage can rehash/re-realpath declared inputs, serialize plugin/config records and parse complete output; discovery, native capability probes, source builds and child execution remain delegated costs of this call. No byte/work ceiling or measured dominant-cost ranking is asserted.
- * @evidence contracts/performance.md#reuse-equivalent-work Source-plugin artifacts are shared by their owning loader; this transform intentionally produces a current generation and gives downstream consumers the graph, source states and host witnesses required to qualify reuse.
+ * @evidence contracts/performance.md#efficient-algorithms Stage filtering, declared-input Sets and proof maps scale with plugin/input counts; merged paths are sorted with path-text comparison costs. Each stage can rehash/re-realpath declared inputs, serialize plugin/config records and parse complete output; discovery, native capability probes, source builds and child execution remain delegated costs of this call. The invocation snapshot adds full captured-population parsing and dirty document encoding/writes per native stage. No byte/work ceiling or measured dominant-cost ranking is asserted.
+ * @evidence contracts/performance.md#reuse-equivalent-work Descriptor/source discovery precedes snapshot allocation so invocation-private paths do not vary its environment cache identity. Source-plugin artifacts are shared by their owning loader; this transform intentionally produces a current generation and gives downstream consumers the graph, source states and host witnesses required to qualify reuse.
  *
- * @evidence contracts/performance.md#bound-retention-and-release-resources This router retains discovery records, per-stage proof maps and accumulated diagnostics/output until synchronous stage completion, then transfers the returned envelope. Native capture/observation owners attempt their own cleanup; suppressed cleanup failures and descendant release remain unconfirmed where those owners do not join them. Artifact-cache retention belongs to the builder, and no stage timeout or input/output byte ceiling is supplied here.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This router retains discovery records, per-stage proof maps and accumulated diagnostics/output until synchronous stage completion, then transfers the returned envelope. The invocation coordinator attempts identity-checked snapshot removal and propagates or aggregates removal failure. Other native capture/observation owners attempt their own cleanup; suppressed cleanup failures and descendant release remain unconfirmed where those owners do not join them. Artifact-cache retention belongs to the builder, and no stage timeout or input/output byte ceiling is supplied here.
  *
  * @evidence contracts/portability.md#os-neutral-implementation Native paths remain filesystem coordinates, child argv are arrays, and environment helpers preserve Windows key equivalence and explicit Node/tsgo/config anchors without shell parsing or native method patching.
  */
@@ -123,6 +124,16 @@ export function transformProjectInMemory(options: ITtscCompilerContext): {
     projectRoot: options.projectRoot,
     tsconfig: options.tsconfig,
   });
+  return CompilationSnapshot.run(options.env, (env) =>
+    transformWithSnapshot({ ...options, env }, loaded),
+  );
+}
+
+/** Run native checks and transformation after descriptor/source discovery. */
+function transformWithSnapshot(
+  options: ITtscCompilerContext,
+  loaded: ReturnType<typeof loadProjectPlugins>,
+): ReturnType<typeof transformProjectInMemory> {
   if (loaded.nativePlugins.length !== 0) {
     // Every step below runs binaries built from these sources, so the output
     // is a function of their state, which the envelope carries for a consumer
@@ -393,7 +404,11 @@ function transformProjectWithPlugins(
     );
     return {
       ...envelopeSideChannels(transformed),
-      graph: mergeCheckGraphs(checked.graph, transformed.graph),
+      graph: mergeTransformGraphs(
+        checked.graph,
+        transformed.graph,
+        checks.length,
+      ),
       ...observationLimitations(
         [loaded, checked, transformed],
         hostInputHashes,
@@ -476,7 +491,7 @@ function transformProjectWithPlugins(
   );
   return {
     ...envelopeSideChannels(output),
-    graph: mergeCheckGraphs(checked.graph, output.graph),
+    graph: mergeTransformGraphs(checked.graph, output.graph, checks.length),
     ...observationLimitations(
       [loaded, checked, output],
       hostInputHashes,
@@ -708,6 +723,7 @@ function runNativeChecks(
     stdout: "",
     stderr: "",
   };
+  let snapshotsComplete = true;
   for (const plugin of checks) {
     const checked = runNativeCheckWithObservations(plugin, (extraArgs) => {
       const res = spawnNative(
@@ -748,7 +764,12 @@ function runNativeChecks(
         project.root,
       );
     });
+    snapshotsComplete &&= checked.graph?.compilationSnapshot !== undefined;
     result = appendBuildOutput(result, checked);
+    if (!snapshotsComplete && result.graph?.compilationSnapshot !== undefined) {
+      const { compilationSnapshot: _snapshot, ...unqualified } = result.graph;
+      result.graph = unqualified;
+    }
     if (result.status !== 0) {
       return result;
     }
@@ -877,3 +898,23 @@ function nativePluginEnv(
   );
   return env;
 }
+
+/**
+ * A legacy check with no graph cannot certify the transform's shared input
+ * view.
+ */
+function mergeTransformGraphs(
+  checked: TtscBuildResult["graph"],
+  transformed: TtscBuildResult["graph"],
+  checks: number,
+): TtscBuildResult["graph"] {
+  const graph = mergeCheckGraphs(checked, transformed);
+  if (
+    graph === undefined ||
+    checks === 0 ||
+    checked?.compilationSnapshot !== undefined
+  )
+    return graph;
+  const { compilationSnapshot: _snapshot, ...unqualified } = graph;
+  return unqualified;
+}

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,

package/src/launcher/internal/runtime/installRuntimeHooks.ts

@@ -22,7 +22,9 @@ import { createCanonicalTempDirectory } from "../../../internal/createCanonicalT
 import { runtimeExecutableIdentity } from "../../../internal/runtimeExecutableIdentity";
 import { moduleResolutionBaseSelects } from "../../../plugin/internal/load/moduleResolutionBaseSelects";
 import { PluginContentIdentities } from "../../../plugin/internal/source/PluginContentIdentities";
+import { SourceBuildCacheLayout } from "../../../plugin/internal/source/SourceBuildCacheLayout";
 import { recordCacheFileUse } from "../../../plugin/internal/source/recordCacheFileUse";
+import { resolveSourceBuildCachePaths } from "../../../plugin/internal/source/resolveSourceBuildCachePaths";
 import { buildSingleRootProject } from "../buildSingleRootProject";
 import { inlineServedSourceMap } from "../inlineServedSourceMap";
 import { runtimeCompilerArgs } from "../runtimeCompilerArgs";
@@ -2192,6 +2194,15 @@ function buildDependency(
     fs.mkdirSync(emitDir, { recursive: true });
     const result = runBuild({
       cwd: project.root,
+      runtimeCacheDir:
+        process.env.TTSX_DISABLE_CACHE === "1" ||
+        process.env.TTSC_PLUGIN_DESCRIPTOR_LOAD === "1"
+          ? undefined
+          : path.join(
+              runtimeRecordStore()?.root ??
+                resolveSourceBuildCachePaths(project.root).root,
+              SourceBuildCacheLayout.RUNTIME_BUILD_CACHE_DIRNAME,
+            ),
       forceEmitProvenance: true,
       // Emit-only means diagnostics never withhold the emit, so a dependency's
       // own `noEmitOnError` is switched off: honoured, it would turn any

package/src/plugin/internal/load/loadProjectPlugins.ts

@@ -824,6 +824,7 @@ export namespace loadProjectPlugins {
                 ...record.capabilities,
                 compilerArgsCwd: true,
                 emitProvenance: true,
+                emitObservations: true,
               }
             : record.capabilities,
         config: record.config,

package/src/plugin/internal/source/SourceBuildCacheLayout.ts

@@ -80,6 +80,9 @@ export namespace SourceBuildCacheLayout {
   /** Directory of the lowered orphan sources inside the cache root. */
   export const ORPHAN_CACHE_DIRNAME = "ttsx-orphan";
 
+  /** Checksummed completed runtime project emits, independent of run lifetime. */
+  export const RUNTIME_BUILD_CACHE_DIRNAME = "runtime-builds";
+
   /**
    * The parts of the cache root whose entries are single files, each collected
    * by `pruneCacheFileRoot` and removed by `ttsc clean`.
@@ -90,6 +93,7 @@ export namespace SourceBuildCacheLayout {
     IDENTITY_CACHE_DIRNAME,
     ANSWER_CACHE_DIRNAME,
     ORPHAN_CACHE_DIRNAME,
+    RUNTIME_BUILD_CACHE_DIRNAME,
   ];
 
   /**

package/src/structures/ITtscCompilerTransformation.ts

@@ -51,6 +51,12 @@ export namespace ITtscCompilerTransformation {
    * @evidence contracts/portability.md#os-neutral-implementation Graph keys use the producer's cwd-relative slash spelling with absolute slash paths for outside-root or cross-volume inputs; this protocol spelling is distinct from reported native realpaths carried by inputRealpaths and observations, which can retain lexical fallback on native VFS errors. The reported compiler case policy governs compiler membership comparisons rather than an OS-name assumption; absent policy or proof does not establish native filesystem capabilities.
    */
   export interface IReferenceGraph {
+    /**
+     * Shared native read-once input view; current delivery authority, never
+     * disk freshness.
+     */
+    compilationSnapshot?: string;
+
     /**
      * Effective native possible-root suffixes and output-directory exclusions.
      * A report that differs from a host's provisional policy requires a new

package/src/structures/ITtscPluginCapabilities.ts

@@ -83,13 +83,25 @@ export interface ITtscPluginCapabilities {
    * from an output filename or configuration prediction.
    *
    * When omitted, ttsc does not pass the option to a strict third-party host. A
-   * runtime operation requiring verified emit provenance must then report that
-   * the selected host does not support it.
+   * runtime operation then uses the existing externally observed provenance
+   * adapter, whose incomplete proof remains visible to the runtime consumer.
    *
    * @default false
    */
   emitProvenance?: true;
 
+  /**
+   * Whether build accepts `--emit-observations-json=<absolute private path>`
+   * and publishes its generation's compiler and native input observations.
+   * Missing support keeps runtime emits fresh rather than assuming reusable
+   * input completeness. This protocol is independent of output ownership. Hosts
+   * publish the same observation envelope as checkObservations, including
+   * failures, before releasing their Program.
+   *
+   * @default false
+   */
+  emitObservations?: true;
+
   /**
    * Whether the sidecar accepts ttsc's `--project-context-json` identity
    * protocol. The payload keeps lexical selection paths, physical Program

package/utility/host.go

@@ -40,6 +40,9 @@ type hostOptions struct {
   // checkObservationsJSON is the caller-owned absolute check input result path.
   checkObservationsJSON string
 
+  // emitObservationsJSON is the caller-owned absolute build input result path.
+  emitObservationsJSON string
+
   // observationsIncomplete points to the resident host's committed generation
   // state. It is nil for non-resident calls and updated only after success.
   observationsIncomplete *bool
@@ -201,6 +204,10 @@ func RunBuild(args []string) int {
 // diagnostics. Analysis-only success writes an empty map. The original build
 // status remains authoritative; absent or invalid metadata supplies no ownership
 // proof. Callers own the artifact's removal.
+// A separately negotiated absolute emit-observations path receives this same
+// Program's compiler and native input witnesses before its checker lease closes,
+// including failing loaded builds. Unavailable optional observations withhold
+// reuse without changing the build status. They supply no authority by themselves.
 // Program.Close returns its checker lease; it does not remove emitted files or
 // private metadata. Summary and diagnostic stream writes are best-effort here,
 // so a zero status does not certify delivery to the supplied io.Writer values.
@@ -211,7 +218,7 @@ func RunBuild(args []string) int {
 // @evidence contracts/common.md#meaningful-documentation Native paragraphs identify stream ownership, failure statuses, private metadata admission and caller artifact removal following the documentation skill.
 // @evidence contracts/portability.md#os-neutral-implementation Driver loading and DefaultWriteFile own native paths and filesystem APIs; output streams are not replaced globally.
 // @evidence contracts/performance.md#efficient-algorithms Admission and loading include argument/plugin-manifest parsing, native project and diagnostic work. Emission dispatches linked AST transforms through the driver, which owns native generation and one authored-coordinate correction. The final writer indexes compiler carrier/map paths and shifts generated map coordinates only when it inserts missing preamble text, including JSON/base64/VLQ and output-byte work. Optional provenance adds output-path candidate collection, successful-write bookkeeping, source-proof checks, owner sorting and JSON/file publication; costs depend on source/graph, output and metadata bytes rather than only the number of emit calls.
-// @evidence contracts/performance.md#reuse-equivalent-work The same loaded compiler generation validates and emits; linked program hooks remain latched rather than independently reexecuted for output files.
+// @evidence contracts/performance.md#reuse-equivalent-work The same loaded compiler generation validates, emits and optionally publishes its input witnesses; linked program hooks remain latched rather than independently reexecuted for output files. Completed-generation reuse belongs to the caller.
 // @evidence contracts/performance.md#bound-retention-and-release-resources Successful loading transfers one Program checker lease to a deferred Close on analysis-only, normal and failure returns. The final writer retains output-path decisions and maps awaiting their carrier without a byte cap, releases pending map entries as their carrier arrives, and reports unfinished pairs at emit completion. Facade graphs, provenance maps, writer closures and serialization buffers lose local ownership when the invocation ends; Close does not destroy all program memory, supplied-stream state or emitted disk artifacts. Callers own stream lifetime and metadata/output removal, with no invocation-enforced byte cap.
 func RunBuildWithIO(args []string, stdout, stderr io.Writer) int {
   opts, ok := parseHostOptions("build", args, stdout, stderr)
@@ -224,6 +231,13 @@ func RunBuildWithIO(args []string, stdout, stderr io.Writer) int {
     return 2
   }
   defer prog.Close()
+  defer func() {
+    if opts.emitObservationsJSON != "" {
+      if err := driver.WriteCheckObservationsJSON(opts.emitObservationsJSON, prog); err != nil {
+        fmt.Fprintf(opts.stderr, "ttsc utility: emit observations write failed: %v\n", err)
+      }
+    }
+  }()
   driver.WritePrettyDiagnostics(opts.stderr, diags, opts.cwd)
   if opts.noEmit {
     if len(diags) != 0 {
@@ -446,8 +460,10 @@ func parseHostOptions(command string, args []string, stdout, stderr io.Writer) (
   tsgoArgsRaw := fs.String("tsgo-args", "", "JSON array of forwarded tsgo CLI flags")
   provenanceJSON := ""
   checkObservationsJSON := ""
+  emitObservationsJSON := ""
   if command == "build" {
     fs.StringVar(&provenanceJSON, "emit-provenance-json", "", "private absolute emit provenance result path")
+    fs.StringVar(&emitObservationsJSON, "emit-observations-json", "", "private absolute build input result path")
   }
   if command == "check" {
     fs.StringVar(&checkObservationsJSON, "check-observations-json", "", "private absolute check input result path")
@@ -463,6 +479,10 @@ func parseHostOptions(command string, args []string, stdout, stderr io.Writer) (
     fmt.Fprintln(stderr, "ttsc utility: check observations path must be absolute")
     return hostOptions{}, false
   }
+  if emitObservationsJSON != "" && !filepath.IsAbs(emitObservationsJSON) {
+    fmt.Fprintln(stderr, "ttsc utility: emit observations path must be absolute")
+    return hostOptions{}, false
+  }
   var tsgoArgs []string
   if *tsgoArgsRaw != "" {
     if err := json.Unmarshal([]byte(*tsgoArgsRaw), &tsgoArgs); err != nil {
@@ -507,6 +527,7 @@ func parseHostOptions(command string, args []string, stdout, stderr io.Writer) (
     stderr:                stderr,
     provenanceJSON:        provenanceJSON,
     checkObservationsJSON: checkObservationsJSON,
+    emitObservationsJSON:  emitObservationsJSON,
   }, true
 }