@syncular/server 0.31.0 → 0.32.1

package/dist/postgres-storage.js

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

package/dist/push.js

@@ -298,6 +298,7 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
             for (let i = 0; i < table.columns.length; i++) {
                 if (present[i] &&
                     !crdtIndexes.has(i) &&
+                    i !== table.primaryKeyIndex &&
                     effectiveVersion(i) > op.baseVersion) {
                     marked.push(i);
                 }
@@ -602,7 +603,16 @@ async function enforceReferences(tx, schema, staged, clientOpCount, cascadeLimit
     const changes = [];
     const operations = [];
     const originByIndex = [];
+    const finalByRow = new Map();
     for (const write of staged) {
+        const rowKey = `${write.table.name}\u0000${write.rowId}`;
+        const existing = finalByRow.get(rowKey);
+        finalByRow.set(rowKey, {
+            first: existing?.first ?? write,
+            last: write,
+        });
+    }
+    for (const { last: write } of finalByRow.values()) {
         if (write.op !== 'upsert' || write.values === undefined)
             continue;
         for (const reference of write.table.references) {
@@ -636,9 +646,9 @@ async function enforceReferences(tx, schema, staged, clientOpCount, cascadeLimit
     const scheduled = new Set();
     const processed = new Set();
     const queue = [];
-    for (const write of staged) {
-        if (write.op === 'delete' && write.stored !== undefined) {
-            schedule(write.table, write.rowId, write.opIndex, scheduled, queue);
+    for (const { first, last } of finalByRow.values()) {
+        if (last.op === 'delete' && first.stored !== undefined) {
+            schedule(last.table, last.rowId, last.opIndex, scheduled, queue);
         }
     }
     for (let cursor = 0; cursor < queue.length; cursor++) {
@@ -649,6 +659,12 @@ async function enforceReferences(tx, schema, staged, clientOpCount, cascadeLimit
         if (processed.has(key))
             continue;
         processed.add(key);
+        const parentPkColumn = item.table.columns[item.table.primaryKeyIndex];
+        const parentKeyValue = parentPkColumn?.type === 'integer'
+            ? Number(item.rowId)
+            : parentPkColumn?.type === 'boolean'
+                ? item.rowId === 'true'
+                : item.rowId;
         for (const reference of item.table.referencedBy) {
             if (tx.scanRowsByIndex === undefined) {
                 throw new Error('storage transaction does not support declared-reference enforcement (scanRowsByIndex)');
@@ -659,7 +675,7 @@ async function enforceReferences(tx, schema, staged, clientOpCount, cascadeLimit
                 const page = await tx.scanRowsByIndex({
                     table: reference.table,
                     index: reference.index,
-                    values: [item.rowId],
+                    values: [parentKeyValue],
                     afterRowId,
                     limit: 1_000,
                 });
@@ -684,15 +700,20 @@ async function enforceReferences(tx, schema, staged, clientOpCount, cascadeLimit
                 throw new Error(`unreachable: reference child table ${reference.table} is not compiled`);
             }
             for (const childRow of children) {
+                if (reference.onDelete === 'CASCADE') {
+                    if (!schedule(child, childRow.rowId, item.originOpIndex, scheduled, queue)) {
+                        continue;
+                    }
+                }
+                else if (scheduled.has(`${child.name}\u0000${childRow.rowId}`)) {
+                    continue;
+                }
                 if (originByIndex.length >= cascadeLimit) {
                     return {
                         kind: 'terminate',
                         record: referenceRejection(item.originOpIndex, 'declared-reference cascade exceeded the per-commit operation cap (§6.11)', { reason: 'cascade_limit' }),
                     };
                 }
-                if (!schedule(child, childRow.rowId, item.originOpIndex, scheduled, queue)) {
-                    continue;
-                }
                 const syntheticIndex = clientOpCount + originByIndex.length;
                 const storedValues = decodeRow(child.columns, childRow.payload);
                 if (reference.onDelete === 'CASCADE') {

package/dist/realtime.d.ts

@@ -169,13 +169,28 @@ export declare class RealtimeSession {
     deliverCommit(commit: StoredCommit): void;
     close(): void;
 }
+/** One open realtime socket. */
+export interface RealtimeConnection {
+    readonly sessionId: string;
+    readonly clientId: string;
+    readonly actorId: string;
+    readonly openedAtMs: number;
+}
 export declare class RealtimeHub {
     #private;
     /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
     readonly presence: PresenceRegistry;
     constructor(config: RealtimeHubConfig);
     projectPayload(registration: Registration, payload: Uint8Array): Uint8Array;
+    /**
+     * Compose `sink` into the hub's `events`, so socket rounds and sessions
+     * opened afterwards report to it as well. `createSyncularHono` uses it to
+     * feed the admin console's event ring.
+     */
+    addEventSink(sink: SyncularServerEvents): void;
     get sessionCount(): number;
+    /** The partition's open sockets, for the admin console. */
+    connections(partition: string): RealtimeConnection[];
     /** §8.6.2 published-document size cap (bytes). */
     get maxPresenceBytes(): number;
     /** §8.6.4 presence rate cap (ms); 0 = off (reference default). */

package/dist/realtime.js

@@ -16,10 +16,11 @@
  * one handler, two framings); the only JSON data-plane server event is
  * the `sync` wake-up (§8.3).
  */
-import { DecodeError, decodeMessage, encodeMessage, encodePresenceError, encodePresenceFanout, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimePresencePublish, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
+import { DecodeError, decodeMessage, encodeMessage, encodePresenceError, encodePresenceFanout, isSupportedProtocolWireVersion, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimePresencePublish, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
 import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
 import { adapterSyncError, reportError, SyncError, syncError, } from './errors.js';
 import { emitEvent } from './events.js';
+import { composeEvents } from './events-ring.js';
 import { createSyncResponseStream } from './handler.js';
 import { compileSchema, } from './schema.js';
 import { schemaWindowOf, projectRowPayload } from './schema-window.js';
@@ -159,6 +160,8 @@ export class RealtimeSession {
     #registrationGeneration = 0;
     /** Generation of the most recent refresh whose result was applied. */
     #registrationApplied = 0;
+    /** Highest sequence that required a catch-up wake for this session. */
+    #wakeRequiredThroughSeq;
     constructor(hub, options, registrations, cursor, latestSeq, clock, maxDeltaBytes, storage, logEpoch, wireVersion, events) {
         this.sessionId = crypto.randomUUID();
         this.partition = options.partition;
@@ -169,6 +172,7 @@ export class RealtimeSession {
         this.cursor = cursor;
         this.lastKnownSeq = latestSeq;
         this.wakePending = cursor < latestSeq;
+        this.#wakeRequiredThroughSeq = cursor < latestSeq ? latestSeq : 0;
         this.registrations = registrations;
         this.openedAtMs = clock();
         this.#send = options.send;
@@ -207,10 +211,10 @@ export class RealtimeSession {
         // proves those commits no longer need socket notifications, so the next
         // notification must be adjacent to the acknowledged cursor.
         this.lastKnownSeq = Math.max(this.lastKnownSeq, this.cursor);
-        if (this.cursor >= this.lastKnownSeq)
+        if (this.cursor >= this.#wakeRequiredThroughSeq)
             this.wakePending = false;
         // §8.2: acks update the client cursor record without an HTTP pull.
-        this.#persistCursor();
+        this.#persistCursor(cursor);
     }
     /**
      * Resolve once every queued control-plane write has settled (§8.2). A host
@@ -412,7 +416,7 @@ export class RealtimeSession {
         };
         try {
             const requestedWireVersion = (requestBytes[4] ?? 0) | ((requestBytes[5] ?? 0) << 8);
-            if (requestedWireVersion === 1 || requestedWireVersion === 2) {
+            if (isSupportedProtocolWireVersion(requestedWireVersion)) {
                 this.wireVersion = requestedWireVersion;
             }
             let stream;
@@ -536,12 +540,12 @@ export class RealtimeSession {
         this.#closeSocket?.();
         this.#hub.disconnect(this);
     }
-    #persistCursor() {
+    #persistCursor(cursor) {
         // §8.2: start the write now and keep it on the control tail so `drain()`
         // can await it. Two acks may write concurrently: storage folds them with
         // `MAX(cursor, ?)`, so neither order loses the later cursor.
         const write = (async () => {
-            await this.#storage.advanceClientCursor(this.partition, this.clientId, this.actorId, this.logEpoch, this.cursor, this.#clock());
+            await this.#storage.advanceClientCursor(this.partition, this.clientId, this.actorId, this.logEpoch, cursor, this.#clock());
         })();
         write.catch((error) => {
             // Best-effort for the connection (the next pull repairs the cursor);
@@ -570,6 +574,7 @@ export class RealtimeSession {
     }
     sendWake(reason) {
         this.wakePending = true;
+        this.#wakeRequiredThroughSeq = Math.max(this.#wakeRequiredThroughSeq, this.lastKnownSeq);
         this.#sendSafe(JSON.stringify({
             event: 'sync',
             data: {
@@ -714,9 +719,32 @@ export class RealtimeHub {
     projectPayload(registration, payload) {
         return projectRowPayload(this.#schema.tables.get(registration.table), registration.codec, payload);
     }
+    /**
+     * Compose `sink` into the hub's `events`, so socket rounds and sessions
+     * opened afterwards report to it as well. `createSyncularHono` uses it to
+     * feed the admin console's event ring.
+     */
+    addEventSink(sink) {
+        const events = this.#config.events;
+        this.#config = {
+            ...this.#config,
+            events: events === undefined ? sink : composeEvents(events, sink),
+        };
+    }
     get sessionCount() {
         return this.#sessions.size;
     }
+    /** The partition's open sockets, for the admin console. */
+    connections(partition) {
+        return [...this.#sessions]
+            .filter((session) => session.partition === partition)
+            .map((session) => ({
+            sessionId: session.sessionId,
+            clientId: session.clientId,
+            actorId: session.actorId,
+            openedAtMs: session.openedAtMs,
+        }));
+    }
     /** §8.6.2 published-document size cap (bytes). */
     get maxPresenceBytes() {
         return this.#config.maxPresenceBytes ?? DEFAULT_MAX_PRESENCE_BYTES;
@@ -842,6 +870,12 @@ export class RealtimeHub {
             ...(this.#config.commitValidator !== undefined
                 ? { commitValidator: this.#config.commitValidator }
                 : {}),
+            ...(this.#config.reactionPlanner !== undefined
+                ? { reactionPlanner: this.#config.reactionPlanner }
+                : {}),
+            ...(this.#config.checkpoints !== undefined
+                ? { checkpoints: this.#config.checkpoints }
+                : {}),
             ...(this.#config.clock !== undefined
                 ? { clock: this.#config.clock }
                 : {}),
@@ -869,6 +903,9 @@ export class RealtimeHub {
             ...(this.#config.onError !== undefined
                 ? { onError: this.#config.onError }
                 : {}),
+            ...(this.#config.mapError !== undefined
+                ? { mapError: this.#config.mapError }
+                : {}),
             realtime: this,
         };
     }
@@ -905,7 +942,9 @@ export class RealtimeHub {
         const registrations = await this.loadRegistrations(options.partition, options.actorId, options.clientId);
         const latestSeq = await storage.getMaxCommitSeq(options.partition);
         const cursor = record?.cursor ?? -1;
-        const session = new RealtimeSession(this, options, registrations, cursor, latestSeq, clock, this.#config.maxDeltaBytes ?? DEFAULT_MAX_DELTA_BYTES, storage, registry.logEpoch, record?.wireVersion ?? PROTOCOL_WIRE_VERSION, this.#config.events);
+        const session = new RealtimeSession(this, options, registrations, cursor, latestSeq, clock, this.#config.maxDeltaBytes ?? DEFAULT_MAX_DELTA_BYTES, storage, registry.logEpoch, record !== undefined && isSupportedProtocolWireVersion(record.wireVersion)
+            ? record.wireVersion
+            : PROTOCOL_WIRE_VERSION, this.#config.events);
         this.#sessions.add(session);
         const helloResult = options.send(JSON.stringify({
             event: 'hello',

package/dist/seed.js

@@ -13,6 +13,7 @@ import { decodeMessage, encodeMessage, encodeSparseRow, PROTOCOL_WIRE_VERSION, }
 import { SyncError } from './errors.js';
 import { composeEvents } from './events-ring.js';
 import { handleSyncRequest } from './handler.js';
+import { renderScopeValue } from './scopes.js';
 /** Structured terminal failure from the real push path used by a seed. */
 export class SeedMutationError extends Error {
     name = 'SeedMutationError';
@@ -94,9 +95,9 @@ export async function seedMutations(config, target, mutations) {
         }
         const values = table.columns.map((column) => (byColumn.get(column.name) ?? null));
         const pkIndex = table.columns.findIndex((c) => c.name === table.primaryKey);
-        const rowId = values[pkIndex];
-        if (typeof rowId !== 'string' || rowId.length === 0) {
-            throw new SyncError('sync.invalid_request', `seedMutations: table ${table.name}: upsert requires a non-empty string primary key`);
+        const rowId = renderScopeValue(values[pkIndex]);
+        if (rowId === undefined) {
+            throw new SyncError('sync.invalid_request', `seedMutations: table ${table.name}: upsert requires a non-empty primary key`);
         }
         return {
             table: mutation.table,

package/dist/sqlite-storage.d.ts

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

package/dist/sqlite-storage.js

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