ttsc 0.34.3 → 0.36.0

package/lib/structures/ITtscPluginCapabilities.d.ts

@@ -79,12 +79,23 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ttsc",
-  "version": "0.34.3",
+  "version": "0.36.0",
   "description": "General-purpose TypeScript-Go compiler, runtime, plugin host, and LSP host.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -64,13 +64,13 @@
   },
   "optionalDependencies": {
     "fsevents": "^2.3.3",
-    "@ttsc/linux-x64": "0.34.3",
-    "@ttsc/linux-arm": "0.34.3",
-    "@ttsc/darwin-x64": "0.34.3",
-    "@ttsc/darwin-arm64": "0.34.3",
-    "@ttsc/win32-x64": "0.34.3",
-    "@ttsc/win32-arm64": "0.34.3",
-    "@ttsc/linux-arm64": "0.34.3"
+    "@ttsc/linux-x64": "0.36.0",
+    "@ttsc/linux-arm64": "0.36.0",
+    "@ttsc/linux-arm": "0.36.0",
+    "@ttsc/win32-x64": "0.36.0",
+    "@ttsc/darwin-x64": "0.36.0",
+    "@ttsc/darwin-arm64": "0.36.0",
+    "@ttsc/win32-arm64": "0.36.0"
   },
   "sideEffects": [
     "./lib/register.js",

package/src/compiler/internal/CompilationSnapshot.ts

@@ -0,0 +1,97 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { createCanonicalTempDirectory } from "../../internal/createCanonicalTempDirectory";
+import { SidecarEnvironment } from "./sharedHost/SidecarEnvironment";
+
+/**
+ * Own one read-once compiler view across sequential native stages. Its private
+ * document stores actual compiler text and lookup answers, including absence;
+ * each invocation starts empty and removes its storage after its final stage.
+ * Disk freshness remains a separate cache-admission decision.
+ *
+ * @evidence contracts/common.md#principled-implementation A unique invocation ID and versioned private document share first-read answers through the driver's supported VFS, without changing source paths or the selected compiler.
+ * @evidence contracts/common.md#clear-and-simple-design One synchronous owner brackets the sequential compiler operation and its transport cleanup.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The driver consumes real captured text; no filesystem methods or compiler internals are replaced.
+ * @evidence contracts/common.md#meaningful-documentation Prose states read-once semantics, sequential stage ownership, absence and independent freshness admission.
+ * @evidence contracts/portability.md#os-neutral-implementation Native temporary-directory creation and path APIs own transport; environment merging preserves Windows key semantics.
+ * @evidence contracts/performance.md#efficient-algorithms Construction writes an empty document; each native stage parses prior captured text/predicates and dirty flushes encode and write the complete reached population. Normal UTF-8 remains plain text, while invalid UTF-8 is encoded losslessly and decoded once per stage.
+ * @evidence contracts/performance.md#reuse-equivalent-work Only stages of this invocation share captured answers; unrelated invocations have fresh IDs and documents.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The synchronous owner attempts identity-checked cleanup after success or failure; native captured bytes have no population cap. A failed initial identity read or cleanup can leave storage behind; cleanup failure retains the original thrown error or completed result.
+ */
+export namespace CompilationSnapshot {
+  export const ENV = "TTSC_COMPILATION_SNAPSHOT";
+
+  /**
+   * Run sequential native stages with a new invocation-owned input document.
+   * The supplied environment is copied; same-directory identity guards cleanup,
+   * and cleanup failure retains the operation error or completed result.
+   *
+   * @evidence contracts/common.md#principled-implementation A unique invocation ID and versioned private document share first-read answers through the driver's supported VFS, without changing source paths or the selected compiler.
+   * @evidence contracts/common.md#clear-and-simple-design One synchronous owner brackets the sequential compiler operation and its transport cleanup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The driver consumes real captured text; no filesystem methods or compiler internals are replaced.
+   * @evidence contracts/common.md#meaningful-documentation Prose states read-once semantics, sequential stage ownership, absence and independent freshness admission.
+   * @evidence contracts/portability.md#os-neutral-implementation Native temporary-directory creation and path APIs own transport; environment merging preserves Windows key semantics.
+   * @evidence contracts/performance.md#efficient-algorithms Construction writes an empty document; each native stage parses prior captured text/predicates and dirty flushes encode and write the complete reached population. Normal UTF-8 remains plain text, while invalid UTF-8 is encoded losslessly and decoded once per stage.
+   * @evidence contracts/performance.md#reuse-equivalent-work Only stages of this invocation share captured answers; unrelated invocations have fresh IDs and documents.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The synchronous owner attempts identity-checked cleanup after success or failure; native captured bytes have no population cap. A failed initial identity read or cleanup can leave storage behind; cleanup failure retains the original thrown error or completed result.
+   */
+  export function run<T>(
+    environment: NodeJS.ProcessEnv | undefined,
+    operation: (environment: NodeJS.ProcessEnv) => T,
+  ): T {
+    const directory = createCanonicalTempDirectory("ttsc-input-snapshot-");
+    const ownership = fs.lstatSync(directory);
+    let completed: T | undefined;
+    let failed = false;
+    let failure: unknown;
+    try {
+      const file = path.join(directory, "inputs.json");
+      fs.writeFileSync(
+        file,
+        JSON.stringify({
+          version: 1,
+          id: crypto.randomUUID(),
+          reads: {},
+          files: {},
+          directories: {},
+          entries: {},
+          realpaths: {},
+          stats: {},
+        }),
+      );
+      const env = SidecarEnvironment.merge(environment, { [ENV]: file });
+      completed = operation(env);
+      return completed;
+    } catch (error) {
+      failed = true;
+      failure = error;
+      throw error;
+    } finally {
+      try {
+        const current = fs.lstatSync(directory);
+        if (
+          !current.isDirectory() ||
+          current.isSymbolicLink() ||
+          current.dev !== ownership.dev ||
+          current.ino !== ownership.ino
+        )
+          throw new Error("Compilation snapshot directory ownership changed");
+        fs.rmSync(directory, { recursive: true });
+      } catch (error) {
+        if (failed)
+          throw new AggregateError(
+            [failure, error],
+            "Compilation snapshot and cleanup failed",
+            { cause: failure },
+          );
+        throw new AggregateError(
+          [completed, error],
+          "Compilation completed but snapshot cleanup failed",
+          { cause: completed },
+        );
+      }
+    }
+  }
+}

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

@@ -13,6 +13,8 @@ import type { TtscBuildOptions } from "../../../structures/internal/TtscBuildOpt
 import type { TtscBuildResult } from "../../../structures/internal/TtscBuildResult";
 import type { TtscCommonOptions } from "../../../structures/internal/TtscCommonOptions";
 import type { TtscPluginSourceInputsHandler } from "../../../structures/internal/TtscSingleFileEmitOptions";
+import { CompilationSnapshot } from "../CompilationSnapshot";
+import { compileProjectInMemory } from "../compileProjectInMemory";
 import { outputText } from "../outputText";
 import { CompilerProjectSelection } from "../project/CompilerProjectSelection";
 import { readProjectConfig } from "../project/readProjectConfig";
@@ -226,6 +228,11 @@ export namespace BuildExecution {
       clearInheritedTsgoArgs(env, extra);
     }
     clearInheritedSemanticConfigPath(env, extra);
+    SidecarEnvironment.write(
+      env,
+      CompilationSnapshot.ENV,
+      SidecarEnvironment.read(extra, CompilationSnapshot.ENV),
+    );
     // The anchor is per-invocation state owned by this host: when this run
     // declared none (and the caller's env does not name one), drop any value
     // inherited from an ancestor ttsc process so a nested build never
@@ -363,22 +370,45 @@ export namespace BuildExecution {
    * opted-in native host reports its captured generation, while the direct
    * compiler adapter admits only a stable observed selection and supported
    * output layout. Unknown ownership remains explicit for consumers rather than
-   * guessed.
+   * guessed. Native runtime stages share one invocation-owned read-once view;
+   * configured checks followed by the exact installed compiler emit through its
+   * matching native target, while custom compiler executables remain
+   * delegated.
    *
    * @evidence contracts/common.md#principled-implementation Ordered checks block emit on failure and retain negotiated same-generation input observations for the actual check verb; effectful fix/format results keep their distinct command contract without fabricated reusable check metadata; transforms use one compatible host. Normally completed native partial emission and supported stable external emission can retain actual-write provenance alongside unchanged nonzero status, while interrupted or unknown generations establish no proof.
    * @evidence contracts/common.md#clear-and-simple-design This dispatcher owns phase policy while argv, spawning, normalization and fallback comparison remain shared helpers used by one-shot and watch lanes.
    * @evidence contracts/common.md#prohibited-implementation-shortcuts Format bypass follows its write-only contract; capability-based diagnostics/provenance and failure fallback preserve supported producer semantics without plugin-name shortcuts, foreign mutation or filename-based ownership guesses.
    * @evidence contracts/common.md#meaningful-documentation Native prose states ordering, format effects and thrown boundary failures; branch comments explain nonobvious emission and display policies.
    * @evidence contracts/portability.md#os-neutral-implementation Commands preserve native executable/argv/cwd boundaries; provenance uses a canonical unique temporary directory and absolute native wire paths without post-compile realpath reconstruction or OS-derived case folding.
-   * @evidence contracts/performance.md#efficient-algorithms Plugin/stage selection scans the configured population; each command includes argv/env publication and native runtime probes under its helpers. Required proof adds artifact or external inspection/JSON/source-executable observation work, plus association/path processing. Accumulating phase reports can recopy earlier bytes; there is no supplied bound on total reports, proof bytes or child duration.
-   * @evidence contracts/performance.md#reuse-equivalent-work A check host declaring TypeScript diagnostics avoids an equivalent extra successful check, while compatible transform plugins share one host; effectful configured checks still execute in order.
-   * @evidence contracts/performance.md#bound-retention-and-release-resources Phase results and command/proof records stay build-local and returned data transfer to the caller, with uncapped report/association bytes. Native proof setup observes ownership before finally, so setup failure can leave allocation unclaimed; accepted artifacts reach identity-checked cleanup attempts. Replaced parents remain untouched. Cleanup aggregates an earlier throw or nonzero result; other cleanup errors propagate without certifying release. Delegated capture/descendant release remains with its owner; no resident history is retained here.
+   * @evidence contracts/performance.md#efficient-algorithms Plugin/stage selection scans the configured population; each command includes argv/env publication and native runtime probes under its helpers. Required proof adds artifact or external inspection/JSON/source-executable observation work, plus association/path processing. Native runtime snapshot stages parse the preceding full document and dirty stages serialize/write its complete captured population. Accumulating phase reports can recopy earlier bytes; there is no supplied bound on total reports, proof bytes or child duration.
+   * @evidence contracts/performance.md#reuse-equivalent-work A check host declaring TypeScript diagnostics avoids an equivalent extra successful check, while compatible transform plugins share one host; effectful configured checks still execute in order. Captured answers are shared only across the sequential native stages of this invocation, independently of later cache admission.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Phase results and command/proof records stay build-local and returned data transfer to the caller, with uncapped report/association bytes. Native proof setup observes ownership before finally, so setup failure can leave allocation unclaimed; accepted artifacts reach identity-checked cleanup attempts. Replaced parents remain untouched. Cleanup aggregates an earlier throw or nonzero result; other cleanup errors propagate without certifying release. The snapshot coordinator attempts identity-checked transport cleanup and retains an original error or completed result when cleanup fails. Captured text and full document buffers follow reached input bytes without a cap. Delegated capture/descendant release remains with its owner; no resident history is retained here.
    */
   export function runPreparedBuild(
     options: RunBuildOptions,
     timing: BuildTiming.BuildTiming,
     execution: ReturnType<typeof resolveExecutionContext>,
     buildOptions: RunBuildOptions,
+  ): TtscBuildResult {
+    if (
+      buildOptions.forceEmitProvenance === true &&
+      execution.nativePlugins.length !== 0
+    )
+      return CompilationSnapshot.run(buildOptions.env, (env) =>
+        runPreparedSnapshotBuild(options, timing, execution, {
+          ...buildOptions,
+          env,
+        }),
+      );
+    return runPreparedSnapshotBuild(options, timing, execution, buildOptions);
+  }
+
+  /** Execute one already selected build without replacing compiler authority. */
+  function runPreparedSnapshotBuild(
+    options: RunBuildOptions,
+    timing: BuildTiming.BuildTiming,
+    execution: ReturnType<typeof resolveExecutionContext>,
+    buildOptions: RunBuildOptions,
   ): TtscBuildResult {
     if (execution.compilerSelection.inspectionError !== undefined) {
       const diagnosed = runTsgo(execution, [], buildOptions);
@@ -463,6 +493,14 @@ export namespace BuildExecution {
             execution,
           );
         }
+      } else if (
+        buildOptions.forceEmitProvenance === true &&
+        isProjectCompiler(execution, buildOptions)
+      ) {
+        result = appendBuildOutput(
+          checked,
+          runSnapshotCompilerBuild(execution, buildOptions),
+        );
       } else {
         if (
           buildOptions.skipDiagnosticsCheck !== true &&
@@ -728,20 +766,33 @@ export namespace BuildExecution {
   ): TtscBuildResult {
     const host = selectSharedHostPlugin(plugins);
     const run = (provenancePath?: string): TtscBuildResult =>
-      runNativePluginCommand(
-        host,
-        NativePluginArguments.createNativeBuildArgs(
-          execution,
-          options,
-          plugins,
-          provenancePath,
-        ),
-        options,
-        execution,
-        "ttsc.build",
-        timing,
-        NativePluginArguments.transformHostTimingLabel(plugins),
-        TsgoArguments.createNativeBuildTsgoArgs(execution, options),
+      runNativeCheckWithObservations(
+        {
+          capabilities:
+            options.runtimeCacheDir === undefined
+              ? undefined
+              : host.capabilities,
+        },
+        (observationArgs) =>
+          runNativePluginCommand(
+            host,
+            [
+              ...NativePluginArguments.createNativeBuildArgs(
+                execution,
+                options,
+                plugins,
+                provenancePath,
+              ),
+              ...observationArgs,
+            ],
+            options,
+            execution,
+            "ttsc.build",
+            timing,
+            NativePluginArguments.transformHostTimingLabel(plugins),
+            TsgoArguments.createNativeBuildTsgoArgs(execution, options),
+          ),
+        "build",
       );
     if (options.forceEmitProvenance !== true) return run();
     if (host.capabilities?.emitProvenance === true)
@@ -966,6 +1017,60 @@ export namespace BuildExecution {
     );
   }
 
+  /**
+   * Preserve custom compiler executables while recognizing the project's exact
+   * compiler.
+   */
+  function isProjectCompiler(
+    execution: ReturnType<typeof resolveExecutionContext>,
+    options: RunBuildOptions,
+  ): boolean {
+    if (execution.tsgo.version !== "custom") return true;
+    try {
+      const env = SidecarEnvironment.merge(process.env, options.env, {
+        TTSC_TSGO_BINARY: undefined,
+      });
+      const installed = resolveTsgo({ cwd: execution.projectRoot, env });
+      return (
+        fs.realpathSync.native(installed.binary) ===
+        fs.realpathSync.native(execution.tsgo.binary)
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  /** Emit through the selected upstream target's native VFS after native checks. */
+  function runSnapshotCompilerBuild(
+    execution: ReturnType<typeof resolveExecutionContext>,
+    options: RunBuildOptions,
+  ): TtscBuildResult {
+    const forwarded = TsgoArguments.createNativeBuildTsgoArgs(
+      execution,
+      options,
+    );
+    const env = SidecarEnvironment.merge(options.env, {
+      [TSGO_ARGS_ENV]: JSON.stringify(forwarded),
+      [TSGO_ARGS_CWD_ENV]: execution.compilerSelection.compilerArgsCwd,
+    });
+    const compiled = compileProjectInMemory({
+      cwd: execution.projectRoot,
+      projectRoot: execution.projectRoot,
+      tsconfig: execution.tsconfig,
+      env,
+      plugins: [],
+      cacheDir: options.cacheDir,
+    });
+    const emittedFiles: string[] = [];
+    for (const [name, text] of Object.entries(compiled.output)) {
+      const output = path.resolve(execution.projectRoot, name);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.writeFileSync(output, text);
+      emittedFiles.push(output);
+    }
+    return { ...compiled.result, emittedFiles };
+  }
+
   /**
    * Run `tsgo` with the full emit arguments and parse `TSFILE:` lines from
    * stdout into `emittedFiles`. Internally requested TSFILE lines are stripped;
@@ -1365,6 +1470,7 @@ export namespace BuildExecution {
     });
     let pluginSetupFailure: TtscBuildResult | undefined;
     let nativePlugins: ITtscLoadedNativePlugin[] = [];
+    let pluginLoad: ReturnType<typeof loadProjectPlugins> | undefined;
     // Opened only for an invocation that loads plugins, so a project without
     // any never gains a cache directory; the load and every later native spawn
     // of this invocation prove their unchanged inputs through it (#1722, #1723).
@@ -1387,7 +1493,7 @@ export namespace BuildExecution {
           cacheDir,
           env,
         });
-        nativePlugins = (yield* loadProjectPlugins.steps({
+        pluginLoad = yield* loadProjectPlugins.steps({
           binary: resolveBinary({ env }) ?? "",
           cacheDir,
           cwd,
@@ -1398,7 +1504,8 @@ export namespace BuildExecution {
           pluginConfigDir: options.pluginConfigDir,
           projectRoot,
           tsconfig,
-        })).nativePlugins;
+        });
+        nativePlugins = pluginLoad.nativePlugins;
       } else {
         yield options.onWatchInputs?.([]);
       }
@@ -1415,6 +1522,7 @@ export namespace BuildExecution {
       cwd,
       ...(identities === undefined ? {} : { identities }),
       nativePlugins,
+      ...(pluginLoad === undefined ? {} : { pluginLoad }),
       pluginConfigDir: resolvePluginConfigDir({
         cwd,
         pluginConfigDir: options.pluginConfigDir,

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

@@ -20,6 +20,9 @@ import type {
  * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
  */
 export type RunBuildOptions = TtscBuildOptions & {
+  /** Persistent private-runtime emit documents; absence keeps ordinary builds. */
+  runtimeCacheDir?: string;
+
   /**
    * Skip the independent direct-compiler type-check gate and the added
    * `--noEmitOnError` guard. Configured plugin checks and native hosts still

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

@@ -0,0 +1,252 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { E2ETrace } from "../../../internal/E2ETrace";
+import { recordCacheFileUse } from "../../../plugin/internal/source/recordCacheFileUse";
+import type { TtscBuildResult } from "../../../structures/internal/TtscBuildResult";
+
+/**
+ * Persist completed private runtime emits as checksummed, atomically published
+ * documents. Readers copy admitted bytes into their own run directory, so cache
+ * collection and concurrent publications cannot remove an executing run's emit.
+ * Input discovery and producer-proof admission belong to the supplied owners.
+ *
+ * @evidence contracts/common.md#principled-implementation Content-addressed snapshots select complete checksummed result and output documents. SHA-256 consumes exact UTF-8 text; native normalization rejects absolute, dot, parent and Windows drive-relative output coordinates. Relocation changes producer output coordinates and private-root stream text while retaining source paths.
+ * @evidence contracts/common.md#clear-and-simple-design One operation coordinates lookup, proof, restore and publication, with private hashing, containment and relocation helpers. Input capture and producer validation remain separate callbacks.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Misses execute the original build exactly once; failed or absent proofs never manufacture successful output. Every transported output must be a normalized private descendant, without filename or consumer-name exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes persistent storage, run-owned copies and proof ownership; run states callback stability and failure behavior, and private helper comments identify byte, path and relocation domains.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths, lstat, relative/join and rename own storage and containment, including Windows drive-relative rejection. Source coordinates remain unchanged; transported symlinks are refused rather than followed.
+ * @evidence contracts/performance.md#efficient-algorithms Lookup hashes snapshot text and reads/hashes the bounded document. Restore and publication scale with output bytes and file count, without unrelated source traversal; normalization scans path bytes and relocation scans output paths and stream text.
+ * @evidence contracts/performance.md#reuse-equivalent-work Equal snapshots reuse completed emits only after independent producer admission and unchanged recapture. A restored run owns its copied bytes and rebased output ledger; concurrent publishers may duplicate compilation but cannot expose partial documents.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Documents are capped at 128 MiB, with fresh output collection limited to a 0.7 raw-byte budget before encoding, and join the existing collected single-file cache population. Snapshots and decoded bytes are invocation-owned; staging removal is attempted in finally and run owners release output. Cleanup or collector failures can retain files; helpers retain no handles or history.
+ */
+export namespace RuntimeBuildCache {
+  const FORMAT = "ttsx-runtime-build-v1";
+  const MAX_BYTES = 128 * 1024 * 1024;
+
+  /**
+   * Reuse a proven private emit, or invoke the original producer once. Capture
+   * returns a deterministic complete input snapshot, or undefined to decline
+   * caching. Admission must validate the producer's extra input observations;
+   * the second argument is the output root that producer actually used. Cache
+   * IO or cache-admission failure costs reuse only. Errors thrown by the
+   * original build retain their normal failure policy.
+   *
+   * @evidence contracts/common.md#principled-implementation Lookup and publication bracket current input snapshots, preserve the actual producer result and require explicit extra-input admission; cache-hit output is copied before the result is rebased.
+   * @evidence contracts/common.md#clear-and-simple-design Snapshot, proof and build callbacks expose their independent responsibilities while the operation alone owns storage and restore cleanup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only successful complete emits are published; malformed, oversized, damaged or unproved documents fall through to the caller's real producer without changing compiler selection.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states complete-snapshot meaning, producer-root coordinates, callback error policy and recoverable cache IO.
+   * @evidence contracts/portability.md#os-neutral-implementation Native lstat refuses aliases, path.relative checks containment and native mkdir/write/rename preserve byte payloads and host path semantics.
+   * @evidence contracts/performance.md#efficient-algorithms Snapshot owners dominate input work; document read/parse/hash and base64 restore scale with bounded encoded bytes, while publication walks only private output and serializes it once.
+   * @evidence contracts/performance.md#reuse-equivalent-work A format-and-snapshot digest names one candidate; checksum, output grammar, producer admission and unchanged recapture are independent reuse gates. Every miss calls build once.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Call-local decoded outputs and serialized documents are bounded by the 128 MiB admission ceiling, except fresh output collection precedes serialization; partial restores are unlinked and staging removal is attempted in finally. Collector failures can retain files under the existing cache policy.
+   */
+  export function run(props: {
+    /** Collected single-file cache root, or undefined to bypass persistence. */
+    directory?: string;
+    /** Empty private output directory owned by this build's caller. */
+    emitDir: string;
+    /** Fresh complete input snapshot; undefined preserves ordinary execution. */
+    capture: () => string | undefined;
+    /** Producer-specific proof, with its original private output root. */
+    admit: (result: TtscBuildResult, emitDir: string) => boolean;
+    /** Original build operation, including its diagnostic policy. */
+    build: () => TtscBuildResult;
+  }): TtscBuildResult {
+    if (props.directory === undefined) return props.build();
+    let snapshot: string | undefined;
+    try {
+      snapshot = props.capture();
+    } catch {
+      /* An unavailable proof is a miss. */
+    }
+    if (snapshot === undefined) return props.build();
+    const key = digest(FORMAT + "\0" + snapshot);
+    const file = path.join(props.directory, key + ".json");
+    const restored: string[] = [];
+    try {
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_BYTES)
+        throw new Error("unusable runtime cache document");
+      const document = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (
+        document.format !== FORMAT ||
+        typeof document.payload !== "string" ||
+        document.hash !== digest(document.payload)
+      )
+        throw new Error("invalid runtime cache checksum");
+      const entry = JSON.parse(document.payload);
+      if (
+        entry.snapshot !== snapshot ||
+        typeof entry.emitDir !== "string" ||
+        !path.isAbsolute(entry.emitDir) ||
+        entry.result?.status !== 0 ||
+        !Array.isArray(entry.outputs) ||
+        !props.admit(entry.result, entry.emitDir)
+      )
+        throw new Error("unproved runtime cache document");
+      const names = new Set<string>();
+      for (const output of entry.outputs) {
+        if (
+          !Array.isArray(output) ||
+          output.length !== 2 ||
+          typeof output[0] !== "string" ||
+          typeof output[1] !== "string" ||
+          !safeRelative(output[0]) ||
+          names.has(output[0]) ||
+          Buffer.from(output[1], "base64").toString("base64") !== output[1]
+        )
+          throw new Error("invalid runtime cache output");
+        names.add(output[0]);
+      }
+      for (const output of Object.keys(entry.result.emittedSources ?? {}))
+        if (!names.has(path.relative(entry.emitDir, output)))
+          throw new Error("missing runtime cache provenance output");
+      for (const [name, bytes] of entry.outputs) {
+        const target = path.join(props.emitDir, name);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, Buffer.from(bytes, "base64"), { flag: "wx" });
+        restored.push(target);
+      }
+      if (
+        props.capture() !== snapshot ||
+        !props.admit(entry.result, entry.emitDir)
+      )
+        throw new Error("runtime inputs moved during restore");
+      recordCacheFileUse(file);
+      E2ETrace.capabilityResolution("runtime-build-cache", {
+        outcome: "reused",
+        key,
+      });
+      return relocate(entry.result, entry.emitDir, props.emitDir);
+    } catch {
+      for (const output of restored)
+        try {
+          fs.unlinkSync(output);
+        } catch {
+          /* Rejected cache output cannot prevent the ordinary producer. */
+        }
+    }
+    const result = props.build();
+    if (result.status !== 0) return result;
+    let temporary: string | undefined;
+    try {
+      const outputs: [string, string][] = [];
+      let outputBytes = 0;
+      const pending = [props.emitDir];
+      while (pending.length !== 0) {
+        const directory = pending.pop()!;
+        for (const child of fs.readdirSync(directory, {
+          withFileTypes: true,
+        })) {
+          const target = path.join(directory, child.name);
+          if (child.isSymbolicLink()) throw new Error("aliased runtime output");
+          if (child.isDirectory()) pending.push(target);
+          else if (child.isFile()) {
+            outputBytes += fs.statSync(target).size;
+            if (outputBytes > MAX_BYTES * 0.7) return result;
+            outputs.push([
+              path.relative(props.emitDir, target),
+              fs.readFileSync(target).toString("base64"),
+            ]);
+          } else throw new Error("nonordinary runtime output");
+        }
+      }
+      if (outputs.length === 0) return result;
+      const payload = JSON.stringify({
+        snapshot,
+        emitDir: props.emitDir,
+        result,
+        outputs,
+      });
+      const text = JSON.stringify({
+        format: FORMAT,
+        hash: digest(payload),
+        payload,
+      });
+      if (Buffer.byteLength(text) > MAX_BYTES) return result;
+      if (props.capture() !== snapshot || !props.admit(result, props.emitDir))
+        return result;
+      fs.mkdirSync(props.directory, { recursive: true });
+      if (fs.lstatSync(props.directory).isSymbolicLink()) return result;
+      temporary = path.join(
+        props.directory,
+        `${key}.${crypto.randomUUID()}.tmp`,
+      );
+      fs.writeFileSync(temporary, text, { flag: "wx" });
+      fs.renameSync(temporary, file);
+      E2ETrace.capabilityResolution("runtime-build-cache", {
+        outcome: "recorded",
+        key,
+      });
+    } catch {
+      /* Persistence never replaces a fresh successful result. */
+    } finally {
+      if (temporary !== undefined) {
+        try {
+          fs.unlinkSync(temporary);
+        } catch {
+          /* Rename or later collection owns it. */
+        }
+      }
+    }
+    return result;
+  }
+
+  /** Hash encoded input or document bytes with SHA-256. */
+  function digest(text: string): string {
+    return crypto.createHash("sha256").update(text).digest("hex");
+  }
+
+  /** Admit only a nonempty relative descendant coordinate. */
+  function safeRelative(name: string): boolean {
+    return (
+      name.length !== 0 &&
+      !name.includes("\0") &&
+      !path.isAbsolute(name) &&
+      path.parse(name).root === "" &&
+      path.normalize(name) === name &&
+      name !== "." &&
+      name !== ".." &&
+      !name.startsWith(".." + path.sep)
+    );
+  }
+
+  /** Move producer-owned output coordinates to the current private run. */
+  function relocate(
+    result: TtscBuildResult,
+    previous: string,
+    current: string,
+  ): TtscBuildResult {
+    const move = (output: string): string => {
+      const relative = path.relative(previous, output);
+      if (!safeRelative(relative))
+        throw new Error("runtime provenance escapes its output root");
+      return path.join(current, relative);
+    };
+    return {
+      ...result,
+      emittedFiles: result.emittedFiles?.map(move),
+      emittedSources:
+        result.emittedSources === undefined
+          ? undefined
+          : Object.fromEntries(
+              Object.entries(result.emittedSources).map(([output, sources]) => [
+                move(output),
+                sources,
+              ]),
+            ),
+      emittedSourceProofFailures:
+        result.emittedSourceProofFailures === undefined
+          ? undefined
+          : Object.fromEntries(
+              Object.entries(result.emittedSourceProofFailures).map(
+                ([output, reason]) => [move(output), reason],
+              ),
+            ),
+      stdout: result.stdout.split(previous).join(current),
+      stderr: result.stderr.split(previous).join(current),
+    };
+  }
+}