Skip to content

Commit 3dd7215

Browse files
committed
docs(service): Document tombstone consistency invariant
1 parent 2f5254a commit 3dd7215

File tree

1 file changed

+15
-0
lines changed

1 file changed

+15
-0
lines changed

objectstore-service/docs/architecture.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,21 @@ A redirect tombstone is an empty object with
4646
in its metadata. It acts as a signpost: "the real data lives in the other
4747
backend."
4848

49+
### Consistency Without Locks
50+
51+
The tombstone system maintains consistency through operation ordering rather
52+
than distributed locks. The invariant is: a redirect tombstone is always the
53+
**last thing written** and the **last thing removed**.
54+
55+
- On **write**, the real object is persisted before the tombstone. If the
56+
tombstone write fails, the real object is rolled back.
57+
- On **delete**, the real object is removed before the tombstone. If the
58+
long-term delete fails, the tombstone remains and the data stays reachable.
59+
60+
This ensures that at every intermediate step, either the data is fully
61+
reachable (tombstone points to data) or fully absent — never an orphan in
62+
either direction.
63+
4964
### How Each Operation Handles Tombstones
5065

5166
**Read** ([`StorageService::get_object`], [`StorageService::get_metadata`]):

0 commit comments

Comments
 (0)