@ttsc/unplugin 0.34.0 → 0.34.2

package/src/core/transform/generation/onlyLearnedCompileFacts.ts

@@ -8,27 +8,29 @@ const LEARNED_FACTS = new Set([
   // The compiler's case policy, first reported by this compile's envelope,
   // which the walk before it did not match under (samchon/ttsc#1545).
   "case-policy-learned",
+  // Effective suffix/output settings reported after provisional root discovery.
+  "membership-policy-learned",
 ]);
 
 /**
  * Whether the retained, lossless failure aggregate names only facts learned
  * after the attempt's pre-compile observation.
  *
- * The retry owner carries learned dependencies and compiler case policy into
- * the next attempt, without spending its movement budget for this
+ * The retry owner carries learned dependencies and compiler membership policy
+ * into the next attempt, without spending its movement budget for this
  * classification. This predicate classifies recorded failures, not independent
  * disk stability; producers must record other failed proofs. An omitted witness
  * could be anything, so it prevents that exemption. The retry owner separately
  * enforces the absolute attempt cap and handles refuted adoptions.
  *
  * @param failures The attempt's recorded proof failures.
- * @evidence contracts/common.md#principled-implementation A nonempty aggregate with omitted=0 and only dependency-unwitnessed or case-policy-learned qualifies for the retry owner's learned-fact exemption. This is classification of supplied witnesses, not a separate proof of project stability; omitted or other recorded failures prevent the exemption.
+ * @evidence contracts/common.md#principled-implementation A nonempty lossless aggregate containing only dependency-unwitnessed, case-policy-learned or membership-policy-learned qualifies for the learned-fact exemption. Other recorded failures prevent it; this classification is not independent proof of project stability.
  * @evidence contracts/common.md#clear-and-simple-design One predicate centralizes which proof classes consume the retry movement budget, leaving actual attempts and the absolute cap to transformProject.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts The recognized kinds express real compile facts learned after pre-witnessing, and no omitted or mixed failure is excused by a fixture-specific retry exception.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the missing-knowledge distinction, retry consequence and conservative dropped-witness rule, with params and acknowledgment separation.
  * @evidence contracts/performance.md#efficient-algorithms Zero omissions and nonempty entries guard an every scan that stops at the first other kind. The recorder bounds normal retained count, while the supplied kind text still contributes to Set hashing/comparison. No per-call index or copied entry list is allocated.
- * @evidenceExclude contracts/performance.md#reuse-equivalent-work The fixed two-kind lookup table is algorithm data, not shared completed or in-flight computation. This predicate recomputes classification of the supplied aggregate; transformProject owns retries and learned observations.
- * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows the aggregate and reads a fixed private two-kind table. It acquires no retained per-attempt state, handle or running task and controls no aggregate lifecycle.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The fixed kind table is algorithm data, not cached computation. The retry owner carries learned observations.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows the aggregate and reads a fixed private table without acquiring state or handles.
  * @evidenceExclude contracts/portability.md#os-neutral-implementation Classifies failure kinds by a fixed set of strings; it reads no filesystem or path.
  */
 export function onlyLearnedCompileFacts(

package/src/core/transform/generation/primeCompilerMembership.ts

@@ -0,0 +1,39 @@
+import type { ITtscProjectMembershipPolicy } from "../../tsconfig/ITtscProjectMembershipPolicy";
+import { hashText } from "../utils/hashText";
+import { stableStringify } from "../utils/stableStringify";
+import type { TtscCompilerMembershipHint } from "./TtscCompilerMembershipHint";
+import { applyCompilerMembership } from "./applyCompilerMembership";
+
+/**
+ * Prime a walk with a native hint only while its JSON policy premise matches. A
+ * match predicts settings; current native reports and walk proofs remain
+ * required.
+ *
+ * @evidence contracts/common.md#principled-implementation Canonical JSON hashing compares the complete supplied config and overlay policy, including explicit option origins. A changed premise discards the previous projection before the pre-compile walk.
+ * @evidence contracts/common.md#clear-and-simple-design One operation returns both the premise identity for capture and the policy to walk; the projection helper retains native path semantics.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Matching config semantics supplies no filesystem freshness claim and cannot certify a post-compile walk as pre-compile evidence.
+ * @evidence contracts/common.md#meaningful-documentation Native prose and result members distinguish prediction identity from current generation proof.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Policy paths are serialized as supplied and projected by their owning helper; this function performs no native observation or case rewriting.
+ * @evidence contracts/performance.md#efficient-algorithms Canonical serialization sorts record keys and visits policy bytes once before hashing; a matching hint additionally copies the suffix and exclusion population. Temporary storage follows policy size.
+ * @evidence contracts/performance.md#reuse-equivalent-work Only a hint learned under the same config policy can prime this walk; no work result, input witness or native authority is reused here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned identity and borrowed or projected policy transfer to the caller; this call retains no cache or resource.
+ */
+export function primeCompilerMembership(
+  policy: ITtscProjectMembershipPolicy,
+  hint?: TtscCompilerMembershipHint,
+): {
+  /** Config-policy identity used to qualify a subsequently learned report. */
+  basis: string;
+
+  /** Fresh config policy, optionally projected by an equivalent prior hint. */
+  policy: ITtscProjectMembershipPolicy;
+} {
+  const basis = hashText(stableStringify(policy));
+  return {
+    basis,
+    policy:
+      hint?.basis === basis
+        ? applyCompilerMembership(policy, hint.report)
+        : policy,
+  };
+}

package/src/core/transform/generation/selectReportedMembershipPolicy.ts

@@ -1,21 +1,23 @@
+import path from "node:path";
 import type { ITtscCompilerTransformation } from "ttsc";
 
 import type { ITtscProjectMembershipPolicy } from "../../tsconfig/ITtscProjectMembershipPolicy";
+import { applyCompilerMembership } from "./applyCompilerMembership";
 
 /**
- * Replace a capture's provisional compiler comparison rule with its report.
+ * Replace provisional root settings and comparison rules with native reports.
  *
  * Capture supplies an explicit priming answer before walking. An exception or
- * an envelope without a case report leaves that same policy intact. A differing
+ * an envelope without reports leaves that same policy intact. A differing
  * report marks the old walk for refusal; this operation neither performs the
  * walk nor establishes that a predicted answer matched the native compiler.
  *
- * @evidence contracts/common.md#principled-implementation An available compiler boolean, including false, overrides the explicit priming answer; equality determines whether the capture learned a different rule. Missing reports retain the original policy identity.
+ * @evidence contracts/common.md#principled-implementation Native case, suffix and output settings replace provisional answers; set equality determines whether a fresh walk is needed. Missing reports preserve the original policy identity and explicit excludes retain authored provenance.
  * @evidence contracts/common.md#clear-and-simple-design One report-selection operation returns the policy and changed-rule fact; capture retains ownership of enumeration authority and proof refusal.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts No OS label or filesystem probe substitutes for a compiler report, and no report supplies missing walk evidence.
  * @evidence contracts/common.md#meaningful-documentation Native prose states the explicit primer requirement, missing-report identity and changed-policy refusal boundary.
- * @evidence contracts/portability.md#os-neutral-implementation The compiler's reported comparison policy wins independently of host path grammar; the explicit primer remains provisional and native prediction or probing is outside this operation.
- * @evidence contracts/performance.md#efficient-algorithms Missing reports return the borrowed policy; an available report shallow-copies its own fields once. Work and temporary object space follow policy field count, without traversing nested specifications.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path grammar resolves directory spelling; component-boundary prefixes map only observed project root aliases to a shared anchor. Insensitive reports permit ASCII case equivalence, while non-ASCII spellings stay conservatively distinct instead of colliding through full lowercasing or Windows path.relative.
+ * @evidence contracts/performance.md#efficient-algorithms Available settings copy extension/exclusion populations; Set comparisons visit their text. At most three observed anchors are resolved once and each exclusion compares their component-boundary prefixes. Temporary storage follows those populations and path lengths; no filesystem query runs here.
  * @evidenceExclude contracts/performance.md#reuse-equivalent-work Selects this envelope's reported rule without retaining a memo or certifying reuse of the primed walk.
  * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Borrows the primer or returns a shallow policy object; capture owns retained policy and observer lifetimes, with no handle or historical state acquired here.
  */
@@ -23,22 +25,66 @@ export function selectReportedMembershipPolicy(
   primed: ITtscProjectMembershipPolicy & { useCaseSensitiveFileNames: boolean },
   result: ITtscCompilerTransformation,
 ): {
-  /** Borrowed primer or reported-case overlay for this capture's validators. */
+  /** Borrowed primer or native settings overlay for this capture's validators. */
   membershipPolicy: ITtscProjectMembershipPolicy;
 
   /** Whether the primed walk used a different rule from this compiler report. */
-  casePolicyLearned: boolean;
+  membershipPolicyLearned: boolean;
 } {
   const reported =
     result.type === "exception"
       ? undefined
       : result.graph?.useCaseSensitiveFileNames;
+  const rootReport =
+    result.type === "exception" ? undefined : result.graph?.membership;
+  const policy = applyCompilerMembership(
+    reported === undefined
+      ? primed
+      : { ...primed, useCaseSensitiveFileNames: reported },
+    rootReport,
+  );
+  // ASCII equivalence cannot introduce Unicode expansion collisions. Other
+  // spelling changes conservatively require a fresh walk under the report.
+  const asciiFold = (value: string): string =>
+    value.replace(/[A-Z]/g, (character) => character.toLowerCase());
+  const canonical = (value: string): string =>
+    policy.useCaseSensitiveFileNames === false ? asciiFold(value) : value;
+  const root = primed.rootFileSpecs?.root;
+  const anchors =
+    root === undefined
+      ? []
+      : [root.path, root.realpath, root.nativepath]
+          .filter((anchor): anchor is string => anchor !== undefined)
+          .map((anchor) => canonical(path.resolve(anchor)));
+  const directoryKey = (directory: string): string => {
+    const target = canonical(path.resolve(directory));
+    for (const anchor of anchors) {
+      if (target === anchor) return "root:";
+      const prefix = anchor.endsWith(path.sep) ? anchor : anchor + path.sep;
+      if (target.startsWith(prefix))
+        return "root:" + target.slice(prefix.length);
+    }
+    return "absolute:" + target;
+  };
+  const sameSet = (
+    left: readonly string[],
+    right: readonly string[],
+    key: (value: string) => string,
+  ): boolean => {
+    const a = new Set(left.map(key));
+    const b = new Set(right.map(key));
+    return a.size === b.size && [...a].every((entry) => b.has(entry));
+  };
   return {
-    membershipPolicy:
-      reported === undefined
-        ? primed
-        : { ...primed, useCaseSensitiveFileNames: reported },
-    casePolicyLearned:
-      reported !== undefined && reported !== primed.useCaseSensitiveFileNames,
+    membershipPolicy: policy,
+    membershipPolicyLearned:
+      (reported !== undefined &&
+        reported !== primed.useCaseSensitiveFileNames) ||
+      !sameSet(primed.inputExtensions, policy.inputExtensions, asciiFold) ||
+      !sameSet(
+        primed.excludedDirectories,
+        policy.excludedDirectories,
+        directoryKey,
+      ),
   };
 }

package/src/core/transform/generation/transformProject.ts

@@ -8,6 +8,7 @@ import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransf
 import { TRANSFORM_ADOPTED_RESULTS } from "../session/TRANSFORM_ADOPTED_RESULTS";
 import { TRANSFORM_FAILED_GENERATION_VALIDATIONS } from "./TRANSFORM_FAILED_GENERATION_VALIDATIONS";
 import { TRANSFORM_GENERATION_FAILURES } from "./TRANSFORM_GENERATION_FAILURES";
+import type { TtscCompilerMembershipHint } from "./TtscCompilerMembershipHint";
 import type { TtscGenerationProofFailures } from "./TtscGenerationProofFailures";
 import { captureTransformGeneration } from "./captureTransformGeneration";
 import { carryTransformAttemptInputs } from "./carryTransformAttemptInputs";
@@ -91,6 +92,14 @@ export async function transformProject(props: {
   /** Compiler-option overlay, preserving the underlying config semantics. */
   compilerOptions: Record<string, unknown>;
 
+  /** Detached environment selected before this generation's cache lookup. */
+  compilerEnvironment?: NodeJS.ProcessEnv;
+  /** Explicit override retained with persisted invocation proof. */
+  runExternalCode?: boolean;
+
+  /** Previous native root policy; the new compiler report can refute it. */
+  compilerMembership?: TtscCompilerMembershipHint;
+
   /** Native path of the module whose delivery initiated this capture. */
   currentFile: string;
 
@@ -160,9 +169,11 @@ export async function transformProject(props: {
   let moved = 0;
   let witnessed = new Set(props.witnessedDependencies);
   let useCaseSensitiveFileNames = props.useCaseSensitiveFileNames;
+  let compilerMembership = props.compilerMembership;
   for (let attempt = 0; ; attempt += 1) {
     const cached = await captureTransformGeneration({
       ...props,
+      compilerMembership,
       rejected,
       useCaseSensitiveFileNames,
       witnessedDependencies: [...witnessed],
@@ -222,6 +233,7 @@ export async function transformProject(props: {
     );
     witnessed = nextInputs.witnessed;
     useCaseSensitiveFileNames = nextInputs.useCaseSensitiveFileNames;
+    compilerMembership = cached.compilerMembership;
     // A publication refuted here would be found again by a retry for the same
     // state, which therefore compiles and replaces it. A retry whose project
     // moved to another state claims that state's publication, and adopts it:

package/src/core/transform/project/isPossibleProgramFileName.ts

@@ -3,27 +3,40 @@ import type { ITtscProjectMembershipPolicy } from "../../tsconfig/ITtscProjectMe
 /**
  * Whether a bare filename has an extension admitted by the project policy.
  *
- * @evidence contracts/common.md#principled-implementation Case-normalized suffix matching applies the policy's admitted extension list; this is an eligibility approximation, not filesystem path identity.
- * @evidence contracts/common.md#clear-and-simple-design One lowercased name and an early-terminating suffix scan represent the extension rule without performing filesystem work.
+ * Literal expressions preserve Unicode simple case folding without expanding or
+ * contextually lowercasing either operand. This remains conservative root
+ * eligibility, independently of filesystem identity or compiler enumeration.
+ *
+ * @evidence contracts/common.md#principled-implementation Escaped literal suffixes use Unicode simple folding and a strict end boundary; this preserves dotted I and contextual sigma without treating mapper punctuation as regex grammar.
+ * @evidence contracts/common.md#clear-and-simple-design One weakly owned expression list per immutable policy serves an early-terminating suffix scan without filesystem work.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts The predicate uses compiler-derived extension policy rather than selected test filenames or bundler output-directory exceptions.
  * @evidence contracts/common.md#meaningful-documentation The native comment states the bare-name input and policy boundary, avoiding an ambiguous reference to another helper's question.
- * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares a lowercased basename suffix with the policy's extensions; it reads no filesystem.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares basename text using literal Unicode suffixes; it reads no filesystem or OS-name policy.
  * @evidence contracts/performance.md#efficient-algorithms
- *   Lowercasing scans the filename and allocates its normalized text once.
- *   The early-terminating scan checks the supplied extension population, with
- *   suffix comparison cost following the extension text. No filename or
- *   extension index is rebuilt inside the scan.
- * @evidenceExclude contracts/performance.md#reuse-equivalent-work
- *   Keeps no cache of its own and computes each value once.
- * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
- *   Acquires no handle, timer or retained state of its own.
+ *   A cold policy compiles its suffix text once. Queries scan the supplied
+ *   expressions until a match, with literal search work following filename
+ *   length and suffix text; no authored wildcard or repeated pattern activates
+ *   backtracking partitions. Retained expression text follows the suffix list.
+ * @evidence contracts/performance.md#reuse-equivalent-work Compiled literal expressions are shared only by the same immutable policy identity; changing its suffix list requires a new policy, as other membership matchers require.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The WeakMap retains expressions while their policy remains reachable and does not pin discarded policies; there are no filename histories, handles or timers.
  */
 export function isPossibleProgramFileName(
   name: string,
   policy: ITtscProjectMembershipPolicy,
 ): boolean {
-  const lowered = name.toLowerCase();
-  return policy.inputExtensions.some((extension) =>
-    lowered.endsWith(extension),
-  );
+  let patterns = compiled.get(policy);
+  if (patterns === undefined) {
+    patterns = policy.inputExtensions.map(
+      (extension) =>
+        new RegExp(
+          `${extension.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&")}(?![\\s\\S])`,
+          "iu",
+        ),
+    );
+    compiled.set(policy, patterns);
+  }
+  return patterns.some((pattern) => pattern.test(name));
 }
+
+/** Literal suffix expressions owned weakly by immutable membership policy. */
+const compiled = new WeakMap<ITtscProjectMembershipPolicy, readonly RegExp[]>();

package/src/core/transform/session/sharedCompileIdentity.ts

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import { pluginBuildVersions } from "ttsc/plugin-source";
 
 import type { ResolvedTtscUnpluginOptions } from "../../options/ResolvedTtscUnpluginOptions";
+import { compilerEnvironmentIdentity } from "../tsconfig/compilerEnvironmentIdentity";
 import { unpluginVersion } from "./unpluginVersion";
 
 /**
@@ -10,11 +11,12 @@ import { unpluginVersion } from "./unpluginVersion";
  *
  * The ordered JSON tuple groups sharing candidates by spelled config and source
  * root, serialized compiler-option/alias/plugin payloads, reported versions and
- * binary platform. Supported option values must preserve their meaning through
- * JSON; omitted or unsupported JavaScript values are not independent key
- * dimensions. This is a truncated digest, not a complete filesystem or output
- * equivalence proof. Claim publication and adoption separately establish the
- * recorded input/stability premises for a reused compile.
+ * binary platform and effective compiler argument transport. Supported option
+ * values must preserve their meaning through JSON; omitted or unsupported
+ * JavaScript values are not independent key dimensions. This is a truncated
+ * digest, not a complete filesystem or output equivalence proof. Claim
+ * publication and adoption separately establish the recorded input/stability
+ * premises for a reused compile.
  *
  * A compile is kept beyond the process that published it, so a dev server
  * started again adopts what the last one compiled (samchon/ttsc#1483). The
@@ -41,6 +43,8 @@ import { unpluginVersion } from "./unpluginVersion";
 export function sharedCompileIdentity(props: {
   aliasPaths: Record<string, string[]>;
   compilerOptions: Record<string, unknown>;
+  /** Effective compiler arguments and their original working directory. */
+  compilerEnvironment?: NodeJS.ProcessEnv;
   plugins?: ResolvedTtscUnpluginOptions["plugins"];
   projectRoot: string;
   tsconfig: string;
@@ -52,6 +56,7 @@ export function sharedCompileIdentity(props: {
         props.tsconfig,
         props.projectRoot,
         props.compilerOptions,
+        compilerEnvironmentIdentity(props.compilerEnvironment),
         props.aliasPaths,
         props.plugins ?? null,
         pluginBuildVersions(props.projectRoot),

package/src/core/transform/transformTtsc.ts

@@ -7,6 +7,7 @@ import { createAliasPaths } from "./alias/createAliasPaths";
 import { TERMINAL_TRANSFORM_GENERATIONS } from "./cache/TERMINAL_TRANSFORM_GENERATIONS";
 import { TRANSFORM_CACHE_CASE_POLICIES } from "./cache/TRANSFORM_CACHE_CASE_POLICIES";
 import { TRANSFORM_CACHE_DEPENDENCY_WITNESSES } from "./cache/TRANSFORM_CACHE_DEPENDENCY_WITNESSES";
+import { TRANSFORM_CACHE_MEMBERSHIP_POLICIES } from "./cache/TRANSFORM_CACHE_MEMBERSHIP_POLICIES";
 import { TRANSFORM_RESULT_FILESYSTEM } from "./cache/TRANSFORM_RESULT_FILESYSTEM";
 import type { TtscTransformCache } from "./cache/TtscTransformCache";
 import { awaitOrEvict } from "./cache/awaitOrEvict";
@@ -24,6 +25,7 @@ import { transformProject } from "./generation/transformProject";
 import { preparePluginBuildEnvironments } from "./inputs/preparePluginBuildEnvironments";
 import { TRANSFORM_CACHE_SESSIONS } from "./session/TRANSFORM_CACHE_SESSIONS";
 import { settleProjectMutationEvents } from "./tracker/settleProjectMutationEvents";
+import { resolveCompilerEnvironment } from "./tsconfig/resolveCompilerEnvironment";
 import { resolveProjectSelection } from "./tsconfig/resolveProjectSelection";
 import { isDeclarationFile } from "./utils/isDeclarationFile";
 import { isHostWrapperQuery } from "./utils/isHostWrapperQuery";
@@ -162,8 +164,12 @@ async function runTransformTtsc(
       ),
     );
   }
+  const compilerEnvironment = resolveCompilerEnvironment(
+    options.runExternalCode,
+  );
   const key = createTransformCacheKey({
     aliasPaths,
+    compilerEnvironment,
     compilerOptions: options.compilerOptions,
     plugins: options.plugins,
     projectRoot: selectedProjectRoot,
@@ -294,6 +300,12 @@ async function runTransformTtsc(
       transformed = transformProject({
         aliasPaths,
         compilerOptions: options.compilerOptions,
+        compilerEnvironment,
+        runExternalCode: options.runExternalCode,
+        compilerMembership:
+          cache === undefined
+            ? undefined
+            : TRANSFORM_CACHE_MEMBERSHIP_POLICIES.get(cache)?.get(key),
         projectRoot: selectedProjectRoot,
         currentFile: file,
         currentSource: source,
@@ -354,6 +366,15 @@ async function runTransformTtsc(
         TRANSFORM_CACHE_DEPENDENCY_WITNESSES.set(cache, witnesses);
       }
       witnesses.set(key, cached.externalDependencyInputs ?? []);
+      const membership = cached.compilerMembership;
+      if (membership !== undefined) {
+        let policies = TRANSFORM_CACHE_MEMBERSHIP_POLICIES.get(cache);
+        if (policies === undefined) {
+          policies = new Map();
+          TRANSFORM_CACHE_MEMBERSHIP_POLICIES.set(cache, policies);
+        }
+        policies.set(key, membership);
+      }
       const reported = cached.membershipPolicy.useCaseSensitiveFileNames;
       if (reported !== undefined) {
         let policies = TRANSFORM_CACHE_CASE_POLICIES.get(cache);

package/src/core/transform/tsconfig/TtscCompilerArgumentsWitness.ts

@@ -0,0 +1,19 @@
+/**
+ * Captured argument transport and the policy used to derive it from
+ * inheritance.
+ *
+ * @evidence contracts/common.md#principled-implementation The digest describes actual effective argv/cwd; the optional override lets detached readers derive the same invocation under current inheritance.
+ * @evidence contracts/common.md#clear-and-simple-design Two scalar facts cross generation and persisted-record boundaries without retaining environment objects.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing witnesses remain unknown and cannot certify an older record's invocation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes transport identity from the override policy needed for later comparison.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The value carries an opaque digest and boolean; normalization belongs to its producer.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This interface performs no computation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This interface establishes no reuse verdict.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This interface owns no runtime resource.
+ */
+export interface TtscCompilerArgumentsWitness {
+  /** SHA-256 of the normalized effective argv/cwd transport tuple. */
+  identity: string;
+  /** Explicit override; omission preserves inherited compiler arguments. */
+  runExternalCode?: boolean;
+}

package/src/core/transform/tsconfig/captureCompilerArguments.ts

@@ -0,0 +1,25 @@
+import { hashText } from "../utils/hashText";
+import type { TtscCompilerArgumentsWitness } from "./TtscCompilerArgumentsWitness";
+import { compilerEnvironmentIdentity } from "./compilerEnvironmentIdentity";
+
+/**
+ * Fingerprint the exact normalized environment chosen for this invocation.
+ *
+ * @evidence contracts/common.md#principled-implementation The digest uses supplied effective argv/cwd rather than rereading a later parent environment; the supplied override retains its inheritance meaning.
+ * @evidence contracts/common.md#clear-and-simple-design One compact witness travels with generations and persisted host records.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No compiler result or filesystem proof is inferred from argument identity.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the normalized-snapshot premise and capture timing.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The environment owner has already normalized native names; tuple spelling is preserved.
+ * @evidence contracts/performance.md#efficient-algorithms Tuple encoding scans argument/cwd text and SHA-256 scans the encoded bytes and retain only a fixed digest and optional boolean.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This projection retains no previous result or in-flight operation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned scalar witness transfers to its caller without handles or history.
+ */
+export function captureCompilerArguments(
+  environment: NodeJS.ProcessEnv,
+  runExternalCode?: boolean,
+): TtscCompilerArgumentsWitness {
+  return {
+    identity: hashText(compilerEnvironmentIdentity(environment)),
+    ...(runExternalCode === undefined ? {} : { runExternalCode }),
+  };
+}

package/src/core/transform/tsconfig/compilerEnvironmentIdentity.ts

@@ -0,0 +1,20 @@
+/**
+ * Identify the argument transport in a normalized invocation snapshot.
+ *
+ * @evidence contracts/common.md#principled-implementation The ordered pair retains raw argv and cwd; absence differs from explicit empty argv.
+ * @evidence contracts/common.md#clear-and-simple-design All cache owners use this transport projection, separate from capture.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No argument is dropped based on a consumer or expected output.
+ * @evidence contracts/common.md#meaningful-documentation The headline states the normalized-snapshot premise and transport scope.
+ * @evidence contracts/portability.md#os-neutral-implementation resolveCompilerEnvironment normalizes native environment names; cwd spelling and JSON argv remain unchanged.
+ * @evidence contracts/performance.md#efficient-algorithms Serialization scans two transport strings and allocates their encoded bytes.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This projection owns no cache or shared operation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned string escapes the call.
+ */
+export function compilerEnvironmentIdentity(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return JSON.stringify([
+    env.TTSC_TSGO_ARGS ?? null,
+    env.TTSC_TSGO_ARGS_CWD ?? null,
+  ]);
+}

package/src/core/transform/tsconfig/resolveCompilerEnvironment.ts

@@ -0,0 +1,61 @@
+/**
+ * Capture one invocation's environment and explicit content-mapper permission.
+ *
+ * Omission preserves inherited arguments. An explicit boolean appends its
+ * upstream assignment after inherited arguments, keeping their order and cwd.
+ * Invalid transport fails instead of discarding inherited choices.
+ *
+ * @evidence contracts/common.md#principled-implementation A detached environment and ordered JSON argv preserve inherited choices; an explicit boolean assignment has final precedence.
+ * @evidence contracts/common.md#clear-and-simple-design Capture happens before cache selection; scratch routing derives a child copy afterward.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No process global or compiler behavior is replaced.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents omission, precedence, cwd and invalid transport.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows environment names follow their native case-insensitive rule; POSIX names remain exact. JSON preserves argv without shell syntax.
+ * @evidence contracts/performance.md#efficient-algorithms Copying visits environment keys; Windows normalization scans them once, and an explicit permission parses and serializes argument bytes once.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Every invocation observes current inherited values; cache owners compare its snapshot.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The detached result transfers to its caller and acquires no handle or history.
+ */
+export function resolveCompilerEnvironment(
+  runExternalCode?: boolean,
+  inherited: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  const env = { ...inherited };
+  if (process.platform === "win32") {
+    const selected = new Map<
+      string,
+      { key: string; value: string | undefined }
+    >();
+    for (const key of Object.keys(env)) {
+      const name = key.toUpperCase();
+      if (name === "TTSC_TSGO_ARGS" || name === "TTSC_TSGO_ARGS_CWD") {
+        const prior = selected.get(name);
+        if (prior === undefined || key < prior.key)
+          selected.set(name, { key, value: env[key] });
+        delete env[key];
+      }
+    }
+    for (const [name, value] of selected) env[name] = value.value;
+  }
+  // Own absent channels too: a later process.env edit must not become a new
+  // inherited argument between this cache lookup and the compiler spawn.
+  env.TTSC_TSGO_ARGS = env.TTSC_TSGO_ARGS;
+  env.TTSC_TSGO_ARGS_CWD = env.TTSC_TSGO_ARGS_CWD;
+  if (runExternalCode === undefined) return env;
+  if (typeof runExternalCode !== "boolean")
+    throw new TypeError("@ttsc/unplugin: runExternalCode must be a boolean");
+  // Go's environment transport trims Unicode White_Space, which excludes BOM.
+  const raw = env.TTSC_TSGO_ARGS?.replace(
+    /^\p{White_Space}+|\p{White_Space}+$/gu,
+    "",
+  );
+  const args: unknown = raw === undefined || raw === "" ? [] : JSON.parse(raw);
+  if (!Array.isArray(args) || args.some((value) => typeof value !== "string"))
+    throw new TypeError(
+      "@ttsc/unplugin: TTSC_TSGO_ARGS must be a JSON string array",
+    );
+  env.TTSC_TSGO_ARGS = JSON.stringify([
+    ...args,
+    "--runExternalCode",
+    String(runExternalCode),
+  ]);
+  return env;
+}

package/src/core/transform/tsconfig/transformScratchEnvironment.ts

@@ -1,8 +1,8 @@
 /**
- * The environment a compile runs under: the host's own, with `TEMP`, `TMP`, and
- * `TMPDIR` naming the compile's scratch directory. Consumers honoring these
- * variables use that temporary root; explicit paths or overridden child
- * environments are not confined by these settings.
+ * The environment a compile runs under: its captured snapshot, with `TEMP`,
+ * `TMP`, and `TMPDIR` naming the compile's scratch directory. Consumers
+ * honoring these variables use that temporary root; explicit paths or
+ * overridden child environments are not confined by these settings.
  *
  * Capture hands this copy to the compiler as `env` (samchon/ttsc#1488);
  * applying it to workers and inherited child environments belongs to the
@@ -15,7 +15,7 @@
  * @evidence contracts/common.md#meaningful-documentation The native paragraphs identify the child-process propagation boundary and explicitly distinguish it from changing the host environment.
  * @evidence contracts/portability.md#os-neutral-implementation All three native temporary-directory variables receive the same owned directory, covering Windows and Unix child consumers without constructing shell syntax or mutating the host environment.
  * @evidence contracts/performance.md#efficient-algorithms
- *   The spread enumerates K process environment keys/values into a fresh object
+ *   The spread enumerates K supplied environment keys/values into a fresh object
  *   before three assignments. Key/value text and native environment retrieval
  *   contribute costs; absence of an explicit loop is not constant work.
  * @evidenceExclude contracts/performance.md#reuse-equivalent-work
@@ -26,9 +26,10 @@
  */
 export function transformScratchEnvironment(
   directory: string,
+  inherited: NodeJS.ProcessEnv = process.env,
 ): NodeJS.ProcessEnv {
   return {
-    ...process.env,
+    ...inherited,
     TEMP: directory,
     TMP: directory,
     TMPDIR: directory,

package/src/core/transform/watch/notifyProjectRecord.ts

@@ -227,6 +227,9 @@ function recordOf(
 ): TtscProjectRecord {
   const dependencies = cached.externalDependencyInputs ?? [];
   const record: TtscProjectRecord = {
+    ...(cached.compilerArguments === undefined
+      ? {}
+      : { compilerArguments: cached.compilerArguments }),
     ...(dependencies.length === 0 ? {} : { dependencies }),
     inputs: {},
     membership:

package/src/core/tsconfig/ITtscProjectMembershipPolicy.ts

@@ -78,9 +78,23 @@ export interface ITtscProjectMembershipPolicy {
   /** Absolute directory exclusions represented for project-root discovery. */
   readonly excludedDirectories: readonly string[];
 
-  /** Lowercased extensions a file needs to be a possible program input. */
+  /** Literal suffix spellings a file needs to be a possible program input. */
   readonly inputExtensions: readonly string[];
 
+  /**
+   * Explicit extension options before compiler defaults, plus declared mapper
+   * suffixes. Missing options use the pinned compiler's defaults. Optional for
+   * older policy producers, whose extension lists remain their own authority.
+   */
+  readonly extensionOptionOrigins?: Readonly<{
+    allowJs?: boolean;
+    checkJs?: boolean;
+    resolveJsonModule?: boolean;
+    module?: string;
+    moduleResolution?: string;
+    mapperExtensions: readonly string[];
+  }>;
+
   /**
    * Every config file consulted to produce this policy, including inherited
    * declarations and unresolved file candidates. A query can stop at its own