@syncular/server 0.15.48 → 0.16.1

package/README.md

@@ -15,6 +15,11 @@ registry, command mutations use the ordinary serialized push path, and
 specified in [`docs/REMOTE.md`](../../docs/REMOTE.md) and the practical setup is
 in the [remote operations guide](https://syncular.dev/guide-remote-operations/).
 
+Remote query registration requires generated `relationPlans` for each selected
+SQL statement. Run `syncular generate` before upgrading existing query modules.
+The server uses those boundaries to bind every physical table occurrence to
+the authenticated partition, including quoted self joins and CTE bodies.
+
 Application intent belongs in immutable domain event rows written in the same
 commit as the state change. `SyncularServerEvents` below remains operational
 telemetry. See the [domain event guide](https://syncular.dev/guide-domain-events/).
@@ -927,10 +932,22 @@ at or below it. Nothing prunes automatically — the host schedules it.
 
 **When to run.** A periodic job per partition — hourly to daily is the
 sensible range; there is no benefit below the granularity of your
-`activeWindowMs`. Prune is cheap when there is nothing to do (one cursor
-scan + two point reads), so err on the side of running it often rather
-than letting a backlog build. Pass `events` to get `prune.completed`
-per pass.
+`activeWindowMs`. Pass `events` to get `prune.completed` per pass.
+
+Pruning verifies the captured log epoch and updates the horizon together with
+commit/change/scope deletion in one transaction. Concurrent passes cannot
+lower the horizon. A retry cleans up eligible records even when the horizon
+already covers them. A restore invalidates a pending pass with
+`sync.storage.prune_epoch_mismatch`; recompute its retention inputs.
+Unregistered partitions cannot be pruned. D1 maintenance enters the owning
+Durable Object's existing write queue through
+`SyncularRealtimeHost.pruneCommitLog`.
+
+Custom storage adapters must add `getPartitionLogEpoch(partition)` and replace
+`pruneCommitsThrough(partition, seq)` with
+`pruneCommitsThrough(partition, { logEpoch, throughSeq })`, returning
+`{ previousHorizonSeq, horizonSeq, removedCommits }` from the transaction.
+`setHorizonSeq` remains monotonic and is no longer used by the pruning helper.
 
 **The retention floors (§4.6, encoded in `RetentionPolicy`).** The
 horizon never advances past `min(cursor)` of *active* clients — clients
@@ -1149,3 +1166,23 @@ deterministic in-process sqlite loopback):
 ```sh
 SYNCULAR_PG_URL=postgres://user:pass@localhost:5432/db bun run bench
 ```
+
+Custom storage adapters must implement
+`getActiveClientCursorFloor(partition, cutoffMs)`. Return the minimum cursor
+whose `updatedAtMs >= cutoffMs`, or `null` when no client qualifies. Preserve
+negative bootstrap cursors. Pruning and admin horizon status use this scalar
+aggregate; `listClientCursors` remains the explicit listing interface.
+
+SQLite image builders now return `Promise<Uint8Array>` and receive
+`rowBatches`, an iterable or async iterable of row arrays. Replace custom
+builders' `input.rows` loop with `for await (const rows of input.rowBatches)`,
+insert each batch into the dedicated image database, and count rows during
+consumption. Write the final row count into `_syncular_segment` before
+serialization. Await `buildSqliteImage(input)` when calling the built-in
+Bun or Node builder directly.
+
+The server shares in-flight builds for the same storage pair and artifact
+identity after authorization. Sharing is local to one process. Signed URL
+grants remain per request. The first eligibility probe has at most
+`limitSnapshotRows + 1` rows; subsequent builder batches have at most 5,000
+rows. The image database and serialized output still consume memory.

package/dist/admin.js

@@ -173,11 +173,7 @@ export class SyncularAdmin {
         const nowMs = this.#clock();
         const maxCommitSeq = await this.#storage.getMaxCommitSeq(partition);
         const horizonSeq = await this.#storage.getHorizonSeq(partition);
-        const cursors = await this.#storage.listClientCursors(partition);
-        const activeCursors = cursors
-            .filter((c) => c.updatedAtMs >= nowMs - this.#retention.activeWindowMs)
-            .map((c) => c.cursor);
-        const activeCursorFloor = activeCursors.length > 0 ? Math.min(...activeCursors) : null;
+        const activeCursorFloor = await this.#storage.getActiveClientCursorFloor(partition, nowMs - this.#retention.activeWindowMs);
         const cursorFloor = activeCursorFloor ?? Number.MAX_SAFE_INTEGER;
         const forcedSeq = await this.#storage.getCommitSeqBefore(partition, nowMs - this.#retention.ageForceMs);
         const retainFloor = maxCommitSeq - this.#retention.minRetainedCommits;

package/dist/authoritative-query.d.ts

@@ -9,12 +9,20 @@ export interface BoundAuthoritativeQuery {
     readonly params: readonly AuthoritativeQueryValue[];
 }
 declare const PARTITION_BIND: unique symbol;
-/**
- * Turn generated local SQL into a partition-local authoritative statement.
- * Only relations declared by the generated descriptor are rewritten. Values
- * remain parameters; request data is never interpolated into SQL.
- */
-export declare function prepareAuthoritativeQuery(sql: string, params: readonly AuthoritativeQueryValue[], declaredTables: readonly string[], tables: ReadonlyMap<string, CompiledTable>): PreparedAuthoritativeQuery;
+/** Compiler-proven occurrences in the exact generated positional statement. */
+export interface AuthoritativeRelationPlan {
+    readonly sql: string;
+    readonly relations: readonly {
+        readonly table: string;
+        readonly start: number;
+        readonly end: number;
+        readonly alias?: string;
+    }[];
+}
+/** Validate trusted generated metadata before registration or storage execution. */
+export declare function validateAuthoritativeRelationPlan(plan: AuthoritativeRelationPlan, declaredTables: readonly string[]): void;
+/** Bind every compiler-proven table occurrence to the authenticated partition. */
+export declare function prepareAuthoritativeQuery(plan: AuthoritativeRelationPlan, params: readonly AuthoritativeQueryValue[], declaredTables: readonly string[], tables: ReadonlyMap<string, CompiledTable>): PreparedAuthoritativeQuery;
 export declare function bindAuthoritativePartition(prepared: PreparedAuthoritativeQuery, partition: string): BoundAuthoritativeQuery;
 export declare function postgresPlaceholders(sql: string): string;
 export {};

package/dist/authoritative-query.js

@@ -1,24 +1,5 @@
 import { quoteIdent, SYNC_PARTITION_COLUMN } from './relational-rows.js';
 const PARTITION_BIND = Symbol('syncular.authoritative_partition');
-const RESERVED_ALIAS = new Set([
-    'on',
-    'where',
-    'group',
-    'order',
-    'inner',
-    'left',
-    'right',
-    'full',
-    'outer',
-    'natural',
-    'join',
-    'cross',
-    'using',
-    'limit',
-    'having',
-]);
-const IDENT = '[A-Za-z_][A-Za-z0-9_]*';
-const TABLE_REF_RE = new RegExp(`\\b(FROM|(?:NATURAL\\s+)?(?:(?:LEFT|RIGHT|FULL)(?:\\s+OUTER)?|INNER|CROSS)?\\s*JOIN)\\s+((?:\\(\\s*)*)(${IDENT})(?:\\s+(?:AS\\s+)?((?!(?:${[...RESERVED_ALIAS].join('|')})\\b)${IDENT}))?`, 'gi');
 function protectedSqlEnd(sql, index) {
     const char = sql[index];
     const next = sql[index + 1];
@@ -48,97 +29,94 @@ function protectedSqlEnd(sql, index) {
     }
     return undefined;
 }
-function maskedSql(sql) {
-    let out = '';
-    let index = 0;
-    while (index < sql.length) {
-        const end = protectedSqlEnd(sql, index);
-        if (end === undefined)
-            out += sql[index];
-        else
-            out += sql.slice(index, end).replace(/[^\n]/g, ' ');
-        index = end ?? index + 1;
+/** Validate trusted generated metadata before registration or storage execution. */
+export function validateAuthoritativeRelationPlan(plan, declaredTables) {
+    if (plan === undefined ||
+        typeof plan.sql !== 'string' ||
+        !Array.isArray(plan.relations)) {
+        throw new Error('registered query requires generated relation plans; regenerate queries');
     }
-    return out;
-}
-/**
- * Turn generated local SQL into a partition-local authoritative statement.
- * Only relations declared by the generated descriptor are rewritten. Values
- * remain parameters; request data is never interpolated into SQL.
- */
-export function prepareAuthoritativeQuery(sql, params, declaredTables, tables) {
-    if (maskedSql(sql).includes(';'))
-        throw new Error('registered query must be one SELECT');
+    const sql = plan.sql;
     const declared = new Set(declaredTables);
-    const masked = maskedSql(sql);
-    const replacements = [];
     const found = new Set();
-    for (const match of masked.matchAll(TABLE_REF_RE)) {
-        const rawTable = match[3];
-        const table = tables.get(rawTable);
-        if (table === undefined)
-            continue;
-        if (!declared.has(table.name)) {
-            throw new Error('registered query table metadata does not match its SQL');
+    let previousEnd = 0;
+    for (const relation of plan.relations) {
+        if (!Number.isSafeInteger(relation.start) ||
+            !Number.isSafeInteger(relation.end) ||
+            relation.start < previousEnd ||
+            relation.end <= relation.start ||
+            relation.end > sql.length) {
+            throw new Error('registered query relation boundaries do not match its SQL; regenerate queries');
         }
-        if (!table.materialize) {
-            throw new Error('registered query targets a non-materialized table');
+        previousEnd = relation.end;
+        if (!declared.has(relation.table)) {
+            throw new Error('registered query table metadata does not match its SQL');
         }
-        let alias = match[4];
-        if (alias !== undefined && RESERVED_ALIAS.has(alias.toLowerCase())) {
-            alias = undefined;
+        const spelling = sql.slice(relation.start, relation.end);
+        const quote = spelling[0];
+        const name = quote === '['
+            ? spelling.slice(1, -1)
+            : quote === '"' || quote === '`'
+                ? spelling
+                    .slice(1, -1)
+                    .split(quote + quote)
+                    .join(quote)
+                : spelling;
+        if (name.toLowerCase() !== relation.table.toLowerCase()) {
+            throw new Error('registered query relation name does not match its SQL; regenerate queries');
         }
-        const matchStart = match.index ?? 0;
-        const afterOperator = match[1].length;
-        const relative = match[0]
-            .toLowerCase()
-            .indexOf(rawTable.toLowerCase(), afterOperator);
-        const start = matchStart + relative;
-        const projection = table.columns.map((column) => quoteIdent(column.name));
-        replacements.push({
-            start,
-            end: start + rawTable.length,
-            text: `(SELECT ${projection.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=/*syncular_partition*/?)${alias === undefined ? ` AS ${quoteIdent(table.name)}` : ''}`,
-        });
-        found.add(table.name);
+        found.add(relation.table);
     }
     if (found.size !== declared.size ||
         [...declared].some((table) => !found.has(table))) {
         throw new Error('registered query table metadata does not match its SQL');
     }
-    let rewritten = sql;
-    for (const replacement of replacements.sort((left, right) => right.start - left.start)) {
-        rewritten =
-            rewritten.slice(0, replacement.start) +
-                replacement.text +
-                rewritten.slice(replacement.end);
-    }
+}
+/** Bind every compiler-proven table occurrence to the authenticated partition. */
+export function prepareAuthoritativeQuery(plan, params, declaredTables, tables) {
+    validateAuthoritativeRelationPlan(plan, declaredTables);
+    const sql = plan.sql;
+    const replacements = plan.relations.map((relation) => {
+        const table = tables.get(relation.table);
+        if (table === undefined)
+            throw new Error('registered query targets an unknown table');
+        if (!table.materialize)
+            throw new Error('registered query targets a non-materialized table');
+        return {
+            start: relation.start,
+            end: relation.end,
+            text: `(SELECT ${table.columns.map((column) => quoteIdent(column.name)).join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?)${relation.alias === undefined ? ` AS ${quoteIdent(table.name)}` : ''}`,
+        };
+    });
     const bound = [];
     let anonymousIndex = 0;
     let rendered = '';
-    for (let index = 0; index < rewritten.length; index += 1) {
-        if (rewritten.startsWith('/*syncular_partition*/?', index)) {
-            rendered += '?';
+    let nextRelation = 0;
+    for (let index = 0; index < sql.length; index += 1) {
+        const replacement = replacements[nextRelation];
+        if (replacement?.start === index) {
+            rendered += replacement.text;
             bound.push(PARTITION_BIND);
-            index += '/*syncular_partition*/?'.length - 1;
+            index = replacement.end - 1;
+            nextRelation += 1;
             continue;
         }
-        const protectedEnd = protectedSqlEnd(rewritten, index);
+        const protectedEnd = protectedSqlEnd(sql, index);
         if (protectedEnd !== undefined) {
-            rendered += rewritten.slice(index, protectedEnd);
+            rendered += sql.slice(index, protectedEnd);
             index = protectedEnd - 1;
             continue;
         }
-        const char = rewritten[index];
+        const char = sql[index];
         if (char !== '?') {
             rendered += char;
             continue;
         }
         let end = index + 1;
-        while (end < rewritten.length && /[0-9]/.test(rewritten[end])) {
+        while (end < sql.length && /[0-9]/.test(sql[end])) {
             end += 1;
         }
-        const numbered = rewritten.slice(index + 1, end);
+        const numbered = sql.slice(index + 1, end);
         const parameterIndex = numbered.length > 0
             ? Number.parseInt(numbered, 10) - 1
             : anonymousIndex++;

package/dist/d1-storage.d.ts

@@ -1,3 +1,4 @@
+import type { CommitPruneQuery, CommitPruneResult } from './storage.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';
 export interface D1PreparedStatement {
@@ -42,9 +43,10 @@ export declare class D1ServerStorage 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>;
@@ -61,6 +63,7 @@ export declare class D1ServerStorage 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/d1-storage.js

@@ -1,4 +1,6 @@
 var _a;
+import { validateCommitPruneQuery } from './prune.js';
+import { StorageQueryError } from './storage-errors.js';
 /**
  * Cloudflare D1 server storage for Workers deployments.
  *
@@ -676,7 +678,7 @@ export class D1ServerStorage {
         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);
         const results = await this.#db.batch([
             this.#db.prepare(prepared.sql).bind(...prepared.params),
             this.#db
@@ -707,6 +709,13 @@ export class D1ServerStorage {
             maxCommitSeq,
         };
     }
+    async getPartitionLogEpoch(partition) {
+        const row = await this.#db
+            .prepare('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
+            .bind(partition)
+            .first();
+        return row?.log_epoch;
+    }
     async getHorizonSeq(partition) {
         const row = await this.#db
             .prepare('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
@@ -716,27 +725,55 @@ export class D1ServerStorage {
     }
     async setHorizonSeq(partition, seq) {
         await this.#db
-            .prepare('INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?) ON CONFLICT(partition) DO UPDATE SET horizon_seq=excluded.horizon_seq')
+            .prepare('INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?) ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)')
             .bind(partition, seq)
             .run();
     }
-    async pruneCommitsThrough(partition, seq) {
-        const before = await this.#db
-            .prepare('SELECT count(*) AS n FROM sync_commits WHERE partition=? AND commit_seq<=?')
-            .bind(partition, seq)
-            .first();
-        await this.#db.batch([
+    async pruneCommitsThrough(partition, query) {
+        validateCommitPruneQuery(query);
+        if (!this.#pushApplySerialized)
+            throw new Error('D1 pruning requires externally serialized partition writes');
+        const epochGuard = 'EXISTS (SELECT 1 FROM sync_partition_registry WHERE partition=? AND log_epoch=?)';
+        const horizon = '(SELECT horizon_seq FROM sync_partitions WHERE partition=?)';
+        const results = await this.#db.batch([
             this.#db
-                .prepare('DELETE FROM sync_commits WHERE partition=? AND commit_seq<=?')
-                .bind(partition, seq),
+                .prepare(`SELECT log_epoch, coalesce(${horizon},0) AS previous_horizon_seq FROM sync_partition_registry WHERE partition=?`)
+                .bind(partition, partition),
             this.#db
-                .prepare('DELETE FROM sync_changes WHERE partition=? AND commit_seq<=?')
-                .bind(partition, seq),
+                .prepare(`INSERT INTO sync_partitions(partition,horizon_seq) SELECT ?,? WHERE ${epochGuard}
+        ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)`)
+                .bind(partition, query.throughSeq, partition, query.logEpoch),
             this.#db
-                .prepare('DELETE FROM sync_change_scopes WHERE partition=? AND commit_seq<=?')
-                .bind(partition, seq),
+                .prepare(`SELECT horizon_seq, (SELECT count(*) FROM sync_commits WHERE partition=? AND commit_seq<=${horizon}) AS removed_commits FROM sync_partitions WHERE partition=?`)
+                .bind(partition, partition, partition),
+            ...['sync_commits', 'sync_changes', 'sync_change_scopes'].map((table) => this.#db
+                .prepare(`DELETE FROM ${table} WHERE partition=? AND commit_seq<=${horizon} AND ${epochGuard}`)
+                .bind(partition, partition, partition, query.logEpoch)),
         ]);
-        return before?.n ?? 0;
+        const [before, after] = [results[0], results[2]].map((result) => {
+            if (typeof result !== 'object' ||
+                result === null ||
+                !('results' in result) ||
+                !Array.isArray(result.results)) {
+                throw new Error('D1 pruning returned an invalid batch result');
+            }
+            const row = result.results[0];
+            return typeof row === 'object' && row !== null
+                ? row
+                : undefined;
+        });
+        if (before?.log_epoch !== query.logEpoch)
+            throw new StorageQueryError('sync.storage.prune_epoch_mismatch');
+        if (typeof before.previous_horizon_seq !== 'number' ||
+            typeof after?.horizon_seq !== 'number' ||
+            typeof after.removed_commits !== 'number') {
+            throw new Error('D1 pruning returned invalid horizon metadata');
+        }
+        return {
+            previousHorizonSeq: before.previous_horizon_seq,
+            horizonSeq: after.horizon_seq,
+            removedCommits: after.removed_commits,
+        };
     }
     async getCommitSeqBefore(partition, createdBeforeMs) {
         const row = await this.#db
@@ -1000,6 +1037,13 @@ export class D1ServerStorage {
             .bind(partition, record.clientId, record.actorId, record.wireVersion, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs)
             .run();
     }
+    async getActiveClientCursorFloor(partition, cutoffMs) {
+        const row = await this.#db
+            .prepare('SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=?')
+            .bind(partition, cutoffMs)
+            .first();
+        return row.cursor;
+    }
     async listClientCursors(partition) {
         const { results } = await this.#db
             .prepare('SELECT client_id, cursor, updated_at_ms FROM sync_clients WHERE partition=?')

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,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';
@@ -107,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');
 }
@@ -381,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;
     }
@@ -661,6 +666,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 +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);
@@ -745,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]);
@@ -1069,6 +1094,10 @@ export class PostgresServerStorage {
             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) => ({

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;