ttsc 0.34.3 → 0.35.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.35.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.35.0",
+    "@ttsc/linux-arm64": "0.35.0",
+    "@ttsc/darwin-x64": "0.35.0",
+    "@ttsc/linux-arm": "0.35.0",
+    "@ttsc/darwin-arm64": "0.35.0",
+    "@ttsc/win32-x64": "0.35.0",
+    "@ttsc/win32-arm64": "0.35.0"
   },
   "sideEffects": [
     "./lib/register.js",

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

@@ -728,20 +728,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)
@@ -1365,6 +1378,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 +1401,7 @@ export namespace BuildExecution {
           cacheDir,
           env,
         });
-        nativePlugins = (yield* loadProjectPlugins.steps({
+        pluginLoad = yield* loadProjectPlugins.steps({
           binary: resolveBinary({ env }) ?? "",
           cacheDir,
           cwd,
@@ -1398,7 +1412,8 @@ export namespace BuildExecution {
           pluginConfigDir: options.pluginConfigDir,
           projectRoot,
           tsconfig,
-        })).nativePlugins;
+        });
+        nativePlugins = pluginLoad.nativePlugins;
       } else {
         yield options.onWatchInputs?.([]);
       }
@@ -1415,6 +1430,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),
+    };
+  }
+}