design.md

AllocDB Engineering Design v0

Status

This file is the top-level engineering overview for the design.

For the detailed design docs, read:

• Semantics and API
• Alpha API
• Architecture
• Fault Model
• Lease Kernel Design Decisions
• Lease Kernel Follow-On
• Replication Notes
• Roadmap
• Work Breakdown
• Spikes
• Storage and Recovery
• Implementation Rules
• Testing Strategy
• AllocDB Principles

v1 Target

The first implementation target is intentionally narrow:

• single process
• single shard
• single writer and executor thread
• WAL plus snapshot recovery
• deterministic TTL expiration through logged events

Design Rules

1. The WAL is the source of truth.
2. Only the executor mutates allocation state.
3. Every state transition must be replayable from persisted input.
4. The state machine must not read wall-clock time, randomness, or thread interleavings.
5. Every hot-path structure has an explicit bound.
6. The trusted core targets allocation-free steady-state execution after startup.

Current implementation anchor:

• crates/allocdb-core contains the trusted-core allocator and durability logic
• crates/allocdb-node contains the first in-process single-node submission wrapper

Document Map

• semantics.md: domain model, identifiers, invariants, commands, retention
• api.md: transport-neutral alpha request/response surface and wire error schema
• architecture.md: single-node pipeline, logical time, bounds, scheduler
• fault-model.md: crash, clock, storage, and bounded-overload assumptions
• lease-kernel-design.md: concrete local M9 design direction for first-class leases, bundle ownership, fencing, and revoke
• lease-kernel-follow-on.md: post-M8 planning for minimal generic lease-kernel extensions such as bundle ownership, fencing, and revoke
• revoke-safety-slice.md: exact M9-T08 scope for revoke, reclaim, and safe-reuse behavior in the current implementation
• replication.md: deferred distributed design areas and boundaries
• roadmap.md: high-level roadmap and exit criteria
• work-breakdown.md: concrete units of work for the first implementation
• spikes.md: bounded throwaway experiments for implementation uncertainty
• storage.md: WAL, snapshots, recovery
• implementation.md: Rust memory policy, dependency policy, assertions
• testing.md: simulation, replay, property tests, Jepsen gate for replication