Orphan cleanup: Behavior and interfaces

Defines conservative reconciliation and deletion for unowned storage objects and missing objects using durable upload intents, grace periods, quarantine, bounded batches, and auditable outcomes.

Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.

Decision

Classify orphans from both database and storage evidence; never delete from a single negative lookup. Quarantine eligible unowned objects through a grace period, recheck ownership, then delete by exact immutable key.

Scope

• Upload-intent lifecycle, storage inventory, ownership reconciliation, classification, quarantine, restore, deletion, rate limits, and audit.
• Objects without committed owners and ownership records whose objects are missing.
• Dry-run and protected execution interfaces.

Outside this block

• User-requested deletion of valid files.
• Bucket-wide recursive deletion or physical cross-project de-duplication.

Contract

• Cleanup joins storage inventory, ownership records, active upload intents, legal/retention holds, and object age.
• A recent or active multipart/upload intent protects the object even when ownership has not committed.
• Candidates first enter quarantine with reason, evidence snapshot, classifier version, and delete_after time.
• Deletion rechecks all protections and addresses one exact key plus observed version or generation.
• Missing-object records are reported and repaired through a separate path; their database owners are not silently deleted.
• Dry-run and execution use the same classifier and produce count and byte summaries by tenant without exposing names.

Implementation guidance

• Inventory with paginated listings and durable checkpoints; do not rely on holding the entire bucket in memory.
• Use a job identity and idempotent candidate/deletion records.
• Cap objects and bytes per run and isolate tenant or prefix blast radius.
• Provide a protected restore action during quarantine when bytes remain available.

Failure handling and safeguards

• If inventory or ownership sources are stale, stop destructive execution and retain candidates.
• If an object changes after classification, version preconditions prevent deletion.
• If deletion returns uncertain status, verify the exact object before retrying.

Verification and operations

• Measure classified, quarantined, restored, deleted, skipped, missing-owned, age, bytes, and source freshness.
• Alert on changes in candidate rate, large single-tenant volume, and any protected-object match.
• Periodically sample dry-run candidates manually and exercise quarantine restore.

The executable-looking examples in this package are fixtures and acceptance contracts. Run python tools/validate.py from the collection root to check package structure and metadata; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Names and numeric values in example.yaml are an adoption profile, not universal defaults.
• The adopting team must map actors, data classes, error vocabulary, and ownership to its system.

References

• No external normative source is required; this package defines a project decision.