ttsc 0.31.6 → 0.32.1

package/src/launcher/internal/watch/WatchTopologyWorkerProtocol.ts

@@ -0,0 +1,106 @@
+import type { PluginContentIdentities } from "../../../plugin/internal/source/PluginContentIdentities";
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+import type { WatchInputChange } from "./WatchInputChange";
+import type { WatchTopology } from "./WatchTopology";
+
+/**
+ * Cloned requests and ordered notifications of one watch topology worker.
+ *
+ * @evidence contracts/common.md#principled-implementation Discriminated messages preserve operation arguments and separate callbacks from request completion; bigint reference maps retain the record store's separability evidence through structured cloning.
+ * @evidence contracts/common.md#clear-and-simple-design One internal protocol serves the facade and its worker without transferring callback functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Messages carry actual topology operations and observations rather than predicted decisions.
+ * @evidence contracts/common.md#meaningful-documentation Members identify correlation, callback ordering and the cloneable option boundary.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The types describe structured messages; execution owns native paths and workers.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms These types execute no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The protocol grants no result reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The types acquire no resources; the facade owns in-flight messages.
+ */
+export namespace WatchTopologyWorkerProtocol {
+  /**
+   * Only the core's selected data options cross the worker boundary.
+   *
+   * @evidence contracts/common.md#principled-implementation Deriving the data type from the core constructor keeps option meaning with its owner.
+   * @evidence contracts/common.md#clear-and-simple-design One alias serves both ends of the worker's startup payload.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The facade explicitly selects these fields without transferring invocation callbacks.
+   * @evidence contracts/common.md#meaningful-documentation Prose identifies the cloneable startup boundary.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This alias executes no native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms The alias chooses no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The type grants no reuse.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The type acquires no resource; the facade owns startup cloning.
+   */
+  export type Options = ConstructorParameters<typeof WatchTopology>[0];
+
+  /**
+   * Callback implementations remain on the launcher thread.
+   *
+   * @evidence contracts/common.md#principled-implementation Core callbacks retain their meanings; actual worker error or unexpected exit invokes separate terminal notification because authority was lost, requiring the launcher to retire its session.
+   * @evidence contracts/common.md#clear-and-simple-design One structural intersection adds a dedicated terminal callback beside recoverable subscription events.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Callbacks report actual observations and authority loss without continuing to claim coverage after thread death.
+   * @evidence contracts/common.md#meaningful-documentation Prose identifies launcher-thread callbacks and the receiving owner's required retirement after terminal loss.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation These signatures perform no native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms Callback signatures choose no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Callback declarations grant no event reuse; terminal failure belongs to one lifecycle.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Signatures acquire no resources; callback implementations own session retention and cleanup.
+   */
+  export type Callbacks = ConstructorParameters<typeof WatchTopology>[1] & {
+    /** Terminal thread loss requires the launcher to retire its watch session. */
+    onFailure(error: unknown): void;
+  };
+
+  /**
+   * An operation carries only the arguments its core member consumes.
+   *
+   * @evidence contracts/common.md#principled-implementation Discriminated method names pair each actual operation with its required payload.
+   * @evidence contracts/common.md#clear-and-simple-design One union describes the core's five transport operations.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Publications retain complete input snapshots and source proof stores without filtering.
+   * @evidence contracts/common.md#meaningful-documentation Prose identifies argument ownership and discriminated payloads.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The union executes no native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms The type chooses no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The payload grants no result reuse.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Transport and core owners retain cloned payloads rather than this type.
+   */
+  export type Operation =
+    | { method: "refresh"; notify: boolean }
+    | {
+        method: "setExtraInputs";
+        inputs: readonly string[];
+        identities?: PluginContentIdentities.Store;
+      }
+    | { method: "setProjectInputs"; inputs: ITtscProjectInputSnapshot }
+    | { method: "whenIdle" }
+    | { method: "close" };
+
+  /**
+   * Each operation receives its own correlated completion or failure.
+   *
+   * @evidence contracts/common.md#principled-implementation A per-facade monotonic id distinguishes concurrent pending operations.
+   * @evidence contracts/common.md#clear-and-simple-design Correlation is one field intersected with the operation union.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts An id identifies the actual request rather than an assumed ordered result.
+   * @evidence contracts/common.md#meaningful-documentation Prose states correlation and terminal outcomes.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The representation performs no native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms This type runs no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Request identity grants no reuse.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The facade owns pending correlation entries.
+   */
+  export type Request = { id: number } & Operation;
+
+  /**
+   * Callbacks and answers use one FIFO port, preserving their causal order.
+   *
+   * @evidence contracts/common.md#principled-implementation Event tags distinguish callbacks from correlated success or failure, and one MessagePort orders callback transmission before operation completion.
+   * @evidence contracts/common.md#clear-and-simple-design One union carries observed changes, coverage reports, recoverable errors and request outcomes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Failures retain serialized causes and actual observed input paths; no expected response replaces them.
+   * @evidence contracts/common.md#meaningful-documentation Prose states causal FIFO ordering.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The union describes portable message data without a native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms The type chooses no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each message belongs to its actual event or operation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Message and correlation retention belongs to worker and facade implementations.
+   */
+  export type Reply =
+    | { id: number; ok: true }
+    | { id: number; ok: false; error: unknown }
+    | { event: "input"; change: WatchInputChange }
+    | { event: "topology" }
+    | { event: "error"; location: string; error: unknown }
+    | { event: "roots" | "unavailable"; roots: readonly string[] };
+}

package/src/launcher/internal/watch/projectInputReloadEventShouldNotify.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
 
 import { type ProjectInputPathIdentity } from "../../../internal/pathIdentity/ProjectInputPathIdentity";
+import { type ProjectInputPathIdentityContext } from "../../../internal/pathIdentity/ProjectInputPathIdentityContext";
 import { createProjectInputPathIdentityContext } from "../../../internal/pathIdentity/createProjectInputPathIdentityContext";
 import { literalGlobRoot } from "./literalGlobRoot";
 
@@ -12,6 +13,8 @@ import { literalGlobRoot } from "./literalGlobRoot";
  * lane only after the surrounding change detector admits the event; unchanged
  * bytes remain quiet before this classifier is observed.
  *
+ * @param identities The decision's identity transaction; absence creates a
+ *   native one for this classification alone.
  * @evidence contracts/common.md#principled-implementation Exact selection files and immediate resolution-directory entries choose execution reload; a strictly nested declared glob can explain its own ancestor's membership delta without exempting unrelated selection changes.
  * @evidence contracts/common.md#clear-and-simple-design Exact-file membership, immediate-entry membership and causal explanations have distinct helpers under one classification operation.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts A data exemption must explain the same directory's observed delta, not cancel every reload because some unrelated data event occurred.
@@ -22,15 +25,17 @@ import { literalGlobRoot } from "./literalGlobRoot";
  *
  * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Identity caches and predicate collections are local to one decision, without a resident historical cache or native handle.
  */
-export function projectInputReloadEventShouldNotify(input: {
-  causedBy?: readonly string[];
-  changed?: string;
-  changedInputs: readonly string[];
-  reloadDirectories?: readonly string[];
-  reloadFiles: readonly string[];
-  globs?: readonly string[];
-}): boolean {
-  const identities = createProjectInputPathIdentityContext();
+export function projectInputReloadEventShouldNotify(
+  input: {
+    causedBy?: readonly string[];
+    changed?: string;
+    changedInputs: readonly string[];
+    reloadDirectories?: readonly string[];
+    reloadFiles: readonly string[];
+    globs?: readonly string[];
+  },
+  identities: ProjectInputPathIdentityContext = createProjectInputPathIdentityContext(),
+): boolean {
   const reloadFiles = new Set(
     input.reloadFiles.map((location) => identities.resolve(location).key),
   );

package/src/launcher/internal/watch/serveWatchTopologyWorker.ts

@@ -0,0 +1,75 @@
+import type { MessagePort } from "node:worker_threads";
+
+import { serializeCompilerError } from "../../../internal/serializeCompilerError";
+import type { WatchTopology } from "./WatchTopology";
+import type { WatchTopologyWorkerProtocol } from "./WatchTopologyWorkerProtocol";
+
+/**
+ * Serve ordered topology operations until close joins all outstanding answers.
+ *
+ * Mutation runs synchronously when its message arrives. An idle barrier yields
+ * so a later close can stop continuous native events; closing then waits for
+ * those earlier barriers to answer before closing the callback channel.
+ *
+ * @evidence contracts/common.md#principled-implementation FIFO messages invoke actual core operations in order, while close releases subscriptions before outstanding idle barriers finish and the reply port retires.
+ * @evidence contracts/common.md#clear-and-simple-design One dispatcher owns operation correlation and answer lifetime; core callbacks and filesystem decisions remain separate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The supplied core is the production owner, and serialization retains actual operation failures without fabricating completion.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains ordered mutation, yielding idle barriers and close ordering.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation MessagePort supplies portable FIFO transport; the core owns native work.
+ * @evidence contracts/performance.md#efficient-algorithms Dispatch and correlation use constant structural work per message plus cloned reply bytes; delegated topology work retains its original costs. Shutdown visits outstanding promises once.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each message invokes its own operation rather than reusing an earlier result.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources In-flight answers occupy an uncapped set and leave it on completion. Close releases the port after all accepted answers settle; core close failure still reaches the caller, which owns worker termination.
+ */
+export function serveWatchTopologyWorker(
+  topology: WatchTopology,
+  port: MessagePort,
+): void {
+  const active = new Set<Promise<void>>();
+  let closing = false;
+  port.on("message", (request: WatchTopologyWorkerProtocol.Request) => {
+    const answering = (
+      closing
+        ? Promise.reject(new Error("ttsc: watch topology is closing"))
+        : execute(topology, request)
+    ).then(
+      () => port.postMessage({ id: request.id, ok: true }),
+      (error: unknown) =>
+        port.postMessage({
+          id: request.id,
+          ok: false,
+          error: serializeCompilerError(error),
+        }),
+    );
+    active.add(answering);
+    if (request.method === "close") closing = true;
+    void answering.then(() => {
+      active.delete(answering);
+      if (request.method === "close")
+        void Promise.allSettled([...active]).then(() => port.close());
+    });
+  });
+}
+
+/** Dispatch one actual core operation; only the idle barrier yields. */
+async function execute(
+  topology: WatchTopology,
+  request: WatchTopologyWorkerProtocol.Request,
+): Promise<void> {
+  switch (request.method) {
+    case "refresh":
+      topology.refresh(request.notify);
+      break;
+    case "setExtraInputs":
+      topology.setExtraInputs(request.inputs, request.identities);
+      break;
+    case "setProjectInputs":
+      topology.setProjectInputs(request.inputs);
+      break;
+    case "whenIdle":
+      await topology.whenIdle();
+      break;
+    case "close":
+      topology.close();
+      break;
+  }
+}

package/src/launcher/internal/watch/watchTopologyWorker.ts

@@ -0,0 +1,29 @@
+/**
+ * Run the synchronous topology on its owned thread. Keeping native probes,
+ * listings and digests together preserves transaction and baseline semantics
+ * while the launcher's resident process timers remain free to run (#1758).
+ */
+import { parentPort, workerData } from "node:worker_threads";
+
+import { serializeCompilerError } from "../../../internal/serializeCompilerError";
+import { WatchTopology } from "./WatchTopology";
+import type { WatchTopologyWorkerProtocol } from "./WatchTopologyWorkerProtocol";
+import { serveWatchTopologyWorker } from "./serveWatchTopologyWorker";
+
+const port = parentPort!;
+const send = (reply: WatchTopologyWorkerProtocol.Reply): void =>
+  port.postMessage(reply);
+const topology = new WatchTopology(
+  workerData as WatchTopologyWorkerProtocol.Options,
+  {
+    onError: (location, error) =>
+      send({ event: "error", location, error: serializeCompilerError(error) }),
+    onInputChange: (change) => send({ event: "input", change }),
+    onProjectInputWatchRoots: (roots) => send({ event: "roots", roots }),
+    onProjectInputWatchUnavailable: (roots) =>
+      send({ event: "unavailable", roots }),
+    onTopologyChange: () => send({ event: "topology" }),
+  },
+);
+
+serveWatchTopologyWorker(topology, port);

package/src/plugin/CapabilityPluginResolver.ts

@@ -8,6 +8,7 @@ import { Worker } from "node:worker_threads";
 import { E2ETrace } from "../internal/E2ETrace";
 import { OwnedNativeProcess } from "../internal/OwnedNativeProcess";
 import { serializeCompilerError } from "../internal/serializeCompilerError";
+import { workerModuleUrl } from "../internal/workerModuleUrl";
 import type { ITtscCapabilityPlugin } from "./ITtscCapabilityPlugin";
 import { receiveCapabilityFailure } from "./internal/receiveCapabilityFailure";
 
@@ -22,7 +23,7 @@ import { receiveCapabilityFailure } from "./internal/receiveCapabilityFailure";
  * @evidence contracts/common.md#clear-and-simple-design This owner controls admission, worker RPC, opaque proof handles and shutdown; the worker owns synchronous discovery and the native owner controls process trees.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts No consumer inventory replaces resolver authority and no warmup, altered timeout or uncontained fallback hides a cold producer.
  * @evidence contracts/common.md#meaningful-documentation Native prose explains proof lifetime, cancellation cleanup and the independent native process owner.
- * @evidence contracts/portability.md#os-neutral-implementation The compiled worker uses the SDK's CommonJS file layout, cloned environments and platform helper resolution rather than consumer-specific paths.
+ * @evidence contracts/portability.md#os-neutral-implementation The worker requires the SDK's CommonJS source or emitted entry through a supported module URL while Node retains inherited execution options and preload hooks; cloned environments and platform helper resolution remain native inputs.
  * @evidence contracts/performance.md#efficient-algorithms One worker serves serialized requests and retains original proof closures; command output serialization scales with returned bytes and request admission grows with submitted demand.
  * @evidence contracts/performance.md#reuse-equivalent-work Worker reuse retains validated SDK caches but every resolve and currentness request still calls its original authority; proof handles never transfer freshness between generations.
  * @evidence contracts/performance.md#bound-retention-and-release-resources Explicit release drops proof handles. Close aborts admitted work, joins command supervisors and waits for worker exit; private command exchange storage is removed after its request settles.
@@ -426,7 +427,13 @@ export class CapabilityPluginResolver {
   /** Keep idle worker failures observed and prevent reuse of a retired thread. */
   private createWorker(): Worker {
     const worker = new Worker(
-      path.join(__dirname, "internal", "capabilityPluginWorker.js"),
+      workerModuleUrl(
+        path.join(
+          __dirname,
+          "internal",
+          `capabilityPluginWorker${path.extname(__filename)}`,
+        ),
+      ),
     );
     const retire = () => {
       if (this.worker === worker) this.worker = undefined;

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

@@ -21,11 +21,11 @@ import { realpathHostInputPaths } from "./realpathHostInputPaths";
  * descriptor's own external-read declarations, supply persistence premises;
  * their presence is not detection of every omitted read or side effect. An
  * answer is kept under everything else the evaluation was given: the
- * descriptor, its factory context, the effective environment it ran under, the
- * runtimes that ran it, and this ttsc build. A hit requires matching current
- * stored content/realpath projections; these sequential observations are not an
- * atomic filesystem snapshot and do not distinguish every cause of an
- * unavailable null value.
+ * descriptor, its factory context, the working directory, the effective
+ * environment, the runtimes that ran it, and this ttsc build. A hit requires
+ * matching current stored content/realpath projections; these sequential
+ * observations are not an atomic filesystem snapshot and do not distinguish
+ * every cause of an unavailable null value.
  *
  * The files a descriptor reads outside its module graph are its own to declare
  * (`hostInputHashes`), so only the answer of a descriptor supplying that
@@ -37,12 +37,12 @@ import { realpathHostInputPaths } from "./realpathHostInputPaths";
  * Startup preloads run before these observations and cannot authorize
  * persistence merely through a stable NODE_OPTIONS string.
  *
- * @evidence contracts/common.md#principled-implementation Persistent evaluation identity includes evaluator format, descriptor/context, effective environment, actual primary/secondary executable content identities and ttsc version. Acceptance checks recorded input observations and producer-declared external content, not every possible read; unobserved startup preload authority refuses persistence.
+ * @evidence contracts/common.md#principled-implementation Persistent evaluation identity includes evaluator format, descriptor/context, working directory, effective environment, actual primary/secondary executable content identities and ttsc version. Acceptance checks recorded input observations and producer-declared external content, not every possible read; unobserved startup preload authority refuses persistence.
  * @evidence contracts/common.md#clear-and-simple-design Locate/read/write separate key construction, proof validation and publication while the loader owns evaluation and its diagnostics.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts A descriptor without its explicit external-read declaration is not persisted, and the caller excludes nonempty captured diagnostics because a cache hit cannot replay them.
- * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains isolation cost, input-proof responsibility, environment identity and write refusal in distinct paragraphs; exported operation comments and tag spacing follow the documentation skill.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains isolation cost, input-proof responsibility, working-directory/environment identity and write refusal in distinct paragraphs; exported operation comments and tag spacing follow the documentation skill.
  * @evidence contracts/portability.md#os-neutral-implementation Native executable identity and same-directory publication handle OS-neutral paths; sorted environment data and actual content/lexical/physical observations detect replacement without OS-name guesses.
- * @evidence contracts/performance.md#efficient-algorithms Key construction includes environment/name sorting, context serialization, executable hashing and delegated cache-root lookup. Reads validate full JSON/maps and observe content/realpaths; writes normalize proof keys and serialize complete entries. Native path/query work and environment/context/record/file bytes contribute cost; a valid hit avoids evaluation without establishing an unmeasured launch-time ranking.
+ * @evidence contracts/performance.md#efficient-algorithms Key construction includes working-directory normalization, environment/name sorting, context serialization, executable hashing and delegated cache-root lookup. Reads validate full JSON/maps and observe content/realpaths; writes normalize proof keys and serialize complete entries. Native path/query work and environment/context/record/file bytes contribute cost; a valid hit avoids evaluation without establishing an unmeasured launch-time ranking.
  * @evidence contracts/performance.md#reuse-equivalent-work Entries share only fully keyed evaluations whose declared inputs still match; incomplete or contradictory fingerprints refuse persistence rather than reviving an unproved answer.
  * @evidence contracts/performance.md#bound-retention-and-release-resources Default JSON entries and staging leftovers are eligible for single-file pruning subject to its interval/protection/error policy; explicit roots remain caller-owned. Hits attempt usage refresh, and writes attempt staging removal in finally. Cleanup or later pruning can fail; no unconditional deletion, entry-count or byte ceiling is supplied here.
  */
@@ -89,18 +89,19 @@ export namespace PluginDescriptorEvaluationCache {
    * @param props.cacheDir The plugin cache directory the caller selected.
    * @param props.request The resolved descriptor module.
    * @param props.context The factory context the descriptor is invoked with.
+   * @param props.cwd The working directory passed to the actual evaluator.
    * @param props.env The complete environment the evaluation runs under.
    * @param props.runtime The runtime executable that evaluates it.
    * @param props.additionalRuntime Selected Node executable exposed to the
    *   descriptor and used by ttsx/config loaders, when distinct from runtime.
    * @param props.version This ttsc build's version.
-   * @evidence contracts/common.md#principled-implementation Canonical identity includes factory context, sorted effective environment and fresh content/lexical/physical proof of both actual runtime authorities; unobserved startup preloads and unreadable runtimes cannot select a reusable entry.
+   * @evidence contracts/common.md#principled-implementation Canonical identity includes factory context, normalized evaluator working directory, sorted effective environment and fresh content/lexical/physical proof of both actual runtime authorities; unobserved startup preloads and unreadable runtimes cannot select a reusable entry.
    * @evidence contracts/common.md#clear-and-simple-design The locator delegates cache-root policy and runtime observation, then constructs only the descriptor entry identity.
    * @evidence contracts/common.md#prohibited-implementation-shortcuts Unidentifiable runtime/storage returns null for uncached evaluation rather than weakening the key or selecting a fixture-specific runtime.
    * @evidence contracts/common.md#meaningful-documentation Native JSDoc identifies every key premise and null result; parameter entries and separate tags follow the documentation skill.
-   * @evidence contracts/portability.md#os-neutral-implementation Native realpath/stat and path.resolve/join preserve executable and cache paths; environment ordering is lexical map data, not shell syntax.
+   * @evidence contracts/portability.md#os-neutral-implementation Native realpath/stat and path.resolve/join preserve executable, working-directory and cache paths; environment ordering is lexical map data, not shell syntax.
    * @evidence contracts/performance.md#efficient-algorithms Environment entries are merged/filtered/sorted by name bytes; context and key fields are serialized and hashed. Primary/secondary executable observation uses bounded read buffers but native metadata/path and escaping identity text also cost work; identical supplied spellings share one proof. Delegated root selection can walk ancestors/read manifests and inspect cache layout, so environment/runtime bytes are not the complete cost dimensions.
-   * @evidence contracts/performance.md#reuse-equivalent-work The key shares only evaluations with identical descriptor/context/environment/runtime/version authorities; observed source state is separately checked by read.
+   * @evidence contracts/performance.md#reuse-equivalent-work The key shares only evaluations with identical descriptor/context/working-directory/environment/runtime/version authorities; observed source state is separately checked by read.
    *
    * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The locator stores no handle or historical entry population; executable observation owns its transient descriptor/close attempt and returns an unproved result on failure. Serialized key/context and returned path transfer without freezing mutable caller authority; persistence/pruning own stored entry lifetime.
    */
@@ -114,10 +115,13 @@ export namespace PluginDescriptorEvaluationCache {
     /** Complete JSON-serializable factory context passed to evaluation. */
     context: unknown;
 
+    /** Actual evaluator working directory, independent of its factory context. */
+    cwd: string;
+
     /** Complete child environment, with undefined values omitted from identity. */
     env: NodeJS.ProcessEnv;
 
-    /** Consumer project anchoring cache-root selection. */
+    /** Project anchoring cache-root selection. */
     projectRoot: string;
 
     /** Resolved descriptor entry module whose evaluation is cached. */
@@ -167,6 +171,7 @@ export namespace PluginDescriptorEvaluationCache {
           props.version,
           path.resolve(props.request),
           props.context,
+          path.resolve(props.cwd),
           Object.entries(environment)
             .filter(
               (entry): entry is [string, string] => entry[1] !== undefined,

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

@@ -6,6 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { readJsonFile } from "../../../compiler/internal/project/readJsonFile";
 import { isRelativePluginSpecifier } from "./isRelativePluginSpecifier";
 import { moduleResolutionBaseSelects } from "./moduleResolutionBaseSelects";
+import { pluginResolutionFailure } from "./pluginResolutionFailure";
 
 /**
  * How ttsc finds a plugin package and reads its manifest.
@@ -277,7 +278,7 @@ export namespace PluginPackageResolution {
   }
 
   /**
-   * Resolve a plugin specifier from the project root, using realpath when
+   * Resolve a plugin specifier from its consumer directory, using realpath when
    * available and retaining selected native spelling on canonicalization
    * failure.
    *
@@ -290,7 +291,7 @@ export namespace PluginPackageResolution {
    * @evidence contracts/common.md#principled-implementation Native absolute/relative inputs use their explicit base; bare packages opt into ttsc target semantics only when a matching branch exists, otherwise createRequire anchors Node resolution at the consuming project's package.json. This authority remains explicit when the caller was itself imported as CommonJS through an ESM loader.
    * @evidence contracts/common.md#clear-and-simple-design One dispatcher keeps plugin-only conditions local and returns best-effort canonical selection to descriptor loading; unsuccessful realpath is not physical-identity proof.
    * @evidence contracts/common.md#prohibited-implementation-shortcuts Dedicated condition selection is a declared package extension, not process-wide patching; opted-in invalid targets fail without falling back to unrelated runtime exports.
-   * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains path versus package behavior and condition scope; helper comments explain error/null semantics and target constraints, with separated prose under the documentation skill.
+   * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains path versus package behavior and condition scope; package failures retain their cause and code while naming the requested plugin and consumer directory, including runtimes whose resolver message is empty.
    * @evidence contracts/portability.md#os-neutral-implementation Native path classification/resolution and best-effort realpath preserve caller bases. Package target URL resolution uses a native pathToFileURL anchor and fileURLToPath decoding before native containment/file checks; URL/export grammar is not interpreted as literal native percent spelling.
    * @evidence contracts/performance.md#efficient-algorithms Path cases still perform native normalization/realpath; package cases include manifest discovery/read/parse and Node queries. Export selection classifies keys, compares patterns and may recursively substitute/inspect target nodes before short-circuit target resolution. Key/target/path/manifest bytes and native operations contribute cost; no target depth or size ceiling is supplied here.
    *
@@ -313,14 +314,18 @@ export namespace PluginPackageResolution {
     // loading the transform would have to build the runtime the transform
     // emits). Such a package opts in with a `ttsc` export condition that points
     // at a runtime-free descriptor; honour it here, scoped to plugin resolution.
-    const conditioned = resolvePluginExportCondition(specifier, projectRoot);
-    if (conditioned !== null) {
-      return conditioned;
+    try {
+      const conditioned = resolvePluginExportCondition(specifier, projectRoot);
+      if (conditioned !== null) {
+        return conditioned;
+      }
+      const projectRequire = createRequire(
+        path.join(projectRoot, "package.json"),
+      );
+      return resolveRealPath(projectRequire.resolve(specifier));
+    } catch (error) {
+      throw pluginResolutionFailure(specifier, projectRoot, error);
     }
-    const projectRequire = createRequire(
-      path.join(projectRoot, "package.json"),
-    );
-    return resolveRealPath(projectRequire.resolve(specifier));
   }
 
   /**

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

@@ -9,12 +9,10 @@ import { isRelativePluginSpecifier } from "./isRelativePluginSpecifier";
  * The plugin entries a project declares, from its `tsconfig.json` and from the
  * `ttsc` block of its direct dependencies' manifests.
  *
- * Every entry carries the directory its specifier resolves from. A bare package
- * specifier resolves from the project root, never from the base config an
- * `extends` chain declared it in. A configured relative entry uses its known
- * declaring directory, falling back to project root; an automatic relative
- * marker uses its package directory. Explicit invocation lists use project root
- * for every entry, rather than recovering declaration provenance.
+ * Every entry carries the directory its specifier resolves from. Bare packages
+ * and explicit invocation lists use pluginConfigDir when supplied, otherwise
+ * the selected config directory. Configured relative entries retain their
+ * declaring directory; automatic relative markers use their package directory.
  *
  * @evidence contracts/common.md#principled-implementation Explicit entries replace discovery; otherwise inherited relative transforms retain their declaring base while bare packages resolve from the consumer, followed by distinct direct-dependency markers.
  * @evidence contracts/common.md#clear-and-simple-design Entry extraction owns ordering/provenance and delegates physical package resolution; descriptor execution/building remain outside discovery.
@@ -27,6 +25,32 @@ import { isRelativePluginSpecifier } from "./isRelativePluginSpecifier";
  * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Discovery collections and returned entries are call-owned; no retained resource or cross-call population is acquired.
  */
 export namespace ProjectPluginEntries {
+  /**
+   * Select the consumer directory for plugin packages and factory contexts.
+   *
+   * Generated configs supply their original directory through pluginConfigDir.
+   * The compiler's source root can include sibling packages and does not choose
+   * the consumer's dependencies.
+   *
+   * @evidence contracts/common.md#principled-implementation The selected config owns the consumer dependency lookup; an explicit pluginConfigDir restores that authority for generated wrappers independently of the compiler source root.
+   * @evidence contracts/common.md#clear-and-simple-design One path selection is shared by entry discovery, presence, host-input observation and factory contexts.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Caller-declared wrapper provenance and the selected config determine the directory without package names or fixture paths.
+   * @evidence contracts/common.md#meaningful-documentation The comment explains the consumer anchor and why sibling-source roots cannot replace it.
+   * @evidence contracts/portability.md#os-neutral-implementation Native dirname and resolve preserve config path identity and resolve explicit relative origins from the recorded invocation cwd.
+   * @evidence contracts/performance.md#efficient-algorithms Selection performs native path operations proportional to path text without filesystem traversal.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This path selection owns no reusable observation or cross-call cache.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources It returns a string and acquires no resource or retained population.
+   */
+  export function resolvePluginBaseDir(
+    project: ITtscParsedProjectConfig,
+    pluginConfigDir?: string,
+  ): string {
+    return pluginConfigDir === undefined || pluginConfigDir === ""
+      ? path.dirname(project.path)
+      : path.resolve(project.identity.invocationCwd, pluginConfigDir);
+  }
+
   /**
    * One declared plugin and the directory its specifier resolves from.
    *
@@ -66,16 +90,18 @@ export namespace ProjectPluginEntries {
   export function resolvePluginEntries(
     project: ITtscParsedProjectConfig,
     entries?: readonly ITtscProjectPluginConfig[],
+    pluginConfigDir?: string,
   ): ProjectPluginEntry[] {
+    const consumerDir = resolvePluginBaseDir(project, pluginConfigDir);
     if (entries !== undefined) {
       return entries.map((config) => ({
-        baseDir: project.root,
+        baseDir: consumerDir,
         config,
       }));
     }
     const configured = project.compilerOptions.plugins.map((config, index) => {
-      // A bare/package plugin specifier (e.g. "typia/lib/transform") must resolve
-      // from the project's own node_modules, not from the tsconfig that declared
+      // A bare package specifier resolves from the consumer's dependencies,
+      // not from the tsconfig that declared
       // it: an `extends`ed base config (a shared `tests/config/tsconfig.json`)
       // declares the plugin, but the package is installed under the consuming
       // project. Only a relative specifier ("./plugin") is meaningful relative to
@@ -86,22 +112,21 @@ export namespace ProjectPluginEntries {
         isRelativePluginSpecifier(config.transform) &&
         declaringDir !== undefined
           ? declaringDir
-          : project.root;
+          : consumerDir;
       return { baseDir, config };
     });
     return [
       ...configured,
-      ...discoverPackagePluginEntries(project, configured),
+      ...discoverPackagePluginEntries(consumerDir, configured),
     ];
   }
 
   function discoverPackagePluginEntries(
-    project: ITtscParsedProjectConfig,
+    consumerDir: string,
     configured: readonly ProjectPluginEntry[],
   ): ProjectPluginEntry[] {
-    const projectPackageJson = PluginPackageResolution.findNearestPackageJson(
-      project.root,
-    );
+    const projectPackageJson =
+      PluginPackageResolution.findNearestPackageJson(consumerDir);
     if (projectPackageJson === undefined) {
       return [];
     }

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

@@ -3,11 +3,14 @@ import path from "node:path";
 
 import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITtscParsedProjectConfig";
 import { PluginPackageResolution } from "./PluginPackageResolution";
+import { ProjectPluginEntries } from "./ProjectPluginEntries";
 import { moduleResolutionBaseSelects } from "./moduleResolutionBaseSelects";
 
 /**
  * Return config ancestry and package-discovery manifest inputs, including
  * missing nearer candidates that could redirect the selected package later.
+ * Discovery uses the selected config directory or explicit pluginConfigDir,
+ * matching the entry resolver independently of the compiler's source root.
  *
  * @evidence contracts/common.md#principled-implementation Config ancestry, lexical selection and missing config candidates influence selection; automatic discovery additionally observes nearest manifest and dependency search candidates through the selecting root. The project reader separately states whether these config observations are complete.
  * @evidence contracts/common.md#clear-and-simple-design The collector obtains package resolution from its owner and assembles universal loader inputs, leaving source Program dependencies to the native reference graph.
@@ -22,6 +25,7 @@ import { moduleResolutionBaseSelects } from "./moduleResolutionBaseSelects";
 export function collectProjectHostInputs(
   project: ITtscParsedProjectConfig,
   includePluginDiscovery: boolean = true,
+  pluginConfigDir?: string,
 ): string[] {
   const inputs = new Set<string>(
     [...project.configPaths, ...(project.configInputs ?? [])].map((file) =>
@@ -30,7 +34,9 @@ export function collectProjectHostInputs(
   );
   if (!includePluginDiscovery) return [...inputs].sort();
   const manifestCandidates =
-    PluginPackageResolution.collectNearestPackageJsonCandidates(project.root);
+    PluginPackageResolution.collectNearestPackageJsonCandidates(
+      ProjectPluginEntries.resolvePluginBaseDir(project, pluginConfigDir),
+    );
   for (const candidate of manifestCandidates) inputs.add(candidate);
   const manifest = manifestCandidates.find(
     PluginPackageResolution.existingFile,

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

@@ -11,6 +11,8 @@ import { ProjectPluginEntries } from "./ProjectPluginEntries";
  * omitted entries can therefore read manifests and resolve native packages.
  *
  * @param entries - Explicit entries; `false` always returns `false`.
+ * @param pluginConfigDir - Original consumer directory for generated configs;
+ *   omitted entries otherwise discover from the selected config directory.
  * @evidence contracts/common.md#principled-implementation Explicit false disables all plugin discovery; otherwise the shared entry resolver's enabled-not-false predicate checks the same population the loader would consider.
  * @evidence contracts/common.md#clear-and-simple-design The presence query delegates config/package selection to its owner instead of reproducing descriptor evaluation or build logic.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Enabled selection follows declared configuration, without assuming a known package marker or fabricating absence after a resolver error.
@@ -23,11 +25,14 @@ import { ProjectPluginEntries } from "./ProjectPluginEntries";
 export function hasProjectPluginEntries(
   project: ITtscParsedProjectConfig,
   entries?: readonly ITtscProjectPluginConfig[] | false,
+  pluginConfigDir?: string,
 ): boolean {
   if (entries === false) {
     return false;
   }
-  return ProjectPluginEntries.resolvePluginEntries(project, entries).some(
-    (entry) => entry.config.enabled !== false,
-  );
+  return ProjectPluginEntries.resolvePluginEntries(
+    project,
+    entries,
+    pluginConfigDir,
+  ).some((entry) => entry.config.enabled !== false);
 }