@syncular/client 0.15.47 → 0.15.48

package/README.md

@@ -14,6 +14,9 @@ server-authoritative commands, and live query watches through the remote
 operation transport. See [remote server operations](https://syncular.dev/guide-remote-operations/).
 Its schema and sync transport are optional for query-only or command-only
 processes.
+Ordinary commits use wire version 1 until the caller supplies an acquired
+partition `logEpoch`. Set `logEpoch` after a restore rotation requires epoch
+validation.
 
 ## Client-local FTS5 projections
 
@@ -69,6 +72,20 @@ SPEC §8.4); the supported page-level realtime supervisor owns reconnect and
 resume policy. The main thread gets `onSyncNeeded` / `onConflict` / `onSynced`
 events for rendering.
 
+A direct `SyncClient` used by a long-running service exposes
+`onSyncNeeded()` and `onSyncIntent()`. Install the shared single-flight loop
+instead of maintaining host timers:
+
+```ts
+const scheduler = installSyncScheduler(client, { onError: reportSyncError });
+// During shutdown:
+scheduler.stop();
+```
+
+Creation-time window helpers produce immutable UTC month scope values.
+`creationTimeBucket(createdAtMs, 'month')` returns `YYYY-MM`, and
+`last(3, 'month')` returns the current and preceding two buckets oldest first.
+
 OPFS is best effort until the browser grants origin persistence. The page owns
 that decision because `StorageManager.persist()` is a Window API and should be
 requested from a user action:

package/dist/bun-database.d.ts

@@ -5,6 +5,11 @@
  */
 import { Database } from 'bun:sqlite';
 import { type ClientDatabase, type SqlRow, type SqlValue } from './database.js';
+declare module 'bun:sqlite' {
+    interface Database {
+        clearQueryCache(): void;
+    }
+}
 export declare class BunClientDatabase implements ClientDatabase {
     #private;
     readonly db: Database;

package/dist/bun-database.js

@@ -23,6 +23,11 @@ export class BunClientDatabase {
     }
     exec(sql, params = []) {
         this.db.query(sql).run(...coerceParams(params));
+        // `Database.query()` caches prepared statements. Clear that cache after
+        // schema DDL so a reset does not reprepare every later row upsert.
+        if (/^\s*(?:CREATE|DROP|ALTER)\b/i.test(sql)) {
+            this.db.clearQueryCache();
+        }
     }
     query(sql, params = []) {
         return this.db.query(sql).all(...coerceParams(params));

package/dist/client.d.ts

@@ -285,6 +285,10 @@ export declare class SyncClient {
     onInvalidate(listener: InvalidationListener): () => void;
     /** Subscribe to exact revisioned observer transactions (SPEC §7.5). */
     onChange(listener: ClientChangeListener): () => void;
+    /** Subscribe to host wake signals raised by startup and realtime. */
+    onSyncNeeded(listener: (reason: 'startup' | 'hello' | WakeReason) => void): () => void;
+    /** Subscribe to exact core-owned scheduling instructions. */
+    onSyncIntent(listener: (intent: SyncIntent) => void): () => void;
     /** Subscribe to complete, privacy-safe diagnostic snapshots. */
     onDiagnostics(listener: ClientDiagnosticsListener): () => void;
     /**

package/dist/client.js

@@ -71,6 +71,7 @@ function emptySummary(pushed) {
         failed: [],
     };
 }
+const LOG_EPOCH_META_KEY = 'logEpoch';
 function isFinalPushResult(frame) {
     return (frame.status !== 'rejected' ||
         !frame.results.some((result) => result.status === 'error' &&
@@ -131,6 +132,8 @@ export class SyncClient {
     #invalidation = new InvalidationEmitter();
     /** §8.6: subscribable presence-change listeners (twin of onPresence). */
     #presenceListeners = new Set();
+    #syncNeededListeners = new Set();
+    #syncIntentListeners = new Set();
     #diagnostics = new ClientDiagnosticsEmitter();
     #diagnosticsDeferralDepth = 0;
     #diagnosticsPending = false;
@@ -233,8 +236,8 @@ export class SyncClient {
                 subscriptions.some((sub) => sub.status === 'active'));
         if (startupWork && this.#securityLifecycle === 'active') {
             this.#needsPull = true;
-            this.#config.onSyncNeeded?.('startup');
-            this.#config.onSyncIntent?.({ kind: 'interactive' });
+            this.#emitSyncNeeded('startup');
+            this.#emitSyncIntent({ kind: 'interactive' });
         }
         // Console introspection is a no-op outside a dev page.
         this.#devtoolsUnregister = registerDevtools({
@@ -298,6 +301,29 @@ export class SyncClient {
         this.#setSchemaFloor(undefined);
         this.#replayOutbox();
     }
+    /** §2.1 reset after the server reports a different log continuity. */
+    #runLogEpochReset(logEpoch) {
+        const subscriptions = loadSubscriptions(this.#db);
+        const pending = listOutbox(this.#db);
+        this.#setUpgrading(true);
+        this.#applyBatch((batch) => {
+            this.#db.transaction(() => {
+                dropAndRecreateSyncedTables(this.#db, this.#schema);
+                resetSubscriptionsForBump(this.#db);
+                setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
+                for (const commit of pending) {
+                    this.#applyOperationsLocally(commit.operations, batch);
+                }
+            });
+            for (const table of this.#schema.tables.values())
+                batch.table(table.name);
+        });
+        this.#localResetEpoch += 1;
+        this.#setSyncNeeded(true);
+        this.#emitSyncNeeded('startup');
+        this.#emitSyncIntent({ kind: 'interactive' });
+        return subscriptions.map((subscription) => subscription.id);
+    }
     #setUpgrading(upgrading) {
         if (this.#upgrading === upgrading)
             return;
@@ -325,6 +351,7 @@ export class SyncClient {
         });
     }
     async close() {
+        this.#emitSyncIntent({ kind: 'none' });
         this.#devtoolsUnregister?.();
         this.#devtoolsUnregister = undefined;
         this.disconnectRealtime();
@@ -332,6 +359,40 @@ export class SyncClient {
         await this.#lease?.release();
         this.#lease = undefined;
         this.#started = false;
+        this.#syncNeededListeners.clear();
+        this.#syncIntentListeners.clear();
+    }
+    #emitSyncNeeded(reason) {
+        try {
+            this.#config.onSyncNeeded?.(reason);
+        }
+        catch {
+            // An observer cannot alter sync correctness.
+        }
+        for (const listener of this.#syncNeededListeners) {
+            try {
+                listener(reason);
+            }
+            catch {
+                // An observer cannot alter sync correctness.
+            }
+        }
+    }
+    #emitSyncIntent(intent) {
+        try {
+            this.#config.onSyncIntent?.(intent);
+        }
+        catch {
+            // An observer cannot alter sync correctness.
+        }
+        for (const listener of this.#syncIntentListeners) {
+            try {
+                listener(intent);
+            }
+            catch {
+                // An observer cannot alter sync correctness.
+            }
+        }
     }
     /** Current fail-closed local-replica security state. */
     get securityLifecycle() {
@@ -382,8 +443,8 @@ export class SyncClient {
                 loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
         if (startupWork) {
             this.#setSyncNeeded(true);
-            this.#config.onSyncNeeded?.('startup');
-            this.#config.onSyncIntent?.({ kind: 'interactive' });
+            this.#emitSyncNeeded('startup');
+            this.#emitSyncIntent({ kind: 'interactive' });
         }
         this.#emitDiagnostics();
     }
@@ -479,6 +540,20 @@ export class SyncClient {
     onChange(listener) {
         return this.#changes.on(listener);
     }
+    /** Subscribe to host wake signals raised by startup and realtime. */
+    onSyncNeeded(listener) {
+        this.#syncNeededListeners.add(listener);
+        return () => {
+            this.#syncNeededListeners.delete(listener);
+        };
+    }
+    /** Subscribe to exact core-owned scheduling instructions. */
+    onSyncIntent(listener) {
+        this.#syncIntentListeners.add(listener);
+        return () => {
+            this.#syncIntentListeners.delete(listener);
+        };
+    }
     /** Subscribe to complete, privacy-safe diagnostic snapshots. */
     onDiagnostics(listener) {
         return this.#diagnostics.on(listener);
@@ -1119,11 +1194,17 @@ export class SyncClient {
             cursor: -1,
             status: 'active',
         });
+        this.#setSyncNeeded(true);
+        this.#emitSyncIntent({ kind: 'interactive' });
         this.#emitDiagnostics();
     }
     unsubscribe(id) {
         this.#requireActive();
+        if (getSubscription(this.#db, id) === undefined)
+            return;
         deleteSubscription(this.#db, id);
+        this.#setSyncNeeded(true);
+        this.#emitSyncIntent({ kind: 'interactive' });
         this.#emitDiagnostics();
     }
     // -- windowed subscriptions (§4.8) ------------------------------------------
@@ -1179,7 +1260,9 @@ export class SyncClient {
                             status: 'active',
                         });
                     });
+                    this.#needsPull = true;
                     batch.window(baseKey, base.table, unit);
+                    batch.status();
                 });
                 changed = true;
                 widened = true;
@@ -1195,6 +1278,9 @@ export class SyncClient {
         const effects = {
             sync: changed || widened ? { kind: 'interactive' } : { kind: 'none' },
         };
+        if (effects.sync.kind === 'interactive') {
+            this.#emitSyncIntent(effects.sync);
+        }
         return { value: undefined, effects };
     }
     /**
@@ -1254,6 +1340,8 @@ export class SyncClient {
             });
             batch.scopeMap(table, effective);
             batch.window(baseKey, table.name, unit);
+            this.#needsPull = true;
+            batch.status();
         });
     }
     /**
@@ -1349,7 +1437,9 @@ export class SyncClient {
                 this.#applyOperationsLocally(operations, batch);
                 batch.status();
             });
+            this.#needsPull = true;
         });
+        this.#emitSyncIntent({ kind: 'interactive' });
         return clientCommitId;
     }
     /** Host-facing mutation result with explicit network work intent (§7.5). */
@@ -1577,8 +1667,8 @@ export class SyncClient {
         this.#localResetEpoch += 1;
         if (!priorUpgrading)
             this.#config.onUpgrading?.(true);
-        this.#config.onSyncNeeded?.('startup');
-        this.#config.onSyncIntent?.({ kind: 'interactive' });
+        this.#emitSyncNeeded('startup');
+        this.#emitSyncIntent({ kind: 'interactive' });
         return {
             alreadyApplied: false,
             retainedCommits: pending.length,
@@ -1798,9 +1888,12 @@ export class SyncClient {
         // survive it — the reference server keeps no replay buffer (§8.2).
         this.#setSyncNeeded(false);
         try {
+            const logEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
             // §5.9.7 B4: upload pending blobs BEFORE pushing rows that reference
             // them, so the server-side existence check (§6.6) passes.
-            if (this.#hasBlobs && this.#config.blobs !== undefined) {
+            if (logEpoch !== undefined &&
+                this.#hasBlobs &&
+                this.#config.blobs !== undefined) {
                 await this.flushBlobUploads();
             }
             // §7.4.4: encode the outbox with the CURRENT codec; a commit that
@@ -1808,7 +1901,9 @@ export class SyncClient {
             // is removed from the push and surfaced as a rejection, never wedging
             // the queue. `pushFrames` and `outbox` stay index-aligned for result
             // mapping.
-            const { pushFrames, outbox, deferred } = await this.#encodeOutboxForPush();
+            const { pushFrames, outbox, deferred } = logEpoch === undefined
+                ? { pushFrames: [], outbox: [], deferred: 0 }
+                : await this.#encodeOutboxForPush();
             // Captured together with the subscription state below: the response
             // apply persists SUB_END cursors only while this epoch is current.
             const resetEpoch = this.#localResetEpoch;
@@ -1819,6 +1914,7 @@ export class SyncClient {
                     type: 'REQ_HEADER',
                     clientId: this.#clientId,
                     schemaVersion: this.#schema.version,
+                    ...(logEpoch !== undefined ? { logEpoch } : {}),
                 },
                 ...pushFrames,
                 {
@@ -1885,12 +1981,7 @@ export class SyncClient {
                     delayMs: this.#retryDelayMs,
                 };
                 this.#retryDelayMs = Math.min(this.#retryDelayMs * 2, 30_000);
-                try {
-                    this.#config.onSyncIntent?.(intent);
-                }
-                catch {
-                    // An observer cannot alter sync correctness.
-                }
+                this.#emitSyncIntent(intent);
             }
             throw error;
         }
@@ -2078,14 +2169,14 @@ export class SyncClient {
         if (event.event === 'hello') {
             if (event.data.requiresSync) {
                 this.#setSyncNeeded(true);
-                this.#config.onSyncNeeded?.('hello');
+                this.#emitSyncNeeded('hello');
             }
             return;
         }
         if (event.event === 'sync') {
             // §8.3: any wake-up means "run a pull soon", never data.
             this.#setSyncNeeded(true);
-            this.#config.onSyncNeeded?.(event.data.reason);
+            this.#emitSyncNeeded(event.data.reason);
             return;
         }
         if (event.event === 'presence') {
@@ -2155,7 +2246,7 @@ export class SyncClient {
             catch {
                 // A delta that cannot be applied is recovered by a pull (§8.3).
                 this.#setSyncNeeded(true);
-                this.#config.onSyncNeeded?.('catchup-required');
+                this.#emitSyncNeeded('catchup-required');
             }
         });
     }
@@ -2195,6 +2286,11 @@ export class SyncClient {
         if (header?.type !== 'RESP_HEADER') {
             throw new ClientSyncError('sync.invalid_request', 'missing RESP_HEADER');
         }
+        if (message.wireVersion < 2 ||
+            header.logEpoch === undefined ||
+            header.resetRequired === undefined) {
+            throw new ClientSyncError('client.invalid_host_response', 'the server response does not carry wire version 2 log-epoch state');
+        }
         if (header.requiredSchemaVersion !== undefined) {
             // §1.6 schema floor: nothing else was processed — stop syncing and
             // surface the upgrade requirement. A live-round floor always stops:
@@ -2216,6 +2312,20 @@ export class SyncClient {
                 schemaFloor,
             };
         }
+        const currentLogEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
+        if (header.resetRequired) {
+            if (mode !== 'pull' || message.frames.length !== 1) {
+                throw new ClientSyncError('client.invalid_host_response', 'a log-epoch reset response must contain only RESP_HEADER');
+            }
+            return {
+                ...summary,
+                resets: this.#runLogEpochReset(header.logEpoch),
+                bootstrapping: [],
+            };
+        }
+        if (currentLogEpoch === undefined || currentLogEpoch !== header.logEpoch) {
+            throw new ClientSyncError('client.invalid_host_response', 'the server changed logEpoch without requiring a reset');
+        }
         let section;
         let errorFrame;
         let deltaCursor = -1;

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * from './realtime-supervisor.js';
 export * from './schema.js';
 export * from './sql-tag.js';
 export * from './state.js';
+export * from './sync-scheduler.js';
 export * from './transport.js';
 export * from './window.js';
 export * from './worker-host.js';

package/dist/index.js

@@ -35,6 +35,7 @@ export * from './realtime-supervisor.js';
 export * from './schema.js';
 export * from './sql-tag.js';
 export * from './state.js';
+export * from './sync-scheduler.js';
 export * from './transport.js';
 export * from './window.js';
 export * from './worker-host.js';

package/dist/remote.d.ts

@@ -18,6 +18,8 @@ export interface SyncRemoteClientConfig {
     readonly operations?: RemoteOperationTransport;
     readonly operationRealtime?: RemoteOperationRealtimeConnector;
     readonly encryption?: EncryptionConfig;
+    /** Acquired partition log epoch for restore-safe ordinary commits (§2.1). */
+    readonly logEpoch?: string;
 }
 export interface RemoteCommitInput {
     /** Stable caller-owned idempotency identity for this logical commit. */

package/dist/remote.js

@@ -2,7 +2,7 @@
  * Database-less SSP2 producer (§6.10). It prepares and sends ordinary commits
  * through the existing push path without creating a local replica or outbox.
  */
-import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
+import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeRow, } from '@syncular/core';
 import { encryptRowValues } from './encryption.js';
 import { ClientSyncError } from './errors.js';
 import { compileClientSchema, recordToRowValues, } from './schema.js';
@@ -71,10 +71,14 @@ export class SyncRemoteClient {
     #operationSocketGeneration = 0;
     #watches = new Map();
     #encryption;
+    #logEpoch;
     constructor(config) {
         if (config.clientId.length === 0) {
             throw invalid('SyncRemoteClient clientId must be non-empty');
         }
+        if (config.logEpoch !== undefined && config.logEpoch.length === 0) {
+            throw invalid('SyncRemoteClient logEpoch must be non-empty');
+        }
         this.#schema =
             config.schema === undefined
                 ? undefined
@@ -84,6 +88,7 @@ export class SyncRemoteClient {
         this.#operations = config.operations;
         this.#operationRealtime = config.operationRealtime;
         this.#encryption = config.encryption;
+        this.#logEpoch = config.logEpoch;
     }
     async prepareCommit(input) {
         const schema = this.#schema;
@@ -137,13 +142,16 @@ export class SyncRemoteClient {
         return {
             requestId: input.requestId,
             bytes: encodeMessage({
-                wireVersion: PROTOCOL_WIRE_VERSION,
+                wireVersion: this.#logEpoch === undefined ? 1 : 2,
                 msgKind: 'request',
                 frames: [
                     {
                         type: 'REQ_HEADER',
                         clientId: this.#clientId,
                         schemaVersion: schema.version,
+                        ...(this.#logEpoch !== undefined
+                            ? { logEpoch: this.#logEpoch }
+                            : {}),
                     },
                     {
                         type: 'PUSH_COMMIT',

package/dist/sync-scheduler.d.ts

@@ -0,0 +1,23 @@
+import type { WakeReason } from '@syncular/core';
+import type { SecurityLifecycle } from './client.js';
+import type { SyncIntent } from './invalidation.js';
+export interface SyncSchedulerClient {
+    readonly syncNeeded: boolean;
+    readonly securityLifecycle: SecurityLifecycle;
+    syncUntilIdle(maxRounds?: number): Promise<unknown>;
+    onSyncNeeded(listener: (reason: 'startup' | 'hello' | WakeReason) => void): () => void;
+    onSyncIntent(listener: (intent: SyncIntent) => void): () => void;
+}
+export interface SyncSchedulerOptions {
+    readonly maxRounds?: number;
+    readonly onError?: (error: unknown) => void;
+    readonly now?: () => number;
+    readonly queueMicrotask?: (callback: () => void) => void;
+    readonly schedule?: (callback: () => void, delayMs: number) => () => void;
+}
+export interface SyncScheduler {
+    readonly stopped: boolean;
+    stop(): void;
+}
+/** Install the event-driven single-flight host loop for a direct client. */
+export declare function installSyncScheduler(client: SyncSchedulerClient, options?: SyncSchedulerOptions): SyncScheduler;

package/dist/sync-scheduler.js

@@ -0,0 +1,122 @@
+/** Install the event-driven single-flight host loop for a direct client. */
+export function installSyncScheduler(client, options = {}) {
+    const now = options.now ?? Date.now;
+    const enqueue = options.queueMicrotask ?? globalThis.queueMicrotask;
+    const schedule = options.schedule ??
+        ((callback, delayMs) => {
+            const timer = globalThis.setTimeout(callback, delayMs);
+            return () => globalThis.clearTimeout(timer);
+        });
+    let stopped = false;
+    let running = false;
+    let immediatePending = false;
+    let immediateQueued = false;
+    let backgroundReady = false;
+    let backgroundDue = Number.POSITIVE_INFINITY;
+    let cancelBackground;
+    const report = (error) => {
+        if (options.onError !== undefined) {
+            options.onError(error);
+            return;
+        }
+        const root = globalThis;
+        if (root.reportError !== undefined)
+            root.reportError(error);
+        else
+            console.error(error);
+    };
+    const clearBackground = () => {
+        cancelBackground?.();
+        cancelBackground = undefined;
+        backgroundReady = false;
+        backgroundDue = Number.POSITIVE_INFINITY;
+    };
+    const queueImmediate = () => {
+        immediatePending = true;
+        if (stopped || running || immediateQueued)
+            return;
+        immediateQueued = true;
+        enqueue(() => {
+            immediateQueued = false;
+            if (stopped || !immediatePending)
+                return;
+            immediatePending = false;
+            run();
+        });
+    };
+    const run = () => {
+        if (stopped || running)
+            return;
+        if (client.securityLifecycle === 'preflight') {
+            immediatePending = false;
+            return;
+        }
+        running = true;
+        backgroundReady = false;
+        void client
+            .syncUntilIdle(options.maxRounds)
+            .catch((error) => {
+            if (!stopped)
+                report(error);
+        })
+            .finally(() => {
+            running = false;
+            if (stopped)
+                return;
+            if (immediatePending || backgroundReady) {
+                queueImmediate();
+                return;
+            }
+            if (cancelBackground !== undefined && backgroundDue <= now()) {
+                clearBackground();
+                queueImmediate();
+            }
+        });
+    };
+    const consume = (intent) => {
+        if (stopped)
+            return;
+        if (intent.kind === 'none') {
+            clearBackground();
+            immediatePending = false;
+            return;
+        }
+        if (intent.kind === 'interactive') {
+            clearBackground();
+            queueImmediate();
+            return;
+        }
+        if (immediatePending || immediateQueued)
+            return;
+        clearBackground();
+        backgroundDue = now() + Math.max(0, intent.delayMs);
+        cancelBackground = schedule(() => {
+            cancelBackground = undefined;
+            backgroundDue = Number.POSITIVE_INFINITY;
+            backgroundReady = true;
+            if (!running)
+                queueImmediate();
+        }, Math.max(0, intent.delayMs));
+    };
+    const unsubscribeNeeded = client.onSyncNeeded(() => {
+        consume({ kind: 'interactive' });
+    });
+    const unsubscribeIntent = client.onSyncIntent(consume);
+    if (client.syncNeeded && client.securityLifecycle === 'active') {
+        consume({ kind: 'interactive' });
+    }
+    return {
+        get stopped() {
+            return stopped;
+        },
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            clearBackground();
+            immediatePending = false;
+            unsubscribeNeeded();
+            unsubscribeIntent();
+        },
+    };
+}

package/dist/window.d.ts

@@ -14,6 +14,11 @@
  */
 import { type ScopeMap } from '@syncular/core';
 import type { ClientDatabase } from './database.js';
+export type TimeBucketUnit = 'month';
+/** Derive the immutable UTC scope value stored when a row is created. */
+export declare function creationTimeBucket(createdAtMs: number, unit: TimeBucketUnit): string;
+/** Return a rolling UTC month window ordered from oldest to newest. */
+export declare function last(count: number, unit: TimeBucketUnit, nowMs?: number): string[];
 /**
  * A window base: one table, one variable whose values are the window
  * units, and any FIXED scopes every unit shares (other variables pinned

package/dist/window.js

@@ -13,6 +13,45 @@
  * transaction and the invalidation choke point.
  */
 import { canonicalScopeJson } from '@syncular/core';
+import { ClientSyncError } from './errors.js';
+const MAX_TIME_BUCKET_MS = 253_402_300_799_999;
+function monthBucket(year, month) {
+    return `${year.toString().padStart(4, '0')}-${month.toString().padStart(2, '0')}`;
+}
+/** Derive the immutable UTC scope value stored when a row is created. */
+export function creationTimeBucket(createdAtMs, unit) {
+    if (unit !== 'month' ||
+        !Number.isSafeInteger(createdAtMs) ||
+        createdAtMs < 0 ||
+        createdAtMs > MAX_TIME_BUCKET_MS) {
+        throw new ClientSyncError('sync.invalid_request', 'creationTimeBucket requires a supported unit and a UTC timestamp from 1970 through 9999');
+    }
+    const date = new Date(createdAtMs);
+    return monthBucket(date.getUTCFullYear(), date.getUTCMonth() + 1);
+}
+/** Return a rolling UTC month window ordered from oldest to newest. */
+export function last(count, unit, nowMs = Date.now()) {
+    if (unit !== 'month' ||
+        !Number.isSafeInteger(count) ||
+        count < 1 ||
+        count > 1_200 ||
+        !Number.isSafeInteger(nowMs) ||
+        nowMs < 0 ||
+        nowMs > MAX_TIME_BUCKET_MS) {
+        throw new ClientSyncError('sync.invalid_request', 'last requires a supported unit, a count from 1 through 1200, and a UTC timestamp from 1970 through 9999');
+    }
+    const date = new Date(nowMs);
+    const current = date.getUTCFullYear() * 12 + date.getUTCMonth();
+    if (current - (count - 1) < 1970 * 12) {
+        throw new ClientSyncError('sync.invalid_request', 'last requires every returned UTC month to fall from 1970 through 9999');
+    }
+    const units = [];
+    for (let offset = count - 1; offset >= 0; offset -= 1) {
+        const value = current - offset;
+        units.push(monthBucket(Math.floor(value / 12), (value % 12) + 1));
+    }
+    return units;
+}
 /**
  * A stable, server-opaque key for a window base — table + variable +
  * canonical fixed scopes. Two `setWindow` calls with the same base