@lzehrung/codegraph 2.3.20 → 2.3.22

package/dist/native/runtime-cache.js

@@ -0,0 +1,667 @@
+import { createHash, randomBytes } from "node:crypto";
+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));
+}
+function isWithinDirectory(filePath, directoryPath) {
+    const relative = path.relative(directoryPath, filePath);
+    return !relative || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function assertSafeCacheSegment(value, label) {
+    if (!value || value === "." || value === ".." || path.basename(value) !== value) {
+        throw new Error(`invalid native cache ${label}: ${value}`);
+    }
+    if (!/^[A-Za-z0-9._+-]+$/.test(value)) {
+        throw new Error(`invalid native cache ${label}: ${value}`);
+    }
+}
+function assertSafePathComponent(componentPath) {
+    const stats = fs.lstatSync(componentPath);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`unsafe native cache path component: ${componentPath}`);
+    }
+}
+function prepareSafeDirectory(directoryPath, create = true) {
+    const absolute = path.resolve(directoryPath);
+    const parsed = path.parse(absolute);
+    let current = parsed.root;
+    assertSafePathComponent(current);
+    const relativeParts = absolute.slice(parsed.root.length).split(path.sep).filter(Boolean);
+    for (const part of relativeParts) {
+        current = path.join(current, part);
+        try {
+            assertSafePathComponent(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || !create) {
+                throw error;
+            }
+            try {
+                fs.mkdirSync(current);
+            }
+            catch (mkdirError) {
+                if (mkdirError.code !== "EEXIST")
+                    throw mkdirError;
+            }
+            assertSafePathComponent(current);
+        }
+    }
+    return fs.realpathSync.native(absolute);
+}
+function findProductionCacheRoot() {
+    const localAppData = process.env.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 cacheRoot;
+}
+export function hashFileStreaming(filePath, onChunk) {
+    const before = fs.statSync(filePath);
+    if (!before.isFile() || before.size <= 0) {
+        throw new Error(`native binary is not a non-empty regular file: ${filePath}`);
+    }
+    const hash = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(HASH_BUFFER_SIZE);
+    const descriptor = fs.openSync(filePath, "r");
+    let size = 0;
+    try {
+        while (true) {
+            const bytesRead = fs.readSync(descriptor, buffer, 0, buffer.length, null);
+            if (!bytesRead)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+            size += bytesRead;
+            onChunk?.(bytesRead);
+        }
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    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, mtimeMs: before.mtimeMs };
+}
+function randomSuffix() {
+    return `${process.pid}.${randomBytes(8).toString("hex")}`;
+}
+function copyFileExclusive(sourcePath, destinationPath) {
+    const source = fs.openSync(sourcePath, "r");
+    let destination;
+    const buffer = Buffer.allocUnsafe(HASH_BUFFER_SIZE);
+    try {
+        destination = fs.openSync(destinationPath, "wx");
+        while (true) {
+            const bytesRead = fs.readSync(source, buffer, 0, buffer.length, null);
+            if (!bytesRead)
+                break;
+            let written = 0;
+            while (written < bytesRead) {
+                written += fs.writeSync(destination, buffer, written, bytesRead - written);
+            }
+        }
+        fs.fsyncSync(destination);
+    }
+    finally {
+        if (destination !== undefined)
+            fs.closeSync(destination);
+        fs.closeSync(source);
+    }
+}
+function removeRegularTemporaryFile(filePath) {
+    try {
+        const stats = fs.lstatSync(filePath);
+        if (stats.isFile() && !stats.isSymbolicLink())
+            fs.unlinkSync(filePath);
+    }
+    catch {
+        // Best-effort cleanup. A later bounded cleanup may remove abandoned temporary files.
+    }
+}
+function verifyFile(filePath, expected) {
+    try {
+        const actual = hashFileStreaming(filePath);
+        return actual.size === expected.size && actual.sha256 === expected.sha256 ? actual : null;
+    }
+    catch {
+        return null;
+    }
+}
+function publishExclusive(temporaryPath, finalPath) {
+    try {
+        fs.linkSync(temporaryPath, finalPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+    finally {
+        removeRegularTemporaryFile(temporaryPath);
+    }
+}
+function populateBinary(sourcePath, finalPath, expected) {
+    const temporaryPath = `${finalPath}.${randomSuffix()}.tmp`;
+    try {
+        copyFileExclusive(sourcePath, temporaryPath);
+        if (!verifyFile(temporaryPath, expected)) {
+            throw new Error("native cache temporary file failed integrity verification");
+        }
+        return publishExclusive(temporaryPath, finalPath);
+    }
+    catch (error) {
+        removeRegularTemporaryFile(temporaryPath);
+        throw error;
+    }
+}
+function recoverCorruptFinal(finalPath) {
+    const recoveryPath = `${finalPath}.corrupt.${randomSuffix()}`;
+    fs.renameSync(finalPath, recoveryPath);
+}
+function writeManifest(entryPath, manifest) {
+    const finalPath = path.join(entryPath, "manifest.json");
+    if (fs.existsSync(finalPath))
+        return;
+    const temporaryPath = `${finalPath}.${randomSuffix()}.tmp`;
+    try {
+        const descriptor = fs.openSync(temporaryPath, "wx");
+        try {
+            fs.writeFileSync(descriptor, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        publishExclusive(temporaryPath, finalPath);
+    }
+    catch (error) {
+        removeRegularTemporaryFile(temporaryPath);
+        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());
+        const targetPath = prepareSafeDirectory(path.join(cacheRoot, request.target));
+        if (!isWithinDirectory(targetPath, cacheRoot)) {
+            throw new Error("native cache target escaped the cache root");
+        }
+        const cacheKey = `${request.packageName}@${request.packageVersion}:${request.target}:${source.sha256}`;
+        const entryPath = prepareSafeDirectory(path.join(targetPath, `${request.packageVersion}-${source.sha256}`));
+        if (!isWithinDirectory(entryPath, cacheRoot)) {
+            throw new Error("native cache entry escaped the cache root");
+        }
+        const sourceFileName = path.basename(sourceRealPath);
+        const finalPath = path.join(entryPath, sourceFileName);
+        let status = "reused";
+        let cached = fs.existsSync(finalPath) ? verifyFile(finalPath, source) : null;
+        if (!cached) {
+            if (fs.existsSync(finalPath))
+                recoverCorruptFinal(finalPath);
+            status = populateBinary(sourceRealPath, finalPath, source) ? "cached" : "reused";
+            cached = verifyFile(finalPath, source);
+            if (!cached) {
+                throw new Error("native cache winner failed integrity verification");
+            }
+        }
+        writeManifest(entryPath, {
+            schemaVersion: CACHE_SCHEMA_VERSION,
+            packageName: request.packageName,
+            packageVersion: request.packageVersion,
+            target: request.target,
+            sourceFileName,
+            sourceSize: source.size,
+            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) {
+        return { status: "unavailable", sourcePath, error: asError(error) };
+    }
+}
+//# sourceMappingURL=runtime-cache.js.map