@syncular/server 0.30.16 → 0.32.0

package/dist/context.d.ts

@@ -7,7 +7,7 @@
 import type { ScopeMap } from '@syncular/core';
 import type { BlobStore } from './blob-store.js';
 import type { CrdtMergerRegistry } from './crdt-merger.js';
-import type { SyncularErrorHandler } from './errors.js';
+import type { SyncularErrorHandler, SyncularErrorMapper } from './errors.js';
 import type { SyncularServerEvents } from './events.js';
 import type { LeaseStore } from './lease-store.js';
 import type { AnyReactionPlanner } from './reactions.js';
@@ -157,11 +157,10 @@ export interface SyncServerConfig {
      */
     readonly blobUploadUrls?: BlobUploadPresignConfig;
     /**
-     * §5.3 sqlite-image builder, injected so the pull path never
-     * statically imports `bun:sqlite`. Absent ⇒ the sqlite-image lane is off
-     * (bit-2 clients are served the rows lane) — the Workers/edge posture. A
-     * Bun or Node host wires `buildSqliteImage` from
-     * `@syncular/server/sqlite`.
+     * §5.3 sqlite-image builder. The host explicitly imports and supplies
+     * `buildSqliteImage` from `@syncular/server/sqlite` on Bun or Node.
+     * Absent ⇒ serve matching stored images or negotiate the rows lane.
+     * The neutral core never imports a runtime-specific builder.
      */
     readonly sqliteImageBuilder?: SqliteImageBuilder;
     readonly realtime?: RealtimeNotifier;
@@ -178,6 +177,17 @@ export interface SyncServerConfig {
      * handler never changes the response.
      */
     readonly onError?: SyncularErrorHandler;
+    /**
+     * Optional synchronous adapter error mapper (§10.2). After `onError`
+     * observes an adapter exception, `mapError` may return a catalog
+     * `SyncError` (including structured `details`, e.g. `retryAfterMs`) that
+     * the adapter answers instead of `sync.internal_error`; `undefined` keeps
+     * the default. A throw, a non-`SyncError` return, or malformed `details`
+     * JSON is contained as `sync.internal_error`. Unlike `onError`, this hook
+     * may affect the response. It does not change the remote-operation
+     * `operation.*` envelope.
+     */
+    readonly mapError?: SyncularErrorMapper;
 }
 /** Per-request context: the config plus host-authenticated identity. */
 export interface SyncRequestContext extends SyncServerConfig {

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) {
@@ -410,13 +410,16 @@ class D1Transaction {
             row,
         });
         const p = this.#partition;
-        this.#buffer_(deleteSqliteRowScopesSql(compiled), [
-            p,
-            table,
-            row.rowId,
-            p,
-            row.rowId,
-        ]);
+        // Scope index maintenance: delete only the old keys the new scope map no
+        // longer carries, then insert the new keys. Keys present in both are left
+        // alone, so the `INSERT OR IGNORE` below finds them and writes nothing.
+        // This DELETE precedes the row upsert in the same atomic batch, and its
+        // subquery reads the row's pre-upsert scope map.
+        const scopesJson = JSON.stringify(row.scopes);
+        this.#buffer_(`${deleteSqliteRowScopesSql(compiled)}
+        AND (var, value) NOT IN (
+          SELECT key, value FROM json_each(?)
+        )`, [p, table, row.rowId, p, row.rowId, scopesJson]);
         this.#buffer_(upsertSql(compiled, 'sqlite'), upsertValues(compiled, p, row, 'sqlite'));
         for (const [variable, value] of Object.entries(row.scopes)) {
             this.#buffer_('INSERT OR IGNORE INTO sync_row_scopes(partition, tbl, var, value, row_id) VALUES (?,?,?,?,?)', [p, table, variable, value, row.rowId]);
@@ -1563,8 +1566,17 @@ export class D1ServerStorage {
         };
     }
     async putClientRecord(partition, record) {
+        // Update the existing record in place, so the table keeps one row per
+        // (partition, client_id). Every non-key field is written from the new
+        // record; a delete-and-insert would drop and recreate the row instead.
         await this.#db
-            .prepare('INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?,?)')
+            .prepare(`INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?,?)
+         ON CONFLICT(partition, client_id) DO UPDATE SET
+           actor_id=excluded.actor_id,
+           wire_version=excluded.wire_version,
+           cursor=excluded.cursor,
+           subscriptions=excluded.subscriptions,
+           updated_at_ms=excluded.updated_at_ms`)
             .bind(partition, record.clientId, record.actorId, record.wireVersion, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs)
             .run();
     }
@@ -1652,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')
@@ -1683,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
@@ -1716,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/errors.d.ts

@@ -44,12 +44,25 @@ export type SyncularErrorRoute = 'sync' | 'operations' | 'segments' | 'blobs' |
 export type SyncularErrorHandler = (error: unknown, context: {
     readonly route: SyncularErrorRoute;
 }) => void;
+/**
+ * Optional synchronous error mapper. After `onError` has observed the
+ * original, `mapError` may translate an adapter exception to a catalog
+ * `SyncError` (with `details` metadata such as `retryAfterMs`) that the
+ * adapter answers instead of `sync.internal_error`. Return `undefined` to
+ * keep the default. A throw, a non-`SyncError` return, or `details` that is
+ * not a JSON document is contained as `sync.internal_error`.
+ */
+export type SyncularErrorMapper = (error: unknown, context: {
+    readonly route: SyncularErrorRoute;
+}) => SyncError | undefined;
 /**
  * The protocol error for an exception an adapter caught. A `SyncError`
- * passes through unchanged. Anything else goes to `onError` and becomes
- * `sync.internal_error` (§10.2), whose message never carries the exception
- * text.
+ * passes through unchanged. Anything else goes to `onError` and answers
+ * `sync.internal_error` (§10.2) unless the optional `mapError` hook returns a
+ * catalog `SyncError` to answer instead. The default `sync.internal_error`
+ * message never carries the exception text; a mapped error's message is the
+ * host's choice.
  */
-export declare function adapterSyncError(error: unknown, onError: SyncularErrorHandler | undefined, route: SyncularErrorRoute): SyncError;
+export declare function adapterSyncError(error: unknown, onError: SyncularErrorHandler | undefined, route: SyncularErrorRoute, mapError?: SyncularErrorMapper): SyncError;
 /** Hand `error` to the host's `onError`; a throwing handler is contained. */
 export declare function reportError(error: unknown, onError: SyncularErrorHandler | undefined, route: SyncularErrorRoute): void;

package/dist/errors.js

@@ -272,10 +272,10 @@ export class SyncError extends Error {
     httpStatus;
     details;
     constructor(code, message, details) {
-        const entry = ERROR_CATALOG[code];
-        if (entry === undefined) {
+        if (!Object.hasOwn(ERROR_CATALOG, code)) {
             throw new Error(`unknown error code ${code} (not in the §10.2 catalog)`);
         }
+        const entry = ERROR_CATALOG[code];
         super(message ?? code);
         this.code = code;
         this.category = entry.category;
@@ -304,14 +304,39 @@ export function errorBody(error) {
 }
 /**
  * The protocol error for an exception an adapter caught. A `SyncError`
- * passes through unchanged. Anything else goes to `onError` and becomes
- * `sync.internal_error` (§10.2), whose message never carries the exception
- * text.
+ * passes through unchanged. Anything else goes to `onError` and answers
+ * `sync.internal_error` (§10.2) unless the optional `mapError` hook returns a
+ * catalog `SyncError` to answer instead. The default `sync.internal_error`
+ * message never carries the exception text; a mapped error's message is the
+ * host's choice.
  */
-export function adapterSyncError(error, onError, route) {
+export function adapterSyncError(error, onError, route, mapError) {
     if (error instanceof SyncError)
         return error;
     reportError(error, onError, route);
+    try {
+        const mapped = mapError?.(error, { route });
+        if (mapped instanceof SyncError) {
+            const { code, message, details } = mapped;
+            let detailsValid = details === undefined;
+            if (!detailsValid && typeof details === 'string') {
+                JSON.parse(details);
+                detailsValid = true;
+            }
+            if (typeof code === 'string' &&
+                typeof message === 'string' &&
+                Object.hasOwn(ERROR_CATALOG, code) &&
+                detailsValid) {
+                // Reconstruct from the validated fields: the catalog owns
+                // retryability and status, so a mutated `SyncError` cannot smuggle a
+                // different entry onto the wire.
+                return new SyncError(code, message, details);
+            }
+        }
+    }
+    catch {
+        // A throwing mapper or getter, or malformed details, keeps the default.
+    }
     return new SyncError('sync.internal_error', 'internal server error');
 }
 /** Hand `error` to the host's `onError`; a throwing handler is contained. */

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