@syncular/server 0.30.16 → 0.32.0

package/dist/postgres-storage.js

@@ -5,7 +5,7 @@ import { serveNotReadyError } from './readiness.js';
 import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
-import { assertPhysicalColumns, assertStoredLayouts, COMMIT_WINDOW_BATCH_SQL, LATEST_SCOPED_CHANGE_BATCH_SQL, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowBatchSql, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, prefetchRowsSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, COMMIT_WINDOW_BATCH_SQL, LATEST_SCOPED_CHANGE_BATCH_SQL, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowBatchSql, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, prefetchRowsSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { isPostgresConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
@@ -1659,17 +1659,45 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         }));
     }
     async listCommitMetadata(partition, query) {
+        // Newest-first window, resumed by `afterSeq` (exclusive lower bound) and
+        // ended by `beforeSeq` (exclusive upper bound) when paging older. An
+        // omitted bound is the largest safe commitSeq, so one statement serves
+        // both the bounded and unbounded read.
+        const beforeSeq = query.beforeSeq ?? Number.MAX_SAFE_INTEGER;
         const { rows } = query.table
             ? await this.#exec.query(`SELECT c.commit_seq, c.client_id, c.client_commit_id, c.actor_id, c.created_at_ms
            FROM sync_commits c
-           WHERE c.partition=$1 AND c.commit_seq>$2
+           WHERE c.partition=$1 AND c.commit_seq>$2 AND c.commit_seq<$3
              AND EXISTS (SELECT 1 FROM sync_changes ch
-               WHERE ch.partition=c.partition AND ch.commit_seq=c.commit_seq AND ch.tbl=$3)
-           ORDER BY c.commit_seq DESC LIMIT $4`, [partition, query.afterSeq, query.table, query.limit])
+               WHERE ch.partition=c.partition AND ch.commit_seq=c.commit_seq AND ch.tbl=$4)
+           ORDER BY c.commit_seq DESC LIMIT $5`, [partition, query.afterSeq, beforeSeq, query.table, query.limit])
             : await this.#exec.query(`SELECT commit_seq, client_id, client_commit_id, actor_id, created_at_ms
            FROM sync_commits
-           WHERE partition=$1 AND commit_seq>$2
-           ORDER BY commit_seq DESC LIMIT $3`, [partition, query.afterSeq, query.limit]);
+           WHERE partition=$1 AND commit_seq>$2 AND commit_seq<$3
+           ORDER BY commit_seq DESC LIMIT $4`, [partition, query.afterSeq, beforeSeq, query.limit]);
+        // `changeSample`: one extra statement for the whole page — the first
+        // `sample` changes (change-index order) of every listed commit.
+        const sampleCount = query.changeSample !== undefined &&
+            Number.isInteger(query.changeSample) &&
+            query.changeSample > 0
+            ? query.changeSample
+            : 0;
+        const samples = new Map();
+        if (sampleCount > 0 && rows.length > 0) {
+            const seqs = rows.map((row) => asNumber(row.commit_seq));
+            const { rows: changeRows } = await this.#exec.query(`SELECT commit_seq, tbl, row_id, op FROM sync_changes
+         WHERE partition=$1 AND commit_seq IN (${seqs.map((_, index) => `$${index + 2}`).join(',')}) AND idx<$${seqs.length + 2}
+         ORDER BY commit_seq, idx`, [partition, ...seqs, sampleCount]);
+            for (const change of changeRows) {
+                const sample = samples.get(asNumber(change.commit_seq)) ?? [];
+                sample.push({
+                    table: change.tbl,
+                    rowId: change.row_id,
+                    op: asNumber(change.op) === 1 ? 'upsert' : 'delete',
+                });
+                samples.set(asNumber(change.commit_seq), sample);
+            }
+        }
         const out = [];
         for (const row of rows) {
             const commitSeq = asNumber(row.commit_seq);
@@ -1682,10 +1710,78 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
                 createdAtMs: asNumber(row.created_at_ms),
                 changeCount: changes.rows.reduce((sum, c) => sum + asNumber(c.n), 0),
                 tables: changes.rows.map((c) => c.tbl),
+                ...(sampleCount > 0 ? { sample: samples.get(commitSeq) ?? [] } : {}),
             });
         }
         return out;
     }
+    async getCommit(partition, commitSeq) {
+        const { rows } = await this.#exec.query('SELECT client_id, client_commit_id, actor_id, created_at_ms FROM sync_commits WHERE partition=$1 AND commit_seq=$2', [partition, commitSeq]);
+        const meta = rows[0];
+        if (meta === undefined)
+            return undefined;
+        const { rows: changeRows } = await this.#exec.query('SELECT tbl, row_id, op, row_version, scopes, payload FROM sync_changes WHERE partition=$1 AND commit_seq=$2 ORDER BY idx', [partition, commitSeq]);
+        const changes = changeRows.map(toStoredChange);
+        return {
+            commitSeq,
+            clientId: meta.client_id,
+            clientCommitId: meta.client_commit_id,
+            actorId: meta.actor_id,
+            createdAtMs: asNumber(meta.created_at_ms),
+            changeCount: changes.length,
+            tables: [...new Set(changes.map((change) => change.table))].sort(),
+            changes,
+        };
+    }
+    async listRowChanges(partition, query) {
+        // Retained-log read for one row: no dedicated index (the write path pays
+        // nothing for it), bounded by retention (§4.6).
+        const { rows } = await this.#exec.query(`SELECT ch.commit_seq, ch.op, ch.row_version, c.actor_id, c.client_id, c.created_at_ms
+       FROM sync_changes ch
+       JOIN sync_commits c
+         ON c.partition=ch.partition AND c.commit_seq=ch.commit_seq
+       WHERE ch.partition=$1 AND ch.tbl=$2 AND ch.row_id=$3
+       ORDER BY ch.commit_seq DESC, ch.idx DESC LIMIT $4`, [partition, query.table, query.rowId, query.limit]);
+        return rows.map((row) => ({
+            commitSeq: asNumber(row.commit_seq),
+            op: asNumber(row.op) === 1 ? 'upsert' : 'delete',
+            ...(row.row_version === null || row.row_version === undefined
+                ? {}
+                : { rowVersion: asNumber(row.row_version) }),
+            actorId: row.actor_id,
+            clientId: row.client_id,
+            createdAtMs: asNumber(row.created_at_ms),
+        }));
+    }
+    async listRows(partition, query) {
+        // Keyset page over the row table's (partition, rowId) primary key: an
+        // index range read, no scope filter, no per-row lookup.
+        const { rows } = await this.#exec.query(`SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions
+       FROM ${quoteIdent(this.table(query.table).name)}
+       WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=$1 AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>$2
+       ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT $3`, [partition, query.afterRowId ?? '', query.limit]);
+        return rows.map(toStoredRow);
+    }
+    async countRows(partition, table) {
+        const { rows } = await this.#exec.query(`SELECT count(*) AS n FROM ${quoteIdent(this.table(table).name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=$1`, [partition]);
+        return rows[0] === undefined ? 0 : asNumber(rows[0].n);
+    }
+    async listPushResults(partition, clientCommitId) {
+        // Retained outcomes for one clientCommitId: no dedicated index, ordered
+        // by client so the read is deterministic.
+        const { rows } = await this.#exec.query('SELECT client_id, result FROM sync_push_results WHERE partition=$1 AND client_commit_id=$2 ORDER BY client_id', [partition, clientCommitId]);
+        return rows.map((row) => {
+            try {
+                return {
+                    clientId: row.client_id,
+                    result: deserializePushResult(asJson(row.result)),
+                };
+            }
+            catch {
+                throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
+            }
+        });
+    }
     async scopeActivity(partition, query) {
         const { rows } = await this.#exec.query(`SELECT DISTINCT commit_seq, tbl FROM sync_change_scopes
        WHERE partition=$1 AND var=$2 AND value=$3
@@ -1708,18 +1804,6 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         }
         return out;
     }
-    async getRowScopes(partition, table, rowId) {
-        const { rows } = await this.#exec.query(selectRowScopesSql(this.table(table), 'postgres'), [partition, rowId]);
-        const row = rows[0];
-        if (row === undefined)
-            return undefined;
-        return {
-            serverVersion: asNumber(row.server_version),
-            scopes: (typeof row.scopes === 'string'
-                ? JSON.parse(row.scopes)
-                : row.scopes),
-        };
-    }
     async listPartitions() {
         return (await this.listPartitionRegistry()).map((entry) => entry.partition);
     }

package/dist/pull.js

@@ -10,24 +10,6 @@ import { issueSegmentUrl } from './signed-url.js';
 import { projectRowPayload, projectRowValues } from './schema-window.js';
 // One artifact build per owning storage pair and complete immutable identity.
 const imageBuilds = new WeakMap();
-/**
- * Resolve the §5.3 image builder: the host-injected one if present, else the
- * in-tree `buildSqliteImage` on a Bun runtime (dynamic import so `bun:sqlite`
- * is never a static dep of the neutral core), else `undefined` (rows lane).
- * Memoized so the dynamic import happens at most once per process.
- */
-let cachedDefaultBuilder;
-async function resolveImageBuilder(ctx) {
-    if (ctx.sqliteImageBuilder !== undefined)
-        return ctx.sqliteImageBuilder;
-    if (cachedDefaultBuilder === undefined) {
-        const hasBun = globalThis.Bun !== undefined;
-        cachedDefaultBuilder = hasBun
-            ? (await import('./sqlite-bun.js')).buildSqliteImage
-            : null;
-    }
-    return cachedDefaultBuilder ?? undefined;
-}
 /** §4.2 accept bitmask. */
 export const ACCEPT_INLINE_ROWS = 1 << 0;
 export const ACCEPT_EXTERNAL_ROWS = 1 << 1;
@@ -176,14 +158,9 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
     // The probe is the rows lane's first page, read by `prepareSections`.
     if (probe.length <= limits.limitSnapshotRows)
         return false;
-    // §5.3: building an image needs a SQLite engine. The host injects the
-    // builder through `sqliteImageBuilder`; when omitted we default to the
-    // in-tree `buildSqliteImage` ONLY on a Bun runtime, reached by a *dynamic*
-    // import so `bun:sqlite` is never a static dependency of the pull path
-    // (runtime neutrality is enforced by test/runtime-neutrality.test.ts). On
-    // Workers/edge (no `Bun`) this yields the rows lane for a bit-2 client — a
-    // support floor, not a fallback (§5.3: sqlite is an *accept*, not a demand).
-    const buildImage = await resolveImageBuilder(ctx);
+    // §5.3: hosts opt into image construction with a runtime-specific builder.
+    // Without one, matching stored images remain usable and cold pulls use rows.
+    const buildImage = ctx.sqliteImageBuilder;
     if (buildImage === undefined)
         return false;
     let stores = imageBuilds.get(storage);

package/dist/realtime.d.ts

@@ -18,7 +18,7 @@
  */
 import { type PresenceKind, type ScopeMap, type WakeReason } from '@syncular/core';
 import type { SyncRequestContext, SyncServerConfig } from './context.js';
-import { type SyncularErrorHandler } from './errors.js';
+import { type SyncularErrorHandler, type SyncularErrorMapper } from './errors.js';
 import { type SyncularServerEvents } from './events.js';
 import { type CompiledTable } from './schema.js';
 import type { ServerStorage, StoredCommit } from './storage.js';
@@ -169,13 +169,28 @@ export declare class RealtimeSession {
     deliverCommit(commit: StoredCommit): void;
     close(): void;
 }
+/** One open realtime socket. */
+export interface RealtimeConnection {
+    readonly sessionId: string;
+    readonly clientId: string;
+    readonly actorId: string;
+    readonly openedAtMs: number;
+}
 export declare class RealtimeHub {
     #private;
     /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
     readonly presence: PresenceRegistry;
     constructor(config: RealtimeHubConfig);
     projectPayload(registration: Registration, payload: Uint8Array): Uint8Array;
+    /**
+     * Compose `sink` into the hub's `events`, so socket rounds and sessions
+     * opened afterwards report to it as well. `createSyncularHono` uses it to
+     * feed the admin console's event ring.
+     */
+    addEventSink(sink: SyncularServerEvents): void;
     get sessionCount(): number;
+    /** The partition's open sockets, for the admin console. */
+    connections(partition: string): RealtimeConnection[];
     /** §8.6.2 published-document size cap (bytes). */
     get maxPresenceBytes(): number;
     /** §8.6.4 presence rate cap (ms); 0 = off (reference default). */
@@ -204,6 +219,8 @@ export declare class RealtimeHub {
     }): SyncRequestContext;
     /** The host's error reporter (`SyncServerConfig.onError`), if any. */
     get onError(): SyncularErrorHandler | undefined;
+    /** The host's adapter error mapper (`SyncServerConfig.mapError`), if any. */
+    get mapError(): SyncularErrorMapper | undefined;
     requestContext(session: RealtimeSession): SyncRequestContext;
     /**
      * Register a connected socket (§8.1): load the client's last pull's

package/dist/realtime.js

@@ -20,6 +20,7 @@ import { DecodeError, decodeMessage, encodeMessage, encodePresenceError, encodeP
 import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
 import { adapterSyncError, reportError, SyncError, syncError, } from './errors.js';
 import { emitEvent } from './events.js';
+import { composeEvents } from './events-ring.js';
 import { createSyncResponseStream } from './handler.js';
 import { compileSchema, } from './schema.js';
 import { schemaWindowOf, projectRowPayload } from './schema-window.js';
@@ -436,7 +437,7 @@ export class RealtimeSession {
                 // `sync.internal_error`, exactly like the HTTP adapter's 500.
                 const sync = error instanceof DecodeError
                     ? syncError(error.code, error.message)
-                    : adapterSyncError(error, this.#hub.onError, 'realtime');
+                    : adapterSyncError(error, (error, context) => this.#hub.onError?.(error, context), 'realtime', (error, context) => this.#hub.mapError?.(error, context));
                 finishRound(); // END is in this one chunk
                 await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
                 return;
@@ -460,7 +461,7 @@ export class RealtimeSession {
                 // the §8.7 violation path.
                 const sync = error instanceof DecodeError
                     ? syncError(error.code, error.message)
-                    : adapterSyncError(error, this.#hub.onError, 'realtime');
+                    : adapterSyncError(error, (error, context) => this.#hub.onError?.(error, context), 'realtime', (error, context) => this.#hub.mapError?.(error, context));
                 finishRound();
                 await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
                 return;
@@ -476,7 +477,7 @@ export class RealtimeSession {
         catch (error) {
             // A host failure mid-stream leaves the byte stream unfinishable —
             // fail loud, drop the connection (§8.7 / §1.4 abort rule).
-            reportError(error, this.#hub.onError, 'realtime');
+            reportError(error, (error, context) => this.#hub.onError?.(error, context), 'realtime');
             this.#violation('sync round failed mid-stream');
         }
         finally {
@@ -714,9 +715,32 @@ export class RealtimeHub {
     projectPayload(registration, payload) {
         return projectRowPayload(this.#schema.tables.get(registration.table), registration.codec, payload);
     }
+    /**
+     * Compose `sink` into the hub's `events`, so socket rounds and sessions
+     * opened afterwards report to it as well. `createSyncularHono` uses it to
+     * feed the admin console's event ring.
+     */
+    addEventSink(sink) {
+        const events = this.#config.events;
+        this.#config = {
+            ...this.#config,
+            events: events === undefined ? sink : composeEvents(events, sink),
+        };
+    }
     get sessionCount() {
         return this.#sessions.size;
     }
+    /** The partition's open sockets, for the admin console. */
+    connections(partition) {
+        return [...this.#sessions]
+            .filter((session) => session.partition === partition)
+            .map((session) => ({
+            sessionId: session.sessionId,
+            clientId: session.clientId,
+            actorId: session.actorId,
+            openedAtMs: session.openedAtMs,
+        }));
+    }
     /** §8.6.2 published-document size cap (bytes). */
     get maxPresenceBytes() {
         return this.#config.maxPresenceBytes ?? DEFAULT_MAX_PRESENCE_BYTES;
@@ -876,6 +900,10 @@ export class RealtimeHub {
     get onError() {
         return this.#config.onError;
     }
+    /** The host's adapter error mapper (`SyncServerConfig.mapError`), if any. */
+    get mapError() {
+        return this.#config.mapError;
+    }
     requestContext(session) {
         return this.requestContextFor(session);
     }

package/dist/sqlite-image.d.ts

@@ -18,7 +18,7 @@ export interface SqliteImageInput {
  * a real SQLite engine, which is not available on every runtime. The core
  * takes the builder as an optional capability rather than importing a driver
  * on the pull path. A Bun or Node host passes `buildSqliteImage`; a Workers
- * host omits it and serves the rows lane.
+ * host omits it and serves matching stored images or the rows lane.
  */
 export type SqliteImageBuilder = (input: SqliteImageInput) => Promise<Uint8Array>;
 /** Populate a §5.3 image database for a whole-table snapshot. */

package/dist/sqlite-storage.d.ts

@@ -2,7 +2,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { ScopeMap } from '@syncular/core';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import { type SqliteDatabase } from './sqlite-driver.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export declare class SqliteServerStorage implements ServerStorage {
     #private;
     readonly db: SqliteDatabase;
@@ -69,10 +69,11 @@ export declare class SqliteServerStorage implements ServerStorage {
     listReferencedBlobIds(partition: string): Promise<string[]>;
     listClientRecords(partition: string): Promise<ClientRecord[]>;
     listCommitMetadata(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
+    getCommit(partition: string, commitSeq: number): Promise<CommitDetail | undefined>;
+    listRowChanges(partition: string, query: RowChangesQuery): Promise<RowChangeRecord[]>;
+    listRows(partition: string, query: RowListQuery): Promise<StoredRow[]>;
+    countRows(partition: string, table: string): Promise<number>;
+    listPushResults(partition: string, clientCommitId: string): Promise<ClientPushResult[]>;
     scopeActivity(partition: string, query: ScopeActivityQuery): Promise<ScopeCommitActivity[]>;
-    getRowScopes(partition: string, table: string, rowId: string): Promise<{
-        serverVersion: number;
-        scopes: Record<string, string>;
-    } | undefined>;
     listPartitions(): Promise<string[]>;
 }

package/dist/sqlite-storage.js

@@ -13,9 +13,9 @@ import { serveNotReadyError } from './readiness.js';
  */
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, latestScopedChangeSeqSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, latestScopedChangeSeqSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
-import { collectCommitWindowPage, deserializePushResult, placeholders, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
+import { collectCommitWindowPage, deserializePushResult, placeholders, SQLITE_DDL, serializePushResult, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
 import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
 import { isSqliteConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
@@ -1218,22 +1218,51 @@ END`);
         }));
     }
     async listCommitMetadata(partition, query) {
-        // Newest-first window, resumed by `afterSeq` (exclusive lower bound).
+        // Newest-first window, resumed by `afterSeq` (exclusive lower bound) and
+        // ended by `beforeSeq` (exclusive upper bound) when paging older. An
+        // omitted bound is the largest safe commitSeq, so one statement serves
+        // both the bounded and unbounded read.
+        const beforeSeq = query.beforeSeq ?? Number.MAX_SAFE_INTEGER;
         const rows = query.table
             ? this.db
                 .query(`SELECT c.commit_seq, c.client_id, c.client_commit_id, c.actor_id, c.created_at_ms
              FROM sync_commits c
-             WHERE c.partition=? AND c.commit_seq>?
+             WHERE c.partition=? AND c.commit_seq>? AND c.commit_seq<?
                AND EXISTS (SELECT 1 FROM sync_changes ch
                  WHERE ch.partition=c.partition AND ch.commit_seq=c.commit_seq AND ch.tbl=?)
              ORDER BY c.commit_seq DESC LIMIT ?`)
-                .all(partition, query.afterSeq, query.table, query.limit)
+                .all(partition, query.afterSeq, beforeSeq, query.table, query.limit)
             : this.db
                 .query(`SELECT commit_seq, client_id, client_commit_id, actor_id, created_at_ms
              FROM sync_commits
-             WHERE partition=? AND commit_seq>?
+             WHERE partition=? AND commit_seq>? AND commit_seq<?
              ORDER BY commit_seq DESC LIMIT ?`)
-                .all(partition, query.afterSeq, query.limit);
+                .all(partition, query.afterSeq, beforeSeq, query.limit);
+        // `changeSample`: one extra statement for the whole page — the first
+        // `sample` changes (change-index order) of every listed commit.
+        const sampleCount = query.changeSample !== undefined &&
+            Number.isInteger(query.changeSample) &&
+            query.changeSample > 0
+            ? query.changeSample
+            : 0;
+        const samples = new Map();
+        if (sampleCount > 0 && rows.length > 0) {
+            const seqs = rows.map((row) => row.commit_seq);
+            const records = this.db
+                .query(`SELECT commit_seq, tbl, row_id, op FROM sync_changes
+           WHERE partition=? AND commit_seq IN (${placeholders(seqs.length)}) AND idx<?
+           ORDER BY commit_seq, idx`)
+                .all(partition, ...seqs, sampleCount);
+            for (const record of records) {
+                const sample = samples.get(record.commit_seq) ?? [];
+                sample.push({
+                    table: record.tbl,
+                    rowId: record.row_id,
+                    op: record.op === 1 ? 'upsert' : 'delete',
+                });
+                samples.set(record.commit_seq, sample);
+            }
+        }
         return rows.map((row) => {
             const changes = this.db
                 .query('SELECT tbl, count(*) AS n FROM sync_changes WHERE partition=? AND commit_seq=? GROUP BY tbl')
@@ -1246,9 +1275,88 @@ END`);
                 createdAtMs: row.created_at_ms,
                 changeCount: changes.reduce((sum, c) => sum + c.n, 0),
                 tables: changes.map((c) => c.tbl),
+                ...(sampleCount > 0
+                    ? { sample: samples.get(row.commit_seq) ?? [] }
+                    : {}),
             };
         });
     }
+    async getCommit(partition, commitSeq) {
+        const meta = this.db
+            .query('SELECT client_id, client_commit_id, actor_id, created_at_ms FROM sync_commits WHERE partition=? AND commit_seq=?')
+            .get(partition, commitSeq);
+        if (meta === null)
+            return undefined;
+        const changes = this.db
+            .query('SELECT tbl, row_id, op, row_version, scopes, payload FROM sync_changes WHERE partition=? AND commit_seq=? ORDER BY idx')
+            .all(partition, commitSeq)
+            .map(toStoredChange);
+        return {
+            commitSeq,
+            clientId: meta.client_id,
+            clientCommitId: meta.client_commit_id,
+            actorId: meta.actor_id,
+            createdAtMs: meta.created_at_ms,
+            changeCount: changes.length,
+            tables: [...new Set(changes.map((change) => change.table))].sort(),
+            changes,
+        };
+    }
+    async listRowChanges(partition, query) {
+        // Retained-log read for one row: no dedicated index (the write path pays
+        // nothing for it), bounded by retention (§4.6).
+        return this.db
+            .query(`SELECT ch.commit_seq, ch.op, ch.row_version, c.actor_id, c.client_id, c.created_at_ms
+         FROM sync_changes ch
+         JOIN sync_commits c
+           ON c.partition=ch.partition AND c.commit_seq=ch.commit_seq
+         WHERE ch.partition=? AND ch.tbl=? AND ch.row_id=?
+         ORDER BY ch.commit_seq DESC, ch.idx DESC LIMIT ?`)
+            .all(partition, query.table, query.rowId, query.limit)
+            .map((row) => ({
+            commitSeq: row.commit_seq,
+            op: row.op === 1 ? 'upsert' : 'delete',
+            ...(row.row_version !== null ? { rowVersion: row.row_version } : {}),
+            actorId: row.actor_id,
+            clientId: row.client_id,
+            createdAtMs: row.created_at_ms,
+        }));
+    }
+    async listRows(partition, query) {
+        // Keyset page over the row table's (partition, rowId) primary key: an
+        // index range read, no scope filter, no per-row lookup.
+        return this.db
+            .query(`SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions
+         FROM ${quoteIdent(this.table(query.table).name)}
+         WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=? AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>?
+         ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT ?`)
+            .all(partition, query.afterRowId ?? '', query.limit)
+            .map(toStoredRow);
+    }
+    async countRows(partition, table) {
+        const record = this.db
+            .query(`SELECT count(*) AS n FROM ${quoteIdent(this.table(table).name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?`)
+            .get(partition);
+        return record?.n ?? 0;
+    }
+    async listPushResults(partition, clientCommitId) {
+        // Retained outcomes for one clientCommitId: no dedicated index, ordered
+        // by client so the read is deterministic.
+        return this.db
+            .query('SELECT client_id, result FROM sync_push_results WHERE partition=? AND client_commit_id=? ORDER BY client_id')
+            .all(partition, clientCommitId)
+            .map((record) => {
+            try {
+                return {
+                    clientId: record.client_id,
+                    result: deserializePushResult(record.result),
+                };
+            }
+            catch {
+                throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
+            }
+        });
+    }
     async scopeActivity(partition, query) {
         // Candidate commits via the change-scope index (§3.1) — never a scan.
         const rows = this.db
@@ -1276,17 +1384,6 @@ END`);
         }
         return out;
     }
-    async getRowScopes(partition, table, rowId) {
-        const record = this.db
-            .query(selectRowScopesSql(this.table(table), 'sqlite'))
-            .get(partition, rowId);
-        if (record === null)
-            return undefined;
-        return {
-            serverVersion: record.server_version,
-            scopes: JSON.parse(record.scopes),
-        };
-    }
     async listPartitions() {
         return (await this.listPartitionRegistry()).map((entry) => entry.partition);
     }

package/dist/storage.d.ts

@@ -303,13 +303,55 @@ export interface CommitMetadata {
     readonly createdAtMs: number;
     readonly changeCount: number;
     readonly tables: readonly string[];
+    /** The first `changeSample` changes in commit order, when requested. */
+    readonly sample?: readonly CommitChangeSummary[];
+}
+/** One change without its payload, for commit lists. */
+export interface CommitChangeSummary {
+    readonly table: string;
+    readonly rowId: string;
+    readonly op: 'upsert' | 'delete';
 }
 export interface CommitMetadataQuery {
-    /** Window `afterSeq < commitSeq`, oldest first. */
+    /** Window lower bound, exclusive: `afterSeq < commitSeq`. */
     readonly afterSeq: number;
+    /** Window upper bound, exclusive: `commitSeq < beforeSeq` (older pages). */
+    readonly beforeSeq?: number;
+    /** Newest first, at most `limit` commits. */
     readonly limit: number;
     /** Restrict to commits that touched this table (via the change index). */
     readonly table?: string;
+    /** Attach the first N changes of each commit as `sample`. */
+    readonly changeSample?: number;
+}
+export interface RowListQuery {
+    readonly table: string;
+    /** Resume after this rowId (exclusive); `null` = start of table. */
+    readonly afterRowId: string | null;
+    readonly limit: number;
+}
+/** A stored push outcome with the client that sent it. */
+export interface ClientPushResult {
+    readonly clientId: string;
+    readonly result: StoredPushResult;
+}
+/** One retained commit with its changes, for the admin commit drill-down. */
+export interface CommitDetail extends CommitMetadata {
+    readonly changes: readonly StoredChange[];
+}
+/** One retained change to a single row, for the admin row history. */
+export interface RowChangeRecord {
+    readonly commitSeq: number;
+    readonly op: 'upsert' | 'delete';
+    readonly rowVersion?: number;
+    readonly actorId: string;
+    readonly clientId: string;
+    readonly createdAtMs: number;
+}
+export interface RowChangesQuery {
+    readonly table: string;
+    readonly rowId: string;
+    readonly limit: number;
 }
 /** One recent commit touching a scope key, for the admin scope activity view. */
 export interface ScopeCommitActivity {
@@ -671,18 +713,27 @@ export interface ServerStorage {
      * touched tables), the newest-oriented window an operator inspects.
      * `scopeActivity`: the recent commits touching one scope key, via the
      * 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.
+     * `getCommit`: one retained commit with its changes and payloads;
+     * `undefined` when the commit does not exist or was pruned.
+     * `listRowChanges`: the retained changes to one row, newest first. It
+     * reads the partition's retained log without a dedicated index, so the
+     * write path pays nothing for it and its cost is bounded by retention.
+     * `listRows`: one table's rows ordered by rowId, without a scope filter.
+     * `countRows`: one table's row count.
+     * `listPushResults`: every stored idempotency outcome for one
+     * clientCommitId across the partition's clients, scanning the retained
+     * outcomes without a dedicated index.
      * `listPartitions`: the partition-only compatibility view of
      * `listPartitionRegistry`, sorted.
      */
     listClientRecords?(partition: string): Promise<ClientRecord[]>;
     listCommitMetadata?(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
     scopeActivity?(partition: string, query: ScopeActivityQuery): Promise<ScopeCommitActivity[]>;
-    getRowScopes?(partition: string, table: string, rowId: string): Promise<{
-        serverVersion: number;
-        scopes: Record<string, string>;
-    } | undefined>;
+    getCommit?(partition: string, commitSeq: number): Promise<CommitDetail | undefined>;
+    listRowChanges?(partition: string, query: RowChangesQuery): Promise<RowChangeRecord[]>;
+    listRows?(partition: string, query: RowListQuery): Promise<StoredRow[]>;
+    countRows?(partition: string, table: string): Promise<number>;
+    listPushResults?(partition: string, clientCommitId: string): Promise<ClientPushResult[]>;
     listPartitions(): Promise<string[]>;
 }
 /** A row referencing a blob, with the scopes needed to authorize download. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.30.16",
+  "version": "0.32.0",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.30.16"
+    "@syncular/core": "0.32.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"