photoncloud-monorepo/specifications/flaredb/001-distributed-core/data-model.md

Data Model: Core Distributed Architecture (Phase 1)

Entities

1. Key-Value Pair (Raw)

• Key: Vec<u8> (Arbitrary bytes)
• Value: Vec<u8> (Arbitrary bytes)
• Scope: rdb-storage (Raw Put)

2. Key-Value Pair (Versioned / CAS)

• Key: Vec<u8>
• Value: Vec<u8> (Metadata + Payload)
• Version: u64 (Monotonic sequence)
• Scope: rdb-storage (CAS)

3. TSO Timestamp

• Physical: u64 (48 bits, milliseconds)
• Logical: u64 (16 bits, counter)
• Combined: u64 (Physical << 16 | Logical)
• Scope: rdb-pd

State Transitions (CAS)

1. Empty -> Created:

   • Current Version: 0 (or None)
   • Expected Version: 0
   • New Version: TSO / Sequence > 0
   • Result: Success

2. Updated -> Updated:

   • Current Version: N
   • Expected Version: N
   • New Version: M (M > N)
   • Result: Success

3. Conflict:

   • Current Version: N
   • Expected Version: M (M != N)
   • Result: Failure (Returns N)

Storage Schema (RocksDB Column Families)

1. default (CF_DEFAULT):

   • Stores data for Raw Puts.
   • Key: Key
   • Value: Value

2. cas (CF_CAS - Proposed name for CAS data separation):

   • Stores versioned data.
   • Key: Key
   • Value: [Version: 8 bytes][Data...]
   • Note: Storing version in value simplifies atomic update via Read-Modify-Write or MergeOperator.