[ENH]: perform collection hard deletes from garbage collector

[codetheweb]

Description of changes

This updates the garbage collector to transition soft deleted collections to hard deleted when eligible.

Test plan

How are these changes tested?

• Tests pass locally with pytest for python, yarn test for js, cargo test for rust

I updated the proptest with a new transition for deleting collections.

Documentation Changes

Are all docstrings for user-facing APIs updated if required? Do we need to make documentation changes in the docs section?

n/a

[github-actions]

Reviewer Checklist

Please leverage this checklist to ensure your code review is thorough before approving

Testing, Bugs, Errors, Logs, Documentation

• Can you think of any use case in which the code does not behave as intended? Have they been tested?
• Can you think of any inputs or external events that could break the code? Is user input validated and safe? Have they been tested?
• If appropriate, are there adequate property based tests?
• If appropriate, are there adequate unit tests?
• Should any logging, debugging, tracing information be added or removed?
• Are error messages user-friendly?
• Have all documentation changes needed been made?
• Have all non-obvious changes been commented?

System Compatibility

• Are there any potential impacts on other parts of the system or backward compatibility?
• Does this change intersect with any items on our roadmap, and if so, is there a plan for fitting them together?

Quality

• Is this code of a unexpectedly high quality (Readability, Modularity, Intuitiveness)

[codetheweb]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• [ENH]: perform collection hard deletes from garbage collector #4605 👈 (View in Graphite)
• [ENH]: sysdb changes to support moving collection hard deletes to garbage collector #4607
• [ENH]: add validation during garbage collection for empty file paths #4586
• [ENH]: garbage collector v2 orchestrator (supports forking) #4468
• [ENH]: allow deleting v0 from version file & correctly propagate errors on DeleteCollectionVersion #4579
• [ENH]: add operator for garbage collection to list all files used by collection version #4466
• [ENH]: add operator to compute versions to garbage collect from version graph #4464
• [ENH]: add orchestrator to construct version graph for garbage collection #4463
• [ENH]: add batch get version file paths method to Sysdb #4432 : 1 other dependent PR (#4447 )
• [ENH]: SysDb should return lineage, version file paths and root collection ID on collections #4557
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[codetheweb]

changes in this file provide a little more debugging info + a new defensive check

[propel-code-bot]

Garbage Collector Now Performs and Finalizes Collection Hard Deletes

This PR reworks the garbage collection pipeline to transition eligible soft-deleted collections to hard-deletion from within the garbage collector, rather than relying on side effects elsewhere. The change spans the garbage collector's orchestrator, its operators, system database abstraction, test suites, and API error types, introducing a new batch interface for querying soft delete status, wiring through relevant status checks, and implementing the full hard delete logic when conditions are met (e.g., no live forks). Defensive checks and additional test coverage for fork scenarios are added to ensure correctness.

Key Changes:
• Garbage collector orchestrator (rust/garbage_collector/src/garbage_collector_orchestrator_v2.rs) identifies soft-deleted collections and, after pruning versions/files, finalizes deletion by invoking sysdb hard delete.
• Introduced batch_get_collection_soft_delete_status interface and error type in sysdb and types to efficiently check collection states.
• sysdb now exposes finish_collection_deletion to finalize/hard delete collections as needed, implemented for GrpcSysDb and TestSysDb.
• Garbage collection test harness and reference state machine reworked to explicitly model collection status transitions (Alive -> SoftDeleted -> Deleted); proptests extended to exercise these states.
• Operators (compute_versions_to_delete_from_graph.rs) and orchestrator now propagate soft-deleted collection information throughout the deletion pipeline, ensuring all versions are marked for deletion.
• Additional and improved proptests and defensive graph checks added, particularly to handle forked collection trees and ensure graph invariants.
• API/types extended for soft delete batch status error propagation and handling.

Affected Areas:
• Garbage collector orchestrator logic
• Garbage collector operators (version deletion logic)
• SysDb abstraction (Rust and test backends, Grpc implementation)
• Test harness and property-based (proptest) tests
• API/types error and status handling

Potential Impact:

Functionality: Enables fully-automated, stateful transition from soft-deletion to true ('hard') deletion of collections only when all fork-children are deleted. Reduces possibility for orphaned data and greatly clarifies deletion flow.

Performance: Batch status queries for soft delete state should scale well, avoiding N calls. Deletion up to O(number of collections) hard deletes may marginally increase load during GC tasks.

Security: No negative impact; possibly positive in ensuring prompt, correct, final deletion for user data.

Scalability: Batching and explicit transition handling should enable robust handling even in large forked-collection graphs.

Review Focus:
• Correctness of forked collection deletion logic (ensuring no live children pre-hardelete).
• SysDb API compatibility across backends.
• Atomicity and idempotency of hard delete transitions (especially on crash/retry).
• Proptest/test coverage for edge GC/delete cases.
• Backward compatibility for collection state transitions and error error propagation.

Testing Needed

• Run the full test suite, especially all proptests in garbage_collector/tests/ to validate complex fork/GC/delete transitions.
• Test end-to-end deletion cycle (create, fork, delete, GC) in integration/staging with both normal and forked collections.
• Check sysdb Grpc and Test implementations for hard delete propagation.
• Exercise batch soft delete query API for regressions.

Code Quality Assessment

rust/garbage_collector/tests/proptest_helpers/garbage_collector_under_test.rs: Adapts to the new logic; validation and check_invariant logic improved to cover all status transitions.

rust/garbage_collector/src/garbage_collector_orchestrator_v2.rs: Clear organization, correct async/await discipline, explicit error propagation, effective defensive checks.

rust/garbage_collector/src/operators/compute_versions_to_delete_from_graph.rs: Improved logic for status filtering; code is thoroughly tested via added and updated property-based tests.

rust/sysdb/src/sysdb.rs: Well-structured, new API introduces minimal disruption, maintainable extension.

rust/garbage_collector/tests/proptest_helpers/garbage_collector_reference.rs: Complex but clear; new status model brings explicitness.

Best Practices

Error Handling:
• Consistent error typing and propagation
• Use of defensive programming (graph component check)

Test Coverage:
• Extensive use of property-based/proptest and new integration tests

Modularity:
• Changes localized per-responsibility (operators, orchestrator, sysdb, types)
• API boundary expansion performed cleanly

Potential Issues

• Edge case: If sysdb or GC crashes mid-hard-delete, double-deletion should be idempotent but should be validated.
• Compatibility: TestSysDb and SQLite sysdb backends have unimplemented stubs for new calls - should not be used in production.
• Potential race if forked collections are quickly created/deleted in parallel; needs attention in prod load.

This summary was automatically generated by @propel-code-bot