@syncular/server 0.15.48 → 0.17.0

package/dist/relational-rows.js

@@ -177,7 +177,7 @@ export function physicalIndexName(declaredName) {
 }
 /**
  * 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.
@@ -188,7 +188,7 @@ export function createIndexDdl(table) {
         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})`;
@@ -401,6 +401,21 @@ export function deleteRowSql(table, dialect) {
     const p = dialect === 'sqlite' ? ['?', '?'] : ['$1', '$2'];
     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) {
+    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/dist/sqlite-bun.js

@@ -27,10 +27,10 @@ export class SqliteLeaseStore extends SharedSqliteLeaseStore {
         super(database(value), options);
     }
 }
-export const buildSqliteImage = (input) => {
+export const buildSqliteImage = async (input) => {
     const db = new BunSqliteDatabase();
     try {
-        writeSqliteImage(db, input);
+        await writeSqliteImage(db, input);
         return db.serialize();
     }
     finally {

package/dist/sqlite-image.d.ts

@@ -10,7 +10,7 @@ export interface SqliteImageInput {
     readonly schemaVersion: number;
     readonly asOfCommitSeq: number;
     readonly scopeDigest: string;
-    readonly rows: readonly StoredRow[];
+    readonly rowBatches: AsyncIterable<readonly StoredRow[]> | Iterable<readonly StoredRow[]>;
 }
 /**
  * The §5.3 image-builder capability, injected through
@@ -20,6 +20,6 @@ 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 declare function writeSqliteImage(db: SqliteDatabase, input: SqliteImageInput): void;
+export declare function writeSqliteImage(db: SqliteDatabase, input: SqliteImageInput): Promise<void>;

package/dist/sqlite-image.js

@@ -45,8 +45,8 @@ function toSql(value) {
     return value;
 }
 /** Populate a §5.3 image database for a whole-table snapshot. */
-export function writeSqliteImage(db, input) {
-    const { table, rows } = input;
+export async function writeSqliteImage(db, input) {
+    const { table, rowBatches } = input;
     const primaryKey = table.columns[table.primaryKeyIndex]?.name;
     const columnDefs = table.columns.map((column) => {
         const notNull = column.nullable ? '' : ' NOT NULL';
@@ -59,7 +59,6 @@ export function writeSqliteImage(db, input) {
       format INTEGER NOT NULL, "table" TEXT NOT NULL,
       "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),
@@ -68,10 +67,15 @@ export function writeSqliteImage(db, input) {
      VALUES (${names.map(() => '?').join(', ')})`);
     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) {

package/dist/sqlite-node.js

@@ -30,13 +30,13 @@ export class SqliteLeaseStore extends SharedSqliteLeaseStore {
         super(database(value), options);
     }
 }
-export const buildSqliteImage = (input) => {
+export const buildSqliteImage = 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/dist/sqlite-storage.d.ts

@@ -1,3 +1,4 @@
+import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import { type SqliteDatabase } from './sqlite-driver.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';
@@ -16,9 +17,10 @@ export declare class SqliteServerStorage implements ServerStorage {
     writeRow(partition: string, table: string, row: StoredRow): void;
     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>;
@@ -35,6 +37,9 @@ export declare class SqliteServerStorage 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/sqlite-storage.js

@@ -1,3 +1,5 @@
+import { validateCommitPruneQuery } from './prune.js';
+import { StorageQueryError } from './storage-errors.js';
 /**
  * SQLite server storage over the shared synchronous driver.
  *
@@ -8,7 +10,7 @@
  */
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { commitWindowPageSql, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { commitWindowPageSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { collectCommitWindowPage, deserializePushResult, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
 import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
@@ -106,8 +108,9 @@ class SqliteTransaction {
     async deleteRow(table, rowId) {
         this.#assertOpen();
         const db = this.#storage.db;
-        db.query(deleteRowSql(this.#storage.table(table), 'sqlite')).run(this.#partition, rowId);
-        db.query('DELETE FROM sync_row_scopes WHERE partition=? AND tbl=? AND row_id=?').run(this.#partition, table, rowId);
+        const compiled = this.#storage.table(table);
+        db.query(deleteSqliteRowScopesSql(compiled)).run(this.#partition, table, rowId, this.#partition, 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=?').run(this.#partition, table, rowId);
     }
@@ -199,7 +202,7 @@ export class SqliteServerStorage {
     /** Set by `ensureSchema`: app-table lookup for the relational row store. */
     #tables;
     #schemaVersion;
-    async #serializeReactionWrite(operation) {
+    async #serializeWrite(operation) {
         const previous = this.#transactionTail;
         let release;
         this.#transactionTail = new Promise((resolve) => {
@@ -275,6 +278,9 @@ export class SqliteServerStorage {
                     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(schema, existing, 'sqlite', existingIndexes)) {
@@ -327,7 +333,7 @@ export class SqliteServerStorage {
     async rotatePartitionLogEpoch(partition, logEpoch, authenticatedAtMs) {
         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
@@ -421,12 +427,12 @@ export class SqliteServerStorage {
     /** Internal: write a row + refresh its scope-index entries. */
     writeRow(partition, table, row) {
         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(...upsertValues(compiled, partition, row, 'sqlite'));
-        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('INSERT OR IGNORE INTO sync_row_scopes(partition, tbl, var, value, row_id) VALUES (?,?,?,?,?)')
@@ -443,7 +449,7 @@ export class SqliteServerStorage {
         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 previous = this.#transactionTail;
         let release;
         this.#transactionTail = new Promise((resolve) => {
@@ -473,6 +479,11 @@ export class SqliteServerStorage {
             release();
         }
     }
+    async getPartitionLogEpoch(partition) {
+        return this.db
+            .query('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
+            .get(partition)?.log_epoch;
+    }
     async getHorizonSeq(partition) {
         const row = this.db
             .query('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
@@ -480,24 +491,52 @@ export class SqliteServerStorage {
         return row?.horizon_seq ?? 0;
     }
     async setHorizonSeq(partition, seq) {
-        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, seq) {
-        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, query) {
+        validateCommitPruneQuery(query);
+        return this.#serializeWrite(() => {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                const epoch = this.db
+                    .query('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('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(partition, createdBeforeMs) {
         const row = this.db
@@ -527,7 +566,7 @@ export class SqliteServerStorage {
     async claimReactions(partition, query) {
         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(`UPDATE sync_reactions
@@ -553,7 +592,7 @@ export class SqliteServerStorage {
         });
     }
     async completeReaction(partition, idempotencyKey, leaseOwner, completedAtMs) {
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const result = this.db
                 .query(`UPDATE sync_reactions
             SET status='completed', completed_at_ms=?,
@@ -565,7 +604,7 @@ export class SqliteServerStorage {
         });
     }
     async extendReactionLease(partition, idempotencyKey, leaseOwner, leaseExpiresAtMs) {
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const result = this.db
                 .query(`UPDATE sync_reactions SET lease_expires_at_ms=?
           WHERE partition=? AND idempotency_key=?
@@ -576,7 +615,7 @@ export class SqliteServerStorage {
     }
     async failReaction(partition, idempotencyKey, update) {
         const retry = update.retryAtMs !== undefined;
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const result = this.db
                 .query(`UPDATE sync_reactions
             SET status=?, available_at_ms=?, last_failure=?,
@@ -588,7 +627,7 @@ export class SqliteServerStorage {
         });
     }
     async retryReaction(partition, idempotencyKey, nowMs) {
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const result = this.db
                 .query(`UPDATE sync_reactions
             SET status='pending', attempts=0, available_at_ms=?,
@@ -626,7 +665,7 @@ export class SqliteServerStorage {
     async pruneReactions(partition, query) {
         if (query.limit <= 0)
             return { completed: 0, deadLetter: 0 };
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const records = this.db
                 .query(`DELETE FROM sync_reactions
             WHERE partition=? AND idempotency_key IN (
@@ -751,6 +790,28 @@ export class SqliteServerStorage {
             .query('INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?,?)')
             .run(partition, record.clientId, record.actorId, record.wireVersion, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs);
     }
+    async advanceClientCursor(partition, clientId, actorId, logEpoch, cursor, updatedAtMs) {
+        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, clientId, cursor, updatedAtMs) {
+        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, cutoffMs) {
+        const row = this.db
+            .query('SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=?')
+            .get(partition, cutoffMs);
+        return row.cursor;
+    }
     async listClientCursors(partition) {
         const records = this.db
             .query('SELECT client_id, cursor, updated_at_ms FROM sync_clients WHERE partition=?')

package/dist/storage-errors.d.ts

@@ -9,7 +9,7 @@ export declare class StorageConstraintError extends Error {
     constructor(cause: unknown, opIndex?: number);
 }
 /** Stable, privacy-safe failures for trusted server storage queries. */
-export type StorageQueryErrorCode = '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';
+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.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor';
 /**
  * Host-only query error. Messages never include identifiers, values, SQL,
  * paths, or row data; callers branch on `code`, never message text.

package/dist/storage-errors.js

@@ -12,6 +12,13 @@ export class StorageConstraintError extends Error {
     }
 }
 const STORAGE_QUERY_MESSAGES = {
+    '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': 'trusted row lookup requires a declared relational index',
     'sync.storage.index_not_materialized': 'trusted row lookup requires a materialized relational table',

package/dist/storage.d.ts

@@ -1,3 +1,4 @@
+import type { AuthoritativeRelationPlan } from './authoritative-query.js';
 /**
  * Storage interface (defined by the SPEC's needs, implementation-agnostic).
  *
@@ -18,6 +19,15 @@
  */
 import type { PushOperationResult, RowValue, ScopeMap } from '@syncular/core';
 import type { CompiledSchema } from './schema.js';
+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;
@@ -244,7 +254,7 @@ export interface ScopeActivityQuery {
 export type AuthoritativeQueryValue = string | number | bigint | boolean | Uint8Array | null;
 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[];
@@ -355,15 +365,18 @@ export interface ServerStorage {
     rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
     /** 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, createdBeforeMs: number): Promise<number>;
     getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
@@ -412,7 +425,18 @@ export interface ServerStorage {
     scanRowsByIndex?(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
     getClientRecord(partition: string, 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[]>;
     /**
      * Blob reference index reads (§5.9.4) — ADDITIVE, optional (mirrors the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.15.48",
+  "version": "0.17.0",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.15.48"
+    "@syncular/core": "0.17.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/admin.ts

@@ -396,12 +396,10 @@ 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,