Storage Backends (Current Status)

Graviton’s runtime is built around small “ports” (interfaces) such as BlobStore, BlockStore, ImmutableObjectStore, and MutableObjectStore. Backend modules implement those ports.

This page describes what exists in the repository today, and what is still scaffolded.

Summary

Module	Implements	Status
modules/graviton-runtime	InMemoryBlockStore (main); InMemoryBlobStore (test sources only)	✅ block store + Graviton.inMemory() for full CAS in demos/tests
modules/backend/graviton-pg	PgBlobManifestRepo, object-store ports, indexes	✅ PgBlobManifestRepo is used by the server; other ports are still stubbed/placeholder
modules/backend/graviton-s3	S3BlockStore, object-store ports	✅ S3BlockStore supports put/get/exists (used by the server); other ports are still evolving
modules/backend/graviton-rocks	RocksKeyValueStore	⚠️ currently stubbed / placeholder behaviors

In-memory reference stores

• Block store: graviton.runtime.stores.InMemoryBlockStore implements BlockStore.putBlocks, deduplicates blocks, and can synthesize BlockFrame values when framing plans are supported.
• Blob store (tests): InMemoryBlobStore in src/test implements BlobStore for unit tests (streaming put / get).
• Full stack without DB: Graviton.inMemory() composes CasBlobStore + in-memory manifests — the usual choice for examples and integration tests that need BlobStore from main sources.

Start with Graviton.inMemory() or Graviton.fs(...) when you want an end-to-end blob API; use InMemoryBlockStore when you are testing block-level behavior directly.

PostgreSQL backend module (graviton-pg)

The Postgres module currently provides both real, server-used components and scaffolding:

• Manifest storage (used by the server):
  • PgBlobManifestRepo persists blob manifests (the server composes it with a BlockStore into CasBlobStore).
• Object-store + index ports (scaffolding):
  • PgImmutableObjectStore, PgMutableObjectStore, PgReplicaIndex, PgKeyValueStore, PgRangeTracker are present primarily as wiring points and will be filled in as the storage APIs stabilize.

If you are looking for the actual database schema used by Graviton’s evolving data model, see:

• Postgres schema notes

S3 backend module (graviton-s3)

The S3 module contains a functional BlockStore plus additional ports that are still evolving:

• Block storage (used by the server):
  • S3BlockStore supports putBlocks, get, and exists and is designed to work against MinIO/S3-compatible endpoints.
• Object-store ports (scaffolding):
  • S3ImmutableObjectStore / S3MutableObjectStore exist but are not the primary “happy path” today.

The server currently uses PostgreSQL for manifests plus S3/MinIO for blocks, composed via CasBlobStore.

Rocks backend module (graviton-rocks)

The Rocks module currently exposes a stub RocksKeyValueStore implementing KeyValueStore. It’s a wiring point for later work; it should not be treated as a durable backend yet.

See also

• Runtime ports — the interfaces backends implement
• Replication — current replica index capabilities and roadmap
• Architecture — where runtime vs backends fit in the module graph