Deleting Documents (Delete)

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• IMPLEMENTATION_PLAN.md
• crates/sentinel/src/lib.rs
• Cargo.toml
• crates/sentinel/Cargo.toml
• CODE_OF_CONDUCT.md
• rustfmt.toml

The document deletion feature in Cyberpath Sentinel is designed around the core principles of the system: auditability, transparency, and compliance. Unlike traditional databases that might perform a physical "hard delete," Sentinel primarily employs a "soft delete" mechanism. This approach ensures that deleted data is recoverable and that a clear, auditable trail of the deletion event is preserved.

This design choice directly supports compliance requirements like GDPR's "right-to-delete" by providing a structured, traceable process for data removal. While the underlying filesystem-based architecture allows for a literal rm file.json, the standard library function implements a safer, non-destructive move operation.

Sources: README.md:21, 100-101, 153, IMPLEMENTATION_PLAN.md:215

Deletion Mechanism

Soft Deletes

The primary mechanism for deleting a document is a "soft delete." When a delete operation is requested, the document file is not permanently erased from the filesystem. Instead, it is moved from its active collection folder into a special, hidden sub-directory named .deleted/ within the same collection.

This approach has several key advantages:

• Auditability: The existence of the file in the .deleted/ folder serves as an audit record of the deletion.
• Recoverability: Accidental deletions can be easily reversed by moving the file back to the parent collection directory.
• Performance: A file move/rename is an O(1) atomic operation on most filesystems, making deletion extremely fast.

Sources: README.md:100-101, 120, IMPLEMENTATION_PLAN.md:46, 215

Filesystem Structure Change

The following diagram illustrates the change in the filesystem structure when a document is deleted.

This diagram shows the user-123.json file being moved into the .deleted directory within the users collection.

Sources: README.md:108-113, IMPLEMENTATION_PLAN.md:44-47

API and Usage

The deletion of a document is handled by the delete method on a Collection object. This is an asynchronous operation that takes the document's primary key (ID) as an argument.

Sources: IMPLEMENTATION_PLAN.md:113, README.md:99

Method Signature

The planned implementation for the delete method is defined as follows:

// From IMPLEMENTATION_PLAN.md
impl Collection {
    // ...
    pub async fn delete(&self, id: &str) -> io::Result<()>
    // ...
}

Sources: IMPLEMENTATION_PLAN.md:113

Example Usage

Here is a basic example of how to delete a document using the Rust client library.

// From README.md
use cyberpath_sentinel::Store;

// Create a store and collection
let store = Store::new("./data").expect("Failed to create store");
let users = store.collection("users").expect("Failed to create collection");

// ... insert document ...

// Delete a document (moves data/users/user-123.json to data/users/.deleted/user-123.json)
users.delete("user-123").expect("Failed to delete");

Sources: README.md:83-100

Transactional Deletes and Durability

To ensure data integrity, especially during system crashes, delete operations are designed to be part of the Write-Ahead Logging (WAL) system. Before the file is moved, a Delete entry is written to the transaction log.

Write-Ahead Log (WAL) Entry

The LogEntry enum includes a variant specifically for deletion operations. This ensures that if a crash occurs after the log is written but before the file is moved, the system can recover and complete the operation upon restart.

// From IMPLEMENTATION_PLAN.md
pub enum LogEntry {
    // ...
    Delete { collection: String, id: String },
    // ...
}

Sources: IMPLEMENTATION_PLAN.md:133, 137

Delete Operation Flow with WAL

The sequence diagram below shows how a delete operation interacts with the Transaction Log and the filesystem.

This diagram illustrates that the Delete action is first recorded in the WAL for durability before the actual file move is executed on the filesystem.

Sources: IMPLEMENTATION_PLAN.md:128-142

Performance and Compliance

The design of the delete operation directly impacts performance and the system's compliance-readiness.

Performance Characteristics

The table below summarizes the performance of the soft delete operation.

Characteristic	Description	Source
Time Complexity	O(1)	README.md:120
Mechanism	Filesystem rename/move	README.md:120
Durability	Ensured via Write-Ahead Logging (WAL)	IMPLEMENTATION_PLAN.md:128, 227
Auditability	File is preserved in .deleted/ folder	README.md:100-101

Compliance Implications

The soft delete mechanism is a foundational feature for regulatory compliance.

• GDPR (General Data Protection Regulation): While a physical rm command can satisfy the "right to be forgotten," the soft-delete mechanism provides a documented and auditable process. A separate, automated process can later perform a hard delete from the .deleted folder based on data retention policies.
• SOC 2 / ISO 27001: The preservation of deleted files and the logging of the delete event create an immutable audit trail, which is a key requirement for these standards.

Sources: README.md:21, 100, 126, IMPLEMENTATION_PLAN.md:301-302, 321

Summary

In Cyberpath Sentinel, deleting a document is a fast, safe, and auditable operation. By implementing deletion as a "soft delete" (a file move to a .deleted/ directory), the system preserves data for recovery and auditing purposes. This O(1) operation is integrated with the Write-Ahead Log to guarantee durability. This design is central to Sentinel's mission of providing a database that is transparent, trustworthy, and compliant by default.

Sources: README.md:15, 100-101, 120, IMPLEMENTATION_PLAN.md:215