@syncular/server 0.3.1 → 0.4.0

package/README.md

@@ -134,9 +134,11 @@ JSON-able queries.
 
 `RingBufferEvents` is a `SyncularServerEvents` sink that retains the last N
 events in memory (bounded — oldest dropped when full) with a
-`query({type?, sinceMs?, limit})`. It is the event stream without any
-infrastructure dependency. Compose it with any other sink so the console
-tail and your logs/metrics see the same emissions:
+`query({type?, sinceMs?, clientId?, actorId?, limit})` and a
+`subscribe(listener)` hook for live tails (the SSE route below). It is the
+event stream without any infrastructure dependency. Compose it with any
+other sink so the console tail and your logs/metrics see the same
+emissions:
 
 ```ts
 import {
@@ -153,21 +155,28 @@ const admin = SyncularAdmin.fromConfig(config, { ring });
 
 ### Query surface
 
-Every method is read-only and partition-scoped:
+Every method is read-only. All are partition-scoped except the two fleet
+reads (`listPartitions` / `partitionsOverview`), which enumerate partitions
+by design:
 
 | Method | Returns |
 | --- | --- |
-| `listClients(partition)` | Known clients: `clientId`, `actorId`, `cursor`, `updatedAtMs`, `subscriptions[]`, and an `active` flag (cursor touched within the §4.6 active window). |
+| `listClients(partition)` | Known clients: `clientId`, `actorId`, `cursor`, `lag` (commits not yet pulled: `maxCommitSeq − max(cursor, 0)`), `updatedAtMs`, `subscriptions[]`, and an `active` flag (cursor touched within the §4.6 active window). |
+| `clientDetail(partition, clientId, {eventLimit?})` | One client's drill-down: `{exists, client?, lease?, events}` — the record (with lag), its §7.3 lease when a lease store is wired, and its slice of the event tail. Answers "why is this client stale" in one read. |
 | `listCommits(partition, {afterSeq?, limit?, table?})` | Commit-log **metadata** (never payloads), newest first: `commitSeq`, `clientId`, `clientCommitId`, `actorId`, `createdAtMs`, `changeCount`, `tables[]`. |
 | `inspectRow(partition, table, rowId)` | `{exists, serverVersion?, scopes?}` — current row version + stored scopes, payload **not** decoded. |
 | `scopeActivity(partition, {variable, value}, {limit?})` | Recent commits touching one scope key, via the §3.1 change-scope index (never a log scan). |
 | `horizonStatus(partition)` | `{maxCommitSeq, horizonSeq, retainedCommits, activeCursorFloor, recommendedHorizonSeq, recommendation}` — the horizon a prune pass would reach now (§4.6) + a coarse `up-to-date` / `prune-recommended`. |
 | `segmentStats()` / `blobStats(partition)` / `stats(partition)` | Counts/bytes where the stores expose them (segments split rows/sqlite). `undefined` when a store omits `stats()`. |
-| `events({type?, sinceMs?, limit?})` | The ring tail, newest first. Empty when no ring is wired (`hasEventStream` reports which). |
+| `metrics(partition, {windowMs?, buckets?})` | Ring-derived request/push health over a trailing window (default 5 min): request count/rate, error share, p50/p95 duration, push applied/rejected/conflicted, and per-bucket counts for a sparkline. Zero new server state; all zeros when no ring is wired. |
+| `listPartitions()` / `partitionsOverview()` | Every partition the storage holds state for; the overview adds retained backlog, client counts (known/active), and the prune recommendation per partition — the fleet view. |
+| `events({type?, sinceMs?, clientId?, actorId?, limit?})` | The ring tail, newest first. Empty when no ring is wired (`hasEventStream` reports which). |
+| `subscribeEvents(listener)` | Live events as they land in the ring; returns the unsubscribe function, `undefined` when no ring is wired. |
 
 The query surface leans on **additive, optional** storage/store methods
 (`ServerStorage.listClientRecords` / `listCommitMetadata` / `scopeActivity` /
-`getRowScopes`; `SegmentStore.stats`; `BlobStore.stats`) — the established
+`getRowScopes` / `listPartitions`; `SegmentStore.stats`; `BlobStore.stats`)
+— the established
 optional-method pattern. `SqliteServerStorage`, `PostgresServerStorage`,
 `D1ServerStorage`, and the memory/sqlite stores implement them; the shared
 `ServerStorage` contract suite exercises them on all backends. A backend that
@@ -199,29 +208,44 @@ app.route('/admin', routes);
 | --- | --- |
 | `GET /` | The console page (see below). |
 | `GET /clients` | `listClients` |
+| `GET /clients/:clientId?eventLimit` | `clientDetail` |
 | `GET /commits?afterSeq&limit&table` | `listCommits` |
 | `GET /rows/:table/:rowId` | `inspectRow` |
 | `GET /scope-activity?variable&value&limit` | `scopeActivity` |
 | `GET /horizon` | `horizonStatus` |
 | `GET /stats` | `stats` |
-| `GET /events?type&sinceMs&limit` | `events` (ring tail) |
+| `GET /metrics?windowMs` | `metrics` |
+| `GET /partitions` | `partitionsOverview` (fleet view) |
+| `GET /events?type&sinceMs&clientId&actorId&limit` | `events` (ring tail) |
+| `GET /events/stream?type&clientId&actorId&limit` | live SSE tail (backlog replay, then `subscribeEvents`) |
 
 `?partition=` selects the partition (falls back to `defaultPartition`).
+`GET /partitions` is the one cross-partition endpoint: the guard still runs
+on it, with an empty `partition` in its context unless the query passes one
+— a host that authorizes per partition should treat it accordingly.
 
 `GET /` (or `/admin`) serves a **single static HTML page** — zero
 framework, no build step, no React. It fetches the sibling JSON endpoints
 (relative to its own mount path, so it works under any prefix and the same
-guard covers its XHRs), renders tables for horizon, store stats, clients,
-recent commits, and the event tail, with an auto-refresh toggle (2 s poll).
-This is a deliberate ~300-line console: 5% of the code a full console app
+guard covers its XHRs) and renders: a metrics statusbar (push rate,
+conflicts, error share, p95, ASCII sparkline), the fleet view (which doubles
+as the partition picker), horizon, store stats, clients with cursor lag and
+a per-client drill-down (subscriptions with full scope sets, lease status,
+the client's event slice), recent commits, the row inspector, scope
+activity, and the event tail — with an auto-refresh toggle (2 s poll).
+This is a deliberate one-file console: 5% of the code a full console app
 would cost, the 80% operator value.
 
-**No SSE (yet).** `GET /events` is a polled ring query; the page's
-auto-refresh polls it. Server-Sent-Events streaming was deliberately
-skipped for this rung — the ring is pull-only, so SSE would need a
-push-notification path from the sink into open connections (extra
-machinery for marginal benefit at admin cadence). Polling is the right
-rung; SSE is a noted follow-up.
+**Live tail over SSE.** `GET /events/stream` streams the ring as
+server-sent events: a recent backlog replays first, then events arrive as
+they land (a `subscribe` hook on the ring), with a comment ping every 5 s
+(under Bun.serve's 10 s default idle timeout, so a quiet stream survives).
+It is plain web-streams, so it serves identically on Bun, Node, and
+Workers. The page upgrades its event panel to the stream automatically and
+falls back to the 2-second poll when the stream is unavailable (no ring, or
+`EventSource` cannot pass the host's auth headers — cookie-authorized
+setups stream fine). The tail can carry sensitive identifiers (actorIds,
+session ids), the same as `GET /events`; the admin guard gates both.
 
 The demo server (`apps/demo`) mounts the admin behind a dev guard:
 `SYNCULAR_DEMO_ADMIN=1` enables `/admin` (optionally token-gated with

package/dist/admin.d.ts

@@ -18,6 +18,7 @@ import type { BlobStore, BlobStoreStats } from './blob-store.js';
 import { type SyncServerConfig } from './context.js';
 import type { SyncularServerEvent } from './events.js';
 import type { RingBufferEvents, RingEventQuery } from './events-ring.js';
+import type { LeaseRecord, LeaseStore } from './lease-store.js';
 import { type RetentionPolicy } from './prune.js';
 import { type ServerSchema } from './schema.js';
 import type { SegmentStore, SegmentStoreStats } from './segment-store.js';
@@ -27,6 +28,11 @@ export interface AdminClient {
     readonly clientId: string;
     readonly actorId: string;
     readonly cursor: number;
+    /**
+     * Commits the client has not pulled yet: `maxCommitSeq − max(cursor, 0)`.
+     * The first number an operator wants for "why is this client stale".
+     */
+    readonly lag: number;
     readonly updatedAtMs: number;
     readonly subscriptions: readonly {
         readonly id: string;
@@ -36,6 +42,58 @@ export interface AdminClient {
     /** True when the cursor record was touched within the active window. */
     readonly active: boolean;
 }
+/** One client's drill-down: record + lease + its slice of the event tail. */
+export interface AdminClientDetail {
+    readonly clientId: string;
+    readonly exists: boolean;
+    /** Present iff `exists` — the same shape `listClients` returns. */
+    readonly client?: AdminClient;
+    /** The client's §7.3 lease, when a lease store is wired and one exists. */
+    readonly lease?: LeaseRecord;
+    /** Recent ring events carrying this clientId (newest first). */
+    readonly events: readonly SyncularServerEvent[];
+}
+/** Ring-derived request/push aggregates over a trailing window. */
+export interface AdminMetrics {
+    readonly partition: string;
+    readonly windowMs: number;
+    /** Wall-clock the aggregation ran at (window end). */
+    readonly atMs: number;
+    readonly requests: {
+        readonly count: number;
+        readonly perMinute: number;
+        readonly errorCount: number;
+        /** errors ÷ requests, 0 when the window is empty. */
+        readonly errorRate: number;
+        readonly p50Ms: number;
+        readonly p95Ms: number;
+    };
+    readonly pushes: {
+        readonly applied: number;
+        readonly rejected: number;
+        readonly conflicted: number;
+    };
+    /**
+     * Request counts split into `counts.length` equal buckets, oldest first —
+     * the console's sparkline. `errors` marks the error share per bucket.
+     */
+    readonly buckets: {
+        readonly widthMs: number;
+        readonly counts: readonly number[];
+        readonly errors: readonly number[];
+    };
+}
+/** One partition's row in the fleet view (`listPartitions` + horizon math). */
+export interface AdminPartitionOverview {
+    readonly partition: string;
+    readonly maxCommitSeq: number;
+    readonly horizonSeq: number;
+    readonly retainedCommits: number;
+    readonly knownClients: number;
+    /** Clients whose cursor record was touched within the active window. */
+    readonly activeClients: number;
+    readonly recommendation: 'up-to-date' | 'prune-recommended';
+}
 export interface AdminRowInspection {
     readonly table: string;
     readonly rowId: string;
@@ -81,6 +139,8 @@ export interface SyncularAdminOptions {
     readonly ring?: RingBufferEvents;
     readonly segments?: SegmentStore;
     readonly blobs?: BlobStore;
+    /** The §7.3 lease store — feeds the client drill-down's lease read. */
+    readonly leases?: LeaseStore;
     /** Retention policy for horizon recommendation (defaults to §4.6). */
     readonly retention?: Partial<RetentionPolicy>;
     /** Epoch-ms clock (defaults to `Date.now`) — active-window math. */
@@ -99,8 +159,16 @@ export declare class SyncularAdmin {
         ring?: RingBufferEvents;
         retention?: Partial<RetentionPolicy>;
     }): SyncularAdmin;
-    /** The known clients for a partition (cursor, last-seen, subscriptions). */
+    /** The known clients for a partition (cursor, lag, subscriptions). */
     listClients(partition: string): Promise<AdminClient[]>;
+    /**
+     * One client's drill-down: its record (with lag), its §7.3 lease when a
+     * lease store is wired, and its recent slice of the event tail. Answers
+     * "why is this client stale" in a single read.
+     */
+    clientDetail(partition: string, clientId: string, options?: {
+        readonly eventLimit?: number;
+    }): Promise<AdminClientDetail>;
     /** Commit-log metadata (no payloads), newest first. */
     listCommits(partition: string, options?: AdminListCommitsOptions): Promise<CommitMetadata[]>;
     /**
@@ -133,4 +201,32 @@ export declare class SyncularAdmin {
     get hasEventStream(): boolean;
     /** The event tail from the ring buffer (newest first). Empty when unwired. */
     events(query?: RingEventQuery): SyncularServerEvent[];
+    /**
+     * Subscribe to events as they land in the ring (the SSE tail). Returns
+     * the unsubscribe function, or `undefined` when no ring is wired — a
+     * host can branch on that the same way `hasEventStream` reports it.
+     */
+    subscribeEvents(listener: (event: SyncularServerEvent) => void): (() => void) | undefined;
+    /**
+     * Request/push health over a trailing window, derived entirely from the
+     * ring (zero new server state): rates, error share, duration percentiles,
+     * and per-bucket counts for the console's sparkline. Only events carrying
+     * this `partition` count. Empty (all zeros) when no ring is wired.
+     */
+    metrics(partition: string, options?: {
+        readonly windowMs?: number;
+        readonly buckets?: number;
+    }): AdminMetrics;
+    /**
+     * Every partition the storage knows (commit log + client records) — the
+     * fleet-view backing and the console's partition picker. Fails loud when
+     * the backend omits the optional `listPartitions`.
+     */
+    listPartitions(): Promise<string[]>;
+    /**
+     * The fleet view: one row per known partition — retained backlog, client
+     * counts, prune recommendation. A cross-partition read (every other
+     * method is partition-scoped); host authorization should account for it.
+     */
+    partitionsOverview(): Promise<AdminPartitionOverview[]>;
 }

package/dist/admin.js

@@ -3,17 +3,30 @@ import { DEFAULT_RETENTION } from './prune.js';
 import { compileSchema } from './schema.js';
 const DEFAULT_COMMIT_LIMIT = 50;
 const DEFAULT_SCOPE_LIMIT = 50;
+const DEFAULT_CLIENT_EVENT_LIMIT = 100;
+const DEFAULT_METRICS_WINDOW_MS = 5 * 60 * 1000;
+const DEFAULT_METRICS_BUCKETS = 30;
+/** Nearest-rank percentile over an unsorted sample; 0 for an empty one. */
+function percentile(sample, q) {
+    if (sample.length === 0)
+        return 0;
+    const sorted = [...sample].sort((a, b) => a - b);
+    const rank = Math.max(1, Math.ceil(q * sorted.length));
+    return sorted[rank - 1] ?? 0;
+}
 function required(value, what) {
     if (value === undefined) {
         throw new Error(`SyncularAdmin: the configured ${what} does not implement this read (TODO §2.5 optional method missing)`);
     }
     return value;
 }
-function toAdminClient(record, active) {
+function toAdminClient(record, active, maxCommitSeq) {
     return {
         clientId: record.clientId,
         actorId: record.actorId,
         cursor: record.cursor,
+        // A never-pulled cursor (-1) has seen nothing: it lags the whole log.
+        lag: Math.max(0, maxCommitSeq - Math.max(0, record.cursor)),
         updatedAtMs: record.updatedAtMs,
         subscriptions: record.subscriptions.map((sub) => ({
             id: sub.id,
@@ -30,6 +43,7 @@ export class SyncularAdmin {
     #ring;
     #segments;
     #blobs;
+    #leases;
     #retention;
     #clock;
     constructor(options) {
@@ -42,6 +56,8 @@ export class SyncularAdmin {
             this.#segments = options.segments;
         if (options.blobs !== undefined)
             this.#blobs = options.blobs;
+        if (options.leases !== undefined)
+            this.#leases = options.leases;
         this.#retention = { ...DEFAULT_RETENTION, ...options.retention };
         this.#clock = options.clock ?? Date.now;
     }
@@ -56,17 +72,44 @@ export class SyncularAdmin {
             schema: config.schema,
             segments: config.segments,
             ...(config.blobs !== undefined ? { blobs: config.blobs } : {}),
+            ...(config.leases !== undefined ? { leases: config.leases.store } : {}),
             ...(extra?.ring !== undefined ? { ring: extra.ring } : {}),
             ...(extra?.retention !== undefined ? { retention: extra.retention } : {}),
             clock: clockOf(config),
         });
     }
-    /** The known clients for a partition (cursor, last-seen, subscriptions). */
+    /** The known clients for a partition (cursor, lag, subscriptions). */
     async listClients(partition) {
         const list = required(this.#storage.listClientRecords?.bind(this.#storage), 'storage');
         const records = await list(partition);
+        const maxCommitSeq = await this.#storage.getMaxCommitSeq(partition);
         const activeFloorMs = this.#clock() - this.#retention.activeWindowMs;
-        return records.map((record) => toAdminClient(record, record.updatedAtMs >= activeFloorMs));
+        return records.map((record) => toAdminClient(record, record.updatedAtMs >= activeFloorMs, maxCommitSeq));
+    }
+    /**
+     * One client's drill-down: its record (with lag), its §7.3 lease when a
+     * lease store is wired, and its recent slice of the event tail. Answers
+     * "why is this client stale" in a single read.
+     */
+    async clientDetail(partition, clientId, options = {}) {
+        const record = await this.#storage.getClientRecord(partition, clientId);
+        const events = this.events({
+            clientId,
+            limit: options.eventLimit ?? DEFAULT_CLIENT_EVENT_LIMIT,
+        });
+        if (record === undefined) {
+            return { clientId, exists: false, events };
+        }
+        const maxCommitSeq = await this.#storage.getMaxCommitSeq(partition);
+        const activeFloorMs = this.#clock() - this.#retention.activeWindowMs;
+        const lease = await this.#leases?.get(partition, clientId);
+        return {
+            clientId,
+            exists: true,
+            client: toAdminClient(record, record.updatedAtMs >= activeFloorMs, maxCommitSeq),
+            ...(lease !== undefined ? { lease } : {}),
+            events,
+        };
     }
     /** Commit-log metadata (no payloads), newest first. */
     async listCommits(partition, options = {}) {
@@ -165,4 +208,103 @@ export class SyncularAdmin {
     events(query = {}) {
         return this.#ring?.query(query) ?? [];
     }
+    /**
+     * Subscribe to events as they land in the ring (the SSE tail). Returns
+     * the unsubscribe function, or `undefined` when no ring is wired — a
+     * host can branch on that the same way `hasEventStream` reports it.
+     */
+    subscribeEvents(listener) {
+        return this.#ring?.subscribe(listener);
+    }
+    /**
+     * Request/push health over a trailing window, derived entirely from the
+     * ring (zero new server state): rates, error share, duration percentiles,
+     * and per-bucket counts for the console's sparkline. Only events carrying
+     * this `partition` count. Empty (all zeros) when no ring is wired.
+     */
+    metrics(partition, options = {}) {
+        const windowMs = options.windowMs ?? DEFAULT_METRICS_WINDOW_MS;
+        const bucketCount = options.buckets ?? DEFAULT_METRICS_BUCKETS;
+        const atMs = this.#clock();
+        const sinceMs = atMs - windowMs;
+        const widthMs = windowMs / bucketCount;
+        const counts = new Array(bucketCount).fill(0);
+        const errors = new Array(bucketCount).fill(0);
+        const durations = [];
+        let requestCount = 0;
+        let errorCount = 0;
+        let applied = 0;
+        let rejected = 0;
+        let conflicted = 0;
+        for (const event of this.events({ sinceMs })) {
+            if (event.partition !== partition)
+                continue;
+            if (event.type === 'push.applied')
+                applied += 1;
+            else if (event.type === 'push.rejected')
+                rejected += 1;
+            else if (event.type === 'push.conflicted')
+                conflicted += 1;
+            if (event.type !== 'request.handled')
+                continue;
+            requestCount += 1;
+            durations.push(event.durationMs);
+            const failed = event.outcome === 'rejected' || event.outcome === 'error';
+            if (failed)
+                errorCount += 1;
+            const bucket = Math.min(bucketCount - 1, Math.max(0, Math.floor((event.atMs - sinceMs) / widthMs)));
+            counts[bucket] = (counts[bucket] ?? 0) + 1;
+            if (failed)
+                errors[bucket] = (errors[bucket] ?? 0) + 1;
+        }
+        return {
+            partition,
+            windowMs,
+            atMs,
+            requests: {
+                count: requestCount,
+                perMinute: requestCount / (windowMs / 60_000),
+                errorCount,
+                errorRate: requestCount === 0 ? 0 : errorCount / requestCount,
+                p50Ms: percentile(durations, 0.5),
+                p95Ms: percentile(durations, 0.95),
+            },
+            pushes: { applied, rejected, conflicted },
+            buckets: { widthMs, counts, errors },
+        };
+    }
+    /**
+     * Every partition the storage knows (commit log + client records) — the
+     * fleet-view backing and the console's partition picker. Fails loud when
+     * the backend omits the optional `listPartitions`.
+     */
+    async listPartitions() {
+        const list = required(this.#storage.listPartitions?.bind(this.#storage), 'storage');
+        return list();
+    }
+    /**
+     * The fleet view: one row per known partition — retained backlog, client
+     * counts, prune recommendation. A cross-partition read (every other
+     * method is partition-scoped); host authorization should account for it.
+     */
+    async partitionsOverview() {
+        const partitions = await this.listPartitions();
+        const activeFloorMs = this.#clock() - this.#retention.activeWindowMs;
+        const out = [];
+        for (const partition of partitions) {
+            const status = await this.horizonStatus(partition);
+            const cursors = await this.#storage.listClientCursors(partition);
+            out.push({
+                partition,
+                maxCommitSeq: status.maxCommitSeq,
+                horizonSeq: status.horizonSeq,
+                retainedCommits: status.retainedCommits,
+                knownClients: cursors.length,
+                activeClients: cursors.filter((c) => c.updatedAtMs >= activeFloorMs)
+                    .length,
+                recommendation: status.recommendation,
+            });
+        }
+        return out;
+    }
 }

package/dist/d1-storage.d.ts

@@ -47,4 +47,5 @@ export declare class D1ServerStorage implements ServerStorage {
         serverVersion: number;
         scopes: Record<string, string>;
     } | undefined>;
+    listPartitions(): Promise<string[]>;
 }

package/dist/events-ring.d.ts

@@ -3,7 +3,8 @@
  * without any infrastructure dependency.
  *
  * `RingBufferEvents` is a `SyncularServerEvents` sink that retains the last
- * N events in memory and exposes a `query({type?, sinceMs?, limit})`. It
+ * N events in memory and exposes a `query({type?, sinceMs?, clientId?,
+ * actorId?, limit})` plus a `subscribe(listener)` hook for live tails. It
  * composes with any other sink through `composeEvents(...sinks)`, so a host
  * can keep `consoleJsonEvents()` (or a Sentry adapter) AND feed the console
  * event tail from the same emissions. Fire-and-forget discipline is
@@ -16,9 +17,20 @@ export interface RingEventQuery {
     readonly type?: SyncularServerEvent['type'];
     /** Only events with `atMs >= sinceMs`. */
     readonly sinceMs?: number;
+    /** Restrict to events carrying this `clientId` (not every type does). */
+    readonly clientId?: string;
+    /** Restrict to events carrying this `actorId` (not every type does). */
+    readonly actorId?: string;
     /** Newest-first cap (default: the whole retained buffer). */
     readonly limit?: number;
 }
+/**
+ * The one matching rule shared by `RingBufferEvents.query` and live
+ * subscribers (the admin SSE tail): `type` matches exactly; `clientId` /
+ * `actorId` match only events that carry the field (events without a
+ * client/actor identity never match an identity filter).
+ */
+export declare function matchesRingQuery(event: SyncularServerEvent, query: Omit<RingEventQuery, 'limit'>): boolean;
 export declare const DEFAULT_RING_CAPACITY = 1000;
 /**
  * In-memory ring of the most recent events. When full, the oldest event is
@@ -33,6 +45,13 @@ export declare class RingBufferEvents implements SyncularServerEvents {
         readonly capacity?: number;
     });
     emit(event: SyncularServerEvent): void;
+    /**
+     * Subscribe to every event as it lands in the ring (the push half the
+     * SSE tail needs). Returns the unsubscribe function. Listeners run
+     * synchronously on the emit path under the same fire-and-forget contract
+     * as sinks: a throwing listener is swallowed.
+     */
+    subscribe(listener: (event: SyncularServerEvent) => void): () => void;
     /** The configured maximum number of retained events. */
     get capacity(): number;
     /** The number of events currently retained. */

package/dist/events-ring.js

@@ -3,7 +3,8 @@
  * without any infrastructure dependency.
  *
  * `RingBufferEvents` is a `SyncularServerEvents` sink that retains the last
- * N events in memory and exposes a `query({type?, sinceMs?, limit})`. It
+ * N events in memory and exposes a `query({type?, sinceMs?, clientId?,
+ * actorId?, limit})` plus a `subscribe(listener)` hook for live tails. It
  * composes with any other sink through `composeEvents(...sinks)`, so a host
  * can keep `consoleJsonEvents()` (or a Sentry adapter) AND feed the console
  * event tail from the same emissions. Fire-and-forget discipline is
@@ -11,6 +12,26 @@
  * guarded), and the ring itself never throws through.
  */
 import { emitEvent, } from './events.js';
+/**
+ * The one matching rule shared by `RingBufferEvents.query` and live
+ * subscribers (the admin SSE tail): `type` matches exactly; `clientId` /
+ * `actorId` match only events that carry the field (events without a
+ * client/actor identity never match an identity filter).
+ */
+export function matchesRingQuery(event, query) {
+    if (query.type !== undefined && event.type !== query.type)
+        return false;
+    if (query.sinceMs !== undefined && event.atMs < query.sinceMs)
+        return false;
+    const carrier = event;
+    if (query.clientId !== undefined && carrier.clientId !== query.clientId) {
+        return false;
+    }
+    if (query.actorId !== undefined && carrier.actorId !== query.actorId) {
+        return false;
+    }
+    return true;
+}
 export const DEFAULT_RING_CAPACITY = 1000;
 /**
  * In-memory ring of the most recent events. When full, the oldest event is
@@ -25,6 +46,8 @@ export class RingBufferEvents {
     /** Index of the oldest element in the circular buffer. */
     #head = 0;
     #size = 0;
+    /** Live subscribers (the SSE tail). Each notify is guarded. */
+    #listeners = new Set();
     constructor(options) {
         const capacity = options?.capacity ?? DEFAULT_RING_CAPACITY;
         if (!Number.isInteger(capacity) || capacity <= 0) {
@@ -42,6 +65,26 @@ export class RingBufferEvents {
             this.#buffer[this.#head] = event;
             this.#head = (this.#head + 1) % this.#capacity;
         }
+        for (const listener of this.#listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // fire-and-forget: a throwing subscriber never affects emission
+            }
+        }
+    }
+    /**
+     * Subscribe to every event as it lands in the ring (the push half the
+     * SSE tail needs). Returns the unsubscribe function. Listeners run
+     * synchronously on the emit path under the same fire-and-forget contract
+     * as sinks: a throwing listener is swallowed.
+     */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
     }
     /** The configured maximum number of retained events. */
     get capacity() {
@@ -64,9 +107,7 @@ export class RingBufferEvents {
             const event = this.#buffer[(this.#head + i) % this.#capacity];
             if (event === undefined)
                 continue;
-            if (query.type !== undefined && event.type !== query.type)
-                continue;
-            if (query.sinceMs !== undefined && event.atMs < query.sinceMs)
+            if (!matchesRingQuery(event, query))
                 continue;
             out.push(event);
         }

package/dist/postgres-storage.d.ts

@@ -66,4 +66,5 @@ export declare class PostgresServerStorage implements ServerStorage {
         serverVersion: number;
         scopes: Record<string, string>;
     } | undefined>;
+    listPartitions(): Promise<string[]>;
 }

package/dist/postgres-storage.js

@@ -763,4 +763,11 @@ export class PostgresServerStorage {
                 : row.scopes),
         };
     }
+    async listPartitions() {
+        // Union: the registry row appears on first commit, the client row on
+        // first pull — a partition with only one of the two still shows up.
+        const { rows } = await this.#exec.query(`SELECT partition FROM sync_partitions
+       UNION SELECT partition FROM sync_clients ORDER BY partition`, []);
+        return rows.map((r) => r.partition);
+    }
 }

package/dist/schema.js

@@ -106,7 +106,7 @@ export function compileSchema(schema) {
         // non-PK, non-scope column is encrypted — a fully-E2EE table's
         // projection would be pure ciphertext, so it defaults off.
         const scopeColumnIndices = new Set(scopePatterns.map((pattern) => pattern.columnIndex));
-        const projectable = table.columns.filter((column, index) => index !== primaryKeyIndex && !scopeColumnIndices.has(index));
+        const projectable = table.columns.filter((_column, index) => index !== primaryKeyIndex && !scopeColumnIndices.has(index));
         const fullyEncrypted = encryptedColumnIndices.length > 0 &&
             projectable.length > 0 &&
             projectable.every((column) => column.encrypted === true);

package/dist/sqlite-storage.d.ts

@@ -44,4 +44,5 @@ export declare class SqliteServerStorage implements ServerStorage {
         serverVersion: number;
         scopes: Record<string, string>;
     } | undefined>;
+    listPartitions(): Promise<string[]>;
 }

package/dist/sqlite-storage.js

@@ -474,4 +474,13 @@ export class SqliteServerStorage {
             scopes: JSON.parse(record.scopes),
         };
     }
+    async listPartitions() {
+        // Union: the registry row appears on first commit, the client row on
+        // first pull — a partition with only one of the two still shows up.
+        const rows = this.db
+            .query(`SELECT partition FROM sync_partitions
+         UNION SELECT partition FROM sync_clients ORDER BY partition`)
+            .all();
+        return rows.map((r) => r.partition);
+    }
 }

package/dist/storage.d.ts

@@ -235,6 +235,10 @@ export interface ServerStorage {
      * change scope index (never a log scan).
      * `getRowScopes`: the (table, rowId) row's current server_version and
      * stored scopes without decoding its payload — the row inspector.
+     * `listPartitions`: every partition this storage holds state for — the
+     * union of the partition registry (commit log counters) and client
+     * records, sorted. Powers the console's fleet view / partition picker;
+     * deliberately NOT partition-scoped (the one cross-partition read).
      */
     listClientRecords?(partition: string): Promise<ClientRecord[]>;
     listCommitMetadata?(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
@@ -243,6 +247,7 @@ export interface ServerStorage {
         serverVersion: number;
         scopes: Record<string, string>;
     } | undefined>;
+    listPartitions?(): Promise<string[]>;
 }
 /** A row referencing a blob, with the scopes needed to authorize download. */
 export interface BlobReferencingRow {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -53,7 +53,7 @@
     "!dist/**/*.test.d.ts"
   ],
   "dependencies": {
-    "@syncular/core": "0.2.1"
+    "@syncular/core": "0.3.1"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/admin.ts

@@ -18,6 +18,7 @@ import type { BlobStore, BlobStoreStats } from './blob-store';
 import { clockOf, type SyncServerConfig } from './context';
 import type { SyncularServerEvent } from './events';
 import type { RingBufferEvents, RingEventQuery } from './events-ring';
+import type { LeaseRecord, LeaseStore } from './lease-store';
 import { DEFAULT_RETENTION, type RetentionPolicy } from './prune';
 import { compileSchema, type ServerSchema } from './schema';
 import type { SegmentStore, SegmentStoreStats } from './segment-store';
@@ -33,6 +34,11 @@ export interface AdminClient {
   readonly clientId: string;
   readonly actorId: string;
   readonly cursor: number;
+  /**
+   * Commits the client has not pulled yet: `maxCommitSeq − max(cursor, 0)`.
+   * The first number an operator wants for "why is this client stale".
+   */
+  readonly lag: number;
   readonly updatedAtMs: number;
   readonly subscriptions: readonly {
     readonly id: string;
@@ -43,6 +49,61 @@ export interface AdminClient {
   readonly active: boolean;
 }
 
+/** One client's drill-down: record + lease + its slice of the event tail. */
+export interface AdminClientDetail {
+  readonly clientId: string;
+  readonly exists: boolean;
+  /** Present iff `exists` — the same shape `listClients` returns. */
+  readonly client?: AdminClient;
+  /** The client's §7.3 lease, when a lease store is wired and one exists. */
+  readonly lease?: LeaseRecord;
+  /** Recent ring events carrying this clientId (newest first). */
+  readonly events: readonly SyncularServerEvent[];
+}
+
+/** Ring-derived request/push aggregates over a trailing window. */
+export interface AdminMetrics {
+  readonly partition: string;
+  readonly windowMs: number;
+  /** Wall-clock the aggregation ran at (window end). */
+  readonly atMs: number;
+  readonly requests: {
+    readonly count: number;
+    readonly perMinute: number;
+    readonly errorCount: number;
+    /** errors ÷ requests, 0 when the window is empty. */
+    readonly errorRate: number;
+    readonly p50Ms: number;
+    readonly p95Ms: number;
+  };
+  readonly pushes: {
+    readonly applied: number;
+    readonly rejected: number;
+    readonly conflicted: number;
+  };
+  /**
+   * Request counts split into `counts.length` equal buckets, oldest first —
+   * the console's sparkline. `errors` marks the error share per bucket.
+   */
+  readonly buckets: {
+    readonly widthMs: number;
+    readonly counts: readonly number[];
+    readonly errors: readonly number[];
+  };
+}
+
+/** One partition's row in the fleet view (`listPartitions` + horizon math). */
+export interface AdminPartitionOverview {
+  readonly partition: string;
+  readonly maxCommitSeq: number;
+  readonly horizonSeq: number;
+  readonly retainedCommits: number;
+  readonly knownClients: number;
+  /** Clients whose cursor record was touched within the active window. */
+  readonly activeClients: number;
+  readonly recommendation: 'up-to-date' | 'prune-recommended';
+}
+
 export interface AdminRowInspection {
   readonly table: string;
   readonly rowId: string;
@@ -93,6 +154,8 @@ export interface SyncularAdminOptions {
   readonly ring?: RingBufferEvents;
   readonly segments?: SegmentStore;
   readonly blobs?: BlobStore;
+  /** The §7.3 lease store — feeds the client drill-down's lease read. */
+  readonly leases?: LeaseStore;
   /** Retention policy for horizon recommendation (defaults to §4.6). */
   readonly retention?: Partial<RetentionPolicy>;
   /** Epoch-ms clock (defaults to `Date.now`) — active-window math. */
@@ -101,6 +164,17 @@ export interface SyncularAdminOptions {
 
 const DEFAULT_COMMIT_LIMIT = 50;
 const DEFAULT_SCOPE_LIMIT = 50;
+const DEFAULT_CLIENT_EVENT_LIMIT = 100;
+const DEFAULT_METRICS_WINDOW_MS = 5 * 60 * 1000;
+const DEFAULT_METRICS_BUCKETS = 30;
+
+/** Nearest-rank percentile over an unsorted sample; 0 for an empty one. */
+function percentile(sample: readonly number[], q: number): number {
+  if (sample.length === 0) return 0;
+  const sorted = [...sample].sort((a, b) => a - b);
+  const rank = Math.max(1, Math.ceil(q * sorted.length));
+  return sorted[rank - 1] ?? 0;
+}
 
 function required<T>(value: T | undefined, what: string): T {
   if (value === undefined) {
@@ -111,11 +185,17 @@ function required<T>(value: T | undefined, what: string): T {
   return value;
 }
 
-function toAdminClient(record: ClientRecord, active: boolean): AdminClient {
+function toAdminClient(
+  record: ClientRecord,
+  active: boolean,
+  maxCommitSeq: number,
+): AdminClient {
   return {
     clientId: record.clientId,
     actorId: record.actorId,
     cursor: record.cursor,
+    // A never-pulled cursor (-1) has seen nothing: it lags the whole log.
+    lag: Math.max(0, maxCommitSeq - Math.max(0, record.cursor)),
     updatedAtMs: record.updatedAtMs,
     subscriptions: record.subscriptions.map((sub) => ({
       id: sub.id,
@@ -133,6 +213,7 @@ export class SyncularAdmin {
   readonly #ring?: RingBufferEvents;
   readonly #segments?: SegmentStore;
   readonly #blobs?: BlobStore;
+  readonly #leases?: LeaseStore;
   readonly #retention: RetentionPolicy;
   readonly #clock: () => number;
 
@@ -142,6 +223,7 @@ export class SyncularAdmin {
     if (options.ring !== undefined) this.#ring = options.ring;
     if (options.segments !== undefined) this.#segments = options.segments;
     if (options.blobs !== undefined) this.#blobs = options.blobs;
+    if (options.leases !== undefined) this.#leases = options.leases;
     this.#retention = { ...DEFAULT_RETENTION, ...options.retention };
     this.#clock = options.clock ?? Date.now;
   }
@@ -160,25 +242,61 @@ export class SyncularAdmin {
       schema: config.schema,
       segments: config.segments,
       ...(config.blobs !== undefined ? { blobs: config.blobs } : {}),
+      ...(config.leases !== undefined ? { leases: config.leases.store } : {}),
       ...(extra?.ring !== undefined ? { ring: extra.ring } : {}),
       ...(extra?.retention !== undefined ? { retention: extra.retention } : {}),
       clock: clockOf(config),
     });
   }
 
-  /** The known clients for a partition (cursor, last-seen, subscriptions). */
+  /** The known clients for a partition (cursor, lag, subscriptions). */
   async listClients(partition: string): Promise<AdminClient[]> {
     const list = required(
       this.#storage.listClientRecords?.bind(this.#storage),
       'storage',
     );
     const records = await list(partition);
+    const maxCommitSeq = await this.#storage.getMaxCommitSeq(partition);
     const activeFloorMs = this.#clock() - this.#retention.activeWindowMs;
     return records.map((record) =>
-      toAdminClient(record, record.updatedAtMs >= activeFloorMs),
+      toAdminClient(record, record.updatedAtMs >= activeFloorMs, maxCommitSeq),
     );
   }
 
+  /**
+   * One client's drill-down: its record (with lag), its §7.3 lease when a
+   * lease store is wired, and its recent slice of the event tail. Answers
+   * "why is this client stale" in a single read.
+   */
+  async clientDetail(
+    partition: string,
+    clientId: string,
+    options: { readonly eventLimit?: number } = {},
+  ): Promise<AdminClientDetail> {
+    const record = await this.#storage.getClientRecord(partition, clientId);
+    const events = this.events({
+      clientId,
+      limit: options.eventLimit ?? DEFAULT_CLIENT_EVENT_LIMIT,
+    });
+    if (record === undefined) {
+      return { clientId, exists: false, events };
+    }
+    const maxCommitSeq = await this.#storage.getMaxCommitSeq(partition);
+    const activeFloorMs = this.#clock() - this.#retention.activeWindowMs;
+    const lease = await this.#leases?.get(partition, clientId);
+    return {
+      clientId,
+      exists: true,
+      client: toAdminClient(
+        record,
+        record.updatedAtMs >= activeFloorMs,
+        maxCommitSeq,
+      ),
+      ...(lease !== undefined ? { lease } : {}),
+      events,
+    };
+  }
+
   /** Commit-log metadata (no payloads), newest first. */
   async listCommits(
     partition: string,
@@ -309,4 +427,111 @@ export class SyncularAdmin {
   events(query: RingEventQuery = {}): SyncularServerEvent[] {
     return this.#ring?.query(query) ?? [];
   }
+
+  /**
+   * Subscribe to events as they land in the ring (the SSE tail). Returns
+   * the unsubscribe function, or `undefined` when no ring is wired — a
+   * host can branch on that the same way `hasEventStream` reports it.
+   */
+  subscribeEvents(
+    listener: (event: SyncularServerEvent) => void,
+  ): (() => void) | undefined {
+    return this.#ring?.subscribe(listener);
+  }
+
+  /**
+   * Request/push health over a trailing window, derived entirely from the
+   * ring (zero new server state): rates, error share, duration percentiles,
+   * and per-bucket counts for the console's sparkline. Only events carrying
+   * this `partition` count. Empty (all zeros) when no ring is wired.
+   */
+  metrics(
+    partition: string,
+    options: { readonly windowMs?: number; readonly buckets?: number } = {},
+  ): AdminMetrics {
+    const windowMs = options.windowMs ?? DEFAULT_METRICS_WINDOW_MS;
+    const bucketCount = options.buckets ?? DEFAULT_METRICS_BUCKETS;
+    const atMs = this.#clock();
+    const sinceMs = atMs - windowMs;
+    const widthMs = windowMs / bucketCount;
+    const counts = new Array<number>(bucketCount).fill(0);
+    const errors = new Array<number>(bucketCount).fill(0);
+    const durations: number[] = [];
+    let requestCount = 0;
+    let errorCount = 0;
+    let applied = 0;
+    let rejected = 0;
+    let conflicted = 0;
+    for (const event of this.events({ sinceMs })) {
+      if (event.partition !== partition) continue;
+      if (event.type === 'push.applied') applied += 1;
+      else if (event.type === 'push.rejected') rejected += 1;
+      else if (event.type === 'push.conflicted') conflicted += 1;
+      if (event.type !== 'request.handled') continue;
+      requestCount += 1;
+      durations.push(event.durationMs);
+      const failed = event.outcome === 'rejected' || event.outcome === 'error';
+      if (failed) errorCount += 1;
+      const bucket = Math.min(
+        bucketCount - 1,
+        Math.max(0, Math.floor((event.atMs - sinceMs) / widthMs)),
+      );
+      counts[bucket] = (counts[bucket] ?? 0) + 1;
+      if (failed) errors[bucket] = (errors[bucket] ?? 0) + 1;
+    }
+    return {
+      partition,
+      windowMs,
+      atMs,
+      requests: {
+        count: requestCount,
+        perMinute: requestCount / (windowMs / 60_000),
+        errorCount,
+        errorRate: requestCount === 0 ? 0 : errorCount / requestCount,
+        p50Ms: percentile(durations, 0.5),
+        p95Ms: percentile(durations, 0.95),
+      },
+      pushes: { applied, rejected, conflicted },
+      buckets: { widthMs, counts, errors },
+    };
+  }
+
+  /**
+   * Every partition the storage knows (commit log + client records) — the
+   * fleet-view backing and the console's partition picker. Fails loud when
+   * the backend omits the optional `listPartitions`.
+   */
+  async listPartitions(): Promise<string[]> {
+    const list = required(
+      this.#storage.listPartitions?.bind(this.#storage),
+      'storage',
+    );
+    return list();
+  }
+
+  /**
+   * The fleet view: one row per known partition — retained backlog, client
+   * counts, prune recommendation. A cross-partition read (every other
+   * method is partition-scoped); host authorization should account for it.
+   */
+  async partitionsOverview(): Promise<AdminPartitionOverview[]> {
+    const partitions = await this.listPartitions();
+    const activeFloorMs = this.#clock() - this.#retention.activeWindowMs;
+    const out: AdminPartitionOverview[] = [];
+    for (const partition of partitions) {
+      const status = await this.horizonStatus(partition);
+      const cursors = await this.#storage.listClientCursors(partition);
+      out.push({
+        partition,
+        maxCommitSeq: status.maxCommitSeq,
+        horizonSeq: status.horizonSeq,
+        retainedCommits: status.retainedCommits,
+        knownClients: cursors.length,
+        activeClients: cursors.filter((c) => c.updatedAtMs >= activeFloorMs)
+          .length,
+        recommendation: status.recommendation,
+      });
+    }
+    return out;
+  }
 }

package/src/events-ring.ts

@@ -3,7 +3,8 @@
  * without any infrastructure dependency.
  *
  * `RingBufferEvents` is a `SyncularServerEvents` sink that retains the last
- * N events in memory and exposes a `query({type?, sinceMs?, limit})`. It
+ * N events in memory and exposes a `query({type?, sinceMs?, clientId?,
+ * actorId?, limit})` plus a `subscribe(listener)` hook for live tails. It
  * composes with any other sink through `composeEvents(...sinks)`, so a host
  * can keep `consoleJsonEvents()` (or a Sentry adapter) AND feed the console
  * event tail from the same emissions. Fire-and-forget discipline is
@@ -21,10 +22,36 @@ export interface RingEventQuery {
   readonly type?: SyncularServerEvent['type'];
   /** Only events with `atMs >= sinceMs`. */
   readonly sinceMs?: number;
+  /** Restrict to events carrying this `clientId` (not every type does). */
+  readonly clientId?: string;
+  /** Restrict to events carrying this `actorId` (not every type does). */
+  readonly actorId?: string;
   /** Newest-first cap (default: the whole retained buffer). */
   readonly limit?: number;
 }
 
+/**
+ * The one matching rule shared by `RingBufferEvents.query` and live
+ * subscribers (the admin SSE tail): `type` matches exactly; `clientId` /
+ * `actorId` match only events that carry the field (events without a
+ * client/actor identity never match an identity filter).
+ */
+export function matchesRingQuery(
+  event: SyncularServerEvent,
+  query: Omit<RingEventQuery, 'limit'>,
+): boolean {
+  if (query.type !== undefined && event.type !== query.type) return false;
+  if (query.sinceMs !== undefined && event.atMs < query.sinceMs) return false;
+  const carrier = event as { clientId?: string; actorId?: string };
+  if (query.clientId !== undefined && carrier.clientId !== query.clientId) {
+    return false;
+  }
+  if (query.actorId !== undefined && carrier.actorId !== query.actorId) {
+    return false;
+  }
+  return true;
+}
+
 export const DEFAULT_RING_CAPACITY = 1000;
 
 /**
@@ -40,6 +67,8 @@ export class RingBufferEvents implements SyncularServerEvents {
   /** Index of the oldest element in the circular buffer. */
   #head = 0;
   #size = 0;
+  /** Live subscribers (the SSE tail). Each notify is guarded. */
+  readonly #listeners = new Set<(event: SyncularServerEvent) => void>();
 
   constructor(options?: { readonly capacity?: number }) {
     const capacity = options?.capacity ?? DEFAULT_RING_CAPACITY;
@@ -58,6 +87,26 @@ export class RingBufferEvents implements SyncularServerEvents {
       this.#buffer[this.#head] = event;
       this.#head = (this.#head + 1) % this.#capacity;
     }
+    for (const listener of this.#listeners) {
+      try {
+        listener(event);
+      } catch {
+        // fire-and-forget: a throwing subscriber never affects emission
+      }
+    }
+  }
+
+  /**
+   * Subscribe to every event as it lands in the ring (the push half the
+   * SSE tail needs). Returns the unsubscribe function. Listeners run
+   * synchronously on the emit path under the same fire-and-forget contract
+   * as sinks: a throwing listener is swallowed.
+   */
+  subscribe(listener: (event: SyncularServerEvent) => void): () => void {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
   }
 
   /** The configured maximum number of retained events. */
@@ -82,8 +131,7 @@ export class RingBufferEvents implements SyncularServerEvents {
     for (let i = this.#size - 1; i >= 0 && out.length < limit; i -= 1) {
       const event = this.#buffer[(this.#head + i) % this.#capacity];
       if (event === undefined) continue;
-      if (query.type !== undefined && event.type !== query.type) continue;
-      if (query.sinceMs !== undefined && event.atMs < query.sinceMs) continue;
+      if (!matchesRingQuery(event, query)) continue;
       out.push(event);
     }
     return out;

package/src/postgres-storage.ts

@@ -1179,4 +1179,15 @@ export class PostgresServerStorage implements ServerStorage {
         : row.scopes) as Record<string, string>,
     };
   }
+
+  async listPartitions(): Promise<string[]> {
+    // Union: the registry row appears on first commit, the client row on
+    // first pull — a partition with only one of the two still shows up.
+    const { rows } = await this.#exec.query<{ partition: string }>(
+      `SELECT partition FROM sync_partitions
+       UNION SELECT partition FROM sync_clients ORDER BY partition`,
+      [],
+    );
+    return rows.map((r) => r.partition);
+  }
 }

package/src/schema.ts

@@ -240,7 +240,7 @@ export function compileSchema(schema: ServerSchema): CompiledSchema {
       scopePatterns.map((pattern) => pattern.columnIndex),
     );
     const projectable = table.columns.filter(
-      (column, index) =>
+      (_column, index) =>
         index !== primaryKeyIndex && !scopeColumnIndices.has(index),
     );
     const fullyEncrypted =

package/src/sqlite-storage.ts

@@ -789,4 +789,16 @@ export class SqliteServerStorage implements ServerStorage {
       scopes: JSON.parse(record.scopes) as Record<string, string>,
     };
   }
+
+  async listPartitions(): Promise<string[]> {
+    // Union: the registry row appears on first commit, the client row on
+    // first pull — a partition with only one of the two still shows up.
+    const rows = this.db
+      .query<{ partition: string }, []>(
+        `SELECT partition FROM sync_partitions
+         UNION SELECT partition FROM sync_clients ORDER BY partition`,
+      )
+      .all();
+    return rows.map((r) => r.partition);
+  }
 }

package/src/storage.ts

@@ -289,6 +289,10 @@ export interface ServerStorage {
    * change scope index (never a log scan).
    * `getRowScopes`: the (table, rowId) row's current server_version and
    * stored scopes without decoding its payload — the row inspector.
+   * `listPartitions`: every partition this storage holds state for — the
+   * union of the partition registry (commit log counters) and client
+   * records, sorted. Powers the console's fleet view / partition picker;
+   * deliberately NOT partition-scoped (the one cross-partition read).
    */
   listClientRecords?(partition: string): Promise<ClientRecord[]>;
   listCommitMetadata?(
@@ -306,6 +310,7 @@ export interface ServerStorage {
   ): Promise<
     { serverVersion: number; scopes: Record<string, string> } | undefined
   >;
+  listPartitions?(): Promise<string[]>;
 }
 
 /** A row referencing a blob, with the scopes needed to authorize download. */