@timurproko/a1 0.1.8-dev.50ebb19 → 0.1.8-dev.512

package/dist/foundation/release/release-gc.js

@@ -0,0 +1,764 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CohortStateStore, planProtectedReleases, } from "./cohort-state.js";
+import { liveReleaseIds } from "./endpoints.js";
+import { resolveProductPaths } from "../lifecycle/index.js";
+import { RELEASE_MANIFEST_FILENAME } from "./release-store.js";
+import { DEPENDENCY_LAYER_MANIFEST, readCertifiedDependencyLayer } from "./dependency-layer.js";
+import { dependencyCertificationDirectory, managedDependencyCertificationPath } from "./dependency-certification.js";
+import { dependencyCertificationProtection } from "./dependency-certification-retention.js";
+import { UpdateTransactionStore } from "./update-transaction.js";
+import { cleanupUpdateRecoveryCapsules } from "./update-recovery.js";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { collectCompileCaches, startupCompileCachePath } from "../startup/index.js";
+const DEFAULT_CANDIDATE_AGE_MS = 60 * 60 * 1_000;
+const DEFAULT_LIMITS = { maxItems: 8, maxDurationMs: 2_000, concurrency: 1 };
+const DEFAULT_WORKER_DURATION_MS = 10 * 60 * 1_000;
+const DEFAULT_NO_PROGRESS_BATCHES = 5;
+const DEFAULT_RETRY_DELAY_MS = 500;
+const WORKER_HOLDS_ENV = "RELEASE_CLEANUP_HOLDS";
+const WORKER_RUN_ID_ENV = "RELEASE_CLEANUP_RUN_ID";
+const WORKER_LEASE_FILENAME = "release-cleanup-worker.lock";
+/**
+ * Reconcile current ownership under the cohort-state lock and durably detach obsolete releases.
+ * This operation intentionally reads only manifests and directory metadata, never payload bytes.
+ */
+export async function prepareReleaseCleanup(dataDir, paths, options = {}) {
+    const store = new CohortStateStore(dataDir);
+    const discovered = await discoverCleanupInputs(dataDir, store, options);
+    const transactionStore = options.transactionStore ?? new UpdateTransactionStore(dataDir);
+    await store.reconcileRetention(async () => await protectionInputs(paths, transactionStore, options.externalHolds ?? []), discovered.orphans);
+    for (const diagnostic of discovered.diagnostics.slice(0, 16)) {
+        await store.recordCleanupFailure(diagnostic.releaseId, diagnostic.stage, diagnostic.error);
+    }
+    return { store, discovered };
+}
+/** Run a bounded, restart-safe physical cleanup pass over detached releases and abandoned artifacts. */
+export async function runBoundedReleaseCleanup(dataDir, paths, options = {}) {
+    const now = options.now ?? Date.now;
+    const limits = normalizeLimits(options.limits);
+    const { store, discovered } = await prepareReleaseCleanup(dataDir, paths, options);
+    // Performance: The physical-work allowance begins after discovery, ownership probes, and the
+    // durable reconciliation write. A slow preparation phase must not starve every worker invocation.
+    const startedAt = now();
+    const initial = await store.read();
+    const pending = sortCleanupDispositions(Object.values(initial.cleanup.pending));
+    const transactionStore = options.transactionStore ?? new UpdateTransactionStore(dataDir);
+    const transaction = await transactionStore.read();
+    const activeTransaction = transaction?.status === "active";
+    const artifacts = sortArtifacts([
+        ...(!activeTransaction ? discovered.candidates : []),
+        ...discovered.unmanagedTrash,
+        ...discovered.certifications,
+    ], initial);
+    let attempted = 0;
+    let completed = 0;
+    let pendingOffset = 0;
+    let artifactOffset = 0;
+    const hasTime = (guaranteed = false) => guaranteed || attempted === 0 || now() - startedAt < limits.maxDurationMs;
+    const attemptPending = async (maximum, guaranteed = false) => {
+        while (pendingOffset < pending.length && attempted < limits.maxItems && maximum > 0 && hasTime(guaranteed)) {
+            const size = Math.min(limits.concurrency, maximum, limits.maxItems - attempted, pending.length - pendingOffset);
+            const batch = pending.slice(pendingOffset, pendingOffset + size);
+            pendingOffset += size;
+            maximum -= size;
+            attempted += batch.length;
+            const results = await Promise.all(batch.map(async (disposition) => await collectDisposition(store, dataDir, paths, disposition, options)));
+            completed += results.filter(Boolean).length;
+            guaranteed = false;
+        }
+    };
+    const attemptArtifacts = async (maximum, guaranteed = false) => {
+        while (artifactOffset < artifacts.length && attempted < limits.maxItems && maximum > 0 && hasTime(guaranteed)) {
+            const artifact = artifacts[artifactOffset++];
+            maximum -= 1;
+            const certificationId = certificationReleaseId(artifact);
+            if (certificationId !== null) {
+                const inputs = await protectionInputs(paths, transactionStore, options.externalHolds ?? []);
+                if (isProtectedDetachedRelease(await store.read(), inputs, certificationId))
+                    continue;
+            }
+            attempted += 1;
+            try {
+                await removeAbandonedArtifact(dataDir, artifact, options.operations);
+                completed += 1;
+            }
+            catch (error) {
+                await store.recordCleanupFailure(artifactName(artifact), "artifact-delete", error);
+            }
+            guaranteed = false;
+        }
+    };
+    // Concurrency: Give each available class one opportunity before filling the batch. This keeps
+    // a locked release or a large release backlog from indefinitely starving candidates and evidence.
+    if (pending.length > 0)
+        await attemptPending(1, true);
+    if (artifacts.length > 0 && attempted < limits.maxItems)
+        await attemptArtifacts(1, true);
+    if (!activeTransaction && attempted < limits.maxItems) {
+        const layerResult = await collectUnreferencedDependencyLayers(store, dataDir, 1, options);
+        attempted += layerResult.attempted;
+        completed += layerResult.completed;
+    }
+    while (attempted < limits.maxItems && hasTime()) {
+        const before = attempted;
+        await attemptPending(1);
+        if (attempted < limits.maxItems)
+            await attemptArtifacts(1);
+        if (attempted === before)
+            break;
+    }
+    if (!activeTransaction && attempted < limits.maxItems && hasTime()) {
+        const layerResult = await collectUnreferencedDependencyLayers(store, dataDir, limits.maxItems - attempted, options);
+        attempted += layerResult.attempted;
+        completed += layerResult.completed;
+    }
+    if (!activeTransaction && hasTime()) {
+        await collectCompileCaches(dataDir, await protectedCompileCachePaths(dataDir, await store.read())).catch(() => { });
+        await cleanupUpdateRecoveryCapsules(dataDir).catch(() => { });
+    }
+    const remaining = Object.keys((await store.read()).cleanup.pending).length;
+    return { planned: pending.length + artifacts.length, attempted, completed, remaining, durationMs: Math.max(0, now() - startedAt) };
+}
+/**
+ * Commit cleanup intent synchronously, then let a dependency-light detached worker perform
+ * potentially slow recursive deletion. A later launch/update resumes work if spawning fails.
+ */
+export async function scheduleReleaseCleanup(dataDir, paths, options = {}) {
+    const { store } = await prepareReleaseCleanup(dataDir, paths, options);
+    const runId = randomUUID();
+    await store.recordCleanupWorkerScheduled(runId);
+    const entry = fileURLToPath(new URL("../../../bin/release-cleanup.js", import.meta.url));
+    const environment = {
+        ...process.env,
+        [PRODUCT_IDENTITY.environment.dataDir]: dataDir,
+        [PRODUCT_IDENTITY.environment.runtimeDir]: paths.runtimeDir,
+        [WORKER_HOLDS_ENV]: JSON.stringify(options.externalHolds ?? []),
+        [WORKER_RUN_ID_ENV]: runId,
+    };
+    try {
+        await (options.workerSpawner ?? spawnCleanupWorker)(entry, environment);
+    }
+    catch (error) {
+        const summary = { batches: 0, attempted: 0, completed: 0, remaining: Object.keys((await store.read()).cleanup.pending).length };
+        await store.recordCleanupWorkerFinished(runId, "failed", summary, error);
+        await store.recordCleanupFailure("worker", "spawn", error);
+    }
+}
+/** Entry used by the private cleanup executable shipped in every immutable release. */
+export async function runReleaseCleanupWorker(environment = process.env, workerOptions = {}) {
+    const paths = resolveProductPaths(environment);
+    const store = new CohortStateStore(paths.dataDir);
+    const runId = environment[WORKER_RUN_ID_ENV] ?? randomUUID();
+    const now = workerOptions.now ?? Date.now;
+    const sleep = workerOptions.sleep ?? (async (durationMs) => await new Promise(resolvePromise => setTimeout(resolvePromise, durationMs)));
+    const cleanupOptions = {
+        ...workerOptions.cleanup,
+        externalHolds: workerOptions.cleanup?.externalHolds ?? parseWorkerHolds(environment[WORKER_HOLDS_ENV]),
+    };
+    const summary = { batches: 0, attempted: 0, completed: 0, remaining: Object.keys((await store.read()).cleanup.pending).length };
+    let lease = null;
+    let continuation = false;
+    let status = "completed";
+    let failure = null;
+    const startedAt = now();
+    try {
+        lease = await acquireWorkerLease(paths.dataDir, runId);
+        if (lease === null) {
+            status = "skipped";
+            failure = "another release cleanup worker owns the data root";
+            return { planned: 0, attempted: 0, completed: 0, remaining: summary.remaining, durationMs: 0 };
+        }
+        await store.recordCleanupWorkerStarted(runId, process.pid);
+        let noProgressBatches = 0;
+        while (true) {
+            const result = await runBoundedReleaseCleanup(paths.dataDir, paths, cleanupOptions);
+            summary.batches += 1;
+            summary.attempted += result.attempted;
+            summary.completed += result.completed;
+            summary.remaining = result.remaining;
+            await store.recordCleanupWorkerProgress(runId, summary);
+            if (result.attempted === 0)
+                break;
+            if (result.completed === 0) {
+                noProgressBatches += 1;
+                if (noProgressBatches >= (workerOptions.maxNoProgressBatches ?? DEFAULT_NO_PROGRESS_BATCHES)) {
+                    status = "blocked";
+                    failure = "cleanup made no progress within its bounded retry allowance";
+                    break;
+                }
+                await sleep((workerOptions.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS) * (2 ** (noProgressBatches - 1)));
+            }
+            else {
+                noProgressBatches = 0;
+            }
+            if (now() - startedAt >= (workerOptions.maxDurationMs ?? DEFAULT_WORKER_DURATION_MS)) {
+                status = "continued";
+                continuation = true;
+                break;
+            }
+        }
+    }
+    catch (error) {
+        status = "failed";
+        failure = error;
+    }
+    finally {
+        if (lease !== null)
+            await releaseWorkerLease(paths.dataDir, runId, lease);
+        await store.recordCleanupWorkerFinished(runId, status, summary, failure);
+    }
+    if (continuation) {
+        await (workerOptions.continueWorker ?? scheduleReleaseCleanup)(paths.dataDir, paths, cleanupOptions).catch(async (error) => {
+            await store.recordCleanupFailure("worker", "continuation", error);
+        });
+    }
+    if (status === "failed")
+        throw failure instanceof Error ? failure : new Error(errorMessage(failure));
+    return {
+        planned: summary.remaining + summary.completed,
+        attempted: summary.attempted,
+        completed: summary.completed,
+        remaining: summary.remaining,
+        durationMs: Math.max(0, now() - startedAt),
+    };
+}
+/** Compatibility helper: detach one requested release and execute a one-item pass. */
+export async function collectRelease(store, dataDir, releaseId, externalReferences, paths) {
+    const holds = externalReferences.map(referenced => ({ authority: "migration", releaseId: referenced }));
+    const state = await store.read();
+    if (!state.releases[releaseId])
+        throw new Error(`unknown release ${releaseId}`);
+    await store.reconcileRetention(async () => ({ ...(await protectionInputs(paths, new UpdateTransactionStore(dataDir), holds)) }));
+    const disposition = (await store.read()).cleanup.pending[releaseId];
+    if (!disposition)
+        throw new Error(`release ${releaseId} is still referenced and cannot be collected`);
+    const removed = await collectDisposition(store, dataDir, paths, disposition, { externalHolds: holds, limits: { maxItems: 1 } });
+    if (!removed)
+        throw new Error(`release ${releaseId} could not be collected`);
+}
+async function collectDisposition(store, dataDir, paths, disposition, options) {
+    const releaseId = disposition.release.releaseId;
+    try {
+        const inputs = await protectionInputs(paths, options.transactionStore ?? new UpdateTransactionStore(dataDir), options.externalHolds ?? []);
+        const current = await store.read();
+        if (isProtectedDetachedRelease(current, inputs, releaseId))
+            return false;
+        const storeRoot = await canonicalReleaseStore(dataDir);
+        const trashRoot = await canonicalTrashRoot(storeRoot);
+        let trashPath = disposition.trashPath;
+        if (disposition.stage === "detached") {
+            const source = resolve(storeRoot, releaseId);
+            const sourceMetadata = await lstat(source).catch(error => missingOrThrow(error));
+            if (sourceMetadata === null) {
+                trashPath = await findReleaseTrash(trashRoot, releaseId);
+                if (trashPath === null) {
+                    await removeCertificationEvidence(dataDir, disposition.release, store);
+                    await store.completeCleanup(releaseId);
+                    return true;
+                }
+            }
+            else {
+                await assertReleaseDirectory(source, storeRoot, disposition.release, releaseId);
+                trashPath = resolve(trashRoot, `${releaseId}--${randomUUID()}`);
+                await (options.operations?.rename ?? rename)(source, trashPath);
+            }
+            await store.markCleanupTrash(releaseId, trashPath);
+        }
+        if (trashPath === null)
+            throw new Error(`release ${releaseId} has no managed trash path`);
+        await assertReleaseDirectory(trashPath, trashRoot, disposition.release, `${releaseId}--`);
+        await (options.operations?.remove ?? rm)(trashPath, { recursive: true, force: false, maxRetries: 0 });
+        await removeCertificationEvidence(dataDir, disposition.release, store);
+        await store.completeCleanup(releaseId);
+        return true;
+    }
+    catch (error) {
+        await store.recordCleanupFailure(releaseId, disposition.stage, error);
+        return false;
+    }
+}
+function isProtectedDetachedRelease(state, inputs, releaseId) {
+    const selected = [state.references.active, state.references.pending, state.references.approved, state.references.rollback]
+        .some(reference => reference === releaseId);
+    return selected
+        || (inputs.liveReleaseIds ?? []).includes(releaseId)
+        || (inputs.externalHolds ?? []).some(hold => hold.releaseId === releaseId)
+        || (inputs.transaction?.status === "active" && inputs.transaction.priorActiveReleaseId === releaseId);
+}
+async function protectionInputs(paths, transactionStore, externalHolds) {
+    const [liveIds, transaction] = await Promise.all([
+        paths ? liveReleaseIds(paths) : Promise.resolve([]),
+        transactionStore.read(),
+    ]);
+    return { liveReleaseIds: liveIds, externalHolds, transaction: transactionReference(transaction) };
+}
+function transactionReference(transaction) {
+    return transaction === null ? null : { status: transaction.status, priorActiveReleaseId: transaction.priorActiveReleaseId };
+}
+async function discoverCleanupInputs(dataDir, store, options) {
+    const releaseRoot = resolve(dataDir, "releases");
+    await mkdir(releaseRoot, { recursive: true, mode: 0o700 });
+    const state = await store.read();
+    const orphans = [];
+    const candidates = [];
+    const unmanagedTrash = [];
+    const certifications = [];
+    const diagnostics = [];
+    const candidateAgeMs = options.candidateAgeMs ?? DEFAULT_CANDIDATE_AGE_MS;
+    const now = options.now ?? Date.now;
+    for (const entry of await readdir(releaseRoot, { withFileTypes: true })) {
+        const path = resolve(releaseRoot, entry.name);
+        if (entry.name === ".trash")
+            continue;
+        if (entry.name.startsWith(".candidate-")) {
+            try {
+                const metadata = await lstat(path);
+                if (metadata.isDirectory() && !metadata.isSymbolicLink() && now() - metadata.mtimeMs >= candidateAgeMs)
+                    candidates.push(path);
+            }
+            catch (error) {
+                diagnostics.push({ releaseId: entry.name, stage: "candidate-discovery", error: errorMessage(error) });
+            }
+            continue;
+        }
+        if (state.releases[entry.name] || state.cleanup.pending[entry.name])
+            continue;
+        try {
+            const release = await readReleaseRecord(path, releaseRoot, entry.name, dataDir);
+            orphans.push({ release, stage: "detached" });
+        }
+        catch (error) {
+            diagnostics.push({ releaseId: entry.name, stage: "orphan-discovery", error: errorMessage(error) });
+        }
+    }
+    const trashRoot = resolve(releaseRoot, ".trash");
+    const trashMetadata = await lstat(trashRoot).catch(error => missingOrThrow(error));
+    if (trashMetadata !== null) {
+        if (!trashMetadata.isDirectory() || trashMetadata.isSymbolicLink()) {
+            diagnostics.push({ releaseId: ".trash", stage: "trash-discovery", error: "managed trash is not a direct non-link directory" });
+        }
+        else {
+            for (const entry of await readdir(trashRoot, { withFileTypes: true })) {
+                const path = resolve(trashRoot, entry.name);
+                const releaseId = entry.name.split("--", 1)[0];
+                if (entry.name.startsWith(".candidate--")) {
+                    unmanagedTrash.push(path);
+                }
+                else if (entry.name.includes("--") && !state.cleanup.pending[releaseId]) {
+                    try {
+                        const release = await readReleaseRecord(path, trashRoot, `${releaseId}--`, dataDir);
+                        orphans.push({ release, stage: "trash", trashPath: path });
+                    }
+                    catch (error) {
+                        diagnostics.push({ releaseId, stage: "trash-discovery", error: errorMessage(error) });
+                    }
+                }
+            }
+        }
+    }
+    for (const entry of await readdir(dataDir, { withFileTypes: true })) {
+        const match = /^certification-(.+)\.json$/.exec(entry.name);
+        if (!match || !entry.isFile())
+            continue;
+        const releaseId = match[1];
+        if (!state.releases[releaseId] && !state.cleanup.pending[releaseId] && !orphans.some(orphan => orphan.release.releaseId === releaseId)) {
+            certifications.push(resolve(dataDir, entry.name));
+        }
+    }
+    return { orphans, candidates, unmanagedTrash, certifications, diagnostics };
+}
+async function readReleaseRecord(path, parent, expectedName, dataDir) {
+    const metadata = await lstat(path);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error("release path is not a non-link directory");
+    const [canonicalParent, canonicalPath] = await Promise.all([realpath(parent), realpath(path)]);
+    assertDirectChild(canonicalParent, canonicalPath);
+    const name = canonicalPath.split(sep).at(-1) ?? "";
+    if (expectedName.endsWith("--") ? !name.startsWith(expectedName) : name !== expectedName)
+        throw new Error("release directory name does not match its disposition");
+    const manifest = JSON.parse(await readFile(resolve(canonicalPath, RELEASE_MANIFEST_FILENAME), "utf8"));
+    if (typeof manifest.releaseId !== "string" || !/^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/.test(manifest.releaseId)
+        || typeof manifest.packageVersion !== "string" || typeof manifest.contentDigest !== "string"
+        || !/^[a-f0-9]{64}$/.test(manifest.contentDigest) || !name.startsWith(manifest.releaseId)) {
+        throw new Error("release manifest identity is invalid for cleanup");
+    }
+    return {
+        releaseId: manifest.releaseId,
+        releaseRoot: resolve(parent, manifest.releaseId),
+        packageVersion: manifest.packageVersion,
+        contentDigest: manifest.contentDigest,
+        approval: "approved",
+        materializedAt: new Date(0).toISOString(),
+        certifiedAt: null,
+        diagnosticsPath: resolve(dataDir, `certification-${manifest.releaseId}.json`),
+    };
+}
+async function assertReleaseDirectory(path, parent, release, expectedName) {
+    const metadata = await lstat(path);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error(`refused cleanup of linked or non-directory release ${release.releaseId}`);
+    const [canonicalParent, canonicalPath] = await Promise.all([realpath(parent), realpath(path)]);
+    assertDirectChild(canonicalParent, canonicalPath);
+    const name = canonicalPath.split(sep).at(-1) ?? "";
+    if (expectedName.endsWith("--") ? !name.startsWith(expectedName) : name !== expectedName)
+        throw new Error(`release directory does not match identity ${release.releaseId}`);
+    if (!expectedName.endsWith("--") && canonicalPath !== await realpath(release.releaseRoot))
+        throw new Error(`recorded release path differs from managed identity ${release.releaseId}`);
+    const manifest = JSON.parse(await readFile(resolve(canonicalPath, RELEASE_MANIFEST_FILENAME), "utf8"));
+    if (manifest.releaseId !== release.releaseId || manifest.contentDigest !== release.contentDigest || manifest.packageVersion !== release.packageVersion) {
+        throw new Error(`release manifest metadata differs from detached record ${release.releaseId}`);
+    }
+}
+async function removeCertificationEvidence(dataDir, release, store) {
+    if (release.diagnosticsPath === null)
+        return;
+    // Security: the persisted path is historical metadata, not deletion authority. Derive the
+    // only permitted target from validated identity so Windows casing changes cannot strand it.
+    const expected = resolve(dataDir, `certification-${release.releaseId}.json`);
+    const metadata = await lstat(expected).catch(error => missingOrThrow(error));
+    if (metadata === null)
+        return;
+    if (!metadata.isFile() || metadata.isSymbolicLink()) {
+        await store.recordCleanupFailure(release.releaseId, "certification", "refused to delete linked or non-file certification evidence");
+        return;
+    }
+    const [canonicalDataDir, canonicalEvidence] = await Promise.all([realpath(dataDir), realpath(expected)]);
+    assertDirectChild(canonicalDataDir, canonicalEvidence);
+    if (artifactName(canonicalEvidence) !== `certification-${release.releaseId}.json`) {
+        await store.recordCleanupFailure(release.releaseId, "certification", "refused to delete certification evidence with a different managed identity");
+        return;
+    }
+    await rm(canonicalEvidence, { force: true });
+}
+async function canonicalReleaseStore(dataDir) {
+    const root = resolve(dataDir, "releases");
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const metadata = await lstat(root);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error("release store is not a non-link directory");
+    return await realpath(root);
+}
+async function canonicalTrashRoot(storeRoot) {
+    const root = resolve(storeRoot, ".trash");
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const metadata = await lstat(root);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error("managed release trash is not a non-link directory");
+    const canonical = await realpath(root);
+    assertDirectChild(storeRoot, canonical);
+    return canonical;
+}
+async function findReleaseTrash(trashRoot, releaseId) {
+    const names = (await readdir(trashRoot)).filter(name => name.startsWith(`${releaseId}--`)).sort();
+    return names.length === 0 ? null : resolve(trashRoot, names[0]);
+}
+async function removeAbandonedArtifact(dataDir, path, operations) {
+    const storeRoot = await canonicalReleaseStore(dataDir);
+    const metadata = await lstat(path);
+    if (metadata.isSymbolicLink())
+        throw new Error("abandoned artifact is a link");
+    const canonical = await realpath(path);
+    const parent = dirname(canonical);
+    const canonicalDataDir = await realpath(dataDir);
+    if (parent === canonicalDataDir && certificationReleaseId(canonical) !== null && metadata.isFile()) {
+        await (operations?.remove ?? rm)(canonical, { force: true });
+        return;
+    }
+    if (!metadata.isDirectory())
+        throw new Error("abandoned artifact is not a managed directory or certification file");
+    if (parent === storeRoot && canonical.split(sep).at(-1)?.startsWith(".candidate-")) {
+        const trashRoot = await canonicalTrashRoot(storeRoot);
+        const moved = resolve(trashRoot, `.candidate--${randomUUID()}`);
+        await (operations?.rename ?? rename)(canonical, moved);
+        await (operations?.remove ?? rm)(moved, { recursive: true, force: false, maxRetries: 0 });
+        return;
+    }
+    const trashRoot = await canonicalTrashRoot(storeRoot);
+    if (parent === trashRoot && canonical.split(sep).at(-1)?.startsWith(".candidate--")) {
+        await (operations?.remove ?? rm)(canonical, { recursive: true, force: false, maxRetries: 0 });
+        return;
+    }
+    throw new Error("abandoned artifact is outside managed candidate, trash, or certification paths");
+}
+async function collectUnreferencedDependencyLayers(store, dataDir, maxItems, options) {
+    const transactionStore = options.transactionStore ?? new UpdateTransactionStore(dataDir);
+    if ((await transactionStore.read())?.status === "active")
+        return { attempted: 0, completed: 0 };
+    const protection = await dependencyCertificationProtection(dataDir, Object.keys((await store.read()).releases));
+    if (protection.uncertain)
+        return { attempted: 0, completed: 0 };
+    const { referenced } = protection;
+    const layersRoot = resolve(dataDir, "dependency-layers");
+    const layersMetadata = await lstat(layersRoot).catch(error => missingOrThrow(error));
+    if (layersMetadata === null)
+        return await collectDependencyCertificationRecords(store, dataDir, protection, maxItems, options);
+    if (!layersMetadata.isDirectory() || layersMetadata.isSymbolicLink())
+        throw new Error("dependency-layer store is not a managed directory");
+    const trashRoot = resolve(layersRoot, ".trash");
+    await mkdir(trashRoot, { recursive: true, mode: 0o700 });
+    let attempted = 0;
+    let completed = 0;
+    const entries = await readdir(layersRoot, { withFileTypes: true });
+    const candidates = [];
+    for (const entry of entries) {
+        if (entry.name === ".trash")
+            continue;
+        const path = resolve(layersRoot, entry.name);
+        if (entry.name.startsWith(".candidate-")) {
+            const metadata = await lstat(path);
+            const currentTime = options.now?.() ?? Date.now();
+            if (currentTime - metadata.mtimeMs >= (options.candidateAgeMs ?? DEFAULT_CANDIDATE_AGE_MS)) {
+                candidates.push({ path, layerId: null, inTrash: false });
+            }
+            continue;
+        }
+        if (!referenced.has(entry.name))
+            candidates.push({ path, layerId: entry.name, inTrash: false });
+    }
+    for (const entry of await readdir(trashRoot, { withFileTypes: true })) {
+        candidates.push({ path: resolve(trashRoot, entry.name), layerId: entry.name.split("--", 1)[0] ?? null, inTrash: true });
+    }
+    const certificates = await collectDependencyCertificationRecords(store, dataDir, protection, Math.min(1, maxItems), options);
+    attempted += certificates.attempted;
+    completed += certificates.completed;
+    for (const candidate of candidates.slice(0, maxItems - attempted)) {
+        if ((await transactionStore.read())?.status === "active")
+            break;
+        if (candidate.layerId !== null && referenced.has(candidate.layerId))
+            continue;
+        attempted += 1;
+        try {
+            const metadata = await lstat(candidate.path);
+            if (!metadata.isDirectory() || metadata.isSymbolicLink())
+                throw new Error("dependency-layer cleanup candidate is not a non-link directory");
+            let removalPath = candidate.path;
+            if (!candidate.inTrash) {
+                const canonicalRoot = await realpath(layersRoot);
+                const canonical = await realpath(candidate.path);
+                assertDirectChild(canonicalRoot, canonical);
+                if (candidate.layerId !== null) {
+                    const manifest = JSON.parse(await readFile(resolve(canonical, DEPENDENCY_LAYER_MANIFEST), "utf8"));
+                    if (manifest.layerId !== candidate.layerId || typeof manifest.contentDigest !== "string")
+                        throw new Error("dependency-layer manifest does not match its directory");
+                }
+                removalPath = resolve(trashRoot, `${candidate.layerId ?? ".candidate"}--${randomUUID()}`);
+                await (options.operations?.rename ?? rename)(canonical, removalPath);
+            }
+            else {
+                const canonicalTrash = await realpath(trashRoot);
+                assertDirectChild(canonicalTrash, await realpath(removalPath));
+            }
+            await (options.operations?.remove ?? rm)(removalPath, { recursive: true, force: false, maxRetries: 0 });
+            if (candidate.layerId !== null && /^dependencies-[a-f0-9]{32}$/.test(candidate.layerId)) {
+                for (const legacy of [false, true]) {
+                    const certificate = await managedDependencyCertificationPath(dataDir, candidate.layerId, legacy);
+                    if (certificate !== null)
+                        await (options.operations?.remove ?? rm)(certificate, { force: true });
+                }
+            }
+            completed += 1;
+        }
+        catch (error) {
+            // Platform: the pass is retry based, so a sharing violation leaves managed trash.
+            await store.recordCleanupFailure(candidate.layerId ?? artifactName(candidate.path), "dependency-layer-delete", error);
+        }
+    }
+    if (attempted < maxItems) {
+        const remaining = await collectDependencyCertificationRecords(store, dataDir, protection, maxItems - attempted, options);
+        attempted += remaining.attempted;
+        completed += remaining.completed;
+    }
+    return { attempted, completed };
+}
+async function collectDependencyCertificationRecords(store, dataDir, protection, maxItems, options) {
+    const candidates = new Map();
+    for (const entry of await readdir(dataDir, { withFileTypes: true })) {
+        const match = /^dependency-layer-certification-(dependencies-[a-f0-9]{32})\.json$/.exec(entry.name);
+        if (match && entry.isFile())
+            candidates.set(resolve(dataDir, entry.name), { layerId: match[1], legacy: true });
+    }
+    try {
+        const directory = await dependencyCertificationDirectory(dataDir);
+        if (directory !== null) {
+            for (const entry of await readdir(directory, { withFileTypes: true })) {
+                const match = /^(dependencies-[a-f0-9]{32})\.json$/.exec(entry.name);
+                if (match && entry.isFile())
+                    candidates.set(resolve(directory, entry.name), { layerId: match[1], legacy: false });
+            }
+        }
+    }
+    catch (error) {
+        await store.recordCleanupFailure("dependency-certifications", "certification-discovery", error);
+        return { attempted: 0, completed: 0 };
+    }
+    const transactionStore = options.transactionStore ?? new UpdateTransactionStore(dataDir);
+    let attempted = 0;
+    let completed = 0;
+    for (const candidate of sortArtifacts([...candidates.keys()], await store.read())) {
+        if (attempted >= maxItems || (await transactionStore.read())?.status === "active")
+            break;
+        const { layerId, legacy } = candidates.get(candidate);
+        if (legacy ? protection.legacyRequired.has(layerId) : protection.referenced.has(layerId))
+            continue;
+        const layerExists = await lstat(resolve(dataDir, "dependency-layers", layerId)).catch(missingOrThrow) !== null;
+        if (!legacy && layerExists)
+            continue;
+        try {
+            if (legacy && (layerExists || protection.referenced.has(layerId))) {
+                // Security: a duplicate is disposable only with validated canonical evidence, never fallback.
+                await readCertifiedDependencyLayer(dataDir, layerId, undefined, { canonicalOnly: true });
+            }
+            attempted += 1;
+            const path = await managedDependencyCertificationPath(dataDir, layerId, legacy);
+            if (path !== null)
+                await (options.operations?.remove ?? rm)(path, { force: true });
+            completed += 1;
+        }
+        catch (error) {
+            await store.recordCleanupFailure(artifactName(candidate), "dependency-layer-certification", error);
+        }
+    }
+    return { attempted, completed };
+}
+async function protectedCompileCachePaths(dataDir, state) {
+    const paths = [];
+    for (const release of Object.values(state.releases)) {
+        try {
+            const manifest = JSON.parse(await readFile(resolve(release.releaseRoot, RELEASE_MANIFEST_FILENAME), "utf8"));
+            const layers = (manifest.dependencyLayers ?? []).map(layer => layer.layerId).filter((id) => typeof id === "string");
+            paths.push(startupCompileCachePath(dataDir, release.releaseId, layers));
+        }
+        catch {
+            paths.push(startupCompileCachePath(dataDir, release.releaseId, []));
+        }
+    }
+    return paths;
+}
+function assertDirectChild(parent, child) {
+    const fromParent = relative(parent, child);
+    if (fromParent.length === 0 || fromParent === ".." || fromParent.startsWith(`..${sep}`) || isAbsolute(fromParent) || fromParent.includes(sep)) {
+        throw new Error(`cleanup path is not a direct child of its managed root: ${child}`);
+    }
+}
+function normalizeLimits(input) {
+    const limits = { ...DEFAULT_LIMITS, ...input };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new Error(`invalid release cleanup ${name}: ${value}`);
+    }
+    return limits;
+}
+function sortCleanupDispositions(dispositions) {
+    return [...dispositions].sort((left, right) => left.attempts - right.attempts
+        || (left.lastAttemptAt ?? "").localeCompare(right.lastAttemptAt ?? "")
+        || left.release.releaseId.localeCompare(right.release.releaseId));
+}
+function sortArtifacts(artifacts, state) {
+    const attempts = new Map();
+    for (const diagnostic of state.cleanup.diagnostics) {
+        attempts.set(diagnostic.releaseId, (attempts.get(diagnostic.releaseId) ?? 0) + 1);
+    }
+    return [...artifacts].sort((left, right) => (attempts.get(artifactName(left)) ?? 0) - (attempts.get(artifactName(right)) ?? 0)
+        || artifactName(left).localeCompare(artifactName(right)));
+}
+async function spawnCleanupWorker(entry, environment) {
+    const child = spawn(process.execPath, [entry], {
+        detached: true,
+        windowsHide: true,
+        stdio: "ignore",
+        env: environment,
+    });
+    await new Promise((resolvePromise, rejectPromise) => {
+        child.once("spawn", resolvePromise);
+        child.once("error", rejectPromise);
+    });
+    child.unref();
+}
+async function acquireWorkerLease(dataDir, runId) {
+    const path = resolve(dataDir, WORKER_LEASE_FILENAME);
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    try {
+        const lease = await open(path, "wx", 0o600);
+        await lease.writeFile(JSON.stringify({ runId, pid: process.pid, createdAt: new Date().toISOString() }));
+        await lease.sync();
+        return lease;
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+            throw error;
+    }
+    const owner = await readWorkerLease(path);
+    if (owner?.pid && processIsAlive(owner.pid))
+        return null;
+    if (owner === null) {
+        const metadata = await stat(path).catch(() => null);
+        if (metadata !== null && Date.now() - metadata.mtimeMs < 10_000)
+            return null;
+    }
+    const quarantine = `${path}.${randomUUID()}.abandoned`;
+    try {
+        await rename(path, quarantine);
+        await rm(quarantine, { force: true });
+    }
+    catch {
+        return null;
+    }
+    return await acquireWorkerLease(dataDir, runId);
+}
+async function releaseWorkerLease(dataDir, runId, lease) {
+    const path = resolve(dataDir, WORKER_LEASE_FILENAME);
+    await lease.close().catch(() => { });
+    const owner = await readWorkerLease(path);
+    if (owner?.runId === runId)
+        await rm(path, { force: true });
+}
+async function readWorkerLease(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        return {
+            ...(typeof value.runId === "string" ? { runId: value.runId } : {}),
+            ...(typeof value.pid === "number" ? { pid: value.pid } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "EPERM";
+    }
+}
+function parseWorkerHolds(value) {
+    if (!value)
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((hold) => Boolean(hold) && typeof hold === "object"
+            && (hold.authority === "agent" || hold.authority === "migration")
+            && typeof hold.releaseId === "string");
+    }
+    catch {
+        return [];
+    }
+}
+function missingOrThrow(error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT")
+        return null;
+    throw error;
+}
+function artifactName(path) { return path.split(sep).at(-1) ?? "artifact"; }
+function certificationReleaseId(path) {
+    return /^certification-(.+)\.json$/.exec(artifactName(path))?.[1] ?? null;
+}
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }