Add Deep Database Style by cloutiertyler · Pull Request #4925 · clockworklabs/SpacetimeDB

cloutiertyler · 2026-04-30T19:19:17Z

Summary

Adds docs/DEEP_DATABASE_STYLE.md, a style guide for the deep core of the SpacetimeDB database (datastore, commitlog, snapshotting, replication).

Read the rendered document

The document is organized around seven principles:

Work towards zero dependencies
Work towards deterministic simulation testing
Work towards thread-per-core
Work towards no_std
Think in terms of persistent data structures
Think in terms of pipelining
Think in terms of unreliable processes
Think in terms of assertions

A short style section follows the principles, covering assertions, bounded loops and queues, error handling, control flow, naming, and formatting. Inspired by TIGER STYLE, narrowed and adapted for Rust and our principles.

This is a seed document. It will grow as we make the principles operational in code and as the practices that serve them become clearer with use.

Test plan

Read the document and review the principles
Discuss any principle the team disagrees with before merging

Replaces SPACETIME_PROGRAMMING_STANDARDS.md with DEEP_CORE_STYLE.md. The document is reorganized around seven principles for the core (datastore, commitlog, snapshotting, replication): 1. Work towards zero dependencies 2. Work towards deterministic simulation testing 3. Work towards thread-per-core 4. Work towards no_std 5. Think in terms of persistent data structures 6. Think in terms of pipelining 7. Think in terms of unreliable processes A short style section follows the principles, covering assertions, bounded loops and queues, error handling, control flow, naming, and formatting.

- Rename DEEP_CORE_STYLE.md to DEEP_DATABASE_STYLE.md and retitle to "Deep Database Style". The "deep core" remains the term we use for the core of the database inside the document. - §4 (no_std): note that an allocator-trait-based, per-resource-type approach is the natural Rust expression, and that the resulting intrusion in the datastore is expected, not a cost to avoid. - §5 (persistent data structures): clarify the principle is about the externally observable behavior of the system, not a ban on mutable internals. Components may still use mutable, non-persistent structures internally. - §7 (unreliable processes): make corruption explicit, including cosmic rays and ordinary hardware faults; tie back to Merkle structures from §5. - Style/Control flow: drop the parts I do not feel strongly about (compound-condition splitting, positive invariant phrasing); keep and expand the macros guidance. - Style/Comments: allow short what-summaries for genuinely complex logic, while still warning about drift between comments and code.

Two additions to DEEP_DATABASE_STYLE.md. Principle 8: Think in terms of assertions. Type systems prove a class of properties at compile time; assertions extend that proof system to properties the compiler cannot express, and combined with principle 2 they cover the rest. Assertion failures are programmer errors and the only correct response is to crash. The principle adds two rules that follow from "assertions are always on": - Use assert!, not debug_assert!. Stripping the check in release reduces an assertion to a comment that runs sometimes, which defeats the point. A failing assertion in production tells us our model was wrong, and production is exactly where we want to know. - Isolate before you assert. An assertion failure must crash only the smallest unit of correctness it bounds. An assertion in code that handles one database's transaction takes down that database's worker, not every database hosted on the same process. Without isolation, "panic on assertion failure" is strictly worse than not asserting. Per-tenant thread plus catch_unwind is one realization; OS process per tenant is another. The existing Style/Assertions sub-section becomes the mechanics that put principle 8 into practice (preconditions, paired checks, positive/negative space, splitting, compile-time assertions). Style addition: "Use explicit integer sizes; never usize." `usize` and `isize` are pointer-width and break cross-target determinism (principle 2). The rule and its rationale come from operating experience with our wasm + native split. Intro updated to "eight principles."

cloutiertyler added 2 commits January 12, 2026 17:21

Initial pass

2da376e

cloutiertyler requested a review from aasoni May 1, 2026 14:39

cloutiertyler and others added 2 commits May 1, 2026 10:44

Merge branch 'master' into tyler/programming-standards

a6b847a

Merge branch 'master' into tyler/programming-standards

e614280

aasoni approved these changes May 7, 2026

View reviewed changes