@syncular/server 0.31.0 → 0.32.0

package/dist/d1-storage.d.ts

@@ -42,7 +42,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
  */
 import { type ScopeMap } from '@syncular/core';
 import type { CompiledSchema, CompiledTable } from './schema.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 interface D1PreparedStatement {
     bind(...values: unknown[]): D1PreparedStatement;
     first<T = Record<string, unknown>>(): Promise<T | null>;
@@ -136,10 +136,11 @@ export declare class D1ServerStorage 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/d1-storage.js

@@ -45,9 +45,9 @@ import { StorageQueryError } from './storage-errors.js';
 import { decodeRow } from '@syncular/core';
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertAppendOnlyMigration, assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, latestScopedChangeSeqSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertAppendOnlyMigration, 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, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
-import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, serializePushResult, sqliteDdlStatements, toStoredRow, } from './sqlite-dialect.js';
+import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, serializePushResult, sqliteDdlStatements, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
 function toStoredReaction(record) {
@@ -1664,24 +1664,61 @@ export class D1ServerStorage {
         }));
     }
     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 { results: rows } = query.table
             ? await this.#db
                 .prepare(`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 ?`)
-                .bind(partition, query.afterSeq, query.table, query.limit)
+                .bind(partition, query.afterSeq, beforeSeq, query.table, query.limit)
                 .all()
             : await this.#db
                 .prepare(`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 ?`)
-                .bind(partition, query.afterSeq, query.limit)
+                .bind(partition, query.afterSeq, beforeSeq, query.limit)
                 .all();
         const out = [];
+        // `changeSample`: extra statement(s) 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);
+            // D1 caps the bound parameters of one statement, so a page larger than
+            // that cap splits into a few chunk statements, never one per commit.
+            const chunkSize = D1_MAX_BIND_PARAMS - 2;
+            for (let offset = 0; offset < seqs.length; offset += chunkSize) {
+                const chunk = seqs.slice(offset, offset + chunkSize);
+                const { results: changes } = await this.#db
+                    .prepare(`SELECT commit_seq, tbl, row_id, op FROM sync_changes
+             WHERE partition=? AND commit_seq IN (${placeholders(chunk.length)}) AND idx<?
+             ORDER BY commit_seq, idx`)
+                    .bind(partition, ...chunk, sampleCount)
+                    .all();
+                for (const change of changes) {
+                    const sample = samples.get(change.commit_seq) ?? [];
+                    sample.push({
+                        table: change.tbl,
+                        rowId: change.row_id,
+                        op: change.op === 1 ? 'upsert' : 'delete',
+                    });
+                    samples.set(change.commit_seq, sample);
+                }
+            }
+        }
         for (const row of rows) {
             const { results: changes } = await this.#db
                 .prepare('SELECT tbl, count(*) AS n FROM sync_changes WHERE partition=? AND commit_seq=? GROUP BY tbl')
@@ -1695,10 +1732,95 @@ export class D1ServerStorage {
                 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) ?? [] }
+                    : {}),
             });
         }
         return out;
     }
+    async getCommit(partition, commitSeq) {
+        const meta = await this.#db
+            .prepare('SELECT client_id, client_commit_id, actor_id, created_at_ms FROM sync_commits WHERE partition=? AND commit_seq=?')
+            .bind(partition, commitSeq)
+            .first();
+        if (meta === null)
+            return undefined;
+        const { results: changeRows } = await this.#db
+            .prepare('SELECT tbl, row_id, op, row_version, scopes, payload FROM sync_changes WHERE partition=? AND commit_seq=? ORDER BY idx')
+            .bind(partition, commitSeq)
+            .all();
+        const changes = changeRows.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).
+        const { results: rows } = await this.#db
+            .prepare(`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 ?`)
+            .bind(partition, query.table, query.rowId, query.limit)
+            .all();
+        return rows.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.
+        const { results } = await this.#schemaDatabase()
+            .prepare(`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 ?`)
+            .bind(partition, query.afterRowId ?? '', query.limit)
+            .all();
+        return results.map(toStoredRow);
+    }
+    async countRows(partition, table) {
+        const record = await this.#schemaDatabase()
+            .prepare(`SELECT count(*) AS n FROM ${quoteIdent(this.table(table).name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?`)
+            .bind(partition)
+            .first();
+        return record?.n ?? 0;
+    }
+    async listPushResults(partition, clientCommitId) {
+        // Retained outcomes for one clientCommitId: no dedicated index, ordered
+        // by client so the read is deterministic.
+        const { results } = await this.#schemaDatabase()
+            .prepare('SELECT client_id, result FROM sync_push_results WHERE partition=? AND client_commit_id=? ORDER BY client_id')
+            .bind(partition, clientCommitId)
+            .all();
+        return results.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) {
         const { results: rows } = await this.#db
             .prepare(`SELECT DISTINCT commit_seq, tbl FROM sync_change_scopes
@@ -1728,19 +1850,6 @@ export class D1ServerStorage {
         }
         return out;
     }
-    async getRowScopes(partition, table, rowId) {
-        const db = this.#schemaDatabase();
-        const record = await db
-            .prepare(selectRowScopesSql(this.table(table), 'sqlite'))
-            .bind(partition, rowId)
-            .first();
-        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/events-ring.d.ts

@@ -3,8 +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?, clientId?,
- * actorId?, limit})` plus a `subscribe(listener)` hook for live tails. It
+ * N events in memory and exposes a `query({type?, partition?, 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
@@ -15,6 +15,10 @@ import { type SyncularServerEvent, type SyncularServerEvents } from './events.js
 export interface RingEventQuery {
     /** Restrict to one event `type` (e.g. `push.applied`). */
     readonly type?: SyncularServerEvent['type'];
+    /** Restrict to one partition (every event carries one). */
+    readonly partition?: string;
+    /** Restrict to the events of one sync request. */
+    readonly requestId?: string;
     /** Only events with `atMs >= sinceMs`. */
     readonly sinceMs?: number;
     /** Restrict to events carrying this `clientId` (not every type does). */
@@ -56,6 +60,12 @@ export declare class RingBufferEvents implements SyncularServerEvents {
     get capacity(): number;
     /** The number of events currently retained. */
     get size(): number;
+    /**
+     * The newest `atMs` among events the ring dropped (evicted when full, or
+     * cleared); `undefined` while nothing was dropped. A window that starts
+     * at or before it is incomplete.
+     */
+    get evictedThroughMs(): number | undefined;
     /**
      * Newest-first slice of the retained events. Filters by `type` and
      * `sinceMs`, then caps to `limit`. Returns a fresh array — the caller may

package/dist/events-ring.js

@@ -3,8 +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?, clientId?,
- * actorId?, limit})` plus a `subscribe(listener)` hook for live tails. It
+ * N events in memory and exposes a `query({type?, partition?, 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,6 +21,12 @@ import { emitEvent, } from './events.js';
 export function matchesRingQuery(event, query) {
     if (query.type !== undefined && event.type !== query.type)
         return false;
+    if (query.partition !== undefined && event.partition !== query.partition) {
+        return false;
+    }
+    if (query.requestId !== undefined && event.requestId !== query.requestId) {
+        return false;
+    }
     if (query.sinceMs !== undefined && event.atMs < query.sinceMs)
         return false;
     const carrier = event;
@@ -46,6 +52,7 @@ export class RingBufferEvents {
     /** Index of the oldest element in the circular buffer. */
     #head = 0;
     #size = 0;
+    #evictedThroughMs;
     /** Live subscribers (the SSE tail). Each notify is guarded. */
     #listeners = new Set();
     constructor(options) {
@@ -62,6 +69,9 @@ export class RingBufferEvents {
         }
         else {
             // Full: overwrite the oldest and advance the head.
+            const evicted = this.#buffer[this.#head];
+            if (evicted !== undefined)
+                this.#markEvicted(evicted.atMs);
             this.#buffer[this.#head] = event;
             this.#head = (this.#head + 1) % this.#capacity;
         }
@@ -94,6 +104,19 @@ export class RingBufferEvents {
     get size() {
         return this.#size;
     }
+    /**
+     * The newest `atMs` among events the ring dropped (evicted when full, or
+     * cleared); `undefined` while nothing was dropped. A window that starts
+     * at or before it is incomplete.
+     */
+    get evictedThroughMs() {
+        return this.#evictedThroughMs;
+    }
+    #markEvicted(atMs) {
+        if (this.#evictedThroughMs === undefined || atMs > this.#evictedThroughMs) {
+            this.#evictedThroughMs = atMs;
+        }
+    }
     /**
      * Newest-first slice of the retained events. Filters by `type` and
      * `sinceMs`, then caps to `limit`. Returns a fresh array — the caller may
@@ -115,6 +138,8 @@ export class RingBufferEvents {
     }
     /** Drop all retained events. */
     clear() {
+        for (const event of this.#buffer)
+            this.#markEvicted(event.atMs);
         this.#buffer = [];
         this.#head = 0;
         this.#size = 0;

package/dist/events.d.ts

@@ -28,11 +28,15 @@ export interface RequestHandledEvent {
     /**
      * `ok` — response streamed to END;
      * `schema_floor` — §2.4 required-schema answer;
-     * `reset` — §2.1 log-epoch reset answer;
+     * `epoch_acquired` — §2.1 answer to a request without `logEpoch` (a new
+     *   or wiped replica's first round);
+     * `reset` — §2.1 answer to a `logEpoch` that no longer matches the log;
      * `rejected` — request validation failed before any bytes (§1.7);
      * `error` — in-band ERROR frame (§1.6) or a thrown host failure.
      */
-    readonly outcome: 'ok' | 'schema_floor' | 'reset' | 'rejected' | 'error';
+    readonly outcome: 'ok' | 'schema_floor' | 'epoch_acquired' | 'reset' | 'rejected' | 'error';
+    /** The REQ_HEADER clientId; absent when the request failed to decode. */
+    readonly clientId?: string;
     /** §10.2 code for `rejected`/`error`; `"internal"` for non-SyncErrors. */
     readonly errorCode?: string;
     readonly pushCommits: number;
@@ -60,6 +64,9 @@ export interface PushRejectedEvent extends PushEventBase {
     readonly type: 'push.rejected';
     readonly code: string;
     readonly opIndex: number;
+    /** The terminating operation's table and rowId. */
+    readonly table?: string;
+    readonly rowId?: string;
     /** True when the rejection was replayed from the idempotency cache. */
     readonly replay: boolean;
     /** Original host time for outcomes recorded by a metadata-aware server. */
@@ -71,6 +78,9 @@ export interface PushRejectedEvent extends PushEventBase {
 export interface PushConflictedEvent extends PushEventBase {
     readonly type: 'push.conflicted';
     readonly opIndex: number;
+    /** The conflicting operation's table and rowId. */
+    readonly table?: string;
+    readonly rowId?: string;
     /** True when the conflict was replayed from the idempotency cache. */
     readonly replay: boolean;
     readonly recordedAtMs?: number;
@@ -277,7 +287,15 @@ export interface LeaseRevokedEvent {
     readonly partition: string;
     readonly leaseId: string;
 }
-export type SyncularServerEvent = RequestHandledEvent | PushAppliedEvent | PushRejectedEvent | PushConflictedEvent | ReactionQueuedEvent | ReactionStartedEvent | ReactionRetriedEvent | ReactionCompletedEvent | ReactionDeadLetteredEvent | ReactionPruneCompletedEvent | PullServedEvent | SegmentDownloadedEvent | BlobUploadedEvent | BlobDownloadedEvent | BlobSweptEvent | RealtimeOpenedEvent | RealtimeClosedEvent | RealtimeDeltaEvent | RealtimeWakeEvent | PruneCompletedEvent | ScopesResolveFailedEvent | LeaseIssuedEvent | LeaseRevokedEvent;
+/**
+ * Every event. `requestId` is present on the events emitted while serving
+ * one sync request (`request.handled`, `push.*`, `pull.served`,
+ * `lease.issued`, `reaction.queued`, `scopes.resolve_failed`) and shared by
+ * all of them, so a sink can group one request's events.
+ */
+export type SyncularServerEvent = (RequestHandledEvent | PushAppliedEvent | PushRejectedEvent | PushConflictedEvent | ReactionQueuedEvent | ReactionStartedEvent | ReactionRetriedEvent | ReactionCompletedEvent | ReactionDeadLetteredEvent | ReactionPruneCompletedEvent | PullServedEvent | SegmentDownloadedEvent | BlobUploadedEvent | BlobDownloadedEvent | BlobSweptEvent | RealtimeOpenedEvent | RealtimeClosedEvent | RealtimeDeltaEvent | RealtimeWakeEvent | PruneCompletedEvent | ScopesResolveFailedEvent | LeaseIssuedEvent | LeaseRevokedEvent) & {
+    readonly requestId?: string;
+};
 /**
  * The seam. Optional on the server config — when absent, no event object
  * is ever built. Implementations receive every event synchronously and

package/dist/handler.js

@@ -253,11 +253,14 @@ function emitPushEvent(events, ctx, clientId, push, processed) {
     }
     // Rejected (§6.3): exactly one terminating operation record.
     const record = frame.results[0];
+    const op = record !== undefined ? push.operations[record.opIndex] : undefined;
+    const target = op !== undefined ? { table: op.table, rowId: op.rowId } : {};
     if (record?.status === 'conflict') {
         emitEvent(events, {
             type: 'push.conflicted',
             ...base,
             opIndex: record.opIndex,
+            ...target,
             replay: processed.replayed,
             ...(processed.recordedAtMs !== undefined
                 ? { recordedAtMs: processed.recordedAtMs }
@@ -275,6 +278,7 @@ function emitPushEvent(events, ctx, clientId, push, processed) {
             ? record.code
             : 'sync.invalid_request',
         opIndex: record?.opIndex ?? 0,
+        ...target,
         replay: processed.replayed,
         ...(processed.recordedAtMs !== undefined
             ? { recordedAtMs: processed.recordedAtMs }
@@ -309,8 +313,10 @@ async function* streamResponse(plan, ctx, schema, report) {
             : {}),
     }, plan.wireVersion);
     if (plan.epochReset) {
-        if (report !== undefined)
-            report.outcome = 'reset';
+        if (report !== undefined) {
+            report.outcome =
+                plan.header.logEpoch === undefined ? 'epoch_acquired' : 'reset';
+        }
         yield END_FRAME_BYTES;
         return;
     }
@@ -498,15 +504,21 @@ async function* streamResponse(plan, ctx, schema, report) {
  * bytes are produced; adapters map them to HTTP JSON errors (§1.1).
  */
 export async function createSyncResponseStream(bytes, ctx) {
-    const events = ctx.events;
-    if (events === undefined)
+    const sink = ctx.events;
+    if (sink === undefined)
         return createStreamCore(bytes, ctx, undefined);
     // Instrumented path: measure with the ctx clock, count bytes at the
-    // seam, emit exactly one `request.handled` per request.
+    // seam, emit exactly one `request.handled` per request. Every event of
+    // this request carries one `requestId`.
+    const requestId = crypto.randomUUID();
+    const events = {
+        emit: (event) => sink.emit({ ...event, requestId }),
+    };
+    const requestCtx = { ...ctx, events };
     const clock = clockOf(ctx);
     const startedAtMs = clock();
     try {
-        return await createStreamCore(bytes, ctx, events, startedAtMs);
+        return await createStreamCore(bytes, requestCtx, events, startedAtMs);
     }
     catch (error) {
         emitEvent(events, {
@@ -617,6 +629,7 @@ async function* instrumentedStream(stream, ctx, events, plan, report, bytesIn, s
             bytesIn,
             bytesOut,
             outcome: report.outcome,
+            clientId: plan.header.clientId,
             ...(report.errorCode !== undefined
                 ? { errorCode: report.errorCode }
                 : {}),

package/dist/postgres-storage.d.ts

@@ -39,7 +39,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { ScopeMap } from '@syncular/core';
 import { type PgExecutor } from './pg-executor.js';
 import type { CompiledSchema, CompiledTable } from './schema.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredCommit, 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, StoredCheckpoint, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -136,10 +136,11 @@ export declare class PostgresServerStorage 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/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);
     }