@syncular/server 0.31.0 → 0.32.1

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) {
@@ -144,6 +144,7 @@ class D1Transaction {
      * `tbl\u0000rowId` → the pending state, consulted by `getRow` before D1.
      */
     #pending = new Map();
+    #clearedTombstones = new Set();
     constructor(db, partition, resolveTable, prepareQuery, pushApplySerialized) {
         this.#db = db;
         this.#partition = partition;
@@ -175,6 +176,9 @@ class D1Transaction {
     }
     async getTombstoneSeq(table, rowId) {
         this.#assertOpen();
+        if (this.#clearedTombstones.has(_a.#key(table, rowId))) {
+            return undefined;
+        }
         // Persisted read, no #pending overlay: a delete buffered by this commit
         // records its tombstone at appendCommit, matching the SQLite/Postgres
         // adapters where the tombstone insert also runs at commit append.
@@ -186,6 +190,7 @@ class D1Transaction {
     }
     async clearTombstone(table, rowId) {
         this.#assertOpen();
+        this.#clearedTombstones.add(_a.#key(table, rowId));
         this.#buffer_('DELETE FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?', [this.#partition, table, rowId]);
     }
     async getPushResult(clientId, clientCommitId) {
@@ -250,7 +255,7 @@ class D1Transaction {
             }
         }
         return [...rows.values()]
-            .sort((left, right) => left.rowId.localeCompare(right.rowId))
+            .sort((left, right) => left.rowId < right.rowId ? -1 : left.rowId > right.rowId ? 1 : 0)
             .slice(0, query.limit);
     }
     async scanRowsByIndex(query) {
@@ -287,7 +292,7 @@ class D1Transaction {
                 rows.set(rowId, pending.row);
         }
         return [...rows.values()]
-            .sort((left, right) => left.rowId.localeCompare(right.rowId))
+            .sort((left, right) => left.rowId < right.rowId ? -1 : left.rowId > right.rowId ? 1 : 0)
             .slice(0, query.limit);
     }
     async queryAuthoritative(query) {
@@ -334,6 +339,7 @@ class D1Transaction {
         }
         this.#buffer.length = checkpoint;
         this.#pending.clear();
+        this.#clearedTombstones.clear();
         this.#maxCommitSeq = undefined;
         this.#applicationOpIndexes.clear();
         await this.putPushResult(clientId, clientCommitId, result);
@@ -1664,24 +1670,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 +1738,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 +1856,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;
     }
@@ -335,25 +341,35 @@ async function* streamResponse(plan, ctx, schema, report) {
     }
     try {
         // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
+        const currentSchema = compileSchema(ctx.schema);
         let acceptedThrough = 0;
         for (const push of plan.pushes) {
-            const processed = await processPushCommitWithTrace(ctx, compileSchema(ctx.schema), plan.resolved, plan.header.clientId, push, schema);
+            const processed = await processPushCommitWithTrace(ctx, currentSchema, plan.resolved, plan.header.clientId, push, schema);
             acceptedThrough = Math.max(acceptedThrough, processed.frame.commitSeq ?? 0);
             const frame = {
                 ...processed.frame,
                 results: processed.frame.results.map((result) => {
-                    if (result.status !== 'conflict')
+                    if (result.status !== 'conflict' || schema === currentSchema) {
                         return result;
+                    }
                     const operation = push.operations[result.opIndex];
+                    // §2.3: a replay returns the persisted result without rebuilding
+                    // operations, so a reused clientCommitId with changed operations
+                    // leaves no table to project the stored conflict row through.
+                    if (operation === undefined) {
+                        throw syncError('sync.invalid_request', 'replayed clientCommitId carries changed operations', JSON.stringify({
+                            clientCommitId: push.clientCommitId,
+                            opIndex: result.opIndex,
+                        }));
+                    }
                     const target = schema.tables.get(operation.table);
-                    const current = compileSchema(ctx.schema).tables.get(operation.table);
+                    const bitmapBytes = Math.ceil(target.columns.length / 8);
                     return {
                         ...result,
-                        serverRow: projectRowPayload(current, target, result.serverRow),
+                        serverRow: projectRowPayload(currentSchema.tables.get(operation.table), target, result.serverRow),
                         conflictColumns: result.conflictColumns
-                            .slice(0, Math.ceil(target.columns.length / 8))
-                            .map((byte, i) => i === Math.ceil(target.columns.length / 8) - 1 &&
-                            target.columns.length % 8 !== 0
+                            .slice(0, bitmapBytes)
+                            .map((byte, i) => i === bitmapBytes - 1 && target.columns.length % 8 !== 0
                             ? byte & ((1 << (target.columns.length % 8)) - 1)
                             : byte),
                     };
@@ -498,15 +514,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 +639,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/operations.js

@@ -4,7 +4,7 @@ import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPar
 import { reportError, SyncError, syncError } from './errors.js';
 import { processPushOperationsWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
-import { authorizeWrite } from './scopes.js';
+import { authorizeWrite, renderScopeValue, } from './scopes.js';
 import { transactionQuery } from './storage-query.js';
 import { toValidateRow } from './validate.js';
 function scopeAllowed(allowed, variable, value) {
@@ -265,9 +265,9 @@ function commandOperations(mutations, schema) {
             }
             return mutation.values[column.name] ?? null;
         });
-        const rowId = values[table.primaryKeyIndex];
-        if (typeof rowId !== 'string' || rowId.length === 0) {
-            throw syncError('operation.invalid_request', 'command upsert requires a non-empty string primary key');
+        const rowId = renderScopeValue(values[table.primaryKeyIndex]);
+        if (rowId === undefined) {
+            throw syncError('operation.invalid_request', 'command upsert requires a non-empty primary key');
         }
         return {
             table: table.name,

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[]>;
 }