artshelf 0.10.2 → 0.12.0

package/dist/src/ledger.js

@@ -2,6 +2,8 @@ import { randomBytes } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { withPathLock } from "./locks.js";
+import { computeProvenance, validateProvenance } from "./provenance.js";
 import { addTtl, assertIsoDate, ageOf, now, ttlToMs, toIso } from "./time.js";
 const KINDS = new Set([
     "scratch",
@@ -25,11 +27,11 @@ export function normalizeLedgerPath(path) {
     return resolve(path ?? defaultLedgerPath());
 }
 export function putRecord(ledgerPath, input) {
-    const record = prepareRecord(input);
+    const record = prepareRecord(input, ledgerPath);
     appendPreparedRecord(ledgerPath, record);
     return record;
 }
-export function prepareRecord(input) {
+export function prepareRecord(input, ledgerPath) {
     const artifactPath = resolve(input.path);
     if (!existsSync(artifactPath)) {
         throw new Error(`Path does not exist: ${input.path}`);
@@ -56,7 +58,8 @@ export function prepareRecord(input) {
         cleanup,
         owner: input.owner ?? "manual",
         labels: input.labels,
-        status: "active"
+        status: "active",
+        provenance: computeProvenance(artifactPath, { ledgerPath })
     };
     return record;
 }
@@ -136,25 +139,27 @@ export function resolveRecord(ledgerPath, input) {
     if (!input.reason || input.reason.trim().length === 0)
         throw new Error("Missing required --reason");
     const status = assertResolveStatus(input.status);
-    const records = readLedger(ledgerPath);
-    const index = records.findIndex((record) => record.id === input.id);
-    if (index === -1)
-        throw new Error(`Artshelf record not found: ${input.id}`);
-    const current = records[index];
-    if (!current)
-        throw new Error(`Artshelf record not found: ${input.id}`);
-    if (current.status === "resolved") {
-        throw new Error(`Artshelf record is already resolved: ${input.id}`);
-    }
-    const updated = {
-        ...current,
-        status,
-        resolvedAt: toIso(now()),
-        resolutionReason: input.reason.trim()
-    };
-    records[index] = updated;
-    writeLedger(ledgerPath, records);
-    return updated;
+    return withLedgerLock(ledgerPath, () => {
+        const records = readLedger(ledgerPath);
+        const index = records.findIndex((record) => record.id === input.id);
+        if (index === -1)
+            throw new Error(`Artshelf record not found: ${input.id}`);
+        const current = records[index];
+        if (!current)
+            throw new Error(`Artshelf record not found: ${input.id}`);
+        if (current.status === "resolved") {
+            throw new Error(`Artshelf record is already resolved: ${input.id}`);
+        }
+        const updated = {
+            ...current,
+            status,
+            resolvedAt: toIso(now()),
+            resolutionReason: input.reason.trim()
+        };
+        records[index] = updated;
+        writeLedger(ledgerPath, records);
+        return updated;
+    });
 }
 export function dueEntries(records, at = now()) {
     return records.filter((record) => record.status === "active").map((record) => {
@@ -236,6 +241,13 @@ export function validateLedger(ledgerPath) {
             if (!record.resolutionReason)
                 errors.push(`${label}: resolved record missing resolutionReason`);
         }
+        // Legacy rows simply omit provenance and are left alone; once a row carries
+        // provenance it must be well-formed so future reconcile can trust it.
+        if ("provenance" in record) {
+            for (const problem of validateProvenance(record.provenance)) {
+                errors.push(`${label}: ${problem}`);
+            }
+        }
     }
     return { ok: errors.length === 0, errors, warnings, entries: records.length };
 }
@@ -305,115 +317,117 @@ export function executeTrashPurgePlan(ledgerPath, purgePlanId) {
     if (!existsSync(planPath))
         throw new Error(`Trash purge plan not found: ${purgePlanId}`);
     const receiptPath = trashPurgeReceiptPath(ledgerPath, purgePlanId);
-    const existingReceipt = existsSync(receiptPath) ? readTrashPurgeReceipt(receiptPath) : null;
-    if (existingReceipt?.completedAt)
-        throw new Error(`Trash purge receipt already exists: ${purgePlanId}`);
     const plan = JSON.parse(readFileSync(planPath, "utf8"));
-    const records = readLedger(ledgerPath);
-    const recordsById = new Map(records.map((record) => [record.id, record]));
-    const trashRoot = resolve(dirname(ledgerPath), "trash");
-    const executedAt = existingReceipt?.executedAt ?? toIso(now());
-    let results = existingReceipt?.results ?? [];
-    const candidates = [];
-    for (const entry of plan.entries) {
-        const existingResult = results.find((result) => result.id === entry.id);
-        if (existingResult && ["failed", "purged", "skipped"].includes(existingResult.status))
-            continue;
-        const record = recordsById.get(entry.id);
-        if (!record) {
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "record is missing from ledger" });
-            continue;
-        }
-        if (record.status !== "trashed") {
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: `record is ${record.status}` });
-            continue;
-        }
-        if (record.targetPath !== entry.targetPath ||
-            record.cleanedAt !== entry.cleanedAt ||
-            record.receiptPath !== entry.receiptPath ||
-            record.cleanupPlanId !== entry.cleanupPlanId) {
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "plan entry no longer matches ledger record" });
-            continue;
-        }
-        const targetPath = resolve(entry.targetPath);
-        const expectedPlanTrashRoot = resolve(trashRoot, record.cleanupPlanId);
-        if (!isPathWithin(trashRoot, targetPath)) {
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is outside Artshelf trash" });
-            continue;
-        }
-        if (!isStrictPathWithin(expectedPlanTrashRoot, targetPath)) {
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is not a trashed artifact path" });
-            continue;
-        }
-        if (!pathExistsForPurge(entry.targetPath)) {
-            if (existingResult?.status === "deleting") {
-                results = upsertTrashPurgeResult(results, { id: entry.id, status: "purged", targetPath });
+    return withLedgerLock(ledgerPath, () => {
+        const existingReceipt = existsSync(receiptPath) ? readTrashPurgeReceipt(receiptPath) : null;
+        if (existingReceipt?.completedAt)
+            throw new Error(`Trash purge receipt already exists: ${purgePlanId}`);
+        const records = readLedger(ledgerPath);
+        const recordsById = new Map(records.map((record) => [record.id, record]));
+        const trashRoot = resolve(dirname(ledgerPath), "trash");
+        const executedAt = existingReceipt?.executedAt ?? toIso(now());
+        let results = existingReceipt?.results ?? [];
+        const candidates = [];
+        for (const entry of plan.entries) {
+            const existingResult = results.find((result) => result.id === entry.id);
+            if (existingResult && ["failed", "purged", "skipped"].includes(existingResult.status))
+                continue;
+            const record = recordsById.get(entry.id);
+            if (!record) {
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "record is missing from ledger" });
                 continue;
             }
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is missing" });
-            continue;
-        }
-        try {
-            if (resolvesOutsideLedgerTrash(dirname(ledgerPath), trashRoot, expectedPlanTrashRoot, targetPath)) {
-                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target resolves outside Artshelf trash" });
+            if (record.status !== "trashed") {
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: `record is ${record.status}` });
                 continue;
             }
+            if (record.targetPath !== entry.targetPath ||
+                record.cleanedAt !== entry.cleanedAt ||
+                record.receiptPath !== entry.receiptPath ||
+                record.cleanupPlanId !== entry.cleanupPlanId) {
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "plan entry no longer matches ledger record" });
+                continue;
+            }
+            const targetPath = resolve(entry.targetPath);
+            const expectedPlanTrashRoot = resolve(trashRoot, record.cleanupPlanId);
+            if (!isPathWithin(trashRoot, targetPath)) {
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is outside Artshelf trash" });
+                continue;
+            }
+            if (!isStrictPathWithin(expectedPlanTrashRoot, targetPath)) {
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is not a trashed artifact path" });
+                continue;
+            }
+            if (!pathExistsForPurge(entry.targetPath)) {
+                if (existingResult?.status === "deleting") {
+                    results = upsertTrashPurgeResult(results, { id: entry.id, status: "purged", targetPath });
+                    continue;
+                }
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is missing" });
+                continue;
+            }
+            try {
+                if (resolvesOutsideLedgerTrash(dirname(ledgerPath), trashRoot, expectedPlanTrashRoot, targetPath)) {
+                    results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target resolves outside Artshelf trash" });
+                    continue;
+                }
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: `target cannot be validated: ${reason}` });
+                continue;
+            }
+            candidates.push({ id: entry.id, targetPath });
         }
-        catch (error) {
-            const reason = error instanceof Error ? error.message : String(error);
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: `target cannot be validated: ${reason}` });
-            continue;
-        }
-        candidates.push({ id: entry.id, targetPath });
-    }
-    writeTrashPurgeReceipt(receiptPath, {
-        purgePlanId,
-        executedAt,
-        status: "started",
-        results: [
-            ...results,
-            ...candidates.map((candidate) => ({ id: candidate.id, status: "pending", targetPath: candidate.targetPath }))
-        ]
-    });
-    for (const candidate of candidates) {
-        results = upsertTrashPurgeResult(results, { id: candidate.id, status: "deleting", targetPath: candidate.targetPath });
         writeTrashPurgeReceipt(receiptPath, {
             purgePlanId,
             executedAt,
             status: "started",
             results: [
                 ...results,
-                ...pendingTrashPurgeResults(candidates, results)
+                ...candidates.map((candidate) => ({ id: candidate.id, status: "pending", targetPath: candidate.targetPath }))
             ]
         });
-        try {
-            rmSync(candidate.targetPath, { recursive: true, force: true });
-            results = upsertTrashPurgeResult(results, { id: candidate.id, status: "purged", targetPath: candidate.targetPath });
-        }
-        catch (error) {
-            const reason = error instanceof Error ? error.message : String(error);
-            results = upsertTrashPurgeResult(results, { id: candidate.id, status: "failed", targetPath: candidate.targetPath, reason });
+        for (const candidate of candidates) {
+            results = upsertTrashPurgeResult(results, { id: candidate.id, status: "deleting", targetPath: candidate.targetPath });
+            writeTrashPurgeReceipt(receiptPath, {
+                purgePlanId,
+                executedAt,
+                status: "started",
+                results: [
+                    ...results,
+                    ...pendingTrashPurgeResults(candidates, results)
+                ]
+            });
+            try {
+                rmSync(candidate.targetPath, { recursive: true, force: true });
+                results = upsertTrashPurgeResult(results, { id: candidate.id, status: "purged", targetPath: candidate.targetPath });
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                results = upsertTrashPurgeResult(results, { id: candidate.id, status: "failed", targetPath: candidate.targetPath, reason });
+            }
+            writeTrashPurgeReceipt(receiptPath, {
+                purgePlanId,
+                executedAt,
+                status: "started",
+                results: [
+                    ...results,
+                    ...pendingTrashPurgeResults(candidates, results)
+                ]
+            });
         }
-        writeTrashPurgeReceipt(receiptPath, {
-            purgePlanId,
-            executedAt,
-            status: "started",
-            results: [
-                ...results,
-                ...pendingTrashPurgeResults(candidates, results)
-            ]
+        updateLedgerAfterTrashPurge(ledgerPath, records, { purgePlanId, receiptPath, executedAt, results });
+        writeTrashPurgeReceipt(receiptPath, { purgePlanId, executedAt, completedAt: toIso(now()), results });
+        registerArtshelfArtifact(ledgerPath, receiptPath, {
+            reason: `Artshelf trash purge receipt for plan ${purgePlanId}`,
+            ttl: "30d",
+            kind: "run-artifact",
+            cleanup: "review",
+            labels: ["artshelf", "trash-purge-receipt", purgePlanId]
         });
-    }
-    updateLedgerAfterTrashPurge(ledgerPath, records, { purgePlanId, receiptPath, executedAt, results });
-    writeTrashPurgeReceipt(receiptPath, { purgePlanId, executedAt, completedAt: toIso(now()), results });
-    registerArtshelfArtifact(ledgerPath, receiptPath, {
-        reason: `Artshelf trash purge receipt for plan ${purgePlanId}`,
-        ttl: "30d",
-        kind: "run-artifact",
-        cleanup: "review",
-        labels: ["artshelf", "trash-purge-receipt", purgePlanId]
+        return { purgePlanId, receiptPath, results };
     });
-    return { purgePlanId, receiptPath, results };
 }
 function readTrashPurgeReceipt(receiptPath) {
     const receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
@@ -537,51 +551,57 @@ export function executeCleanupPlan(ledgerPath, planId) {
     if (!existsSync(planPath))
         throw new Error(`Cleanup plan not found: ${planId}`);
     const plan = JSON.parse(readFileSync(planPath, "utf8"));
+    assertCleanupPlanExecutable(plan, planId, ledgerPath);
     const trashRoot = join(dirname(ledgerPath), "trash", planId);
-    const records = readLedger(ledgerPath);
-    const recordsById = new Map(records.map((record) => [record.id, record]));
-    const results = [];
-    for (const entry of plan.entries) {
-        const record = recordsById.get(entry.id);
-        if (!record) {
-            results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "record is missing from ledger" });
-            continue;
-        }
-        if (record.status !== "active") {
-            results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: `record is ${record.status}` });
-            continue;
-        }
-        if (!existsSync(entry.path)) {
-            results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "path is missing" });
-            continue;
-        }
-        if (entry.action === "delete") {
-            results.push({ id: entry.id, action: entry.action, status: "refused", path: entry.path, reason: "delete is disabled in v1" });
-            continue;
-        }
-        if (entry.action === "review") {
-            results.push({ id: entry.id, action: entry.action, status: "review-required", path: entry.path });
-            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 });
-    }
-    const receiptPath = receiptPathFor(ledgerPath, planId);
-    const executedAt = toIso(now());
-    writeJson(receiptPath, { planId, executedAt, results });
-    updateLedgerAfterCleanup(ledgerPath, records, { planId, receiptPath, executedAt, results });
-    registerArtshelfArtifact(ledgerPath, receiptPath, {
-        reason: `Artshelf cleanup receipt for plan ${planId}`,
-        ttl: "30d",
-        kind: "run-artifact",
-        cleanup: "review",
-        labels: ["artshelf", "cleanup-receipt", planId]
+    return withLedgerLock(ledgerPath, () => {
+        const records = readLedger(ledgerPath);
+        const recordsById = new Map(records.map((record) => [record.id, record]));
+        const results = [];
+        for (const entry of plan.entries) {
+            const record = recordsById.get(entry.id);
+            if (!record) {
+                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "record is missing from ledger" });
+                continue;
+            }
+            if (record.status !== "active") {
+                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: `record is ${record.status}` });
+                continue;
+            }
+            if (!existsSync(entry.path)) {
+                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "path is missing" });
+                continue;
+            }
+            if (entry.action === "delete") {
+                results.push({ id: entry.id, action: entry.action, status: "refused", path: entry.path, reason: "delete is disabled in v1" });
+                continue;
+            }
+            if (entry.action === "review") {
+                results.push({ id: entry.id, action: entry.action, status: "review-required", path: entry.path });
+                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 });
+        }
+        const receiptPath = receiptPathFor(ledgerPath, planId);
+        const executedAt = toIso(now());
+        writeJson(receiptPath, { planId, executedAt, results });
+        updateLedgerAfterCleanup(ledgerPath, records, { planId, receiptPath, executedAt, results });
+        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 };
     });
-    return { planId, receiptPath, results };
 }
-function registerArtshelfArtifact(ledgerPath, path, input) {
+// 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.
+export function registerArtshelfArtifact(ledgerPath, path, input) {
     const prepared = prepareRecord({
         path,
         reason: input.reason,
@@ -590,30 +610,32 @@ function registerArtshelfArtifact(ledgerPath, path, input) {
         cleanup: input.cleanup,
         owner: "artshelf",
         labels: input.labels
+    }, ledgerPath);
+    withLedgerLock(ledgerPath, () => {
+        const records = readLedger(ledgerPath);
+        const index = records.findIndex((record) => (isMatchingArtshelfArtifact(record, path, input.labels) &&
+            record.status === "active" &&
+            record.path === path));
+        if (index === -1) {
+            appendPreparedRecord(ledgerPath, prepared);
+            return;
+        }
+        const current = records[index];
+        if (!current)
+            return;
+        records[index] = {
+            ...current,
+            reason: prepared.reason,
+            createdAt: prepared.createdAt,
+            ...(prepared.retainUntil ? { retainUntil: prepared.retainUntil } : {}),
+            retention: prepared.retention,
+            kind: prepared.kind,
+            cleanup: prepared.cleanup,
+            owner: prepared.owner,
+            labels: prepared.labels
+        };
+        writeLedger(ledgerPath, records);
     });
-    const records = readLedger(ledgerPath);
-    const index = records.findIndex((record) => (isMatchingArtshelfArtifact(record, path, input.labels) &&
-        record.status === "active" &&
-        record.path === path));
-    if (index === -1) {
-        appendPreparedRecord(ledgerPath, prepared);
-        return;
-    }
-    const current = records[index];
-    if (!current)
-        return;
-    records[index] = {
-        ...current,
-        reason: prepared.reason,
-        createdAt: prepared.createdAt,
-        ...(prepared.retainUntil ? { retainUntil: prepared.retainUntil } : {}),
-        retention: prepared.retention,
-        kind: prepared.kind,
-        cleanup: prepared.cleanup,
-        owner: prepared.owner,
-        labels: prepared.labels
-    };
-    writeLedger(ledgerPath, records);
 }
 function isMatchingArtshelfArtifact(record, path, labels) {
     if (record.path !== path)
@@ -659,16 +681,29 @@ function cleanupPlanEntriesFingerprint(plan) {
         dueStatus: entry.dueStatus
     })));
 }
+function withLedgerLock(ledgerPath, fn) {
+    return withPathLock(ledgerPath, fn, "Artshelf ledger");
+}
+function atomicWriteFileSync(targetPath, content) {
+    const tmpPath = `${targetPath}.${Date.now().toString(36)}-${randomBytes(4).toString("hex")}.tmp`;
+    writeFileSync(tmpPath, content);
+    renameSync(tmpPath, targetPath);
+}
 function appendRecord(ledgerPath, record) {
-    mkdirSync(dirname(ledgerPath), { recursive: true });
-    const previous = existsSync(ledgerPath) ? readFileSync(ledgerPath, "utf8") : "";
-    writeFileSync(ledgerPath, `${previous}${previous && !previous.endsWith("\n") ? "\n" : ""}${JSON.stringify(record)}\n`);
+    withLedgerLock(ledgerPath, () => {
+        mkdirSync(dirname(ledgerPath), { recursive: true });
+        const previous = existsSync(ledgerPath) ? readFileSync(ledgerPath, "utf8") : "";
+        atomicWriteFileSync(ledgerPath, `${previous}${previous && !previous.endsWith("\n") ? "\n" : ""}${JSON.stringify(record)}\n`);
+    });
 }
-function writeLedger(ledgerPath, records) {
-    mkdirSync(dirname(ledgerPath), { recursive: true });
-    const tmpPath = `${ledgerPath}.tmp`;
-    writeFileSync(tmpPath, records.map((record) => JSON.stringify(record)).join("\n") + (records.length > 0 ? "\n" : ""));
-    renameSync(tmpPath, ledgerPath);
+// Exported so the reconcile execute layer (src/reconcile.ts) persists its mutated
+// records through the canonical JSONL writer + ledger lock instead of duplicating the
+// atomic-write format, keeping the reconcile -> ledger import direction one-way.
+export function writeLedger(ledgerPath, records) {
+    withLedgerLock(ledgerPath, () => {
+        mkdirSync(dirname(ledgerPath), { recursive: true });
+        atomicWriteFileSync(ledgerPath, records.map((record) => JSON.stringify(record)).join("\n") + (records.length > 0 ? "\n" : ""));
+    });
 }
 function updateLedgerAfterCleanup(ledgerPath, records, receipt) {
     const resultById = new Map(receipt.results.map((result) => [result.id, result]));
@@ -802,6 +837,7 @@ function makePurgePlanId(date) {
     return `purge_${toIso(date).replace(/[-:]/g, "").replace("T", "_").replace("Z", "")}_${randomBytes(2).toString("hex")}`;
 }
 function cleanupPlanPath(ledgerPath, planId) {
+    assertSafeGeneratedId(planId, "cleanup plan id");
     return join(dirname(ledgerPath), "plans", `${planId}.json`);
 }
 function trashPurgePlanPath(ledgerPath, purgePlanId) {
@@ -809,6 +845,7 @@ function trashPurgePlanPath(ledgerPath, purgePlanId) {
     return join(dirname(ledgerPath), "purge-plans", `${purgePlanId}.json`);
 }
 function receiptPathFor(ledgerPath, planId) {
+    assertSafeGeneratedId(planId, "cleanup plan id");
     return join(dirname(ledgerPath), "receipts", `${planId}.json`);
 }
 function trashPurgeReceiptPath(ledgerPath, purgePlanId) {
@@ -845,11 +882,31 @@ function pathExistsForPurge(path) {
         return false;
     }
 }
-function assertSafeGeneratedId(value, label) {
+export function assertSafeGeneratedId(value, label) {
     if (!/^[A-Za-z0-9_-]+$/.test(value)) {
         throw new Error(`Invalid ${label}: ${value}`);
     }
 }
+// Bind a loaded cleanup plan to the request before any filesystem mutation: the
+// plan must declare the requested id, belong to the executing ledger, and carry
+// executable-looking entries. This keeps `cleanup --execute` plan-id bound, the
+// same posture trash purge already enforces against ledger record metadata.
+function assertCleanupPlanExecutable(plan, planId, ledgerPath) {
+    if (plan.planId !== planId) {
+        throw new Error(`Cleanup plan id mismatch: plan file declares ${plan.planId}, requested ${planId}`);
+    }
+    if (plan.ledgerPath !== ledgerPath) {
+        throw new Error(`Cleanup plan ledger mismatch: plan was created for ${plan.ledgerPath}, executing ${ledgerPath}`);
+    }
+    if (!Array.isArray(plan.entries)) {
+        throw new Error(`Cleanup plan entries are malformed: ${planId}`);
+    }
+    for (const entry of plan.entries) {
+        if (!entry || typeof entry.id !== "string" || typeof entry.path !== "string" || !CLEANUP_ACTIONS.has(entry.action)) {
+            throw new Error(`Cleanup plan entries are malformed: ${planId}`);
+        }
+    }
+}
 function writeJson(path, value) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);

package/dist/src/locks.js

@@ -0,0 +1,73 @@
+import { mkdirSync, rmSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+const heldLocks = new Map();
+/**
+ * Run `fn` while holding a cross-process advisory lock for `targetPath`.
+ *
+ * The lock is a sibling `${targetPath}.lock` directory; `mkdir` is atomic across
+ * processes, so only one holder proceeds at a time. A stale lock is reclaimed
+ * after `staleAfterMs`, and acquisition gives up after the deadline so a crashed
+ * holder cannot block forever.
+ *
+ * Locks are re-entrant within a single process: nested calls for the same path
+ * reuse the existing lock instead of deadlocking on the directory they created.
+ */
+export function withPathLock(targetPath, fn, label = "Artshelf") {
+    const key = resolve(targetPath);
+    const depth = heldLocks.get(key) ?? 0;
+    if (depth > 0) {
+        heldLocks.set(key, depth + 1);
+        try {
+            return fn();
+        }
+        finally {
+            const next = (heldLocks.get(key) ?? 1) - 1;
+            if (next > 0)
+                heldLocks.set(key, next);
+            else
+                heldLocks.delete(key);
+        }
+    }
+    mkdirSync(dirname(key), { recursive: true });
+    const lockPath = `${key}.lock`;
+    const deadline = Date.now() + 5000;
+    const staleAfterMs = 30_000;
+    while (true) {
+        try {
+            mkdirSync(lockPath);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (isStaleLock(lockPath, staleAfterMs)) {
+                rmSync(lockPath, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new Error(`Timed out waiting for ${label} lock: ${key}`);
+            sleep(25);
+        }
+    }
+    heldLocks.set(key, 1);
+    try {
+        return fn();
+    }
+    finally {
+        heldLocks.delete(key);
+        rmSync(lockPath, { recursive: true, force: true });
+    }
+}
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function isStaleLock(lockPath, staleAfterMs) {
+    try {
+        return Date.now() - statSync(lockPath).mtimeMs > staleAfterMs;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}