gitnexus 1.6.10-rc.99 → 1.6.10

package/dist/core/analyzer-identity.js

@@ -129,7 +129,11 @@ function detectLibcVariant() {
 const LIBC_VARIANT = detectLibcVariant();
 function resolveRuntimeVariant() {
     return {
-        executablePath: resolveExistingPath(process.execPath),
+        // Normalized like build.rootPath (#2668): executablePath is a compared
+        // identity field (only invokedArtifact is stripped in the comparison), and
+        // process.execPath carries the same Windows drive-letter case ambiguity —
+        // so leaving it un-normalized would reintroduce the false-stale via runtime.
+        executablePath: normalizeAnalyzerRootPath(resolveExistingPath(process.execPath), process.platform),
         nodeVersion: process.version,
         platform: process.platform,
         architecture: process.arch,
@@ -150,6 +154,24 @@ function snapshotReadableFile(candidate) {
         ...(link.isSymbolicLink() ? { symlinkTarget: readlinkSync(candidate) } : {}),
     };
 }
+/**
+ * Snapshot a symbolic link without resolving it. Unlike
+ * {@link snapshotReadableFile} this never stats the target, so it is total over
+ * linked directories, dangling links, and links to device nodes — the inputs
+ * that make the readable-file snapshot throw.
+ */
+function snapshotSymlinkArtifact(candidate) {
+    const link = lstatSync(candidate, { bigint: true });
+    if (!link.isSymbolicLink()) {
+        throw new Error(`Analyzer identity input is not a symbolic link: ${candidate}`);
+    }
+    return { link: statState(link), symlinkTarget: readlinkSync(candidate) };
+}
+function snapshotRuntimeArtifact(artifact) {
+    return artifact.kind === 'unfollowed-symlink'
+        ? snapshotSymlinkArtifact(artifact.absolutePath)
+        : snapshotReadableFile(artifact.absolutePath);
+}
 function snapshotDirectory(candidate) {
     const stat = lstatSync(candidate, { bigint: true });
     if (!stat.isDirectory() || stat.isSymbolicLink()) {
@@ -256,6 +278,52 @@ function hashStableFile(candidate) {
 function resolveExistingPath(candidate) {
     return realpathSync.native(path.resolve(candidate));
 }
+/**
+ * Case-stabilize a path's Windows drive letter so two processes that observed
+ * the same directory under different drive-letter casing (`c:\…` vs `C:\…`)
+ * produce byte-identical analyzer-identity path fields (#2668).
+ *
+ * `realpathSync.native` canonicalizes 8.3 short names and symlinks but does not
+ * guarantee the drive-letter case it returns — it can preserve whatever casing
+ * the caller's path carried, and `import.meta.url` casing depends on how each
+ * entry process (CLI shim vs `npx`/npm wrapper vs server worker) was launched.
+ * When `analyze` stamps `build.rootPath` under one casing and `status`
+ * recomputes it under another, `analyzerRunnerIdentitiesEqual` deep-compares
+ * unequal and `status` reports a freshly-analyzed, untouched repo as stale.
+ * Uppercasing the drive letter (drive letters are case-insensitive; uppercase
+ * is the conventional form) collapses that variance. POSIX paths are returned
+ * unchanged. `platform` is explicit so the transform is unit-testable off
+ * Windows.
+ *
+ * The optional `\\?\` extended-length prefix is preserved and the drive letter
+ * after it is still normalized; UNC paths (`\\server\share`, `\\?\UNC\...`)
+ * have no drive letter and are left untouched.
+ *
+ * That optional group is defensive, not a case `realpathSync.native` produces:
+ * libuv's `fs__realpath_handle` strips `\\?\` (and rewrites `\\?\UNC\` back to
+ * `\\`) before returning, so the prefix can only reach here from caller-supplied
+ * input, which `path.resolve` preserves (#2667).
+ *
+ * Preserving it is load-bearing. The roots this normalizes are not just compared —
+ * they are READ FROM: `resolveBuildRoot` joins `package.json` onto `packageRoot`,
+ * `collectBuildEntries` walks `buildRoot`, and the lockfile lookup walks
+ * `packageRoot`'s ancestors. Node does not re-add `\\?\` for over-MAX_PATH paths,
+ * so stripping here would break analyzer-identity resolution on a deep checkout
+ * exactly as it would at any other filesystem boundary. (These fields are also
+ * compared between an `analyze` and a later `status` run, so a shape change would
+ * additionally risk the #2668 false-stale class — but the filesystem reads are the
+ * reason that matters.)
+ *
+ * Registry-style path COMPARISON is a different domain, never opens what it
+ * canonicalizes, and does normalize the prefix away: see
+ * `stripWindowsLongPathPrefix` in `src/lib/utils.ts` and its use in
+ * `canonicalizePath`.
+ */
+export function normalizeAnalyzerRootPath(p, platform) {
+    if (platform !== 'win32')
+        return p;
+    return p.replace(/^(\\\\\?\\)?([a-z]):/, (_match, prefix, drive) => `${prefix ?? ''}${drive.toUpperCase()}:`);
+}
 function isFile(candidate) {
     try {
         return statSync(candidate).isFile();
@@ -274,10 +342,29 @@ function manifestLabel(manifest) {
     const version = typeof manifest.version === 'string' ? manifest.version : '<unversioned>';
     return `${name}@${version}`;
 }
-function isInside(parent, candidate) {
-    const relative = path.relative(parent, candidate);
-    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..');
+/**
+ * Whether `candidate` is `parent` itself or lives beneath it.
+ *
+ * The absolute-result rejection is load-bearing on Windows: `path.relative`
+ * cannot express a relative path between two different drives, so it returns the
+ * absolute target instead — `path.win32.relative('C:\\parent', 'D:\\other')` is
+ * `'D:\\other'`. That string does not start with `..`, so the `..` checks alone
+ * would report an unrelated drive as *inside* the parent. This mirrors the
+ * containment guards elsewhere in the repo (`server/api.ts`,
+ * `server/git-clone.ts`, `group/extractors/fs-utils.ts`), which all pair the
+ * `..` check with `path.isAbsolute`.
+ *
+ * `pathApi` is injectable so the win32 semantics are unit-testable from a POSIX
+ * runner; production callers always use the platform-bound `path`.
+ */
+function isInside(parent, candidate, pathApi = path) {
+    const relative = pathApi.relative(parent, candidate);
+    if (pathApi.isAbsolute(relative))
+        return false;
+    return relative === '' || (!relative.startsWith(`..${pathApi.sep}`) && relative !== '..');
 }
+/** Test seam for {@link isInside} (see `_hashAnalyzerIdentityFramesForTests`). */
+export const _isInsideForTests = isInside;
 function resolveBuildRoot(analyzerModulePath) {
     let cursor = path.dirname(analyzerModulePath);
     while (true) {
@@ -286,9 +373,18 @@ function resolveBuildRoot(analyzerModulePath) {
             const packageRoot = path.dirname(cursor);
             const packageJson = path.join(packageRoot, 'package.json');
             if (lstatSync(packageJson).isFile()) {
+                // Normalize the drive-letter case at this single upstream source so
+                // every derived identity path field — build.rootPath, identityCacheKey,
+                // and (via collectDependencyInputs) dependencyRuntime.manifestPath /
+                // lockfilePath — inherits a case-stable root and analyze-stamp equals
+                // status-recompute regardless of launch-path casing (#2668).
+                // Migration: a Windows index stamped before this fix carries the old,
+                // un-normalized casing, so the first post-upgrade `status` sees one
+                // spurious "stale" flip — self-healing on the next `analyze`, which
+                // re-stamps the normalized (idempotent) form.
                 return {
-                    packageRoot,
-                    buildRoot: cursor,
+                    packageRoot: normalizeAnalyzerRootPath(packageRoot, process.platform),
+                    buildRoot: normalizeAnalyzerRootPath(cursor, process.platform),
                     kind: base === 'src' ? 'source' : 'distribution',
                 };
             }
@@ -519,6 +615,96 @@ function runtimePackageLocator(packageRoot, runtimeRoot) {
     const relative = path.relative(packageRoot, runtimeRoot).split(path.sep).join('/');
     return `relative:${relative}`;
 }
+/** Protocols that name a checkout-local package instead of a registry tarball. */
+const LOCAL_LINK_PROTOCOL_PATTERN = /^(?:file|link|workspace|portal):/;
+/** npm's bare local-path shorthands: `./x`, `../x`, `/x`, `~/x`, `C:\x`. */
+const LOCAL_LINK_PATH_PATTERN = /^(?:\.\.?[/\\]|~[/\\]|[/\\]|[A-Za-z]:)/;
+function isLocallyLinkedSpecifier(specifier) {
+    if (typeof specifier !== 'string')
+        return false;
+    const value = specifier.trim();
+    return LOCAL_LINK_PROTOCOL_PATTERN.test(value) || LOCAL_LINK_PATH_PATTERN.test(value);
+}
+/**
+ * Whether a REALPATH'd package root lives inside some installed dependency
+ * tree. Used as the resolved-location half of "is this dependency a checkout
+ * this repository owns?" (see {@link undeclaredLocalDevDependencyNames}).
+ *
+ * The input must already be realpath'd: `resolveDependencyPackageRoot` returns
+ * `realpathSync.native`, so a package reached through a link out of
+ * `node_modules` reports its checkout location and a package that merely lives
+ * in `node_modules` reports a path that still carries the segment.
+ *
+ * `pathApi` is injectable so the Windows separator handling is unit-testable
+ * from a POSIX runner, exactly as {@link isInside} does. The separator sets
+ * differ deliberately: `\` is a legal filename character on POSIX, so only
+ * win32 may treat it as a boundary.
+ */
+function hasNodeModulesSegment(candidate, pathApi = path) {
+    const segments = pathApi.sep === '\\' ? candidate.split(/[\\/]+/) : candidate.split('/');
+    return segments.includes('node_modules');
+}
+/** Test seam for {@link hasNodeModulesSegment} (see {@link _isInsideForTests}). */
+export const _hasNodeModulesSegmentForTests = hasNodeModulesSegment;
+/**
+ * How many dev dependencies may be admitted by RESOLVED LOCATION alone before
+ * the whole resolved-location channel is treated as untrustworthy and disabled.
+ *
+ * "Realpath carries no `node_modules` segment" is a proxy for "checkout-local",
+ * and a layout that materializes packages outside `node_modules` — pnpm with a
+ * relocated `virtual-store-dir`, a custom linker — makes every dev dependency
+ * pass it. Folding an entire dev tree into the receipt is not a graceful
+ * degradation: `runtimePackages`/`runtimeEntries`/`runtimeBytes` THROW, so a
+ * mis-fired proxy on a legitimate install would abort analyze outright.
+ *
+ * The bound is therefore on ADMISSIONS, and overflow admits NONE of them rather
+ * than an arbitrary prefix. A prefix would not bound the failure — the abort
+ * comes from the transitive payload of whichever trees get folded in — and it
+ * would make the receipt depend on an arbitrary slice of a sorted name list.
+ * Dropping the channel wholesale falls back to the specifier-only receipt,
+ * which is the behaviour that ships today and is known not to abort, and leaves
+ * the declared-intent half in {@link dependencyNames} untouched.
+ *
+ * Four is measured, not guessed. Monorepo and workspace links are declared
+ * (`file:`/`link:`/`workspace:`) and travel the uncapped declared half, so this
+ * channel only ever carries UNDECLARED `npm link <pkg>` — a manual, per-package
+ * developer action, in practice one or two packages. A mis-fire admits the
+ * entire dev-only set instead: 13 names in this repository's own install, tens
+ * in a typical application. The cap sits an order of magnitude below the
+ * mis-fire population and comfortably above realistic link counts.
+ */
+const MAX_UNDECLARED_LOCAL_DEV_DEPENDENCIES = 4;
+/**
+ * Dependency names whose resolved packages can contribute analyzer semantics.
+ *
+ * The three runtime sections are enumerated wholesale. `devDependencies` are
+ * deliberately not: a registry dev tool (vitest, eslint, typescript) is never
+ * loaded by the analyzer, and folding the dev tree into the receipt would churn
+ * `dependencyRuntime.digest` — and force a full re-analysis — on every unrelated
+ * devDependency bump.
+ *
+ * Locally linked dev dependencies are the exception. A `file:`/`link:`/
+ * `workspace:` sibling is part of this checkout and ships code the analyzer
+ * imports at runtime: GitNexus links `gitnexus-shared`, whose schema constants
+ * feed `RELATION_SCHEMA`/`NODE_SCHEMA_QUERIES`. In `kind: 'source'` runs that
+ * sibling sits outside `buildRoot`, so leaving it out let a semantic change
+ * there alter analyzer behaviour while moving neither `build.digest` nor
+ * `dependencyRuntime.digest` — DDL-affecting edits were still caught by the
+ * schema fingerprint, semantics-only edits by nothing.
+ *
+ * An unresolvable link (a published install, where the sibling checkout does not
+ * exist) still contributes its `<missing>` edge, so the linked package appearing
+ * or disappearing remains a receipt change rather than a silent one. That is why
+ * the specifier check cannot be replaced by resolution: resolution returns
+ * `null` for an absent linked checkout exactly as it does for an uninstalled
+ * registry dev tool, and the two must not be conflated.
+ *
+ * This function is the DECLARED-INTENT half and is enumerated for every package
+ * in the dependency BFS, so it must stay a pure function of the manifest. The
+ * RESOLVED-LOCATION half — `npm link <pkg>`, which leaves the specifier a
+ * registry range — lives in {@link undeclaredLocalDevDependencyNames} and is
+ * applied to the root package only.
+ */
 function dependencyNames(manifest) {
     const names = new Set();
     for (const section of [
@@ -531,6 +717,13 @@ function dependencyNames(manifest) {
         for (const name of Object.keys(section))
             names.add(name);
     }
+    const development = manifest.devDependencies;
+    if (development && typeof development === 'object') {
+        for (const [name, specifier] of Object.entries(development)) {
+            if (isLocallyLinkedSpecifier(specifier))
+                names.add(name);
+        }
+    }
     return [...names].sort(compareBytes);
 }
 function resolveDependencyPackageRoot(fromRoot, packageName, pathGuards, limits) {
@@ -563,6 +756,51 @@ function resolveDependencyPackageRoot(fromRoot, packageName, pathGuards, limits)
         cursor = parent;
     }
 }
+/**
+ * Dev dependencies that are locally linked by INSTALLED LOCATION rather than by
+ * declared specifier — the `npm link <pkg>` shape, where the manifest still
+ * carries a registry range while `node_modules/<pkg>` is a symlink into a
+ * working checkout. {@link isLocallyLinkedSpecifier} is blind to those, yet the
+ * linked code is exactly as load-bearing for analyzer semantics as a declared
+ * `file:` sibling, so a semantic-only edit there would move neither digest.
+ *
+ * The resolver already knows: {@link resolveDependencyPackageRoot} returns a
+ * realpath, so a linked package reports a root outside every `node_modules`
+ * tree while an ordinary installed package cannot.
+ *
+ * Two properties are load-bearing and must not be relaxed:
+ *
+ * 1. ROOT ONLY. {@link dependencyNames} runs for every package in the BFS, and
+ *    published tarballs keep their `devDependencies`, so probing dev-only names
+ *    everywhere costs 1998 resolutions rather than the ~13 this manifest
+ *    declares — measured on this install, with 0 true positives. Persisted
+ *    `dependencyPathGuards` grow 2220 → 11049, and every guard is re-probed on
+ *    each warm validation, so the cost is recurring and on the `status` path.
+ *    Root-only costs 13 resolutions and ~29 guards.
+ * 2. An unresolvable name is NEVER admitted. `null` here means "uninstalled
+ *    registry dev tool" far more often than "broken link", and admitting it
+ *    would emit a `<missing>` edge for every dev tool absent from a published
+ *    install. Declared links keep that edge through {@link dependencyNames};
+ *    undeclared ones have no declaration to honour.
+ *
+ * The admission count is bounded by {@link MAX_UNDECLARED_LOCAL_DEV_DEPENDENCIES}.
+ */
+function undeclaredLocalDevDependencyNames(rootPackage, pathGuards, limits) {
+    const development = rootPackage.manifest.devDependencies;
+    if (!development || typeof development !== 'object')
+        return [];
+    const admitted = [];
+    for (const [name, specifier] of Object.entries(development)) {
+        // Already carried by the declared half; resolving again would only add
+        // guards. Its `<missing>` edge is that half's responsibility.
+        if (isLocallyLinkedSpecifier(specifier))
+            continue;
+        const resolved = resolveDependencyPackageRoot(rootPackage.root, name, pathGuards, limits);
+        if (resolved !== null && !hasNodeModulesSegment(resolved))
+            admitted.push(name);
+    }
+    return admitted.length <= MAX_UNDECLARED_LOCAL_DEV_DEPENDENCIES ? admitted : [];
+}
 function collectRuntimePackages(packageRoot, directoryGuards, pathGuards, options, budget, limits) {
     const rootManifestPath = path.join(packageRoot, 'package.json');
     recordDirectoryGuard(directoryGuards, packageRoot);
@@ -582,7 +820,20 @@ function collectRuntimePackages(packageRoot, directoryGuards, pathGuards, option
     budget.packages = 1;
     for (let index = 0; index < queue.length; index += 1) {
         const parent = queue[index];
-        for (const dependencyName of dependencyNames(parent.manifest)) {
+        // The declared half is enumerated for every package; the resolved-location
+        // half is scoped to the root package, where the 1998-resolution /
+        // 8829-extra-guard blow-up documented on
+        // `undeclaredLocalDevDependencyNames` cannot occur. Dropping this scope is
+        // the expensive regression, so it is pinned by a guard-count test.
+        const dependencies = parent.root === packageRoot
+            ? [
+                ...new Set([
+                    ...dependencyNames(parent.manifest),
+                    ...undeclaredLocalDevDependencyNames(parent, pathGuards, limits),
+                ]),
+            ].sort(compareBytes)
+            : dependencyNames(parent.manifest);
+        for (const dependencyName of dependencies) {
             budget.edges += 1;
             if (budget.edges > limits.runtimeEdges) {
                 throw new Error(`Analyzer dependency graph exceeded ${limits.runtimeEdges} edges: ${packageRoot}`);
@@ -658,22 +909,63 @@ function collectArtifacts(root, canonicalPrefix, directoryGuards, options, budge
             throw new Error(`Analyzer runtime payload scan exceeded ${limits.runtimeEntries} entries: ${root}`);
         }
         for (const entry of entries) {
+            const absolutePath = path.join(absoluteDir, entry.name);
+            const relativePath = path.relative(root, absolutePath).split(path.sep).join('/');
+            const stat = lstatSync(absolutePath);
             // Nested dependencies are collected from their manifests as separate
             // packages. Only prune those separately traversed trees and VCS
             // metadata; generic cache/model directories can contain loadable code,
             // native addons, Wasm modules, or data consumed by the runtime.
-            if (entry.isDirectory() && PRUNED_RUNTIME_DIRECTORIES.has(entry.name)) {
+            //
+            // Pruning is decided by NAME alone. These four names never carry analyzer
+            // payload in any form: `node_modules` is traversed separately through
+            // `resolveDependencyPackageRoot` (which follows links and guards each
+            // hop), and a `.git`/`.hg`/`.svn` entry is VCS metadata whether it is a
+            // directory, a symbolic link into a shared store, or — inside a submodule
+            // or linked worktree checkout — a regular file holding a gitdir pointer.
+            // Hashing that pointer would make analyzer identity depend on where the
+            // checkout happens to live, which is a false-stale source, not a
+            // semantic input.
+            if (PRUNED_RUNTIME_DIRECTORIES.has(entry.name))
                 continue;
-            }
-            const absolutePath = path.join(absoluteDir, entry.name);
-            const relativePath = path.relative(root, absolutePath).split(path.sep).join('/');
-            const stat = lstatSync(absolutePath);
             if (stat.isDirectory()) {
                 if (depth >= limits.runtimeDepth) {
                     throw new Error(`Analyzer runtime payload scan exceeded depth ${limits.runtimeDepth}: ${absolutePath}`);
                 }
                 pending.push({ absoluteDir: absolutePath, depth: depth + 1 });
             }
+            else if (stat.isSymbolicLink() && !isFile(absolutePath)) {
+                // A symbolic link that does not resolve to a regular file must never
+                // reach the payload branch below: `snapshotReadableFile` stats the
+                // target, and a directory (or a dangling link) makes it throw, aborting
+                // the entire analyze. Workspace-linked checkouts made this reachable
+                // for every name, not just the pruned four — `dist -> build`, a
+                // vendored-grammar link, anything a sibling checkout ships.
+                //
+                // Such links are RECORDED by their link text rather than followed.
+                // Following them would (a) recurse without cycle protection — this
+                // traversal has none, so `self -> .` would ride the depth limit, which
+                // THROWS, trading one hard abort for another; (b) re-scan trees already
+                // reached by their real path, inflating the entry/byte budgets that
+                // also throw; and (c) need a whole containment/TOCTOU trust boundary
+                // for targets outside the package. Recording the text is cycle-free,
+                // costs one `readlink`, and still moves the receipt when the link is
+                // retargeted. The trade-off is that a link's target contributes no
+                // content of its own: when it points outside the package, only the
+                // link text is covered. Links that DO resolve to a regular file keep
+                // their content digest below, unchanged.
+                if (shouldHashRuntimePayload(relativePath)) {
+                    budget.artifacts += 1;
+                    if (budget.artifacts > limits.runtimePayloads) {
+                        throw new Error(`Analyzer runtime payload scan exceeded ${limits.runtimePayloads} payloads: ${root}`);
+                    }
+                    artifacts.push({
+                        absolutePath,
+                        canonicalPath: `${canonicalPrefix}/${relativePath}`,
+                        kind: 'unfollowed-symlink',
+                    });
+                }
+            }
             else if ((stat.isFile() || stat.isSymbolicLink()) &&
                 shouldHashRuntimePayload(relativePath)) {
                 const readableState = snapshotReadableFile(absolutePath);
@@ -811,7 +1103,7 @@ function dependencySnapshot(inputs) {
             absolutePath: artifact.absolutePath,
             canonicalPath: artifact.canonicalPath,
             kind: artifact.kind,
-            state: snapshotReadableFile(artifact.absolutePath),
+            state: snapshotRuntimeArtifact(artifact),
         })),
         directories: [...inputs.directoryGuards.entries()]
             .map(([absolutePath, guard]) => ({ absolutePath, ...guard }))
@@ -825,9 +1117,26 @@ function artifactCacheKey(artifact) {
     return JSON.stringify([artifact.kind, artifact.canonicalPath, artifact.absolutePath]);
 }
 function hashRuntimeArtifact(artifact, cache, options) {
+    if (artifact.kind === 'unfollowed-symlink') {
+        // The link text is the entire payload, so there is no file read for a
+        // cached digest to amortize: recompute it and stay independent of the
+        // cache's freshness. The distinct frame label keeps a link recording from
+        // ever colliding with a content digest.
+        const state = snapshotSymlinkArtifact(artifact.absolutePath);
+        return {
+            ...artifact,
+            state,
+            digest: hashCanonicalFrames([
+                ['runtime-payload-link-v1', artifact.kind, state.symlinkTarget],
+            ]),
+        };
+    }
     const before = snapshotReadableFile(artifact.absolutePath);
-    if (cache && SHA256_PATTERN.test(cache.digest) && isDeepStrictEqual(cache.state, before)) {
-        return { digest: cache.digest, state: before };
+    if (cache &&
+        cache.kind !== 'unfollowed-symlink' &&
+        SHA256_PATTERN.test(cache.digest) &&
+        isDeepStrictEqual(cache.state, before)) {
+        return { ...artifact, state: before, digest: cache.digest };
     }
     const stable = hashStableFile(artifact.absolutePath);
     const digest = hashCanonicalFrames([
@@ -843,7 +1152,7 @@ function hashRuntimeArtifact(artifact, cache, options) {
         path: artifact.absolutePath,
         bytes: stable.bytes,
     });
-    return { digest, state: stable.state };
+    return { ...artifact, state: stable.state, digest };
 }
 function compareEdges(a, b) {
     return compareBytes(JSON.stringify([
@@ -908,7 +1217,7 @@ function hashDependencyRuntime(inputs, cache, options, runtimeVariant) {
             artifact.kind,
             digestBytes(hashed.digest),
         ]);
-        nextArtifacts.push({ ...artifact, state: hashed.state, digest: hashed.digest });
+        nextArtifacts.push(hashed);
     }
     return {
         identity: {
@@ -936,6 +1245,17 @@ function isReadableFileState(value) {
         isStatState(record.target) &&
         (record.symlinkTarget === undefined || typeof record.symlinkTarget === 'string'));
 }
+function isSymlinkArtifactState(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    // `target === undefined` keeps a readable-file state from masquerading as an
+    // unresolved link recording, which would otherwise be validated against the
+    // wrong guard mode on the warm path.
+    return (isStatState(record.link) &&
+        typeof record.symlinkTarget === 'string' &&
+        record.target === undefined);
+}
 function isDependencyPathGuardResult(value) {
     if (value === null)
         return true;
@@ -1081,13 +1401,16 @@ function isIdentityCachePayload(value, packageRoot, buildRoot, runtimeVariant, t
         if (typeof entry !== 'object' || entry === null)
             return false;
         const item = entry;
-        return (typeof item.absolutePath === 'string' &&
-            path.isAbsolute(item.absolutePath) &&
-            typeof item.canonicalPath === 'string' &&
-            (item.kind === 'file' || item.kind === 'symlink') &&
-            isReadableFileState(item.state) &&
-            typeof item.digest === 'string' &&
-            SHA256_PATTERN.test(item.digest));
+        if (typeof item.absolutePath !== 'string' ||
+            !path.isAbsolute(item.absolutePath) ||
+            typeof item.canonicalPath !== 'string' ||
+            typeof item.digest !== 'string' ||
+            !SHA256_PATTERN.test(item.digest)) {
+            return false;
+        }
+        return item.kind === 'unfollowed-symlink'
+            ? isSymlinkArtifactState(item.state)
+            : (item.kind === 'file' || item.kind === 'symlink') && isReadableFileState(item.state);
     });
     const hasBuildRootGuard = record.buildDirectoryGuards.some((entry) => typeof entry === 'object' &&
         entry !== null &&
@@ -1509,9 +1832,24 @@ function validateIdentityCache(cache, options) {
         }
     }
     for (const artifact of cache.artifactEntries) {
-        if (!add({ absolutePath: artifact.absolutePath, mode: 'readable-file' }, { type: 'readable-file', state: artifact.state })) {
+        // A recorded link is re-probed as a link, never as a readable file: the
+        // readable-file probe resolves the target and would report `null` for the
+        // very inputs this kind exists to describe, failing every warm validation.
+        const probe = artifact.kind === 'unfollowed-symlink'
+            ? {
+                request: { absolutePath: artifact.absolutePath, mode: 'link' },
+                expected: {
+                    type: 'symlink',
+                    state: artifact.state.link,
+                    symlinkTarget: artifact.state.symlinkTarget,
+                },
+            }
+            : {
+                request: { absolutePath: artifact.absolutePath, mode: 'readable-file' },
+                expected: { type: 'readable-file', state: artifact.state },
+            };
+        if (!add(probe.request, probe.expected))
             return false;
-        }
     }
     const entries = [...expected.entries()];
     const requests = entries.map(([key]) => {