@syncular/server 0.15.48 → 0.16.1

package/dist/prune.js

@@ -7,6 +7,16 @@
  * least the newest `minRetainedCommits` commits are always retained.
  */
 import { emitEvent } from './events.js';
+import { StorageQueryError } from './storage-errors.js';
+/** Shared validation for the built-in atomic pruning adapters. */
+export function validateCommitPruneQuery(query) {
+    if (!Number.isSafeInteger(query.throughSeq) ||
+        query.throughSeq < 0 ||
+        typeof query.logEpoch !== 'string' ||
+        query.logEpoch.length === 0) {
+        throw new StorageQueryError('sync.storage.invalid_prune_cursor');
+    }
+}
 export const DEFAULT_RETENTION = {
     activeWindowMs: 14 * 24 * 60 * 60 * 1000,
     ageForceMs: 30 * 24 * 60 * 60 * 1000,
@@ -16,24 +26,18 @@ export const DEFAULT_RETENTION = {
 export async function pruneCommitLog(options) {
     const { storage, partition, nowMs } = options;
     const policy = { ...DEFAULT_RETENTION, ...options.retention };
+    const logEpoch = await storage.getPartitionLogEpoch(partition);
+    if (logEpoch === undefined)
+        throw new StorageQueryError('sync.storage.partition_unregistered');
     const maxSeq = await storage.getMaxCommitSeq(partition);
-    const cursors = await storage.listClientCursors(partition);
-    const activeCursors = cursors
-        .filter((c) => c.updatedAtMs >= nowMs - policy.activeWindowMs)
-        .map((c) => c.cursor);
-    const cursorFloor = activeCursors.length > 0
-        ? Math.min(...activeCursors)
-        : Number.MAX_SAFE_INTEGER;
+    const cursorFloor = (await storage.getActiveClientCursorFloor(partition, nowMs - policy.activeWindowMs)) ?? Number.MAX_SAFE_INTEGER;
     const forcedSeq = await storage.getCommitSeqBefore(partition, nowMs - policy.ageForceMs);
     const retainFloor = maxSeq - policy.minRetainedCommits;
     const target = Math.min(Math.max(cursorFloor, forcedSeq), retainFloor);
-    const current = await storage.getHorizonSeq(partition);
-    const horizon = Math.max(current, Math.max(0, target));
-    let removedCommits = 0;
-    if (horizon > current) {
-        await storage.setHorizonSeq(partition, horizon);
-        removedCommits = await storage.pruneCommitsThrough(partition, horizon);
-    }
+    const { previousHorizonSeq: current, horizonSeq: horizon, removedCommits, } = await storage.pruneCommitsThrough(partition, {
+        logEpoch,
+        throughSeq: Math.max(0, target),
+    });
     const events = options.events;
     if (events !== undefined) {
         emitEvent(events, {

package/dist/pull.js

@@ -6,6 +6,8 @@ import { decodeRow, encodeRowsSegment, } from '@syncular/core';
 import { clockOf, limitsOf } from './context.js';
 import { scopeDigest } from './scopes.js';
 import { issueSegmentUrl } from './signed-url.js';
+// One artifact build per owning storage pair and complete immutable identity.
+const imageBuilds = new WeakMap();
 /**
  * Resolve the §5.3 image builder: the host-injected one if present, else the
  * in-tree `buildSqliteImage` on a Bun runtime (dynamic import so `bun:sqlite`
@@ -177,33 +179,17 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
     const buildImage = await resolveImageBuilder(ctx);
     if (buildImage === undefined)
         return false;
-    // The probe rows are the snapshot's first page — keep them and scan on
-    // from the probe's cursor instead of re-reading the whole prefix (the
-    // scan is keyset-ordered by rowId, so the concatenation is exactly the
-    // rows a single full scan would return).
-    const rows = [...probe];
-    let afterRowId = probe[probe.length - 1]?.rowId ?? null;
-    for (;;) {
-        const scanned = await storage.scanRows(partition, {
-            table: plan.table.name,
-            scopeFilter: plan.effective,
-            afterRowId,
-            limit: 50_000,
-        });
-        rows.push(...scanned);
-        const last = scanned[scanned.length - 1];
-        if (scanned.length < 50_000 || last === undefined)
-            break;
-        afterRowId = last.rowId;
+    let stores = imageBuilds.get(storage);
+    if (stores === undefined) {
+        stores = new WeakMap();
+        imageBuilds.set(storage, stores);
     }
-    const bytes = buildImage({
-        table: plan.table,
-        schemaVersion: schema.version,
-        asOfCommitSeq: asOf,
-        scopeDigest: digest,
-        rows,
-    });
-    const record = await segments.put({
+    let builds = stores.get(segments);
+    if (builds === undefined) {
+        builds = new Map();
+        stores.set(segments, builds);
+    }
+    const identity = {
         partition,
         logEpoch,
         table: plan.table.name,
@@ -211,18 +197,63 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
         mediaType: 'sqlite',
         scopeDigest: digest,
         asOfCommitSeq: asOf,
-        rowCount: rows.length,
-        rowCursor: null,
-        nextRowCursor: null,
-    }, bytes, now);
+    };
+    const key = JSON.stringify(identity);
+    let building = builds.get(key);
+    let builtHere = false;
+    if (building === undefined) {
+        building = (async () => {
+            // Another request can finish while this one's eligibility probe awaits.
+            const cached = await segments.find(identity, clockOf(ctx)());
+            if (cached !== undefined)
+                return cached;
+            builtHere = true;
+            let rowCount = 0;
+            const bytes = await buildImage({
+                table: plan.table,
+                schemaVersion: schema.version,
+                asOfCommitSeq: asOf,
+                scopeDigest: digest,
+                rowBatches: (async function* () {
+                    rowCount += probe.length;
+                    yield probe;
+                    let afterRowId = probe[probe.length - 1].rowId;
+                    for (;;) {
+                        const rows = await storage.scanRows(partition, {
+                            table: plan.table.name,
+                            scopeFilter: plan.effective,
+                            afterRowId,
+                            limit: 5_000,
+                        });
+                        rowCount += rows.length;
+                        yield rows;
+                        const last = rows[rows.length - 1];
+                        if (rows.length < 5_000 || last === undefined)
+                            break;
+                        afterRowId = last.rowId;
+                    }
+                })(),
+            });
+            return segments.put({ ...identity, rowCount, rowCursor: null, nextRowCursor: null }, bytes, clockOf(ctx)());
+        })();
+        builds.set(key, building);
+    }
+    let record;
+    try {
+        record = await building;
+    }
+    finally {
+        if (builds.get(key) === building)
+            builds.delete(key);
+    }
     trace?.segments.push({
         mediaType: 'sqlite',
         delivery: 'ref',
-        origin: 'built',
+        origin: builtHere ? 'built' : 'reused',
         bytes: record.byteLength,
         rows: record.rowCount,
     });
-    yield segmentRefFrame(record, await signedUrlFields(ctx, limits, record.segmentId, digest, now));
+    yield segmentRefFrame(record, await signedUrlFields(ctx, limits, record.segmentId, digest, clockOf(ctx)()));
     return true;
 }
 async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCursor, trace, logEpoch) {

package/dist/push.js

@@ -98,7 +98,7 @@ async function runValidator(validators, table, op, rowId, values, storedValues,
         // §6.7: a non-ValidationRejection throw is still a rejection, mapped to
         // the generic server-side constraint code (§10.2) — the validator's
         // failure never crashes the request or leaks its message as a code.
-        return errorRecord(opIndex, 'sync.constraint_violation', `write validator for table ${JSON.stringify(table.name)} threw: ${error instanceof Error ? error.message : String(error)}`);
+        return errorRecord(opIndex, 'sync.constraint_violation', 'write validator failed');
     }
     return undefined;
 }
@@ -124,7 +124,7 @@ async function mergeCrdtColumns(table, values, storedValues, opIndex, mergers) {
             continue; // NULL clear or absent
         const merger = mergers?.[crdtType];
         if (merger === undefined) {
-            return errorRecord(opIndex, 'sync.crdt_merge_failed', `no CRDT merger registered for crdtType ${JSON.stringify(crdtType)} (§5.10.2)`);
+            return errorRecord(opIndex, 'sync.crdt_merge_failed', 'no CRDT merger registered');
         }
         const storedRaw = storedValues?.[index];
         const stored = storedRaw instanceof Uint8Array ? storedRaw : null;
@@ -132,8 +132,8 @@ async function mergeCrdtColumns(table, values, storedValues, opIndex, mergers) {
         try {
             merged = await merger(stored, incoming);
         }
-        catch (error) {
-            return errorRecord(opIndex, 'sync.crdt_merge_failed', `CRDT merger for ${JSON.stringify(crdtType)} threw: ${error instanceof Error ? error.message : String(error)}`);
+        catch {
+            return errorRecord(opIndex, 'sync.crdt_merge_failed', 'CRDT merger failed');
         }
         values[index] = merged;
         changed = true;
@@ -452,7 +452,7 @@ async function runCommitValidator(validator, tx, schema, clientId, clientCommitI
         if (error instanceof ValidationRejection) {
             return errorRecord(operations[0]?.opIndex ?? 0, error.code, error.message, false, error.details);
         }
-        return errorRecord(operations[0]?.opIndex ?? 0, 'sync.constraint_violation', `whole-commit validator threw: ${error instanceof Error ? error.message : String(error)}`);
+        return errorRecord(operations[0]?.opIndex ?? 0, 'sync.constraint_violation', 'whole-commit validator failed');
     }
     return undefined;
 }

package/dist/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,7 @@ 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>;
+    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.
  *
@@ -199,7 +201,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) => {
@@ -327,7 +329,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
@@ -443,7 +445,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 +475,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 +487,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 +562,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 +588,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 +600,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 +611,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 +623,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 +661,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 +786,12 @@ 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 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.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,9 @@ export class StorageConstraintError extends Error {
     }
 }
 const STORAGE_QUERY_MESSAGES = {
+    '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,9 @@ 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. */
+    /** 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.16.1",
   "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.16.1"
   },
   "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,