@syncular/server 0.31.0 → 0.32.0

package/dist/admin.js

@@ -1,11 +1,33 @@
-import { clockOf } from './context.js';
-import { DEFAULT_RETENTION } from './prune.js';
-import { compileSchema } from './schema.js';
+/**
+ * `SyncularAdmin` is the operator-facing surface over the server core: a
+ * partition-scoped, JSON-able query layer over `ServerStorage`, the optional
+ * segment/blob store stats, and an in-memory event ring, plus three explicit
+ * operator actions (retry a dead-lettered reaction, prune the commit log,
+ * revoke a client's lease). No separate UI package, no framework, and no
+ * wire-protocol surface. This host surface is mirrored in the server README.
+ *
+ * Nothing here is on the sync hot path. The additive optional storage/store
+ * methods it depends on are documented as such and this module fails loud (a
+ * thrown `Error`) when a backend lacks one, so a host wiring an unsupported
+ * store learns immediately rather than getting a silently-empty console.
+ */
+import { bytesToBase64, decodeRow, renderRowValues, } from '@syncular/core';
+import { clockOf, RESOLVER_OUTAGE, } from './context.js';
+import { SyncError } from './errors.js';
+import { emitEvent, } from './events.js';
+import { RealtimeHub } from './realtime.js';
+import { DEFAULT_RETENTION, pruneCommitLog, } from './prune.js';
+import { compileSchema, } from './schema.js';
+import { computeEffective, matchesEffective } from './scopes.js';
+const DEFAULT_CLIENT_LIMIT = 200;
+const DEFAULT_PARTITION_LIMIT = 100;
 const DEFAULT_COMMIT_LIMIT = 50;
 const DEFAULT_SCOPE_LIMIT = 50;
 const DEFAULT_REACTION_LIMIT = 100;
 const DEFAULT_CLIENT_EVENT_LIMIT = 100;
-const DEFAULT_METRICS_WINDOW_MS = 5 * 60 * 1000;
+const DEFAULT_ROW_HISTORY_LIMIT = 20;
+const DEFAULT_ROW_PAGE_LIMIT = 50;
+const DEFAULT_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) {
@@ -21,28 +43,77 @@ function required(value, what) {
     }
     return value;
 }
-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) => ({
+/** Verdicts in evaluation order; `rowDelivery` sorts by it. */
+const VERDICT_ORDER = [
+    'client-unknown',
+    'row-missing',
+    'no-subscription',
+    'row-deleted',
+    'scope-mismatch',
+    'scope-denied',
+    'pending-pull',
+    'delivered',
+];
+/** One known client's subscriptions on the row's table and its verdict. */
+function traceVerdict(record, row, lastChange, horizonSeq, allowed) {
+    const rowScopes = row.scopes ?? {};
+    const subscriptions = record.subscriptions
+        .filter((sub) => sub.table === row.table)
+        .map((sub) => {
+        const mismatches = Object.entries(sub.scopes)
+            .filter(([variable, values]) => {
+            const value = rowScopes[variable];
+            return value === undefined || !values.includes(value);
+        })
+            .map(([variable, values]) => ({
+            variable,
+            rowValue: rowScopes[variable] ?? null,
+            requested: values,
+        }));
+        const traced = {
             id: sub.id,
-            table: sub.table,
             scopes: sub.scopes,
-        })),
-        active,
-    };
+            requestedMatch: mismatches.length === 0,
+            mismatches,
+        };
+        if (allowed === undefined || allowed === 'outage')
+            return traced;
+        const effective = computeEffective(sub.scopes, { ok: true, allowed });
+        return {
+            ...traced,
+            effectiveMatch: effective.status === 'active' &&
+                matchesEffective(rowScopes, effective.effective),
+        };
+    });
+    // With no retained change left, the newest one sits at or below the
+    // horizon, so a cursor at the horizon has pulled it.
+    const pulled = record.cursor >= (lastChange?.commitSeq ?? horizonSeq);
+    const verdict = !row.exists && lastChange === undefined
+        ? 'row-missing'
+        : subscriptions.length === 0
+            ? 'no-subscription'
+            : !row.exists
+                ? pulled
+                    ? 'row-deleted'
+                    : 'pending-pull'
+                : !subscriptions.some((sub) => sub.requestedMatch)
+                    ? 'scope-mismatch'
+                    : subscriptions.every((sub) => sub.effectiveMatch === false)
+                        ? 'scope-denied'
+                        : pulled
+                            ? 'delivered'
+                            : 'pending-pull';
+    return { subscriptions, verdict };
 }
-/** The read-only console query surface. Construct one per host process. */
+/** The console query surface plus its operator actions. One per process. */
 export class SyncularAdmin {
     #storage;
     #schema;
     #checkpoints;
     #ring;
+    #events;
+    #resolveScopes;
+    #realtime;
     #segments;
     #blobs;
     #leases;
@@ -50,12 +121,20 @@ export class SyncularAdmin {
     #clock;
     constructor(options) {
         this.#storage = options.storage;
-        if (options.schema !== undefined)
-            this.#schema = options.schema;
+        if (options.schema !== undefined) {
+            this.#schema = compileSchema(options.schema);
+        }
         if (options.checkpoints !== undefined)
             this.#checkpoints = options.checkpoints;
         if (options.ring !== undefined)
             this.#ring = options.ring;
+        if (options.events !== undefined)
+            this.#events = options.events;
+        if (options.resolveScopes !== undefined) {
+            this.#resolveScopes = options.resolveScopes;
+        }
+        if (options.realtime !== undefined)
+            this.#realtime = options.realtime;
         if (options.segments !== undefined)
             this.#segments = options.segments;
         if (options.blobs !== undefined)
@@ -66,9 +145,10 @@ export class SyncularAdmin {
         this.#clock = options.clock ?? Date.now;
     }
     /**
-     * Build an admin over a `SyncServerConfig`, reusing its storage / segment
-     * / blob store / clock. Pass the ring separately (it is an events sink,
-     * composed into the config's `events` by the host — see `composeEvents`).
+     * Build an admin over a `SyncServerConfig`, reusing its storage, schema,
+     * resolver, events sink, stores, leases and clock. Pass the ring
+     * separately (it is an events sink, composed into the config's `events` by
+     * the host — see `composeEvents`).
      */
     static fromConfig(config, extra) {
         return new SyncularAdmin({
@@ -77,6 +157,11 @@ export class SyncularAdmin {
             ...(config.checkpoints !== undefined
                 ? { checkpoints: config.checkpoints }
                 : {}),
+            resolveScopes: config.resolveScopes,
+            ...(config.realtime instanceof RealtimeHub
+                ? { realtime: config.realtime }
+                : {}),
+            ...(config.events !== undefined ? { events: config.events } : {}),
             segments: config.segments,
             ...(config.blobs !== undefined ? { blobs: config.blobs } : {}),
             ...(config.leases !== undefined ? { leases: config.leases.store } : {}),
@@ -85,35 +170,53 @@ export class SyncularAdmin {
             clock: clockOf(config),
         });
     }
-    /** The known clients for a partition (cursor, lag, subscriptions). */
-    async listClients(partition) {
+    /** The server schema version; `undefined` without a schema. */
+    get schemaVersion() {
+        return this.#schema?.version;
+    }
+    /** The schema tables and columns, for row and commit pickers. */
+    tables() {
+        return [...(this.#schema?.tables.values() ?? [])].map((table) => ({
+            name: table.name,
+            columns: table.columns.map((column, i) => ({
+                name: column.name,
+                type: column.type,
+                nullable: column.nullable,
+                primaryKey: i === table.primaryKeyIndex,
+            })),
+        }));
+    }
+    /** The known clients for a partition (cursor, lag, versions, subs). */
+    async listClients(partition, options = {}) {
         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, maxCommitSeq));
+        const view = await this.#clientView(partition);
+        const clients = (await list(partition)).map(view);
+        clients.sort((a, b) => options.sort === 'lag' ? b.lag - a.lag : b.updatedAtMs - a.updatedAtMs);
+        return {
+            clients: clients.slice(0, options.limit ?? DEFAULT_CLIENT_LIMIT),
+            total: clients.length,
+        };
     }
     /**
      * 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.
+     * lease store is wired, its realtime state, 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({
+            partition,
             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),
+            client: (await this.#clientView(partition))(record),
             ...(lease !== undefined ? { lease } : {}),
             events,
         };
@@ -123,10 +226,56 @@ export class SyncularAdmin {
         const read = required(this.#storage.listCommitMetadata?.bind(this.#storage), 'storage');
         return read(partition, {
             afterSeq: options.afterSeq ?? 0,
+            ...(options.beforeSeq !== undefined
+                ? { beforeSeq: options.beforeSeq }
+                : {}),
             limit: options.limit ?? DEFAULT_COMMIT_LIMIT,
             ...(options.table !== undefined ? { table: options.table } : {}),
+            ...(options.changeSample !== undefined
+                ? { changeSample: options.changeSample }
+                : {}),
         });
     }
+    /**
+     * One retained commit with every change rendered per §11. Throws
+     * `sync.not_found` when the commit does not exist or was pruned.
+     */
+    async commitDetail(partition, commitSeq) {
+        const read = required(this.#storage.getCommit?.bind(this.#storage), 'storage');
+        const schema = this.#requireSchema();
+        const commit = await read(partition, commitSeq);
+        if (commit === undefined) {
+            throw new SyncError('sync.not_found', 'commit is not in the retained log', JSON.stringify({ commitSeq }));
+        }
+        return {
+            ...commit,
+            changes: commit.changes.map((change) => {
+                const base = {
+                    table: change.table,
+                    rowId: change.rowId,
+                    op: change.op,
+                    ...(change.rowVersion !== undefined
+                        ? { rowVersion: change.rowVersion }
+                        : {}),
+                    scopes: change.scopes,
+                };
+                const table = schema.tables.get(change.table);
+                if (change.payload === undefined)
+                    return base;
+                if (table === undefined)
+                    return { ...base, undecodable: true };
+                try {
+                    return {
+                        ...base,
+                        values: renderRowValues(table.columns, decodeRow(table.columns, change.payload)),
+                    };
+                }
+                catch {
+                    return { ...base, undecodable: true };
+                }
+            }),
+        };
+    }
     /** Pending, leased, completed, and dead-lettered durable reactions. */
     async listReactions(partition, options = {}) {
         const read = required(this.#storage.listReactions?.bind(this.#storage), 'storage');
@@ -137,18 +286,26 @@ export class SyncularAdmin {
         });
     }
     /**
-     * Inspect a single row: current server_version, stored scopes, and the
-     * blobIds it references (when the store tracks references). Payload bytes
-     * are deliberately NOT decoded — the console shows metadata, not content.
+     * Inspect a single row: server_version, stored scopes, its values decoded
+     * per §11, and its retained change history (newest first). Throws
+     * `sync.unknown_table` for a table outside the schema.
      */
-    async inspectRow(partition, table, rowId) {
-        const read = required(this.#storage.getRowScopes?.bind(this.#storage), 'storage');
-        if (this.#schema !== undefined) {
-            await this.#storage.ensureSchema(compileSchema(this.#schema), this.#checkpoints);
+    async inspectRow(partition, table, rowId, options = {}) {
+        const schema = this.#requireSchema();
+        const compiled = schema.tables.get(table);
+        if (compiled === undefined) {
+            throw new SyncError('sync.unknown_table', 'table is not in the server schema', JSON.stringify({ table }));
         }
-        const row = await read(partition, table, rowId);
+        await this.#storage.ensureSchema(schema, this.#checkpoints);
+        const listChanges = required(this.#storage.listRowChanges?.bind(this.#storage), 'storage');
+        const history = await listChanges(partition, {
+            table,
+            rowId,
+            limit: options.historyLimit ?? DEFAULT_ROW_HISTORY_LIMIT,
+        });
+        const row = await this.#storage.getRow(partition, table, rowId);
         if (row === undefined) {
-            return { table, rowId, exists: false };
+            return { table, rowId, exists: false, history };
         }
         return {
             table,
@@ -156,6 +313,242 @@ export class SyncularAdmin {
             exists: true,
             serverVersion: row.serverVersion,
             scopes: row.scopes,
+            values: renderRowValues(compiled.columns, decodeRow(compiled.columns, row.payload)),
+            history,
+        };
+    }
+    /**
+     * Trace whether one client receives one row, combining the row's stored
+     * scopes and newest change with the client's subscriptions, cursor, the
+     * actor's allowed scopes, and its retained push failures. See
+     * `AdminTraceVerdict` for the verdict order.
+     */
+    async traceRow(partition, query) {
+        const { table, rowId, clientId } = query;
+        const row = await this.inspectRow(partition, table, rowId, {
+            historyLimit: 1,
+        });
+        const lastChange = row.history[0];
+        const horizonSeq = await this.#storage.getHorizonSeq(partition);
+        const rejections = this.events({ partition, clientId }).filter((event) => event.type === 'push.rejected' || event.type === 'push.conflicted');
+        const record = await this.#storage.getClientRecord(partition, clientId);
+        const base = {
+            table,
+            rowId,
+            clientId,
+            row,
+            horizonSeq,
+            rejections,
+            ...(lastChange !== undefined ? { lastChange } : {}),
+        };
+        if (record === undefined) {
+            return { ...base, verdict: 'client-unknown', subscriptions: [] };
+        }
+        const allowed = await this.#allowedScopes(partition, record);
+        return {
+            ...base,
+            client: (await this.#clientView(partition))(record),
+            ...(allowed !== undefined ? { allowed } : {}),
+            ...traceVerdict(record, row, lastChange, horizonSeq, allowed),
+        };
+    }
+    /**
+     * Who has one row and who does not: the trace verdict for every known
+     * client in the partition, resolving each actor's allowed scopes once.
+     */
+    async rowDelivery(partition, table, rowId) {
+        const list = required(this.#storage.listClientRecords?.bind(this.#storage), 'storage');
+        const row = await this.inspectRow(partition, table, rowId, {
+            historyLimit: 1,
+        });
+        const lastChange = row.history[0];
+        const horizonSeq = await this.#storage.getHorizonSeq(partition);
+        const view = await this.#clientView(partition);
+        const allowedByActor = new Map();
+        const clients = [];
+        for (const record of await list(partition)) {
+            if (!allowedByActor.has(record.actorId)) {
+                allowedByActor.set(record.actorId, await this.#allowedScopes(partition, record));
+            }
+            clients.push({
+                client: view(record),
+                verdict: traceVerdict(record, row, lastChange, horizonSeq, allowedByActor.get(record.actorId)).verdict,
+            });
+        }
+        clients.sort((a, b) => VERDICT_ORDER.indexOf(a.verdict) - VERDICT_ORDER.indexOf(b.verdict) ||
+            b.client.updatedAtMs - a.client.updatedAtMs);
+        return {
+            table,
+            rowId,
+            row,
+            ...(lastChange !== undefined ? { lastChange } : {}),
+            horizonSeq,
+            clients,
+        };
+    }
+    /**
+     * The partition's actors with their devices (clients), open sockets,
+     * worst lag, and failures in the last 5 minutes; most recently seen
+     * first.
+     */
+    async actors(partition) {
+        const { clients } = await this.listClients(partition, {
+            limit: Number.MAX_SAFE_INTEGER,
+        });
+        // The same per-client tally as `errors()`, so People and the overview's
+        // failure panel agree.
+        const failures = new Map();
+        for (const client of this.errors(partition).byClient) {
+            failures.set(client.actorId, (failures.get(client.actorId) ?? 0) + client.count);
+        }
+        const byActor = new Map();
+        for (const client of clients) {
+            byActor.set(client.actorId, [
+                ...(byActor.get(client.actorId) ?? []),
+                client,
+            ]);
+        }
+        return [...byActor].map(([actorId, devices]) => ({
+            actorId,
+            clients: devices,
+            ...(this.#realtime !== undefined
+                ? { connected: devices.filter((device) => device.connected).length }
+                : {}),
+            lastSeenMs: Math.max(...devices.map((device) => device.updatedAtMs)),
+            maxLag: Math.max(...devices.map((device) => device.lag)),
+            recentFailures: failures.get(actorId) ?? 0,
+        }));
+    }
+    /** Row counts per schema table for the partition. */
+    async tableCounts(partition) {
+        const count = required(this.#storage.countRows?.bind(this.#storage), 'storage');
+        const schema = this.#requireSchema();
+        await this.#storage.ensureSchema(schema, this.#checkpoints);
+        const counts = {};
+        for (const table of schema.tables.keys()) {
+            counts[table] = await count(partition, table);
+        }
+        return counts;
+    }
+    /**
+     * One page of a table's rows decoded per §11, ordered by rowId. With a
+     * `scope`, only rows whose stored scope matches, read through the scope
+     * index.
+     */
+    async listRows(partition, table, options = {}) {
+        const schema = this.#requireSchema();
+        const compiled = schema.tables.get(table);
+        if (compiled === undefined) {
+            throw new SyncError('sync.unknown_table', 'table is not in the server schema', JSON.stringify({ table }));
+        }
+        await this.#storage.ensureSchema(schema, this.#checkpoints);
+        const limit = options.limit ?? DEFAULT_ROW_PAGE_LIMIT;
+        const afterRowId = options.afterRowId ?? null;
+        let rows;
+        if (options.scope !== undefined) {
+            if (!compiled.declaredVariables.has(options.scope.variable)) {
+                throw new SyncError('sync.invalid_request', 'the table declares no such scope variable', JSON.stringify({ table, variable: options.scope.variable }));
+            }
+            rows = await this.#storage.scanRows(partition, {
+                table,
+                scopeFilter: { [options.scope.variable]: [options.scope.value] },
+                afterRowId,
+                limit,
+            });
+        }
+        else {
+            const list = required(this.#storage.listRows?.bind(this.#storage), 'storage');
+            rows = await list(partition, { table, afterRowId, limit });
+        }
+        const last = rows.at(-1);
+        return {
+            table,
+            rows: rows.map((row) => ({
+                rowId: row.rowId,
+                serverVersion: row.serverVersion,
+                scopes: row.scopes,
+                values: renderRowValues(compiled.columns, decodeRow(compiled.columns, row.payload)),
+            })),
+            ...(rows.length === limit && last !== undefined
+                ? { nextAfterRowId: last.rowId }
+                : {}),
+        };
+    }
+    /**
+     * What happened to a write: every stored idempotency outcome for the
+     * clientCommitId (applied with its commitSeq, or rejected with the
+     * per-operation results), plus the retained ring events that carry it.
+     */
+    async findWrite(partition, clientCommitId) {
+        const list = required(this.#storage.listPushResults?.bind(this.#storage), 'storage');
+        const outcomes = (await list(partition, clientCommitId)).map(({ clientId, result }) => ({
+            clientId,
+            status: result.status,
+            ...(result.commitSeq !== undefined
+                ? { commitSeq: result.commitSeq }
+                : {}),
+            ...(result.recordedAtMs !== undefined
+                ? { recordedAtMs: result.recordedAtMs }
+                : {}),
+            results: result.results.map((entry) => entry.status === 'conflict'
+                ? {
+                    ...entry,
+                    serverRow: bytesToBase64(entry.serverRow),
+                    conflictColumns: bytesToBase64(entry.conflictColumns),
+                }
+                : entry),
+        }));
+        const events = this.events({ partition }).filter((event) => 'clientCommitId' in event && event.clientCommitId === clientCommitId);
+        return { clientCommitId, outcomes, events };
+    }
+    /**
+     * Resolve an id pasted from a bug report: clients and actors containing
+     * it, rows with that rowId in any table, the commit with that seq, and
+     * writes with that clientCommitId.
+     */
+    async search(partition, query) {
+        const needle = query.trim();
+        if (needle.length === 0) {
+            throw new SyncError('sync.invalid_request', 'search query is empty');
+        }
+        const { clients } = await this.listClients(partition, {
+            limit: Number.MAX_SAFE_INTEGER,
+        });
+        const schema = this.#requireSchema();
+        await this.#storage.ensureSchema(schema, this.#checkpoints);
+        const rows = [];
+        for (const table of schema.tables.keys()) {
+            if ((await this.#storage.getRow(partition, table, needle)) !== undefined) {
+                rows.push({ table, rowId: needle });
+            }
+        }
+        const read = required(this.#storage.getCommit?.bind(this.#storage), 'storage');
+        const commit = /^\d+$/.test(needle)
+            ? await read(partition, Number.parseInt(needle, 10))
+            : undefined;
+        return {
+            query: needle,
+            clients: clients.filter((client) => client.clientId.includes(needle) || client.actorId === needle),
+            actors: [
+                ...new Set(clients
+                    .map((client) => client.actorId)
+                    .filter((actorId) => actorId.includes(needle))),
+            ],
+            rows,
+            ...(commit !== undefined
+                ? {
+                    commit: {
+                        commitSeq: commit.commitSeq,
+                        clientId: commit.clientId,
+                        clientCommitId: commit.clientCommitId,
+                        actorId: commit.actorId,
+                        createdAtMs: commit.createdAtMs,
+                        changeCount: commit.changeCount,
+                        tables: commit.tables,
+                    },
+                }
+                : {}),
+            writes: (await this.findWrite(partition, needle)).outcomes,
         };
     }
     /**
@@ -204,13 +597,9 @@ export class SyncularAdmin {
             ...(blobs !== undefined ? { blobs } : {}),
         };
     }
-    /** Segment store counters alone (undefined when unsupported/unset). */
-    async segmentStats() {
-        return this.#segments?.stats?.();
-    }
-    /** Blob store counters for a partition (undefined when unsupported/unset). */
-    async blobStats(partition) {
-        return this.#blobs?.stats?.(partition);
+    /** True when a realtime hub is wired: clients report `connected`. */
+    get hasRealtime() {
+        return this.#realtime !== undefined;
     }
     /** True when this admin has an event ring wired (the event tail is live). */
     get hasEventStream() {
@@ -231,58 +620,178 @@ export class SyncularAdmin {
     /**
      * 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.
+     * and per-bucket series. Only events carrying this `partition` count.
+     * `coverage` reports when the ring dropped events inside the window.
      */
     metrics(partition, options = {}) {
-        const windowMs = options.windowMs ?? DEFAULT_METRICS_WINDOW_MS;
+        const windowMs = options.windowMs ?? DEFAULT_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 bucketDurations = Array.from({ length: bucketCount }, () => []);
+        const bucketPushes = Array.from({ length: bucketCount }, () => ({
+            applied: 0,
+            rejected: 0,
+            conflicted: 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;
+        const pushes = { applied: 0, rejected: 0, conflicted: 0 };
+        for (const event of this.events({ partition, sinceMs })) {
+            const bucket = Math.min(bucketCount - 1, Math.max(0, Math.floor((event.atMs - sinceMs) / widthMs)));
+            const outcome = event.type === 'push.applied'
+                ? 'applied'
+                : event.type === 'push.rejected'
+                    ? 'rejected'
+                    : event.type === 'push.conflicted'
+                        ? 'conflicted'
+                        : undefined;
+            if (outcome !== undefined) {
+                pushes[outcome] += 1;
+                const slot = bucketPushes[bucket];
+                if (slot !== undefined)
+                    slot[outcome] += 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)));
+            bucketDurations[bucket]?.push(event.durationMs);
             counts[bucket] = (counts[bucket] ?? 0) + 1;
-            if (failed)
+            if (event.outcome === 'rejected' || event.outcome === 'error') {
+                errorCount += 1;
                 errors[bucket] = (errors[bucket] ?? 0) + 1;
+            }
         }
         return {
             partition,
             windowMs,
             atMs,
+            coverage: this.#coverage(sinceMs),
             requests: {
-                count: requestCount,
-                perMinute: requestCount / (windowMs / 60_000),
+                count: durations.length,
+                perMinute: durations.length / (windowMs / 60_000),
                 errorCount,
-                errorRate: requestCount === 0 ? 0 : errorCount / requestCount,
+                errorRate: durations.length === 0 ? 0 : errorCount / durations.length,
                 p50Ms: percentile(durations, 0.5),
                 p95Ms: percentile(durations, 0.95),
             },
-            pushes: { applied, rejected, conflicted },
-            buckets: { widthMs, counts, errors },
+            pushes,
+            buckets: {
+                widthMs,
+                counts,
+                errors,
+                p95Ms: bucketDurations.map((sample) => sample.length === 0 ? null : percentile(sample, 0.95)),
+                pushes: bucketPushes,
+            },
+        };
+    }
+    /**
+     * Failures over a trailing window, grouped by source and code and by
+     * client: failed requests, push rejections and conflicts, dead-lettered
+     * reactions, and throwing scope resolvers. Derived from the ring.
+     */
+    errors(partition, options = {}) {
+        const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+        const atMs = this.#clock();
+        const sinceMs = atMs - windowMs;
+        const groups = new Map();
+        const byClient = new Map();
+        // Newest first, so the first event per group or client is its latest.
+        for (const event of this.events({ partition, sinceMs })) {
+            let source;
+            let code;
+            let clientId;
+            let actorId;
+            if (event.type === 'request.handled') {
+                if (event.outcome !== 'rejected' && event.outcome !== 'error')
+                    continue;
+                source = 'request';
+                code = event.errorCode ?? 'sync.internal_error';
+                clientId = event.clientId;
+                actorId = event.actorId;
+            }
+            else if (event.type === 'push.rejected') {
+                source = 'push';
+                code = event.code;
+                clientId = event.clientId;
+                actorId = event.actorId;
+            }
+            else if (event.type === 'push.conflicted') {
+                source = 'push';
+                code = 'sync.version_conflict';
+                clientId = event.clientId;
+                actorId = event.actorId;
+            }
+            else if (event.type === 'reaction.dead_lettered') {
+                source = 'reaction';
+                code = event.errorCode;
+            }
+            else if (event.type === 'scopes.resolve_failed') {
+                source = 'scopes';
+                code = 'scopes.resolve_failed';
+                actorId = event.actorId;
+            }
+            else {
+                continue;
+            }
+            const key = `${source} ${code}`;
+            const group = groups.get(key) ?? {
+                source,
+                code,
+                count: 0,
+                clients: new Set(),
+                actors: new Set(),
+                rows: new Map(),
+                lastAtMs: event.atMs,
+            };
+            group.count += 1;
+            if ((event.type === 'push.rejected' || event.type === 'push.conflicted') &&
+                event.table !== undefined &&
+                event.rowId !== undefined) {
+                group.rows.set(`${event.table} ${event.rowId}`, {
+                    table: event.table,
+                    rowId: event.rowId,
+                });
+            }
+            if (clientId !== undefined)
+                group.clients.add(clientId);
+            if (actorId !== undefined)
+                group.actors.add(actorId);
+            groups.set(key, group);
+            if (clientId !== undefined && actorId !== undefined) {
+                const seen = byClient.get(clientId);
+                byClient.set(clientId, seen !== undefined
+                    ? { ...seen, count: seen.count + 1 }
+                    : {
+                        clientId,
+                        actorId,
+                        count: 1,
+                        lastCode: code,
+                        lastAtMs: event.atMs,
+                    });
+            }
+        }
+        return {
+            partition,
+            windowMs,
+            atMs,
+            coverage: this.#coverage(sinceMs),
+            byCode: [...groups.values()]
+                .sort((a, b) => b.count - a.count)
+                .map((group) => ({
+                source: group.source,
+                code: group.code,
+                count: group.count,
+                clients: group.clients.size,
+                actors: group.actors.size,
+                lastAtMs: group.lastAtMs,
+                sampleClientIds: [...group.clients].slice(0, 5),
+                sampleRows: [...group.rows.values()].slice(0, 5),
+            })),
+            byClient: [...byClient.values()].sort((a, b) => b.count - a.count),
         };
     }
     /** Every authenticated partition in the storage-backed registry. */
@@ -291,14 +800,18 @@ export class SyncularAdmin {
     }
     /**
      * 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.
+     * counts, prune recommendation — paged by `offset`/`limit` (default 100)
+     * because each row costs several reads. A cross-partition read (every
+     * other method is partition-scoped); host authorization should account
+     * for it.
      */
-    async partitionsOverview() {
+    async partitionsOverview(options = {}) {
         const partitions = await this.listPartitions();
+        const offset = options.offset ?? 0;
+        const page = partitions.slice(offset, offset + (options.limit ?? DEFAULT_PARTITION_LIMIT));
         const activeFloorMs = this.#clock() - this.#retention.activeWindowMs;
         const out = [];
-        for (const partition of partitions) {
+        for (const partition of page) {
             const status = await this.horizonStatus(partition);
             const cursors = await this.#storage.listClientCursors(partition);
             out.push({
@@ -312,6 +825,125 @@ export class SyncularAdmin {
                 recommendation: status.recommendation,
             });
         }
-        return out;
+        return { partitions: out, total: partitions.length };
+    }
+    /**
+     * Operator action: requeue a dead-lettered reaction. Throws
+     * `sync.invalid_request` when the key names no dead-lettered reaction.
+     */
+    async retryReaction(partition, idempotencyKey) {
+        const retry = required(this.#storage.retryReaction?.bind(this.#storage), 'storage');
+        const read = required(this.#storage.getReaction?.bind(this.#storage), 'storage');
+        if (!(await retry(partition, idempotencyKey, this.#clock()))) {
+            throw new SyncError('sync.invalid_request', 'no dead-lettered reaction with this key', JSON.stringify({ idempotencyKey }));
+        }
+        const reaction = await read(partition, idempotencyKey);
+        if (reaction === undefined) {
+            throw new Error('SyncularAdmin: a retried reaction disappeared');
+        }
+        return reaction;
+    }
+    /** Operator action: one §4.6 prune pass now, emitting `prune.completed`. */
+    async prune(partition) {
+        const previousHorizonSeq = await this.#storage.getHorizonSeq(partition);
+        const horizonSeq = await pruneCommitLog({
+            storage: this.#storage,
+            partition,
+            nowMs: this.#clock(),
+            retention: this.#retention,
+            ...(this.#events !== undefined ? { events: this.#events } : {}),
+        });
+        return { previousHorizonSeq, horizonSeq };
+    }
+    /**
+     * Operator action: revoke the client's §7.3 lease (§7.3.4), emitting
+     * `lease.revoked`. Throws `sync.invalid_request` when the client holds no
+     * lease.
+     */
+    async revokeLease(partition, clientId) {
+        const leases = required(this.#leases, 'lease store');
+        const lease = await leases.get(partition, clientId);
+        if (lease === undefined) {
+            throw new SyncError('sync.invalid_request', 'the client holds no lease', JSON.stringify({ clientId }));
+        }
+        await leases.revoke(partition, lease.leaseId);
+        if (this.#events !== undefined) {
+            emitEvent(this.#events, {
+                type: 'lease.revoked',
+                atMs: this.#clock(),
+                partition,
+                leaseId: lease.leaseId,
+            });
+        }
+        return { ...lease, revoked: true };
+    }
+    #requireSchema() {
+        if (this.#schema === undefined) {
+            throw new Error('SyncularAdmin: row reads require the server schema');
+        }
+        return this.#schema;
+    }
+    /**
+     * Map client records to `AdminClient` with one read of the head, the
+     * active floor, and the hub's open sockets for the partition.
+     */
+    async #clientView(partition) {
+        const maxCommitSeq = await this.#storage.getMaxCommitSeq(partition);
+        const activeFloorMs = this.#clock() - this.#retention.activeWindowMs;
+        const sockets = this.#realtime?.connections(partition);
+        const connectedSince = new Map();
+        for (const socket of sockets ?? []) {
+            const since = connectedSince.get(socket.clientId);
+            if (since === undefined || socket.openedAtMs < since) {
+                connectedSince.set(socket.clientId, socket.openedAtMs);
+            }
+        }
+        return (record) => {
+            let schemaVersion;
+            for (const sub of record.subscriptions) {
+                if (sub.schemaVersion !== undefined &&
+                    (schemaVersion === undefined || sub.schemaVersion > schemaVersion)) {
+                    schemaVersion = sub.schemaVersion;
+                }
+            }
+            const connectedSinceMs = connectedSince.get(record.clientId);
+            return {
+                clientId: record.clientId,
+                actorId: record.actorId,
+                wireVersion: record.wireVersion,
+                ...(schemaVersion !== undefined ? { schemaVersion } : {}),
+                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,
+                    table: sub.table,
+                    scopes: sub.scopes,
+                })),
+                active: record.updatedAtMs >= activeFloorMs,
+                ...(sockets !== undefined
+                    ? { connected: connectedSinceMs !== undefined }
+                    : {}),
+                ...(connectedSinceMs !== undefined ? { connectedSinceMs } : {}),
+            };
+        };
+    }
+    /** The actor's allowed scopes from the host resolver, if one is wired. */
+    async #allowedScopes(partition, record) {
+        if (this.#resolveScopes === undefined)
+            return undefined;
+        const resolved = await this.#resolveScopes({
+            partition,
+            actorId: record.actorId,
+            clientId: record.clientId,
+        });
+        return resolved === RESOLVER_OUTAGE ? 'outage' : resolved;
+    }
+    #coverage(sinceMs) {
+        const evicted = this.#ring?.evictedThroughMs;
+        return evicted === undefined || evicted < sinceMs
+            ? { complete: true, fromMs: sinceMs }
+            : { complete: false, fromMs: evicted };
     }
 }