Architecture

High-level overview

Client SDK  ──WebSocket──►  Cosmictron  ──►  Your Logic (WASM/V8)
                               │                    │
                               │              ◄─────┘
                               │         mutations + queries
                               ▼
                          Real-Time Deltas
                          pushed to clients

Cosmictron is a single binary that combines:

Protocol gateway — WebSocket, PgWire, and HTTP REST
Module host — Wasmtime (WASM) and V8 (JavaScript) sandboxes
Query engine — SQL parser, cost-based planner, DBSP subscriptions
Storage engine — Page-based table store, MVCC, WAL, snapshot manager
Auth subsystem — JWT, email/password, passkeys, magic links

Protocol gateway

Three network surfaces share the same port (3000 by default):

Protocol	Use case
WebSocket (BSATN binary)	Client SDK connections, real-time subscriptions
PgWire	Connect existing Postgres tooling (psql, DBeaver, etc.)
HTTP REST	Admin operations, module publish, health checks

The gateway router detects the protocol, validates JWTs, resolves identity, applies rate limiting (per-client token bucket), and creates OpenTelemetry spans.

Module host

Your business logic runs as a module — a compiled WASM binary or a JavaScript file — loaded into an isolated sandbox.

WASM (Wasmtime)

Pre-instantiation for fast cold-start
Fuel metering — configurable CPU budget per reducer call
Memory limits — per-module heap cap
Host function ABI — the datastore, cosm, and console import modules (see WASM ABI)

JavaScript (V8)

OS-thread isolation — each module gets its own V8 isolate
Heap limits — configurable per-module
JavaScript modules are transpiled and executed inside the V8 runtime. Full V8 runtime groundwork is complete; production hardening is ongoing.

Query engine

Subscriptions are compiled into DBSP (Database Stream Processing) circuits. On each write:

Only the circuit subgraph affected by the changed rows is recomputed
Joins are incremental — O(delta), not O(N)
Aggregations are incremental — COUNT(*), SUM(amount) update in O(1) per row

Additional capabilities:

SQL parser via sqlparser-rs
Cost-based planner with statistics
Time-travel queries: SELECT ... AS OF TX <txid> and AS OF TIMESTAMP <ts>
Row-level security policy injection into every query plan

Storage engine

Table store

8 KB pages in a BTree structure
BTree and hash indexes
BlobStore for binary/large objects

Transaction manager

MVCC (Multi-Version Concurrency Control) with Optimistic Concurrency Control (OCC)
MutTx (write) and Tx (read) transaction types
Row-level conflict detection

Write-Ahead Log (WAL)

Append-only, segmented, checksummed
Configurable fsync policy: always, periodic, never
The WAL is also the event log used for deterministic replay and compliance signing

Snapshot manager

Background snapshots for fast recovery
Segment-level compaction

Auth subsystem

Built-in auth — no external identity provider required for basic use:

Email/password with bcrypt
Passkeys (WebAuthn)
Magic links (SMTP)
JWT tokens with configurable secret and expiry
Identity-aware row-level security via $identity variable

Compliance layer

An optional cryptographic layer that wraps the WAL:

Per-event Ed25519 signatures — each WAL entry signed on write
SHA-256 hash chain — each event links to the previous hash
RFC 3161 timestamps — trusted timestamping from an external TSA
FROST threshold signing — requires M-of-N key shares to sign (Coming Soon: DKG)
Signed bundle export — produces a self-contained tamper-evident archive

See Security & Compliance for the full breakdown.