Ovstorage User Delete Safely

Delete Safely

Goal: Remove objects without losing data you didn't mean to lose.

When to use this: Cleaning up after a job, removing stale state, or implementing user-initiated delete. Especially when the target is a directory or you're not 100% sure what's underneath it.

Single-object delete

Removes one object. Low risk — there's exactly one thing to delete.

{
  "tool": "ovstorage_delete",
  "arguments": {
    "address": "s3://my-bucket/temp/scratch.bin"
  }
}

Successful response:

{"v": "0.1", "ok": true, "operation": "ovstorage_delete", "result": {"ok": true}}

Directory delete: always dry-run first

Recursive directory deletes are dangerous. The tool requires an explicit dry_run parameter. Always run with dry_run: true first and review the plan.

Step 1: dry-run

{
  "tool": "ovstorage_delete_directory",
  "arguments": {
    "address": "s3://my-bucket/old-results/",
    "recursive": true,
    "dry_run": true
  }
}

Response shows what would be deleted:

{
  "v": "0.1",
  "ok": true,
  "operation": "ovstorage_delete_directory",
  "result": {
    "dry_run": true,
    "would_delete_count": 47,
    "would_delete_paths": [
      "s3://my-bucket/old-results/run-001/output.json",
      "s3://my-bucket/old-results/run-001/log.txt",
      "..."
    ]
  }
}

Read the count. Read enough of would_delete_paths to confirm the shape matches your intent. If anything surprises you, stop.

Step 2: execute

If the plan is right, repeat the call with dry_run: false:

{
  "tool": "ovstorage_delete_directory",
  "arguments": {
    "address": "s3://my-bucket/old-results/",
    "recursive": true,
    "dry_run": false
  }
}

Response:

{
  "v": "0.1",
  "ok": true,
  "operation": "ovstorage_delete_directory",
  "result": {"dry_run": false, "deleted": true}
}

Non-recursive directory delete

If you just want to remove an empty directory marker:

{
  "tool": "ovstorage_delete_directory",
  "arguments": {
    "address": "s3://my-bucket/empty/",
    "recursive": false,
    "dry_run": false
  }
}

This fails with DirectoryNotEmpty if anything's underneath.

What NOT to do

• Don't skip the dry-run. Even for "just a temp folder" — the dry-run is 100ms of work to catch a mistake that's hours of work to recover from.
• Don't paginate past 100k entries. The tool caps dry-run enumeration at 100,000 entries. If your prefix has more than that, you've targeted the wrong prefix or you need to delete in batches.
• Don't pass dry_run: false to "skip the confirmation." That's exactly what it does, and that's exactly the bug.

When things go wrong

See also

• ovstorage-user-list-and-paginate — dry-run reuses list internally
• ovstorage-user-handle-errors — when errors surface mid-operation