@ttsc/metro 0.28.5 → 0.28.6

package/lib/core/fingerprint.js

@@ -21,20 +21,20 @@ var path = require('node:path');
  *   `projectRoot` plus the resolved tsconfig's directory when it lies outside),
  *   hashed with the exact walk universe the `@ttsc/unplugin` transform core
  *   validates its own cache against.
- * - **Recorded out-of-walk inputs.** The transform core cannot walk files outside
- *   the roots or under ignored directories, but the host-owned reference graph
- *   (samchon/ttsc#718) reports them per transform. Workers record them into a
- *   snapshot under `node_modules/.cache/ttsc-metro`; the next run's
- *   `getCacheKey` re-hashes the recorded set.
+ * - **Recorded transform inputs.** The host-owned reference graph
+ *   (samchon/ttsc#718) reports each transform's derived inputs. Workers retain
+ *   them under `node_modules/.cache/ttsc-metro`, compare their generation state
+ *   with the exact main-process key baseline, and batch one durable write per
+ *   delivered module.
  *
  * Snapshot layout: one main file carrying a random epoch id plus per-worker
  * files with unique names, so concurrent workers never race a shared write.
- * `withTtsc` (the single config process, before workers exist) compacts worker
- * files into the main file. Readers take the union of every file, reading the
- * worker files strictly before the main file: the compactor renames the merged
- * main into place strictly before deleting a worker file, so a worker file that
- * disappears mid-read is always already merged into the main the reader loads
- * afterwards.
+ * `withTtsc` compacts worker files into the main file before its workers exist,
+ * under a process-shared lock for builds using the same project cache. Readers
+ * take the union of every file, reading the worker files strictly before the
+ * main file: the compactor renames the merged main into place strictly before
+ * deleting a worker file, so a worker file that disappears mid-read is always
+ * already merged into the main the reader loads afterwards.
  *
  * Sound degradations, by design:
  *
@@ -50,9 +50,12 @@ var path = require('node:path');
  *   until a later run records the volatile declaration gone.
  * - A recorded input that disappears hashes as a stable `missing` marker, so
  *   deletion and reappearance both move the key.
+ * - A worker state that differs from the static key's run baseline taints the
+ *   observation; compaction rotates the epoch so even A -> B -> A cannot reuse
+ *   output stored under the earlier A key.
  */
 /** Bumped when the snapshot JSON shape changes; mismatches read as corrupt. */
-const SNAPSHOT_VERSION = 1;
+const SNAPSHOT_VERSION = 2;
 /** Snapshot directory segments under the fingerprint base directory. */
 const SNAPSHOT_DIRECTORY = ["node_modules", ".cache", "ttsc-metro"];
 /** Recovery-document prefix in the parent cache directory. */
@@ -63,6 +66,14 @@ const MAIN_SNAPSHOT = "graph-inputs.json";
 const WORKER_SNAPSHOT_PREFIX = "graph-inputs.worker-";
 /** Prefix used after a compactor atomically claims an immutable worker file. */
 const CLAIMED_WORKER_SNAPSHOT_PREFIX = "graph-inputs.worker-claimed-";
+/** Directory lock serializing the one mutable main-snapshot rewrite. */
+const SNAPSHOT_COMPACTION_LOCK = "snapshot-compaction.lock";
+/** Complete owner record stored inside an atomically published lock. */
+const SNAPSHOT_COMPACTION_OWNER = "owner.json";
+/** Cache-key baseline file prefix, one immutable identity per Metro run. */
+const KEY_BASELINE_PREFIX = "key-baseline-";
+/** Run-token prefix that forces every transformer key to be non-reusable. */
+const NON_REUSABLE_RUN_PREFIX = "nonce:";
 /** Bases whose latest observation is not yet durable in the main snapshot. */
 const unhealthySnapshots = new Set();
 /**
@@ -83,11 +94,15 @@ function resolveFingerprintBase(projectRoot) {
  * already inside the base walk (an explicit out-of-root `project`, or a
  * monorepo-root tsconfig discovered above the app). Matching the transform
  * core's own validation universe keeps the invariant simple: everything the
- * core treats as an input is fingerprinted, either by a walk here or by the
- * recorded out-of-walk snapshot.
+ * core treats as an input is fingerprinted by the walk, the recorded snapshot,
+ * or both.
  */
 function fingerprintRoots(base, explicitProject) {
-    const tsconfig = resolveProjectTsconfig(base, explicitProject);
+    const explicit = normalizedExplicitProject(explicitProject);
+    return projectViewRoots(base, resolveProjectTsconfig(base, explicit), explicit);
+}
+/** Roots covered by one selected project's static walk. */
+function projectViewRoots(base, tsconfig, explicitProject) {
     // Containment, not walk membership. The question here is whether the
     // tsconfig's directory already sits inside the subtree the base walk covers,
     // so that adding it would repeat the same walk. `isProjectWalkPath` answers a
@@ -95,13 +110,17 @@ function fingerprintRoots(base, explicitProject) {
     // stopped hashing files that cannot enter the program it began answering
     // `false` for every `tsconfig.json`, which returned the base twice and hashed
     // the whole project twice on every cache key (samchon/ttsc#1307).
+    const resolvedBase = path.resolve(base);
     const directory = path.dirname(path.resolve(tsconfig));
-    const relative = path.relative(path.resolve(base), directory);
+    const relative = path.relative(resolvedBase, directory);
     const inside = relative === "" ||
         (relative !== ".." &&
             !relative.startsWith(`..${path.sep}`) &&
             !path.isAbsolute(relative));
-    return inside ? [base] : [base, directory];
+    if (explicitProject === undefined && inside && directory !== resolvedBase) {
+        return [directory];
+    }
+    return inside ? [resolvedBase] : [resolvedBase, directory];
 }
 /**
  * Resolve one transform's project view, once, for every watch input it reports.
@@ -112,105 +131,204 @@ function fingerprintRoots(base, explicitProject) {
  */
 function resolveProjectView(props) {
     const base = resolveFingerprintBase(props.projectRoot);
-    return {
+    const explicitProject = normalizedExplicitProject(props.explicitProject);
+    const start = explicitProject === undefined && props.filename !== undefined
+        ? path.dirname(path.resolve(props.filename))
+        : base;
+    const discovery = explicitProject === undefined
+        ? api.discoverNearestProjectTsconfig(start, props.projectDiscoveryFilesystem)
+        : undefined;
+    const tsconfig = discovery === undefined
+        ? resolveProjectTsconfig(start, explicitProject)
+        : (discovery.file ?? path.resolve(process.cwd(), "tsconfig.json"));
+    const discoveryInputs = discovery === undefined
+        ? [captureProjectDiscoveryInput(tsconfig)]
+        : discovery.candidates.map((candidate) => captureProjectDiscoveryInput(candidate.file, candidate.fileExists));
+    if (!discoveryInputs.some((input) => samePath(input.file, tsconfig))) {
+        discoveryInputs.push(captureProjectDiscoveryInput(tsconfig));
+    }
+    return createProjectView({
         base,
+        compilerOptions: props.compilerOptions,
+        discoveryInputs,
+        explicitProject,
+        tsconfig,
+    });
+}
+/** Create one cache view from an already selected project config. */
+function createProjectView(props) {
+    const policy = membershipPolicy(props.tsconfig, props.compilerOptions);
+    return {
+        base: props.base,
+        discoveryInputs: props.discoveryInputs ?? [],
         explicitProject: props.explicitProject,
-        policy: membershipPolicy(resolveProjectTsconfig(base, props.explicitProject), props.compilerOptions),
+        policy,
+        roots: projectViewRoots(props.base, props.tsconfig, props.explicitProject),
+        tsconfig: props.tsconfig,
+        walkPolicy: policy,
     };
 }
-/**
- * The membership policy of one project, memoized per resolved tsconfig and
- * caller overlay.
- *
- * Every use of the walk pair has to ask the same policy, or the two halves
- * disagree about the same project. The walk hashes what the configuration can
- * admit, and `isProjectWalkPath` answers whether the walk covers a path, so a
- * permissive answer here would claim coverage the walk does not provide and the
- * input would be recorded nowhere at all (samchon/ttsc#1307).
- */
-const MEMBERSHIP_POLICIES = new Map();
-function membershipPolicy(tsconfig, compilerOptions) {
-    // Keyed by the config's path and the caller's overlay, and never trusted on
-    // the key alone: a hit is served only while the config's own stamp still
-    // matches. A Metro worker outlives many runs, and this is consulted once per
-    // delivered file, so a memo that trusted its key would hold the policy a
-    // project had when the worker started. An edit adding `exclude` would then
-    // leave the worker judging a file in-walk while the next run's walk skipped
-    // it, which is precisely the both-sides-disagree hole this policy exists to
-    // close.
-    //
-    // The overlay belongs in the key rather than the stamp because it is part of
-    // the question, not part of any file: keyed by path alone the memo would hand
-    // a caller who passed `allowJs` the policy resolved for a caller who did not.
-    const key = [tsconfig, stableStringify(compilerOptions ?? {})].join(String.fromCharCode(0));
-    const existing = MEMBERSHIP_POLICIES.get(key);
-    if (existing !== undefined && existing.stamp === stampOf(existing.sources)) {
-        return existing.policy;
-    }
-    // The caller's compiler-options overlay wins for the compile, so it has to
-    // win here too, exactly as it does in the adapter: a project given
-    // `allowJs: true` through `withTtsc` has a wider program than its tsconfig
-    // alone describes, and a narrower policy here would ask a different question
-    // about the same project (samchon/ttsc#1316).
-    const policy = api.mergeMembershipPolicyOverlay(api.readProjectMembershipPolicy(tsconfig), compilerOptions ?? {}, path.dirname(path.resolve(tsconfig)));
-    // Stamp the whole `extends` chain, not the leaf. Adding `exclude` to a shared
-    // `tsconfig.base.json` leaves the leaf's own mtime and size untouched while
-    // changing every answer the policy gives, so a leaf-only stamp would keep the
-    // worker on the pre-edit policy for its lifetime.
-    const sources = policy.sources.length === 0 ? [tsconfig] : [...policy.sources];
-    MEMBERSHIP_POLICIES.set(key, {
-        policy,
-        sources,
-        stamp: stampOf(sources),
-    });
-    return policy;
+/** Attach identity to the exact file predicate that selected a worker project. */
+function captureProjectDiscoveryInput(file, selectedFileExists) {
+    const baseline = api.captureWatchInputFileBaseline(file);
+    if (baseline === undefined) {
+        return { file };
+    }
+    const fileExists = selectedFileExists ?? baseline.fileExists;
+    return {
+        evidence: {
+            identity: baseline.identity,
+            missing: !fileExists,
+            state: {
+                codec: "predicates",
+                observation: { fileExists },
+            },
+            unavailable: fileExists ? undefined : "not-file",
+        },
+        file,
+    };
 }
-/** A stamp over every config a policy was read from, in a stable order. */
-function stampOf(sources) {
-    return sources
-        .map((source) => {
-        try {
-            const stats = fs.statSync(source);
-            // A directory occupying a candidate path can never be the config, so it
-            // contributes its existence and not its modification time, which moves
-            // whenever any child is added or removed (samchon/ttsc#1316).
-            return stats.isDirectory()
-                ? `${source}:directory`
-                : `${source}:${stats.mtimeMs}:${stats.size}`;
-        }
-        catch {
-            // Absent now. `readProjectMembershipPolicy` answers for that too, and
-            // the policy must be re-asked once the config appears.
-            return `${source}:absent`;
-        }
-    })
-        .join("|");
+/** Resolve one project policy from source rather than trusting metadata alone. */
+function membershipPolicy(tsconfig, compilerOptions) {
+    // The caller overlay wins here exactly as it does for the compile. Re-reading
+    // source is deliberate: a long-lived worker cannot validate config contents
+    // from mtime and size, because a same-stamp rewrite is legal on coarse or
+    // restored filesystems. `resolveProjectView` runs once per delivered module,
+    // and its result is shared by the batched recorder.
+    return api.mergeMembershipPolicyOverlay(api.readProjectMembershipPolicy(tsconfig), compilerOptions ?? {}, path.dirname(path.resolve(tsconfig)));
 }
 /**
  * Locate the tsconfig governing the project, mirroring the transform core's
  * discovery: an explicit `project` resolves against the working directory;
  * otherwise ancestor directories starting at `base` are searched for a
- * `tsconfig.json`, falling back to `<base>/tsconfig.json`.
+ * `tsconfig.json` file, falling back to `<cwd>/tsconfig.json` like the shared
+ * transform core.
  */
 function resolveProjectTsconfig(base, explicitProject) {
-    if (explicitProject !== undefined && explicitProject.length !== 0) {
+    if (explicitProject !== undefined) {
         return path.isAbsolute(explicitProject)
             ? explicitProject
             : path.resolve(process.cwd(), explicitProject);
     }
-    let current = base;
-    while (true) {
-        const candidate = path.join(current, "tsconfig.json");
-        if (fs.existsSync(candidate)) {
-            return candidate;
-        }
-        const parent = path.dirname(current);
-        if (parent === current) {
-            break;
+    const discovered = api.findNearestProjectTsconfig(base);
+    if (discovered !== undefined) {
+        return discovered;
+    }
+    return path.resolve(process.cwd(), "tsconfig.json");
+}
+/** Empty project strings carry the same implicit meaning as omission. */
+function normalizedExplicitProject(explicitProject) {
+    return explicitProject === undefined || explicitProject.length === 0
+        ? undefined
+        : explicitProject;
+}
+/** Resolve every implicit project whose files can be delivered below base. */
+function fingerprintProjectViews(props) {
+    const primary = resolveProjectView(props);
+    if (primary.explicitProject !== undefined) {
+        return {
+            discoveryInputs: [primary.tsconfig],
+            projects: [stableFingerprintProjectView(primary, props.compilerOptions)],
+        };
+    }
+    const firstMap = api.findProjectTsconfigs(primary.base, props.projectDiscoveryFilesystem);
+    if (!firstMap.complete) {
+        throw new Error("Unable to enumerate Metro's implicit TypeScript projects.");
+    }
+    const projects = [
+        stableFingerprintProjectView(primary, props.compilerOptions),
+    ];
+    for (const tsconfig of firstMap.files) {
+        const resolved = path.resolve(tsconfig);
+        if (projects.some((project) => samePath(project.tsconfig, resolved))) {
+            continue;
         }
-        current = parent;
+        projects.push(stableFingerprintProjectView(createProjectView({
+            base: primary.base,
+            compilerOptions: props.compilerOptions,
+            explicitProject: undefined,
+            tsconfig: resolved,
+        }), props.compilerOptions));
+    }
+    const secondMap = api.findProjectTsconfigs(primary.base, props.projectDiscoveryFilesystem);
+    const selectedAfter = resolveProjectView(props);
+    if (!secondMap.complete ||
+        !sameProjectMap(firstMap.files, secondMap.files) ||
+        !sameProjectMap(firstMap.candidates, secondMap.candidates) ||
+        !samePath(primary.tsconfig, selectedAfter.tsconfig) ||
+        stableStringify(primary.discoveryInputs) !==
+            stableStringify(selectedAfter.discoveryInputs) ||
+        projects.some((project) => stableStringify(api.readTsconfigSourceSnapshot(project.tsconfig)) !==
+            stableStringify(project.configSources))) {
+        throw new Error("Metro's implicit TypeScript project map changed.");
     }
-    return path.resolve(base, "tsconfig.json");
+    const routedRoots = projects.map((project) => project.roots[0]);
+    return {
+        // `findProjectTsconfigs` covers candidates at and below Metro's base. The
+        // primary nearest-config search can also cross above that base to a
+        // monorepo config, and every rejected candidate on that ancestor path is
+        // just as capable of changing the selected project. Keep both sets in the
+        // main-process baseline so a worker does not taint every unchanged run for
+        // reporting a candidate the static key itself used.
+        discoveryInputs: [
+            ...new Set([
+                ...primary.discoveryInputs.map((input) => input.file),
+                ...firstMap.candidates,
+            ]),
+        ].sort(),
+        projects: projects.map((project, index) => {
+            const root = routedRoots[index];
+            const nestedRoots = routedRoots.filter((candidate, candidateIndex) => candidateIndex !== index &&
+                !samePath(candidate, root) &&
+                pathIsWithin(candidate, root));
+            return nestedRoots.length === 0
+                ? project
+                : {
+                    ...project,
+                    walkPolicy: {
+                        ...project.policy,
+                        excludedDirectories: [
+                            ...project.policy.excludedDirectories,
+                            ...nestedRoots,
+                        ],
+                    },
+                };
+        }),
+    };
+}
+/** Read one implicit project's policy between equal complete config snapshots. */
+function stableFingerprintProjectView(project, compilerOptions) {
+    const before = api.readTsconfigSourceSnapshot(project.tsconfig);
+    const refreshed = createProjectView({
+        base: project.base,
+        compilerOptions,
+        explicitProject: project.explicitProject,
+        tsconfig: project.tsconfig,
+    });
+    const after = api.readTsconfigSourceSnapshot(project.tsconfig);
+    if (before.some((entry) => entry.contents === null) ||
+        after.some((entry) => entry.contents === null) ||
+        stableStringify(before) !== stableStringify(after)) {
+        throw new Error("Unable to read a stable TypeScript project config graph.");
+    }
+    return { ...refreshed, configSources: after };
+}
+/** Whether two complete lexical config enumerations name the same paths. */
+function sameProjectMap(left, right) {
+    return (left.length === right.length &&
+        left.every((entry, index) => samePath(entry, right[index])));
+}
+/** Host-platform equality for two resolved path spellings. */
+function samePath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === "";
+}
+/** Whether one resolved path lies at or below another. */
+function pathIsWithin(child, parent) {
+    const relative = path.relative(path.resolve(parent), path.resolve(child));
+    return (relative === "" ||
+        (relative !== ".." &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative)));
 }
 /**
  * Compute the fingerprint `getCacheKey` folds into Metro's static transformer
@@ -220,80 +338,183 @@ function resolveProjectTsconfig(base, explicitProject) {
 function computeProjectFingerprint(props) {
     try {
         const base = resolveFingerprintBase(props.projectRoot);
-        const hash = node_crypto.createHash("sha256");
-        // Judge the fingerprint's walk by the same configuration the compile
-        // does. Metro folds this into one static key, so an entry the program
-        // could never contain used to re-key every transformed file rather than
-        // costing one compile the way it does for a bundler (samchon/ttsc#1307).
-        //
-        // The caller's compiler-options overlay is part of that configuration, and
-        // has to reach the walk as well as the recorder. The two are the halves of
-        // one cache key and run in different processes, so they agree only by
-        // deriving from the same declared options: a walk resolved without the
-        // overlay while the recorder resolves with it leaves an overlay-admitted
-        // input in neither half, which is the both-sides-disagree hole in its
-        // quietest form (samchon/ttsc#1316).
-        const project = resolveProjectView({
-            compilerOptions: props.compilerOptions,
-            explicitProject: props.explicitProject,
-            projectRoot: props.projectRoot,
-        });
-        for (const root of fingerprintRoots(base, props.explicitProject)) {
-            hash.update(stableStringify(api.collectProjectInputHashes(root, undefined, undefined, project.policy)));
-        }
-        const snapshot = readSnapshotState(base);
-        if (snapshot === undefined || snapshot.volatile) {
-            hash.update(nonce());
+        const before = observeProjectFingerprint(props);
+        const after = observeProjectFingerprint(props);
+        if (stableStringify(before) !== stableStringify(after)) {
+            throw new Error("Metro's project fingerprint changed while observed.");
         }
-        else {
-            hash.update(`snapshot:${snapshot.id}`);
-            hash.update(stableStringify(api.collectExternalInputHashes(snapshot.files)));
+        if (props.runId !== undefined) {
+            writeKeyBaseline(base, props.runId, after.inputs, after.staticInputs);
         }
+        const hash = node_crypto.createHash("sha256");
+        hash.update(stableStringify(after.fingerprint));
         return hash.digest("hex");
     }
     catch {
         return nonce();
     }
 }
+/** Build the complete value hashed by one static key. */
+function observeProjectFingerprint(props) {
+    // Judge the fingerprint's walk by the same configuration the compile does.
+    // The caller overlay reaches this walk and the worker through the same
+    // serialized options, so neither side can silently describe another program.
+    const projectMap = fingerprintProjectViews(props);
+    const inputs = {};
+    const staticInputs = new Set();
+    const configSources = new Map();
+    const projectFingerprints = [];
+    for (const candidate of projectMap.discoveryInputs) {
+        addDiscoveryBaselineInput(inputs, candidate, staticInputs);
+    }
+    for (const project of projectMap.projects) {
+        for (const source of project.configSources) {
+            const existing = configSources.get(source.path);
+            if (existing !== undefined && existing.contents !== source.contents) {
+                throw new Error("A TypeScript config changed during fingerprinting.");
+            }
+            const baseline = addBaselineInput(inputs, source.path, staticInputs);
+            configSources.set(source.path, {
+                contents: source.contents,
+                identity: baseline.identity,
+            });
+        }
+        for (const root of project.roots) {
+            const snapshot = api.collectProjectInputHashSnapshot(root, undefined, undefined, project.walkPolicy);
+            if (!snapshot.complete) {
+                throw new Error("Unable to read a complete Metro project walk.");
+            }
+            const fingerprintedInputs = {};
+            for (const [key, expected] of Object.entries(snapshot.hashes)) {
+                const file = path.resolve(root, key);
+                const baseline = addBaselineInput(inputs, file, staticInputs);
+                if (baseline.hostHash !== expected) {
+                    throw new Error("A Metro project input changed while fingerprinted.");
+                }
+                fingerprintedInputs[key] = {
+                    hash: expected,
+                    identity: baseline.identity,
+                };
+            }
+            projectFingerprints.push({
+                inputs: fingerprintedInputs,
+                root,
+                tsconfig: project.tsconfig,
+            });
+        }
+    }
+    const snapshot = readSnapshotState(resolveFingerprintBase(props.projectRoot));
+    if (snapshot === undefined || snapshot.volatile || snapshot.tainted) {
+        throw new Error("Metro's recorded transform snapshot is not reusable.");
+    }
+    const recorded = {};
+    for (const file of snapshot.files) {
+        const baseline = addBaselineInput(inputs, file);
+        recorded[snapshotPathKey(file)] = {
+            hash: baseline.hostHash,
+            identity: baseline.identity,
+        };
+    }
+    return {
+        fingerprint: {
+            configSources: [...configSources].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0),
+            projects: projectFingerprints,
+            snapshot: { id: snapshot.id, inputs: recorded },
+        },
+        inputs,
+        staticInputs: [...staticInputs].sort(),
+    };
+}
+/** Add one lexical path's stable broad state to a key baseline. */
+function addBaselineInput(inputs, file, staticInputs) {
+    const key = snapshotPathKey(file);
+    const observed = api.captureWatchInputBaseline(file);
+    if (observed === undefined) {
+        throw new Error("Unable to read a stable Metro input baseline.");
+    }
+    const existing = inputs[key];
+    if (existing !== undefined) {
+        if (existing.identity !== observed.identity ||
+            existing.fileExists !== observed.fileExists ||
+            ("hostHash" in existing &&
+                stableStringify(existing) !== stableStringify(observed))) {
+            throw new Error("A Metro input changed between baseline observations.");
+        }
+        inputs[key] = { ...existing, ...observed };
+    }
+    else {
+        inputs[key] = observed;
+    }
+    staticInputs?.add(key);
+    return observed;
+}
+/** Add the stable file predicate used by the project-map traversal. */
+function addDiscoveryBaselineInput(inputs, file, staticInputs) {
+    const key = snapshotPathKey(file);
+    const observed = api.captureWatchInputFileBaseline(file);
+    if (observed === undefined) {
+        throw new Error("Unable to read a stable Metro project candidate.");
+    }
+    const existing = inputs[key];
+    if (existing !== undefined &&
+        (existing.identity !== observed.identity ||
+            existing.fileExists !== observed.fileExists)) {
+        throw new Error("A Metro project candidate changed while observed.");
+    }
+    inputs[key] = existing ?? observed;
+    staticInputs.add(key);
+}
 /**
  * A value no other run can reproduce. Folding it means this run's cache entries
  * are written but never reused by later runs, and this run reuses nothing from
- * earlier ones — the sound fallback whenever the recorded out-of-walk input set
+ * earlier ones — the sound fallback whenever the recorded transform input set
  * is unknown or unrepresentable.
  */
 function nonce() {
     return `nonce:${node_crypto.randomBytes(32).toString("hex")}`;
 }
 /**
- * Prepare the snapshot for a new run. Called from `withTtsc` in the single
- * Metro config process, before any worker exists: creates the main snapshot
- * (fresh epoch id) when missing or corrupt, compacts leftover worker files into
- * it, and sweeps unparseable worker files plus crash-leftover temp files. An
- * unparseable worker file's recordings are unrecoverable, so its removal mints
- * a fresh epoch id — every key that might have depended on the lost recordings
- * is soundly orphaned, and later runs stabilize instead of degrading to a nonce
- * forever. A failed rewrite leaves a recovery document outside the snapshot
- * directory so `getCacheKey` degrades to a nonce until a later compaction
- * succeeds. If an older readable main exists and neither location is writable,
- * preparation throws instead of authorizing stale reuse.
+ * Prepare the snapshot for a new run. Called from `withTtsc` before any worker
+ * exists: creates the main snapshot (fresh epoch id) when missing or corrupt,
+ * compacts leftover worker files into it, and sweeps unparseable worker files
+ * plus crash-leftover temp files. Concurrent config processes are serialized; a
+ * contender takes a non-reusable run token instead of racing the mutable main
+ * rewrite. An unparseable worker file's recordings are unrecoverable, so its
+ * removal mints a fresh epoch id — every key that might have depended on the
+ * lost recordings is soundly orphaned, and later runs stabilize instead of
+ * degrading to a nonce forever. A failed rewrite leaves a recovery document
+ * outside the snapshot directory and returns a non-reusable run token. The
+ * token crosses bundle and process boundaries, so `getCacheKey` degrades to a
+ * nonce even when neither snapshot location can persist the failure and an old
+ * main later reappears.
  */
 function prepareSnapshot(projectRoot) {
     const base = resolveFingerprintBase(projectRoot);
-    let hadReadableMain = false;
+    const runId = node_crypto.randomBytes(16).toString("hex");
+    let reusable = true;
     let pending = {
         files: [],
+        tainted: false,
         version: SNAPSHOT_VERSION,
         volatile: false,
     };
+    let releaseCompactionLock;
     try {
         // A nonexistent base can never be a working Metro setup (Metro verifies
         // the project root exists), so preparing a snapshot there would only
         // materialize directory trees at arbitrary paths.
         if (!fs.existsSync(base)) {
-            return;
+            return runId;
         }
         const directory = snapshotDirectory(base);
         fs.mkdirSync(directory, { recursive: true });
+        releaseCompactionLock = acquireSnapshotCompactionLock(directory);
+        if (releaseCompactionLock === undefined) {
+            // Another Metro config process is already rewriting the mutable main
+            // snapshot. It owns all pending worker documents, while this run takes a
+            // private nonce and therefore cannot reuse or publish under a stale key.
+            return `${NON_REUSABLE_RUN_PREFIX}${runId}`;
+        }
         // Read the worker files strictly before the main file (see the module doc
         // comment): a concurrent compactor deletes a worker file only after the
         // merged main is renamed into place, so whatever this enumeration misses
@@ -305,9 +526,9 @@ function prepareSnapshot(projectRoot) {
             throw new Error("Unable to enumerate Metro snapshot state.");
         }
         const main = readMainDocument(directory);
-        hadReadableMain = main !== undefined && typeof main.id === "string";
         const files = new Set(main?.files ?? []);
         const observations = [...recovery.entries, ...workers.entries];
+        const tainted = observations.some((entry) => entry.tainted);
         const volatile = observations.length === 0
             ? (main?.volatile ?? false)
             : // Worker files carry the previous run's fresh observations, so they
@@ -324,9 +545,10 @@ function prepareSnapshot(projectRoot) {
             recovery.corruptPaths.length !== 0;
         pending = {
             files: [...files].sort(),
-            id: !recovering && workers.corruptPaths.length === 0
+            id: !recovering && workers.corruptPaths.length === 0 && !tainted
                 ? (main?.id ?? node_crypto.randomBytes(16).toString("hex"))
                 : node_crypto.randomBytes(16).toString("hex"),
+            tainted: false,
             version: SNAPSHOT_VERSION,
             volatile,
         };
@@ -337,6 +559,7 @@ function prepareSnapshot(projectRoot) {
             ...recovery.paths,
             ...recovery.corruptPaths,
             ...listTemporaryFiles(directory),
+            ...listExpiredKeyBaselines(directory),
         ]) {
             try {
                 fs.rmSync(file, { force: true });
@@ -353,16 +576,133 @@ function prepareSnapshot(projectRoot) {
             unhealthySnapshots.delete(base);
         }
     }
-    catch (snapshotError) {
+    catch {
+        reusable = false;
         try {
             persistUnhealthySnapshot(base, pending);
         }
-        catch (recoveryError) {
-            if (hadReadableMain || hasReadableMainSnapshot(base)) {
-                throw new AggregateError([snapshotError, recoveryError], "Unable to persist Metro snapshot state or its recovery record.");
+        catch {
+            // The returned token carries the failure when neither on-disk location
+            // can. No consumer may turn that token into a reusable cache key.
+        }
+    }
+    finally {
+        if (releaseCompactionLock !== undefined) {
+            try {
+                releaseCompactionLock();
+            }
+            catch {
+                reusable = false;
+                try {
+                    persistUnhealthySnapshot(base, pending);
+                }
+                catch {
+                    // The returned non-reusable token remains the final safety boundary.
+                }
             }
         }
     }
+    return reusable ? runId : `${NON_REUSABLE_RUN_PREFIX}${runId}`;
+}
+/**
+ * Acquire the process-shared lock for the mutable main snapshot.
+ *
+ * A complete owner directory is published atomically, and no process waits
+ * while holding a reusable run identity. A contending process therefore
+ * degrades immediately to a nonce. The owner retires the directory atomically
+ * after every success or failure path has persisted its verdict.
+ */
+function acquireSnapshotCompactionLock(directory) {
+    const lock = path.join(directory, SNAPSHOT_COMPACTION_LOCK);
+    const token = node_crypto.randomBytes(16).toString("hex");
+    const candidate = path.join(directory, `.snapshot-compaction-${process.pid.toString(36)}-${token}`);
+    let candidateCreated = false;
+    try {
+        fs.mkdirSync(candidate);
+        candidateCreated = true;
+        fs.writeFileSync(path.join(candidate, SNAPSHOT_COMPACTION_OWNER), JSON.stringify({ pid: process.pid, token }), "utf8");
+        if (fs.existsSync(lock)) {
+            reapDeadSnapshotCompactionLock(lock);
+            return undefined;
+        }
+        fs.renameSync(candidate, lock);
+        candidateCreated = false;
+    }
+    catch (error) {
+        if (fs.existsSync(lock)) {
+            reapDeadSnapshotCompactionLock(lock);
+            return undefined;
+        }
+        throw error;
+    }
+    finally {
+        if (candidateCreated) {
+            fs.rmSync(candidate, { force: true, recursive: true });
+        }
+    }
+    return () => {
+        const owner = readSnapshotCompactionOwner(lock);
+        if (owner?.pid !== process.pid || owner.token !== token) {
+            throw new Error("Metro snapshot compaction lock ownership changed.");
+        }
+        const retired = path.join(directory, `.snapshot-compaction-released-${token}`);
+        fs.renameSync(lock, retired);
+        try {
+            fs.rmSync(retired, { force: true, recursive: true });
+        }
+        catch {
+            // A retired owner cannot block or be confused with the fixed lock name.
+        }
+    };
+}
+/** Read a complete lock owner; malformed state remains a conservative lock. */
+function readSnapshotCompactionOwner(lock) {
+    try {
+        const value = JSON.parse(fs.readFileSync(path.join(lock, SNAPSHOT_COMPACTION_OWNER), "utf8"));
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            return undefined;
+        }
+        const owner = value;
+        return Number.isSafeInteger(owner.pid) &&
+            owner.pid > 0 &&
+            typeof owner.token === "string" &&
+            /^[a-f0-9]{32}$/.test(owner.token)
+            ? { pid: owner.pid, token: owner.token }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Remove a lock whose recorded process is proven dead.
+ *
+ * The dead owner's random token also names its quarantine. At most one
+ * contender can move the fixed lock there. The quarantine remains as a tiny
+ * election record, so a delayed contender can never move a newer owner's lock
+ * after the first contender has recovered the fixed name.
+ */
+function reapDeadSnapshotCompactionLock(lock) {
+    const owner = readSnapshotCompactionOwner(lock);
+    if (owner === undefined || processIsAlive(owner.pid))
+        return;
+    const quarantine = path.join(path.dirname(lock), `.snapshot-compaction-stale-${owner.token}`);
+    try {
+        fs.renameSync(lock, quarantine);
+    }
+    catch {
+        // Another contender recovered this owner, or the lock changed after read.
+    }
+}
+/** Treat every process-query failure except a definite missing PID as live. */
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
 }
 /**
  * Crash-leftover temp files from the atomic writer, swept at compaction. Only
@@ -390,6 +730,27 @@ function listTemporaryFiles(directory) {
         return [];
     }
 }
+/** Old run baselines that cannot belong to an ordinary live Metro session. */
+function listExpiredKeyBaselines(directory) {
+    const horizon = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    try {
+        return fs
+            .readdirSync(directory)
+            .filter((name) => name.startsWith(KEY_BASELINE_PREFIX) && name.endsWith(".json"))
+            .map((name) => path.join(directory, name))
+            .filter((file) => {
+            try {
+                return fs.statSync(file).mtimeMs < horizon;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Read the unioned snapshot state, or `undefined` when the main snapshot is
  * missing or any snapshot file is corrupt (a torn or foreign write means the
@@ -417,27 +778,62 @@ function readSnapshotState(base) {
     }
     const files = new Set(main.files);
     let volatile = main.volatile;
+    let tainted = main.tainted;
     for (const entry of workers.entries) {
         for (const file of entry.files) {
             files.add(file);
         }
         volatile ||= entry.volatile;
+        tainted ||= entry.tainted;
     }
-    return { files: [...files].sort(), id: main.id, volatile };
+    return { files: [...files].sort(), id: main.id, tainted, volatile };
 }
 /**
- * Recorder held by each Metro worker. It persists out-of-walk watch inputs and
- * missing in-walk paths delivered through the transform core's `addWatchFile`
- * hook, plus any volatile declaration. Existing in-walk files stay covered by
- * the project walk; a missing path must be retained because its creation is a
- * state change that the initial walk could not hash. A clean in-walk transform
- * also writes a document so it can clear a volatile declaration from an earlier
- * run. The unique name makes worker writes race-free; `withTtsc` compacts the
- * files on the next run.
+ * Recorder held by each Metro worker. It persists every derived watch input and
+ * any volatile declaration, compares compiler-generation evidence with the
+ * matching main-process run baseline, and marks any temporal mismatch tainted.
+ * A clean transform also writes a document so it can clear a volatile
+ * declaration from an earlier run. One cumulative document is flushed per
+ * delivered module; the unique name makes worker writes race-free, and
+ * `withTtsc` compacts the files on the next run.
  */
-function createSnapshotRecorder() {
+function createSnapshotRecorder(runId) {
     const suffix = `${process.pid.toString(36)}-${node_crypto.randomBytes(6).toString("hex")}`;
     const states = new Map();
+    const baselines = new Map();
+    const baselineStaticInputs = new Map();
+    function keyBaselineCoverage(input, base) {
+        // A direct recorder without the private run handshake cannot prove that
+        // any input belongs to the main process's static key. Retain every path
+        // without claiming a temporal mismatch. Production always receives a run
+        // id from `withTtsc`; an absent or unreadable matching baseline then fails
+        // closed.
+        if (runId === undefined) {
+            return { matches: true, static: false };
+        }
+        let baseline = baselines.get(base);
+        if (baseline === undefined) {
+            baseline = readKeyBaseline(base, runId) ?? null;
+            baselines.set(base, baseline);
+            baselineStaticInputs.set(base, new Set(baseline?.staticInputs ?? []));
+        }
+        const key = snapshotPathKey(input.file);
+        const expected = baseline?.inputs[key];
+        try {
+            const matches = expected !== undefined &&
+                input.evidence !== undefined &&
+                api.watchInputEvidenceMatchesBaseline(input.evidence, expected);
+            return {
+                matches,
+                static: matches &&
+                    baseline !== null &&
+                    baselineStaticInputs.get(base)?.has(key) === true,
+            };
+        }
+        catch {
+            return { matches: false, static: false };
+        }
+    }
     function stateFor(project) {
         const base = project.base;
         let state = states.get(base);
@@ -446,7 +842,7 @@ function createSnapshotRecorder() {
                 dirty: false,
                 files: new Set(),
                 observed: false,
-                roots: fingerprintRoots(base, project.explicitProject),
+                tainted: false,
                 volatile: false,
             };
             states.set(base, state);
@@ -459,6 +855,7 @@ function createSnapshotRecorder() {
         }
         const document = {
             files: [...state.files].sort(),
+            tainted: state.tainted,
             version: SNAPSHOT_VERSION,
             volatile: state.volatile,
         };
@@ -475,35 +872,47 @@ function createSnapshotRecorder() {
                 persistUnhealthySnapshot(base, document);
             }
             catch (recoveryError) {
-                if (hasReadableMainSnapshot(base)) {
+                // A reusable run id proves that the main process authorized a cache
+                // key. The explicit nonce token is different: it guarantees that this
+                // run's output cannot be reused, so losing its observation is safe.
+                if (isReusableSnapshotRunId(runId) ||
+                    (runId === undefined && hasReadableMainSnapshot(base))) {
                     throw new AggregateError([snapshotError, recoveryError], "Unable to persist a Metro snapshot observation or its recovery record.");
                 }
             }
         }
     }
-    return {
-        record(props) {
-            const base = props.project.base;
-            const state = stateFor(props.project);
-            const input = path.resolve(props.input);
-            const firstObservation = !state.observed;
-            state.observed = true;
-            if (state.files.has(input) ||
-                (fs.existsSync(input) &&
-                    state.roots.some((root) => api.isProjectWalkPath(root, input, undefined, undefined, props.project.policy)))) {
-                // Even when every input belongs to the project walk, the worker must
-                // publish that it performed a clean transform. Otherwise an old main
-                // snapshot with `volatile: true` remains sticky forever.
-                if (firstObservation || state.dirty) {
-                    state.dirty = true;
-                    flush(base, state);
-                }
-                return;
+    function recordMany(props) {
+        const base = props.project.base;
+        const state = stateFor(props.project);
+        const firstObservation = !state.observed;
+        state.observed = true;
+        for (const input of props.inputs) {
+            const file = path.resolve(input.file);
+            const coverage = keyBaselineCoverage({ ...input, file }, base);
+            if (!coverage.matches) {
+                state.tainted = true;
+            }
+            if (!coverage.static && !state.files.has(file)) {
+                state.files.add(file);
+                state.dirty = true;
             }
-            state.files.add(input);
+        }
+        // A clean empty delivery must still clear a volatile verdict from the
+        // preceding run. Persist once for the whole module, not once per input.
+        if (firstObservation || state.tainted) {
             state.dirty = true;
-            flush(base, state);
+        }
+        flush(base, state);
+    }
+    return {
+        record(props) {
+            recordMany({
+                inputs: [{ file: props.input }],
+                project: props.project,
+            });
         },
+        recordMany,
         recordVolatile(props) {
             const base = props.project.base;
             const state = stateFor(props.project);
@@ -517,6 +926,65 @@ function createSnapshotRecorder() {
         },
     };
 }
+/** Filesystem-keyed lexical spelling used by main and worker processes. */
+function snapshotPathKey(file) {
+    const resolved = path.resolve(file);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+/** Persist the exact filesystem state one run's static key observed. */
+function writeKeyBaseline(base, runId, inputs, staticInputs) {
+    if (!isReusableSnapshotRunId(runId)) {
+        throw new Error("Invalid Metro snapshot run identity.");
+    }
+    const file = path.join(snapshotDirectory(base), `${KEY_BASELINE_PREFIX}${runId}.json`);
+    if (fs.existsSync(file)) {
+        const existing = readKeyBaseline(base, runId);
+        if (existing === undefined ||
+            stableStringify(existing.inputs) !== stableStringify(inputs) ||
+            stableStringify(existing.staticInputs) !== stableStringify(staticInputs)) {
+            throw new Error("A Metro run attempted to replace its key baseline.");
+        }
+        return;
+    }
+    writeSnapshotDocument(file, {
+        inputs,
+        runId,
+        staticInputs,
+        version: SNAPSHOT_VERSION,
+    });
+}
+/** Read only the immutable baseline belonging to this worker's run. */
+function readKeyBaseline(base, runId) {
+    if (!isReusableSnapshotRunId(runId)) {
+        return undefined;
+    }
+    try {
+        const value = JSON.parse(fs.readFileSync(path.join(snapshotDirectory(base), `${KEY_BASELINE_PREFIX}${runId}.json`), "utf8"));
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            return undefined;
+        }
+        const document = value;
+        if (document.version !== SNAPSHOT_VERSION ||
+            document.runId !== runId ||
+            typeof document.inputs !== "object" ||
+            document.inputs === null ||
+            Array.isArray(document.inputs) ||
+            Object.values(document.inputs).some((entry) => !api.isWatchInputKeyBaseline(entry)) ||
+            !Array.isArray(document.staticInputs) ||
+            document.staticInputs.some((entry) => typeof entry !== "string" ||
+                !Object.prototype.hasOwnProperty.call(document.inputs, entry))) {
+            return undefined;
+        }
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether a run token is allowed to authorize a reusable static key. */
+function isReusableSnapshotRunId(runId) {
+    return runId !== undefined && /^[a-f0-9]{32}$/.test(runId);
+}
 function snapshotDirectory(base) {
     return path.join(base, ...SNAPSHOT_DIRECTORY);
 }
@@ -656,14 +1124,32 @@ function parseSnapshotDocument(text) {
         return undefined;
     }
     const document = value;
-    if (document.version !== SNAPSHOT_VERSION || !Array.isArray(document.files)) {
+    const keys = Object.keys(document).sort();
+    const expectedKeys = ["files", "tainted", "version", "volatile"];
+    if (Object.prototype.hasOwnProperty.call(document, "id")) {
+        expectedKeys.push("id");
+        expectedKeys.sort();
+    }
+    if (stableStringify(keys) !== stableStringify(expectedKeys) ||
+        document.version !== SNAPSHOT_VERSION ||
+        !Array.isArray(document.files) ||
+        document.files.some((entry) => typeof entry !== "string" ||
+            !(path.posix.isAbsolute(entry) || path.win32.isAbsolute(entry))) ||
+        new Set(document.files).size !== document.files.length ||
+        stableStringify(document.files) !==
+            stableStringify([...document.files].sort()) ||
+        typeof document.tainted !== "boolean" ||
+        typeof document.volatile !== "boolean" ||
+        (document.id !== undefined &&
+            (typeof document.id !== "string" || !/^[a-f0-9]{32}$/.test(document.id)))) {
         return undefined;
     }
     return {
-        files: document.files.filter((entry) => typeof entry === "string"),
+        files: document.files,
         ...(typeof document.id === "string" ? { id: document.id } : {}),
+        tainted: document.tainted,
         version: SNAPSHOT_VERSION,
-        volatile: document.volatile === true,
+        volatile: document.volatile,
     };
 }
 /** Write a snapshot document atomically (unique temp file, then rename). */