artshelf 0.3.0

package/dist/src/ledger.js

@@ -0,0 +1,846 @@
+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 { addTtl, assertIsoDate, ageOf, now, ttlToMs, toIso } from "./time.js";
+const KINDS = new Set([
+    "scratch",
+    "backup",
+    "run-artifact",
+    "evidence",
+    "cache",
+    "quarantine",
+    "other"
+]);
+const CLEANUP_ACTIONS = new Set(["trash", "review", "delete"]);
+const STATUSES = new Set(["active", "review-required", "trashed", "cleanup-refused", "resolved"]);
+const RESOLVE_STATUSES = new Set(["resolved"]);
+export function defaultLedgerPath(cwd = process.cwd()) {
+    const repoRoot = findGitRoot(cwd);
+    if (repoRoot)
+        return join(repoRoot, ".shelf", "ledger.jsonl");
+    return join(homedir(), ".shelf", "ledger.jsonl");
+}
+export function normalizeLedgerPath(path) {
+    return resolve(path ?? defaultLedgerPath());
+}
+export function putRecord(ledgerPath, input) {
+    const record = prepareRecord(input);
+    appendPreparedRecord(ledgerPath, record);
+    return record;
+}
+export function prepareRecord(input) {
+    const artifactPath = resolve(input.path);
+    if (!existsSync(artifactPath)) {
+        throw new Error(`Path does not exist: ${input.path}`);
+    }
+    if (!input.reason || input.reason.trim().length === 0) {
+        throw new Error("Missing required --reason");
+    }
+    const retentionCount = [input.ttl, input.retainUntil, input.manualReview].filter(Boolean).length;
+    if (retentionCount !== 1) {
+        throw new Error("Choose exactly one of --ttl, --retain-until, or --manual-review");
+    }
+    const kind = assertKind(input.kind ?? "other");
+    const cleanup = assertCleanup(input.cleanup ?? "review");
+    const createdAt = now();
+    const retentionPlan = buildRetention(input, createdAt);
+    const record = {
+        id: makeId(createdAt),
+        path: artifactPath,
+        kind,
+        reason: input.reason.trim(),
+        createdAt: toIso(createdAt),
+        ...(retentionPlan.retainUntil ? { retainUntil: retentionPlan.retainUntil } : {}),
+        retention: retentionPlan.retention,
+        cleanup,
+        owner: input.owner ?? "manual",
+        labels: input.labels,
+        status: "active"
+    };
+    return record;
+}
+export function appendPreparedRecord(ledgerPath, record) {
+    appendRecord(ledgerPath, record);
+}
+export function readLedger(ledgerPath) {
+    if (!existsSync(ledgerPath))
+        return [];
+    const content = readFileSync(ledgerPath, "utf8").trim();
+    if (!content)
+        return [];
+    return content.split(/\n+/).map((line, index) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`Invalid JSONL at line ${index + 1}: ${error.message}`);
+        }
+    });
+}
+export function listTrashedRecords(ledgerPath) {
+    const records = readLedger(ledgerPath).filter((record) => record.status === "trashed");
+    const current = now();
+    return records.map((record) => {
+        if (!record.id || !record.targetPath || !record.cleanedAt || !record.receiptPath || !record.cleanupPlanId) {
+            throw new Error(`trashed record ${record.id ?? "<missing id>"} missing cleanup metadata`);
+        }
+        return {
+            id: record.id,
+            targetPath: record.targetPath,
+            cleanedAt: record.cleanedAt,
+            receiptPath: record.receiptPath,
+            cleanupPlanId: record.cleanupPlanId,
+            age: ageOf(current, record.cleanedAt)
+        };
+    });
+}
+export function filterRecordsByStatus(records, status) {
+    if (!status)
+        return records;
+    const normalized = assertStatus(status);
+    return records.filter((record) => record.status === normalized);
+}
+export function getRecord(records, id) {
+    if (!id || id.trim().length === 0)
+        throw new Error("get requires <id>");
+    const record = records.find((entry) => entry.id === id);
+    if (!record)
+        throw new Error(`Artshelf record not found: ${id}`);
+    return record;
+}
+export function findRecords(records, input) {
+    const hasQuery = Boolean(input.path || input.owner || input.labels.length > 0 || input.status);
+    if (!hasQuery) {
+        throw new Error("find requires at least one of --path, --owner, --label, or --status");
+    }
+    const normalizedPath = input.path ? resolve(input.path) : undefined;
+    const normalizedStatus = input.status ? assertStatus(input.status) : undefined;
+    return records.filter((record) => {
+        if (normalizedPath && record.path !== normalizedPath)
+            return false;
+        if (input.owner && record.owner !== input.owner)
+            return false;
+        if (normalizedStatus && record.status !== normalizedStatus)
+            return false;
+        for (const label of input.labels) {
+            if (!record.labels.includes(label))
+                return false;
+        }
+        return true;
+    });
+}
+export function resolveRecord(ledgerPath, input) {
+    if (!input.id || input.id.trim().length === 0)
+        throw new Error("resolve requires <id>");
+    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;
+}
+export function dueEntries(records, at = now()) {
+    return records.filter((record) => record.status === "active").map((record) => {
+        const dueStatus = classifyDue(record, at);
+        return {
+            id: record.id,
+            path: record.path,
+            reason: record.reason,
+            cleanup: record.cleanup,
+            dueStatus,
+            ...(record.retainUntil ? { retainUntil: record.retainUntil } : {})
+        };
+    });
+}
+export function validateLedger(ledgerPath) {
+    const errors = [];
+    const warnings = [];
+    let records = [];
+    try {
+        records = readLedger(ledgerPath);
+    }
+    catch (error) {
+        errors.push(error.message);
+        return { ok: false, errors, warnings, entries: 0 };
+    }
+    const ids = new Set();
+    for (const [index, record] of records.entries()) {
+        const label = record.id ?? `line ${index + 1}`;
+        for (const field of ["id", "path", "kind", "reason", "createdAt", "retention", "cleanup", "owner", "labels", "status"]) {
+            if (!(field in record))
+                errors.push(`${label}: missing ${field}`);
+        }
+        if (record.id) {
+            if (ids.has(record.id))
+                errors.push(`${record.id}: duplicate id`);
+            ids.add(record.id);
+        }
+        if (record.path && !isAbsolute(record.path))
+            errors.push(`${label}: path must be absolute`);
+        if (record.kind && !KINDS.has(record.kind))
+            errors.push(`${label}: unknown kind ${record.kind}`);
+        if (record.cleanup && !CLEANUP_ACTIONS.has(record.cleanup)) {
+            errors.push(`${label}: unknown cleanup ${record.cleanup}`);
+        }
+        if (!Array.isArray(record.labels))
+            errors.push(`${label}: labels must be an array`);
+        if (record.status && !STATUSES.has(record.status))
+            errors.push(`${label}: unknown status ${record.status}`);
+        if (!validRetention(record))
+            errors.push(`${label}: invalid retention`);
+        if ((record.status === "active" || record.status === "review-required") && record.path && !existsSync(record.path)) {
+            warnings.push(`${label}: recorded path is missing`);
+        }
+        if (record.status === "trashed") {
+            if (!record.cleanupPlanId)
+                errors.push(`${label}: trashed record missing cleanupPlanId`);
+            if (!record.receiptPath)
+                errors.push(`${label}: trashed record missing receiptPath`);
+            if (!record.cleanedAt)
+                errors.push(`${label}: trashed record missing cleanedAt`);
+            if (!record.targetPath) {
+                errors.push(`${label}: trashed record missing targetPath`);
+            }
+            else if (!existsSync(record.targetPath)) {
+                warnings.push(`${label}: trashed target path is missing`);
+            }
+        }
+        if (record.status === "review-required" || record.status === "cleanup-refused") {
+            if (!record.cleanupPlanId)
+                errors.push(`${label}: ${record.status} record missing cleanupPlanId`);
+            if (!record.receiptPath)
+                errors.push(`${label}: ${record.status} record missing receiptPath`);
+            if (!record.cleanedAt)
+                errors.push(`${label}: ${record.status} record missing cleanedAt`);
+        }
+        if (record.status === "resolved") {
+            if (!record.resolvedAt)
+                errors.push(`${label}: resolved record missing resolvedAt`);
+            if (!record.resolutionReason)
+                errors.push(`${label}: resolved record missing resolutionReason`);
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings, entries: records.length };
+}
+export function createCleanupPlan(ledgerPath) {
+    const plan = buildCleanupPlan(ledgerPath);
+    if (plan.entries.length === 0)
+        return noCreatedPlan(plan);
+    const existingPlan = matchingExistingCleanupPlan(ledgerPath, plan);
+    if (existingPlan) {
+        const refreshedPlan = {
+            ...plan,
+            planId: existingPlan.planId,
+            planPath: existingPlan.planPath
+        };
+        if (!refreshedPlan.planPath)
+            throw new Error("cleanup plan path was not created");
+        writeJson(refreshedPlan.planPath, refreshedPlan);
+        registerArtshelfArtifact(ledgerPath, refreshedPlan.planPath, {
+            reason: `Artshelf cleanup dry-run plan ${refreshedPlan.planId}`,
+            ttl: "14d",
+            kind: "run-artifact",
+            cleanup: "trash",
+            labels: ["artshelf", "cleanup-plan", refreshedPlan.planId]
+        });
+        return refreshedPlan;
+    }
+    if (!plan.planPath)
+        throw new Error("cleanup plan path was not created");
+    writeJson(plan.planPath, plan);
+    registerArtshelfArtifact(ledgerPath, plan.planPath, {
+        reason: `Artshelf cleanup dry-run plan ${plan.planId}`,
+        ttl: "14d",
+        kind: "run-artifact",
+        cleanup: "trash",
+        labels: ["artshelf", "cleanup-plan", plan.planId]
+    });
+    return plan;
+}
+export function previewCleanupPlan(ledgerPath) {
+    const plan = buildCleanupPlan(ledgerPath);
+    return plan.entries.length === 0 ? noCreatedPlan(plan) : plan;
+}
+export function createTrashPurgePlan(ledgerPath, olderThan) {
+    const plan = buildTrashPurgePlan(ledgerPath, olderThan);
+    if (plan.entries.length === 0)
+        return noCreatedTrashPurgePlan(plan);
+    if (!plan.planPath)
+        throw new Error("trash purge plan path was not created");
+    writeJson(plan.planPath, plan);
+    registerArtshelfArtifact(ledgerPath, plan.planPath, {
+        reason: `Artshelf trash purge dry-run plan ${plan.purgePlanId}`,
+        ttl: "14d",
+        kind: "run-artifact",
+        cleanup: "review",
+        labels: ["artshelf", "trash-purge-plan", plan.purgePlanId]
+    });
+    return plan;
+}
+export function previewTrashPurgePlan(ledgerPath, olderThan) {
+    const plan = buildTrashPurgePlan(ledgerPath, olderThan);
+    return plan.entries.length === 0 ? noCreatedTrashPurgePlan(plan) : plan;
+}
+export function executeTrashPurgePlan(ledgerPath, purgePlanId) {
+    if (!purgePlanId)
+        throw new Error("trash purge --execute requires --plan-id");
+    const planPath = trashPurgePlanPath(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 });
+                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 });
+    }
+    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)
+            ]
+        });
+        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)
+            ]
+        });
+    }
+    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 };
+}
+function readTrashPurgeReceipt(receiptPath) {
+    const receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+    return {
+        ...(typeof receipt.purgePlanId === "string" ? { purgePlanId: receipt.purgePlanId } : {}),
+        ...(typeof receipt.executedAt === "string" ? { executedAt: receipt.executedAt } : {}),
+        ...(typeof receipt.completedAt === "string" ? { completedAt: receipt.completedAt } : {}),
+        results: Array.isArray(receipt.results) ? receipt.results : []
+    };
+}
+function writeTrashPurgeReceipt(receiptPath, receipt) {
+    writeJson(receiptPath, receipt);
+}
+function pendingTrashPurgeResults(candidates, results) {
+    return candidates
+        .filter((pending) => !results.some((result) => result.id === pending.id))
+        .map((pending) => ({ id: pending.id, status: "pending", targetPath: pending.targetPath }));
+}
+function upsertTrashPurgeResult(results, next) {
+    return [...results.filter((result) => result.id !== next.id), next];
+}
+function noCreatedPlan(plan) {
+    return {
+        ...plan,
+        planId: "not-created",
+        planPath: null
+    };
+}
+function noCreatedTrashPurgePlan(plan) {
+    return {
+        ...plan,
+        purgePlanId: "not-created",
+        planPath: null
+    };
+}
+function buildCleanupPlan(ledgerPath) {
+    const generatedAt = now();
+    const records = readLedger(ledgerPath);
+    const due = dueEntries(records, generatedAt);
+    const entries = [];
+    const skipped = [];
+    for (const item of due) {
+        if (item.dueStatus === "kept") {
+            skipped.push({ id: item.id, path: item.path, reason: "retention has not expired", dueStatus: item.dueStatus });
+            continue;
+        }
+        if (item.dueStatus === "missing-path") {
+            skipped.push({ id: item.id, path: item.path, reason: "path is missing", dueStatus: item.dueStatus });
+            continue;
+        }
+        entries.push({ id: item.id, path: item.path, action: item.cleanup, dueStatus: item.dueStatus });
+    }
+    const planId = makePlanId(generatedAt);
+    const planPath = cleanupPlanPath(ledgerPath, planId);
+    const plan = {
+        planId,
+        generatedAt: toIso(generatedAt),
+        ledgerPath,
+        entries,
+        skipped,
+        planPath
+    };
+    return plan;
+}
+function buildTrashPurgePlan(ledgerPath, olderThan) {
+    const generatedAt = now();
+    const olderThanMs = ttlToMs(olderThan);
+    const cutoff = toIso(new Date(generatedAt.getTime() - olderThanMs));
+    const records = readLedger(ledgerPath);
+    const entries = [];
+    const skipped = [];
+    for (const record of records) {
+        if (record.status !== "trashed")
+            continue;
+        if (!record.id || !record.targetPath || !record.cleanedAt || !record.receiptPath || !record.cleanupPlanId) {
+            skipped.push({
+                id: record.id ?? "",
+                targetPath: record.targetPath ?? "",
+                reason: "trashed record missing cleanup metadata"
+            });
+            continue;
+        }
+        const cleanedAt = new Date(record.cleanedAt);
+        if (Number.isNaN(cleanedAt.getTime())) {
+            skipped.push({
+                id: record.id,
+                targetPath: record.targetPath,
+                reason: "invalid cleanedAt value"
+            });
+            continue;
+        }
+        if (cleanedAt.getTime() > generatedAt.getTime() - olderThanMs) {
+            skipped.push({ id: record.id, targetPath: record.targetPath, reason: `cleanedAt is newer than ${olderThan}` });
+            continue;
+        }
+        entries.push({
+            id: record.id,
+            targetPath: record.targetPath,
+            cleanedAt: record.cleanedAt,
+            receiptPath: record.receiptPath,
+            cleanupPlanId: record.cleanupPlanId
+        });
+    }
+    const purgePlanId = makePurgePlanId(generatedAt);
+    const planPath = trashPurgePlanPath(ledgerPath, purgePlanId);
+    return {
+        purgePlanId,
+        generatedAt: toIso(generatedAt),
+        ledgerPath,
+        olderThan,
+        cutoff,
+        entries,
+        skipped,
+        planPath
+    };
+}
+export function executeCleanupPlan(ledgerPath, planId) {
+    if (!planId)
+        throw new Error("cleanup --execute requires --plan-id");
+    const planPath = cleanupPlanPath(ledgerPath, planId);
+    if (!existsSync(planPath))
+        throw new Error(`Cleanup plan not found: ${planId}`);
+    const plan = JSON.parse(readFileSync(planPath, "utf8"));
+    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 { planId, receiptPath, results };
+}
+function registerArtshelfArtifact(ledgerPath, path, input) {
+    const prepared = prepareRecord({
+        path,
+        reason: input.reason,
+        ttl: input.ttl,
+        kind: input.kind,
+        cleanup: input.cleanup,
+        owner: "artshelf",
+        labels: input.labels
+    });
+    const records = readLedger(ledgerPath);
+    const index = records.findIndex((record) => (record.owner === "artshelf" &&
+        record.status === "active" &&
+        record.path === path &&
+        sameLabels(record.labels, input.labels)));
+    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,
+        labels: prepared.labels
+    };
+    writeLedger(ledgerPath, records);
+}
+function sameLabels(left, right) {
+    if (left.length !== right.length)
+        return false;
+    return left.every((label, index) => label === right[index]);
+}
+function matchingExistingCleanupPlan(ledgerPath, plan) {
+    const plansDir = join(dirname(ledgerPath), "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.ledgerPath !== ledgerPath)
+                continue;
+            if (cleanupPlanEntriesFingerprint(candidate) !== cleanupPlanEntriesFingerprint(plan))
+                continue;
+            return { ...candidate, planPath };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function cleanupPlanEntriesFingerprint(plan) {
+    return JSON.stringify(plan.entries.map((entry) => ({
+        id: entry.id,
+        path: entry.path,
+        action: entry.action,
+        dueStatus: entry.dueStatus
+    })));
+}
+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`);
+}
+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);
+}
+function updateLedgerAfterCleanup(ledgerPath, records, receipt) {
+    const resultById = new Map(receipt.results.map((result) => [result.id, result]));
+    const updated = records.map((record) => {
+        const result = resultById.get(record.id);
+        if (!result)
+            return record;
+        if (result.status === "trashed") {
+            return {
+                ...record,
+                status: "trashed",
+                cleanupPlanId: receipt.planId,
+                receiptPath: receipt.receiptPath,
+                cleanedAt: receipt.executedAt,
+                ...(result.target ? { targetPath: result.target } : {})
+            };
+        }
+        if (result.status === "review-required") {
+            return {
+                ...record,
+                status: "review-required",
+                cleanupPlanId: receipt.planId,
+                receiptPath: receipt.receiptPath,
+                cleanedAt: receipt.executedAt
+            };
+        }
+        if (result.status === "refused") {
+            return {
+                ...record,
+                status: "cleanup-refused",
+                cleanupPlanId: receipt.planId,
+                receiptPath: receipt.receiptPath,
+                cleanedAt: receipt.executedAt,
+                ...(result.reason ? { cleanupReason: result.reason } : {})
+            };
+        }
+        return record;
+    });
+    writeLedger(ledgerPath, updated);
+}
+function updateLedgerAfterTrashPurge(ledgerPath, records, receipt) {
+    const resultById = new Map(receipt.results.map((result) => [result.id, result]));
+    const updated = records.map((record) => {
+        const result = resultById.get(record.id);
+        if (!result || result.status !== "purged")
+            return record;
+        return {
+            ...record,
+            status: "resolved",
+            resolvedAt: receipt.executedAt,
+            resolutionReason: "trash purge completed",
+            purgedAt: receipt.executedAt,
+            purgePlanId: receipt.purgePlanId,
+            purgeReceiptPath: receipt.receiptPath
+        };
+    });
+    writeLedger(ledgerPath, updated);
+}
+function buildRetention(input, createdAt) {
+    if (input.manualReview)
+        return { retention: { mode: "manual-review" } };
+    if (input.ttl) {
+        return { retention: { mode: "ttl", ttl: input.ttl }, retainUntil: toIso(addTtl(createdAt, input.ttl)) };
+    }
+    if (input.retainUntil) {
+        const retainUntil = assertIsoDate(input.retainUntil, "--retain-until");
+        return { retention: { mode: "retain-until", retainUntil }, retainUntil };
+    }
+    throw new Error("Choose exactly one of --ttl, --retain-until, or --manual-review");
+}
+function classifyDue(record, at) {
+    if (!existsSync(record.path))
+        return "missing-path";
+    if (record.retention.mode === "manual-review")
+        return "manual-review";
+    if (!record.retainUntil)
+        return "due";
+    return new Date(record.retainUntil).getTime() <= at.getTime() ? "due" : "kept";
+}
+function validRetention(record) {
+    if (!record.retention || !("mode" in record.retention))
+        return false;
+    if (record.retention.mode === "manual-review")
+        return !record.retainUntil;
+    if (record.retention.mode === "ttl")
+        return Boolean(record.retention.ttl && record.retainUntil);
+    if (record.retention.mode === "retain-until")
+        return Boolean(record.retention.retainUntil && record.retainUntil);
+    return false;
+}
+function findGitRoot(cwd) {
+    let current = resolve(cwd);
+    while (true) {
+        if (existsSync(join(current, ".git")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function assertKind(kind) {
+    if (!KINDS.has(kind))
+        throw new Error(`Unknown kind: ${kind}`);
+    return kind;
+}
+function assertCleanup(cleanup) {
+    if (!CLEANUP_ACTIONS.has(cleanup))
+        throw new Error(`Unknown cleanup action: ${cleanup}`);
+    return cleanup;
+}
+function assertStatus(status) {
+    if (!STATUSES.has(status))
+        throw new Error(`Unknown status: ${status}`);
+    return status;
+}
+function assertResolveStatus(status) {
+    const normalized = assertStatus(status);
+    if (!RESOLVE_STATUSES.has(normalized)) {
+        throw new Error(`resolve currently supports --status resolved`);
+    }
+    return normalized;
+}
+function makeId(date) {
+    return `shf_${toIso(date).replace(/[-:]/g, "").replace("T", "_").replace("Z", "")}_${randomBytes(2).toString("hex")}`;
+}
+function makePlanId(date) {
+    return `plan_${toIso(date).replace(/[-:]/g, "").replace("T", "_").replace("Z", "")}_${randomBytes(2).toString("hex")}`;
+}
+function makePurgePlanId(date) {
+    return `purge_${toIso(date).replace(/[-:]/g, "").replace("T", "_").replace("Z", "")}_${randomBytes(2).toString("hex")}`;
+}
+function cleanupPlanPath(ledgerPath, planId) {
+    return join(dirname(ledgerPath), "plans", `${planId}.json`);
+}
+function trashPurgePlanPath(ledgerPath, purgePlanId) {
+    assertSafeGeneratedId(purgePlanId, "trash purge plan id");
+    return join(dirname(ledgerPath), "purge-plans", `${purgePlanId}.json`);
+}
+function receiptPathFor(ledgerPath, planId) {
+    return join(dirname(ledgerPath), "receipts", `${planId}.json`);
+}
+function trashPurgeReceiptPath(ledgerPath, purgePlanId) {
+    assertSafeGeneratedId(purgePlanId, "trash purge plan id");
+    return join(dirname(ledgerPath), "purge-receipts", `${purgePlanId}.json`);
+}
+function isPathWithin(parentPath, childPath) {
+    const fromParent = relative(resolve(parentPath), resolve(childPath));
+    return fromParent === "" || (!fromParent.startsWith("..") && !isAbsolute(fromParent));
+}
+function isStrictPathWithin(parentPath, childPath) {
+    const fromParent = relative(resolve(parentPath), resolve(childPath));
+    return fromParent !== "" && !fromParent.startsWith("..") && !isAbsolute(fromParent);
+}
+function resolvesOutsideLedgerTrash(ledgerDir, trashRoot, expectedPlanTrashRoot, targetPath) {
+    const realLedgerDir = realpathSync(ledgerDir);
+    const realTrashRoot = realpathSync(trashRoot);
+    const realExpectedPlanTrashRoot = realpathSync(expectedPlanTrashRoot);
+    const targetStats = lstatSync(targetPath);
+    const realTargetPath = targetStats.isSymbolicLink() ? realpathSync(dirname(targetPath)) : realpathSync(targetPath);
+    const targetWithinExpectedRoot = targetStats.isSymbolicLink()
+        ? isPathWithin(realExpectedPlanTrashRoot, realTargetPath)
+        : isStrictPathWithin(realExpectedPlanTrashRoot, realTargetPath);
+    return (!isStrictPathWithin(realLedgerDir, realTrashRoot) ||
+        !isStrictPathWithin(realTrashRoot, realExpectedPlanTrashRoot) ||
+        !targetWithinExpectedRoot);
+}
+function pathExistsForPurge(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function assertSafeGeneratedId(value, label) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+        throw new Error(`Invalid ${label}: ${value}`);
+    }
+}
+function writeJson(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}