feat(api): track Durable Object instances with storage usage

[braden-w]

Why this exists

Every Epicenter user gets their own Durable Objects—workspace rooms for structured metadata, document rooms for content with version history. Until now, the API had no visibility into which DOs exist per user or how much storage they consume. We need this for a user dashboard ("here are your workspaces and their sizes") and eventually for usage-based billing.

The challenge: we can't query Cloudflare for a list of DO instances or their storage externally. The only way to measure storage is from inside the DO via ctx.storage.sql.databaseSize. So we piggyback on existing RPC calls that are already happening.

How it works

┌─────────┐    sync(body)     ┌──────────────┐
│  Client  │ ───────────────► │  Hono Worker  │
└─────────┘                   └──────┬───────┘
                                     │
                          ┌──────────┴──────────┐
                          │                     │
                     stub.sync()          upsertDoInstance()
                          │                     │
                    ┌─────▼─────┐        ┌──────▼──────┐
                    │ Durable   │        │  Postgres   │
                    │ Object    │        │ (Hyperdrive)│
                    │           │        │             │
                    │ returns:  │        │ INSERT ...  │
                    │ {diff,    │        │ ON CONFLICT │
                    │  storage  │        │ DO UPDATE   │
                    │  Bytes}   │        └─────────────┘
                    └───────────┘

The Worker already calls stub.sync() and stub.getDoc() on every request. We added storageBytes to the return value (read from ctx.storage.sql.databaseSize inside the DO—zero extra cost) and fire a non-blocking upsert to Postgres via the afterResponse queue. The upsert completes before the DB connection closes but doesn't block the HTTP response to the client.

The afterResponse pattern

// Route handler — fire and forget
c.var.afterResponse.push(
  upsertDoInstance(c.var.db, { userId, doType, resourceName, doName, storageBytes })
);
return new Response(diff, { ... }); // Response goes out immediately

// Middleware — drain queued promises, then close DB connection
finally {
  c.executionCtx.waitUntil(afterResponse.drain().then(() => client.end()));
}

createAfterResponseQueue() encapsulates the promise collection with push() and drain() methods. drain() settles all queued promises via Promise.allSettled, and cleanup (closing the pg connection) is chained by the caller via .then()—drain() itself takes no parameters. The Promise<unknown> typing is the semantic contract for fire-and-forget: we track promises to completion but never inspect what they resolve to.

DO naming convention alignment

This PR builds on the naming convention change from #1520 (user:{userId}:{type}:{name}). The 6 upsert calls in route handlers construct doName with the type segment, matching getWorkspaceStub/getDocumentStub:

doName: `user:${userId}:workspace:${resourceName}`
doName: `user:${userId}:document:${resourceName}`

Schema

CREATE TABLE durable_object_instance (
  user_id              text      NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
  do_type              text      NOT NULL,   -- 'workspace' | 'document'
  resource_name        text      NOT NULL,   -- e.g. 'epicenter.tab-manager'
  do_name              text      PRIMARY KEY, -- e.g. 'user:abc:workspace:epicenter.tab-manager'
  storage_bytes        bigint,               -- latest measurement from DO SQLite
  created_at           timestamp NOT NULL DEFAULT now(),
  last_accessed_at     timestamp NOT NULL DEFAULT now(),
  storage_measured_at  timestamp            -- NULL when only lastAccessedAt was updated (WebSocket)
);
CREATE INDEX doi_user_id_idx ON durable_object_instance (user_id);

Design decisions:

• doName as primary key — doName = user:{userId}:{doType}:{resourceName}, so it already encodes the full identity. A composite PK on the decomposed columns was redundant (two indexes for the same logical key). Single-column PK simplifies the upsert conflict target from 3 columns to 1.
• userId index — needed for FK cascade delete performance and "list all DOs for user X" queries. The PK on doName can't serve prefix queries on userId.
• doType and resourceName as data columns — derivable from doName, but kept for query convenience (avoids string parsing).
• DoType branded union — type DoType = 'workspace' | 'document' with $type<DoType>() on the column for compile-time safety.
• storageBytes nullable — WebSocket upgrades update lastAccessedAt only (no RPC to measure storage).
• Separate storageMeasuredAt — distinguishes "never measured" from "measured at time T", since active WebSocket traffic can make lastAccessedAt fresh while storageBytes is stale.
• Best-effort — .catch() on upsert means a DB failure doesn't break sync. This is a resource registry, not billing authority.

Also in this PR

Workspace ID standardization: tab-manager → epicenter.tab-manager (clean break, no migration—local-first clients re-sync to new DO).

deleteStorage() RPC: New method on BaseSyncRoom for cleanup of renamed/orphaned DOs.

Technical article: docs/articles/piggyback-storage-tracking-on-existing-rpcs.md documents the afterResponse queue pattern and the piggybacking approach for broader reference.

What this is NOT

This is not a billing system. For billing you'd need time-series storage measurements, request/connection counting, and AI token tracking—all separate append-only tables. This is a v1 resource registry for a user dashboard.