@ttsc/unplugin 0.31.2 → 0.31.4

package/src/core/transform/tracker/settleProjectMutationEvents.ts

@@ -2,49 +2,43 @@ import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTrans
 import { settleMutationTrackers } from "./settleMutationTrackers";
 
 /**
- * Await the cached trackers' drain operations, then recheck their watched
- * directory identities before persistent validation reads their verdicts.
+ * Await the cached trackers' drain operations before persistent validation
+ * reads their verdicts.
  *
  * A synchronous edit returns before its watch event is applied, so without this
  * a delivery could validate against a tracker that has not been told yet. Each
  * tracker uses its supplied native drain or the local two-immediate fallback;
  * that fallback is a scheduling opportunity, not independent native delivery
- * proof. Concurrent sibling deliveries share an in-flight tracker drain. Each
- * tracker with a verifier then checks its watched directories against those it
- * opened on, so a replaced directory withdraws the tracker instead of leaving
- * its silence to stand as proof. The trackers share what they read, so a
- * directory they all watch, the project root above all, costs one metadata call
- * per invocation rather than one per tracker. This map assumes those callbacks
- * share a coherent filesystem view; it is not an atomic snapshot. Drain
- * rejection aborts this verification phase and does not cancel sibling drains.
+ * proof. Concurrent sibling deliveries share an in-flight tracker drain. Drain
+ * rejection aborts the delivery's settlement and does not cancel sibling
+ * drains.
+ *
+ * The watched directories' identities are not checked here but by the
+ * delivery's synchronous admission (`verifyGenerationLocations`), after its
+ * last await, so a directory replaced while the delivery prepared is still
+ * caught and its reading is current when a validator reuses it.
  *
  * @evidence contracts/common.md#principled-implementation
- *   Successful aggregate completion precedes the available directory verifiers.
- *   Missing optional verifiers and backend delivery premises are not supplied
- *   by this adapter; the caller still decides whether silence has authority.
+ *   Successful aggregate completion precedes admission. Missing backend
+ *   delivery premises are not supplied by this adapter; the caller still
+ *   decides whether silence has authority.
  * @evidence contracts/common.md#clear-and-simple-design
- *   One three-tracker list drives both phases; a delivery-local identity map
- *   shares metadata without adding persistent validity state.
+ *   One three-tracker list drives drainage; directory identity belongs to the
+ *   synchronous admission that reads it.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts
- *   A replaced watched directory withdraws authority; the operation does not
- *   patch watcher paths or certify a generation from a timeout alone.
+ *   The operation does not patch watcher paths or certify a generation from a
+ *   timeout alone.
  * @evidence contracts/common.md#meaningful-documentation
- *   Native paragraphs explain event ordering, directory replacement and shared
- *   verification under the documentation skill.
+ *   Native paragraphs explain event ordering and where location verification
+ *   moved, under the documentation skill.
  * @evidence contracts/portability.md#os-neutral-implementation
- *   OS-neutral delivery uses backend-owned drains and filesystem-owned physical
- *   identities; lexical aliases cannot prove a replaced directory unchanged.
+ *   OS-neutral delivery uses backend-owned drains.
  * @evidence contracts/performance.md#efficient-algorithms
- *   Three tracker slots are visited after concurrent drainage. Existing
- *   verifiers scan their retained watched locations, sharing one metadata read
- *   per exact directory spelling; native path traversal, key bytes and bigint
- *   identity formatting plus delegated drain work remain variable costs.
+ *   Three tracker slots are drained concurrently; delegated drain work remains
+ *   a variable cost.
  * @evidence contracts/performance.md#reuse-equivalent-work
- *   In-flight drainage is shared by tracker and identity observations by this
- *   delivery's map; the map is recreated for every delivery, not cached forever.
+ *   In-flight drainage is shared by concurrent sibling deliveries.
  * @evidence contracts/performance.md#bound-retention-and-release-resources
- *   The identity map is local to the post-drain verification call, retaining
- *   queried directory/identity text with no independent population/byte cap.
  *   Pending drains retain the cached tracker references until they settle;
  *   rejection does not cancel siblings and no aggregate deadline is supplied.
  *   Tracker owners still control backend task and watcher closure.
@@ -52,14 +46,9 @@ import { settleMutationTrackers } from "./settleMutationTrackers";
 export async function settleProjectMutationEvents(
   cached: TtscCachedProjectTransform,
 ): Promise<void> {
-  const trackers = [
+  await settleMutationTrackers([
     cached.projectMutationTracker,
     cached.hostInputMutationTracker,
     cached.candidateMutationTracker,
-  ];
-  await settleMutationTrackers(trackers);
-  // A watch that now observes a replaced directory has nothing left to say
-  // about the new one, so it gives up its authority before anything reads it.
-  const seen = new Map<string, string | undefined>();
-  for (const tracker of trackers) tracker?.verifyLocations?.(seen);
+  ]);
 }

package/src/core/transform/tracker/verifyGenerationLocations.ts

@@ -0,0 +1,53 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+
+/**
+ * Recheck every watched directory's identity against the one its tracker opened
+ * on, returning what the check read.
+ *
+ * A watch that now observes a replaced directory has nothing left to say about
+ * the new one, so its tracker gives up its authority before anything reads it.
+ * The trackers share what they read, so a directory they all watch, the project
+ * root above all, costs one metadata call per delivery rather than one per
+ * tracker. The returned readings belong to the synchronous admission that ran
+ * the check: a validator in it that must know whether one of these directories
+ * is still a directory reads the answer here instead of stating it again
+ * (samchon/ttsc#1735). The map assumes the callbacks share a coherent
+ * filesystem view; it is not an atomic snapshot.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Each verifier compares followed device and file ids with the opened ones,
+ *   and a mismatch or unreadable location withdraws its tracker.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One three-tracker list drives every verifier through one delivery-local
+ *   identity map, which is also the result.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   A replaced watched directory withdraws authority; lexical spelling never
+ *   proves a directory unchanged.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native prose explains withdrawal, sharing and the result's synchronous
+ *   lifetime under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Identities are the filesystem's own physical identities, followed through
+ *   links, with no platform case rule.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Three tracker slots are visited; existing verifiers scan their retained
+ *   watched locations, sharing one metadata read per exact directory spelling.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The map is created for each admission and handed to that admission's
+ *   validators, never retained across deliveries.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The caller's synchronous transaction owns the map, which retains queried
+ *   directory and identity text only until that transaction ends.
+ */
+export function verifyGenerationLocations(
+  cached: TtscCachedProjectTransform,
+): Map<string, string | undefined> {
+  const seen = new Map<string, string | undefined>();
+  for (const tracker of [
+    cached.projectMutationTracker,
+    cached.hostInputMutationTracker,
+    cached.candidateMutationTracker,
+  ])
+    tracker?.verifyLocations?.(seen);
+  return seen;
+}

package/src/core/transform/utils/isZombieProcess.ts

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+
+/**
+ * Whether process `pid` has exited and only waits for its parent to collect its
+ * status.
+ *
+ * Signal zero still reaches such a zombie, so a liveness probe built on it
+ * alone counts the process alive. A parent that never collects, such as a
+ * container's PID 1 that is not an init or a subreaper that collects only when
+ * its own command ends, keeps the zombie indefinitely, and the locks and
+ * directories it owned would never be reclaimed. Only Linux exposes the state,
+ * through `/proc`; elsewhere, and whenever it cannot be read, this answers
+ * `false` so the caller's existing probe decides. A leader whose own thread
+ * exited also reads as a zombie while its other threads run, so the zombie must
+ * be the process's last thread. A zombie keeps its id until collected, so this
+ * never names a live process.
+ *
+ * @param pid A positive process id that signal zero just found.
+ * @evidence contracts/common.md#principled-implementation The kernel's own process status, zombie or dead with no other thread, establishes the exit; any unreadable or other status leaves the caller's signal-zero answer standing.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate serves the shared-compile lock, session-owner and watch-probe owners alike.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No PID list, timeout or error-to-exited fallback substitutes for the kernel status.
+ * @evidence contracts/common.md#meaningful-documentation The paragraph explains why signal zero misses a zombie, which parents leave one behind, why a zombie leader with running threads is not one and why its id cannot name a live process.
+ * @evidence contracts/portability.md#os-neutral-implementation Only Linux exposes zombies through /proc; other platforms keep their probe's answer.
+ * @evidence contracts/performance.md#efficient-algorithms One small /proc read on Linux, nothing elsewhere.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Process state is a current observation and is never cached.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The read retains no handle; the status text becomes reclaimable on return.
+ */
+export function isZombieProcess(pid: number): boolean {
+  if (process.platform !== "linux") return false;
+  let status: string;
+  try {
+    status = fs.readFileSync(`/proc/${pid}/status`, "utf8");
+  } catch {
+    return false;
+  }
+  const state = /^State:\s*(\S)/m.exec(status)?.[1];
+  const threads = /^Threads:\s*(\d+)/m.exec(status)?.[1];
+  return (state === "Z" || state === "X") && threads === "1";
+}

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

@@ -10,6 +10,7 @@ import { selectPluginSourceInputs } from "../envelope/selectPluginSourceInputs";
 import { pathIdentityKey } from "../filesystem/pathIdentityKey";
 import { preparePluginBuildEnvironments } from "../inputs/preparePluginBuildEnvironments";
 import { toProjectKey } from "../project/toProjectKey";
+import { verifyGenerationLocations } from "../tracker/verifyGenerationLocations";
 import type { TtscTransformHooks } from "../watch/TtscTransformHooks";
 
 /**
@@ -56,6 +57,13 @@ export namespace TtscGenerationProof {
 
     /** Current native predicate verdict, unbuilt until its first gate. */
     nativePredicates?: boolean;
+
+    /**
+     * Identities this admission's location verification read, by watched
+     * directory, absent when it ran none. An identity proves its directory is
+     * one now; an absent or undefined entry proves nothing.
+     */
+    readonly locations?: ReadonlyMap<string, string | undefined>;
   }
 
   /**
@@ -86,15 +94,17 @@ export namespace TtscGenerationProof {
 
   /**
    * Start fresh synchronous observation after notification and preparation
-   * awaits, sharing actual SDK queries and native predicate replay locally.
+   * awaits, sharing actual SDK queries and native predicate replay locally. A
+   * persistent delivery also rechecks its trackers' watched directories here
+   * and keeps what that read for the validators that follow.
    *
-   * @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#principled-implementation Current environments are batch-qualified after asynchronous work, and a persistent delivery's watched directories are rechecked after it; 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#efficient-algorithms Plugin selection is generation-indexed; one batch shares variable hashing and distinct SDK metadata queries, and location verification reads each watched directory once.
+   * @evidence contracts/performance.md#reuse-equivalent-work Only the following synchronous validators borrow this batch and the location identities; 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(
@@ -104,6 +114,12 @@ export namespace TtscGenerationProof {
   ): Transaction {
     return {
       cached,
+      // A persistent delivery rechecks its watched directories here, after
+      // its last await, so a directory replaced while it prepared withdraws
+      // its tracker before admission reads it.
+      ...(epoch === undefined
+        ? { locations: verifyGenerationLocations(cached) }
+        : {}),
       ...(sharesPass(cached, file, epoch)
         ? {}
         : {

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

@@ -5,6 +5,7 @@ import { resultFilesystem } from "../cache/resultFilesystem";
 import { derivationIdentity } from "../envelope/derivationIdentity";
 import { envelopeDerivation } from "../envelope/envelopeDerivation";
 import { graphInputStateHash } from "../inputs/graphInputStateHash";
+import { hostInputRealpath } from "../inputs/hostInputRealpath";
 import { hostInputStateHash } from "../inputs/hostInputStateHash";
 import { inputMetadataEvidence } from "../inputs/inputMetadataEvidence";
 import { inputMetadataSignature } from "../inputs/inputMetadataSignature";
@@ -20,7 +21,7 @@ import { MISSING_INPUT_STATE } from "./MISSING_INPUT_STATE";
  * The caller adopts those signatures only once every input is proven unchanged,
  * so a signature never outlives the content comparison that justified it.
  *
- * @evidence contracts/common.md#principled-implementation Each lexical spelling replays its predicates or owning content codec; only stable separable metadata can replace that comparison, so aliases cannot answer for one another.
+ * @evidence contracts/common.md#principled-implementation Each lexical spelling replays its predicates or owning content codec and resolves its own physical file; only stable separable metadata can replace that comparison, so aliases cannot answer for one another. Spellings resolving to one physical file now share that file's content read, which the codecs hash by content alone.
  * @evidence contracts/common.md#clear-and-simple-design One pass returns the aggregate verdict and earned signatures, leaving all-or-nothing adoption to its caller.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Recorded missing states and absent hash keys remain distinct from successful content proof; newer reads do not rewrite the authoritative recorded hashes.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish mixed codecs, clock-qualified reuse and caller-owned signature adoption before tags.
@@ -34,7 +35,7 @@ import { MISSING_INPUT_STATE } from "./MISSING_INPUT_STATE";
  *   failures/listings, then recaptures metadata for earned signatures.
  *   Earned signature storage grows with successful observed spellings; legacy
  *   fallback also materializes the recorded hash key array.
- * @evidence contracts/performance.md#reuse-equivalent-work The generation's unchanged separable signatures share prior content validation; changed metadata or clock ordering requires replay, and adopted signatures come only from a completely successful caller verdict.
+ * @evidence contracts/performance.md#reuse-equivalent-work The generation's unchanged separable signatures share prior content validation; changed metadata or clock ordering requires replay, read once per codec and physical file in this pass, and adopted signatures come only from a completely successful caller verdict.
  */
 export function matchesCachedExternalInputs(
   /** Generation recording lexical inputs, distinct codecs and earned signatures. */
@@ -53,6 +54,8 @@ export function matchesCachedExternalInputs(
   const filesystem = resultFilesystem(cached.result);
   const recordedHashes = cached.externalInputHashes ?? {};
   const recordedSignatures = cached.externalInputSignatures ?? {};
+  // Content hashes this pass read, by codec and current physical file.
+  const sharedReads = new Map<string, string | null>();
   // Compare each spelling against the recorded state under its own name. Two
   // spellings share one identity exactly when they selected one physical file
   // at generation time, which is the state a retarget ends, so neither may
@@ -102,9 +105,29 @@ export function matchesCachedExternalInputs(
     ) {
       continue;
     }
-    const hash = Object.prototype.hasOwnProperty.call(graphRealpaths, identity)
-      ? graphInputStateHash(file, filesystem)
-      : hostInputStateHash(file, filesystem);
+    // Each spelling resolves on its own and the first one resolving to a
+    // physical file reads it through its own spelling, as the filesystem view
+    // answers; a later spelling resolving to that file now reuses the read,
+    // since the codecs hash content alone. A metadata-only change otherwise
+    // read an alias and its target twice in one delivery.
+    const graph = Object.prototype.hasOwnProperty.call(
+      graphRealpaths,
+      identity,
+    );
+    const physical = hostInputRealpath(file, filesystem);
+    const shared =
+      physical === null
+        ? undefined
+        : `${graph ? "graph" : "host"}\0${physical}`;
+    let hash: string | null;
+    if (shared !== undefined && sharedReads.has(shared)) {
+      hash = sharedReads.get(shared)!;
+    } else {
+      hash = graph
+        ? graphInputStateHash(file, filesystem)
+        : hostInputStateHash(file, filesystem);
+      if (shared !== undefined) sharedReads.set(shared, hash);
+    }
     const after = inputMetadataSignature(file, filesystem);
     if (
       !Object.prototype.hasOwnProperty.call(recordedHashes, identity) ||

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

@@ -73,7 +73,7 @@ export function matchesCompleteInputSnapshot(
   if (
     hostValidation === undefined ||
     !matchesUniversalHostInputEntries(cached, hostValidation) ||
-    !matchesUniversalHostInputProbes(cached, hostValidation) ||
+    !matchesUniversalHostInputProbes(cached, hostValidation, proof) ||
     !matchesUniversalHostInputTrees(cached, hostValidation, proof)
   ) {
     return false;

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

@@ -2,6 +2,7 @@ import path from "node:path";
 
 import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
 import { resultFilesystem } from "../cache/resultFilesystem";
+import type { TtscGenerationProof } from "./TtscGenerationProof";
 import type { TtscHostInputValidation } from "./TtscHostInputValidation";
 
 /**
@@ -17,18 +18,25 @@ import type { TtscHostInputValidation } from "./TtscHostInputValidation";
  * Complete validation still compares its recorded byte and membership
  * populations after this independent native absence predicate holds.
  *
- * @evidence contracts/common.md#principled-implementation Exact native ENOENT or ENOTDIR observations prove candidate absence, including native Unicode and short-name aliases. A vanished ancestor leaves descendants unreachable; replacement by a file rejects the grouped directory proof.
+ * A group also needs its directory to still be one, which a candidate's own
+ * stat cannot say: Windows answers ENOENT below a file just as below nothing.
+ * The admission's location verification has already read that of every watched
+ * directory, so a group under one reuses it instead of stating the directory a
+ * second time in the same delivery (samchon/ttsc#1735).
+ *
+ * @evidence contracts/common.md#principled-implementation Exact native ENOENT or ENOTDIR observations prove candidate absence, including native Unicode and short-name aliases. A vanished ancestor leaves descendants unreachable; replacement by a file rejects the grouped directory proof, whether this pass or the admission's location verification observed the directory.
  * @evidence contracts/common.md#clear-and-simple-design Missing-name validation has its own native absence boundary shared by narrow and complete proof; byte hashes and project membership remain separate predicates.
- * @evidence contracts/common.md#prohibited-implementation-shortcuts Listing inequality is not native name inequality; permission and transient failures are not fabricated absence. Only ENOENT and ENOTDIR qualify missing-path observations.
- * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain inability-to-prove rejection, unreadable-content ambiguity and both caller routes before tags.
- * @evidence contracts/portability.md#os-neutral-implementation The injected native stat resolves original candidate spelling, and its platform selects the same win32 or posix joining grammar as capture's ancestor probe. Case flags and JavaScript Unicode folding do not replace native alias resolution.
- * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The pass borrows generation-owned groups and retains only each current native probe result; no directory listing, historical state or handle is acquired.
- * @evidence contracts/performance.md#efficient-algorithms Each group checks its directory once, then each candidate requires one native stat. Work follows candidate count and native path resolution, without enumerating unrelated directory entries; exact probes are necessary because listing names cannot establish all native aliases.
- * @evidence contracts/performance.md#reuse-equivalent-work Capture shares nearest-ancestor selection and raw candidate groups across consumers; each current absence proof must observe native candidates again unless the owning notification validator establishes unchanged inputs.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Listing inequality is not native name inequality; permission and transient failures are not fabricated absence. Only ENOENT and ENOTDIR qualify missing-path observations, and only an identity read by the same synchronous admission stands for a directory stat.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain inability-to-prove rejection, unreadable-content ambiguity, both caller routes and the shared directory reading before tags.
+ * @evidence contracts/portability.md#os-neutral-implementation The injected native stat resolves original candidate spelling, and its platform selects the same win32 or posix joining grammar as capture's ancestor probe. Case flags and JavaScript Unicode folding do not replace native alias resolution, and the directory check does not rely on ENOTDIR, which Windows does not report.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The pass borrows generation-owned groups and the admission's identities, and retains only each current native probe result; no directory listing, historical state or handle is acquired.
+ * @evidence contracts/performance.md#efficient-algorithms Each candidate requires one native stat, and each group one directory stat unless its admission already read the directory's identity. Work follows candidate count and native path resolution, without enumerating unrelated directory entries; exact probes are necessary because listing names cannot establish all native aliases.
+ * @evidence contracts/performance.md#reuse-equivalent-work Capture shares nearest-ancestor selection and raw candidate groups across consumers, and one synchronous admission shares its watched directories' identities; each current absence proof must observe native candidates again unless the owning notification validator establishes unchanged inputs.
  */
 export function matchesUniversalHostInputProbes(
   cached: TtscCachedProjectTransform,
   validation: TtscHostInputValidation,
+  proof?: TtscGenerationProof.Transaction,
 ): boolean {
   const filesystem = resultFilesystem(cached.result);
   const paths =
@@ -44,15 +52,18 @@ export function matchesUniversalHostInputProbes(
     }
   }
   for (const [directory, names] of validation.missing) {
-    try {
-      if (!filesystem.stat(directory).isDirectory()) return false;
-    } catch (error) {
-      // Only a provably absent/non-directory ancestor keeps every descendant
-      // unreachable. Permission and transient I/O failures cannot prove that
-      // a candidate is still missing, while replacing the proving directory
-      // with an exact file can itself redirect module resolution.
-      if (!isMissingPathError(error)) return false;
-      continue;
+    // An identity the admission read proves the directory is one now.
+    if (proof?.locations?.get(directory) === undefined) {
+      try {
+        if (!filesystem.stat(directory).isDirectory()) return false;
+      } catch (error) {
+        // Only a provably absent/non-directory ancestor keeps every descendant
+        // unreachable. Permission and transient I/O failures cannot prove that
+        // a candidate is still missing, while replacing the proving directory
+        // with an exact file can itself redirect module resolution.
+        if (!isMissingPathError(error)) return false;
+        continue;
+      }
     }
     for (const name of names) {
       try {

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

@@ -49,7 +49,7 @@ export function matchesUniversalHostInputs(
     return matchesUniversalHostInputTrees(cached, validation, proof);
   return (
     matchesUniversalHostInputEntries(cached, validation) &&
-    matchesUniversalHostInputProbes(cached, validation) &&
+    matchesUniversalHostInputProbes(cached, validation, proof) &&
     matchesUniversalHostInputTrees(cached, validation, proof)
   );
 }