@syncular/server 0.15.47 → 0.16.1

package/dist/postgres-storage.d.ts

@@ -1,6 +1,7 @@
+import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import { type PgExecutor } from './pg-executor.js';
 import type { CompiledSchema, CompiledTable } from './schema.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -23,7 +24,7 @@ import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorI
  *     set, §5.9.5) as an index range, never a scan. `postgres-explain
  *     .test.ts` asserts an `Index` node here too.
  */
-export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result JSONB NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload JSONB NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,\n  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,\n  last_failure JSONB,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\n";
+export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n  partition TEXT PRIMARY KEY,\n  log_epoch TEXT NOT NULL,\n  epoch_required BOOLEAN NOT NULL DEFAULT FALSE,\n  last_authenticated_at_ms BIGINT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result JSONB NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload JSONB NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,\n  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,\n  last_failure JSONB,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  wire_version INTEGER NOT NULL DEFAULT 1,\n  cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nALTER TABLE sync_clients\n  ADD COLUMN IF NOT EXISTS wire_version INTEGER NOT NULL DEFAULT 1;\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\n";
 export declare class PostgresServerStorage implements ServerStorage {
     #private;
     constructor(exec: PgExecutor);
@@ -32,6 +33,9 @@ export declare class PostgresServerStorage implements ServerStorage {
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name: string): CompiledTable;
     ensureSchema(schema: CompiledSchema): Promise<void>;
+    touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
+    rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
+    listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
     /**
      * Open a real Postgres transaction. The push handler drives the returned
      * `StorageTransaction` imperatively (getRow/upsert/…/commit), but the
@@ -43,9 +47,10 @@ export declare class PostgresServerStorage implements ServerStorage {
     begin(partition: string): Promise<StorageTransaction>;
     getMaxCommitSeq(partition: string): Promise<number>;
     queryAuthoritative(partition: string, query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
+    getPartitionLogEpoch(partition: string): Promise<string | undefined>;
     getHorizonSeq(partition: string): Promise<number>;
     setHorizonSeq(partition: string, seq: number): Promise<void>;
-    pruneCommitsThrough(partition: string, seq: number): Promise<number>;
+    pruneCommitsThrough(partition: string, query: CommitPruneQuery): Promise<CommitPruneResult>;
     getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
     getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
     getPushResult(partition: string, clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
@@ -62,6 +67,7 @@ export declare class PostgresServerStorage implements ServerStorage {
     scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
     getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
     putClientRecord(partition: string, record: ClientRecord): Promise<void>;
+    getActiveClientCursorFloor(partition: string, cutoffMs: number): Promise<number | null>;
     listClientCursors(partition: string): Promise<ClientCursorInfo[]>;
     listRowsReferencingBlob(partition: string, blobId: string): Promise<{
         readonly table: string;

package/dist/postgres-storage.js

@@ -1,3 +1,5 @@
+import { validateCommitPruneQuery } from './prune.js';
+import { StorageQueryError } from './storage-errors.js';
 import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
@@ -33,6 +35,12 @@ CREATE TABLE IF NOT EXISTS sync_partitions(
   max_commit_seq BIGINT NOT NULL DEFAULT 0,
   horizon_seq BIGINT NOT NULL DEFAULT 0
 );
+CREATE TABLE IF NOT EXISTS sync_partition_registry(
+  partition TEXT PRIMARY KEY,
+  log_epoch TEXT NOT NULL,
+  epoch_required BOOLEAN NOT NULL DEFAULT FALSE,
+  last_authenticated_at_ms BIGINT NOT NULL
+);
 CREATE TABLE IF NOT EXISTS sync_row_scopes(
   partition TEXT NOT NULL, tbl TEXT NOT NULL,
   var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,
@@ -86,10 +94,13 @@ CREATE INDEX IF NOT EXISTS sync_reactions_dead_letter
   ON sync_reactions(partition, status, available_at_ms, idempotency_key);
 CREATE TABLE IF NOT EXISTS sync_clients(
   partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,
+  wire_version INTEGER NOT NULL DEFAULT 1,
   cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,
   updated_at_ms BIGINT NOT NULL,
   PRIMARY KEY(partition, client_id)
 );
+ALTER TABLE sync_clients
+  ADD COLUMN IF NOT EXISTS wire_version INTEGER NOT NULL DEFAULT 1;
 CREATE TABLE IF NOT EXISTS sync_blob_refs(
   partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,
   blob_id TEXT NOT NULL,
@@ -98,6 +109,11 @@ CREATE TABLE IF NOT EXISTS sync_blob_refs(
 CREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob
   ON sync_blob_refs(partition, blob_id);
 `;
+async function lockPartitionOn(client, partition) {
+    await client.query(`INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 0)
+    ON CONFLICT (partition) DO NOTHING`, [partition]);
+    await client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1 FOR UPDATE', [partition]);
+}
 function toBase64(bytes) {
     return Buffer.from(bytes).toString('base64');
 }
@@ -372,9 +388,7 @@ class PostgresTransaction {
     }
     async lockPartitionForPush() {
         this.#assertOpen();
-        await this.#client.query(`INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 0)
-       ON CONFLICT (partition) DO NOTHING`, [this.#partition]);
-        await this.#client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1 FOR UPDATE', [this.#partition]);
+        await lockPartitionOn(this.#client, this.#partition);
         await this.#client.query('SAVEPOINT syncular_push_candidate');
         this.#pushApplySavepoint = true;
     }
@@ -628,6 +642,59 @@ export class PostgresServerStorage {
         this.#tables = schema.tables;
         this.#schemaVersion = schema.version;
     }
+    async touchPartition(partition, authenticatedAtMs, initialLogEpoch) {
+        if (initialLogEpoch.length === 0) {
+            throw new Error('initial log epoch must be non-empty');
+        }
+        const { rows } = await this.#exec.query(`INSERT INTO sync_partition_registry(
+         partition, log_epoch, last_authenticated_at_ms
+       ) VALUES ($1,$2,$3)
+       ON CONFLICT(partition) DO UPDATE SET
+         last_authenticated_at_ms=EXCLUDED.last_authenticated_at_ms
+       RETURNING log_epoch, epoch_required, last_authenticated_at_ms`, [partition, initialLogEpoch, authenticatedAtMs]);
+        const row = rows[0];
+        if (row === undefined)
+            throw new Error('partition registry write did not persist');
+        return {
+            partition,
+            logEpoch: row.log_epoch,
+            epochRequired: row.epoch_required,
+            lastAuthenticatedAtMs: asNumber(row.last_authenticated_at_ms),
+        };
+    }
+    async rotatePartitionLogEpoch(partition, logEpoch, authenticatedAtMs) {
+        if (logEpoch.length === 0)
+            throw new Error('log epoch must be non-empty');
+        await this.#exec.transaction(async (client) => {
+            await lockPartitionOn(client, partition);
+            await client.query(`INSERT INTO sync_partition_registry(
+           partition, log_epoch, epoch_required, last_authenticated_at_ms
+         ) VALUES ($1,$2,TRUE,$3)
+         ON CONFLICT(partition) DO UPDATE SET
+           log_epoch=EXCLUDED.log_epoch,
+           epoch_required=TRUE,
+           last_authenticated_at_ms=EXCLUDED.last_authenticated_at_ms`, [partition, logEpoch, authenticatedAtMs]);
+            await client.query('DELETE FROM sync_clients WHERE partition=$1', [
+                partition,
+            ]);
+        });
+        return {
+            partition,
+            logEpoch,
+            epochRequired: true,
+            lastAuthenticatedAtMs: authenticatedAtMs,
+        };
+    }
+    async listPartitionRegistry() {
+        const { rows } = await this.#exec.query(`SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
+         FROM sync_partition_registry ORDER BY partition`, []);
+        return rows.map((row) => ({
+            partition: row.partition,
+            logEpoch: row.log_epoch,
+            epochRequired: row.epoch_required,
+            lastAuthenticatedAtMs: asNumber(row.last_authenticated_at_ms),
+        }));
+    }
     /**
      * Open a real Postgres transaction. The push handler drives the returned
      * `StorageTransaction` imperatively (getRow/upsert/…/commit), but the
@@ -671,7 +738,7 @@ export class PostgresServerStorage {
         if (this.#tables === undefined) {
             throw new Error('ensureSchema(schema) must run before registered queries');
         }
-        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.sql, query.params, query.tables, this.#tables), partition);
+        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.plan, query.params, query.tables, this.#tables), partition);
         return this.#exec.transaction(async (client) => {
             await client.query('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
             const result = await client.query(postgresPlaceholders(prepared.sql), prepared.params);
@@ -684,19 +751,38 @@ export class PostgresServerStorage {
             };
         });
     }
+    async getPartitionLogEpoch(partition) {
+        const { rows } = await this.#exec.query('SELECT log_epoch FROM sync_partition_registry WHERE partition=$1', [partition]);
+        return rows[0]?.log_epoch;
+    }
     async getHorizonSeq(partition) {
         const { rows } = await this.#exec.query('SELECT horizon_seq FROM sync_partitions WHERE partition=$1', [partition]);
         return rows[0] === undefined ? 0 : asNumber(rows[0].horizon_seq);
     }
     async setHorizonSeq(partition, seq) {
         await this.#exec.query(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES ($1,$2)
-       ON CONFLICT (partition) DO UPDATE SET horizon_seq=EXCLUDED.horizon_seq`, [partition, seq]);
+       ON CONFLICT (partition) DO UPDATE SET horizon_seq=GREATEST(sync_partitions.horizon_seq,EXCLUDED.horizon_seq)`, [partition, seq]);
     }
-    async pruneCommitsThrough(partition, seq) {
-        const removed = await this.#exec.query('DELETE FROM sync_commits WHERE partition=$1 AND commit_seq<=$2', [partition, seq]);
-        await this.#exec.query('DELETE FROM sync_changes WHERE partition=$1 AND commit_seq<=$2', [partition, seq]);
-        await this.#exec.query('DELETE FROM sync_change_scopes WHERE partition=$1 AND commit_seq<=$2', [partition, seq]);
-        return removed.rowCount;
+    async pruneCommitsThrough(partition, query) {
+        validateCommitPruneQuery(query);
+        return this.#exec.transaction(async (client) => {
+            await lockPartitionOn(client, partition);
+            const epoch = await client.query('SELECT log_epoch FROM sync_partition_registry WHERE partition=$1 FOR UPDATE', [partition]);
+            if (epoch.rows[0]?.log_epoch !== query.logEpoch)
+                throw new StorageQueryError('sync.storage.prune_epoch_mismatch');
+            const previous = await client.query('SELECT horizon_seq FROM sync_partitions WHERE partition=$1', [partition]);
+            const previousHorizonSeq = asNumber(previous.rows[0]?.horizon_seq);
+            const horizonSeq = Math.max(previousHorizonSeq, query.throughSeq);
+            await client.query('UPDATE sync_partitions SET horizon_seq=$2 WHERE partition=$1', [partition, horizonSeq]);
+            const removed = await client.query('DELETE FROM sync_commits WHERE partition=$1 AND commit_seq<=$2', [partition, horizonSeq]);
+            await client.query('DELETE FROM sync_changes WHERE partition=$1 AND commit_seq<=$2', [partition, horizonSeq]);
+            await client.query('DELETE FROM sync_change_scopes WHERE partition=$1 AND commit_seq<=$2', [partition, horizonSeq]);
+            return {
+                previousHorizonSeq,
+                horizonSeq,
+                removedCommits: removed.rowCount,
+            };
+        });
     }
     async getCommitSeqBefore(partition, createdBeforeMs) {
         const { rows } = await this.#exec.query('SELECT max(commit_seq) AS seq FROM sync_commits WHERE partition=$1 AND created_at_ms<$2', [partition, createdBeforeMs]);
@@ -978,33 +1064,40 @@ export class PostgresServerStorage {
         return scanRowsByIndexOn(this.#exec, this.table(query.table), partition, query);
     }
     async getClientRecord(partition, clientId) {
-        const { rows } = await this.#exec.query('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 AND client_id=$2', [partition, clientId]);
+        const { rows } = await this.#exec.query('SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 AND client_id=$2', [partition, clientId]);
         const record = rows[0];
         if (record === undefined)
             return undefined;
         return {
             clientId: record.client_id,
             actorId: record.actor_id,
+            wireVersion: asNumber(record.wire_version),
             cursor: asNumber(record.cursor),
             updatedAtMs: asNumber(record.updated_at_ms),
             subscriptions: asJson(record.subscriptions),
         };
     }
     async putClientRecord(partition, record) {
-        await this.#exec.query(`INSERT INTO sync_clients(partition, client_id, actor_id, cursor, subscriptions, updated_at_ms)
-       VALUES ($1,$2,$3,$4,$5,$6)
+        await this.#exec.query(`INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms)
+       VALUES ($1,$2,$3,$4,$5,$6,$7)
        ON CONFLICT (partition, client_id) DO UPDATE
-         SET actor_id=EXCLUDED.actor_id, cursor=EXCLUDED.cursor,
+         SET actor_id=EXCLUDED.actor_id, wire_version=EXCLUDED.wire_version,
+             cursor=EXCLUDED.cursor,
              subscriptions=EXCLUDED.subscriptions,
              updated_at_ms=EXCLUDED.updated_at_ms`, [
             partition,
             record.clientId,
             record.actorId,
+            record.wireVersion,
             record.cursor,
             JSON.stringify(record.subscriptions),
             record.updatedAtMs,
         ]);
     }
+    async getActiveClientCursorFloor(partition, cutoffMs) {
+        const { rows } = await this.#exec.query('SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=$1 AND updated_at_ms>=$2', [partition, cutoffMs]);
+        return rows[0].cursor === null ? null : asNumber(rows[0].cursor);
+    }
     async listClientCursors(partition) {
         const { rows } = await this.#exec.query('SELECT client_id, cursor, updated_at_ms FROM sync_clients WHERE partition=$1', [partition]);
         return rows.map((r) => ({
@@ -1040,10 +1133,11 @@ export class PostgresServerStorage {
     }
     // -- admin/console read surface --------------------------------------------
     async listClientRecords(partition) {
-        const { rows } = await this.#exec.query('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 ORDER BY updated_at_ms DESC', [partition]);
+        const { rows } = await this.#exec.query('SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 ORDER BY updated_at_ms DESC', [partition]);
         return rows.map((r) => ({
             clientId: r.client_id,
             actorId: r.actor_id,
+            wireVersion: asNumber(r.wire_version),
             cursor: asNumber(r.cursor),
             updatedAtMs: asNumber(r.updated_at_ms),
             subscriptions: (typeof r.subscriptions === 'string'
@@ -1114,10 +1208,6 @@ export class PostgresServerStorage {
         };
     }
     async listPartitions() {
-        // Union: the registry row appears on first commit, the client row on
-        // first pull — a partition with only one of the two still shows up.
-        const { rows } = await this.#exec.query(`SELECT partition FROM sync_partitions
-       UNION SELECT partition FROM sync_clients ORDER BY partition`, []);
-        return rows.map((r) => r.partition);
+        return (await this.listPartitionRegistry()).map((entry) => entry.partition);
     }
 }

package/dist/prune.d.ts

@@ -7,7 +7,9 @@
  * least the newest `minRetainedCommits` commits are always retained.
  */
 import { type SyncularServerEvents } from './events.js';
-import type { ServerStorage } from './storage.js';
+import type { CommitPruneQuery, ServerStorage } from './storage.js';
+/** Shared validation for the built-in atomic pruning adapters. */
+export declare function validateCommitPruneQuery(query: CommitPruneQuery): void;
 export interface RetentionPolicy {
     /** Active window for laggard cursors (default 14 days). */
     readonly activeWindowMs: number;

package/dist/prune.js

@@ -7,6 +7,16 @@
  * least the newest `minRetainedCommits` commits are always retained.
  */
 import { emitEvent } from './events.js';
+import { StorageQueryError } from './storage-errors.js';
+/** Shared validation for the built-in atomic pruning adapters. */
+export function validateCommitPruneQuery(query) {
+    if (!Number.isSafeInteger(query.throughSeq) ||
+        query.throughSeq < 0 ||
+        typeof query.logEpoch !== 'string' ||
+        query.logEpoch.length === 0) {
+        throw new StorageQueryError('sync.storage.invalid_prune_cursor');
+    }
+}
 export const DEFAULT_RETENTION = {
     activeWindowMs: 14 * 24 * 60 * 60 * 1000,
     ageForceMs: 30 * 24 * 60 * 60 * 1000,
@@ -16,24 +26,18 @@ export const DEFAULT_RETENTION = {
 export async function pruneCommitLog(options) {
     const { storage, partition, nowMs } = options;
     const policy = { ...DEFAULT_RETENTION, ...options.retention };
+    const logEpoch = await storage.getPartitionLogEpoch(partition);
+    if (logEpoch === undefined)
+        throw new StorageQueryError('sync.storage.partition_unregistered');
     const maxSeq = await storage.getMaxCommitSeq(partition);
-    const cursors = await storage.listClientCursors(partition);
-    const activeCursors = cursors
-        .filter((c) => c.updatedAtMs >= nowMs - policy.activeWindowMs)
-        .map((c) => c.cursor);
-    const cursorFloor = activeCursors.length > 0
-        ? Math.min(...activeCursors)
-        : Number.MAX_SAFE_INTEGER;
+    const cursorFloor = (await storage.getActiveClientCursorFloor(partition, nowMs - policy.activeWindowMs)) ?? Number.MAX_SAFE_INTEGER;
     const forcedSeq = await storage.getCommitSeqBefore(partition, nowMs - policy.ageForceMs);
     const retainFloor = maxSeq - policy.minRetainedCommits;
     const target = Math.min(Math.max(cursorFloor, forcedSeq), retainFloor);
-    const current = await storage.getHorizonSeq(partition);
-    const horizon = Math.max(current, Math.max(0, target));
-    let removedCommits = 0;
-    if (horizon > current) {
-        await storage.setHorizonSeq(partition, horizon);
-        removedCommits = await storage.pruneCommitsThrough(partition, horizon);
-    }
+    const { previousHorizonSeq: current, horizonSeq: horizon, removedCommits, } = await storage.pruneCommitsThrough(partition, {
+        logEpoch,
+        throughSeq: Math.max(0, target),
+    });
     const events = options.events;
     if (events !== undefined) {
         emitEvent(events, {

package/dist/pull.d.ts

@@ -41,4 +41,4 @@ export interface PullSectionTrace {
  * Produce the `SUB_START … SUB_END` section for one subscription (§1.6),
  * returning the cursor recorded for the retention watermark (§4.5).
  */
-export declare function subscriptionSection(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plan: SubscriptionPlan, maxSeq: number, horizonSeq: number, trace?: PullSectionTrace): AsyncGenerator<ResponseFrame, SubscriptionResult>;
+export declare function subscriptionSection(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plan: SubscriptionPlan, maxSeq: number, horizonSeq: number, trace?: PullSectionTrace, logEpoch?: string): AsyncGenerator<ResponseFrame, SubscriptionResult>;

package/dist/pull.js

@@ -6,6 +6,8 @@ import { decodeRow, encodeRowsSegment, } from '@syncular/core';
 import { clockOf, limitsOf } from './context.js';
 import { scopeDigest } from './scopes.js';
 import { issueSegmentUrl } from './signed-url.js';
+// One artifact build per owning storage pair and complete immutable identity.
+const imageBuilds = new WeakMap();
 /**
  * Resolve the §5.3 image builder: the host-injected one if present, else the
  * in-tree `buildSqliteImage` on a Bun runtime (dynamic import so `bun:sqlite`
@@ -134,11 +136,12 @@ function segmentRefFrame(record, extra) {
  * bootstrap-storm rule. Returns false when the table is not eligible
  * (the rows lane takes over).
  */
-async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace) {
+async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace, logEpoch) {
     const { storage, segments, partition } = ctx;
     const now = clockOf(ctx)();
     const existing = await segments.find({
         partition,
+        logEpoch,
         table: plan.table.name,
         schemaVersion: schema.version,
         mediaType: 'sqlite',
@@ -176,54 +179,84 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
     const buildImage = await resolveImageBuilder(ctx);
     if (buildImage === undefined)
         return false;
-    // The probe rows are the snapshot's first page — keep them and scan on
-    // from the probe's cursor instead of re-reading the whole prefix (the
-    // scan is keyset-ordered by rowId, so the concatenation is exactly the
-    // rows a single full scan would return).
-    const rows = [...probe];
-    let afterRowId = probe[probe.length - 1]?.rowId ?? null;
-    for (;;) {
-        const scanned = await storage.scanRows(partition, {
-            table: plan.table.name,
-            scopeFilter: plan.effective,
-            afterRowId,
-            limit: 50_000,
-        });
-        rows.push(...scanned);
-        const last = scanned[scanned.length - 1];
-        if (scanned.length < 50_000 || last === undefined)
-            break;
-        afterRowId = last.rowId;
+    let stores = imageBuilds.get(storage);
+    if (stores === undefined) {
+        stores = new WeakMap();
+        imageBuilds.set(storage, stores);
     }
-    const bytes = buildImage({
-        table: plan.table,
-        schemaVersion: schema.version,
-        asOfCommitSeq: asOf,
-        scopeDigest: digest,
-        rows,
-    });
-    const record = await segments.put({
+    let builds = stores.get(segments);
+    if (builds === undefined) {
+        builds = new Map();
+        stores.set(segments, builds);
+    }
+    const identity = {
         partition,
+        logEpoch,
         table: plan.table.name,
         schemaVersion: schema.version,
         mediaType: 'sqlite',
         scopeDigest: digest,
         asOfCommitSeq: asOf,
-        rowCount: rows.length,
-        rowCursor: null,
-        nextRowCursor: null,
-    }, bytes, now);
+    };
+    const key = JSON.stringify(identity);
+    let building = builds.get(key);
+    let builtHere = false;
+    if (building === undefined) {
+        building = (async () => {
+            // Another request can finish while this one's eligibility probe awaits.
+            const cached = await segments.find(identity, clockOf(ctx)());
+            if (cached !== undefined)
+                return cached;
+            builtHere = true;
+            let rowCount = 0;
+            const bytes = await buildImage({
+                table: plan.table,
+                schemaVersion: schema.version,
+                asOfCommitSeq: asOf,
+                scopeDigest: digest,
+                rowBatches: (async function* () {
+                    rowCount += probe.length;
+                    yield probe;
+                    let afterRowId = probe[probe.length - 1].rowId;
+                    for (;;) {
+                        const rows = await storage.scanRows(partition, {
+                            table: plan.table.name,
+                            scopeFilter: plan.effective,
+                            afterRowId,
+                            limit: 5_000,
+                        });
+                        rowCount += rows.length;
+                        yield rows;
+                        const last = rows[rows.length - 1];
+                        if (rows.length < 5_000 || last === undefined)
+                            break;
+                        afterRowId = last.rowId;
+                    }
+                })(),
+            });
+            return segments.put({ ...identity, rowCount, rowCursor: null, nextRowCursor: null }, bytes, clockOf(ctx)());
+        })();
+        builds.set(key, building);
+    }
+    let record;
+    try {
+        record = await building;
+    }
+    finally {
+        if (builds.get(key) === building)
+            builds.delete(key);
+    }
     trace?.segments.push({
         mediaType: 'sqlite',
         delivery: 'ref',
-        origin: 'built',
+        origin: builtHere ? 'built' : 'reused',
         bytes: record.byteLength,
         rows: record.rowCount,
     });
-    yield segmentRefFrame(record, await signedUrlFields(ctx, limits, record.segmentId, digest, now));
+    yield segmentRefFrame(record, await signedUrlFields(ctx, limits, record.segmentId, digest, clockOf(ctx)()));
     return true;
 }
-async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCursor, trace) {
+async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCursor, trace, logEpoch) {
     const { storage, segments, partition } = ctx;
     const serverLimits = limitsOf(ctx);
     const digest = await scopeDigest(plan.effective);
@@ -237,7 +270,7 @@ async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCurso
     if ((limits.accept & ACCEPT_SQLITE) !== 0 &&
         startRowCursor === null &&
         plan.table.encryptedColumnIndices.length === 0) {
-        const imaged = yield* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace);
+        const imaged = yield* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace, logEpoch);
         if (imaged)
             return { complete: true, rowCursor: null };
     }
@@ -281,6 +314,7 @@ async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCurso
         else {
             const record = await segments.put({
                 partition,
+                logEpoch,
                 table: plan.table.name,
                 schemaVersion: schema.version,
                 mediaType: 'rows',
@@ -309,8 +343,11 @@ async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCurso
  * Produce the `SUB_START … SUB_END` section for one subscription (§1.6),
  * returning the cursor recorded for the retention watermark (§4.5).
  */
-export async function* subscriptionSection(ctx, schema, limits, plan, maxSeq, horizonSeq, trace) {
+export async function* subscriptionSection(ctx, schema, limits, plan, maxSeq, horizonSeq, trace, logEpoch) {
     const sub = plan.frame;
+    if (logEpoch === undefined || logEpoch.length === 0) {
+        throw new Error('subscriptionSection requires a non-empty log epoch');
+    }
     if (plan.status === 'revoked') {
         yield {
             type: 'SUB_START',
@@ -355,7 +392,7 @@ export async function* subscriptionSection(ctx, schema, limits, plan, maxSeq, ho
             effectiveScopes: plan.effective,
             bootstrap: true,
         };
-        const outcome = yield* bootstrapSegments(ctx, schema, limits, plan, asOf, startCursor, trace);
+        const outcome = yield* bootstrapSegments(ctx, schema, limits, plan, asOf, startCursor, trace, logEpoch);
         if (outcome.complete) {
             yield { type: 'SUB_END', nextCursor: asOf };
         }

package/dist/push.js

@@ -98,7 +98,7 @@ async function runValidator(validators, table, op, rowId, values, storedValues,
         // §6.7: a non-ValidationRejection throw is still a rejection, mapped to
         // the generic server-side constraint code (§10.2) — the validator's
         // failure never crashes the request or leaks its message as a code.
-        return errorRecord(opIndex, 'sync.constraint_violation', `write validator for table ${JSON.stringify(table.name)} threw: ${error instanceof Error ? error.message : String(error)}`);
+        return errorRecord(opIndex, 'sync.constraint_violation', 'write validator failed');
     }
     return undefined;
 }
@@ -124,7 +124,7 @@ async function mergeCrdtColumns(table, values, storedValues, opIndex, mergers) {
             continue; // NULL clear or absent
         const merger = mergers?.[crdtType];
         if (merger === undefined) {
-            return errorRecord(opIndex, 'sync.crdt_merge_failed', `no CRDT merger registered for crdtType ${JSON.stringify(crdtType)} (§5.10.2)`);
+            return errorRecord(opIndex, 'sync.crdt_merge_failed', 'no CRDT merger registered');
         }
         const storedRaw = storedValues?.[index];
         const stored = storedRaw instanceof Uint8Array ? storedRaw : null;
@@ -132,8 +132,8 @@ async function mergeCrdtColumns(table, values, storedValues, opIndex, mergers) {
         try {
             merged = await merger(stored, incoming);
         }
-        catch (error) {
-            return errorRecord(opIndex, 'sync.crdt_merge_failed', `CRDT merger for ${JSON.stringify(crdtType)} threw: ${error instanceof Error ? error.message : String(error)}`);
+        catch {
+            return errorRecord(opIndex, 'sync.crdt_merge_failed', 'CRDT merger failed');
         }
         values[index] = merged;
         changed = true;
@@ -452,7 +452,7 @@ async function runCommitValidator(validator, tx, schema, clientId, clientCommitI
         if (error instanceof ValidationRejection) {
             return errorRecord(operations[0]?.opIndex ?? 0, error.code, error.message, false, error.details);
         }
-        return errorRecord(operations[0]?.opIndex ?? 0, 'sync.constraint_violation', `whole-commit validator threw: ${error instanceof Error ? error.message : String(error)}`);
+        return errorRecord(operations[0]?.opIndex ?? 0, 'sync.constraint_violation', 'whole-commit validator failed');
     }
     return undefined;
 }

package/dist/realtime.d.ts

@@ -96,6 +96,9 @@ export declare class RealtimeSession {
     readonly partition: string;
     readonly actorId: string;
     readonly clientId: string;
+    readonly logEpoch: string;
+    /** Response/delta layout selected by the most recent socket round. */
+    wireVersion: number;
     /** Highest contiguously applied commitSeq acknowledged by the client. */
     cursor: number;
     /** Suppress deltas until the client catches up via pull + ack (§8.2). */
@@ -105,7 +108,7 @@ export declare class RealtimeSession {
     registrations: readonly Registration[];
     /** Epoch-ms (hub clock) at registration, for `realtime.closed`. */
     readonly openedAtMs: number;
-    constructor(hub: RealtimeHub, options: RealtimeConnectOptions, registrations: readonly Registration[], cursor: number, latestSeq: number, clock: () => number, maxDeltaBytes: number, storage: ServerStorage, events: SyncularServerEvents | undefined);
+    constructor(hub: RealtimeHub, options: RealtimeConnectOptions, registrations: readonly Registration[], cursor: number, latestSeq: number, clock: () => number, maxDeltaBytes: number, storage: ServerStorage, logEpoch: string, wireVersion: number, events: SyncularServerEvents | undefined);
     /** Feed an inbound text frame (client → server control message, §8.2
      * ack, §8.6.2 presence). */
     handleMessage(text: string): void;