@syncular/server 0.15.48 → 0.17.0

package/dist/operations.d.ts

@@ -1,3 +1,4 @@
+import { type AuthoritativeRelationPlan } from './authoritative-query.js';
 import { type RemoteOperationResponse, type RowValue } from '@syncular/core';
 import type { SyncRequestContext } from './context.js';
 import type { AuthoritativeQueryValue } from './storage.js';
@@ -20,6 +21,7 @@ export interface AuthoritativeQueryDescriptor<Params = undefined> {
     readonly hasParams: boolean;
     readonly sql: string;
     readonly tables: readonly string[];
+    readonly relationPlans: readonly AuthoritativeRelationPlan[];
     readonly resultColumns: readonly {
         readonly name: string;
         readonly type: 'string' | 'integer' | 'float' | 'boolean' | 'json' | 'bytes' | 'blob_ref' | 'crdt';

package/dist/operations.js

@@ -1,3 +1,4 @@
+import { validateAuthoritativeRelationPlan, } from './authoritative-query.js';
 import { decodeRow, decodeRemoteOperationRequest, encodeRow, encodeRemoteOperationResponse, } from '@syncular/core';
 import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
 import { SyncError, syncError } from './errors.js';
@@ -97,13 +98,19 @@ function normalizeQueryRows(rows, columns) {
 }
 /** Register one generated named query as an authoritative remote operation. */
 export function registerRemoteQuery(descriptor, options) {
-    if (descriptor.id.length === 0 ||
+    if (!Array.isArray(descriptor.relationPlans) ||
+        !descriptor.relationPlans.some((plan) => plan.sql === descriptor.sql) ||
+        descriptor.relationPlans.some((plan) => !Array.isArray(plan.relations)) ||
+        descriptor.id.length === 0 ||
         new Set(descriptor.tables).size !== descriptor.tables.length ||
         !Array.isArray(descriptor.resultColumns) ||
         descriptor.resultColumns.length === 0 ||
         new Set(descriptor.resultColumns.map((column) => column.name)).size !==
             descriptor.resultColumns.length) {
-        throw new Error('remote query requires a non-empty id and unique tables and result columns');
+        throw new Error('remote query requires generated relation plans, a non-empty id, and unique tables and result columns; regenerate queries');
+    }
+    for (const plan of descriptor.relationPlans) {
+        validateAuthoritativeRelationPlan(plan, descriptor.tables);
     }
     if (!Number.isSafeInteger(options.maxRows) ||
         options.maxRows < 1 ||
@@ -173,12 +180,24 @@ export function registerRemoteQuery(descriptor, options) {
             if (ctx.storage.queryAuthoritative === undefined) {
                 throw syncError('operation.storage_unsupported', 'configured storage does not implement authoritative queries');
             }
-            await ctx.storage.ensureSchema(schema);
             const selectedSql = descriptor.sqlFor?.(params) ?? descriptor.sql;
+            const plan = descriptor.relationPlans.find((candidate) => candidate.sql === selectedSql);
+            if (plan === undefined) {
+                throw syncError('operation.invalid_request', 'selected SQL has no generated relation plan; regenerate queries');
+            }
+            await ctx.storage.ensureSchema(schema);
+            const prefix = 'SELECT * FROM (';
             let result;
             try {
                 result = await ctx.storage.queryAuthoritative(ctx.partition, {
-                    sql: `SELECT * FROM (${selectedSql}) AS "_syncular_registered_query" LIMIT ?`,
+                    plan: {
+                        sql: `${prefix}${selectedSql}) AS "_syncular_registered_query" LIMIT ?`,
+                        relations: plan.relations.map((relation) => ({
+                            ...relation,
+                            start: relation.start + prefix.length,
+                            end: relation.end + prefix.length,
+                        })),
+                    },
                     params: [...descriptor.bind(params), options.maxRows + 1],
                     tables: descriptor.tables,
                 });

package/dist/postgres-storage.d.ts

@@ -1,3 +1,4 @@
+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, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
@@ -46,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>;
@@ -65,6 +67,9 @@ 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>;
+    advanceClientCursor(partition: string, clientId: string, actorId: string, logEpoch: string, cursor: number, updatedAtMs: number): Promise<void>;
+    updateClientCursor(partition: string, clientId: string, cursor: number, updatedAtMs: number): 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';
@@ -107,6 +109,16 @@ 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) {
+    const locked = await client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1 FOR UPDATE', [partition]);
+    if (locked.rows.length > 0)
+        return;
+    // The first writer initializes the partition. Concurrent initializers may
+    // wait on this insert, so acquire the row lock again before applying writes.
+    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');
 }
@@ -381,9 +393,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;
     }
@@ -433,26 +443,37 @@ class PostgresTransaction {
         // Allocate the next dense commitSeq under a per-partition row lock: the
         // UPDATE … RETURNING serializes concurrent pushes to this partition and
         // never leaves a gap on rollback (see the file header).
-        const { rows } = await q.query(`INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 1)
-       ON CONFLICT (partition) DO UPDATE
-         SET max_commit_seq = sync_partitions.max_commit_seq + 1
-       RETURNING max_commit_seq`, [p]);
-        const commitSeq = asNumber(rows[0]?.max_commit_seq);
-        await q.query(`INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms)
-       VALUES ($1,$2,$3,$4,$5,$6)`, [
+        const { rows } = await q.query(`WITH allocated AS (
+         INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 1)
+         ON CONFLICT (partition) DO UPDATE
+           SET max_commit_seq = sync_partitions.max_commit_seq + 1
+         RETURNING max_commit_seq
+       )
+       INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms)
+       SELECT $1, max_commit_seq, $2, $3, $4, $5 FROM allocated
+       RETURNING commit_seq`, [
             p,
-            commitSeq,
             commit.clientId,
             commit.clientCommitId,
             commit.actorId,
             commit.createdAtMs,
         ]);
+        const commitSeq = asNumber(rows[0]?.commit_seq);
         for (let idx = 0; idx < commit.changes.length; idx++) {
             const change = commit.changes[idx];
             if (change === undefined)
                 continue;
-            await q.query(`INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
-         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)`, [
+            // Bind serialized scopes as text before parsing JSONB. Drivers that
+            // encode JSONB parameters would otherwise store this string as a scalar.
+            await q.query(`WITH inserted AS (
+           INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
+           VALUES ($1,$2,$3,$4,$5,$6,$7,$8::text::jsonb,$9)
+           RETURNING partition, tbl, commit_seq, scopes
+         )
+         INSERT INTO sync_change_scopes(partition, tbl, var, value, commit_seq)
+         SELECT inserted.partition, inserted.tbl, scope.key, scope.value, inserted.commit_seq
+         FROM inserted CROSS JOIN LATERAL jsonb_each_text(inserted.scopes) AS scope
+         ON CONFLICT DO NOTHING`, [
                 p,
                 commitSeq,
                 idx,
@@ -463,10 +484,6 @@ class PostgresTransaction {
                 JSON.stringify(change.scopes),
                 change.payload ?? null,
             ]);
-            for (const [variable, value] of Object.entries(change.scopes)) {
-                await q.query(`INSERT INTO sync_change_scopes(partition, tbl, var, value, commit_seq)
-           VALUES ($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING`, [p, change.table, variable, value, commitSeq]);
-            }
         }
         return commitSeq;
     }
@@ -617,6 +634,9 @@ export class PostgresServerStorage {
                     await client.query('DELETE FROM sync_row_scopes WHERE tbl=$1', [
                         tableName,
                     ]);
+                    await client.query('DELETE FROM sync_blob_refs WHERE tbl=$1', [
+                        tableName,
+                    ]);
                     await client.query(dropTableDdl(tableName));
                 }
                 for (const statement of schemaDdl(schema, existing, 'postgres', existingIndexes)) {
@@ -661,6 +681,7 @@ export class PostgresServerStorage {
         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)
@@ -732,7 +753,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);
@@ -745,19 +766,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]);
@@ -1069,6 +1109,22 @@ export class PostgresServerStorage {
             record.updatedAtMs,
         ]);
     }
+    async advanceClientCursor(partition, clientId, actorId, logEpoch, cursor, updatedAtMs) {
+        await this.#exec.query(`UPDATE sync_clients
+         SET cursor=GREATEST(cursor, $1), updated_at_ms=GREATEST(updated_at_ms, $2)
+         WHERE partition=$3 AND client_id=$4 AND actor_id=$5
+           AND EXISTS (SELECT 1 FROM sync_partition_registry
+                       WHERE partition=sync_clients.partition AND log_epoch=$6)`, [cursor, updatedAtMs, partition, clientId, actorId, logEpoch]);
+    }
+    async updateClientCursor(partition, clientId, cursor, updatedAtMs) {
+        await this.#exec.query(`UPDATE sync_clients
+       SET cursor=GREATEST(cursor, $3), updated_at_ms=GREATEST(updated_at_ms, $4)
+       WHERE partition=$1 AND client_id=$2`, [partition, clientId, cursor, 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) => ({

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.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`
@@ -177,33 +179,17 @@ 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,
@@ -211,18 +197,63 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
         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, logEpoch) {
@@ -330,6 +361,22 @@ export async function* subscriptionSection(ctx, schema, limits, plan, maxSeq, ho
         return { nextCursor: sub.cursor, active: false };
     }
     const token = parseBootstrapToken(sub.bootstrapState, sub.table);
+    let commits = [];
+    if (token === undefined &&
+        sub.cursor >= 0 &&
+        sub.cursor >= horizonSeq &&
+        sub.cursor <= maxSeq) {
+        commits = await ctx.storage.readCommitWindow(ctx.partition, {
+            table: sub.table,
+            scopeFilter: plan.effective,
+            afterSeq: sub.cursor,
+            throughSeq: maxSeq,
+            limitChanges: limits.limitCommits + 1,
+        });
+        // Validate continuity before committing to an active section. A prune
+        // during a paged read can otherwise make an incomplete window look empty.
+        horizonSeq = Math.max(horizonSeq, await ctx.storage.getHorizonSeq(ctx.partition));
+    }
     // §4.6: a cursor behind the horizon (and not resuming a bootstrap)
     // cannot compute deltas — answer `reset` and echo the cursor.
     if (token === undefined && sub.cursor >= 0 && sub.cursor < horizonSeq) {
@@ -390,13 +437,6 @@ export async function* subscriptionSection(ctx, schema, limits, plan, maxSeq, ho
         effectiveScopes: plan.effective,
         bootstrap: false,
     };
-    const commits = await ctx.storage.readCommitWindow(ctx.partition, {
-        table: sub.table,
-        scopeFilter: plan.effective,
-        afterSeq: sub.cursor,
-        throughSeq: maxSeq,
-        limitChanges: limits.limitCommits + 1,
-    });
     let delivered = 0;
     let deliveredCommits = 0;
     let lastDeliveredSeq = sub.cursor;

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

@@ -137,7 +137,7 @@ export declare class RealtimeSession {
     handleBinary(bytes: Uint8Array): Promise<void> | undefined;
     sendHeartbeat(): void;
     sendWake(reason: WakeReason): void;
-    /** Called by the hub for every applied commit, in commitSeq order. */
+    /** Called by the hub for every applied commit notification. */
     deliverCommit(commit: StoredCommit): void;
     close(): void;
 }

package/dist/realtime.js

@@ -191,6 +191,10 @@ export class RealtimeSession {
         if (typeof cursor !== 'number' || !Number.isSafeInteger(cursor))
             return;
         this.cursor = Math.max(this.cursor, cursor);
+        // The client may have caught up through another binding (§8.4). Its ack
+        // 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)
             this.wakePending = false;
         // §8.2: acks update the client cursor record without an HTTP pull.
@@ -468,14 +472,7 @@ export class RealtimeSession {
     }
     async #persistCursor() {
         try {
-            const record = await this.#storage.getClientRecord(this.partition, this.clientId);
-            if (record === undefined)
-                return;
-            await this.#storage.putClientRecord(this.partition, {
-                ...record,
-                cursor: Math.max(record.cursor, this.cursor),
-                updatedAtMs: this.#clock(),
-            });
+            await this.#storage.advanceClientCursor(this.partition, this.clientId, this.actorId, this.logEpoch, this.cursor, this.#clock());
         }
         catch {
             // Cursor persistence is best-effort; the next pull repairs it.
@@ -523,8 +520,9 @@ export class RealtimeSession {
             });
         }
     }
-    /** Called by the hub for every applied commit, in commitSeq order. */
+    /** Called by the hub for every applied commit notification. */
     deliverCommit(commit) {
+        const contiguous = commit.commitSeq === this.lastKnownSeq + 1;
         this.lastKnownSeq = Math.max(this.lastKnownSeq, commit.commitSeq);
         const sections = [];
         for (const registration of this.registrations) {
@@ -544,6 +542,14 @@ export class RealtimeSession {
             if (changes.length > 0)
                 sections.push({ registration, changes });
         }
+        if (!contiguous) {
+            // Pushes allocate commitSeq under the partition lock but notify after
+            // commit, so racing notifications may arrive out of order. A gap,
+            // duplicate, or regression cannot be a delta: the client would apply
+            // and acknowledge a cursor that does not prove the intervening log.
+            this.sendWake('catchup-required');
+            return;
+        }
         if (sections.length === 0)
             return;
         if (this.#activeRound !== undefined) {
@@ -600,7 +606,7 @@ export class RealtimeSession {
         tagged[0] = REALTIME_TAG_DELTA;
         tagged.set(bytes, 1);
         this.#sendSafe(tagged);
-        this.cursor = commit.commitSeq;
+        this.cursor = Math.max(this.cursor, commit.commitSeq);
         const events = this.#events;
         if (events !== undefined) {
             emitEvent(events, {

package/dist/relational-rows.d.ts

@@ -87,7 +87,7 @@ export declare const SYNC_INDEX_PREFIX = "sync_ix_";
 export declare function physicalIndexName(declaredName: string): string;
 /**
  * CREATE INDEX IF NOT EXISTS for the table's user-declared indexes. These use
- * the same declared names and columns the client materializes. Cross-table
+ * the declared columns with a leading server partition column. Cross-table
  * index-name uniqueness is the user's schema concern, as it is client-side.
  * Server-side the physical name carries the {@link SYNC_INDEX_PREFIX}
  * ownership marker.
@@ -181,6 +181,12 @@ export declare function commitWindowPageSql(valueCount: number, dialect: Relatio
 export declare function selectRowScopesSql(table: CompiledTable, dialect: RelationalDialect): string;
 /** DELETE one stored row. Params: [partition, rowId]. */
 export declare function deleteRowSql(table: CompiledTable, dialect: RelationalDialect): string;
+/**
+ * SQLite: remove the old row's exact scope keys before replacing or deleting the row.
+ * Params: [partition, table, rowId, partition, rowId]. The caller keeps this
+ * statement and the row write in the same transaction (or D1 atomic batch).
+ */
+export declare function deleteSqliteRowScopesSql(table: CompiledTable): string;
 /**
  * The schema-version marker table gates DDL work. `ensureSchema` compares the
  * stored version and skips