@syncular/server 0.16.1 → 0.17.0

package/README.md

@@ -110,6 +110,11 @@ Log the cause for operators and stop startup. Do not catch readiness errors in
 authentication or convert them to a 401; request-time schema checks are only a
 defensive fallback.
 
+For D1, finish `storage.migrateSchema(compileSchema(schema))` across separate
+Worker invocations before admitting traffic. Each call returns `complete` and
+`statementsExecuted`; the default budget is 50 statements. See
+[D1 schema migration](https://syncular.dev/server-workers/#schema-migration).
+
 After restoring an authoritative database, keep traffic stopped and call
 `rotatePartitionLogEpoch({ storage, partition })` for every restored
 partition. The rotation clears stale client cursors and requires version 2
@@ -1111,13 +1116,19 @@ cannot silently return.
 ### commitSeq allocation under concurrency
 
 Per-partition `commitSeq` is dense and gap-free (§2.1). `appendCommit`
-allocates it with `UPDATE sync_partitions SET max_commit_seq =
-max_commit_seq + 1 … RETURNING`, which takes a row-level write lock on the
-partition row for the transaction's duration — concurrent pushes to the
-same partition serialize on that row; cross-partition pushes never
-contend. A Postgres `SEQUENCE` is deliberately **not** used: it would leave
+allocates it with an upsert that increments `sync_partitions.max_commit_seq`
+and returns the allocated value. A common table expression feeds that value
+into the commit metadata insert in the same SQL statement. The upsert takes a
+row-level write lock on the partition for the transaction duration. Concurrent
+pushes to that partition serialize; separate partitions use separate locks. A Postgres `SEQUENCE` is deliberately **not** used: it would leave
 gaps on rollback, which the §4.5 pull-window arithmetic does not tolerate.
 
+Each change insert expands its scope object into the inverted scope entries in
+the same statement. Serialized scopes bind as text before JSONB parsing; this
+avoids driver-specific JSON string encoding. Historical string-form scopes
+remain readable. Empty scopes still produce a change row, and repeated scopes
+within a commit retain one index entry.
+
 ### Multi-instance fanout (LISTEN/NOTIFY)
 
 Behind a load balancer, a commit applied on instance A fans out to A's
@@ -1186,3 +1197,12 @@ identity after authorization. Sharing is local to one process. Signed URL
 grants remain per request. The first eligibility probe has at most
 `limitSnapshotRows + 1` rows; subsequent builder batches have at most 5,000
 rows. The image database and serialized output still consume memory.
+
+
+Realtime acknowledgements call `advanceClientCursor(partition, clientId,
+actorId, logEpoch, cursor, updatedAtMs)`. Custom storage adapters must implement
+this atomic update: advance the cursor and activity timestamp to their respective
+maxima, preserve registration fields, and require a matching actor and current
+partition log epoch. Leave missing records unchanged. SQLite, Postgres, and D1
+perform one update without reading or serializing the subscription list. HTTP
+registration keeps its existing cursor and subscription replacement rules.

package/dist/d1-storage.d.ts

@@ -37,6 +37,13 @@ export declare class D1ServerStorage implements ServerStorage {
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name: string): CompiledTable;
     ensureSchema(schema: CompiledSchema): Promise<void>;
+    /** Run once per Worker invocation. Resume an incomplete result in another invocation. */
+    migrateSchema(schema: CompiledSchema, options?: {
+        readonly maxStatements?: number;
+    }): Promise<{
+        readonly complete: boolean;
+        readonly statementsExecuted: number;
+    }>;
     touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
     rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
     listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
@@ -63,6 +70,8 @@ export declare class D1ServerStorage 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<{