artshelf 0.13.0 → 0.14.0

package/dist/src/ledger.js

@@ -553,41 +553,94 @@ export function executeCleanupPlan(ledgerPath, planId) {
     const plan = JSON.parse(readFileSync(planPath, "utf8"));
     assertCleanupPlanExecutable(plan, planId, ledgerPath);
     const trashRoot = join(dirname(ledgerPath), "trash", planId);
+    const receiptPath = receiptPathFor(ledgerPath, planId);
     return withLedgerLock(ledgerPath, () => {
+        const existingReceipt = existsSync(receiptPath) ? readCleanupReceiptIfValid(receiptPath) : null;
+        const planReceipt = existingReceipt?.planId === planId ? existingReceipt : null;
+        const priorResultById = new Map((planReceipt?.results ?? []).map((result) => [result.id, result]));
         const records = readLedger(ledgerPath);
+        if (planReceipt?.completedAt) {
+            if (!records.some((record) => record.status === "active" && isMatchingArtshelfArtifact(record, receiptPath, ["artshelf", "cleanup-receipt", planId]))) {
+                registerArtshelfArtifact(ledgerPath, receiptPath, {
+                    reason: `Artshelf cleanup receipt for plan ${planId}`,
+                    ttl: "30d",
+                    kind: "run-artifact",
+                    cleanup: "review",
+                    labels: ["artshelf", "cleanup-receipt", planId]
+                });
+            }
+            return { planId, receiptPath, results: planReceipt.results };
+        }
         const recordsById = new Map(records.map((record) => [record.id, record]));
-        const results = [];
-        for (const entry of plan.entries) {
+        const executedAt = toIso(now());
+        const results = plan.entries.map((entry) => {
+            const prior = priorResultById.get(entry.id);
+            if (prior && isTerminalCleanupResult(prior)) {
+                return withCleanupResultExecutedAt(prior, cleanupResultExecutedAt(prior, planReceipt, executedAt));
+            }
+            return { id: entry.id, action: entry.action, status: "pending", path: entry.path };
+        });
+        writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
+        for (const [index, entry] of plan.entries.entries()) {
             const record = recordsById.get(entry.id);
+            const prior = priorResultById.get(entry.id);
+            const priorExecutedAt = prior && isTerminalCleanupResult(prior)
+                ? cleanupResultExecutedAt(prior, planReceipt, executedAt)
+                : executedAt;
             if (!record) {
-                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "record is missing from ledger" });
+                results[index] = { id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "record is missing from ledger" };
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
                 continue;
             }
             if (record.status !== "active") {
-                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: `record is ${record.status}` });
+                if (prior && priorCleanupResultMatchesLedger(record, prior, { planId, receiptPath, executedAt: priorExecutedAt })) {
+                    results[index] = withCleanupResultExecutedAt(prior, priorExecutedAt);
+                    writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
+                    continue;
+                }
+                results[index] = { id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: `record is ${record.status}` };
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
                 continue;
             }
-            if (!existsSync(entry.path)) {
-                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "path is missing" });
+            if (prior && isTerminalCleanupResult(prior)) {
+                results[index] = withCleanupResultExecutedAt(prior, priorExecutedAt);
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
                 continue;
             }
-            if (entry.action === "delete") {
-                results.push({ id: entry.id, action: entry.action, status: "refused", path: entry.path, reason: "delete is disabled in v1" });
+            if (entry.action === "trash") {
+                const target = join(trashRoot, `${entry.id}-${basename(entry.path)}`);
+                if (existsSync(target)) {
+                    results[index] = { id: entry.id, action: entry.action, status: "trashed", path: entry.path, target, executedAt };
+                    writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
+                    continue;
+                }
+                if (existsSync(entry.path)) {
+                    mkdirSync(trashRoot, { recursive: true });
+                    renameSync(entry.path, target);
+                    results[index] = { id: entry.id, action: entry.action, status: "trashed", path: entry.path, target, executedAt };
+                    writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
+                    continue;
+                }
+                results[index] = { id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "path is missing" };
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
+                continue;
+            }
+            if (!existsSync(entry.path)) {
+                results[index] = { id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "path is missing" };
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
                 continue;
             }
-            if (entry.action === "review") {
-                results.push({ id: entry.id, action: entry.action, status: "review-required", path: entry.path });
+            if (entry.action === "delete") {
+                results[index] = { id: entry.id, action: entry.action, status: "refused", path: entry.path, reason: "delete is disabled in v1", executedAt };
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
                 continue;
             }
-            mkdirSync(trashRoot, { recursive: true });
-            const target = join(trashRoot, `${entry.id}-${basename(entry.path)}`);
-            renameSync(entry.path, target);
-            results.push({ id: entry.id, action: entry.action, status: "trashed", path: entry.path, target });
+            results[index] = { id: entry.id, action: entry.action, status: "review-required", path: entry.path, executedAt };
+            writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
         }
-        const receiptPath = receiptPathFor(ledgerPath, planId);
-        const executedAt = toIso(now());
-        writeJson(receiptPath, { planId, executedAt, results });
-        updateLedgerAfterCleanup(ledgerPath, records, { planId, receiptPath, executedAt, results });
+        const receiptExecutedAt = cleanupReceiptExecutedAt(results, executedAt);
+        updateLedgerAfterCleanup(ledgerPath, records, { planId, receiptPath, executedAt: receiptExecutedAt, results });
+        writeCleanupReceipt(receiptPath, { planId, executedAt: receiptExecutedAt, completedAt: toIso(now()), results });
         registerArtshelfArtifact(ledgerPath, receiptPath, {
             reason: `Artshelf cleanup receipt for plan ${planId}`,
             ttl: "30d",
@@ -598,6 +651,69 @@ export function executeCleanupPlan(ledgerPath, planId) {
         return { planId, receiptPath, results };
     });
 }
+function priorCleanupResultMatchesLedger(record, result, receipt) {
+    if (record.cleanupPlanId !== receipt.planId)
+        return false;
+    if (record.receiptPath !== receipt.receiptPath)
+        return false;
+    if (record.cleanedAt !== receipt.executedAt)
+        return false;
+    if (result.status === "trashed") {
+        return record.status === "trashed" && !!result.target && record.targetPath === result.target;
+    }
+    if (result.status === "review-required") {
+        return record.status === "review-required";
+    }
+    if (result.status === "refused") {
+        return record.status === "cleanup-refused" && (!result.reason || record.cleanupReason === result.reason);
+    }
+    return false;
+}
+function isTerminalCleanupResult(result) {
+    return result.status === "trashed" || result.status === "review-required" || result.status === "refused";
+}
+function cleanupResultExecutedAt(result, receipt, fallback) {
+    if (typeof result.executedAt === "string")
+        return result.executedAt;
+    if (isTerminalCleanupResult(result) && typeof receipt?.executedAt === "string")
+        return receipt.executedAt;
+    return fallback;
+}
+function withCleanupResultExecutedAt(result, executedAt) {
+    return { ...result, executedAt };
+}
+function cleanupReceiptExecutedAt(results, fallback) {
+    const terminalExecutedAt = results
+        .filter(isTerminalCleanupResult)
+        .map((result) => result.executedAt)
+        .filter((value) => typeof value === "string");
+    const firstExecutedAt = terminalExecutedAt[0];
+    if (firstExecutedAt && terminalExecutedAt.every((value) => value === firstExecutedAt)) {
+        return firstExecutedAt;
+    }
+    return fallback;
+}
+function readCleanupReceiptIfValid(receiptPath) {
+    try {
+        return readCleanupReceipt(receiptPath);
+    }
+    catch {
+        return null;
+    }
+}
+function readCleanupReceipt(receiptPath) {
+    const receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+    return {
+        ...(typeof receipt.planId === "string" ? { planId: receipt.planId } : {}),
+        ...(typeof receipt.executedAt === "string" ? { executedAt: receipt.executedAt } : {}),
+        ...(typeof receipt.completedAt === "string" ? { completedAt: receipt.completedAt } : {}),
+        ...(typeof receipt.status === "string" ? { status: receipt.status } : {}),
+        results: Array.isArray(receipt.results) ? receipt.results : []
+    };
+}
+function writeCleanupReceipt(receiptPath, receipt) {
+    writeJson(receiptPath, receipt);
+}
 // Exported so the reconcile plan layer (src/reconcile.ts) registers its dry-run plan
 // artifacts through the same upsert-by-path-and-labels path that cleanup plans use,
 // keeping plan files tracked and reused under a stable plan id.
@@ -712,31 +828,34 @@ function updateLedgerAfterCleanup(ledgerPath, records, receipt) {
         if (!result)
             return record;
         if (result.status === "trashed") {
+            const cleanedAt = result.executedAt ?? receipt.executedAt;
             return {
                 ...record,
                 status: "trashed",
                 cleanupPlanId: receipt.planId,
                 receiptPath: receipt.receiptPath,
-                cleanedAt: receipt.executedAt,
+                cleanedAt,
                 ...(result.target ? { targetPath: result.target } : {})
             };
         }
         if (result.status === "review-required") {
+            const cleanedAt = result.executedAt ?? receipt.executedAt;
             return {
                 ...record,
                 status: "review-required",
                 cleanupPlanId: receipt.planId,
                 receiptPath: receipt.receiptPath,
-                cleanedAt: receipt.executedAt
+                cleanedAt
             };
         }
         if (result.status === "refused") {
+            const cleanedAt = result.executedAt ?? receipt.executedAt;
             return {
                 ...record,
                 status: "cleanup-refused",
                 cleanupPlanId: receipt.planId,
                 receiptPath: receipt.receiptPath,
-                cleanedAt: receipt.executedAt,
+                cleanedAt,
                 ...(result.reason ? { cleanupReason: result.reason } : {})
             };
         }
@@ -909,5 +1028,5 @@ function assertCleanupPlanExecutable(plan, planId, ledgerPath) {
 }
 function writeJson(path, value) {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+    atomicWriteFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
 }

package/dist/src/registry-prune.js

@@ -0,0 +1,259 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { assertSafeGeneratedId } from "./ledger.js";
+import { withPathLock } from "./locks.js";
+import { listRegisteredLedgers, normalizeRegistryPath, removeRegisteredLedgers } from "./registry.js";
+import { now, toIso } from "./time.js";
+// Classify the registry into prune findings (read-only). A registration is prunable
+// when its ledger file is missing — the same "missing/stale" signal `ledgers list`
+// reports via existence of the ledger path. Registrations whose resolved path appears
+// more than once are ambiguous: pruning one would silently drop a sibling, so they are
+// blocked for manual resolution instead of pruned. Present ledger files yield nothing.
+export function classifyRegistryPruneFindings(registryPath) {
+    const entries = listRegisteredLedgers(normalizeRegistryPath(registryPath));
+    const pathCounts = new Map();
+    for (const entry of entries) {
+        pathCounts.set(entry.path, (pathCounts.get(entry.path) ?? 0) + 1);
+    }
+    const findings = [];
+    for (const entry of entries) {
+        if ((pathCounts.get(entry.path) ?? 0) > 1) {
+            findings.push(finding(entry, "blocked", "ambiguous duplicate registry path; resolve manually before pruning"));
+            continue;
+        }
+        if (existsSync(entry.path))
+            continue;
+        findings.push(finding(entry, "prune", "registered ledger file is missing"));
+    }
+    return findings;
+}
+// Build the registry-prune plan without persisting anything (dry-run preview). Fully
+// read-only: it classifies the registry and returns the plan a `--dry-run` would
+// create, but never writes a plan file or mutates the registry. A plan with no
+// actionable entries collapses to the not-created shape so callers can render
+// "nothing to prune" the same way cleanup and reconcile do.
+export function previewRegistryPrunePlan(registryPath) {
+    const plan = buildRegistryPrunePlan(normalizeRegistryPath(registryPath));
+    return plan.entries.length === 0 ? noCreatedRegistryPrunePlan(plan) : plan;
+}
+// Create (or reuse) a reviewed registry-prune plan (dry-run). This is the only part of
+// dry-run that writes, and it only writes the plan file — never the registry. When an
+// earlier plan already covers the same prunable entries it is reused verbatim (stable
+// plan id), and when nothing is actionable no plan artifact is created at all, keeping
+// dry-run side-effect-free in that case. The plan file lives next to the registry under
+// `registry-prune-plans/` so a later `--execute` can discover it by exact plan id.
+export function createRegistryPrunePlan(registryPath) {
+    const normalized = normalizeRegistryPath(registryPath);
+    const plan = buildRegistryPrunePlan(normalized);
+    if (plan.entries.length === 0)
+        return noCreatedRegistryPrunePlan(plan);
+    const existing = matchingExistingRegistryPrunePlan(normalized, plan);
+    const reviewed = existing ? { ...plan, planId: existing.planId, planPath: existing.planPath } : plan;
+    if (!reviewed.planPath)
+        throw new Error("registry prune plan path was not created");
+    writeRegistryPrunePlanFile(reviewed.planPath, reviewed);
+    return reviewed;
+}
+// Apply a reviewed registry-prune plan (NGX-481 `ledgers prune --execute`). This is the
+// only mutating registry-prune entrypoint and it is deliberately conservative:
+//   * It refuses up front when the plan id is missing, the registry is absent, the plan
+//     file is absent, or the plan file's declared id/registry does not match the scoped
+//     request (no fresh plan, no `--all`; it binds to one exact reviewed plan id against
+//     one exact registry path).
+//   * Inside one registry lock it re-classifies the live registry and only removes a
+//     planned entry that still classifies as prunable; entries whose ledger file
+//     reappeared or whose path became an ambiguous duplicate are skipped, not removed.
+//   * It writes a rollback copy of the registry before mutating and a receipt after,
+//     then verifies the removed registrations are actually gone.
+export function executeRegistryPrunePlan(registryPath, planId) {
+    if (!planId)
+        throw new Error("ledgers prune --execute requires --plan-id");
+    const normalized = normalizeRegistryPath(registryPath);
+    if (!existsSync(normalized))
+        throw new Error(`Registry not found: ${normalized}`);
+    const planPath = registryPrunePlanPath(normalized, planId);
+    if (!existsSync(planPath))
+        throw new Error(`Registry prune plan not found: ${planId}`);
+    const plan = JSON.parse(readFileSync(planPath, "utf8"));
+    assertRegistryPrunePlanExecutable(plan, planId, normalized);
+    const receiptPath = registryPruneReceiptPath(normalized, planId);
+    const rollbackPath = registryPruneRollbackPath(normalized, planId);
+    return withPathLock(normalized, () => {
+        const existingReceipt = readExistingRegistryPruneReceipt(receiptPath, planId, normalized);
+        if (existingReceipt)
+            return existingReceipt;
+        const liveByKey = new Map(classifyRegistryPruneFindings(normalized).map((item) => [pruneKey(item.name, item.path), item]));
+        const removable = [];
+        const skipped = [];
+        for (const entry of plan.entries) {
+            if (liveByKey.get(pruneKey(entry.name, entry.path))?.status === "prune")
+                removable.push(entry);
+            else
+                skipped.push(removal(entry.name, entry.path, entry.scope));
+        }
+        let removedEntries = [];
+        const receiptRollbackPath = removable.length > 0 ? rollbackPath : null;
+        if (removable.length > 0) {
+            copyRegistrySnapshot(normalized, rollbackPath);
+            removedEntries = removeRegisteredLedgers(normalized, removable.map((entry) => ({ name: entry.name, path: entry.path })));
+        }
+        const removed = removedEntries.map((entry) => removal(entry.name, entry.path, entry.scope));
+        const verification = verifyRegistryPrune(normalized, removed);
+        const receipt = {
+            planId,
+            registryPath: normalized,
+            executedAt: toIso(now()),
+            rollbackPath: receiptRollbackPath,
+            removed,
+            skipped,
+            verification,
+            receiptPath
+        };
+        writeRegistryPruneReceiptFile(receiptPath, receipt);
+        return receipt;
+    }, "Artshelf ledger registry");
+}
+function finding(entry, status, reason) {
+    return { name: entry.name, path: entry.path, scope: entry.scope, status, reason };
+}
+function buildRegistryPrunePlan(registryPath) {
+    const generatedAt = now();
+    const findings = classifyRegistryPruneFindings(registryPath);
+    const entries = findings.filter((item) => item.status === "prune").map(planEntry);
+    const skipped = findings.filter((item) => item.status === "blocked").map(planEntry);
+    const planId = makeRegistryPrunePlanId(generatedAt);
+    return {
+        planId,
+        generatedAt: toIso(generatedAt),
+        registryPath,
+        entries,
+        skipped,
+        planPath: registryPrunePlanPath(registryPath, planId)
+    };
+}
+function planEntry(item) {
+    return { name: item.name, path: item.path, scope: item.scope, reason: item.reason };
+}
+function noCreatedRegistryPrunePlan(plan) {
+    return { ...plan, planId: "not-created", planPath: null };
+}
+// Reuse an unexecuted earlier plan whose prunable entries match this one's, so repeated
+// dry-runs converge on a single stable plan id (mirrors cleanup/reconcile plan reuse).
+// Only the structural entry fields are fingerprinted; volatile fields (generatedAt) and
+// the review-only skipped list do not affect reuse.
+function matchingExistingRegistryPrunePlan(registryPath, plan) {
+    const plansDir = join(dirname(registryPath), "registry-prune-plans");
+    if (!existsSync(plansDir))
+        return null;
+    const filenames = readdirSync(plansDir).filter((name) => name.endsWith(".json")).sort().reverse();
+    for (const filename of filenames) {
+        const planPath = join(plansDir, filename);
+        try {
+            const candidate = JSON.parse(readFileSync(planPath, "utf8"));
+            if (candidate.registryPath !== registryPath)
+                continue;
+            if (registryPrunePlanFingerprint(candidate) !== registryPrunePlanFingerprint(plan))
+                continue;
+            if (existsSync(registryPruneReceiptPath(registryPath, candidate.planId)))
+                continue;
+            return { ...candidate, planPath };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function registryPrunePlanFingerprint(plan) {
+    return JSON.stringify(plan.entries.map((entry) => ({ name: entry.name, path: entry.path, scope: entry.scope })));
+}
+function writeRegistryPrunePlanFile(planPath, plan) {
+    mkdirSync(dirname(planPath), { recursive: true });
+    writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
+}
+function makeRegistryPrunePlanId(date) {
+    return `registry-prune_${toIso(date).replace(/[-:]/g, "").replace("T", "_").replace("Z", "")}_${randomBytes(2).toString("hex")}`;
+}
+function registryPrunePlanPath(registryPath, planId) {
+    assertSafeGeneratedId(planId, "registry prune plan id");
+    return join(dirname(registryPath), "registry-prune-plans", `${planId}.json`);
+}
+// Bind a loaded registry-prune plan to the request before any registry mutation,
+// mirroring reconcile's assertReconcilePlanExecutable: the plan must declare the
+// requested id, belong to the executing registry, and carry well-formed entries.
+function assertRegistryPrunePlanExecutable(plan, planId, registryPath) {
+    if (plan.planId !== planId) {
+        throw new Error(`Registry prune plan id mismatch: plan file declares ${plan.planId}, requested ${planId}`);
+    }
+    if (plan.registryPath !== registryPath) {
+        throw new Error(`Registry prune plan registry mismatch: plan was created for ${plan.registryPath}, executing ${registryPath}`);
+    }
+    if (!Array.isArray(plan.entries)) {
+        throw new Error(`Registry prune plan entries are malformed: ${planId}`);
+    }
+    for (const entry of plan.entries) {
+        if (!entry || typeof entry.name !== "string" || typeof entry.path !== "string") {
+            throw new Error(`Registry prune plan entries are malformed: ${planId}`);
+        }
+    }
+}
+// Re-scan the registry after mutation and confirm every removed registration is gone.
+// `ok` stays true only when none of them resurface; `remainingPrunable` counts any
+// prunable registrations left registry-wide so the receipt reflects whether the
+// registry is fully clean or other plans still have work.
+function verifyRegistryPrune(registryPath, removed) {
+    const live = classifyRegistryPruneFindings(registryPath);
+    const stillPresent = removed.filter((entry) => live.some((item) => item.name === entry.name && item.path === entry.path));
+    const remainingPrunable = live.filter((item) => item.status === "prune").length;
+    return {
+        ok: stillPresent.length === 0,
+        remainingPrunable,
+        detail: stillPresent.length === 0
+            ? "removed registrations are gone; registry re-scan is clean of them"
+            : `still registered after prune: ${stillPresent.map((entry) => entry.name).join(", ")}`
+    };
+}
+// Snapshot the registry verbatim before mutation so the receipt's rollbackPath points
+// at a restorable copy. The registry is always UTF-8 JSON, so a read/write round-trip
+// reproduces it byte-for-byte and keeps file I/O consistent with the rest of the code.
+function copyRegistrySnapshot(registryPath, rollbackPath) {
+    mkdirSync(dirname(rollbackPath), { recursive: true });
+    writeFileSync(rollbackPath, readFileSync(registryPath, "utf8"));
+}
+function readExistingRegistryPruneReceipt(receiptPath, planId, registryPath) {
+    if (!existsSync(receiptPath))
+        return null;
+    let receipt;
+    try {
+        receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+    }
+    catch {
+        throw new Error(`Registry prune receipt already exists but is unreadable: ${receiptPath}`);
+    }
+    if (receipt.planId !== planId || receipt.registryPath !== registryPath || receipt.receiptPath !== receiptPath) {
+        throw new Error(`Registry prune receipt already exists for a different execution: ${receiptPath}`);
+    }
+    if (!Array.isArray(receipt.removed) || !Array.isArray(receipt.skipped) || !receipt.verification) {
+        throw new Error(`Registry prune receipt already exists but is malformed: ${receiptPath}`);
+    }
+    return receipt;
+}
+function removal(name, path, scope) {
+    return { name, path, scope };
+}
+function pruneKey(name, path) {
+    return JSON.stringify([name, path]);
+}
+function registryPruneReceiptPath(registryPath, planId) {
+    assertSafeGeneratedId(planId, "registry prune plan id");
+    return join(dirname(registryPath), "registry-prune-receipts", `${planId}.json`);
+}
+function registryPruneRollbackPath(registryPath, planId) {
+    assertSafeGeneratedId(planId, "registry prune plan id");
+    return join(dirname(registryPath), "registry-prune-rollbacks", `${planId}.json`);
+}
+function writeRegistryPruneReceiptFile(receiptPath, receipt) {
+    mkdirSync(dirname(receiptPath), { recursive: true });
+    writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+}

package/dist/src/registry.js

@@ -51,6 +51,33 @@ export function registerLedger(input) {
         return entry;
     });
 }
+// Remove registrations matching the given (name, path) targets, returning the entries
+// actually removed. The approval-gated registry prune execute composes this under its
+// own registry lock (re-entrant), so classification, rollback copy, mutation, and
+// verification all stay inside one critical section. Matching on both name and path
+// keeps removal precise when two registrations happen to share a path. The registry is
+// only rewritten when something is actually removed, so a no-op target list is inert.
+export function removeRegisteredLedgers(registryPath, targets) {
+    const normalized = normalizeRegistryPath(registryPath);
+    return withRegistryLock(normalized, () => {
+        const registry = readRegistry(normalized);
+        const wanted = new Set(targets.map((target) => removalKey(target.name, resolve(target.path))));
+        const removed = [];
+        const kept = [];
+        for (const entry of registry.ledgers) {
+            if (wanted.has(removalKey(entry.name, entry.path)))
+                removed.push(entry);
+            else
+                kept.push(entry);
+        }
+        if (removed.length > 0)
+            writeRegistry(normalized, { version: 1, ledgers: kept });
+        return removed;
+    });
+}
+function removalKey(name, path) {
+    return JSON.stringify([name, path]);
+}
 function writeRegistry(registryPath, registry) {
     mkdirSync(dirname(registryPath), { recursive: true });
     const tmpPath = `${registryPath}.${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}.tmp`;

package/dist/src/renderers/doctor.js

@@ -5,7 +5,17 @@ function doctorAttention(summary) {
 }
 function doctorNextAction(blockers, summary, registryPath) {
     if (blockers.length > 0) {
-        return `repair ${blockers.length} registry/ledger issue(s) above, then re-run \`artshelf doctor\``;
+        const fixes = [];
+        if (summary.stale > 0) {
+            fixes.push(`run \`artshelf ledgers prune --dry-run --registry ${registryPath}\` to review removing ${summary.stale} missing/stale registration(s)`);
+        }
+        if (summary.invalid > 0) {
+            fixes.push(`repair ${summary.invalid} invalid ledger file(s) above`);
+        }
+        if (fixes.length === 0) {
+            return `repair ${blockers.length} registry/ledger issue(s) above, then re-run \`artshelf doctor\``;
+        }
+        return `${fixes.join("; ")}, then re-run \`artshelf doctor\``;
     }
     if (summary.warnings > 0) {
         return `healthy, but ${summary.warnings} warning(s) noted — run \`artshelf reconcile --dry-run --all --registry ${registryPath}\` to prepare reconcile-ready approvals, then run \`artshelf review --all --registry ${registryPath}\`; nothing is auto-executed`;

package/dist/src/renderers/review.js

@@ -11,6 +11,14 @@ export function reviewNextAction(summary, scope, ledgerPath, registryPath) {
     const broken = summary.invalid + summary.stale;
     const review = statusCommand(scope, "review", ledgerPath);
     if (broken > 0) {
+        if (scope === "all" && summary.stale > 0 && registryPath) {
+            const fixes = [
+                `run \`artshelf ledgers prune --dry-run --registry ${registryPath}\` to review removing ${summary.stale} missing/stale registration(s)`
+            ];
+            if (summary.invalid > 0)
+                fixes.push(`repair ${summary.invalid} invalid ledger(s) above (re-register or fix the file)`);
+            return `${fixes.join("; ")}, then re-run \`${review}\``;
+        }
         const repair = scope === "all" ? "re-register or fix the file" : "fix the file";
         return `repair ${broken} broken ledger(s) above (${repair}), then re-run \`${review}\``;
     }
@@ -45,7 +53,7 @@ export function printReview(results) {
         process.stdout.write(`ledger: ${result.ledger.path}\n`);
     }
 }
-function buildReviewDecisions(results, scope) {
+function buildReviewDecisions(results, scope, registryPath) {
     const readyForApproval = [];
     const needsReviewFirst = [];
     const blocked = [];
@@ -54,6 +62,20 @@ function buildReviewDecisions(results, scope) {
         const { ledger, validate, due } = result;
         if (!validate.ok) {
             const status = result.ledgerExists ? "invalid" : "missing";
+            // A missing registered ledger is repaired through the approval-gated registry-prune
+            // flow rather than hand-editing the registry; an invalid-but-present file still needs
+            // a manual re-register/fix.
+            if (scope === "all" && status === "missing" && registryPath) {
+                blocked.push({
+                    label: `Prune ${ledger.name} registration (missing)`,
+                    itemIds: [],
+                    actionType: "fix-registry",
+                    approvalTarget: null,
+                    reason: validate.errors[0] ?? "the registered ledger file is missing",
+                    nextStep: `run \`artshelf ledgers prune --dry-run --registry ${registryPath} --json\` to review removing it, then approve \`approve artshelf ledgers prune registry ${registryPath} plan <plan-id>\``
+                });
+                continue;
+            }
             const repair = scope === "all" ? `re-register or fix ${ledger.path}` : `fix ${ledger.path}`;
             blocked.push({
                 label: `Repair ${ledger.name} ledger (${status})`,
@@ -177,7 +199,7 @@ function reviewCounts(summary) {
     };
 }
 export function buildReviewAgentPacketAll(results, summary, registry) {
-    const groups = buildReviewDecisions(results, "all");
+    const groups = buildReviewDecisions(results, "all", registry.path);
     return {
         schemaVersion: 1,
         command: "review",

package/dist/src/renderers/status.js

@@ -14,9 +14,17 @@ export function statusCommand(scope, command, ledgerPath) {
         return `artshelf ${command} --all`;
     return ledgerPath ? `artshelf ${command} --ledger ${ledgerPath}` : `artshelf ${command}`;
 }
-function statusNextAction(blockers, counts, scope, ledgerPath, registryPath) {
+function statusNextAction(blockers, counts, scope, ledgerPath, registryPath, stale = 0, invalid = 0) {
     if (blockers.length > 0) {
         const verify = statusCommand(scope, "status", ledgerPath);
+        if (scope === "all" && stale > 0 && registryPath) {
+            const fixes = [
+                `run \`artshelf ledgers prune --dry-run --registry ${registryPath}\` to review removing ${stale} missing/stale registration(s)`
+            ];
+            if (invalid > 0)
+                fixes.push(`repair ${invalid} invalid ledger(s) above`);
+            return `${fixes.join("; ")}, then re-run \`${verify}\``;
+        }
         return `repair ${blockers.length} broken ledger(s) above, then re-run \`${verify}\``;
     }
     const review = statusCommand(scope, "review", ledgerPath);
@@ -59,7 +67,7 @@ export function buildStatusAgentPacketAll(report) {
         counts,
         attention: statusAttention(counts),
         blockers,
-        nextAction: statusNextAction(blockers, counts, "all", undefined, report.registryPath),
+        nextAction: statusNextAction(blockers, counts, "all", undefined, report.registryPath, report.totals.stale, report.totals.invalid),
         verification: `artshelf status --all --agent --registry ${report.registryPath}`
     };
 }