ttsc 0.30.4 → 0.31.0

package/src/plugin/internal/capabilityPluginWorker.ts

@@ -0,0 +1,216 @@
+import type { SpawnSyncOptions, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parentPort } from "node:worker_threads";
+
+import { SidecarEnvironment } from "../../compiler/internal/sharedHost/SidecarEnvironment";
+import { E2ETrace } from "../../internal/E2ETrace";
+import { OwnedSynchronousProcess } from "../../internal/OwnedSynchronousProcess";
+import { SourceNativeRetirement } from "../../internal/SourceNativeRetirement";
+import { restoreCompilerError } from "../../internal/restoreCompilerError";
+import { serializeCompilerError } from "../../internal/serializeCompilerError";
+import type { ITtscCapabilityPluginResolution } from "../ITtscCapabilityPlugin";
+import { resolveCapabilityPluginResolution } from "../resolveCapabilityPlugins";
+import { decodeCapabilityCommandReply } from "./decodeCapabilityCommandReply";
+
+/**
+ * Keep original capability proof closures on their synchronous SDK thread. Each
+ * task's native commands rendezvous with the parent process owner, while shared
+ * cancellation wakes payload sleeps and rejects only after cleanup.
+ */
+const proofs = new Map<number, ITtscCapabilityPluginResolution>();
+let nextHandle = 0;
+let queue = Promise.resolve();
+parentPort?.on("message", (request: Request) => {
+  if (request.kind === "discard") {
+    proofs.delete(request.handle!);
+    return;
+  }
+  queue = queue
+    .then(() => handle(request))
+    .catch((error: unknown) => {
+      // An unrecoverable protocol write must retire this owner, rather than leave
+      // a live thread whose queue can never produce another terminal reply.
+      parentPort!.close();
+      throw error;
+    });
+});
+
+async function handle(request: Request): Promise<void> {
+  if (request.kind === "close") {
+    proofs.clear();
+    parentPort!.close();
+    return;
+  }
+  const retirements = new Set<Promise<unknown>>();
+  const ownershipFailures: unknown[] = [];
+  let value: unknown;
+  let thrown: unknown;
+  let createdHandle: number | undefined;
+  try {
+    adoptEnvironment(request.env);
+    const scope = SourceNativeRetirement.createScope(
+      `${request.directory}:${request.id}`,
+    );
+    value = SourceNativeRetirement.run(scope, () =>
+      OwnedSynchronousProcess.run(
+        {
+          cancel: request.cancel,
+          retirements,
+          failures: ownershipFailures,
+          launch: (command, args, options) =>
+            commandRelay(request, command, args, options),
+        },
+        () => {
+          if (request.kind === "resolve") {
+            const result = resolveCapabilityPluginResolution(request.options!);
+            OwnedSynchronousProcess.checkpoint();
+            const handle = ++nextHandle;
+            createdHandle = handle;
+            proofs.set(handle, result);
+            return { handle, status: result.status, plugins: result.plugins };
+          }
+          if (request.kind === "release") {
+            proofs.delete(request.handle!);
+            return undefined;
+          }
+          return proofs.get(request.handle!)?.isCurrent() ?? false;
+        },
+      ),
+    );
+  } catch (error) {
+    thrown = error;
+  }
+  const released = await Promise.allSettled(retirements);
+  const failures = [
+    ...ownershipFailures,
+    ...released.flatMap((result) =>
+      result.status === "rejected" ? [result.reason] : [],
+    ),
+  ];
+  if (failures.length > 0)
+    thrown = new AggregateError(
+      [...(thrown === undefined ? [] : [thrown]), ...failures],
+      "ttsc: resolver background cleanup failed",
+    );
+  if (
+    Atomics.load(new Int32Array(request.cancel), 0) !== 0 &&
+    thrown === undefined
+  )
+    thrown = new DOMException("ttsc: operation cancelled", "AbortError");
+  if (thrown !== undefined && createdHandle !== undefined)
+    proofs.delete(createdHandle);
+  // The general compiler serializer intentionally does not invoke accessors.
+  // DOMException exposes name/message through accessors, so transport this
+  // worker-owned cancellation as explicit Error data, not an accessor marker.
+  if (thrown instanceof DOMException && thrown.name === "AbortError")
+    thrown = Object.assign(new Error(thrown.message), { name: "AbortError" });
+  parentPort!.postMessage({
+    kind: "reply",
+    id: request.id,
+    ...(thrown === undefined
+      ? { value }
+      : {
+          thrown: serializeCompilerError(thrown),
+          ownershipFailed: failures.length > 0,
+        }),
+  });
+}
+
+function commandRelay(
+  request: Request,
+  command: string,
+  args: readonly string[],
+  options: SpawnSyncOptions,
+): ReturnType<typeof spawnSync> {
+  const done = new SharedArrayBuffer(4);
+  const responseFile = path.join(
+    request.directory,
+    `command-${++nextCommand}.bin`,
+  );
+  const boundary = `${request.id}:${nextCommand}`;
+  SourceNativeRetirement.begin(boundary);
+  let certified = false;
+  try {
+    parentPort!.postMessage({
+      kind: "command",
+      id: request.id,
+      command,
+      args,
+      options: {
+        ...options,
+        ...(options.cwd instanceof URL
+          ? { cwd: fileURLToPath(options.cwd) }
+          : {}),
+      },
+      done,
+      responseFile,
+    });
+    E2ETrace.capabilityResolution("command-relay-queued", {
+      request: request.id,
+      boundary,
+      responseFile,
+    });
+    const state = new Int32Array(done);
+    while (Atomics.load(state, 0) === 0) Atomics.wait(state, 0, 0);
+    const response = decodeCapabilityCommandReply(
+      fs.readFileSync(responseFile),
+    );
+    if (
+      response.retirement !== "joined" &&
+      response.retirement !== "not-started"
+    )
+      throw new Error("ttsc: native relay did not certify retirement", {
+        cause: response.thrown,
+      });
+    SourceNativeRetirement.settle(boundary, response.retirement);
+    certified = true;
+    fs.rmSync(responseFile, { force: true });
+    if (response.thrown !== undefined) {
+      const failure = restoreCompilerError(response.thrown);
+      if (failure.name !== "AbortError")
+        OwnedSynchronousProcess.reportFailure(failure);
+      throw failure;
+    }
+    if (response.result === undefined)
+      throw new Error("ttsc: native relay omitted its result");
+    if (response.result.error !== undefined)
+      response.result.error = restoreCompilerError(response.result.error);
+    return response.result;
+  } catch (error) {
+    // This is idempotent after a certified settlement; a broken exchange has
+    // no authority to release registered source and cache inputs.
+    if (!certified) {
+      // Existing discovery intentionally catches incompatible runtime probes.
+      // It cannot downgrade a lost native lifetime proof to a usable answer.
+      OwnedSynchronousProcess.reportFailure(error);
+      try {
+        SourceNativeRetirement.settle(boundary, "unknown", String(error));
+      } catch (failure) {
+        OwnedSynchronousProcess.reportFailure(failure);
+        throw new AggregateError(
+          [error, failure],
+          "ttsc: native retirement protection failed",
+        );
+      }
+    }
+    throw error;
+  }
+}
+
+function adoptEnvironment(env: NodeJS.ProcessEnv): void {
+  SidecarEnvironment.replace(process.env, env);
+}
+
+interface Request {
+  kind: "resolve" | "current" | "release" | "close" | "discard";
+  id: number;
+  handle?: number;
+  options?: { capability: string; cwd?: string; tsconfig?: string };
+  cancel: SharedArrayBuffer;
+  directory: string;
+  env: NodeJS.ProcessEnv;
+}
+
+let nextCommand = 0;

package/src/plugin/internal/decodeCapabilityCommandReply.ts

@@ -0,0 +1,27 @@
+import type { spawnSync } from "node:child_process";
+import { deserialize } from "node:v8";
+
+/**
+ * Decode one same-runtime command relay reply without interpreting user data.
+ *
+ * Parent and worker share one Node version and exchange disposable V8-encoded
+ * bytes. Native Buffers, sparse arrays and enumerable diagnostic data retain
+ * their values without JSON conversion or an ambiguous Buffer marker reviver.
+ * Invalid bytes throw; this decoder grants no native retirement authority.
+ *
+ * @evidence contracts/common.md#principled-implementation Node's structured serialization reconstructs actual byte buffers and the compiler serializer's data graph without treating user metadata as control markers. The private parent and worker use the same Node runtime, so this is not a cross-version persistent artifact contract.
+ * @evidence contracts/common.md#clear-and-simple-design One supported binary decoding operation returns the existing reply envelope; compiler-error restoration and native retirement classification stay with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Structured transport replaces JSON's data loss instead of layering marker guesses or permitting lost fields; malformed bytes remain errors rather than becoming successful commands.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies same-runtime disposable bytes, retained values, decoding failure and the absence of retirement authority.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Node's V8 transport represents data only; this decoder queries no native process or filesystem and introduces no OS-name policy.
+ * @evidence contracts/performance.md#efficient-algorithms One delegated deserialization processes the actual encoded graph and byte buffers; no independent recursive scan or marker conversion follows it here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each command reply contains independent observed outputs and is decoded independently.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Parsed data and decoded buffers transfer to the caller; temporary parse state has no global history or native handle.
+ */
+export function decodeCapabilityCommandReply(bytes: Uint8Array): {
+  retirement?: "joined" | "not-started" | "unknown";
+  result?: ReturnType<typeof spawnSync>;
+  thrown?: unknown;
+} {
+  return deserialize(bytes);
+}

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

@@ -0,0 +1,182 @@
+import {
+  PLUGIN_INPUT_OBSERVATION_PATH,
+  RESOLUTION_INPUT_RECORDER_PATH,
+} from "./RESOLUTION_INPUT_RECORDER_PATH";
+
+/**
+ * CommonJS evaluator emitted into a clean Node process for every load.
+ *
+ * What the descriptor's resolutions read is recorded by the resolution input
+ * recorder (`RESOLUTION_INPUT_RECORDER_PATH`), bracketing every resolution the
+ * hooks see. The process starts with recording active, so user --import
+ * preloads retain their observed inputs. The runtime hooks bypass only this
+ * generated entry; its synchronous bootstrap imports suspend recording until
+ * descriptor loading starts. The recorder is read and evaluated as a module of
+ * its own, as a Go config loader evaluates the copy it embeds: nothing resolves
+ * it, so nothing records it. Running this CommonJS entry as a file keeps its
+ * CommonJS bindings local; Node's -e global bindings must not become ambient
+ * values in ESM descriptors.
+ */
+export const COMMONJS_PLUGIN_DESCRIPTOR_SHIM_SOURCE = [
+  `process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_ACTIVE = "0";`,
+  `const fs = require("node:fs");`,
+  `const Module = require("node:module");`,
+  `const path = require("node:path");`,
+  `const vm = require("node:vm");`,
+  `const { PluginDescriptorInputObservation } = require.cache[${JSON.stringify(PLUGIN_INPUT_OBSERVATION_PATH)}]?.exports ?? require(${JSON.stringify(PLUGIN_INPUT_OBSERVATION_PATH)});`,
+  `const { fileURLToPath } = require("node:url");`,
+  `const { createResolutionInputRecorder, requireResolveConsultsHooks } = (() => {`,
+  `  const file = ${JSON.stringify(RESOLUTION_INPUT_RECORDER_PATH)};`,
+  `  const recorder = { exports: {} };`,
+  `  vm.runInThisContext("(function (exports, require, module, __filename, __dirname) {\\n" + fs.readFileSync(file, "utf8") + "\\n})", { filename: file })(recorder.exports, require, recorder, file, path.dirname(file));`,
+  `  return recorder.exports;`,
+  `})();`,
+  `const out = process.env.TTSC_PLUGIN_DESCRIPTOR_OUT;`,
+  `let retryWithTtsx = false;`,
+  `const moduleLoadFailures = new WeakMap();`,
+  `const moduleResolutionFailures = new WeakMap();`,
+  `function existingFile(file) { try { return fs.statSync(file).isFile(); } catch { return false; } }`,
+  `function shouldRetryWithTtsx(error) {`,
+  `  const loadFailure = error && (typeof error === "object" || typeof error === "function") ? moduleLoadFailures.get(error) : undefined;`,
+  `  if (loadFailure?.retryWithTtsx === true) return true;`,
+  `  const failure = error && (typeof error === "object" || typeof error === "function") ? moduleResolutionFailures.get(error) : undefined;`,
+  `  return failure?.retryWithTtsx === true;`,
+  `}`,
+  `try {`,
+  `  const request = process.env.TTSC_PLUGIN_ENTRY;`,
+  `  const context = JSON.parse(process.env.TTSC_PLUGIN_CONTEXT);`,
+  `  process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_ACTIVE = "1";`,
+  `  const recorder = createResolutionInputRecorder({ extensions: typeof globalThis.Bun === "object" ? [".tsx", ".jsx", ".ts", ".mjs", ".js", ".cjs", ".json"] : [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".json", ".node"] });`,
+  `  if (typeof Module.registerHooks !== "function" || (!requireResolveConsultsHooks() && !PluginDescriptorInputObservation.snapshot().requireResolveObserved)) recorder.invalidateObservation();`,
+  `  function asFile(resolved) {`,
+  `    if (typeof resolved !== "string") return undefined;`,
+  `    if (!resolved.startsWith("file:")) return path.isAbsolute(resolved) ? path.resolve(resolved) : undefined;`,
+  `    try { return path.resolve(fileURLToPath(resolved)); } catch { return undefined; }`,
+  `  }`,
+  `  recorder.recordFile(request);`,
+  `  function scanBunModuleGraph(entry) {`,
+  `    if (typeof globalThis.Bun !== "object" || typeof globalThis.Bun.Transpiler !== "function") return;`,
+  `    const scanned = new Set();`,
+  `    function scan(file) {`,
+  `      file = asFile(file);`,
+  `      if (file === undefined) return;`,
+  `      let canonical;`,
+  `      try { canonical = fs.realpathSync.native(file); } catch { return; }`,
+  `      if (scanned.has(canonical)) return;`,
+  `      scanned.add(canonical);`,
+  `      const extension = path.extname(canonical).toLowerCase();`,
+  `      if (![".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts"].includes(extension)) return;`,
+  `      const loader = extension === ".tsx" ? "tsx" : extension === ".jsx" ? "jsx" : [".ts", ".mts", ".cts"].includes(extension) ? "ts" : "js";`,
+  `      let imports;`,
+  `      try {`,
+  `        const source = fs.readFileSync(canonical, "utf8");`,
+  `        imports = new globalThis.Bun.Transpiler({ loader }).scan(source).imports;`,
+  `      } catch { return; }`,
+  `      for (const imported of imports) {`,
+  `        const specifier = imported && imported.path;`,
+  `        if (typeof specifier !== "string" || specifier.startsWith("node:") || Module.isBuiltin(specifier)) continue;`,
+  `        const resolution = recorder.beginResolution(specifier, canonical);`,
+  `        let resolved;`,
+  `        try {`,
+  `          resolved = globalThis.Bun.resolveSync(specifier, path.dirname(canonical));`,
+  `        } catch {`,
+  `          // The real descriptor load below owns user-facing resolution errors.`,
+  `        }`,
+  `        recorder.endResolution(resolution, resolved);`,
+  `        if (resolved !== undefined) scan(resolved);`,
+  `      }`,
+  `    }`,
+  `    scan(entry);`,
+  `  }`,
+  `  if (typeof Module.registerHooks === "function") {`,
+  `    Module.registerHooks({`,
+  `      load(url, loadContext, nextLoad) {`,
+  `        try { return nextLoad(url, loadContext); }`,
+  `        catch (error) {`,
+  `          if (error && (typeof error === "object" || typeof error === "function")) moduleLoadFailures.set(error, { retryWithTtsx: error.code === "ERR_UNKNOWN_FILE_EXTENSION" });`,
+  `          throw error;`,
+  `        }`,
+  `      },`,
+  `      resolve(specifier, resolveContext, nextResolve) {`,
+  `        const resolution = recorder.beginResolution(specifier, resolveContext.parentURL);`,
+  `        let resolved;`,
+  `        try {`,
+  `          resolved = nextResolve(specifier, resolveContext);`,
+  `        } catch (error) {`,
+  `          recorder.endResolution(resolution, undefined);`,
+  `          if (error && (typeof error === "object" || typeof error === "function")) {`,
+  `            const parent = asFile(resolveContext.parentURL);`,
+  `            const anchor = typeof parent === "string" ? parent : request;`,
+  `            const candidate = specifier.startsWith(".") && path.extname(specifier) === "" ? path.resolve(path.dirname(anchor), specifier) : undefined;`,
+  `            const retryWithTtsx = candidate !== undefined && [".ts", ".cts", ".mts", ".tsx"].some((extension) => existingFile(candidate + extension) || existingFile(path.join(candidate, "index" + extension)));`,
+  `            moduleResolutionFailures.set(error, { retryWithTtsx });`,
+  `          }`,
+  `          throw error;`,
+  `        }`,
+  `        recorder.endResolution(resolution, typeof resolved === "string" ? resolved : resolved && resolved.url);`,
+  `        return resolved;`,
+  `      },`,
+  `    });`,
+  `  }`,
+  `  if (typeof globalThis.Bun === "object" && typeof globalThis.Bun.plugin === "function") {`,
+  `    let insideBunResolve = false;`,
+  `    globalThis.Bun.plugin({`,
+  `      name: "ttsc-plugin-descriptor-inputs",`,
+  `      setup(build) {`,
+  `        build.onResolve({ filter: /.*/ }, (args) => {`,
+  `          if (insideBunResolve || args.path.startsWith("node:")) return;`,
+  `          try {`,
+  `            insideBunResolve = true;`,
+  `            const importer = args.importer && args.importer.startsWith("file:") ? fileURLToPath(args.importer) : args.importer;`,
+  `            const from = importer ? path.dirname(importer) : process.cwd();`,
+  `            const resolution = recorder.beginResolution(args.path, importer);`,
+  `            let resolved;`,
+  `            try {`,
+  `              resolved = globalThis.Bun.resolveSync(args.path, from);`,
+  `            } finally {`,
+  `              recorder.endResolution(resolution, resolved);`,
+  `            }`,
+  `          } catch {`,
+  `            // The real resolver below owns user-facing resolution errors.`,
+  `          } finally {`,
+  `            insideBunResolve = false;`,
+  `          }`,
+  `        });`,
+  `      },`,
+  `    });`,
+  `  }`,
+  `  scanBunModuleGraph(request);`,
+  `  let mod;`,
+  `  try {`,
+  `    mod = require(request);`,
+  `  } catch (error) {`,
+  `    retryWithTtsx = shouldRetryWithTtsx(error);`,
+  `    throw error;`,
+  `  }`,
+  `  const candidate = mod.createTtscPlugin ?? mod.default ?? mod.plugin ?? mod;`,
+  `  const descriptor = typeof candidate === "function" ? candidate(context) : candidate;`,
+  `  if (descriptor && typeof descriptor === "object" && ("transformSource" in descriptor || "transformOutput" in descriptor)) {`,
+  `    throw new Error("ttsc: plugin descriptor declares unsupported JS transform functions; declare a native backend instead");`,
+  `  }`,
+  // Serialize the descriptor while the module-resolution hooks are still
+  // collecting. Getters are allowed by JavaScript's object model and can
+  // lazily require a config; snapshotting inputs first would silently omit
+  // that influence.
+  `  const serializedDescriptor = JSON.stringify(descriptor);`,
+  `  const recorded = recorder.finish();`,
+  `  const observation = PluginDescriptorInputObservation.snapshot();`,
+  `  observation.complete = observation.complete && recorded.complete === true;`,
+  `  const payload = { inputHashes: recorded.hashes, inputRealpaths: recorded.realpaths, inputs: recorded.inputs, observation };`,
+  `  if (serializedDescriptor !== undefined) payload.descriptor = JSON.parse(serializedDescriptor);`,
+  `  fs.writeFileSync(out, JSON.stringify(payload));`,
+  `} catch (error) {`,
+  `  const message = error instanceof Error ? error.message : String(error);`,
+  `  const stack = error instanceof Error && error.stack ? error.stack : String(error);`,
+  `  try {`,
+  `    fs.writeFileSync(out, JSON.stringify({ __ttscLoaderError: message, __ttscRetryWithTtsx: retryWithTtsx }));`,
+  `  } catch {}`,
+  `  try { process.stderr.write(stack + "\\n"); } catch {}`,
+  `  process.exit(1);`,
+  `}`,
+  ``,
+].join("\n");

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

@@ -0,0 +1,59 @@
+import { PLUGIN_INPUT_OBSERVATION_PATH } from "./RESOLUTION_INPUT_RECORDER_PATH";
+
+/**
+ * The descriptor shim's emitted source.
+ *
+ * Exported so a regression can inspect the same bytes ttsx executes. This
+ * template consumes its own escapes, so reading this file's text instead would
+ * check characters no consumer ever sees — and a dropped backslash turns an
+ * escape into the character it was escaping: a raw line terminator inside a
+ * string literal, which stops the shim parsing and takes every descriptor load
+ * with it.
+ */
+export const PLUGIN_DESCRIPTOR_SHIM_SOURCE = [
+  `// @ts-nocheck`,
+  `import { writeFileSync } from "node:fs";`,
+  `import { createRequire } from "node:module";`,
+  `import { pathToFileURL } from "node:url";`,
+  // The import is inside the try, not above it. A descriptor that cannot be
+  // found, or whose module body throws, fails exactly where a descriptor
+  // whose factory throws does, and a caller deserves the same reason for
+  // both — "Cannot find module ./missing" is as actionable as anything the
+  // factory could have said.
+  `try {`,
+  `  const { PluginDescriptorInputObservation } = createRequire(import.meta.url).cache[${JSON.stringify(PLUGIN_INPUT_OBSERVATION_PATH)}].exports;`,
+  // Runtime hooks are installed before this shim loads. Arm their internal
+  // side channel only for the descriptor import itself, after this shim's own
+  // imports have resolved, so ttsc implementation files never become project
+  // cache inputs.
+  `  process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_ACTIVE = "1";`,
+  `  const mod = await import(pathToFileURL(process.env.TTSC_PLUGIN_ENTRY).href);`,
+  `  const context = JSON.parse(process.env.TTSC_PLUGIN_CONTEXT);`,
+  `  const candidate = mod.createTtscPlugin ?? mod.default ?? mod.plugin ?? mod;`,
+  `  const descriptor =`,
+  `    typeof candidate === "function" ? candidate(context) : candidate;`,
+  // Membership must be checked before JSON drops functions, undefined values,
+  // and inherited properties. The parent cannot recover those descriptor keys.
+  `  if (descriptor && typeof descriptor === "object" && ("transformSource" in descriptor || "transformOutput" in descriptor)) {`,
+  `    throw new Error("ttsc: plugin descriptor declares unsupported JS transform functions; declare a native backend instead");`,
+  `  }`,
+  `  const serializedDescriptor = JSON.stringify(descriptor);`,
+  `  const payload = { observation: PluginDescriptorInputObservation.snapshot() };`,
+  `  if (serializedDescriptor !== undefined) payload.descriptor = JSON.parse(serializedDescriptor);`,
+  `  writeFileSync(process.env.TTSC_PLUGIN_DESCRIPTOR_OUT, JSON.stringify(payload));`,
+  `} catch (error) {`,
+  // The stack streams to the user's stderr on its own. This puts the reason
+  // a caller can act on into the channel the parent already reads, so the
+  // failure is not reduced to a bare exit status.
+  // The escape is doubled on purpose: this template consumes one level, so
+  // `\\n` here is what puts the two-character escape into the emitted shim.
+  // A single `\n` would put a raw line terminator inside a string literal,
+  // and the shim would stop parsing — taking every descriptor load with it.
+  `  process.stderr.write((error instanceof Error && error.stack ? error.stack : String(error)) + "\\n");`,
+  `  try {`,
+  `    writeFileSync(process.env.TTSC_PLUGIN_DESCRIPTOR_OUT, JSON.stringify({ __ttscLoaderError: error instanceof Error ? error.message : String(error) }));`,
+  `  } catch {}`,
+  `  process.exit(1);`,
+  `}`,
+  ``,
+].join("\n");

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

@@ -0,0 +1,75 @@
+import type { ITtscPlugin } from "../../../structures/ITtscPlugin";
+import type { TtscPluginStage } from "../../../structures/TtscPluginStage";
+
+/**
+ * Admit an evaluated descriptor object and its supported execution stage.
+ * Evaluation, JS-transform rejection and native source acquisition remain
+ * separate owners; object admission does not validate every descriptor field.
+ *
+ * @evidence contracts/common.md#principled-implementation The actual loader uses object admission before its existing JS-function guard and stage selection before native preparation.
+ * @evidence contracts/common.md#clear-and-simple-design One descriptor concern groups shape admission and stage defaults/errors without an evaluator abstraction.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supplied evaluated values are not synthetic producer certificates and these members execute no loader.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes shallow shape admission from evaluation and other field validation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This namespace groups supplied-value policies without native filesystem or process operations.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The grouping chooses no input-processing algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The grouping owns no cached evaluation result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace retains no runtime registry, task or native handle.
+ */
+export namespace PluginDescriptorAdmission {
+  /**
+   * Return the same non-null, non-array object or reject the named export.
+   * Other field validation remains with the loader's subsequent guards.
+   *
+   * @evidence contracts/common.md#principled-implementation The former loader predicate admits exactly non-null objects except arrays and preserves admitted reference identity.
+   * @evidence contracts/common.md#clear-and-simple-design One return-or-throw boundary owns the actual invalid-export diagnostic.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No descriptor is evaluated or fabricated by this shallow admission.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states accepted shape, identity and the remaining field-validation responsibility.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Supplied values and diagnostic text require no native path, file or process operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms Scalar shape checks select no growing-population algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Admission uses the current supplied value and owns no evaluation cache.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The same object returns to the caller; no handle, task or history is retained.
+   */
+  export function descriptor(value: unknown, specifier: string): ITtscPlugin {
+    if (typeof value === "object" && value !== null && !Array.isArray(value))
+      return value as ITtscPlugin;
+    throw new Error(
+      `ttsc: plugin "${specifier}" does not export a valid ttsc plugin`,
+    );
+  }
+
+  /**
+   * Default an omitted stage to transform and reject removed/unknown stages.
+   * The removed output stage retains its specific upgrade diagnostic.
+   *
+   * @evidence contracts/common.md#principled-implementation Omission defaults to transform, transform/check retain their values, and removed output remains distinct from unsupported stage text.
+   * @evidence contracts/common.md#clear-and-simple-design Stage selection owns its default and two rejection diagnostics in one supplied-descriptor operation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No successful evaluator or native host is inferred from an accepted stage.
+   * @evidence contracts/common.md#meaningful-documentation Native prose names the default, admitted stages and removed-stage distinction.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Supplied stage/name values are interpreted without native paths, files or processes.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms Scalar stage selection and diagnostic formatting choose no growing-population algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current descriptor fields are read without retained stage-result caching.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This operation retains no descriptor population, handle or task.
+   */
+  export function stage(plugin: ITtscPlugin): TtscPluginStage {
+    if (plugin.stage === undefined) return "transform";
+    if (!isPluginStage(plugin.stage)) {
+      if (plugin.stage === "output")
+        throw new Error(
+          `ttsc: plugin "${plugin.name}" requested removed stage "output"; ` +
+            "upgrade the plugin to a transform-stage descriptor compatible with this ttsc version",
+        );
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" requested unsupported stage ${JSON.stringify(plugin.stage)}`,
+      );
+    }
+    return plugin.stage;
+  }
+}
+
+/**
+ * Retain the loader's scalar stage predicate without rereading descriptor
+ * fields.
+ */
+function isPluginStage(value: string): value is TtscPluginStage {
+  return value === "transform" || value === "check";
+}