@syncular/server 0.15.48 → 0.17.0

package/src/realtime.ts

@@ -307,6 +307,10 @@ export class RealtimeSession {
     const cursor = (parsed as { cursor?: unknown }).cursor;
     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.
     void this.#persistCursor();
@@ -626,16 +630,14 @@ export class RealtimeSession {
 
   async #persistCursor(): Promise<void> {
     try {
-      const record = await this.#storage.getClientRecord(
+      await this.#storage.advanceClientCursor(
         this.partition,
         this.clientId,
+        this.actorId,
+        this.logEpoch,
+        this.cursor,
+        this.#clock(),
       );
-      if (record === undefined) return;
-      await this.#storage.putClientRecord(this.partition, {
-        ...record,
-        cursor: Math.max(record.cursor, this.cursor),
-        updatedAtMs: this.#clock(),
-      });
     } catch {
       // Cursor persistence is best-effort; the next pull repairs it.
     }
@@ -688,8 +690,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: StoredCommit): void {
+    const contiguous = commit.commitSeq === this.lastKnownSeq + 1;
     this.lastKnownSeq = Math.max(this.lastKnownSeq, commit.commitSeq);
     const sections: Array<{
       registration: Registration;
@@ -716,6 +719,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) {
       // §8.7 interleaving: no 0x00 messages while a response stream is
@@ -771,7 +782,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/src/relational-rows.ts

@@ -205,7 +205,7 @@ export 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.
@@ -215,7 +215,7 @@ export function createIndexDdl(table: CompiledTable): string[] {
   if (!table.materialize) return [];
   return table.indexes.map((index) => {
     const unique = index.unique ? 'UNIQUE ' : '';
-    const columns = index.columns
+    const columns = [SYNC_PARTITION_COLUMN, ...index.columns]
       .map((column) => quoteIdent(column))
       .join(', ');
     return `CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(physicalIndexName(index.name))} ON ${quoteIdent(table.name)} (${columns})`;
@@ -477,6 +477,22 @@ export function deleteRowSql(
   return `DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${p[0]} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${p[1]}`;
 }
 
+/**
+ * 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 function deleteSqliteRowScopesSql(table: CompiledTable): string {
+  return `DELETE FROM sync_row_scopes
+    WHERE partition=? AND tbl=? AND row_id=?
+      AND (var, value) IN (
+        SELECT key, value FROM json_each((
+          SELECT ${quoteIdent(SYNC_SCOPES_COLUMN)} FROM ${quoteIdent(table.name)}
+          WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=? AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=?
+        ))
+      )`;
+}
+
 /**
  * The schema-version marker table gates DDL work. `ensureSchema` compares the
  * stored version and skips

package/src/sqlite-bun.ts

@@ -40,10 +40,10 @@ export class SqliteLeaseStore extends SharedSqliteLeaseStore {
   }
 }
 
-export const buildSqliteImage: SqliteImageBuilder = (input) => {
+export const buildSqliteImage: SqliteImageBuilder = async (input) => {
   const db = new BunSqliteDatabase();
   try {
-    writeSqliteImage(db, input);
+    await writeSqliteImage(db, input);
     return db.serialize();
   } finally {
     db.close();

package/src/sqlite-image.ts

@@ -57,7 +57,9 @@ export interface SqliteImageInput {
   readonly schemaVersion: number;
   readonly asOfCommitSeq: number;
   readonly scopeDigest: string;
-  readonly rows: readonly StoredRow[];
+  readonly rowBatches:
+    | AsyncIterable<readonly StoredRow[]>
+    | Iterable<readonly StoredRow[]>;
 }
 
 /**
@@ -68,14 +70,16 @@ export interface SqliteImageInput {
  * on the pull path. A Bun or Node host passes `buildSqliteImage`; a Workers
  * host omits it and serves the rows lane.
  */
-export type SqliteImageBuilder = (input: SqliteImageInput) => Uint8Array;
+export type SqliteImageBuilder = (
+  input: SqliteImageInput,
+) => Promise<Uint8Array>;
 
 /** Populate a §5.3 image database for a whole-table snapshot. */
-export function writeSqliteImage(
+export async function writeSqliteImage(
   db: SqliteDatabase,
   input: SqliteImageInput,
-): void {
-  const { table, rows } = input;
+): Promise<void> {
+  const { table, rowBatches } = input;
   const primaryKey = table.columns[table.primaryKeyIndex]?.name;
   const columnDefs = table.columns.map((column) => {
     const notNull = column.nullable ? '' : ' NOT NULL';
@@ -90,13 +94,6 @@ export function writeSqliteImage(
       "schemaVersion" INTEGER NOT NULL, "asOfCommitSeq" INTEGER NOT NULL,
       "scopeDigest" TEXT NOT NULL, "rowCount" INTEGER NOT NULL)`,
   );
-  db.query(`INSERT INTO ${IMAGE_METADATA_TABLE} VALUES (1, ?, ?, ?, ?, ?)`).run(
-    table.name,
-    input.schemaVersion,
-    input.asOfCommitSeq,
-    input.scopeDigest,
-    rows.length,
-  );
   const names = [
     ...table.columns.map((column) => quoteIdent(column.name)),
     quoteIdent(IMAGE_VERSION_COLUMN),
@@ -107,10 +104,24 @@ export function writeSqliteImage(
   );
   db.exec('BEGIN');
   try {
-    for (const row of rows) {
-      const values = decodeRow(table.columns, row.payload);
-      insert.run(...values.map(toSql), row.serverVersion);
+    let rowCount = 0;
+    for await (const rows of rowBatches) {
+      for (const row of rows) {
+        const values = decodeRow(table.columns, row.payload);
+        insert.run(...values.map(toSql), row.serverVersion);
+      }
+      rowCount += rows.length;
     }
+    db.query(
+      `INSERT INTO ${IMAGE_METADATA_TABLE} VALUES (1, ?, ?, ?, ?, ?)`,
+    ).run(
+      table.name,
+      input.schemaVersion,
+      input.asOfCommitSeq,
+      input.scopeDigest,
+      rowCount,
+    );
+
     db.exec('COMMIT');
   } catch (error) {
     db.exec('ROLLBACK');

package/src/sqlite-node.ts

@@ -43,13 +43,13 @@ export class SqliteLeaseStore extends SharedSqliteLeaseStore {
   }
 }
 
-export const buildSqliteImage: SqliteImageBuilder = (input) => {
+export const buildSqliteImage: SqliteImageBuilder = async (input) => {
   const directory = mkdtempSync(join(tmpdir(), 'syncular-server-image-'));
   const path = join(directory, 'segment.db');
   const db = new NodeSqliteDatabase(path);
   try {
     try {
-      writeSqliteImage(db, input);
+      await writeSqliteImage(db, input);
     } finally {
       db.close();
     }

package/src/sqlite-storage.ts

@@ -1,3 +1,6 @@
+import { validateCommitPruneQuery } from './prune';
+import { StorageQueryError } from './storage-errors';
+import type { CommitPruneQuery, CommitPruneResult } from './storage';
 /**
  * SQLite server storage over the shared synchronous driver.
  *
@@ -14,6 +17,7 @@ import { syncError } from './errors';
 import {
   commitWindowPageSql,
   deleteRowSql,
+  deleteSqliteRowScopesSql,
   dropTableDdl,
   indexRowPageStatement,
   layoutsOf,
@@ -225,13 +229,15 @@ class SqliteTransaction implements StorageTransaction {
   async deleteRow(table: string, rowId: string): Promise<void> {
     this.#assertOpen();
     const db = this.#storage.db;
-    db.query(deleteRowSql(this.#storage.table(table), 'sqlite')).run(
+    const compiled = this.#storage.table(table);
+    db.query(deleteSqliteRowScopesSql(compiled)).run(
+      this.#partition,
+      table,
+      rowId,
       this.#partition,
       rowId,
     );
-    db.query(
-      'DELETE FROM sync_row_scopes WHERE partition=? AND tbl=? AND row_id=?',
-    ).run(this.#partition, table, rowId);
+    db.query(deleteRowSql(compiled, 'sqlite')).run(this.#partition, rowId);
     // §5.9.4: a deleted row references no blobs.
     db.query(
       'DELETE FROM sync_blob_refs WHERE partition=? AND tbl=? AND row_id=?',
@@ -390,7 +396,7 @@ export class SqliteServerStorage implements ServerStorage {
   #tables: ReadonlyMap<string, CompiledTable> | undefined;
   #schemaVersion: number | undefined;
 
-  async #serializeReactionWrite<T>(operation: () => T): Promise<T> {
+  async #serializeWrite<T>(operation: () => T): Promise<T> {
     const previous = this.#transactionTail;
     let release!: () => void;
     this.#transactionTail = new Promise<void>((resolve) => {
@@ -482,6 +488,9 @@ export class SqliteServerStorage implements ServerStorage {
           this.db
             .query('DELETE FROM sync_row_scopes WHERE tbl=?')
             .run(tableName);
+          this.db
+            .query('DELETE FROM sync_blob_refs WHERE tbl=?')
+            .run(tableName);
           this.db.exec(dropTableDdl(tableName));
         }
         for (const statement of schemaDdl(
@@ -559,7 +568,7 @@ export class SqliteServerStorage implements ServerStorage {
     authenticatedAtMs: number,
   ): Promise<PartitionRegistryEntry> {
     if (logEpoch.length === 0) throw new Error('log epoch must be non-empty');
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       this.db.exec('BEGIN IMMEDIATE');
       try {
         this.db
@@ -680,6 +689,9 @@ export class SqliteServerStorage implements ServerStorage {
   /** Internal: write a row + refresh its scope-index entries. */
   writeRow(partition: string, table: string, row: StoredRow): void {
     const compiled = this.table(table);
+    this.db
+      .query(deleteSqliteRowScopesSql(compiled))
+      .run(partition, table, row.rowId, partition, row.rowId);
     this.db
       .query(upsertSql(compiled, 'sqlite'))
       .run(
@@ -691,11 +703,6 @@ export class SqliteServerStorage implements ServerStorage {
           | null
         )[]),
       );
-    this.db
-      .query(
-        'DELETE FROM sync_row_scopes WHERE partition=? AND tbl=? AND row_id=?',
-      )
-      .run(partition, table, row.rowId);
     for (const [variable, value] of Object.entries(row.scopes)) {
       this.db
         .query(
@@ -725,7 +732,7 @@ export class SqliteServerStorage implements ServerStorage {
     }
     const prepared = bindAuthoritativePartition(
       prepareAuthoritativeQuery(
-        query.sql,
+        query.plan,
         query.params,
         query.tables,
         this.#tables,
@@ -763,6 +770,14 @@ export class SqliteServerStorage implements ServerStorage {
     }
   }
 
+  async getPartitionLogEpoch(partition: string): Promise<string | undefined> {
+    return this.db
+      .query<{ log_epoch: string }, [string]>(
+        'SELECT log_epoch FROM sync_partition_registry WHERE partition=?',
+      )
+      .get(partition)?.log_epoch;
+  }
+
   async getHorizonSeq(partition: string): Promise<number> {
     const row = this.db
       .query<{ horizon_seq: number }, [string]>(
@@ -773,27 +788,62 @@ export class SqliteServerStorage implements ServerStorage {
   }
 
   async setHorizonSeq(partition: string, seq: number): Promise<void> {
-    this.db
-      .query('INSERT OR IGNORE INTO sync_partitions(partition) VALUES (?)')
-      .run(partition);
-    this.db
-      .query('UPDATE sync_partitions SET horizon_seq=? WHERE partition=?')
-      .run(seq, partition);
+    await this.#serializeWrite(() => {
+      this.db
+        .query(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?)
+        ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)`)
+        .run(partition, seq);
+    });
   }
 
-  async pruneCommitsThrough(partition: string, seq: number): Promise<number> {
-    const removed = this.db
-      .query('DELETE FROM sync_commits WHERE partition=? AND commit_seq<=?')
-      .run(partition, seq);
-    this.db
-      .query('DELETE FROM sync_changes WHERE partition=? AND commit_seq<=?')
-      .run(partition, seq);
-    this.db
-      .query(
-        'DELETE FROM sync_change_scopes WHERE partition=? AND commit_seq<=?',
-      )
-      .run(partition, seq);
-    return Number(removed.changes);
+  async pruneCommitsThrough(
+    partition: string,
+    query: CommitPruneQuery,
+  ): Promise<CommitPruneResult> {
+    validateCommitPruneQuery(query);
+    return this.#serializeWrite(() => {
+      this.db.exec('BEGIN IMMEDIATE');
+      try {
+        const epoch = this.db
+          .query<{ log_epoch: string }, [string]>(
+            'SELECT log_epoch FROM sync_partition_registry WHERE partition=?',
+          )
+          .get(partition)?.log_epoch;
+        if (epoch !== query.logEpoch)
+          throw new StorageQueryError('sync.storage.prune_epoch_mismatch');
+        const previousHorizonSeq =
+          this.db
+            .query<{ horizon_seq: number }, [string]>(
+              'SELECT horizon_seq FROM sync_partitions WHERE partition=?',
+            )
+            .get(partition)?.horizon_seq ?? 0;
+        const horizonSeq = Math.max(previousHorizonSeq, query.throughSeq);
+        this.db
+          .query(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?)
+          ON CONFLICT(partition) DO UPDATE SET horizon_seq=excluded.horizon_seq`)
+          .run(partition, horizonSeq);
+        const removed = this.db
+          .query('DELETE FROM sync_commits WHERE partition=? AND commit_seq<=?')
+          .run(partition, horizonSeq);
+        this.db
+          .query('DELETE FROM sync_changes WHERE partition=? AND commit_seq<=?')
+          .run(partition, horizonSeq);
+        this.db
+          .query(
+            'DELETE FROM sync_change_scopes WHERE partition=? AND commit_seq<=?',
+          )
+          .run(partition, horizonSeq);
+        this.db.exec('COMMIT');
+        return {
+          previousHorizonSeq,
+          horizonSeq,
+          removedCommits: Number(removed.changes),
+        };
+      } catch (error) {
+        this.db.exec('ROLLBACK');
+        throw error;
+      }
+    });
   }
 
   async getCommitSeqBefore(
@@ -847,7 +897,7 @@ export class SqliteServerStorage implements ServerStorage {
     query: ReactionClaimQuery,
   ): Promise<StoredReaction[]> {
     if (query.types.length === 0 || query.limit <= 0) return [];
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const typeParams = query.types.map(() => '?').join(',');
       const records = this.db
         .query<SqliteReactionRecord, (string | number)[]>(
@@ -895,7 +945,7 @@ export class SqliteServerStorage implements ServerStorage {
     leaseOwner: string,
     completedAtMs: number,
   ): Promise<boolean> {
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const result = this.db
         .query(
           `UPDATE sync_reactions
@@ -915,7 +965,7 @@ export class SqliteServerStorage implements ServerStorage {
     leaseOwner: string,
     leaseExpiresAtMs: number,
   ): Promise<boolean> {
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const result = this.db
         .query(
           `UPDATE sync_reactions SET lease_expires_at_ms=?
@@ -933,7 +983,7 @@ export class SqliteServerStorage implements ServerStorage {
     update: ReactionFailureUpdate,
   ): Promise<boolean> {
     const retry = update.retryAtMs !== undefined;
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const result = this.db
         .query(
           `UPDATE sync_reactions
@@ -959,7 +1009,7 @@ export class SqliteServerStorage implements ServerStorage {
     idempotencyKey: string,
     nowMs: number,
   ): Promise<boolean> {
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const result = this.db
         .query(
           `UPDATE sync_reactions
@@ -1014,7 +1064,7 @@ export class SqliteServerStorage implements ServerStorage {
     query: ReactionPruneQuery,
   ): Promise<PrunedReactionCounts> {
     if (query.limit <= 0) return { completed: 0, deadLetter: 0 };
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const records = this.db
         .query<
           { status: 'completed' | 'dead-letter' },
@@ -1226,6 +1276,50 @@ export class SqliteServerStorage implements ServerStorage {
       );
   }
 
+  async advanceClientCursor(
+    partition: string,
+    clientId: string,
+    actorId: string,
+    logEpoch: string,
+    cursor: number,
+    updatedAtMs: number,
+  ): Promise<void> {
+    this.db
+      .query(`UPDATE sync_clients
+         SET cursor=MAX(cursor, ?), updated_at_ms=MAX(updated_at_ms, ?)
+         WHERE partition=? AND client_id=? AND actor_id=?
+           AND EXISTS (SELECT 1 FROM sync_partition_registry
+                       WHERE partition=sync_clients.partition AND log_epoch=?)`)
+      .run(cursor, updatedAtMs, partition, clientId, actorId, logEpoch);
+  }
+
+  async updateClientCursor(
+    partition: string,
+    clientId: string,
+    cursor: number,
+    updatedAtMs: number,
+  ): Promise<void> {
+    this.db
+      .query(
+        `UPDATE sync_clients
+         SET cursor=MAX(cursor, ?), updated_at_ms=MAX(updated_at_ms, ?)
+         WHERE partition=? AND client_id=?`,
+      )
+      .run(cursor, updatedAtMs, partition, clientId);
+  }
+
+  async getActiveClientCursorFloor(
+    partition: string,
+    cutoffMs: number,
+  ): Promise<number | null> {
+    const row = this.db
+      .query<{ cursor: number | null }, [string, number]>(
+        'SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=?',
+      )
+      .get(partition, cutoffMs);
+    return row!.cursor;
+  }
+
   async listClientCursors(partition: string): Promise<ClientCursorInfo[]> {
     const records = this.db
       .query<

package/src/storage-errors.ts

@@ -15,14 +15,35 @@ export class StorageConstraintError extends Error {
 
 /** Stable, privacy-safe failures for trusted server storage queries. */
 export type StorageQueryErrorCode =
+  | 'sync.storage.schema_migration_pending'
+  | 'sync.storage.schema_migration_conflict'
+  | 'sync.storage.schema_changed'
+  | 'sync.storage.invalid_migration_budget'
   | 'sync.storage.scan_requires_scope'
   | 'sync.storage.index_not_found'
   | 'sync.storage.index_not_materialized'
   | 'sync.storage.index_value_count_mismatch'
-  | 'sync.storage.invalid_limit';
+  | 'sync.storage.invalid_limit'
+  | 'sync.storage.prune_epoch_mismatch'
+  | 'sync.storage.partition_unregistered'
+  | 'sync.storage.invalid_prune_cursor';
 
 const STORAGE_QUERY_MESSAGES: Readonly<Record<StorageQueryErrorCode, string>> =
   {
+    'sync.storage.schema_migration_pending':
+      'schema migration requires another invocation',
+    'sync.storage.schema_migration_conflict':
+      'another schema migration target is already pending',
+    'sync.storage.schema_changed':
+      'storage schema is not ready for this operation',
+    'sync.storage.invalid_migration_budget':
+      'migration statement budget must be an integer from 10 through 1000',
+    'sync.storage.prune_epoch_mismatch':
+      'partition log epoch changed; recompute retention inputs',
+    'sync.storage.partition_unregistered':
+      'pruning requires a registered partition',
+    'sync.storage.invalid_prune_cursor':
+      'pruning requires a non-negative safe integer cursor and a non-empty log epoch',
     'sync.storage.scan_requires_scope':
       'scope-indexed row scans require at least one scope variable',
     'sync.storage.index_not_found':

package/src/storage.ts

@@ -1,3 +1,4 @@
+import type { AuthoritativeRelationPlan } from './authoritative-query';
 /**
  * Storage interface (defined by the SPEC's needs, implementation-agnostic).
  *
@@ -19,6 +20,17 @@
 import type { PushOperationResult, RowValue, ScopeMap } from '@syncular/core';
 import type { CompiledSchema } from './schema';
 
+export interface CommitPruneQuery {
+  readonly logEpoch: string;
+  readonly throughSeq: number;
+}
+
+export interface CommitPruneResult {
+  readonly previousHorizonSeq: number;
+  readonly horizonSeq: number;
+  readonly removedCommits: number;
+}
+
 /** The current stored state of a synced row. */
 export interface StoredRow {
   readonly rowId: string;
@@ -281,7 +293,7 @@ export type AuthoritativeQueryValue =
 
 export interface AuthoritativeQueryRequest {
   /** Generated, positional SQLite-family SQL. It never comes from the request. */
-  readonly sql: string;
+  readonly plan: AuthoritativeRelationPlan;
   readonly params: readonly AuthoritativeQueryValue[];
   /** Generated dependency set, used to validate and partition every relation. */
   readonly tables: readonly string[];
@@ -422,16 +434,23 @@ export interface ServerStorage {
   /** Registry entries ordered by partition for maintenance loops. */
   listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
 
+  /** Read continuity without refreshing authenticated activity. */
+  getPartitionLogEpoch(partition: string): Promise<string | undefined>;
+
   begin(partition: string): Promise<StorageTransaction>;
 
   getMaxCommitSeq(partition: string): Promise<number>;
   getHorizonSeq(partition: string): Promise<number>;
+  /** Monotonic within the current epoch; use atomic pruning for maintenance. */
   setHorizonSeq(partition: string, seq: number): Promise<void>;
   /**
-   * Deletes commits with `commitSeq <= seq` (log, changes, scope index).
-   * Returns the number of commits removed (ops observability).
+   * Atomically verifies the log epoch, advances the horizon monotonically,
+   * and removes log/change/scope records through the effective horizon.
    */
-  pruneCommitsThrough(partition: string, seq: number): Promise<number>;
+  pruneCommitsThrough(
+    partition: string,
+    query: CommitPruneQuery,
+  ): Promise<CommitPruneResult>;
   /** Newest commitSeq created strictly before the timestamp; 0 if none. */
   getCommitSeqBefore(
     partition: string,
@@ -541,7 +560,33 @@ export interface ServerStorage {
     clientId: string,
   ): Promise<ClientRecord | undefined>;
   putClientRecord(partition: string, record: ClientRecord): Promise<void>;
-  /** Cursor records feeding the §4.6 retention watermark. */
+  /**
+   * Atomically advance an existing record's cursor and activity timestamp.
+   * Preserve registration fields; require matching actor and current log epoch.
+   * Missing records and mismatched identities are unchanged (§8.2).
+   */
+  advanceClientCursor(
+    partition: string,
+    clientId: string,
+    actorId: string,
+    logEpoch: string,
+    cursor: number,
+    updatedAtMs: number,
+  ): Promise<void>;
+  /** Advance an existing client's ACK cursor and timestamp atomically,
+   * preserving actor, wire version, and subscriptions. Missing records stay absent. */
+  updateClientCursor(
+    partition: string,
+    clientId: string,
+    cursor: number,
+    updatedAtMs: number,
+  ): Promise<void>;
+  /** Minimum cursor with updatedAtMs >= cutoff; null when none are active. */
+  getActiveClientCursorFloor(
+    partition: string,
+    cutoffMs: number,
+  ): Promise<number | null>;
+  /** Cursor records for client listings and administrative counts. */
   listClientCursors(partition: string): Promise<ClientCursorInfo[]>;
 
   /**