Definition
Version history is the model that keeps previous states of a file or object after new writes arrive.
Instead of treating a file as one mutable blob:
file_id -> bytes
a sync system stores a sequence of versions:
file_id f1
version 7 -> manifest_a
version 8 -> manifest_b
version 9 -> manifest_c
current_version = 9
The current pointer changes. Older versions remain available according to retention policy.
The Pain That Forces This Concept
Without version history, every overwrite is dangerous.
A client bug can replace good data with corrupted data. A stale offline device can upload an old version. A user can delete important content and only notice later. A sync conflict can be resolved poorly. A ransomware-style change can rewrite many files.
If the system only keeps the latest state, recovery depends on backups or luck.
Version history gives the product a normal recovery path.
Mental Model
Treat the file identity as stable and each content state as append-only.
file node: report.docx
version 1: original upload
version 2: edits from laptop
version 3: edits from tablet
version 4: restored version 2
Restoring an old version usually creates a new current version. It should not mutate history in place.
How It Works
A version record may store:
file_version
- version_id
- file_id
- parent_version_id
- manifest_id
- created_by_device_id
- created_at
- size_bytes
- content_hash
- mutation_id
- change_reason
With chunking, old and new versions can share most chunks. This makes version history cheaper than storing every whole file again.
The metadata record points at the current version:
file_node.current_version_id = v9
The version table provides restore, audit, conflict inspection, and repair.
Tradeoffs
| Benefit | Cost |
|---|---|
| Recover from bad overwrites | More storage and metadata |
| Helps debug sync bugs | Retention policy gets complex |
| Supports conflict recovery | Users may see confusing version trees |
| Enables restore after delete | Garbage collection must respect references |
| Improves trust | Privacy and compliance rules matter |
Version history is not free. The system must define how long to keep versions, who can view them, how sharing applies to old versions, and when chunks can be garbage collected.
Operational Reality
Operators should monitor:
- version creation rate
- restore rate
- version storage growth
- shared chunk ratio
- garbage collection lag
- versions blocked from deletion
- corrupted version reports
- restore failures
Failure modes:
- Current version pointer advances before chunks are durable.
- Garbage collection removes chunks still referenced by an old version.
- Restore bypasses permission checks.
- Version history grows without retention enforcement.
- Conflict versions are hidden from users.
- Delete recovery conflicts with compliance deletion rules.