@lzehrung/codegraph 2.1.2 → 2.2.0

package/dist/native/runtimeCache.d.ts

@@ -1,3 +1,4 @@
+import type { NativeBindingOrigin } from "./contracts.js";
 export type NativeCacheManifestV1 = {
     schemaVersion: 1;
     packageName: string;
@@ -8,12 +9,57 @@ export type NativeCacheManifestV1 = {
     sourceSha256: string;
     cachedAt: string;
 };
+/**
+ * Written as a path-keyed record beside `manifest.json` after a process has successfully
+ * loaded the cached binary. `manifest.json` is content-addressed and published once,
+ * immutably; these records are mutable (the TTL refreshes them) and carry facts that only exist
+ * after the addon loads. One record per source realpath lets projects sharing the binary retain
+ * their own origin without invalidating each other's fast path.
+ */
+export type NativeCacheIdentityV1 = {
+    version: 1;
+    /** Size and mtime of the installed source binary at the last full verification. */
+    sourceSize: number;
+    sourceMtimeMs: number;
+    /** Size and mtime of the cached copy that was verified and then loaded. */
+    cachedSize: number;
+    cachedMtimeMs: number;
+    sha256: string;
+    cacheKey: string;
+    sourcePath: string;
+    loadedPath: string;
+    verifiedAt: string;
+    /**
+     * The runtime that proved this file loadable. The stat fields say the bytes are unchanged;
+     * they say nothing about whether this Node can still load them. A major Node upgrade changes
+     * the ABI, so the same bytes stop loading while every other check still matches, and the fast
+     * path would report an addon as available that the build then falls back away from.
+     */
+    runtime: {
+        abi: string;
+        platform: string;
+        arch: string;
+    };
+    /**
+     * Recorded so a cache-hit command can answer "which languages does the addon support"
+     * without loading it. Present only once a load has succeeded for this exact file.
+     */
+    supportedLanguageIds: string[];
+    /**
+     * The origin the loading process reported, stored whole rather than rebuilt field by field.
+     * The runtime fingerprint embeds this object verbatim, so replaying it is what guarantees a
+     * fast-path fingerprint is byte-identical to the one a full load produces.
+     */
+    origin: NativeBindingOrigin;
+};
 export type PrepareNativeRuntimeCacheRequest = {
     sourcePath: string;
     packageName: string;
     packageVersion: string;
     target: string;
     cacheRoot?: string | undefined;
+    /** Injected in tests so the identity TTL branch is reachable without waiting a day. */
+    now?: number | undefined;
 };
 export type PrepareNativeRuntimeCacheResult = {
     status: "cached" | "reused";
@@ -21,6 +67,17 @@ export type PrepareNativeRuntimeCacheResult = {
     loadedPath: string;
     cacheKey: string;
     sha256: string;
+    /** Verified stat snapshots used to reject a source/cache replacement before identity recording. */
+    sourceSize: number;
+    sourceMtimeMs: number;
+    cachedSize: number;
+    cachedMtimeMs: number;
+    /**
+     * True when this call hashed the files rather than trusting a recorded identity. Only a
+     * verified result may refresh the identity record, otherwise each fast-path hit would
+     * push the re-verification TTL out and the entry would never be hashed again.
+     */
+    verified: boolean;
 } | {
     status: "unavailable";
     sourcePath: string;
@@ -29,8 +86,43 @@ export type PrepareNativeRuntimeCacheResult = {
 type FileHash = {
     sha256: string;
     size: number;
+    mtimeMs: number;
 };
 export declare function hashFileStreaming(filePath: string, onChunk?: (bytesRead: number) => void): FileHash;
+export type NativeCacheLookupRequest = {
+    sourcePath: string;
+    packageName: string;
+    packageVersion: string;
+    target: string;
+    cacheRoot?: string | undefined;
+    /** Injected in tests so the TTL branch is reachable without waiting a day. */
+    now?: number | undefined;
+};
+export type NativeCacheLookupHit = {
+    entryPath: string;
+    identity: NativeCacheIdentityV1;
+    revalidateAt: number;
+};
+/**
+ * Find a cache entry for this (package version, target) whose recorded identity still matches
+ * the files on disk, without hashing either of them.
+ *
+ * The entry directory is named `<packageVersion>-<sha256>`, so locating it the normal way means
+ * hashing the source first. Scanning the target directory for the version prefix and comparing
+ * the stat fields recorded at the last full verification reaches the same entry with bounded
+ * metadata reads. A miss - no entry, no identity file, a stat mismatch, or an expired
+ * TTL - returns null, and every caller then does the full hash-and-verify pass.
+ */
+export declare function lookupNativeRuntimeCacheEntry(request: NativeCacheLookupRequest): NativeCacheLookupHit | null;
+/**
+ * Record what a successful load proved about this entry, so the next process can skip both
+ * SHA-256 passes and the addon load itself. Called only after the binary at `loadedPath` has
+ * been fully verified and then loaded, so every field describes a state known to work.
+ *
+ * Replaces any previous record atomically: the TTL refresh rewrites it, unlike the immutable
+ * `manifest.json` beside it.
+ */
+export declare function recordNativeRuntimeCacheIdentity(identity: Omit<NativeCacheIdentityV1, "version" | "runtime">): void;
 export declare function prepareNativeRuntimeCache(request: PrepareNativeRuntimeCacheRequest): PrepareNativeRuntimeCacheResult;
 export {};
 //# sourceMappingURL=runtimeCache.d.ts.map

package/dist/native/runtimeCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtimeCache.d.ts","sourceRoot":"","sources":["../../src/native/runtimeCache.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,qBAAqB,GAAG;IAClC,aAAa,EAAE,CAAC,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,+BAA+B,GACvC;IACE,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEN,KAAK,QAAQ,GAAG;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AA8DF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,QAAQ,CA0BnG;AAgGD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gCAAgC,GAAG,+BAA+B,CAoDpH"}
+{"version":3,"file":"runtimeCache.d.ts","sourceRoot":"","sources":["../../src/native/runtimeCache.ts"],"names":[],"mappings":"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"}

package/dist/native/runtimeCache.js

@@ -3,6 +3,32 @@ import fs from "node:fs";
 import path from "node:path";
 const CACHE_SCHEMA_VERSION = 1;
 const HASH_BUFFER_SIZE = 1024 * 1024;
+const IDENTITY_FILE_PREFIX = "identity-";
+const IDENTITY_FILE_SUFFIX = ".json";
+const IDENTITY_VERSION = 1;
+/**
+ * How long a stat-only match is trusted before the entry is hashed again.
+ *
+ * The fast path below skips two 29 MB SHA-256 passes when the source and cached binaries
+ * both match the size and mtime recorded at the last full verification. That is weaker than
+ * hashing: an attacker who can write the cache directory can also preserve both fields. The
+ * TTL bounds how long such a substitution goes unnoticed, so verification still happens -
+ * once a day per entry instead of twice per process.
+ */
+const IDENTITY_REVERIFY_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/**
+ * How long an entry for another package version is kept before it is treated as abandoned.
+ *
+ * The cache root is per-user and shared by every project on the machine, so "not the version I
+ * am installing" does not mean "nobody's". Deleting on that basis alone makes two projects
+ * pinned to different native versions delete each other's entry on every run, each re-copying
+ * 29 MB and never reaching the fast path - worse than the unbounded growth it set out to fix.
+ *
+ * An entry in use is re-verified at least every IDENTITY_REVERIFY_INTERVAL_MS of use, and that
+ * refreshes its timestamp, so an entry older than this window is one no project has run in a
+ * month. That is the signal, rather than which version happens to be installing right now.
+ */
+const ABANDONED_ENTRY_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 function asError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
@@ -24,7 +50,7 @@ function assertSafePathComponent(componentPath) {
         throw new Error(`unsafe native cache path component: ${componentPath}`);
     }
 }
-function prepareSafeDirectory(directoryPath) {
+function prepareSafeDirectory(directoryPath, create = true) {
     const absolute = path.resolve(directoryPath);
     const parsed = path.parse(absolute);
     let current = parsed.root;
@@ -36,7 +62,7 @@ function prepareSafeDirectory(directoryPath) {
             assertSafePathComponent(current);
         }
         catch (error) {
-            if (error.code !== "ENOENT") {
+            if (error.code !== "ENOENT" || !create) {
                 throw error;
             }
             try {
@@ -51,12 +77,18 @@ function prepareSafeDirectory(directoryPath) {
     }
     return fs.realpathSync.native(absolute);
 }
-function resolveProductionCacheRoot() {
+function findProductionCacheRoot() {
     const localAppData = process.env.LOCALAPPDATA;
-    if (!localAppData) {
+    if (!localAppData)
+        return null;
+    return path.join(localAppData, "codegraph", "native-cache", `v${CACHE_SCHEMA_VERSION}`);
+}
+function resolveProductionCacheRoot() {
+    const cacheRoot = findProductionCacheRoot();
+    if (!cacheRoot) {
         throw new Error("LOCALAPPDATA is unavailable; cannot prepare the Windows native runtime cache");
     }
-    return path.join(localAppData, "codegraph", "native-cache", `v${CACHE_SCHEMA_VERSION}`);
+    return cacheRoot;
 }
 export function hashFileStreaming(filePath, onChunk) {
     const before = fs.statSync(filePath);
@@ -80,10 +112,11 @@ export function hashFileStreaming(filePath, onChunk) {
     finally {
         fs.closeSync(descriptor);
     }
-    if (size !== before.size) {
+    const after = fs.statSync(filePath);
+    if (!after.isFile() || size !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs) {
         throw new Error(`native binary changed while hashing: ${filePath}`);
     }
-    return { sha256: hash.digest("hex"), size };
+    return { sha256: hash.digest("hex"), size, mtimeMs: before.mtimeMs };
 }
 function randomSuffix() {
     return `${process.pid}.${randomBytes(8).toString("hex")}`;
@@ -124,10 +157,10 @@ function removeRegularTemporaryFile(filePath) {
 function verifyFile(filePath, expected) {
     try {
         const actual = hashFileStreaming(filePath);
-        return actual.size === expected.size && actual.sha256 === expected.sha256;
+        return actual.size === expected.size && actual.sha256 === expected.sha256 ? actual : null;
     }
     catch {
-        return false;
+        return null;
     }
 }
 function publishExclusive(temporaryPath, finalPath) {
@@ -183,11 +216,399 @@ function writeManifest(entryPath, manifest) {
         throw error;
     }
 }
+function currentRuntimeStamp() {
+    return { abi: process.versions.modules, platform: process.platform, arch: process.arch };
+}
+function identityFilePath(entryPath, sourcePath) {
+    const sourceKey = createHash("sha256").update(sourcePath).digest("hex");
+    return path.join(entryPath, `${IDENTITY_FILE_PREFIX}${sourceKey}${IDENTITY_FILE_SUFFIX}`);
+}
+function isIdentityFileName(fileName) {
+    return /^identity-[a-f0-9]{64}\.json$/.test(fileName);
+}
+function readCacheIdentityFile(filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        // Absent (an entry written before this file existed), unreadable, or malformed. All three
+        // mean the same thing to the caller: no fast path, fall back to hashing.
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const candidate = parsed;
+    if (candidate.version !== IDENTITY_VERSION)
+        return null;
+    const numbers = [candidate.sourceSize, candidate.sourceMtimeMs, candidate.cachedSize, candidate.cachedMtimeMs];
+    if (numbers.some((value) => typeof value !== "number" || !Number.isFinite(value)))
+        return null;
+    const strings = [
+        candidate.sha256,
+        candidate.cacheKey,
+        candidate.sourcePath,
+        candidate.loadedPath,
+        candidate.verifiedAt,
+    ];
+    if (strings.some((value) => typeof value !== "string" || !value))
+        return null;
+    if (!Array.isArray(candidate.supportedLanguageIds))
+        return null;
+    if (candidate.supportedLanguageIds.some((value) => typeof value !== "string"))
+        return null;
+    const origin = candidate.origin;
+    if (!origin || typeof origin !== "object" || origin.mode !== "cache" || typeof origin.packageName !== "string") {
+        return null;
+    }
+    const runtime = candidate.runtime;
+    if (!runtime || typeof runtime !== "object")
+        return null;
+    if (typeof runtime.abi !== "string" || typeof runtime.platform !== "string" || typeof runtime.arch !== "string") {
+        return null;
+    }
+    return candidate;
+}
+function readCacheIdentity(entryPath, sourcePath) {
+    return readCacheIdentityFile(identityFilePath(entryPath, sourcePath));
+}
+function latestCacheIdentityVerifiedAt(entryPath, now) {
+    let fileNames;
+    try {
+        fileNames = fs.readdirSync(entryPath);
+    }
+    catch {
+        return Number.NaN;
+    }
+    let latest = Number.NaN;
+    for (const fileName of fileNames) {
+        if (!isIdentityFileName(fileName))
+            continue;
+        const identity = readCacheIdentityFile(path.join(entryPath, fileName));
+        const verifiedAt = identity ? Date.parse(identity.verifiedAt) : Number.NaN;
+        if (!Number.isFinite(verifiedAt) || verifiedAt > now)
+            continue;
+        if (!Number.isFinite(latest) || verifiedAt > latest)
+            latest = verifiedAt;
+    }
+    return latest;
+}
+function statOrNull(filePath) {
+    try {
+        const stats = fs.statSync(filePath);
+        return stats.isFile() ? stats : null;
+    }
+    catch {
+        return null;
+    }
+}
+function lstatRegularFileOrNull(filePath) {
+    try {
+        const stats = fs.lstatSync(filePath);
+        return stats.isFile() && !stats.isSymbolicLink() ? stats : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isSafeExistingDirectory(directoryPath) {
+    try {
+        prepareSafeDirectory(directoryPath, false);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pathsResolveEqual(left, right) {
+    return path.resolve(left) === path.resolve(right);
+}
+/**
+ * Find a cache entry for this (package version, target) whose recorded identity still matches
+ * the files on disk, without hashing either of them.
+ *
+ * The entry directory is named `<packageVersion>-<sha256>`, so locating it the normal way means
+ * hashing the source first. Scanning the target directory for the version prefix and comparing
+ * the stat fields recorded at the last full verification reaches the same entry with bounded
+ * metadata reads. A miss - no entry, no identity file, a stat mismatch, or an expired
+ * TTL - returns null, and every caller then does the full hash-and-verify pass.
+ */
+export function lookupNativeRuntimeCacheEntry(request) {
+    try {
+        assertSafeCacheSegment(request.target, "target");
+        assertSafeCacheSegment(request.packageVersion, "package version");
+        const cacheRoot = request.cacheRoot ?? findProductionCacheRoot();
+        if (!cacheRoot)
+            return null;
+        const sourceRealPath = fs.realpathSync.native(request.sourcePath);
+        const sourceStats = statOrNull(sourceRealPath);
+        if (!sourceStats)
+            return null;
+        const runtime = currentRuntimeStamp();
+        const resolvedCacheRoot = path.resolve(cacheRoot);
+        const targetPath = path.join(resolvedCacheRoot, request.target);
+        if (!isSafeExistingDirectory(resolvedCacheRoot) || !isSafeExistingDirectory(targetPath))
+            return null;
+        const prefix = `${request.packageVersion}-`;
+        let entryNames;
+        try {
+            entryNames = fs.readdirSync(targetPath);
+        }
+        catch {
+            return null;
+        }
+        const now = request.now ?? Date.now();
+        for (const entryName of entryNames) {
+            if (!entryName.startsWith(prefix))
+                continue;
+            const entryPath = path.join(targetPath, entryName);
+            if (!isSafeExistingDirectory(entryPath))
+                continue;
+            const identity = readCacheIdentity(entryPath, sourceRealPath);
+            if (!identity)
+                continue;
+            const expectedEntryName = `${request.packageVersion}-${identity.sha256}`;
+            const expectedCacheKey = `${request.packageName}@${request.packageVersion}:${request.target}:${identity.sha256}`;
+            const loadedPath = path.resolve(identity.loadedPath);
+            if (entryName !== expectedEntryName ||
+                identity.cacheKey !== expectedCacheKey ||
+                identity.loadedPath !== loadedPath ||
+                path.dirname(loadedPath) !== entryPath ||
+                path.basename(loadedPath) !== path.basename(sourceRealPath)) {
+                continue;
+            }
+            // Same version, same bytes, different install. The cache root is shared by every project
+            // on the machine, and npm can produce byte-identical files with matching mtimes, so size
+            // and mtime alone can match another project's record - whose sourcePath would then be
+            // replayed into this build's binding origin and change its runtime fingerprint.
+            if (identity.sourcePath !== sourceRealPath)
+                continue;
+            if (identity.sourceSize !== sourceStats.size || identity.sourceMtimeMs !== sourceStats.mtimeMs)
+                continue;
+            if (identity.origin.packageName !== request.packageName ||
+                identity.origin.packageVersion !== request.packageVersion ||
+                identity.origin.target !== request.target ||
+                identity.origin.sourcePath === undefined ||
+                identity.origin.loadedPath === undefined ||
+                !pathsResolveEqual(identity.origin.sourcePath, sourceRealPath) ||
+                !pathsResolveEqual(identity.origin.loadedPath, identity.loadedPath) ||
+                identity.origin.cacheKey !== identity.cacheKey ||
+                identity.origin.sha256 !== identity.sha256) {
+                continue;
+            }
+            // Recorded by a runtime that could load the file. A different ABI cannot, and claiming
+            // otherwise would report native as available for a build that falls back away from it.
+            if (identity.runtime.abi !== runtime.abi ||
+                identity.runtime.platform !== runtime.platform ||
+                identity.runtime.arch !== runtime.arch) {
+                continue;
+            }
+            const cachedStats = lstatRegularFileOrNull(identity.loadedPath);
+            if (!cachedStats)
+                continue;
+            if (identity.cachedSize !== cachedStats.size || identity.cachedMtimeMs !== cachedStats.mtimeMs)
+                continue;
+            const verifiedAt = Date.parse(identity.verifiedAt);
+            if (!Number.isFinite(verifiedAt) || verifiedAt > now || now - verifiedAt >= IDENTITY_REVERIFY_INTERVAL_MS) {
+                continue;
+            }
+            if (!isWithinDirectory(identity.loadedPath, resolvedCacheRoot))
+                continue;
+            return { entryPath, identity, revalidateAt: verifiedAt + IDENTITY_REVERIFY_INTERVAL_MS };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record what a successful load proved about this entry, so the next process can skip both
+ * SHA-256 passes and the addon load itself. Called only after the binary at `loadedPath` has
+ * been fully verified and then loaded, so every field describes a state known to work.
+ *
+ * Replaces any previous record atomically: the TTL refresh rewrites it, unlike the immutable
+ * `manifest.json` beside it.
+ */
+export function recordNativeRuntimeCacheIdentity(identity) {
+    try {
+        const sourceStats = statOrNull(identity.sourcePath);
+        const cachedStats = lstatRegularFileOrNull(identity.loadedPath);
+        if (!sourceStats ||
+            !cachedStats ||
+            sourceStats.size !== identity.sourceSize ||
+            sourceStats.mtimeMs !== identity.sourceMtimeMs ||
+            cachedStats.size !== identity.cachedSize ||
+            cachedStats.mtimeMs !== identity.cachedMtimeMs) {
+            return;
+        }
+        const entryPath = path.dirname(identity.loadedPath);
+        const record = {
+            version: IDENTITY_VERSION,
+            runtime: currentRuntimeStamp(),
+            ...identity,
+        };
+        const finalPath = identityFilePath(entryPath, identity.sourcePath);
+        const temporaryPath = `${finalPath}.${randomSuffix()}.tmp`;
+        try {
+            const descriptor = fs.openSync(temporaryPath, "wx");
+            try {
+                fs.writeFileSync(descriptor, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+                fs.fsyncSync(descriptor);
+            }
+            finally {
+                fs.closeSync(descriptor);
+            }
+            fs.renameSync(temporaryPath, finalPath);
+        }
+        catch {
+            removeRegularTemporaryFile(temporaryPath);
+        }
+    }
+    catch {
+        // Best effort. Failing to record identity costs the next process the slow path, nothing more.
+    }
+}
+/**
+ * When an entry was last known to be in use, and which version it holds.
+ *
+ * Path-keyed identity records are refreshed whenever a process re-verifies an entry, so their
+ * latest non-future timestamp is the freshest signal. `manifest.json`'s `cachedAt` covers an
+ * entry that has never been loaded through the fast path. An entry that yields neither is left
+ * alone rather than guessed about.
+ */
+function readEntrySummary(entryPath, now) {
+    let packageVersion = null;
+    let sourceFileName = null;
+    let cachedAtMs = null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(entryPath, "manifest.json"), "utf8"));
+        if (parsed && typeof parsed === "object") {
+            const manifest = parsed;
+            if (typeof manifest.packageVersion === "string" && manifest.packageVersion) {
+                packageVersion = manifest.packageVersion;
+            }
+            if (typeof manifest.sourceFileName === "string" &&
+                manifest.sourceFileName &&
+                path.basename(manifest.sourceFileName) === manifest.sourceFileName) {
+                sourceFileName = manifest.sourceFileName;
+            }
+            const cachedAt = typeof manifest.cachedAt === "string" ? Date.parse(manifest.cachedAt) : Number.NaN;
+            if (Number.isFinite(cachedAt))
+                cachedAtMs = cachedAt;
+        }
+    }
+    catch {
+        // Missing or malformed: indistinguishable from an entry another process is still writing.
+        return null;
+    }
+    if (!packageVersion || !sourceFileName)
+        return null;
+    const verifiedAt = latestCacheIdentityVerifiedAt(entryPath, now);
+    const lastUsedMs = Number.isFinite(verifiedAt) ? verifiedAt : cachedAtMs;
+    if (lastUsedMs === null)
+        return null;
+    return { packageVersion, lastUsedMs, sourceFileName };
+}
+/**
+ * Delete the mapped binary before its metadata. Windows rejects an unlink of a loaded DLL,
+ * leaving the whole entry unchanged instead of partially deleting it through recursive removal.
+ */
+function removeAbandonedEntry(entryPath, sourceFileName) {
+    const cachedBinaryPath = path.join(entryPath, sourceFileName);
+    if (!isWithinDirectory(cachedBinaryPath, entryPath) || path.dirname(cachedBinaryPath) !== entryPath) {
+        throw new Error("invalid native cache binary path");
+    }
+    const stats = fs.lstatSync(cachedBinaryPath);
+    if (!stats.isFile() || stats.isSymbolicLink())
+        throw new Error("unsafe native cache binary");
+    fs.unlinkSync(cachedBinaryPath);
+    fs.rmSync(entryPath, { recursive: true, force: true });
+}
+/**
+ * Delete entries that no project has used in a long time.
+ *
+ * The cache only ever grew: every upgrade left roughly 29 MB behind, and a machine that had
+ * tracked a few releases carried well over a hundred megabytes of addons nothing would load
+ * again. Keeping the directory small also keeps it warm, which is what the stat-only fast path
+ * above depends on.
+ *
+ * Retention is by age rather than by version, because the cache root is per-user and shared by
+ * every project on the machine. Removing "every version that is not the one installing" would
+ * make two projects pinned to different native versions delete each other's entry on every run.
+ *
+ * Best effort throughout, and deliberately conservative:
+ * - the entry just produced is never a candidate, nor is any entry for its version;
+ * - an entry whose manifest is missing, unreadable, or undated is left alone, because that is
+ *   what a concurrent population in progress looks like;
+ * - Windows holds a lock on a loaded DLL, so unlinking its binary fails with EBUSY or EPERM
+ *   before recursive metadata removal begins. Those failures preserve the whole entry and are
+ *   expected rather than exceptional, so they are simply skipped.
+ */
+function pruneAbandonedEntries(targetPath, cacheRoot, keepEntryPath, keepVersion, now) {
+    let entryNames;
+    try {
+        entryNames = fs.readdirSync(targetPath);
+    }
+    catch {
+        return;
+    }
+    for (const entryName of entryNames) {
+        const entryPath = path.join(targetPath, entryName);
+        if (entryPath === keepEntryPath)
+            continue;
+        if (!isWithinDirectory(entryPath, cacheRoot))
+            continue;
+        try {
+            if (!fs.lstatSync(entryPath).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const summary = readEntrySummary(entryPath, now);
+        if (!summary || summary.packageVersion === keepVersion)
+            continue;
+        if (now - summary.lastUsedMs < ABANDONED_ENTRY_RETENTION_MS)
+            continue;
+        try {
+            removeAbandonedEntry(entryPath, summary.sourceFileName);
+        }
+        catch {
+            // In use, incomplete, or not ours to remove. The next install tries again.
+        }
+    }
+}
 export function prepareNativeRuntimeCache(request) {
     const sourcePath = path.resolve(request.sourcePath);
     try {
         assertSafeCacheSegment(request.target, "target");
         assertSafeCacheSegment(request.packageVersion, "package version");
+        // Cheap-identity fast path: a previous process verified this exact pair of files and
+        // recorded their stat fields, so nothing here needs to be hashed. Population and every
+        // mismatch still take the full path below.
+        const hit = lookupNativeRuntimeCacheEntry({
+            sourcePath,
+            packageName: request.packageName,
+            packageVersion: request.packageVersion,
+            target: request.target,
+            ...(request.cacheRoot !== undefined ? { cacheRoot: request.cacheRoot } : {}),
+            ...(request.now !== undefined ? { now: request.now } : {}),
+        });
+        if (hit) {
+            return {
+                status: "reused",
+                sourcePath: hit.identity.sourcePath,
+                loadedPath: hit.identity.loadedPath,
+                cacheKey: hit.identity.cacheKey,
+                sha256: hit.identity.sha256,
+                sourceSize: hit.identity.sourceSize,
+                sourceMtimeMs: hit.identity.sourceMtimeMs,
+                cachedSize: hit.identity.cachedSize,
+                cachedMtimeMs: hit.identity.cachedMtimeMs,
+                verified: false,
+            };
+        }
         const sourceRealPath = fs.realpathSync.native(sourcePath);
         const source = hashFileStreaming(sourceRealPath);
         const cacheRoot = prepareSafeDirectory(request.cacheRoot ?? resolveProductionCacheRoot());
@@ -203,12 +624,13 @@ export function prepareNativeRuntimeCache(request) {
         const sourceFileName = path.basename(sourceRealPath);
         const finalPath = path.join(entryPath, sourceFileName);
         let status = "reused";
-        const finalExists = fs.existsSync(finalPath);
-        if (!finalExists || !verifyFile(finalPath, source)) {
-            if (finalExists)
+        let cached = fs.existsSync(finalPath) ? verifyFile(finalPath, source) : null;
+        if (!cached) {
+            if (fs.existsSync(finalPath))
                 recoverCorruptFinal(finalPath);
             status = populateBinary(sourceRealPath, finalPath, source) ? "cached" : "reused";
-            if (!verifyFile(finalPath, source)) {
+            cached = verifyFile(finalPath, source);
+            if (!cached) {
                 throw new Error("native cache winner failed integrity verification");
             }
         }
@@ -222,12 +644,20 @@ export function prepareNativeRuntimeCache(request) {
             sourceSha256: source.sha256,
             cachedAt: new Date().toISOString(),
         });
+        // Only on the verified path. A fast-path hit means nothing new arrived, so there is nothing
+        // to clean up, and the warm run stays free of extra directory work.
+        pruneAbandonedEntries(targetPath, cacheRoot, entryPath, request.packageVersion, request.now ?? Date.now());
         return {
             status,
             sourcePath: sourceRealPath,
             loadedPath: finalPath,
             cacheKey,
             sha256: source.sha256,
+            sourceSize: source.size,
+            sourceMtimeMs: source.mtimeMs,
+            cachedSize: cached.size,
+            cachedMtimeMs: cached.mtimeMs,
+            verified: true,
         };
     }
     catch (error) {