rea-agents 6.4.0 → 6.7.0

package/dist/kuna/KunaProjectCache.js

@@ -0,0 +1,804 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, stat, utimes, } from "node:fs/promises";
+import { join } from "node:path";
+import canonicalize from "canonicalize";
+import writeFileAtomic from "write-file-atomic";
+import { z } from "zod";
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
+import { AnalysisCancelledError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { hashStableFile, stableFileHashCause, } from "../filesystem/StableFileHash.js";
+import { RegularFileCleanupFailure, regularFileCancellation, } from "../filesystem/OwnedRegularFile.js";
+import { exportKunaProject, KUNA_EXPORT_OPERATION, kunaExportFailure, readKunaExport, } from "./KunaProjectExport.js";
+import { KUNA_PROVIDER_ID } from "./KunaRelease.js";
+/** Bumped whenever the entry layout or manifest meaning changes. */
+const CACHE_LAYOUT = 1;
+/** A manifest names five files and their digests; anything larger is not ours. */
+const MANIFEST_MAX_BYTES = 64 * 1024;
+const KEY_PATTERN = /^[0-9a-f]{64}$/u;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+/** Content address of one export: every input that can change its bytes. */
+export const kunaProjectKey = (inputs) => createHash("sha256")
+    .update(canonicalize({
+    layout: CACHE_LAYOUT,
+    target_sha256: inputs.targetSha256,
+    kuna_sha256: inputs.kunaSha256,
+    kuna_version: inputs.kunaVersion,
+    export: { command: "decompile-project", jobs: inputs.jobs },
+}) ?? "")
+    .digest("hex");
+const fileSchema = z.strictObject({
+    path: z.string().min(1),
+    bytes: z.number().int().nonnegative(),
+    sha256: z.string().regex(SHA256_PATTERN),
+});
+const manifestSchema = z.strictObject({
+    layout: z.literal(CACHE_LAYOUT),
+    key: z.string().regex(KEY_PATTERN),
+    inputs: z.strictObject({
+        target_sha256: z.string().regex(SHA256_PATTERN),
+        kuna_sha256: z.string().regex(SHA256_PATTERN),
+        kuna_version: z.string().min(1),
+        jobs: z.number().int().positive(),
+    }),
+    files: z.strictObject({
+        c: fileSchema,
+        h: fileSchema,
+        asm: fileSchema,
+        readme: fileSchema,
+        inventory: fileSchema,
+    }),
+    summary: z.strictObject({
+        decompiled: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+    }),
+    created_at: z.string().datetime(),
+});
+const isMissing = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    (cause.code === "ENOENT" || cause.code === "ENOTDIR");
+/** A file an entry's manifest names is gone, replaced or changed under it. */
+const isDamaged = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    ["ENOENT", "ENOTDIR", "EISDIR", "ENOTFILE", "ESTALE"].includes(String(cause.code));
+const isPublishedByAnother = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    (cause.code === "EEXIST" || cause.code === "ENOTEMPTY");
+const parseManifest = (text) => {
+    try {
+        const parsed = manifestSchema.safeParse(JSON.parse(text));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const manifestBytes = (manifest) => Object.values(manifest.files).reduce((sum, file) => sum + file.bytes, 0);
+/**
+ * REA-owned on-disk cache of `kuna decompile-project` exports.
+ *
+ * Layout under the root: `projects/<key>/` holds published entries
+ * (`manifest.json` plus the export and inventory in `project/`), `staging/`
+ * holds builds whose processes may still be live, `trash/` holds retired
+ * workspaces and evicted entries awaiting removal,
+ * and `home/` is Kuna's own HOME so its spec cache stays inside REA's
+ * ownership.
+ *
+ * Entries are content-addressed and immutable. A build runs in private
+ * staging and is published by one directory rename, so a reader sees a
+ * complete entry or none, and concurrent publishers of one key keep the first.
+ * File digests are recorded once at publish and checked on every first read.
+ * Recency is the entry directory's mtime; publishing evicts the least recently
+ * used entries above the size cap, never an entry pinned by this process.
+ */
+export class KunaProjectCache {
+    #root;
+    #maxBytes;
+    #launcher;
+    /** Builds new requests may join, at most one per key. */
+    #inflight = new Map();
+    /** Every build not yet settled, including abandoned ones a retry replaced. */
+    #unfinished = new Set();
+    #verified = new Map();
+    #pins = new Map();
+    /** One eviction decision at a time; exports themselves remain concurrent. */
+    #eviction = Promise.resolve();
+    #capacity = "within_limit";
+    #maintenance;
+    #maintenanceRequested = false;
+    /** Builds whose process tree could not be proven stopped; their staging stays. */
+    #retainedProcesses = [];
+    /** Only resources whose process cleanup is proven may be retried as files. */
+    #retainedFiles = new Map();
+    /** Hash descriptors whose close was not confirmed; staging stays until retry. */
+    #retainedHashFiles = new Map();
+    /** Keep the exact close lease available for errors bound after a retry ends. */
+    #hashRecords = new WeakMap();
+    /** Serialize owner release and staging retirement across concurrent lookups. */
+    #hashRetry = Promise.resolve();
+    /** Weakly track caller errors against every resource owner they report. */
+    #cleanupErrorReports = [];
+    #stagingCleanupOwners = new Map();
+    constructor(root, options) {
+        this.#root = root;
+        this.#maxBytes = options.maxBytes;
+        this.#launcher = options.launcher;
+    }
+    /** Report cleanup owners retained after failed process or file cleanup. */
+    get hasPendingCleanup() {
+        return (this.#retainedProcesses.length > 0 ||
+            this.#retainedFiles.size > 0 ||
+            this.#retainedHashFiles.size > 0);
+    }
+    /** Keep an entry from eviction while this process serves it. */
+    pin(key) {
+        this.#pins.set(key, (this.#pins.get(key) ?? 0) + 1);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const count = (this.#pins.get(key) ?? 1) - 1;
+            if (count === 0) {
+                this.#pins.delete(key);
+                if (this.#capacity !== "within_limit")
+                    this.#scheduleEviction();
+            }
+            else
+                this.#pins.set(key, count);
+        };
+    }
+    /**
+     * Return the verified published entry for a key, or undefined when none is
+     * usable. A corrupt or tampered entry is removed and reported as absent.
+     */
+    async lookup(key, signal) {
+        await this.#retryHashFiles(key);
+        const cleanup = this.#cleanupResult(this.#hashCleanupFailures(key));
+        if (!cleanup.ok)
+            throw cleanup.error;
+        const verified = this.#verified.get(key);
+        if (verified !== undefined) {
+            // Another process may have evicted it since this one verified it.
+            if (await this.#touch(key))
+                return verified;
+            this.#verified.delete(key);
+            return undefined;
+        }
+        const entry = join(this.#root, "projects", key);
+        let text;
+        try {
+            text = await this.#readBounded(join(entry, "manifest.json"));
+        }
+        catch (cause) {
+            if (isMissing(cause))
+                return undefined;
+            if (!(cause instanceof RangeError))
+                throw cause;
+            await this.#discard(key);
+            return undefined;
+        }
+        const manifest = parseManifest(text);
+        if (manifest?.key !== key) {
+            await this.#discard(key);
+            return undefined;
+        }
+        const directory = join(entry, "project");
+        for (const file of Object.values(manifest.files)) {
+            let observed;
+            try {
+                const path = join(directory, file.path);
+                observed = await hashStableFile(path, {
+                    ...(signal === undefined ? {} : { signal }),
+                    retainFailedClose: (owner) => this.#retainHashFile(owner, key, null, path),
+                });
+            }
+            catch (cause) {
+                if (cause instanceof RegularFileCleanupFailure)
+                    throw this.#replaceHashCloseError(key, null, kunaExportFailure(cause, signal), cause);
+                if (regularFileCancellation(cause) !== undefined)
+                    throw cause;
+                if (!isDamaged(stableFileHashCause(cause)))
+                    throw cause;
+                await this.#discard(key);
+                return undefined;
+            }
+            if (observed.sha256 !== file.sha256 || observed.bytes !== file.bytes) {
+                await this.#discard(key);
+                return undefined;
+            }
+        }
+        const parsed = await readKunaExport(directory, manifest.files, manifest.summary, signal);
+        if (!parsed.ok) {
+            await this.#discard(key);
+            return undefined;
+        }
+        const project = { key, directory, manifest, ...parsed.value };
+        if (!(await this.#touch(key)))
+            return undefined;
+        this.#verified.set(key, project);
+        return project;
+    }
+    /**
+     * Return the entry for a request, building and publishing it when absent.
+     * Concurrent requests for one key share one Kuna run; the run is cancelled
+     * only when every waiting request has been cancelled.
+     */
+    async build(request) {
+        if (request.signal?.aborted === true)
+            return err(new AnalysisCancelledError(KUNA_EXPORT_OPERATION));
+        const key = kunaProjectKey({
+            targetSha256: request.targetSha256,
+            kunaSha256: request.installation.sha256,
+            kunaVersion: request.installation.version,
+            jobs: request.installation.configuration.jobs,
+        });
+        const running = this.#inflight.get(key);
+        // A build whose waiters all left is winding down; a new request starts afresh.
+        if (running !== undefined && !running.controller.signal.aborted)
+            return this.#await(running, request);
+        const controller = new AbortController();
+        const listeners = new Set();
+        // #produce reports its first status only after an await, once `created` exists.
+        const promise = this.#produce(key, request, controller.signal, (status) => {
+            created.status = status;
+            for (const listener of listeners)
+                listener(status);
+        });
+        const created = {
+            key,
+            promise,
+            controller,
+            listeners,
+            status: undefined,
+            waiters: 0,
+        };
+        this.#inflight.set(key, created);
+        this.#unfinished.add(created);
+        void promise.then(() => {
+            this.#unfinished.delete(created);
+            if (this.#inflight.get(key) === created)
+                this.#inflight.delete(key);
+            if (this.#unfinished.size === 0 && this.#capacity === "building")
+                this.#scheduleEviction();
+        });
+        return this.#await(created, request);
+    }
+    /**
+     * Wait until a build that every waiter abandoned has stopped its Kuna
+     * process and removed its staging. A build another request still waits for
+     * keeps running and is not awaited.
+     */
+    async settled(key) {
+        await Promise.allSettled([...this.#unfinished]
+            .filter((entry) => entry.key === key && entry.controller.signal.aborted)
+            .map((entry) => entry.promise));
+        await this.#retryProcesses((retained) => retained.key === key);
+        await this.#retryFiles(key);
+        return this.#cleanupResult(this.#retainedCleanupFailures(key));
+    }
+    /** Wait for builds, retry safe file removal, and report unresolved cleanup. */
+    async close() {
+        await Promise.allSettled([...this.#unfinished].map((entry) => entry.promise));
+        while (this.#maintenance !== undefined)
+            await this.#maintenance;
+        await this.#retryProcesses(() => true);
+        await this.#retryFiles();
+        return this.#cleanupResult(this.#retainedCleanupFailures());
+    }
+    /** Retry stopping retained process trees; retire the staging of each one proven stopped. */
+    async #retryProcesses(selected) {
+        for (const retained of this.#retainedProcesses.filter(selected)) {
+            const stopped = await retained.owner?.stop();
+            if (stopped === undefined || stopped.status === "incomplete")
+                continue;
+            this.#retainedProcesses.splice(this.#retainedProcesses.indexOf(retained), 1);
+            this.#resolveCleanupOwner(retained);
+            await this.#retireStaging(retained.staging, retained.key);
+        }
+    }
+    /** Retry only stopped file resources belonging to the closing task, or all. */
+    async #retryFiles(key) {
+        await this.#retryHashFiles(key);
+        for (const [path, retained] of [...this.#retainedFiles])
+            if (key === undefined || retained.key === key)
+                await this.#removeRetired(path).catch(() => undefined);
+    }
+    /** Retry retained hash descriptors before admitting another read for a key. */
+    async #retryHashFiles(key) {
+        const previous = this.#hashRetry;
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.#hashRetry = previous.then(() => current);
+        await previous;
+        try {
+            const staging = new Map();
+            for (const [owner, retained] of [...this.#retainedHashFiles]) {
+                if (key !== undefined && retained.key !== key)
+                    continue;
+                try {
+                    await retained.lease.release();
+                    this.#retainedHashFiles.delete(owner);
+                    this.#resolveCleanupOwner(owner);
+                    if (retained.staging !== null)
+                        staging.set(retained.staging, retained.key);
+                }
+                catch (cause) {
+                    const original = retained.originatingFailure;
+                    const closeFailure = new ProviderCleanupError(KUNA_PROVIDER_ID, [retained.resource], { reason: cause instanceof Error ? cause.message : String(cause) }, {
+                        operation: KUNA_EXPORT_OPERATION,
+                        cause: original === undefined
+                            ? cause
+                            : new AggregateError([original, cause], "Hash operation and descriptor cleanup both failed"),
+                    });
+                    retained.lastCloseFailure = closeFailure;
+                    this.#bindCleanupError(closeFailure, [
+                        owner,
+                        ...(retained.staging === null
+                            ? []
+                            : [this.#stagingCleanupOwner(retained.staging)]),
+                    ]);
+                }
+            }
+            for (const [path, retainedKey] of staging)
+                if (![...this.#retainedHashFiles.values()].some(({ staging: ownerStaging }) => ownerStaging === path))
+                    await this.#retireStaging(path, retainedKey);
+        }
+        finally {
+            release();
+        }
+    }
+    #hashCleanupFailures(key) {
+        return [...this.#retainedHashFiles.entries()]
+            .filter(([, retained]) => key === undefined || retained.key === key)
+            .flatMap(([owner, retained]) => {
+            const failure = retained.lastCloseFailure ?? retained.originatingFailure;
+            return failure === undefined
+                ? []
+                : [
+                    {
+                        error: failure,
+                        owners: [
+                            owner,
+                            ...(retained.staging === null
+                                ? []
+                                : [this.#stagingCleanupOwner(retained.staging)]),
+                        ],
+                    },
+                ];
+        });
+    }
+    #retainedCleanupFailures(key) {
+        return [
+            ...this.#retainedProcesses
+                .filter((retained) => key === undefined || retained.key === key)
+                .map((retained) => ({
+                error: retained.error,
+                owners: [retained, this.#stagingCleanupOwner(retained.staging)],
+            })),
+            ...[...this.#retainedFiles.values()]
+                .filter((retained) => key === undefined || retained.key === key)
+                .map((retained) => ({
+                error: retained.error,
+                owners: [retained.cleanupOwner],
+            })),
+            ...this.#hashCleanupFailures(key),
+        ];
+    }
+    #cleanupResult(failures) {
+        const result = cleanupResult(failures.map(({ error }) => error));
+        if (result.ok)
+            return result;
+        const owners = new Set(failures.flatMap(({ owners }) => owners));
+        this.#bindCleanupError(result.error, [...owners]);
+        return result;
+    }
+    #bindCleanupError(error, owners) {
+        this.#pruneCleanupErrorReports();
+        const report = this.#cleanupErrorReports.find((candidate) => candidate.error.deref() === error);
+        const pending = report?.pendingOwners ?? new Set();
+        for (const owner of owners)
+            pending.add(owner);
+        if (report === undefined && pending.size > 0)
+            this.#cleanupErrorReports.push({
+                error: new WeakRef(error),
+                pendingOwners: pending,
+            });
+    }
+    #fileCleanupOwner(path) {
+        return this.#retainedFiles.get(path)?.cleanupOwner ?? {};
+    }
+    #stagingCleanupOwner(path) {
+        let owner = this.#stagingCleanupOwners.get(path);
+        if (owner === undefined) {
+            owner = {};
+            this.#stagingCleanupOwners.set(path, owner);
+        }
+        return owner;
+    }
+    #resolveCleanupOwner(owner) {
+        for (const report of [...this.#cleanupErrorReports]) {
+            const error = report.error.deref();
+            if (error === undefined) {
+                this.#cleanupErrorReports.splice(this.#cleanupErrorReports.indexOf(report), 1);
+                continue;
+            }
+            report.pendingOwners.delete(owner);
+            if (report.pendingOwners.size === 0) {
+                error.resolveCleanup();
+                this.#cleanupErrorReports.splice(this.#cleanupErrorReports.indexOf(report), 1);
+            }
+        }
+    }
+    #transferCleanupOwner(from, to) {
+        this.#pruneCleanupErrorReports();
+        for (const report of this.#cleanupErrorReports)
+            if (report.pendingOwners.delete(from))
+                report.pendingOwners.add(to);
+    }
+    #pruneCleanupErrorReports() {
+        for (let index = this.#cleanupErrorReports.length - 1; index >= 0; index -= 1)
+            if (this.#cleanupErrorReports[index]?.error.deref() === undefined)
+                this.#cleanupErrorReports.splice(index, 1);
+    }
+    /**
+     * Move proven-stopped staging into trash and remove it. A failed removal
+     * stays owned as a file cleanup that close retries.
+     */
+    async #retireStaging(staging, key) {
+        let cleanupPath = staging;
+        const stagingOwner = this.#stagingCleanupOwners.get(staging);
+        try {
+            const retired = join(this.#root, "trash", `build-${randomUUID()}`);
+            await rename(staging, retired);
+            cleanupPath = retired;
+            await this.#removeRetired(retired, key);
+            if (stagingOwner !== undefined)
+                this.#resolveCleanupOwner(stagingOwner);
+            return undefined;
+        }
+        catch (cause) {
+            const failure = cause instanceof ProviderCleanupError
+                ? cause
+                : this.#retainFileCleanup(cleanupPath, cause, key);
+            if (stagingOwner !== undefined)
+                this.#transferCleanupOwner(stagingOwner, this.#fileCleanupOwner(cleanupPath));
+            return failure;
+        }
+        finally {
+            this.#stagingCleanupOwners.delete(staging);
+        }
+    }
+    #await(entry, request) {
+        entry.waiters += 1;
+        const onStatus = request.onStatus;
+        // Each waiter owns its registration, even when callers reuse a callback.
+        const listener = onStatus === undefined
+            ? undefined
+            : (status) => onStatus(status);
+        if (listener !== undefined)
+            entry.listeners.add(listener);
+        return new Promise((resolve) => {
+            let settled = false;
+            const leave = () => {
+                if (listener !== undefined)
+                    entry.listeners.delete(listener);
+                entry.waiters -= 1;
+            };
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                leave();
+                if (entry.waiters === 0)
+                    entry.controller.abort();
+                resolve(err(new AnalysisCancelledError(KUNA_EXPORT_OPERATION)));
+            };
+            request.signal?.addEventListener("abort", onAbort, { once: true });
+            void entry.promise.then((result) => {
+                request.signal?.removeEventListener("abort", onAbort);
+                if (settled)
+                    return;
+                settled = true;
+                leave();
+                resolve(result);
+            });
+            // Replay only once cancellation is registered, so a listener may abort.
+            if (listener !== undefined && entry.status !== undefined)
+                listener(entry.status);
+        });
+    }
+    async #produce(key, request, signal, onStatus) {
+        let staging;
+        try {
+            const existing = await this.lookup(key, signal);
+            if (existing !== undefined)
+                return ok(existing);
+            await Promise.all(["projects", "staging", "trash", "home"].map((name) => mkdir(join(this.#root, name), { recursive: true, mode: 0o700 })));
+            await this.#sweep(signal);
+            staging = await mkdtemp(join(this.#root, "staging", "build-"));
+        }
+        catch (cause) {
+            return err(kunaExportFailure(cause, signal));
+        }
+        const built = await this.#exportAndPublish(key, staging, request, signal, onStatus).catch((cause) => ({
+            result: err(kunaExportFailure(cause, signal)),
+            retainStaging: false,
+            ...(cause instanceof RegularFileCleanupFailure
+                ? { fileCleanupFailure: cause }
+                : {}),
+        }));
+        if (built.retainStaging)
+            return built.result;
+        const retainedStaging = [...this.#retainedHashFiles.values()].some((retained) => retained.staging === staging);
+        if (retainedStaging) {
+            if (!built.result.ok &&
+                built.result.error.cleanupIncomplete &&
+                built.fileCleanupFailure !== undefined)
+                this.#replaceHashCloseError(key, staging, built.result.error, built.fileCleanupFailure);
+            return built.result;
+        }
+        // Only a proven-stopped build may enter trash. A failed write, crash or
+        // lost cleanup identity therefore never makes live staging reclaimable.
+        const retired = await this.#retireStaging(staging, key);
+        if (retired !== undefined)
+            return err(retired);
+        if (built.result.ok)
+            // The entry is published either way; a failed eviction retries on the next publish.
+            await this.#evict(key).catch(() => undefined);
+        return built.result;
+    }
+    async #exportAndPublish(key, staging, request, signal, onStatus) {
+        const outcome = await exportKunaProject({
+            installation: request.installation,
+            targetPath: request.targetPath,
+            targetSha256: request.targetSha256,
+            workspace: staging,
+            output: join(staging, "entry", "project"),
+            signal,
+            onStatus,
+            launcher: this.#launcher,
+            retainFailedFileClose: (owner, resource) => this.#retainHashFile(owner, key, staging, resource),
+        });
+        if (outcome.kind === "retained") {
+            const retained = {
+                key,
+                error: outcome.error,
+                owner: outcome.owner,
+                staging,
+            };
+            this.#retainedProcesses.push(retained);
+            this.#bindCleanupError(outcome.error, [
+                retained,
+                this.#stagingCleanupOwner(staging),
+            ]);
+            return { result: err(outcome.error), retainStaging: true };
+        }
+        return {
+            result: outcome.result.ok
+                ? await this.#publish(key, staging, request, outcome.result.value, signal)
+                : outcome.result,
+            retainStaging: false,
+            ...(outcome.fileCleanupFailure === undefined
+                ? {}
+                : { fileCleanupFailure: outcome.fileCleanupFailure }),
+        };
+    }
+    /** Record the manifest and publish the staged export under its key. */
+    async #publish(key, staging, request, exported, signal) {
+        const manifest = {
+            layout: CACHE_LAYOUT,
+            key,
+            inputs: {
+                target_sha256: request.targetSha256,
+                kuna_sha256: request.installation.sha256,
+                kuna_version: request.installation.version,
+                jobs: request.installation.configuration.jobs,
+            },
+            files: exported.files,
+            summary: exported.summary,
+            created_at: new Date().toISOString(),
+        };
+        const total = manifestBytes(manifest);
+        if (total > this.#maxBytes)
+            return err(new AnalysisResourceConstraintError(KUNA_EXPORT_OPERATION, "capacity", `This export occupies ${String(total)} bytes, more than the whole Kuna cache may hold.`, { cache_max_bytes: this.#maxBytes, export_bytes: total }, {
+                remediationAction: "Raise REA_KUNA_CACHE_MAX_BYTES above the export size, or analyze this target with another provider.",
+            }));
+        await writeFileAtomic(join(staging, "entry", "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+        const destination = join(this.#root, "projects", key);
+        try {
+            await rename(join(staging, "entry"), destination);
+        }
+        catch (cause) {
+            if (!isPublishedByAnother(cause))
+                throw cause;
+            const winner = await this.lookup(key, signal);
+            if (winner !== undefined)
+                return ok(winner);
+            throw cause;
+        }
+        const project = {
+            key,
+            directory: join(destination, "project"),
+            manifest,
+            functions: exported.functions,
+            inventory: exported.inventory,
+        };
+        this.#verified.set(key, project);
+        return ok(project);
+    }
+    /**
+     * Remove retired resources only. Age and a missing marker cannot establish
+     * that a process stopped, so unresolved staging is never swept.
+     */
+    async #sweep(signal) {
+        for (const name of await readdir(join(this.#root, "trash"))) {
+            signal.throwIfAborted();
+            await this.#removeRetired(join(this.#root, "trash", name)).catch(() => undefined);
+        }
+    }
+    /** Evict least recently used entries above the cap, keeping pinned ones. */
+    #evict(keep) {
+        const eviction = this.#eviction.then(() => this.#evictUnpinned(keep));
+        this.#eviction = eviction.catch(() => undefined);
+        return eviction;
+    }
+    /** Coalesce deferred reclamation after callers have had a turn to pin results. */
+    #scheduleEviction() {
+        this.#maintenanceRequested = true;
+        if (this.#maintenance !== undefined)
+            return;
+        const maintenance = (async () => {
+            while (this.#maintenanceRequested) {
+                await new Promise((resolve) => setImmediate(resolve));
+                this.#maintenanceRequested = false;
+                await this.#evict(null).catch(() => undefined);
+            }
+        })();
+        this.#maintenance = maintenance;
+        void maintenance.then(() => {
+            if (this.#maintenance === maintenance)
+                this.#maintenance = undefined;
+            if (this.#maintenanceRequested)
+                this.#scheduleEviction();
+        });
+    }
+    async #evictUnpinned(keep) {
+        // A successful build must reach its callers before they can pin its entry.
+        // Protect every unfinished build while reading this eviction snapshot.
+        const building = new Set([...this.#unfinished].map(({ key }) => key));
+        const entries = [];
+        for (const name of await readdir(join(this.#root, "projects"))) {
+            if (!KEY_PATTERN.test(name))
+                continue;
+            const path = join(this.#root, "projects", name);
+            const status = await stat(path).catch(() => undefined);
+            if (status === undefined)
+                continue;
+            const manifest = await this.#readBounded(join(path, "manifest.json"))
+                .then(parseManifest)
+                .catch(() => undefined);
+            // An owned entry without a valid manifest is unusable; evict it first.
+            entries.push(manifest === undefined
+                ? { key: name, bytes: 0, mtimeMs: -1 }
+                : {
+                    key: name,
+                    bytes: manifestBytes(manifest),
+                    mtimeMs: status.mtimeMs,
+                });
+        }
+        let total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+        let deferredByBuild = false;
+        for (const entry of entries.sort((a, b) => a.mtimeMs - b.mtimeMs)) {
+            if (total <= this.#maxBytes && entry.mtimeMs >= 0)
+                break;
+            if (building.has(entry.key) || this.#inflight.has(entry.key)) {
+                deferredByBuild = true;
+                continue;
+            }
+            if (entry.key === keep || this.#pins.has(entry.key))
+                continue;
+            await this.#discard(entry.key);
+            total -= entry.bytes;
+        }
+        this.#capacity =
+            total <= this.#maxBytes
+                ? "within_limit"
+                : deferredByBuild
+                    ? "building"
+                    : "pinned";
+    }
+    /** Atomically retire one owned entry, then remove it. */
+    async #discard(key) {
+        this.#verified.delete(key);
+        const trash = join(this.#root, "trash", `${key}-${randomUUID()}`);
+        try {
+            await mkdir(join(this.#root, "trash"), { recursive: true, mode: 0o700 });
+            await rename(join(this.#root, "projects", key), trash);
+        }
+        catch (cause) {
+            if (isMissing(cause))
+                return;
+            throw cause;
+        }
+        await this.#removeRetired(trash, key);
+    }
+    /** Keep each failed removal owned until that path is successfully removed. */
+    async #removeRetired(path, key) {
+        try {
+            await rm(path, { recursive: true, force: true });
+            const retained = this.#retainedFiles.get(path);
+            this.#retainedFiles.delete(path);
+            if (retained !== undefined)
+                this.#resolveCleanupOwner(retained.cleanupOwner);
+        }
+        catch (cause) {
+            throw this.#retainFileCleanup(path, cause, key);
+        }
+    }
+    /** Mark an entry recently used; false when it is no longer published. */
+    async #touch(key) {
+        const now = new Date();
+        try {
+            await utimes(join(this.#root, "projects", key), now, now);
+            return true;
+        }
+        catch (cause) {
+            // Recency is advisory; only a missing entry changes the answer.
+            return !isMissing(cause);
+        }
+    }
+    async #readBounded(path) {
+        const status = await stat(path);
+        if (status.size > MANIFEST_MAX_BYTES)
+            throw new RangeError(`${path} exceeds ${String(MANIFEST_MAX_BYTES)} bytes`);
+        return readFile(path, "utf8");
+    }
+    #retainFileCleanup(path, cause, key) {
+        const error = new ProviderCleanupError(KUNA_PROVIDER_ID, [path], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation: KUNA_EXPORT_OPERATION, cause });
+        const retained = {
+            key: key ?? this.#retainedFiles.get(path)?.key ?? null,
+            error,
+            cleanupOwner: this.#retainedFiles.get(path)?.cleanupOwner ?? {},
+        };
+        this.#retainedFiles.set(path, retained);
+        this.#bindCleanupError(error, [retained.cleanupOwner]);
+        return error;
+    }
+    #retainHashFile(owner, key, staging, resource) {
+        const retained = {
+            key,
+            staging,
+            resource,
+            lease: new AnalysisCleanupLease(async () => owner.close(), [resource]),
+        };
+        this.#hashRecords.set(owner, retained);
+        this.#retainedHashFiles.set(owner, retained);
+    }
+    #replaceHashCloseError(key, staging, failure, fileCleanupFailure) {
+        const owner = fileCleanupFailure.owner;
+        const retained = this.#hashRecords.get(owner);
+        if (retained !== undefined) {
+            retained.lease.bindCleanupError(failure);
+            if (retained.key === key && retained.staging === staging)
+                retained.originatingFailure ??= failure;
+        }
+        return failure;
+    }
+}
+/** One cleanup error aggregating what remains owned, or success when nothing does. */
+const cleanupResult = (remaining) => {
+    if (remaining.length === 0)
+        return ok(null);
+    return err(new ProviderCleanupError(KUNA_PROVIDER_ID, remaining.flatMap((entry) => entry.cleanupResources), {
+        reason: remaining
+            .map((entry) => String(entry.diagnostics?.["reason"] ?? entry.message))
+            .join("; "),
+    }, {
+        operation: KUNA_EXPORT_OPERATION,
+        cause: new AggregateError(remaining, "Kuna cache cleanup is incomplete"),
+    }));
+};