@syncular/server 0.15.48 → 0.16.1

package/src/authoritative-query.ts

@@ -14,28 +14,16 @@ export interface BoundAuthoritativeQuery {
 
 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',
-);
+/** 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;
+  }[];
+}
 
 function protectedSqlEnd(sql: string, index: number): number | undefined {
   const char = sql[index];
@@ -64,66 +52,57 @@ function protectedSqlEnd(sql: string, index: number): number | undefined {
   return undefined;
 }
 
-function maskedSql(sql: string): string {
-  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;
-  }
-  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: string,
-  params: readonly AuthoritativeQueryValue[],
+/** Validate trusted generated metadata before registration or storage execution. */
+export function validateAuthoritativeRelationPlan(
+  plan: AuthoritativeRelationPlan,
   declaredTables: readonly string[],
-  tables: ReadonlyMap<string, CompiledTable>,
-): PreparedAuthoritativeQuery {
-  if (maskedSql(sql).includes(';'))
-    throw new Error('registered query must be one SELECT');
+): void {
+  if (
+    plan === undefined ||
+    typeof plan.sql !== 'string' ||
+    !Array.isArray(plan.relations)
+  ) {
+    throw new Error(
+      'registered query requires generated relation plans; regenerate queries',
+    );
+  }
+  const sql = plan.sql;
   const declared = new Set(declaredTables);
-  const masked = maskedSql(sql);
-  const replacements: Array<{
-    readonly start: number;
-    readonly end: number;
-    readonly text: string;
-  }> = [];
   const found = new Set<string>();
-  for (const match of masked.matchAll(TABLE_REF_RE)) {
-    const rawTable = match[3] as string;
-    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] as string).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 ||
@@ -131,42 +110,58 @@ export function prepareAuthoritativeQuery(
   ) {
     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: AuthoritativeRelationPlan,
+  params: readonly AuthoritativeQueryValue[],
+  declaredTables: readonly string[],
+  tables: ReadonlyMap<string, CompiledTable>,
+): PreparedAuthoritativeQuery {
+  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: (AuthoritativeQueryValue | typeof PARTITION_BIND)[] = [];
   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] as string;
+    const char = sql[index] as string;
     if (char !== '?') {
       rendered += char;
       continue;
     }
     let end = index + 1;
-    while (end < rewritten.length && /[0-9]/.test(rewritten[end] as string)) {
+    while (end < sql.length && /[0-9]/.test(sql[end] as string)) {
       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

package/src/d1-storage.ts

@@ -1,3 +1,6 @@
+import { validateCommitPruneQuery } from './prune';
+import { StorageQueryError } from './storage-errors';
+import type { CommitPruneQuery, CommitPruneResult } from './storage';
 /**
  * Cloudflare D1 server storage for Workers deployments.
  *
@@ -1027,7 +1030,7 @@ export class D1ServerStorage implements ServerStorage {
     }
     const prepared = bindAuthoritativePartition(
       prepareAuthoritativeQuery(
-        query.sql,
+        query.plan,
         query.params,
         query.tables,
         this.#tables,
@@ -1071,6 +1074,16 @@ export class D1ServerStorage implements ServerStorage {
     };
   }
 
+  async getPartitionLogEpoch(partition: string): Promise<string | undefined> {
+    const row = await this.#db
+      .prepare(
+        'SELECT log_epoch FROM sync_partition_registry WHERE partition=?',
+      )
+      .bind(partition)
+      .first<{ log_epoch: string }>();
+    return row?.log_epoch;
+  }
+
   async getHorizonSeq(partition: string): Promise<number> {
     const row = await this.#db
       .prepare('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
@@ -1082,33 +1095,76 @@ export class D1ServerStorage implements ServerStorage {
   async setHorizonSeq(partition: string, seq: number): Promise<void> {
     await this.#db
       .prepare(
-        'INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?) ON CONFLICT(partition) DO UPDATE SET horizon_seq=excluded.horizon_seq',
+        '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: string, seq: number): Promise<number> {
-    const before = await this.#db
-      .prepare(
-        'SELECT count(*) AS n FROM sync_commits WHERE partition=? AND commit_seq<=?',
-      )
-      .bind(partition, seq)
-      .first<{ n: number }>();
-    await this.#db.batch([
+  async pruneCommitsThrough(
+    partition: string,
+    query: CommitPruneQuery,
+  ): Promise<CommitPruneResult> {
+    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<=?',
+          `SELECT horizon_seq, (SELECT count(*) FROM sync_commits WHERE partition=? AND commit_seq<=${horizon}) AS removed_commits FROM sync_partitions WHERE partition=?`,
         )
-        .bind(partition, seq),
+        .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: unknown = result.results[0];
+      return typeof row === 'object' && row !== null
+        ? (row as Readonly<Record<string, unknown>>)
+        : 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(
@@ -1530,6 +1586,19 @@ export class D1ServerStorage implements ServerStorage {
       .run();
   }
 
+  async getActiveClientCursorFloor(
+    partition: string,
+    cutoffMs: number,
+  ): Promise<number | null> {
+    const row = await this.#db
+      .prepare(
+        'SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=?',
+      )
+      .bind(partition, cutoffMs)
+      .first<{ cursor: number | null }>();
+    return row!.cursor;
+  }
+
   async listClientCursors(partition: string): Promise<ClientCursorInfo[]> {
     const { results } = await this.#db
       .prepare(

package/src/operations.ts

@@ -1,3 +1,7 @@
+import {
+  type AuthoritativeRelationPlan,
+  validateAuthoritativeRelationPlan,
+} from './authoritative-query';
 import {
   decodeRow,
   decodeRemoteOperationRequest,
@@ -42,6 +46,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:
@@ -280,6 +285,9 @@ export function registerRemoteQuery<Params>(
   options: RemoteQueryOptions<Params>,
 ): RegisteredRemoteQuery {
   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) ||
@@ -288,9 +296,12 @@ export function registerRemoteQuery<Params>(
       descriptor.resultColumns.length
   ) {
     throw new Error(
-      'remote query requires a non-empty id and unique tables and result columns',
+      '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 ||
@@ -394,12 +405,29 @@ export function registerRemoteQuery<Params>(
           '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/src/postgres-storage.ts

@@ -1,3 +1,6 @@
+import { validateCommitPruneQuery } from './prune';
+import { StorageQueryError } from './storage-errors';
+import type { CommitPruneQuery, CommitPruneResult } from './storage';
 /**
  * Postgres server storage: the production database path.
  *
@@ -223,6 +226,21 @@ interface SerializedResult {
   details?: import('@syncular/core').RejectionDetails;
 }
 
+async function lockPartitionOn(
+  client: PgQueryable,
+  partition: string,
+): Promise<void> {
+  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: Uint8Array): string {
   return Buffer.from(bytes).toString('base64');
 }
@@ -649,15 +667,7 @@ class PostgresTransaction implements StorageTransaction {
 
   async lockPartitionForPush(): Promise<void> {
     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;
   }
@@ -1047,6 +1057,7 @@ export class PostgresServerStorage implements ServerStorage {
   ): Promise<PartitionRegistryEntry> {
     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
@@ -1148,7 +1159,7 @@ export class PostgresServerStorage implements ServerStorage {
     }
     const prepared = bindAuthoritativePartition(
       prepareAuthoritativeQuery(
-        query.sql,
+        query.plan,
         query.params,
         query.tables,
         this.#tables,
@@ -1177,6 +1188,14 @@ export class PostgresServerStorage implements ServerStorage {
     });
   }
 
+  async getPartitionLogEpoch(partition: string): Promise<string | undefined> {
+    const { rows } = await this.#exec.query<{ log_epoch: string }>(
+      'SELECT log_epoch FROM sync_partition_registry WHERE partition=$1',
+      [partition],
+    );
+    return rows[0]?.log_epoch;
+  }
+
   async getHorizonSeq(partition: string): Promise<number> {
     const { rows } = await this.#exec.query<{ horizon_seq: unknown }>(
       'SELECT horizon_seq FROM sync_partitions WHERE partition=$1',
@@ -1188,25 +1207,52 @@ export class PostgresServerStorage implements ServerStorage {
   async setHorizonSeq(partition: string, seq: number): Promise<void> {
     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`,
+       ON CONFLICT (partition) DO UPDATE SET horizon_seq=GREATEST(sync_partitions.horizon_seq,EXCLUDED.horizon_seq)`,
       [partition, seq],
     );
   }
 
-  async pruneCommitsThrough(partition: string, seq: number): Promise<number> {
-    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: string,
+    query: CommitPruneQuery,
+  ): Promise<CommitPruneResult> {
+    validateCommitPruneQuery(query);
+    return this.#exec.transaction(async (client) => {
+      await lockPartitionOn(client, partition);
+      const epoch = await client.query<{ log_epoch: string }>(
+        '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<{ horizon_seq: unknown }>(
+        '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(
@@ -1630,6 +1676,17 @@ export class PostgresServerStorage implements ServerStorage {
     );
   }
 
+  async getActiveClientCursorFloor(
+    partition: string,
+    cutoffMs: number,
+  ): Promise<number | null> {
+    const { rows } = await this.#exec.query<{ cursor: unknown }>(
+      '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: string): Promise<ClientCursorInfo[]> {
     const { rows } = await this.#exec.query<{
       client_id: string;

package/src/prune.ts

@@ -7,7 +7,20 @@
  * least the newest `minRetainedCommits` commits are always retained.
  */
 import { emitEvent, type SyncularServerEvents } from './events';
-import type { ServerStorage } from './storage';
+import type { CommitPruneQuery, ServerStorage } from './storage';
+import { StorageQueryError } from './storage-errors';
+
+/** Shared validation for the built-in atomic pruning adapters. */
+export function validateCommitPruneQuery(query: CommitPruneQuery): void {
+  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 interface RetentionPolicy {
   /** Active window for laggard cursors (default 14 days). */
@@ -37,28 +50,29 @@ export interface PruneOptions {
 export async function pruneCommitLog(options: PruneOptions): Promise<number> {
   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;
+    (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, {