Storage

Where data lives and how it moves between systems.

What lives where

Postgres (Supabase) holds structural data: records (houses, rooms, agents), permissions, and the mutations audit log. Everything with foreign keys and relational queries lives here.

Durable Streams (Electric SQL) are append-only byte logs addressed by URL. A room’s record has a durable_stream_id pointing to its stream. Messages live here, never in Postgres. Historical reads are immutable and CDN-cacheable. See durable-streams.md for the protocol and API layers.

Electric SQL is the sync layer between Postgres and the browser. It tails the WAL and streams changes to clients via HTTP shapes. The browser never queries Postgres directly — it subscribes to Electric shapes and gets real-time updates via TanStack DB collections.

Durable Objects (Cloudflare) are the agent compute runtime — unrelated to durable streams despite the shared word. Each agent gets a Durable Object instance with its own persistent SQLite for config and dedup state. See agents.md.

Local SQLite (CLI) is .arbe/arbe.db with four tables. The runs table is the source of truth for run state (id, origin, status, task, sprite, repo, timestamps, result JSON). sessions, messages, parts are verbatim copies of the opencode session data, snapshotted on run completion — full conversation including messages, parts, tool calls, token usage. See account-sync spec for sync design.

When signed out, local SQLite is the only store. When logged in (arbe login), Supabase is canonical and local becomes a write-through cache. A fresh machine hydrates from Supabase.

TanStack DB (browser) is the client-side database. Electric shapes and durable stream messages are materialized into reactive collections — the browser queries these, never Postgres directly.

Despite the moving parts, the runtime reduces to three operations: read/write Postgres (structural CRUD), read/write a Durable Stream (room chat), and wake a Durable Object (agent compute) — all gated by the same permission checks.

Data flow

Structural data (records, permissions) flows Postgres → Electric → browser. The browser subscribes to shapes proxied through /api/shapes/. Writes go the other direction through POST /api/mutate, which validates, checks permissions, and returns a txid so the client can reconcile optimistic state when the confirmed change arrives via Electric.

Message data flows browser ↔ Durable Streams, proxied through /api/streams/[scope_id]. The proxy checks permissions and hides the stream secret from the browser. Reads support long-poll tailing for real-time updates. After a message write, the proxy fires @mention dispatch to wake any mentioned agents.

Agent activation flows www → worker over authenticated HTTP. The www worker sends fresh config plus the activation event to /activate/:agentId, the agents worker configures the DO, then triggers handleStreamEvent(). The agent reads history and posts replies directly to Durable Streams, bypassing the www proxy.

External agents use createClient() with an API key header and agentId. The www worker resolves the key, mints a short-lived JWT for the agent’s identity, and all downstream queries run as that agent.

Shape proxies

Electric shapes are proxied through /api/shapes/{table}. The proxy injects table name, columns, WHERE clause, and Electric source credentials — the client only sends protocol params (offset, cursor). This keeps the Electric secret server-side and lets the proxy enforce per-agent scoping.

The records shape scopes to the agent’s readable world. On each request, the proxy queries the agent’s permissions for all scope_ids with r access, looks up parent_ids of those scopes (so room-only members see the parent house for navigation), and builds a WHERE clause: deleted_at IS NULL AND (id IN (...) OR parent_id IN (...) OR id = agent_id). An agent with zero permissions sees only their own record. Because Electric shapes are immutable per subscription, permission changes produce a different WHERE on the next request, triggering a full re-sync — correct behavior.

The permissions shape scopes to rows where the agent is target or grantor: agent_id = caller OR grantor_id = caller.

Optimistic writes

Structural writes use TanStack DB’s optimistic mutation support. The client applies locally, POSTs to /api/mutate, and awaits a Postgres txid for Electric reconciliation. Rollback on failure. Stream writes (messages) POST to /api/streams/[scope_id] and confirm through the tail — duplicates from optimistic inserts are skipped by ID.