Motivation

Adds a plan + execute flow for cleanup so deletions become auditable. Per reviewer feedback on the original design, the plan now follows SQL EXPLAIN semantics: it is a read-only audit report, not a frozen deletion contract.

Design

• Plan is an EXPLAIN-style report. CleanupPlan exposes:

  • dataset_uri, base_path, policy, created_at — authoritative inputs reused by execution.
  • files, stats, referenced_branches, tagged_old_versions — informational; describe the dataset state observed at planning time.

• Execute re-plans against the current dataset state. cleanup_with_plan:

  1. Validates dataset_uri / base_path match the current dataset.
  2. Re-runs planning with plan.policy.
  3. Deletes from the freshly computed set.

  Tags, branches, and commits added after planning are naturally honored — including the cases where they do not advance the manifest version.

• Drops the read_version enforcement. latest_version_id does not move when new tags or branch refs are created, so the previous check did not protect against the TOCTOU case the reviewer raised. Re-planning is strictly stronger.

API

pub struct CleanupPlan {
    pub dataset_uri: String,
    pub base_path: String,
    pub policy: CleanupPolicy,
    pub created_at: DateTime<Utc>,
    pub files: Vec<CleanupFile>,
    pub stats: CleanupPlanStats,
    pub referenced_branches: Vec<CleanupReferencedBranch>,
    pub tagged_old_versions: Vec<u64>,
}

pub async fn plan_cleanup(dataset: &Dataset, policy: CleanupPolicy) -> Result<CleanupPlan>;
pub async fn cleanup_with_plan(dataset: &Dataset, plan: CleanupPlan) -> Result<RemovalStats>;

Impact

• Audit value is preserved: policy, referenced branches, tag-protected versions, and per-category stats are still surfaced.
• The actual delete set may differ from plan.files if the dataset changes between plan and execute. This upper-bound semantics matches SQL EXPLAIN and is documented on CleanupPlan and cleanup_with_plan.
• Public API shape is unchanged aside from removing the read_version field, which has not been released yet.

Tests

• cleanup_with_plan_reevaluates_against_concurrent_commit — execute after a concurrent commit succeeds and removes the correct set.
• cleanup_with_plan_handles_encoded_paths — re-planning still discovers temp manifests with URL-unsafe names.
• Replaced tests that asserted on read_version with behavior-level coverage of the new semantics.