@ttsc/unplugin 0.31.0 → 0.31.2

package/src/core/transform/tracker/broker/openBrokeredWatch.ts

@@ -7,6 +7,7 @@ import { WATCH_PROBE_DIRECTORY_PREFIX } from "./WATCH_PROBE_DIRECTORY_PREFIX";
 import { WATCH_PROBE_TIMEOUT_MS } from "./WATCH_PROBE_TIMEOUT_MS";
 import type { WatchBrokerLocation } from "./WatchBrokerLocation";
 import type { WatchBrokerSink } from "./WatchBrokerSink";
+import { WatchBrokerTransport } from "./WatchBrokerTransport";
 import { drainWatchBroker } from "./drainWatchBroker";
 import { getWatchBroker } from "./getWatchBroker";
 import { probeForLocation } from "./probeForLocation";
@@ -16,11 +17,11 @@ import { sweepAbandonedWatchProbes } from "./sweepAbandonedWatchProbes";
  * Open directory watches in the isolated watch process for one sink, and report
  * when they hear.
  *
- * On Windows, Node's fs-event backend can assert in native code when a watched
- * temporary tree is deleted. Isolation turns that unrecoverable process abort
- * into an ordinary broker exit and a conservative fallback in the host. On
- * macOS, each registration's watches are streams of their own, started before
- * the child reports ready, and a dropped event reaches the sink as a gap
+ * On Windows, ttsc's native helper owns completion-port directory subscriptions
+ * and omits access-only notifications (#1719). Native loss and failure withdraw
+ * coverage; actual change events remain authoritative even after A-B-A writes.
+ * On macOS, each registration's watches are streams of their own, started
+ * before the child reports ready, and a dropped event reaches the sink as a gap
  * (samchon/ttsc#1425). A stream that can be probed reports ready only once its
  * opening probe came back through it; the child suppresses ordinary callbacks
  * received before that probe. This is its backend protocol, not a guarantee
@@ -143,10 +144,7 @@ export function openBrokeredWatch(
     };
   });
   broker.pendingRegistrations += 1;
-  broker.child.ref();
-  // Bun's IPC channel omits Node's Control.ref/unref methods. The child itself
-  // still owns the outstanding acknowledgement on that runtime.
-  broker.child.channel?.ref?.();
+  WatchBrokerTransport.reference(broker, true);
   const id = broker.nextId++;
   let resolveReady!: () => void;
   const answered = new Promise<void>((resolve) => {
@@ -166,7 +164,7 @@ export function openBrokeredWatch(
     let failed = false;
     let failure: unknown;
     try {
-      broker.child.send?.({ id, op: "remove" });
+      WatchBrokerTransport.send(broker, { id, op: "remove" });
     } catch (error) {
       failed = true;
       failure = error;
@@ -176,7 +174,7 @@ export function openBrokeredWatch(
         WATCH_BROKER.current = undefined;
       }
       try {
-        broker.child.disconnect?.();
+        WatchBrokerTransport.close(broker);
       } catch (error) {
         if (!failed) {
           failed = true;
@@ -194,7 +192,7 @@ export function openBrokeredWatch(
     }
     if (failed) throw failure;
   };
-  broker.child.send?.({
+  WatchBrokerTransport.send(broker, {
     allEvents: options.allEvents,
     locations: normalized,
     id,
@@ -226,8 +224,7 @@ export function openBrokeredWatch(
     // a reply over an unreferenced channel lets the loop empty and the process
     // exit mid-build.
     if (broker.pendingRegistrations === 0 && broker.pendingDrains === 0) {
-      broker.child.unref();
-      broker.child.channel?.unref?.();
+      WatchBrokerTransport.reference(broker, false);
     }
   });
   return {

package/src/core/transform/tracker/broker/usesWatchBroker.ts

@@ -4,13 +4,13 @@ import type { TtscTransformFilesystemOperations } from "../../filesystem/TtscTra
  * Whether a tracker over `filesystem` opens its watches in the isolated watch
  * broker rather than in this process.
  *
- * The host filesystem on Windows and macOS does: Windows so that a native
- * fs-event abort cannot take the host down, and macOS so that each watch is its
- * own FSEventStream, whose dropped events are reported, rather than one libuv
- * re-creates whenever any watch in the host opens or closes, and whose drops it
- * discards (samchon/ttsc#1418, samchon/ttsc#1425). An embedder that supplies
- * its own `watch` retains that capability, including for a host-filesystem
- * view.
+ * The host filesystem on Windows and macOS does: Windows so that native
+ * mutation filters exclude access-time noise without a Node fs-event handle,
+ * and macOS so that each watch is its own FSEventStream, whose dropped events
+ * are reported, rather than one libuv re-creates whenever any watch in the host
+ * opens or closes, and whose drops it discards (samchon/ttsc#1418,
+ * samchon/ttsc#1425). An embedder that supplies its own `watch` retains that
+ * capability, including for a host-filesystem view.
  *
  * @evidence contracts/common.md#principled-implementation
  *   A supplied filesystem watcher is authoritative; only the native host

package/src/core/transform/tracker/broker/watchBrokerSource.ts

@@ -8,13 +8,10 @@ import { WATCH_PROBE_TIMEOUT_MS } from "./WATCH_PROBE_TIMEOUT_MS";
  * frontier described below; a reply alone does not certify every scope, since
  * probe-dependent streams can be named unproven and gaps withdraw authority.
  *
- * On Windows the watches are `fs.watch`. A drain yields through two immediate
- * turns to allow the loop to poll and deliver queued callbacks before replying.
- * The real Windows scenario checks two hundred synchronous write/drain pairs;
- * the scripted unit checks this scheduling boundary separately. These checks
- * are not a universal kernel-order proof: FIFO completion-port queueing alone
- * does not guarantee dequeue order or establish when notification completion
- * becomes observable relative to a write and IPC request.
+ * Windows production registrations use ttsc's native helper, not this program
+ * (#1719). The optional fs.watch backend remains an explicit direct program
+ * capability used by its scripted protocol tests; it never supplies Windows
+ * production cache proof. Its drain yields through two immediate turns.
  *
  * On macOS the watches go through the `fsevents` binding, one FSEventStream per
  * location, instead of relying on `fs.watch` for stream and loss authority
@@ -59,11 +56,13 @@ import { WATCH_PROBE_TIMEOUT_MS } from "./WATCH_PROBE_TIMEOUT_MS";
  *   The child protocol keeps per-registration streams and ordered drains;
  *   macOS proof requires clean probe delivery. Loss flags withdraw coverage
  *   before probe recognition, so matching a probe name cannot erase that warning.
- *   The Windows two-turn frontier retains its runtime/backend ordering premise;
+ *   The optional fs.watch two-turn frontier retains its runtime/backend ordering premise;
  *   this source does not independently prove kernel completeness.
  * @evidence contracts/common.md#clear-and-simple-design
- *   One maintained child program serves both native backends; this function only
- *   injects resolved capability and the shared timeout, with JSON-safe path encoding.
+ *   One maintained child program serves macOS and the explicitly selected
+ *   fs.watch protocol capability; Windows production uses its native helper.
+ *   This function injects resolved capability and the shared timeout with
+ *   JSON-safe path encoding.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts
  *   Native flags and deadlines express backend contracts, not fixture-specific
  *   repairs. Missing bindings and probes report uncertainty rather than silent success.
@@ -351,7 +350,7 @@ function drain(requestId) {
       entry.abandon();
     }
   }
-  // Windows watches, and streams already proven, answer after two turns: the
+  // Explicit fs.watch watches, and streams already proven, answer after two turns: the
   // first lets the loop poll for completions the kernel had already queued,
   // the second answers after their callbacks.
   outstanding += 1;

package/src/core/transform/transformTtsc.ts

@@ -10,37 +10,28 @@ import { TRANSFORM_RESULT_FILESYSTEM } from "./cache/TRANSFORM_RESULT_FILESYSTEM
 import type { TtscTransformCache } from "./cache/TtscTransformCache";
 import { awaitOrEvict } from "./cache/awaitOrEvict";
 import { createTransformCacheKey } from "./cache/createTransformCacheKey";
-import { disposeCachedTransform } from "./cache/disposeCachedTransform";
 import { evictGeneration } from "./cache/evictGeneration";
 import { replaysTerminalGeneration } from "./cache/replaysTerminalGeneration";
 import { selectCachedGenerationAction } from "./cache/selectCachedGenerationAction";
-import { selectOrEvict } from "./cache/selectOrEvict";
 import { transformCacheEpoch } from "./cache/transformCacheEpoch";
 import { transformCacheTrustsNotifications } from "./cache/transformCacheTrustsNotifications";
 import { transformFilesystem } from "./cache/transformFilesystem";
 import { withdrawGenerationNotifications } from "./cache/withdrawGenerationNotifications";
-import { reportMissingProgramOutput } from "./diagnostics/reportMissingProgramOutput";
-import { reportSuccessDiagnostics } from "./diagnostics/reportSuccessDiagnostics";
-import type { TtscTransformedOutput } from "./envelope/TtscTransformedOutput";
-import { TtscMissingProgramOutputError } from "./errors/TtscMissingProgramOutputError";
+import { deliverCachedTransform } from "./deliverCachedTransform";
 import { TtscUnstableGenerationError } from "./errors/TtscUnstableGenerationError";
 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 { resolveProjectSelection } from "./tsconfig/resolveProjectSelection";
-import { createTransformResult } from "./utils/createTransformResult";
 import { isDeclarationFile } from "./utils/isDeclarationFile";
 import { isHostWrapperQuery } from "./utils/isHostWrapperQuery";
 import { pluginsAreDisabled } from "./utils/pluginsAreDisabled";
 import { stripQuery } from "./utils/stripQuery";
-import { markCachedSourceServed } from "./validation/markCachedSourceServed";
+import { TtscGenerationProof } from "./validation/TtscGenerationProof";
 import type { TtscTransformHooks } from "./watch/TtscTransformHooks";
 import type { TtscWatchSelection } from "./watch/TtscWatchSelection";
-import { notifyFailedGenerationInputs } from "./watch/notifyFailedGenerationInputs";
 import { notifyRejectedGenerationInputs } from "./watch/notifyRejectedGenerationInputs";
-import { notifyVolatileDelivery } from "./watch/notifyVolatileDelivery";
-import { notifyWatchInputs } from "./watch/notifyWatchInputs";
 import { prepareProjectRecordDirectories } from "./watch/prepareProjectRecordDirectories";
 
 /**
@@ -78,7 +69,7 @@ import { prepareProjectRecordDirectories } from "./watch/prepareProjectRecordDir
  *   per build, not per compilation.
  * @evidence contracts/common.md#principled-implementation Project selection and generation-qualified cache admission preserve compiler disk authority; fresh-only success additionally needs an explicit nonwatching lifecycle, coherent project declaration and actual host-cache withdrawal, because incomplete observation cannot support watch invalidation.
  * @evidence contracts/common.md#clear-and-simple-design One delivery coordinator composes project selection, cache admission, compilation, output selection and host notifications; dedicated owners handle proof and lifetime internals.
- * @evidence contracts/common.md#prohibited-implementation-shortcuts Wrapper modules cannot poison source baselines and incomplete generations cannot authorize reuse; a separately admitted fresh-only result is evicted before capability checks, unknown or watching lifecycles fail explicitly, and unsupported withdrawal cannot be replaced by a fake record or guessed dependency closure.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Wrapper modules cannot poison source baselines; incomplete local results can share only explicitly nonwatching first deliveries in their exact pass. Unknown/watching lifecycles or unsupported withdrawal reject and evict them rather than invent persistent records or dependency closure.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs and argument tags explain project scope, no-transform outcomes, cache epochs and per-build notification responsibilities with links to maintained reference context.
  * @evidence contracts/performance.md#efficient-algorithms
  *   Selection/key construction pays ancestor/config/alias/option/path text work.
@@ -86,15 +77,18 @@ import { prepareProjectRecordDirectories } from "./watch/prepareProjectRecordDir
  *   replay source/project/external/universal proofs before selecting output.
  *   In-flight/valid completed reuse avoids compilation, not those checks or
  *   output/map/notification/record work. Capture misses pay whole native compile
- *   and input populations; concurrent supersession can repeat the outer loop
+ *   and input populations. The common proof owner skips redundant environment
+ *   preparation for proven first deliveries and shares synchronous native proof
+ *   queries; persistent/repeated delivery establishes fresh authority. Concurrent supersession can repeat the outer loop
  *   without a delivery-level retry/time bound here.
  * @evidence contracts/performance.md#reuse-equivalent-work Cache identity covers config/options/plugins/aliases; current generations, pass-qualified terminal verdicts and in-flight Promises are shared only while their source and dependency proof remains valid.
  * @evidence contracts/performance.md#bound-retention-and-release-resources
  *   Optional cache state retains current generation Promises/results and
  *   per-key dependency/case facts without a byte/key cap here. Native tasks
  *   belong to compiler/capture owners; uncached captures retain no notification
- *   or persistent clock probe. Fresh-only delivery detaches its generation
- *   before host callbacks; eviction/disposal attempt independent resource release
+ *   or persistent clock probe. Fresh-only delivery releases capture resources,
+ *   retaining only an explicitly admitted local pass result; rejected or failed
+ *   incomplete handoff detaches its generation. Eviction/disposal attempt independent resource release
  *   and native failures need not close every handle or remove every probe.
  * @evidence contracts/portability.md#os-neutral-implementation Native module paths and project coordinates use supported path/filesystem abstractions, while actual case policy and watcher capability come from generation proof rather than OS-name assumptions.
  */
@@ -171,6 +165,8 @@ export async function transformTtsc(
           await preparePluginBuildEnvironments(
             terminal.validation.cached.result,
             filesystem,
+            undefined,
+            terminal.validation.cached.projectRoot,
           );
           if (cache?.get(key) !== transformed) continue;
         }
@@ -218,15 +214,18 @@ export async function transformTtsc(
       if (!transformCacheTrustsNotifications(cache)) {
         withdrawGenerationNotifications(cached);
       }
-      await preparePluginBuildEnvironments(cached.result, filesystem, cached);
-      if (cache?.get(key) !== transformed) continue;
       if (epoch === undefined) {
         await settleProjectMutationEvents(cached);
         if (cache?.get(key) !== transformed) {
           continue;
         }
       }
+      await TtscGenerationProof.prepare(cached, file, epoch);
+      if (cache?.get(key) !== transformed) continue;
+      // No await between this observation and synchronous admission.
+      const proof = TtscGenerationProof.create(cached, file, epoch);
       const action = selectCachedGenerationAction({
+        proof,
         cache,
         cached,
         epoch,
@@ -239,36 +238,17 @@ export async function transformTtsc(
         continue;
       }
       if (action === "serve") {
-        reportSuccessDiagnostics(cached, epoch);
-        // A resolved `"exception"` / `"failure"` envelope makes this throw;
-        // that is a failed generation too, so it is retained for this pass or
-        // evicted outside one before being surfaced.
-        let output: TtscTransformedOutput;
-        try {
-          output = selectOrEvict(cache, key, transformed, epoch, {
-            file,
-            projectRoot: cached.projectRoot,
-            result: cached.result,
-            tsconfig: cached.tsconfig,
-          });
-        } catch (error) {
-          if (!(error instanceof TtscMissingProgramOutputError)) {
-            notifyFailedGenerationInputs(hooks, cached, file, watchSelection);
-            throw error;
-          }
-          // The compile is fine and simply has nothing for this module, so the
-          // module goes back to the host untransformed rather than failing the
-          // build (samchon/ttsc#1308). Its project config and selection inputs
-          // still decide whether a later generation will contain this module,
-          // so hosts must receive the same universal watch-input batch.
-          reportMissingProgramOutput(cached, error, epoch);
-          notifyWatchInputs(hooks, cached, file, watchSelection);
-          markCachedSourceServed(cached, file);
-          return undefined;
-        }
-        notifyWatchInputs(hooks, cached, file, watchSelection);
-        markCachedSourceServed(cached, file);
-        return createTransformResult(file, source, output);
+        return deliverCachedTransform({
+          cache,
+          cached,
+          generation: transformed,
+          key,
+          epoch,
+          file,
+          source,
+          hooks,
+          selection: watchSelection,
+        });
       }
       transformed = undefined;
     }
@@ -336,50 +316,16 @@ export async function transformTtsc(
         policies.set(key, reported);
       }
     }
-    const { projectRoot, result } = cached;
-    if (cached.freshDeliveryOnly === true) {
-      // This delivery owns a newly compiled answer, but unavailable observer
-      // authority cannot certify any later resident or host-cache delivery.
-      // Eviction schedules resource release even if a host callback throws.
-      if (cache === undefined) disposeCachedTransform(cached);
-      else evictGeneration(cache, key, generation);
-      if (
-        result.type === "success" &&
-        (hooks?.watching !== false ||
-          hooks.markVolatile === undefined ||
-          (hooks.project?.watching !== undefined &&
-            hooks.project.watching !== hooks.watching))
-      ) {
-        throw new Error(
-          "@ttsc/unplugin: plugin input observation is unavailable; fresh output " +
-            "requires an explicitly nonwatching host with supported cache withdrawal. " +
-            "Watching, unknown or contradictory lifecycles cannot safely observe its changes.",
-        );
-      }
-      hooks?.markVolatile?.();
-    }
-    reportSuccessDiagnostics(cached, epoch);
-    let output: TtscTransformedOutput;
-    try {
-      output = selectOrEvict(cache, key, generation, epoch, {
-        file,
-        projectRoot,
-        result,
-        tsconfig: cached.tsconfig,
-      });
-    } catch (error) {
-      if (!(error instanceof TtscMissingProgramOutputError)) {
-        notifyFailedGenerationInputs(hooks, cached, file, watchSelection);
-        throw error;
-      }
-      reportMissingProgramOutput(cached, error, epoch);
-      notifyWatchInputs(hooks, cached, file, watchSelection);
-      markCachedSourceServed(cached, file);
-      return undefined;
-    }
-    notifyWatchInputs(hooks, cached, file, watchSelection);
-    markCachedSourceServed(cached, file);
-    notifyVolatileDelivery(hooks, cached, file);
-    return createTransformResult(file, source, output);
+    return deliverCachedTransform({
+      cache,
+      cached,
+      generation,
+      key,
+      epoch,
+      file,
+      source,
+      hooks,
+      selection: watchSelection,
+    });
   }
 }

package/src/core/transform/validation/TtscGenerationProof.ts

@@ -0,0 +1,201 @@
+import { PluginBuildEnvironmentReadings } from "ttsc/plugin-source";
+
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import type { TtscTransformCache } from "../cache/TtscTransformCache";
+import { disposeCachedTransform } from "../cache/disposeCachedTransform";
+import { evictGeneration } from "../cache/evictGeneration";
+import { resultFilesystem } from "../cache/resultFilesystem";
+import { envelopeDerivation } from "../envelope/envelopeDerivation";
+import { selectPluginSourceInputs } from "../envelope/selectPluginSourceInputs";
+import { pathIdentityKey } from "../filesystem/pathIdentityKey";
+import { preparePluginBuildEnvironments } from "../inputs/preparePluginBuildEnvironments";
+import { toProjectKey } from "../project/toProjectKey";
+import type { TtscTransformHooks } from "../watch/TtscTransformHooks";
+
+/**
+ * The shared ownership boundary for generation reuse in every adapter.
+ *
+ * WARNING (#1712, #1713): a module, a synchronous input-proof transaction, a
+ * delivery pass, and a persistent generation have different lifetimes. Keep
+ * those distinctions here. Do not add native preparation before every module,
+ * keep positive toolchain checks for a whole process, or make Bun's adapter
+ * invent its own cache policy. A proven pass shares its first deliveries;
+ * persistent/repeated deliveries require new current observations. Incomplete
+ * observations can share a coherent local result only inside an explicitly
+ * nonwatching pass with actual host-cache withdrawal, never a record or pool.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit pass identity, source baseline and first-delivery membership delimit sharing; synchronous transactions independently qualify current native inputs and incomplete local outputs retain stricter lifecycle admission.
+ * @evidence contracts/common.md#clear-and-simple-design One core owner supplies the same preparation, pass and fresh-only policies to every adapter instead of separate host-specific caches.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observation never becomes complete snapshot authority; watching, persistent, repeated and unknown boundaries cannot borrow an incomplete pass result.
+ * @evidence contracts/common.md#meaningful-documentation Native context names the four lifetimes and warns against the specific performance and stale-cache regressions they prevent.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Members delegate native observations to the generation's filesystem and the native environment owner.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Members own baseline lookup, batch qualification and admission.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Members establish the distinct sharing boundaries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no registry; transactions and generations have explicit callers.
+ */
+export namespace TtscGenerationProof {
+  /**
+   * One synchronous admission after all asynchronous preparation has settled.
+   * Never retain this object in a generation or use it after an await.
+   *
+   * @evidence contracts/common.md#principled-implementation The exact cached owner prevents a proof of another result from supplying authority; optional native verdict is earned only by this synchronous transaction.
+   * @evidence contracts/common.md#clear-and-simple-design One transaction carries environment observations and the shared native predicate verdict.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Absent environment or predicate proof remains absent, never implied success.
+   * @evidence contracts/common.md#meaningful-documentation Prose states the no-await lifetime and members distinguish owner, environment and predicate authority.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Native identity is retained by the referenced generation, not inferred by this carrier.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms This carrier executes no computation.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The creating operation and validators own sharing decisions.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous caller owns this handle-free carrier.
+   */
+  export interface Transaction {
+    /** Exact generation being synchronously admitted. */
+    readonly cached: TtscCachedProjectTransform;
+
+    /** Current batch, absent when the pass already owns this input proof. */
+    readonly environments?: ReadonlyMap<string, string | undefined>;
+
+    /** Current native predicate verdict, unbuilt until its first gate. */
+    nativePredicates?: boolean;
+  }
+
+  /**
+   * Prepare native authority only when this delivery needs a new input proof.
+   * The caller must create its synchronous transaction after awaiting this.
+   *
+   * @evidence contracts/common.md#principled-implementation A qualified first-delivery pass already owns environment proof; all other requests prepare actual authority before synchronous admission.
+   * @evidence contracts/common.md#clear-and-simple-design One branch delegates native preparation rather than repeating it in adapters.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the existing explicit pass contract permits skipping preparation; no watcher silence or process lifetime substitutes for it.
+   * @evidence contracts/common.md#meaningful-documentation Prose states preparation versus transaction ordering.
+   * @evidence contracts/portability.md#os-neutral-implementation Preparation uses the actual generation filesystem and native toolchain reader.
+   * @evidence contracts/performance.md#efficient-algorithms Qualified first deliveries perform baseline/identity lookups; other deliveries delegate one preparation per unique plugin directory.
+   * @evidence contracts/performance.md#reuse-equivalent-work The pass shares its existing first-delivery proof; persistent and repeated deliveries establish new native authority.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Native requests belong to their environment owner; no transaction survives this await.
+   */
+  export async function prepare(
+    cached: TtscCachedProjectTransform,
+    file: string,
+    epoch: number | undefined,
+  ): Promise<void> {
+    if (!sharesPass(cached, file, epoch))
+      await preparePluginBuildEnvironments(
+        cached.result,
+        resultFilesystem(cached.result),
+        cached,
+      );
+  }
+
+  /**
+   * Start fresh synchronous observation after notification and preparation
+   * awaits, sharing actual SDK queries and native predicate replay locally.
+   *
+   * @evidence contracts/common.md#principled-implementation Current environments are batch-qualified after asynchronous work; a qualified pass needs no redundant native environment observation.
+   * @evidence contracts/common.md#clear-and-simple-design One constructor binds observations to their exact generation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No current verdict is retained across deliveries or asynchronous boundaries.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies the mandatory ordering and synchronous lifetime.
+   * @evidence contracts/portability.md#os-neutral-implementation Native observation remains with the environment witness owner and actual generation path identity.
+   * @evidence contracts/performance.md#efficient-algorithms Plugin selection is generation-indexed; one batch shares variable hashing and distinct SDK metadata queries.
+   * @evidence contracts/performance.md#reuse-equivalent-work Only the following synchronous validators borrow this batch; pass sharing uses its independent first-delivery contract.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The caller releases the transaction at the end of synchronous admission; no registry or native handle is acquired.
+   */
+  export function create(
+    cached: TtscCachedProjectTransform,
+    file: string,
+    epoch: number | undefined,
+  ): Transaction {
+    return {
+      cached,
+      ...(sharesPass(cached, file, epoch)
+        ? {}
+        : {
+            environments: PluginBuildEnvironmentReadings.cachedAll(
+              selectPluginSourceInputs(cached.result).keys(),
+            ),
+          }),
+    };
+  }
+
+  /**
+   * Whether this module's first delivery belongs to this generation's proven
+   * pass. A missing source baseline cannot acquire this permission.
+   *
+   * @evidence contracts/common.md#principled-implementation Epoch equality, coherent snapshot or admitted local-pass state, a recorded source and an unserved identity are all required.
+   * @evidence contracts/common.md#clear-and-simple-design One predicate is shared by async preparation and synchronous source validation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts An incomplete ordinary generation or absent module baseline cannot earn pass reuse.
+   * @evidence contracts/common.md#meaningful-documentation Prose states the first-delivery and baseline restrictions.
+   * @evidence contracts/portability.md#os-neutral-implementation Baselines use the generation's actual identity and compiler project-key policy.
+   * @evidence contracts/performance.md#efficient-algorithms Baseline and served-set lookup avoid full input population traversal.
+   * @evidence contracts/performance.md#reuse-equivalent-work Only first deliveries in the same explicitly declared pass share its proof; repeated and later-pass requests do not.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows generation state without retaining another owner.
+   */
+  export function sharesPass(
+    cached: TtscCachedProjectTransform,
+    file: string,
+    epoch: number | undefined,
+  ): boolean {
+    if (
+      epoch === undefined ||
+      cached.deliveryEpoch !== epoch ||
+      (cached.projectSnapshotComplete !== true &&
+        cached.passDeliveryOnly !== true) ||
+      (cached.freshDeliveryOnly === true && cached.passDeliveryOnly !== true)
+    )
+      return false;
+    const identities = envelopeDerivation(cached).identityContext;
+    const identity = pathIdentityKey(file, identities);
+    if (cached.servedFiles?.has(identity)) return false;
+    const key = toProjectKey(cached.projectRoot, file, identities);
+    return (
+      cached.sourceHashes?.[identity] !== undefined ||
+      Object.hasOwn(cached.inputHashes, key) ||
+      cached.externalInputHashes?.[identity] !== undefined
+    );
+  }
+
+  /**
+   * Admit and notify a fresh-only local delivery. A coherent pass-only success
+   * can keep its result inside this pass after releasing capture resources;
+   * every other fresh-only answer is detached before notifying the host.
+   * Callback failure always evicts the incomplete owner.
+   *
+   * @evidence contracts/common.md#principled-implementation Explicit nonwatching, consistent project lifecycle and cache-withdrawal capability are required on every successful incomplete delivery; retention additionally needs the compile's exact pass-only epoch.
+   * @evidence contracts/common.md#clear-and-simple-design One owner handles initial and cached fresh-only admission, resource release and host notification.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Incomplete output never acquires a persistent record or publication, and failed/unknown/watching capability cannot leave a reusable owner.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish local pass retention, resource release and callback failure effects.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This lifecycle operation delegates native resource release to the generation disposer.
+   * @evidence contracts/performance.md#efficient-algorithms Identity/epoch checks and one callback add no input scan; resource disposal visits the fixed tracker population.
+   * @evidence contracts/performance.md#reuse-equivalent-work Only coherent locally admitted output in its exact nonwatching pass survives; a later pass or repeated module must obtain another result.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Capture resources are released even when local output is kept; rejection and callback failure detach the owning Promise, and the cache lifecycle bounds retained result lifetime.
+   */
+  export function admitFreshOnly(
+    cached: TtscCachedProjectTransform,
+    cache: TtscTransformCache | undefined,
+    key: string,
+    generation: Promise<TtscCachedProjectTransform>,
+    epoch: number | undefined,
+    hooks: TtscTransformHooks | undefined,
+  ): void {
+    if (cached.freshDeliveryOnly !== true) return;
+    const authorized =
+      hooks?.watching === false &&
+      hooks.markVolatile !== undefined &&
+      (hooks.project?.watching === undefined ||
+        hooks.project.watching === false);
+    const retain =
+      authorized &&
+      epoch !== undefined &&
+      cached.deliveryEpoch === epoch &&
+      cached.passDeliveryOnly === true;
+    disposeCachedTransform(cached);
+    if (!retain) evictGeneration(cache, key, generation);
+    if (cached.result.type === "success" && !authorized)
+      throw new Error(
+        "@ttsc/unplugin: plugin input observation is unavailable; fresh output requires an explicitly nonwatching host with supported cache withdrawal. Watching, unknown or contradictory lifecycles cannot safely observe its changes.",
+      );
+    try {
+      hooks?.markVolatile?.();
+    } catch (error) {
+      evictGeneration(cache, key, generation);
+      throw error;
+    }
+  }
+}

package/src/core/transform/validation/captureUniversalHostInputValidation.ts

@@ -302,7 +302,7 @@ export function captureUniversalHostInputValidation(
     const prepared = usesPreparedPluginBuildEnvironments(cached.result);
     const environment = prepared
       ? PluginBuildEnvironmentReadings.cached(directory)
-      : processPluginBuildEnvironment(directory);
+      : processPluginBuildEnvironment(directory, false, cached.projectRoot);
     if (
       environment === undefined ||
       !pluginSourceHolds(
@@ -310,6 +310,7 @@ export function captureUniversalHostInputValidation(
         digest,
         filesystem,
         prepared ? { environment } : undefined,
+        cached.projectRoot,
       )
     ) {
       recordGenerationProofFailure(failures, {