gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/core/analyzer-identity.js

@@ -0,0 +1,2158 @@
+/**
+ * Reproducible analyzer identity stamped into RepoMeta after a successful run.
+ *
+ * Schema v4 uses length-prefixed canonical frames. Build files and runtime
+ * artifacts contribute SHA-256 payload digests, so a validated stat inventory
+ * can safely reuse those expensive per-file digests across short-lived CLI and
+ * server-worker processes. The cache is only an optimization: malformed,
+ * mismatched, or missing entries are rehashed, and every identity calculation
+ * performs a final return-boundary inventory before returning.
+ *
+ * `invokedArtifact` remains in the receipt for diagnostics, but is deliberately
+ * excluded from semantic freshness. The CLI and the server analyze worker are
+ * different entry files inside the same build tree; alternating between them
+ * must not make an otherwise identical index stale.
+ */
+import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { isDeepStrictEqual } from 'node:util';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const ANALYZER_RUNNER_IDENTITY_SCHEMA_VERSION = 4;
+const BUILD_CANONICALIZATION = 'gitnexus-analyzer-build-v2';
+const DEPENDENCY_RUNTIME_CANONICALIZATION = 'gitnexus-analyzer-dependency-runtime-v4';
+const IDENTITY_CACHE_SCHEMA_VERSION = 6;
+const MAX_CACHE_ENTRIES = 100_000;
+const MAX_CACHE_FILE_BYTES = 64 * 1024 * 1024;
+const HASH_BUFFER_BYTES = 256 * 1024;
+const SHA256_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const DEFAULT_TRAVERSAL_LIMITS = {
+    buildEntries: 100_000,
+    buildDepth: 128,
+    buildBytes: 512 * 1024 * 1024,
+    runtimePackages: 10_000,
+    runtimeEdges: 100_000,
+    runtimeEntries: 250_000,
+    runtimeDepth: 64,
+    runtimePayloads: 100_000,
+    runtimeBytes: 2 * 1024 * 1024 * 1024,
+    resolutionAncestors: 256,
+};
+function toBuffer(value) {
+    return Buffer.isBuffer(value) ? value : Buffer.from(value);
+}
+/** Update a hash with one unambiguous, length-prefixed canonical record. */
+function updateCanonicalFrame(hash, fields) {
+    const fieldCount = Buffer.allocUnsafe(4);
+    fieldCount.writeUInt32BE(fields.length);
+    hash.update(fieldCount);
+    for (const field of fields) {
+        const bytes = toBuffer(field);
+        const length = Buffer.allocUnsafe(8);
+        length.writeBigUInt64BE(BigInt(bytes.length));
+        hash.update(length);
+        hash.update(bytes);
+    }
+}
+function hashCanonicalFrames(frames) {
+    const hash = createHash('sha256');
+    for (const frame of frames)
+        updateCanonicalFrame(hash, frame);
+    return `sha256:${hash.digest('hex')}`;
+}
+/** @internal Regression seam for adversarial canonical-framing tests. */
+export const _hashAnalyzerIdentityFramesForTests = hashCanonicalFrames;
+function sha256(payload) {
+    return `sha256:${createHash('sha256').update(payload).digest('hex')}`;
+}
+function digestBytes(digest) {
+    if (!SHA256_PATTERN.test(digest))
+        throw new Error(`Invalid SHA-256 digest: ${digest}`);
+    return Buffer.from(digest.slice('sha256:'.length), 'hex');
+}
+function statState(stat) {
+    const bigintStat = stat;
+    return {
+        dev: String(bigintStat.dev),
+        ino: String(bigintStat.ino),
+        mode: String(bigintStat.mode),
+        nlink: String(bigintStat.nlink),
+        size: String(bigintStat.size),
+        mtimeNs: String(bigintStat.mtimeNs),
+        ctimeNs: String(bigintStat.ctimeNs),
+    };
+}
+function resolveTraversalLimits(options) {
+    const overrides = options.traversalLimits ?? {};
+    const resolved = { ...DEFAULT_TRAVERSAL_LIMITS };
+    for (const key of Object.keys(DEFAULT_TRAVERSAL_LIMITS)) {
+        const value = overrides[key];
+        if (value === undefined)
+            continue;
+        if (!Number.isSafeInteger(value) || value < 1) {
+            throw new Error(`Analyzer identity traversal limit ${key} must be a positive safe integer`);
+        }
+        resolved[key] = Math.min(value, DEFAULT_TRAVERSAL_LIMITS[key]);
+    }
+    return resolved;
+}
+function stateSize(state, label) {
+    const value = BigInt(state.size);
+    if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error(`Analyzer identity input has an unsupported size: ${label}`);
+    }
+    return Number(value);
+}
+function detectLibcVariant() {
+    if (process.platform !== 'linux')
+        return 'not-applicable';
+    try {
+        const report = process.report?.getReport();
+        const glibc = report?.header?.glibcVersionRuntime;
+        if (typeof glibc === 'string' && glibc.length > 0)
+            return `glibc:${glibc}`;
+        if (Array.isArray(report?.sharedObjects)) {
+            const musl = report.sharedObjects.find((entry) => typeof entry === 'string' && /(?:^|[/\\])(?:ld-)?musl[^/\\]*\.so/i.test(entry));
+            if (musl)
+                return `musl:${path.basename(musl)}`;
+        }
+    }
+    catch {
+        // Runtime reporting is optional on some embedded Node builds. Unknown is
+        // still a distinct, fail-closed variant rather than being conflated with
+        // glibc or a known musl loader.
+    }
+    return 'linux-libc:unknown';
+}
+const LIBC_VARIANT = detectLibcVariant();
+function resolveRuntimeVariant() {
+    return {
+        // 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,
+        endianness: os.endianness(),
+        modulesAbi: process.versions.modules ?? 'unknown',
+        napiAbi: process.versions.napi ?? 'unknown',
+        libc: LIBC_VARIANT,
+    };
+}
+function snapshotReadableFile(candidate) {
+    const link = lstatSync(candidate, { bigint: true });
+    const target = statSync(candidate, { bigint: true });
+    if (!target.isFile())
+        throw new Error(`Analyzer identity input is not a file: ${candidate}`);
+    return {
+        link: statState(link),
+        target: statState(target),
+        ...(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()) {
+        throw new Error(`Analyzer identity input is not a directory: ${candidate}`);
+    }
+    return statState(stat);
+}
+function readDirectory(candidate, options) {
+    options.onCacheMissWork?.({ kind: 'directory-walk', path: candidate });
+    return readdirSync(candidate, { withFileTypes: true });
+}
+function directoryEntriesDigestFrom(entriesInput) {
+    const entries = entriesInput
+        .map((entry) => ({
+        name: entry.name,
+        kind: entry.isDirectory()
+            ? 'directory'
+            : entry.isFile()
+                ? 'file'
+                : entry.isSymbolicLink()
+                    ? 'symlink'
+                    : 'other',
+    }))
+        .sort((a, b) => compareBytes(a.name, b.name));
+    const hash = createHash('sha256');
+    updateCanonicalFrame(hash, ['directory-entries-v1']);
+    for (const entry of entries)
+        updateCanonicalFrame(hash, [entry.name, entry.kind]);
+    return `sha256:${hash.digest('hex')}`;
+}
+function directoryEntriesDigest(candidate) {
+    return directoryEntriesDigestFrom(readdirSync(candidate, { withFileTypes: true }));
+}
+function snapshotDirectoryInventory(candidate) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const before = snapshotDirectory(candidate);
+        const entriesDigest = directoryEntriesDigest(candidate);
+        const after = snapshotDirectory(candidate);
+        if (isDeepStrictEqual(before, after))
+            return { state: after, entriesDigest };
+    }
+    throw new Error(`Analyzer identity directory changed while it was read: ${candidate}`);
+}
+function readStableFile(candidate) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const before = snapshotReadableFile(candidate);
+        const bytes = readFileSync(candidate);
+        const after = snapshotReadableFile(candidate);
+        if (isDeepStrictEqual(before, after))
+            return { bytes, state: after };
+    }
+    throw new Error(`Analyzer identity input changed while it was being read: ${candidate}`);
+}
+function readStableFileWithinBudget(candidate, budget, maxBytes) {
+    const before = snapshotReadableFile(candidate);
+    const bytes = stateSize(before.target, candidate);
+    if (budget.bytes + bytes > maxBytes) {
+        throw new Error(`Analyzer runtime scan exceeded ${maxBytes} bytes: ${candidate}`);
+    }
+    const stable = readStableFile(candidate);
+    budget.bytes += stable.bytes.length;
+    return stable;
+}
+/** Hash a stable file through a fixed-size buffer instead of materializing it. */
+function hashStableFile(candidate) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const before = snapshotReadableFile(candidate);
+        const expectedBytes = stateSize(before.target, candidate);
+        let descriptor = null;
+        try {
+            descriptor = openSync(candidate, fsConstants.O_RDONLY);
+            const openedBefore = statState(fstatSync(descriptor, { bigint: true }));
+            if (!isDeepStrictEqual(openedBefore, before.target))
+                continue;
+            const hash = createHash('sha256');
+            const buffer = Buffer.allocUnsafe(HASH_BUFFER_BYTES);
+            let bytes = 0;
+            while (true) {
+                const read = readSync(descriptor, buffer, 0, buffer.length, null);
+                if (read === 0)
+                    break;
+                hash.update(buffer.subarray(0, read));
+                bytes += read;
+                if (bytes > expectedBytes)
+                    break;
+            }
+            const openedAfter = statState(fstatSync(descriptor, { bigint: true }));
+            closeSync(descriptor);
+            descriptor = null;
+            const after = snapshotReadableFile(candidate);
+            if (bytes === expectedBytes &&
+                isDeepStrictEqual(openedBefore, openedAfter) &&
+                isDeepStrictEqual(before, after)) {
+                return { digest: `sha256:${hash.digest('hex')}`, state: after, bytes };
+            }
+        }
+        finally {
+            if (descriptor !== null)
+                closeSync(descriptor);
+        }
+    }
+    throw new Error(`Analyzer identity input changed while it was being hashed: ${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();
+    }
+    catch {
+        return false;
+    }
+}
+function readManifest(manifestPath, options, budget, limits) {
+    options.onCacheMissWork?.({ kind: 'manifest-read', path: manifestPath });
+    const { bytes, state } = readStableFileWithinBudget(manifestPath, budget, limits.runtimeBytes);
+    return { bytes, state, manifest: JSON.parse(bytes.toString('utf8')) };
+}
+function manifestLabel(manifest) {
+    const name = typeof manifest.name === 'string' ? manifest.name : '<unnamed>';
+    const version = typeof manifest.version === 'string' ? manifest.version : '<unversioned>';
+    return `${name}@${version}`;
+}
+/**
+ * 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) {
+        const base = path.basename(cursor);
+        if (base === 'src' || base === 'dist') {
+            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: normalizeAnalyzerRootPath(packageRoot, process.platform),
+                    buildRoot: normalizeAnalyzerRootPath(cursor, process.platform),
+                    kind: base === 'src' ? 'source' : 'distribution',
+                };
+            }
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    throw new Error(`Cannot resolve GitNexus package root from analyzer module: ${analyzerModulePath}`);
+}
+function compareBytes(a, b) {
+    return Buffer.compare(Buffer.from(a), Buffer.from(b));
+}
+function collectBuildEntries(buildRoot, options, limits) {
+    const entries = [];
+    const pending = [
+        { absoluteDir: buildRoot, depth: 0 },
+    ];
+    let scannedEntries = 0;
+    let scannedBytes = 0;
+    while (pending.length > 0) {
+        const next = pending.pop();
+        if (!next)
+            break;
+        const { absoluteDir, depth } = next;
+        const directoryEntries = readDirectory(absoluteDir, options);
+        scannedEntries += directoryEntries.length;
+        if (scannedEntries > limits.buildEntries) {
+            throw new Error(`Analyzer build scan exceeded ${limits.buildEntries} entries: ${buildRoot}`);
+        }
+        for (const entry of directoryEntries) {
+            const absolutePath = path.join(absoluteDir, entry.name);
+            const relativePath = path.relative(buildRoot, absolutePath).split(path.sep).join('/');
+            const link = lstatSync(absolutePath, { bigint: true });
+            if (link.isDirectory()) {
+                entries.push({
+                    absolutePath,
+                    relativePath,
+                    kind: 'directory',
+                    state: statState(link),
+                });
+                if (depth >= limits.buildDepth) {
+                    throw new Error(`Analyzer build scan exceeded depth ${limits.buildDepth}: ${absolutePath}`);
+                }
+                pending.push({ absoluteDir: absolutePath, depth: depth + 1 });
+            }
+            else if (link.isFile()) {
+                const state = statState(link);
+                scannedBytes += stateSize(state, absolutePath);
+                if (scannedBytes > limits.buildBytes) {
+                    throw new Error(`Analyzer build scan exceeded ${limits.buildBytes} bytes: ${buildRoot}`);
+                }
+                entries.push({ absolutePath, relativePath, kind: 'file', state });
+            }
+            else if (link.isSymbolicLink()) {
+                entries.push({ absolutePath, relativePath, kind: 'symlink', state: statState(link) });
+            }
+            else {
+                throw new Error(`Unsupported analyzer build entry: ${absolutePath}`);
+            }
+        }
+    }
+    entries.sort((a, b) => compareBytes(a.relativePath, b.relativePath));
+    return entries;
+}
+function buildSnapshot(entries) {
+    return entries.map(({ relativePath, kind, state }) => ({ relativePath, kind, state }));
+}
+function buildCacheKey(entry) {
+    return JSON.stringify([entry.kind, entry.relativePath]);
+}
+function hashBuildTree(buildRoot, cache, options, limits) {
+    const entries = collectBuildEntries(buildRoot, options, limits);
+    const cachedEntries = new Map((cache?.buildEntries ?? []).map((entry) => [buildCacheKey(entry), entry]));
+    const nextEntries = [];
+    const hash = createHash('sha256');
+    updateCanonicalFrame(hash, ['domain', BUILD_CANONICALIZATION]);
+    for (const entry of entries) {
+        const cached = cachedEntries.get(buildCacheKey(entry));
+        let digest;
+        if (entry.kind !== 'directory' &&
+            cached?.digest &&
+            SHA256_PATTERN.test(cached.digest) &&
+            isDeepStrictEqual(cached.state, entry.state)) {
+            digest = cached.digest;
+        }
+        else if (entry.kind === 'file') {
+            const stable = hashStableFile(entry.absolutePath);
+            entry.state = stable.state.link;
+            digest = stable.digest;
+            options.onHashedInput?.({
+                kind: 'build',
+                path: entry.absolutePath,
+                bytes: stable.bytes,
+            });
+        }
+        else if (entry.kind === 'symlink') {
+            // Imported files and directories are resolved through symlinks by Node.
+            // Hashing only link text would let bytes outside buildRoot change without
+            // changing the receipt. Reject them instead of inventing an incomplete
+            // recursive trust boundary (target containment, cycles, and TOCTOU).
+            throw new Error(`Analyzer build symbolic links are not supported; materialize the build tree: ${entry.absolutePath}`);
+        }
+        updateCanonicalFrame(hash, [
+            'build-entry',
+            entry.relativePath,
+            entry.kind,
+            digest ? digestBytes(digest) : Buffer.alloc(0),
+        ]);
+        nextEntries.push({
+            relativePath: entry.relativePath,
+            kind: entry.kind,
+            state: entry.state,
+            ...(digest ? { digest } : {}),
+        });
+    }
+    const directoryGuards = [
+        { relativePath: '', state: snapshotDirectory(buildRoot), entriesDigest: '' },
+        ...nextEntries
+            .filter((entry) => entry.kind === 'directory')
+            .map((entry) => ({
+            relativePath: entry.relativePath,
+            state: entry.state,
+            entriesDigest: '',
+        })),
+    ].map((guard) => {
+        const absolutePath = guard.relativePath
+            ? path.join(buildRoot, ...guard.relativePath.split('/'))
+            : buildRoot;
+        const inventory = snapshotDirectoryInventory(absolutePath);
+        return {
+            relativePath: guard.relativePath,
+            state: inventory.state,
+            entriesDigest: inventory.entriesDigest,
+        };
+    });
+    return {
+        digest: `sha256:${hash.digest('hex')}`,
+        entries: nextEntries,
+        snapshot: buildSnapshot(entries),
+        rootState: directoryGuards[0].state,
+        directoryGuards,
+    };
+}
+function recordDirectoryGuard(guards, candidate) {
+    if (guards.has(candidate))
+        return true;
+    try {
+        guards.set(candidate, snapshotDirectoryInventory(candidate));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function snapshotDependencyPathGuard(candidate) {
+    try {
+        const stat = lstatSync(candidate, { bigint: true });
+        const type = stat.isDirectory()
+            ? 'directory'
+            : stat.isFile()
+                ? 'file'
+                : stat.isSymbolicLink()
+                    ? 'symlink'
+                    : 'other';
+        return {
+            type,
+            state: statState(stat),
+            ...(type === 'symlink' ? { symlinkTarget: readlinkSync(candidate) } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function recordDependencyPathGuard(guards, candidate) {
+    if (guards.has(candidate))
+        return guards.get(candidate) ?? null;
+    const result = snapshotDependencyPathGuard(candidate);
+    guards.set(candidate, result);
+    return result;
+}
+function findNearestPackageLock(packageRoot, pathGuards, limits) {
+    let cursor = packageRoot;
+    let ancestors = 0;
+    while (true) {
+        ancestors += 1;
+        if (ancestors > limits.resolutionAncestors) {
+            throw new Error(`Analyzer package-lock lookup exceeded ${limits.resolutionAncestors} ancestors: ${packageRoot}`);
+        }
+        const candidate = path.join(cursor, 'package-lock.json');
+        recordDependencyPathGuard(pathGuards, candidate);
+        // Preserve the link path so ReadableFileState guards both the link and its
+        // resolved target. Realpathing here would miss a later retarget while the
+        // old target remained unchanged.
+        try {
+            const link = lstatSync(candidate);
+            if (link.isFile())
+                return path.resolve(candidate);
+            if (link.isSymbolicLink()) {
+                try {
+                    const target = statSync(candidate);
+                    if (!target.isFile()) {
+                        throw new Error(`Analyzer package lock symbolic link does not resolve to a file: ${candidate}`);
+                    }
+                }
+                catch {
+                    throw new Error(`Analyzer package lock symbolic link does not resolve to a file: ${candidate}`);
+                }
+                return path.resolve(candidate);
+            }
+            throw new Error(`Analyzer package lock is not a regular file: ${candidate}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return null;
+        cursor = parent;
+    }
+}
+function runtimePackageLocator(packageRoot, runtimeRoot) {
+    if (runtimeRoot === packageRoot)
+        return 'root:.';
+    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 [
+        manifest.dependencies,
+        manifest.optionalDependencies,
+        manifest.peerDependencies,
+    ]) {
+        if (!section || typeof section !== 'object')
+            continue;
+        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) {
+    let cursor = fromRoot;
+    const segments = packageName.split('/');
+    let ancestors = 0;
+    while (true) {
+        ancestors += 1;
+        if (ancestors > limits.resolutionAncestors) {
+            throw new Error(`Analyzer dependency resolution exceeded ${limits.resolutionAncestors} ancestors: ${packageName}`);
+        }
+        const nodeModulesRoot = path.join(cursor, 'node_modules');
+        recordDependencyPathGuard(pathGuards, nodeModulesRoot);
+        let candidateParent = nodeModulesRoot;
+        for (const segment of segments) {
+            candidateParent = path.join(candidateParent, segment);
+            // Guard every lexical hop, not only the final manifest. Package
+            // managers commonly expose packages through symlinks; a retarget can
+            // otherwise preserve a hard-linked manifest's stat identity while
+            // changing the runtime payload tree selected by Node.
+            recordDependencyPathGuard(pathGuards, candidateParent);
+        }
+        const manifestPath = path.join(candidateParent, 'package.json');
+        recordDependencyPathGuard(pathGuards, manifestPath);
+        if (isFile(manifestPath))
+            return resolveExistingPath(path.dirname(manifestPath));
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return null;
+        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);
+    const rootRead = readManifest(rootManifestPath, options, budget, limits);
+    const rootPackage = {
+        root: packageRoot,
+        locator: runtimePackageLocator(packageRoot, packageRoot),
+        manifestPath: rootManifestPath,
+        manifestBytes: rootRead.bytes,
+        manifestState: rootRead.state,
+        manifest: rootRead.manifest,
+        label: manifestLabel(rootRead.manifest),
+    };
+    const queue = [rootPackage];
+    const packages = new Map([[packageRoot, rootPackage]]);
+    const edges = [];
+    budget.packages = 1;
+    for (let index = 0; index < queue.length; index += 1) {
+        const parent = queue[index];
+        // 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}`);
+            }
+            const childRoot = resolveDependencyPackageRoot(parent.root, dependencyName, pathGuards, limits);
+            if (!childRoot) {
+                edges.push({
+                    parentLocator: parent.locator,
+                    parentLabel: parent.label,
+                    dependencyName,
+                    childLocator: '<missing>',
+                    childLabel: '<missing>',
+                });
+                continue;
+            }
+            let child = packages.get(childRoot);
+            if (!child) {
+                budget.packages += 1;
+                if (budget.packages > limits.runtimePackages) {
+                    throw new Error(`Analyzer dependency graph exceeded ${limits.runtimePackages} packages: ${packageRoot}`);
+                }
+                const manifestPath = path.join(childRoot, 'package.json');
+                recordDirectoryGuard(directoryGuards, childRoot);
+                const read = readManifest(manifestPath, options, budget, limits);
+                child = {
+                    root: childRoot,
+                    locator: runtimePackageLocator(packageRoot, childRoot),
+                    manifestPath,
+                    manifestBytes: read.bytes,
+                    manifestState: read.state,
+                    manifest: read.manifest,
+                    label: manifestLabel(read.manifest),
+                };
+                packages.set(childRoot, child);
+                queue.push(child);
+            }
+            edges.push({
+                parentLocator: parent.locator,
+                parentLabel: parent.label,
+                dependencyName,
+                childLocator: child.locator,
+                childLabel: child.label,
+            });
+        }
+    }
+    return { packages: [...packages.values()], edges };
+}
+const PRUNED_RUNTIME_DIRECTORIES = new Set(['node_modules', '.git', '.hg', '.svn']);
+function shouldHashRuntimePayload(relativePath) {
+    const lower = relativePath.toLowerCase();
+    // Each package manifest is already hashed as a separately framed dependency
+    // input. Avoid counting/reading it twice while still hashing every other
+    // package payload: JavaScript modules, JSON data, native/Wasm binaries,
+    // extensionless exports, and files loaded explicitly through fs APIs. File
+    // and directory names are not authoritative platform-selection metadata:
+    // loaders may select or read a payload whose name mentions another target.
+    return lower !== 'package.json';
+}
+function collectArtifacts(root, canonicalPrefix, directoryGuards, options, budget, limits) {
+    const artifacts = [];
+    const pending = [{ absoluteDir: root, depth: 0 }];
+    while (pending.length > 0) {
+        const next = pending.pop();
+        if (!next)
+            break;
+        const { absoluteDir, depth } = next;
+        if (!recordDirectoryGuard(directoryGuards, absoluteDir)) {
+            throw new Error(`Analyzer runtime payload directory is unavailable: ${absoluteDir}`);
+        }
+        const entries = readDirectory(absoluteDir, options);
+        budget.entries += entries.length;
+        if (budget.entries > limits.runtimeEntries) {
+            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.
+            //
+            // 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;
+            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);
+                const payloadBytes = stateSize(readableState.target, absolutePath);
+                budget.artifacts += 1;
+                if (budget.artifacts > limits.runtimePayloads) {
+                    throw new Error(`Analyzer runtime payload scan exceeded ${limits.runtimePayloads} payloads: ${root}`);
+                }
+                if (budget.bytes + payloadBytes > limits.runtimeBytes) {
+                    throw new Error(`Analyzer runtime scan exceeded ${limits.runtimeBytes} bytes: ${absolutePath}`);
+                }
+                budget.bytes += payloadBytes;
+                artifacts.push({
+                    absolutePath,
+                    canonicalPath: `${canonicalPrefix}/${relativePath}`,
+                    kind: stat.isSymbolicLink() ? 'symlink' : 'file',
+                });
+            }
+            else if (!stat.isFile() && !stat.isSymbolicLink()) {
+                throw new Error(`Unsupported analyzer runtime payload entry: ${absolutePath}`);
+            }
+        }
+    }
+    return artifacts;
+}
+function collectVendoredGrammarInputs(packageRoot, directoryGuards, options, budget, limits) {
+    const vendorRoot = path.join(packageRoot, 'vendor');
+    if (!existsSync(vendorRoot) || !lstatSync(vendorRoot).isDirectory()) {
+        recordDirectoryGuard(directoryGuards, packageRoot);
+        return { manifests: [], artifacts: [] };
+    }
+    const manifests = [];
+    const artifacts = [];
+    if (!recordDirectoryGuard(directoryGuards, vendorRoot)) {
+        throw new Error(`Analyzer vendored runtime directory is unavailable: ${vendorRoot}`);
+    }
+    const vendorEntries = readDirectory(vendorRoot, options);
+    budget.entries += vendorEntries.length;
+    if (budget.entries > limits.runtimeEntries) {
+        throw new Error(`Analyzer runtime payload scan exceeded ${limits.runtimeEntries} entries: ${vendorRoot}`);
+    }
+    for (const entry of vendorEntries) {
+        if (!entry.isDirectory() || !entry.name.startsWith('tree-sitter-'))
+            continue;
+        const grammarRoot = path.join(vendorRoot, entry.name);
+        const manifestPath = path.join(grammarRoot, 'package.json');
+        if (isFile(manifestPath)) {
+            options.onCacheMissWork?.({ kind: 'manifest-read', path: manifestPath });
+            const read = readStableFileWithinBudget(manifestPath, budget, limits.runtimeBytes);
+            manifests.push({
+                canonicalPath: `vendor:${entry.name}/package.json`,
+                absolutePath: manifestPath,
+                bytes: read.bytes,
+                state: read.state,
+            });
+        }
+        artifacts.push(...collectArtifacts(grammarRoot, `vendor:${entry.name}`, directoryGuards, options, budget, limits));
+    }
+    return { manifests, artifacts };
+}
+function collectDependencyInputs(packageRoot, options, limits) {
+    const directoryGuards = new Map();
+    const pathGuards = new Map();
+    const artifactScanBudget = {
+        entries: 0,
+        artifacts: 0,
+        bytes: 0,
+        packages: 0,
+        edges: 0,
+    };
+    const manifestPath = resolveExistingPath(path.join(packageRoot, 'package.json'));
+    const lockfilePath = findNearestPackageLock(packageRoot, pathGuards, limits);
+    if (lockfilePath)
+        options.onCacheMissWork?.({ kind: 'manifest-read', path: lockfilePath });
+    const lockfile = lockfilePath
+        ? readStableFileWithinBudget(lockfilePath, artifactScanBudget, limits.runtimeBytes)
+        : null;
+    const { packages, edges } = collectRuntimePackages(packageRoot, directoryGuards, pathGuards, options, artifactScanBudget, limits);
+    const vendored = collectVendoredGrammarInputs(packageRoot, directoryGuards, options, artifactScanBudget, limits);
+    // The root build and vendored grammars are covered separately. Every
+    // resolved external runtime package is scanned, regardless of package name:
+    // native loaders are not constrained to a permanent allowlist (for example,
+    // Transformers resolves Sharp's @img platform packages).
+    const artifacts = packages
+        .slice(1)
+        .flatMap((runtimePackage) => collectArtifacts(runtimePackage.root, `package:${runtimePackage.locator}`, directoryGuards, options, artifactScanBudget, limits));
+    artifacts.push(...vendored.artifacts);
+    artifacts.sort((a, b) => compareBytes(`${a.canonicalPath}\u0000${a.absolutePath}`, `${b.canonicalPath}\u0000${b.absolutePath}`));
+    return {
+        manifestPath,
+        lockfilePath,
+        lockfileBytes: lockfile?.bytes ?? null,
+        lockfileState: lockfile?.state ?? null,
+        packages,
+        edges,
+        vendoredManifests: vendored.manifests,
+        artifacts,
+        directoryGuards,
+        pathGuards,
+    };
+}
+function dependencySnapshot(inputs) {
+    const edgeKey = (edge) => JSON.stringify([
+        edge.parentLocator,
+        edge.parentLabel,
+        edge.dependencyName,
+        edge.childLocator,
+        edge.childLabel,
+    ]);
+    return {
+        manifestPath: inputs.manifestPath,
+        lockfilePath: inputs.lockfilePath,
+        lockfileDigest: inputs.lockfileBytes ? sha256(inputs.lockfileBytes) : null,
+        lockfileState: inputs.lockfileState,
+        packages: inputs.packages
+            .map((runtimePackage) => ({
+            root: runtimePackage.root,
+            locator: runtimePackage.locator,
+            manifestPath: runtimePackage.manifestPath,
+            manifestDigest: sha256(runtimePackage.manifestBytes),
+            manifestState: runtimePackage.manifestState,
+            label: runtimePackage.label,
+        }))
+            .sort((a, b) => compareBytes(a.locator, b.locator)),
+        edges: inputs.edges.map(edgeKey).sort(compareBytes),
+        vendoredManifests: inputs.vendoredManifests
+            .map((entry) => ({
+            canonicalPath: entry.canonicalPath,
+            absolutePath: entry.absolutePath,
+            digest: sha256(entry.bytes),
+            state: entry.state,
+        }))
+            .sort((a, b) => compareBytes(a.canonicalPath, b.canonicalPath)),
+        artifacts: inputs.artifacts.map((artifact) => ({
+            absolutePath: artifact.absolutePath,
+            canonicalPath: artifact.canonicalPath,
+            kind: artifact.kind,
+            state: snapshotRuntimeArtifact(artifact),
+        })),
+        directories: [...inputs.directoryGuards.entries()]
+            .map(([absolutePath, guard]) => ({ absolutePath, ...guard }))
+            .sort((a, b) => compareBytes(a.absolutePath, b.absolutePath)),
+        paths: [...inputs.pathGuards.entries()]
+            .map(([absolutePath, result]) => ({ absolutePath, result }))
+            .sort((a, b) => compareBytes(a.absolutePath, b.absolutePath)),
+    };
+}
+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 &&
+        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([
+        [
+            'runtime-payload-content-v1',
+            artifact.kind,
+            stable.state.symlinkTarget ?? '',
+            digestBytes(stable.digest),
+        ],
+    ]);
+    options.onHashedInput?.({
+        kind: 'runtime-artifact',
+        path: artifact.absolutePath,
+        bytes: stable.bytes,
+    });
+    return { ...artifact, state: stable.state, digest };
+}
+function compareEdges(a, b) {
+    return compareBytes(JSON.stringify([
+        a.parentLocator,
+        a.parentLabel,
+        a.dependencyName,
+        a.childLocator,
+        a.childLabel,
+    ]), JSON.stringify([
+        b.parentLocator,
+        b.parentLabel,
+        b.dependencyName,
+        b.childLocator,
+        b.childLabel,
+    ]));
+}
+function hashDependencyRuntime(inputs, cache, options, runtimeVariant) {
+    const cachedArtifacts = new Map((cache?.artifactEntries ?? []).map((entry) => [artifactCacheKey(entry), entry]));
+    const nextArtifacts = [];
+    const hash = createHash('sha256');
+    updateCanonicalFrame(hash, ['domain', DEPENDENCY_RUNTIME_CANONICALIZATION]);
+    updateCanonicalFrame(hash, [
+        'runtime-variant',
+        runtimeVariant.nodeVersion,
+        runtimeVariant.platform,
+        runtimeVariant.architecture,
+        runtimeVariant.endianness,
+        runtimeVariant.modulesAbi,
+        runtimeVariant.napiAbi,
+        runtimeVariant.libc,
+    ]);
+    updateCanonicalFrame(hash, [
+        'lockfile',
+        inputs.lockfilePath ? 'present' : 'absent',
+        inputs.lockfileBytes ?? Buffer.alloc(0),
+    ]);
+    const packageEntries = inputs.packages
+        .map((runtimePackage) => ({
+        canonicalPath: `package:${runtimePackage.locator}/package.json`,
+        bytes: runtimePackage.manifestBytes,
+    }))
+        .concat(inputs.vendoredManifests.map(({ canonicalPath, bytes }) => ({ canonicalPath, bytes })))
+        .sort((a, b) => compareBytes(a.canonicalPath, b.canonicalPath));
+    for (const entry of packageEntries) {
+        updateCanonicalFrame(hash, ['package-manifest', entry.canonicalPath, entry.bytes]);
+    }
+    for (const edge of [...inputs.edges].sort(compareEdges)) {
+        updateCanonicalFrame(hash, [
+            'dependency-edge',
+            edge.parentLocator,
+            edge.parentLabel,
+            edge.dependencyName,
+            edge.childLocator,
+            edge.childLabel,
+        ]);
+    }
+    for (const artifact of inputs.artifacts) {
+        const hashed = hashRuntimeArtifact(artifact, cachedArtifacts.get(artifactCacheKey(artifact)), options);
+        updateCanonicalFrame(hash, [
+            'runtime-artifact',
+            artifact.canonicalPath,
+            artifact.kind,
+            digestBytes(hashed.digest),
+        ]);
+        nextArtifacts.push(hashed);
+    }
+    return {
+        identity: {
+            manifestPath: inputs.manifestPath,
+            lockfilePath: inputs.lockfilePath,
+            canonicalization: DEPENDENCY_RUNTIME_CANONICALIZATION,
+            packageCount: inputs.packages.length,
+            artifactCount: inputs.artifacts.length,
+            digest: `sha256:${hash.digest('hex')}`,
+        },
+        entries: nextArtifacts,
+    };
+}
+function isStatState(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return ['dev', 'ino', 'mode', 'nlink', 'size', 'mtimeNs', 'ctimeNs'].every((key) => typeof record[key] === 'string');
+}
+function isReadableFileState(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return (isStatState(record.link) &&
+        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;
+    if (typeof value !== 'object')
+        return false;
+    const record = value;
+    return (['directory', 'file', 'symlink', 'other'].includes(String(record.type)) &&
+        isStatState(record.state) &&
+        (record.type === 'symlink'
+            ? typeof record.symlinkTarget === 'string'
+            : record.symlinkTarget === undefined));
+}
+function isRuntimeVariant(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return [
+        'executablePath',
+        'nodeVersion',
+        'platform',
+        'architecture',
+        'endianness',
+        'modulesAbi',
+        'napiAbi',
+        'libc',
+    ].every((key) => typeof record[key] === 'string' && record[key].length > 0);
+}
+function isTraversalLimits(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return Object.keys(DEFAULT_TRAVERSAL_LIMITS).every((key) => Number.isSafeInteger(record[key]) &&
+        Number(record[key]) >= 1 &&
+        Number(record[key]) <= DEFAULT_TRAVERSAL_LIMITS[key]);
+}
+function isDependencyRuntimeIdentity(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const dependency = value;
+    return (typeof dependency.manifestPath === 'string' &&
+        dependency.manifestPath.length > 0 &&
+        (dependency.lockfilePath === null ||
+            (typeof dependency.lockfilePath === 'string' && dependency.lockfilePath.length > 0)) &&
+        dependency.canonicalization === DEPENDENCY_RUNTIME_CANONICALIZATION &&
+        Number.isSafeInteger(dependency.packageCount) &&
+        Number(dependency.packageCount) >= 1 &&
+        Number.isSafeInteger(dependency.artifactCount) &&
+        Number(dependency.artifactCount) >= 0 &&
+        typeof dependency.digest === 'string' &&
+        SHA256_PATTERN.test(dependency.digest));
+}
+function isSafeBuildRelativePath(value) {
+    if (typeof value !== 'string' || value.length === 0 || path.posix.isAbsolute(value)) {
+        return false;
+    }
+    const normalized = path.posix.normalize(value);
+    return normalized === value && normalized !== '..' && !normalized.startsWith('../');
+}
+function isSafeBuildDirectoryGuardPath(value) {
+    return value === '' || isSafeBuildRelativePath(value);
+}
+function isIdentityCachePayload(value, packageRoot, buildRoot, runtimeVariant, traversalLimits) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    if (record.schemaVersion !== IDENTITY_CACHE_SCHEMA_VERSION ||
+        record.packageRoot !== packageRoot ||
+        record.buildRoot !== buildRoot ||
+        typeof record.packageVersion !== 'string' ||
+        record.packageVersion.length === 0 ||
+        (record.buildKind !== 'source' && record.buildKind !== 'distribution') ||
+        record.buildCanonicalization !== BUILD_CANONICALIZATION ||
+        record.dependencyCanonicalization !== DEPENDENCY_RUNTIME_CANONICALIZATION ||
+        !isTraversalLimits(record.traversalLimits) ||
+        !isDeepStrictEqual(record.traversalLimits, traversalLimits) ||
+        !isRuntimeVariant(record.runtimeVariant) ||
+        !isDeepStrictEqual(record.runtimeVariant, runtimeVariant) ||
+        !isStatState(record.buildRootState) ||
+        typeof record.buildDigest !== 'string' ||
+        !SHA256_PATTERN.test(record.buildDigest) ||
+        !isDependencyRuntimeIdentity(record.dependencyIdentity) ||
+        !Array.isArray(record.buildEntries) ||
+        !Array.isArray(record.buildDirectoryGuards) ||
+        !Array.isArray(record.dependencyFileGuards) ||
+        !Array.isArray(record.dependencyDirectoryGuards) ||
+        !Array.isArray(record.dependencyPathGuards) ||
+        !Array.isArray(record.artifactEntries) ||
+        record.buildEntries.length > MAX_CACHE_ENTRIES ||
+        record.buildDirectoryGuards.length > MAX_CACHE_ENTRIES ||
+        record.dependencyFileGuards.length > MAX_CACHE_ENTRIES ||
+        record.dependencyDirectoryGuards.length > MAX_CACHE_ENTRIES ||
+        record.dependencyPathGuards.length > MAX_CACHE_ENTRIES ||
+        record.artifactEntries.length > MAX_CACHE_ENTRIES) {
+        return false;
+    }
+    const buildEntriesValid = record.buildEntries.every((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return false;
+        const item = entry;
+        return (isSafeBuildRelativePath(item.relativePath) &&
+            ['directory', 'file'].includes(String(item.kind)) &&
+            isStatState(item.state) &&
+            (item.kind === 'directory'
+                ? item.digest === undefined
+                : typeof item.digest === 'string' && SHA256_PATTERN.test(item.digest)));
+    });
+    const buildDirectoryGuardsValid = record.buildDirectoryGuards.every((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return false;
+        const item = entry;
+        return (isSafeBuildDirectoryGuardPath(item.relativePath) &&
+            isStatState(item.state) &&
+            typeof item.entriesDigest === 'string' &&
+            SHA256_PATTERN.test(item.entriesDigest));
+    });
+    const dependencyFileGuardsValid = record.dependencyFileGuards.every((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return false;
+        const item = entry;
+        return (typeof item.absolutePath === 'string' &&
+            path.isAbsolute(item.absolutePath) &&
+            isReadableFileState(item.state));
+    });
+    const dependencyDirectoryGuardsValid = record.dependencyDirectoryGuards.every((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return false;
+        const item = entry;
+        return (typeof item.absolutePath === 'string' &&
+            path.isAbsolute(item.absolutePath) &&
+            isStatState(item.state) &&
+            typeof item.entriesDigest === 'string' &&
+            SHA256_PATTERN.test(item.entriesDigest));
+    });
+    const dependencyPathGuardsValid = record.dependencyPathGuards.every((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return false;
+        const item = entry;
+        return (typeof item.absolutePath === 'string' &&
+            path.isAbsolute(item.absolutePath) &&
+            isDependencyPathGuardResult(item.result));
+    });
+    const artifactEntriesValid = record.artifactEntries.every((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return false;
+        const item = entry;
+        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 &&
+        entry.relativePath === '');
+    return (buildEntriesValid &&
+        buildDirectoryGuardsValid &&
+        hasBuildRootGuard &&
+        dependencyFileGuardsValid &&
+        dependencyDirectoryGuardsValid &&
+        dependencyPathGuardsValid &&
+        artifactEntriesValid);
+}
+function currentUid() {
+    return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+function isOwnedPrivateDirectory(candidate) {
+    try {
+        const stat = lstatSync(candidate);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return false;
+        const uid = currentUid();
+        return uid !== null && stat.uid === uid && (stat.mode & 0o077) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function isSafeTemporaryParent(candidate) {
+    try {
+        const stat = lstatSync(candidate);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return false;
+        if (currentUid() === null)
+            return false;
+        // A shared temp root is safe only with the sticky bit: another UID then
+        // cannot replace the private child after our atomic mkdir + owner check.
+        const writableByOthers = (stat.mode & 0o022) !== 0;
+        return !writableByOthers || (stat.mode & 0o1000) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+function ensurePrivateChild(parent, childName) {
+    let resolvedParent;
+    try {
+        resolvedParent = realpathSync.native(parent);
+    }
+    catch {
+        return null;
+    }
+    if (!isSafeTemporaryParent(resolvedParent))
+        return null;
+    const candidate = path.join(resolvedParent, childName);
+    try {
+        // Non-recursive mkdir is intentional: it cannot follow an attacker-made
+        // intermediate symlink. EEXIST is accepted only after the ownership/mode
+        // validation below.
+        mkdirSync(candidate, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            return null;
+    }
+    return isOwnedPrivateDirectory(candidate) ? candidate : null;
+}
+function defaultCacheDirectory() {
+    // On platforms without POSIX ownership APIs we cannot prove that a default
+    // cache file is private to this process's user. Persistence is therefore
+    // disabled unless the operator supplied an explicit trusted override.
+    const uid = currentUid();
+    if (uid === null)
+        return null;
+    // XDG_RUNTIME_DIR is already per-user and normally 0700. Use it only when
+    // that contract is true; a spoofed/insecure value falls back to the sticky
+    // OS temp root rather than becoming a cache-poisoning surface.
+    const runtimeDir = process.env.XDG_RUNTIME_DIR;
+    if (runtimeDir) {
+        try {
+            const resolvedRuntime = realpathSync.native(runtimeDir);
+            if (isOwnedPrivateDirectory(resolvedRuntime)) {
+                const runtimeCache = ensurePrivateChild(resolvedRuntime, 'gitnexus-analyzer-identity');
+                if (runtimeCache)
+                    return runtimeCache;
+            }
+        }
+        catch {
+            /* fall through to the OS temp directory */
+        }
+    }
+    let tempRoot;
+    try {
+        tempRoot = realpathSync.native(os.tmpdir());
+    }
+    catch {
+        return null;
+    }
+    return ensurePrivateChild(tempRoot, `gitnexus-analyzer-identity-${uid}`);
+}
+const TRUSTED_CACHE_DIRECTORY_ENV = 'GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR';
+function pathsEqual(left, right) {
+    return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+function trustedEnvironmentCacheDirectory() {
+    const configured = process.env[TRUSTED_CACHE_DIRECTORY_ENV];
+    if (configured === undefined)
+        return null;
+    if (configured.length === 0 || configured.includes('\0') || !path.isAbsolute(configured)) {
+        throw new Error(`${TRUSTED_CACHE_DIRECTORY_ENV} must name an absolute protected directory`);
+    }
+    const normalized = path.normalize(configured);
+    let resolved;
+    try {
+        const link = lstatSync(normalized);
+        if (!link.isDirectory() || link.isSymbolicLink()) {
+            throw new Error('not a real directory');
+        }
+        resolved = realpathSync.native(normalized);
+    }
+    catch {
+        throw new Error(`${TRUSTED_CACHE_DIRECTORY_ENV} must name a pre-existing protected non-symlink directory`);
+    }
+    // Reject junctions/symlinked ancestors as well as a symlink final component.
+    // The environment variable is an explicit trust assertion, but its spelling
+    // must still bind exactly to the directory the cache will use.
+    if (!pathsEqual(path.resolve(normalized), resolved)) {
+        throw new Error(`${TRUSTED_CACHE_DIRECTORY_ENV} must not traverse symbolic links or junctions`);
+    }
+    return resolved;
+}
+function cacheDirectory(options, packageRoot, buildRoot) {
+    // An explicit location is a trusted operator/test override and therefore
+    // remains authoritative, including when the secure default is unavailable.
+    if (options.cacheDirectory) {
+        const explicit = path.resolve(options.cacheDirectory);
+        try {
+            // Create it before any build/dependency directory guards are captured.
+            // A cache nested immediately under a package root then changes that
+            // parent's directory state once, not after we persist the first entry.
+            mkdirSync(explicit, { recursive: true, mode: 0o700 });
+        }
+        catch {
+            /* persistence remains optional and will fail closed */
+        }
+        return explicit;
+    }
+    const configured = trustedEnvironmentCacheDirectory();
+    if (configured) {
+        if (isInside(packageRoot, configured) || isInside(buildRoot, configured)) {
+            throw new Error(`${TRUSTED_CACHE_DIRECTORY_ENV} must be outside the analyzer package and build roots`);
+        }
+        return configured;
+    }
+    return defaultCacheDirectory();
+}
+function hasTrustedCacheOverride(options) {
+    return (options.cacheDirectory !== undefined || process.env[TRUSTED_CACHE_DIRECTORY_ENV] !== undefined);
+}
+function identityCacheKey(packageRoot, buildRoot, runtimeVariant, traversalLimits) {
+    return hashCanonicalFrames([
+        [
+            'analyzer-identity-cache-key-v3',
+            String(IDENTITY_CACHE_SCHEMA_VERSION),
+            packageRoot,
+            buildRoot,
+            runtimeVariant.executablePath,
+            runtimeVariant.nodeVersion,
+            runtimeVariant.platform,
+            runtimeVariant.architecture,
+            runtimeVariant.endianness,
+            runtimeVariant.modulesAbi,
+            runtimeVariant.napiAbi,
+            runtimeVariant.libc,
+            JSON.stringify(traversalLimits),
+        ],
+    ]).slice('sha256:'.length);
+}
+const MAX_PROCESS_CACHE_ENTRIES = 12;
+const processIdentityCache = new Map();
+/** @internal Clear process-local reuse between simulated-process unit tests. */
+export function _clearAnalyzerIdentityProcessCacheForTests() {
+    processIdentityCache.clear();
+}
+function cachePathFor(packageRoot, buildRoot, runtimeVariant, traversalLimits, options) {
+    const directory = cacheDirectory(options, packageRoot, buildRoot);
+    if (!directory)
+        return null;
+    const key = identityCacheKey(packageRoot, buildRoot, runtimeVariant, traversalLimits);
+    return path.join(directory, `${key}.json`);
+}
+function readCacheFile(target) {
+    let descriptor = null;
+    try {
+        const noFollow = 'O_NOFOLLOW' in fsConstants ? fsConstants.O_NOFOLLOW : 0;
+        descriptor = openSync(target, fsConstants.O_RDONLY | noFollow);
+        const stat = fstatSync(descriptor);
+        const uid = currentUid();
+        if (!stat.isFile() ||
+            stat.isSymbolicLink() ||
+            stat.size > MAX_CACHE_FILE_BYTES ||
+            (uid !== null && (stat.uid !== uid || (stat.mode & 0o077) !== 0))) {
+            return null;
+        }
+        return readFileSync(descriptor, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (descriptor !== null)
+            closeSync(descriptor);
+    }
+}
+function loadIdentityCache(packageRoot, buildRoot, runtimeVariant, traversalLimits, options) {
+    // Invalid explicit cache configuration is an operator error, not an optional
+    // cache miss. Resolve it outside the best-effort envelope read below.
+    const target = cachePathFor(packageRoot, buildRoot, runtimeVariant, traversalLimits, options);
+    try {
+        // Validate any operator-selected persistence location on every call, even
+        // when the payload itself is reusable from this process's guarded LRU.
+        const key = identityCacheKey(packageRoot, buildRoot, runtimeVariant, traversalLimits);
+        const local = processIdentityCache.get(key);
+        if (local)
+            return local;
+        if (!target)
+            return null;
+        const raw = readCacheFile(target);
+        if (raw === null)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            typeof parsed.checksum !== 'string' ||
+            !isIdentityCachePayload(parsed.payload, packageRoot, buildRoot, runtimeVariant, traversalLimits) ||
+            parsed.checksum !== sha256(JSON.stringify(parsed.payload))) {
+            return null;
+        }
+        return parsed.payload;
+    }
+    catch {
+        return null;
+    }
+}
+const CACHE_GUARD_PROBE_SCRIPT = String.raw `
+const fs = require('node:fs/promises');
+const crypto = require('node:crypto');
+const state = (value) => ({
+  dev: String(value.dev), ino: String(value.ino), mode: String(value.mode),
+  nlink: String(value.nlink), size: String(value.size),
+  mtimeNs: String(value.mtimeNs), ctimeNs: String(value.ctimeNs),
+});
+const frame = (hash, fields) => {
+  const fieldCount = Buffer.allocUnsafe(4);
+  fieldCount.writeUInt32BE(fields.length);
+  hash.update(fieldCount);
+  for (const field of fields) {
+    const bytes = Buffer.from(field);
+    const length = Buffer.allocUnsafe(8);
+    length.writeBigUInt64BE(BigInt(bytes.length));
+    hash.update(length);
+    hash.update(bytes);
+  }
+};
+const inventoryDigest = (entries) => {
+  const normalized = entries.map((entry) => ({
+    name: entry.name,
+    kind: entry.isDirectory() ? 'directory'
+      : entry.isFile() ? 'file'
+      : entry.isSymbolicLink() ? 'symlink' : 'other',
+  })).sort((a, b) => Buffer.compare(Buffer.from(a.name), Buffer.from(b.name)));
+  const hash = crypto.createHash('sha256');
+  frame(hash, ['directory-entries-v1']);
+  for (const entry of normalized) frame(hash, [entry.name, entry.kind]);
+  return 'sha256:' + hash.digest('hex');
+};
+const probe = async (request) => {
+  try {
+    const link = await fs.lstat(request.absolutePath, { bigint: true });
+    const type = link.isDirectory() ? 'directory'
+      : link.isFile() ? 'file'
+      : link.isSymbolicLink() ? 'symlink' : 'other';
+    if (request.mode === 'link') return {
+      type,
+      state: state(link),
+      ...(type === 'symlink' ? { symlinkTarget: await fs.readlink(request.absolutePath) } : {}),
+    };
+    if (request.mode === 'directory-inventory') {
+      if (!link.isDirectory() || link.isSymbolicLink()) return null;
+      const entriesDigest = inventoryDigest(
+        await fs.readdir(request.absolutePath, { withFileTypes: true }),
+      );
+      const after = await fs.lstat(request.absolutePath, { bigint: true });
+      if (JSON.stringify(state(link)) !== JSON.stringify(state(after))) return null;
+      return { type: 'directory-inventory', state: state(after), entriesDigest };
+    }
+    const target = await fs.stat(request.absolutePath, { bigint: true });
+    if (!target.isFile()) return null;
+    const result = { type: 'readable-file', state: { link: state(link), target: state(target) } };
+    if (link.isSymbolicLink()) result.state.symlinkTarget = await fs.readlink(request.absolutePath);
+    return result;
+  } catch { return null; }
+};
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', async () => {
+  try {
+    const requests = JSON.parse(input);
+    const results = [];
+    for (let offset = 0; offset < requests.length; offset += 512) {
+      results.push(...await Promise.all(requests.slice(offset, offset + 512).map(probe)));
+    }
+    process.stdout.write(JSON.stringify(results));
+  } catch { process.exitCode = 1; }
+});
+`;
+function snapshotCacheGuardDirect(request) {
+    try {
+        if (request.mode === 'readable-file') {
+            return { type: 'readable-file', state: snapshotReadableFile(request.absolutePath) };
+        }
+        if (request.mode === 'directory-inventory') {
+            const inventory = snapshotDirectoryInventory(request.absolutePath);
+            return { type: 'directory-inventory', ...inventory };
+        }
+        const stat = lstatSync(request.absolutePath, { bigint: true });
+        const type = stat.isDirectory()
+            ? 'directory'
+            : stat.isFile()
+                ? 'file'
+                : stat.isSymbolicLink()
+                    ? 'symlink'
+                    : 'other';
+        return {
+            type,
+            state: statState(stat),
+            ...(type === 'symlink' ? { symlinkTarget: readlinkSync(request.absolutePath) } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function snapshotCacheGuards(requests) {
+    if (requests.length < 128)
+        return requests.map(snapshotCacheGuardDirect);
+    try {
+        const probe = spawnSync(process.execPath, ['--input-type=commonjs', '-e', CACHE_GUARD_PROBE_SCRIPT], {
+            input: JSON.stringify(requests),
+            encoding: 'utf8',
+            maxBuffer: MAX_CACHE_FILE_BYTES,
+            timeout: 30_000,
+            windowsHide: true,
+        });
+        if (probe.status === 0 && !probe.error) {
+            const parsed = JSON.parse(probe.stdout);
+            if (Array.isArray(parsed) && parsed.length === requests.length) {
+                return parsed;
+            }
+        }
+    }
+    catch {
+        /* fall through to the slower in-process validator */
+    }
+    return requests.map(snapshotCacheGuardDirect);
+}
+function validateIdentityCache(cache, options) {
+    const expected = new Map();
+    const add = (request, result) => {
+        const key = JSON.stringify([request.mode, request.absolutePath]);
+        const prior = expected.get(key);
+        if (expected.has(key) && !isDeepStrictEqual(prior, result)) {
+            options.onCacheValidationFailure?.({ mode: request.mode, path: request.absolutePath });
+            return false;
+        }
+        expected.set(key, result);
+        return true;
+    };
+    if (!add({ absolutePath: cache.buildRoot, mode: 'link' }, { type: 'directory', state: cache.buildRootState })) {
+        return false;
+    }
+    for (const entry of cache.buildEntries) {
+        const absolutePath = path.join(cache.buildRoot, ...entry.relativePath.split('/'));
+        if (!isInside(cache.buildRoot, absolutePath) ||
+            !add({ absolutePath, mode: 'link' }, { type: entry.kind, state: entry.state })) {
+            return false;
+        }
+    }
+    for (const guard of cache.buildDirectoryGuards) {
+        const absolutePath = guard.relativePath
+            ? path.join(cache.buildRoot, ...guard.relativePath.split('/'))
+            : cache.buildRoot;
+        if (!isInside(cache.buildRoot, absolutePath) ||
+            !add({ absolutePath, mode: 'directory-inventory' }, {
+                type: 'directory-inventory',
+                state: guard.state,
+                entriesDigest: guard.entriesDigest,
+            })) {
+            return false;
+        }
+    }
+    for (const guard of cache.dependencyDirectoryGuards) {
+        if (!add({ absolutePath: guard.absolutePath, mode: 'directory-inventory' }, {
+            type: 'directory-inventory',
+            state: guard.state,
+            entriesDigest: guard.entriesDigest,
+        })) {
+            return false;
+        }
+    }
+    for (const guard of cache.dependencyPathGuards) {
+        if (!add({ absolutePath: guard.absolutePath, mode: 'link' }, guard.result)) {
+            return false;
+        }
+    }
+    for (const guard of cache.dependencyFileGuards) {
+        if (!add({ absolutePath: guard.absolutePath, mode: 'readable-file' }, { type: 'readable-file', state: guard.state })) {
+            return false;
+        }
+    }
+    for (const artifact of cache.artifactEntries) {
+        // 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]) => {
+        const [mode, absolutePath] = JSON.parse(key);
+        return { mode, absolutePath };
+    });
+    options.onCacheValidationPass?.({ guardCount: requests.length });
+    const actual = snapshotCacheGuards(requests);
+    const mismatch = actual.findIndex((result, index) => !isDeepStrictEqual(result, entries[index][1]));
+    if (mismatch !== -1) {
+        const [mode, absolutePath] = JSON.parse(entries[mismatch][0]);
+        options.onCacheValidationFailure?.({ mode, path: absolutePath });
+        return false;
+    }
+    return true;
+}
+function cachedBuildDigestForPath(cache, absolutePath) {
+    if (!isInside(cache.buildRoot, absolutePath))
+        return null;
+    const relativePath = path.relative(cache.buildRoot, absolutePath).split(path.sep).join('/');
+    const entry = cache.buildEntries.find((candidate) => candidate.kind === 'file' && candidate.relativePath === relativePath);
+    return entry?.digest ?? null;
+}
+function dependencyFileGuards(inputs) {
+    const guards = new Map();
+    if (inputs.lockfilePath && inputs.lockfileState) {
+        guards.set(inputs.lockfilePath, inputs.lockfileState);
+    }
+    for (const runtimePackage of inputs.packages) {
+        guards.set(runtimePackage.manifestPath, runtimePackage.manifestState);
+    }
+    for (const manifest of inputs.vendoredManifests) {
+        guards.set(manifest.absolutePath, manifest.state);
+    }
+    return [...guards.entries()]
+        .map(([absolutePath, state]) => ({ absolutePath, state }))
+        .sort((a, b) => compareBytes(a.absolutePath, b.absolutePath));
+}
+function dependencyDirectoryGuards(inputs) {
+    return [...inputs.directoryGuards.entries()]
+        .map(([absolutePath, guard]) => ({ absolutePath, ...guard }))
+        .sort((a, b) => compareBytes(a.absolutePath, b.absolutePath));
+}
+function dependencyPathGuards(inputs) {
+    return [...inputs.pathGuards.entries()]
+        .map(([absolutePath, result]) => ({ absolutePath, result }))
+        .sort((a, b) => compareBytes(a.absolutePath, b.absolutePath));
+}
+function persistIdentityCache(packageRoot, buildRoot, payload, previous, options) {
+    if (previous && isDeepStrictEqual(previous, payload))
+        return;
+    const target = cachePathFor(packageRoot, buildRoot, payload.runtimeVariant, payload.traversalLimits, options);
+    if (!target)
+        return;
+    const temporary = `${target}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        if (options.cacheDirectory) {
+            mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+        }
+        else if (!hasTrustedCacheOverride(options) &&
+            !isOwnedPrivateDirectory(path.dirname(target))) {
+            return;
+        }
+        const envelope = {
+            payload,
+            checksum: sha256(JSON.stringify(payload)),
+        };
+        writeFileSync(temporary, `${JSON.stringify(envelope)}\n`, {
+            encoding: 'utf8',
+            flag: 'wx',
+            mode: 0o600,
+        });
+        renameSync(temporary, target);
+    }
+    catch {
+        // The cache is optional (notably for read-only package/container setups).
+        // A failed write only loses the optimization; identity remains fail-closed.
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* already renamed or never created */
+        }
+    }
+}
+function rememberIdentityCache(payload) {
+    const key = identityCacheKey(payload.packageRoot, payload.buildRoot, payload.runtimeVariant, payload.traversalLimits);
+    processIdentityCache.delete(key);
+    processIdentityCache.set(key, payload);
+    while (processIdentityCache.size > MAX_PROCESS_CACHE_ENTRIES) {
+        const oldest = processIdentityCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        processIdentityCache.delete(oldest);
+    }
+}
+function resolveInvokedArtifact(buildRoot, analyzerModulePath) {
+    const argvEntry = process.argv[1];
+    if (!argvEntry)
+        return analyzerModulePath;
+    try {
+        const resolved = resolveExistingPath(argvEntry);
+        return isInside(buildRoot, resolved) && lstatSync(resolved).isFile()
+            ? resolved
+            : analyzerModulePath;
+    }
+    catch {
+        return analyzerModulePath;
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function runnerRuntimeIdentity(runtimeVariant) {
+    return {
+        executablePath: runtimeVariant.executablePath,
+        version: runtimeVariant.nodeVersion,
+        platform: runtimeVariant.platform,
+        architecture: runtimeVariant.architecture,
+        modulesAbi: runtimeVariant.modulesAbi,
+        libc: runtimeVariant.libc,
+    };
+}
+function isAnalyzerRunnerIdentity(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const identity = value;
+    const runtime = identity.runtime;
+    const invoked = identity.invokedArtifact;
+    const build = identity.build;
+    const dependency = identity.dependencyRuntime;
+    return (identity.schemaVersion === ANALYZER_RUNNER_IDENTITY_SCHEMA_VERSION &&
+        !!runtime &&
+        isNonEmptyString(runtime.executablePath) &&
+        isNonEmptyString(runtime.version) &&
+        isNonEmptyString(runtime.platform) &&
+        isNonEmptyString(runtime.architecture) &&
+        isNonEmptyString(runtime.modulesAbi) &&
+        isNonEmptyString(runtime.libc) &&
+        isNonEmptyString(identity.cliVersion) &&
+        !!invoked &&
+        isNonEmptyString(invoked.path) &&
+        typeof invoked.digest === 'string' &&
+        SHA256_PATTERN.test(invoked.digest) &&
+        !!build &&
+        (build.kind === 'source' || build.kind === 'distribution') &&
+        isNonEmptyString(build.rootPath) &&
+        build.canonicalization === BUILD_CANONICALIZATION &&
+        typeof build.digest === 'string' &&
+        SHA256_PATTERN.test(build.digest) &&
+        !!dependency &&
+        isNonEmptyString(dependency.manifestPath) &&
+        (dependency.lockfilePath === null || isNonEmptyString(dependency.lockfilePath)) &&
+        dependency.canonicalization === DEPENDENCY_RUNTIME_CANONICALIZATION &&
+        Number.isSafeInteger(dependency.packageCount) &&
+        Number(dependency.packageCount) >= 1 &&
+        Number.isSafeInteger(dependency.artifactCount) &&
+        Number(dependency.artifactCount) >= 0 &&
+        typeof dependency.digest === 'string' &&
+        SHA256_PATTERN.test(dependency.digest));
+}
+/**
+ * Normalize a raw diagnostic receipt for freshness comparison. The entrypoint
+ * is the only excluded field; malformed/legacy receipts never compare equal.
+ */
+export function normalizeAnalyzerRunnerIdentityForComparison(identity) {
+    if (!isAnalyzerRunnerIdentity(identity))
+        return null;
+    const { invokedArtifact: _diagnosticEntrypoint, ...semantic } = identity;
+    return semantic;
+}
+/** Resolve the identity of the analyzer build and runtime executing now. */
+export function resolveAnalyzerRunnerIdentity(analyzerModuleUrl, options = {}) {
+    const analyzerModulePath = resolveExistingPath(fileURLToPath(analyzerModuleUrl));
+    const { packageRoot, buildRoot, kind } = resolveBuildRoot(analyzerModulePath);
+    const runtimeVariant = resolveRuntimeVariant();
+    const traversalLimits = resolveTraversalLimits(options);
+    const previousCache = loadIdentityCache(packageRoot, buildRoot, runtimeVariant, traversalLimits, options);
+    const invokedArtifactPath = resolveInvokedArtifact(buildRoot, analyzerModulePath);
+    if (previousCache?.buildKind === kind) {
+        const invokedDigest = cachedBuildDigestForPath(previousCache, invokedArtifactPath);
+        if (invokedDigest) {
+            const cachedIdentity = {
+                schemaVersion: ANALYZER_RUNNER_IDENTITY_SCHEMA_VERSION,
+                runtime: runnerRuntimeIdentity(runtimeVariant),
+                cliVersion: previousCache.packageVersion,
+                invokedArtifact: { path: invokedArtifactPath, digest: invokedDigest },
+                build: {
+                    kind,
+                    rootPath: buildRoot,
+                    canonicalization: BUILD_CANONICALIZATION,
+                    digest: previousCache.buildDigest,
+                },
+                dependencyRuntime: previousCache.dependencyIdentity,
+            };
+            // One batched pass is deliberately the last filesystem observation on
+            // a warm hit. Repeating the complete inventory both doubles status
+            // latency and still cannot close the post-check scheduling window.
+            if (validateIdentityCache(previousCache, options)) {
+                rememberIdentityCache(previousCache);
+                return cachedIdentity;
+            }
+        }
+    }
+    const build = hashBuildTree(buildRoot, previousCache, options, traversalLimits);
+    const dependencyInputs = collectDependencyInputs(packageRoot, options, traversalLimits);
+    const dependencySnapshotBefore = dependencySnapshot(dependencyInputs);
+    const dependency = hashDependencyRuntime(dependencyInputs, previousCache, options, runtimeVariant);
+    const packageVersion = dependencyInputs.packages[0]?.manifest.version;
+    if (typeof packageVersion !== 'string' || packageVersion.trim() === '') {
+        throw new Error(`GitNexus package version is unavailable in ${packageRoot}`);
+    }
+    const buildSnapshotAfter = buildSnapshot(collectBuildEntries(buildRoot, options, traversalLimits));
+    if (!isDeepStrictEqual(build.snapshot, buildSnapshotAfter)) {
+        throw new Error(`Analyzer build changed while its identity was being computed: ${buildRoot}`);
+    }
+    const dependencySnapshotAfter = dependencySnapshot(collectDependencyInputs(packageRoot, options, traversalLimits));
+    if (!isDeepStrictEqual(dependencySnapshotBefore, dependencySnapshotAfter)) {
+        throw new Error(`Analyzer dependency runtime changed while its identity was being computed: ${packageRoot}`);
+    }
+    const nextCache = {
+        schemaVersion: IDENTITY_CACHE_SCHEMA_VERSION,
+        packageRoot,
+        buildRoot,
+        packageVersion,
+        buildKind: kind,
+        buildCanonicalization: BUILD_CANONICALIZATION,
+        dependencyCanonicalization: DEPENDENCY_RUNTIME_CANONICALIZATION,
+        traversalLimits,
+        runtimeVariant,
+        buildRootState: build.rootState,
+        buildDigest: build.digest,
+        buildEntries: build.entries,
+        buildDirectoryGuards: build.directoryGuards,
+        dependencyIdentity: dependency.identity,
+        dependencyFileGuards: dependencyFileGuards(dependencyInputs),
+        dependencyDirectoryGuards: dependencyDirectoryGuards(dependencyInputs),
+        dependencyPathGuards: dependencyPathGuards(dependencyInputs),
+        artifactEntries: dependency.entries,
+    };
+    const invokedDigest = cachedBuildDigestForPath(nextCache, invokedArtifactPath);
+    if (!invokedDigest) {
+        throw new Error(`Invoked analyzer artifact is absent from the validated build: ${invokedArtifactPath}`);
+    }
+    const identity = {
+        schemaVersion: ANALYZER_RUNNER_IDENTITY_SCHEMA_VERSION,
+        runtime: runnerRuntimeIdentity(runtimeVariant),
+        cliVersion: packageVersion,
+        invokedArtifact: {
+            path: invokedArtifactPath,
+            digest: invokedDigest,
+        },
+        build: {
+            kind,
+            rootPath: buildRoot,
+            canonicalization: BUILD_CANONICALIZATION,
+            digest: build.digest,
+        },
+        dependencyRuntime: dependency.identity,
+    };
+    let validationFailure;
+    const validationOptions = {
+        ...options,
+        onCacheValidationFailure: (failure) => {
+            validationFailure = failure;
+            options.onCacheValidationFailure?.(failure);
+        },
+    };
+    if (!validateIdentityCache(nextCache, validationOptions)) {
+        const mismatch = validationFailure
+            ? ` (failed ${validationFailure.mode} guard: ${validationFailure.path})`
+            : '';
+        throw new Error(`Analyzer build or dependency runtime changed while its identity was being computed: ${packageRoot}${mismatch}`);
+    }
+    rememberIdentityCache(nextCache);
+    persistIdentityCache(packageRoot, buildRoot, nextCache, previousCache, options);
+    return identity;
+}
+/**
+ * Semantic freshness comparison. Both receipts must be well-formed schema-v4
+ * values; only the diagnostic entrypoint field is normalized away.
+ */
+export function analyzerRunnerIdentitiesEqual(indexedIdentity, currentIdentity) {
+    const indexed = normalizeAnalyzerRunnerIdentityForComparison(indexedIdentity);
+    const current = normalizeAnalyzerRunnerIdentityForComparison(currentIdentity);
+    return indexed !== null && current !== null && isDeepStrictEqual(indexed, current);
+}
+/**
+ * Capture analyzer identity before invoking a loader that may evaluate the
+ * analyzer module graph. The explicit receipt is then threaded into analysis
+ * and checked again immediately before metadata commit.
+ */
+export async function captureAnalyzerIdentityBeforeLoad(analyzerModuleUrl, loader, options = {}) {
+    const runnerIdentity = resolveAnalyzerRunnerIdentity(analyzerModuleUrl, options);
+    const loaded = await loader();
+    return { runnerIdentity, loaded };
+}
+/** Re-resolve immediately before commit and reject analyzer mutation mid-run. */
+export function finalizeAnalyzerRunnerIdentity(analyzerModuleUrl, startedWith, options = {}) {
+    const finalIdentity = resolveAnalyzerRunnerIdentity(analyzerModuleUrl, options);
+    if (!analyzerRunnerIdentitiesEqual(startedWith, finalIdentity)) {
+        throw new Error('Analyzer build or dependency runtime changed during analysis; refusing to stamp metadata. ' +
+            'Retry with a stable GitNexus installation.');
+    }
+    return finalIdentity;
+}