Introduction
The Sovereign Engine is a planetary-scale, zero-garbage-collection, off-heap δ-CRDT database engine. It solves a specific, hard data problem: how to maintain a single, convergent, causally-attributable view of state across a large fleet of mutually-distrusting nodes that partition, heal, reorder, duplicate, and drop messages — while keeping the write/read hot path free of allocator pressure, futex stalls, and cache-line contention, and while being post-quantum-secure from day one.
Documentation basis
This portal is synthesized from the engine's Go source — every claim is grounded in a real package, type, and test.
The data problem it addresses
Most operational databases model state as either a mutable row (last-writer-wins, single site of truth) or an append-only operational log (event sourcing with a replay-based read model). Neither handles the planetary edge case well:
- a mutable row conflicts under concurrent multi-region writers;
- an operational log conflates what happened with what the system believed to be true at a given moment.
The Sovereign Engine instead models state as a tri-temporal CRDT — keyed simultaneously by:
system_time— when the system observed the fact,valid_time— when the fact was true in the real world,assertion_time— the causal/assertion epoch under which the fact was claimed,
with a fourth decision_time carried on the wire. State is an Add-Wins Set lattice element folded by a merge-union Join, so concurrent writers converge without coordination and without losing history.
The durable tier materializes this tri-temporal lattice as an off-heap LSM tree (SkipListArena MemTable → per-entity Arrow IPC L0 files → merged L1 files) with bitemporal point-in-time (AsOf) and interval (Range) queries, a read-your-writes live δ-CRDT HAMT merge, and tri-temporal dominance pruning with an auto-inferred garbage-collection horizon.
Operating envelope
| Metric | Value | Source / caveat |
|---|---|---|
| CRDT core microbench (NOT ingest) | 50,736,038 ops/s gate-passing floor → 57,638,422 residency high at GOMAXPROCS=32, ARM64 Graviton | CORE microbench — in-process HAMT.Set crucible: no Ed25519 verify, no envelope, no network, no TLS, no persistence. Range 50.7M–57.6M across clean runs; the 57.6M is a residency high-end, not "sustained". Load-bearing contrast: 1.1M ops/s with false sharing vs this range (1.6% efficiency). Provenance: upstream pre-fork silicon (cache-line post-mortem SHA f719be4, not in this fork's git history); this-fork 32c re-run PENDING |
| Production ingest rate | 1.0M–3.1M deltas/sec at 64c, N=256 batching | The rate a real operator driving the receive endpoint sees — with signatures, envelopes, network. ~17–57× below the core number, because the core number omits the ~60µs/batch Ed25519 verify |
| Hot-path allocations | 0 allocs/op for HAMT.Set | TestHotPathZeroAllocations (pkg/sync/physics_test.go); raceEnabled build-tag pair self-skips under -race |
End-to-end Join benchmark | ~5.5M ops/s, ~8174 ns/op, 472 B/op, 6 allocs/op | BenchmarkCRDTEngine_Join at 2 GiB arena; 64 MiB arena panics HamtArena: OOM at ~1M ops due to reclamation lag |
| Silicon ingest (Day 7, corrected) | 1M events/sec (N=256 clears the bar; N=100 straddles) | Corrected for the *GOMAXPROCS double-count bug (b.RunParallel ns/op is already aggregate) |
| Ed25519 verify cost | ~60.19 µs/op | The crypto-dominated ingress cost; the cheap-gate stack exists to drop forged frames before this verify |
| ML-DSA-65 (post-quantum preview) | sig = 3309 B, pub = 1952 B (51.7× sig inflation vs Ed25519 64 B) | filippo.io/mldsa; pq_preview build-tagged, preview-only |
Throughput-honesty disclosure
The 50.7M–57.6M ops/s range is the CRDT CORE microbenchmark — the in-process HAMT.Set data-structure floor with everything else stripped out — not the production ingest rate (which is 1.0M–3.1M deltas/sec). Quoting 57.6M alone as "the Sovereign Engine's sustained throughput" is a hero-number round-up the cache-line post-mortem explicitly forbids; we show the floor, the high, and the ingest rate together so no single figure can be misread. Provenance: the 32c core number was measured upstream pre-fork (post-mortem SHA f719be4, not in this fork's git history); this fork's 32c re-run of RUN_CRUCIBLE=1 go test -run TestStage5ScalingGate ./pkg/sync/ is PENDING.
The majority of component-level benches in the tree are honestly measured on a 4-core 0xd40 (Cortex-A76-class / Graviton-3-era) gear and carry a _4c tag; the _32c tag is a roadmap target, not honest measured gear. A gear-honesty test gate (TestGate_GearHonesty) actively forbids relabeling a 4-core number as 32-core. Numbers are reported here as numbers, never as adjectives.
Where to go next
- Core Architecture & Design — the layered packages and the end-to-end request/data flow.
- Design Rationale — the five physical laws and why each is non-optional.
- Key Features & Specialties — the concrete specialties, with where each lives.
- Quickstart — run a node and write/read through the SDK.
- Integration & Usage — the binary, the SDK, the control surface, and an honest readiness assessment.
- Primary Use Cases — where the engine excels.