@syncular/client 0.59.0 → 0.60.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/README.md +27 -27
  2. package/dist/apply.d.ts +6 -5
  3. package/dist/apply.js +52 -25
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +4 -4
  6. package/dist/bun-database.js +3 -16
  7. package/dist/client.d.ts +57 -66
  8. package/dist/client.js +701 -796
  9. package/dist/devtools.d.ts +2 -2
  10. package/dist/devtools.js +3 -3
  11. package/dist/diagnostics.d.ts +17 -28
  12. package/dist/diagnostics.js +1 -2
  13. package/dist/errors.d.ts +1 -1
  14. package/dist/errors.js +1 -1
  15. package/dist/failed-overlay.js +4 -1
  16. package/dist/http.js +19 -5
  17. package/dist/invalidation.d.ts +3 -4
  18. package/dist/invalidation.js +9 -22
  19. package/dist/native-bridge.d.ts +7 -16
  20. package/dist/native-bridge.js +16 -41
  21. package/dist/node-database.js +16 -25
  22. package/dist/outbox.js +1 -0
  23. package/dist/progress.d.ts +2 -2
  24. package/dist/query-guard.d.ts +15 -6
  25. package/dist/query-guard.js +38 -6
  26. package/dist/reactive-store.js +2 -2
  27. package/dist/remote.js +9 -9
  28. package/dist/schema.d.ts +3 -2
  29. package/dist/schema.js +28 -12
  30. package/dist/state.d.ts +69 -36
  31. package/dist/state.js +178 -89
  32. package/dist/sync-scheduler.js +2 -2
  33. package/dist/transport.d.ts +2 -2
  34. package/dist/window.d.ts +30 -52
  35. package/dist/window.js +33 -77
  36. package/dist/worker-core.js +6 -6
  37. package/dist/worker-host.d.ts +9 -8
  38. package/dist/worker-host.js +23 -14
  39. package/dist/worker-protocol.d.ts +9 -8
  40. package/package.json +3 -3
  41. package/src/apply.ts +87 -33
  42. package/src/authority.ts +31 -17
  43. package/src/blob.ts +4 -3
  44. package/src/bun-database.ts +9 -14
  45. package/src/client.ts +886 -1037
  46. package/src/devtools.ts +5 -5
  47. package/src/diagnostics.ts +17 -37
  48. package/src/errors.ts +1 -1
  49. package/src/failed-overlay.ts +6 -1
  50. package/src/http.ts +22 -9
  51. package/src/invalidation.ts +9 -29
  52. package/src/native-bridge.ts +22 -58
  53. package/src/node-database.ts +26 -27
  54. package/src/outbox.ts +1 -0
  55. package/src/progress.ts +2 -2
  56. package/src/query-guard.ts +45 -8
  57. package/src/reactive-store.ts +2 -2
  58. package/src/remote.ts +12 -16
  59. package/src/schema.ts +48 -13
  60. package/src/state.ts +246 -125
  61. package/src/sync-scheduler.ts +2 -2
  62. package/src/transport.ts +2 -2
  63. package/src/window.ts +55 -134
  64. package/src/worker-core.ts +6 -6
  65. package/src/worker-host.ts +27 -19
  66. package/src/worker-protocol.ts +8 -8
@@ -25,10 +25,10 @@ import type { PromiseMethods } from './client.js';
25
25
  */
26
26
  import { type PresenceErrorCode, type WakeReason } from '@syncular/core';
27
27
  import type { BlobRef, CachedBlob } from './blob.js';
28
- import type { ConflictRecord, CurrentBaseProof, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
28
+ import type { ConflictRecord, CurrentBaseProof, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
29
29
  import type { SqlRow, SqlValue } from './database.js';
30
30
  import type { DevtoolsRegistrar } from './devtools.js';
31
- import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
31
+ import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
32
32
  import type { EncryptionKeyringConfig } from './encryption.js';
33
33
  import { ClientSyncError } from './errors.js';
34
34
  import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
@@ -40,7 +40,8 @@ import type { OutboxCommit } from './outbox.js';
40
40
  import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
41
41
  import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
42
42
  import type { ClientSchema } from './schema.js';
43
- import type { SubscriptionRecord } from './state.js';
43
+ import type { UnitScopes } from '@syncular/core';
44
+ import type { UnitRecord } from './state.js';
44
45
  import type { WindowBase } from './window.js';
45
46
  import { type LocalAuthorityState, type SyncWorkerEvent, type WorkerApi, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape, type WorkerSecurityActivation } from './worker-protocol.js';
46
47
  /** Classify startup without echoing a chunk URL or bundler text to UI/logs. */
@@ -239,8 +240,8 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
239
240
  * worker still holds the database files.
240
241
  */
241
242
  takeOver(): Promise<void>;
242
- subscribe(input: SubscribeInput): Promise<void>;
243
- subscribeMany(inputs: readonly SubscribeInput[]): Promise<void>;
243
+ subscribe(scopes: UnitScopes): Promise<string>;
244
+ subscribeMany(units: readonly UnitScopes[]): Promise<string[]>;
244
245
  securityLifecycle(): Promise<SecurityLifecycle>;
245
246
  beginSecurityPreflight(): Promise<void>;
246
247
  activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
@@ -275,7 +276,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
275
276
  snapshotRead<Row = SqlRow>(spec: SnapshotReadRequest): Promise<SnapshotRead<Row>>;
276
277
  localRevision(): Promise<LocalRevision>;
277
278
  statusSnapshot(): Promise<SyncStatusSnapshot>;
278
- diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;
279
+ diagnosticsSnapshot(): Promise<ClientDiagnosticsSnapshot>;
279
280
  conflicts(): Promise<readonly ConflictRecord[]>;
280
281
  rejections(): Promise<readonly RejectionRecord[]>;
281
282
  commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
@@ -283,8 +284,8 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
283
284
  resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
284
285
  /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
285
286
  pendingCommits(): Promise<OutboxCommit[]>;
286
- subscriptions(): Promise<SubscriptionRecord[]>;
287
- subscription(id: string): Promise<SubscriptionRecord | undefined>;
287
+ units(): Promise<UnitRecord[]>;
288
+ unit(id: string): Promise<UnitRecord | undefined>;
288
289
  connectRealtime(): Promise<void>;
289
290
  disconnectRealtime(): Promise<void>;
290
291
  /** §8.6: publish/clear a scope-keyed presence document. */
@@ -137,7 +137,7 @@ export class SyncClientHandle {
137
137
  clientId: () => this.#clientId,
138
138
  role: () => this.#role,
139
139
  outbox: async () => (await this.statusSnapshot()).outbox,
140
- subscriptions: () => this.subscriptions(),
140
+ units: () => this.units(),
141
141
  conflicts: async () => (await this.conflicts()).length,
142
142
  rejections: async () => (await this.rejections()).length,
143
143
  syncNeeded: async () => (await this.statusSnapshot()).syncNeeded,
@@ -303,11 +303,11 @@ export class SyncClientHandle {
303
303
  }
304
304
  return this.#core.invoke(method, args);
305
305
  }
306
- subscribe(input) {
307
- return this.#call('subscribe', [input]);
306
+ subscribe(scopes) {
307
+ return this.#call('subscribe', [scopes]);
308
308
  }
309
- subscribeMany(inputs) {
310
- return this.#call('subscribeMany', [inputs]);
309
+ subscribeMany(units) {
310
+ return this.#call('subscribeMany', [units]);
311
311
  }
312
312
  securityLifecycle() {
313
313
  return this.#call('securityLifecycle', []);
@@ -391,8 +391,8 @@ export class SyncClientHandle {
391
391
  statusSnapshot() {
392
392
  return this.#call('statusSnapshot', []);
393
393
  }
394
- async diagnosticsSnapshot(request = {}) {
395
- const snapshot = await this.#call('diagnosticsSnapshot', [request]);
394
+ async diagnosticsSnapshot() {
395
+ const snapshot = await this.#call('diagnosticsSnapshot', []);
396
396
  return withClientDiagnosticsHost(snapshot, {
397
397
  ...snapshot.host,
398
398
  kind: 'worker',
@@ -418,11 +418,11 @@ export class SyncClientHandle {
418
418
  pendingCommits() {
419
419
  return this.#call('pendingCommits', []);
420
420
  }
421
- subscriptions() {
422
- return this.#call('subscriptions', []);
421
+ units() {
422
+ return this.#call('units', []);
423
423
  }
424
- subscription(id) {
425
- return this.#call('subscription', [id]);
424
+ unit(id) {
425
+ return this.#call('unit', [id]);
426
426
  }
427
427
  connectRealtime() {
428
428
  return this.#call('connectRealtime', []);
@@ -597,9 +597,18 @@ async function startWorkerCore(options) {
597
597
  config: initConfig,
598
598
  });
599
599
  });
600
- // A config callback is a consumer from the first round.
601
- if (config.onDiagnostics !== undefined)
602
- await invoke('diagnosticsSnapshot', []);
600
+ // A config callback is a consumer from the first round. Under security
601
+ // preflight the core refuses the snapshot after the pull registered the
602
+ // worker as a push source, and activateSecurity() emits the first one.
603
+ if (config.onDiagnostics !== undefined) {
604
+ await invoke('diagnosticsSnapshot', []).catch((error) => {
605
+ if (config.securityPreflight !== true ||
606
+ !(error instanceof ClientSyncError) ||
607
+ error.code !== 'client.security_preflight_required') {
608
+ throw error;
609
+ }
610
+ });
611
+ }
603
612
  return {
604
613
  clientId: initResult.clientId,
605
614
  invoke,
@@ -19,7 +19,7 @@ import type { SyncProgress } from './progress.js';
19
19
  */
20
20
  import type { PresenceErrorCode, WakeReason } from '@syncular/core';
21
21
  import type { BlobRef, CachedBlob } from './blob.js';
22
- import type { ConflictRecord, CurrentBaseProof, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
22
+ import type { ConflictRecord, CurrentBaseProof, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
23
23
  import type { SqlRow, SqlValue } from './database.js';
24
24
  import type { ClientDiagnosticsSnapshot, RealtimePolicy } from './diagnostics.js';
25
25
  import type { EncryptionKeyringConfig } from './encryption.js';
@@ -30,7 +30,8 @@ import type { OutboxCommit } from './outbox.js';
30
30
  import type { CommitOutcome } from './outcomes.js';
31
31
  import type { PreviousVersionAudit, PreviousVersionReadSpec, PreviousVersionSnapshot } from './previous-version.js';
32
32
  import type { ClientSchema } from './schema.js';
33
- import type { SubscriptionRecord } from './state.js';
33
+ import type { UnitScopes } from '@syncular/core';
34
+ import type { UnitRecord } from './state.js';
34
35
  import type { WindowBase } from './window.js';
35
36
  /** The handle exists but this tab lost the leader election. */
36
37
  export declare const NOT_LEADER_CODE = "client.not_leader";
@@ -133,12 +134,12 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
133
134
  securityLifecycle(): SecurityLifecycle;
134
135
  beginSecurityPreflight(): Promise<void>;
135
136
  activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
136
- subscribe(input: SubscribeInput): void;
137
- subscribeMany(inputs: readonly SubscribeInput[]): void;
137
+ subscribe(scopes: UnitScopes): string;
138
+ subscribeMany(units: readonly UnitScopes[]): string[];
138
139
  unsubscribe(id: string): void;
139
- /** §4.8 windowed subscriptions: set the live units for a window base. */
140
+ /** §4.8 windows: set the windowed-in values of a base. */
140
141
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
141
- /** §4.8 completeness oracle (I3): the windowed-in units for a base. */
142
+ /** §4.8 completeness oracle: the windowed-in values of a base. */
142
143
  windowState(base: WindowBase): WindowState;
143
144
  mutate(mutations: readonly MutationInput[]): string;
144
145
  /** Partial-update convenience: read-merge-write one full-row upsert. */
@@ -167,8 +168,8 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
167
168
  querySnapshot(spec: QueryReadSpec): QuerySnapshot;
168
169
  localRevision(): LocalRevision;
169
170
  pendingCommits(): OutboxCommit[];
170
- subscriptions(): SubscriptionRecord[];
171
- subscription(id: string): SubscriptionRecord | undefined;
171
+ units(): UnitRecord[];
172
+ unit(id: string): UnitRecord | undefined;
172
173
  connectRealtime(): Promise<void>;
173
174
  disconnectRealtime(): void;
174
175
  /** §8.6 presence: publish/clear a scope-keyed presence document. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.59.0",
3
+ "version": "0.60.1",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -113,11 +113,11 @@
113
113
  },
114
114
  "dependencies": {
115
115
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
116
- "@syncular/core": "0.59.0"
116
+ "@syncular/core": "0.60.1"
117
117
  },
118
118
  "devDependencies": {
119
119
  "@electric-sql/pglite": "^0.5.4",
120
- "@syncular/server": "0.59.0",
120
+ "@syncular/server": "0.60.1",
121
121
  "playwright": "1.63.0",
122
122
  "vite": "8.3.4"
123
123
  }
package/src/apply.ts CHANGED
@@ -83,9 +83,43 @@ export function deleteLocalRow(
83
83
  }
84
84
 
85
85
  /**
86
- * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4).
87
- * Upserts land with `_sync_version = rowVersion`; deletes remove the row.
88
- * Re-application is idempotent (§1.4 rule 5).
86
+ * §4.5 version guard for one server row: whether a write at `version` lands.
87
+ * A skipped row keeps its overlay, so its key leaves the rebase scope unless a
88
+ * retained base was restored for it; `kept` and `skipped` collect the keys.
89
+ */
90
+ function lands(
91
+ db: ClientDatabase,
92
+ table: CompiledClientTable,
93
+ rowId: string,
94
+ version: number,
95
+ kept: Set<string>,
96
+ skipped: Set<string>,
97
+ ): boolean {
98
+ const key = JSON.stringify([table.name, rowId]);
99
+ const local = db.query(
100
+ `SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v,EXISTS(SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=?) AS retained FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
101
+ [table.name, rowId, pkSqlValue(table, rowId)],
102
+ )[0];
103
+ const land = local === undefined || Number(local.v) < version;
104
+ if (land || local.retained) kept.add(key);
105
+ else skipped.add(key);
106
+ return land;
107
+ }
108
+
109
+ /** The scope a guarded write leaves for the overlay replay. */
110
+ function rebaseScope(
111
+ scope: OverlayScope,
112
+ kept: Set<string>,
113
+ skipped: Set<string>,
114
+ ): OverlayScope {
115
+ return scope.filter((key) => kept.has(key) || !skipped.has(key));
116
+ }
117
+
118
+ /**
119
+ * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4) under the
120
+ * §4.5 version guard: a change lands only when its `rowVersion` exceeds the
121
+ * local row's `_sync_version`. Upserts land with `_sync_version = rowVersion`;
122
+ * deletes remove the row. Re-application changes nothing.
89
123
  *
90
124
  * §5.11: encrypted columns are decrypted here — the apply seam. Because
91
125
  * WebCrypto is async and the local transaction is synchronous, every row is
@@ -102,13 +136,8 @@ export async function applyCommitFrame(
102
136
  transaction: (fn: () => OverlayScope) => unknown = (fn) => db.transaction(fn),
103
137
  ): Promise<void> {
104
138
  type Resolved =
105
- | { op: 'delete'; table: CompiledClientTable; rowId: string }
106
- | {
107
- op: 'upsert';
108
- table: CompiledClientTable;
109
- values: readonly RowValue[];
110
- rowVersion: number;
111
- };
139
+ | { op: 'delete'; table: CompiledClientTable }
140
+ | { op: 'upsert'; table: CompiledClientTable; values: readonly RowValue[] };
112
141
  const resolved: Resolved[] = [];
113
142
  for (const change of frame.changes) {
114
143
  const tableName = frame.tables[change.tableIndex];
@@ -125,10 +154,10 @@ export async function applyCommitFrame(
125
154
  );
126
155
  }
127
156
  if (change.op === 'delete') {
128
- resolved.push({ op: 'delete', table, rowId: change.rowId });
157
+ resolved.push({ op: 'delete', table });
129
158
  continue;
130
159
  }
131
- if (change.row === undefined || change.rowVersion === undefined) {
160
+ if (change.row === undefined) {
132
161
  throw invalidRequest('upsert change without row payload');
133
162
  }
134
163
  let values = decodeRow(table.columns, change.row);
@@ -136,12 +165,7 @@ export async function applyCommitFrame(
136
165
  const { decryptRowValues } = await import('./encryption');
137
166
  values = await decryptRowValues(encryption, table, values);
138
167
  }
139
- resolved.push({
140
- op: 'upsert',
141
- table,
142
- values,
143
- rowVersion: change.rowVersion,
144
- });
168
+ resolved.push({ op: 'upsert', table, values });
145
169
  }
146
170
  transaction(() => {
147
171
  // Exact keys name the rows this frame rebases; unique-key peers widen the
@@ -153,8 +177,11 @@ export async function applyCommitFrame(
153
177
  JSON.stringify([change.table.name, frame.changes[index]!.rowId]),
154
178
  ]);
155
179
  restoreFailedBases(db, schema, scope);
180
+ const kept = new Set<string>();
181
+ const skipped = new Set<string>();
156
182
  for (const [index, change] of resolved.entries()) {
157
- const rowId = frame.changes[index]!.rowId;
183
+ const { rowId, rowVersion } = frame.changes[index]!;
184
+ const land = lands(db, change.table, rowId, rowVersion, kept, skipped);
158
185
  db.exec(
159
186
  `UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`,
160
187
  [frame.commitSeq, change.table.name, rowId],
@@ -163,13 +190,11 @@ export async function applyCommitFrame(
163
190
  `DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`,
164
191
  [change.table.name, rowId, frame.commitSeq],
165
192
  );
166
- if (change.op === 'delete') {
167
- deleteLocalRow(db, change.table, change.rowId);
168
- } else {
169
- upsertLocalRow(db, change.table, change.values, change.rowVersion);
170
- }
193
+ if (!land) continue;
194
+ if (change.op === 'delete') deleteLocalRow(db, change.table, rowId);
195
+ else upsertLocalRow(db, change.table, change.values, rowVersion);
171
196
  }
172
- return scope;
197
+ return rebaseScope(scope, kept, skipped);
173
198
  });
174
199
  }
175
200
 
@@ -418,7 +443,7 @@ export async function applySqliteSegment(
418
443
  options: {
419
444
  readonly clearFirst: boolean;
420
445
  readonly effective: ScopeMap;
421
- /** Effective scopes of the other row-holding subscriptions (§5.6). */
446
+ /** Pair scopes of the units that own rows of the table (§3.3). */
422
447
  readonly owners: readonly ScopeMap[];
423
448
  readonly transaction?: ApplyTransaction;
424
449
  readonly onProgress?: (rowsProcessed: number) => void;
@@ -503,6 +528,7 @@ export async function applySqliteSegment(
503
528
  .filter((name) => name !== primaryKey)
504
529
  .map((name) => `${name}=excluded.${name}`)
505
530
  .join(', ');
531
+ const version = quoteIdent(SYNC_VERSION_COLUMN);
506
532
  let after: SqlValue | undefined;
507
533
  let applied = 0;
508
534
  for (;;) {
@@ -548,13 +574,31 @@ export async function applySqliteSegment(
548
574
  const protectedRows = restoreFailedBases(db, schema, scope);
549
575
  if (after === undefined && options.clearFirst)
550
576
  deleteScopedRows(db, table, options.effective, options.owners);
577
+ const kept = new Set<string>();
578
+ const skipped = new Set<string>();
579
+ const landing = rows.filter((row) =>
580
+ lands(
581
+ db,
582
+ table,
583
+ String(row[table.primaryKey]),
584
+ Number(row._syncular_version),
585
+ kept,
586
+ skipped,
587
+ ),
588
+ );
589
+ const where = predicates.join(' AND ') || 'true';
551
590
  db.exec(
552
- `INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')} FROM ${source} WHERE ${predicates.join(' AND ') || 'true'} ON CONFLICT(${primaryKey})DO UPDATE SET ${updates}`,
591
+ `INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')} FROM ${source} WHERE ${where} ON CONFLICT(${primaryKey})DO UPDATE SET ${updates} WHERE excluded.${version}>${quoteIdent(table.name)}.${version}`,
553
592
  params,
554
593
  );
555
- applied += Number(db.query('SELECT changes()AS n')[0]?.n ?? 0);
594
+ applied += Number(
595
+ db.query(
596
+ `SELECT count(*)AS n FROM ${source} WHERE ${where}`,
597
+ params,
598
+ )[0]?.n,
599
+ );
556
600
  if (protectedRows)
557
- for (const row of rows) {
601
+ for (const row of landing) {
558
602
  retainedBaseWrite(
559
603
  db,
560
604
  table,
@@ -568,7 +612,7 @@ export async function applySqliteSegment(
568
612
  Number(row._syncular_version),
569
613
  );
570
614
  }
571
- return scope;
615
+ return rebaseScope(scope, kept, skipped);
572
616
  });
573
617
  options.onProgress?.(applied);
574
618
  await yieldToHost();
@@ -597,7 +641,7 @@ export async function applyRowsSegment(
597
641
  options: {
598
642
  readonly clearFirst: boolean;
599
643
  readonly effective: ScopeMap;
600
- /** Effective scopes of the other row-holding subscriptions (§5.6). */
644
+ /** Pair scopes of the units that own rows of the table (§3.3). */
601
645
  readonly owners: readonly ScopeMap[];
602
646
  readonly transaction?: ApplyTransaction;
603
647
  readonly onProgress?: (rowsProcessed: number) => void;
@@ -646,12 +690,22 @@ export async function applyRowsSegment(
646
690
  if (clearThisBlock) {
647
691
  deleteScopedRows(db, table, options.effective, options.owners);
648
692
  }
693
+ const kept = new Set<string>();
694
+ const skipped = new Set<string>();
649
695
  for (const row of rows) {
650
- upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
696
+ const rowId = String(row.values[table.primaryKeyIndex]);
697
+ if (lands(db, table, rowId, row.serverVersion, kept, skipped))
698
+ upsertLocalRow(
699
+ db,
700
+ table,
701
+ row.values,
702
+ row.serverVersion,
703
+ protectedRows,
704
+ );
651
705
  applied += 1;
652
706
  if (applied % 1024 === 0) options.onProgress?.(applied);
653
707
  }
654
- return scope;
708
+ return rebaseScope(scope, kept, skipped);
655
709
  });
656
710
  options.onProgress?.(applied);
657
711
  await yieldToHost();
package/src/authority.ts CHANGED
@@ -2,7 +2,15 @@ import type { ClientDatabase, SqlRow, SqlValue } from './database';
2
2
  import { ClientSyncError } from './errors';
3
3
  import { listOutbox, listOutboxBeforeImages } from './outbox';
4
4
  import { RETAINED_ROWS } from './failed-overlay';
5
- import { getLocalRevision, getMeta, loadSubscriptions } from './state';
5
+ import {
6
+ bootstrapping,
7
+ covers,
8
+ getLocalRevision,
9
+ getMeta,
10
+ loadUnits,
11
+ pairScopes,
12
+ replicaCursor,
13
+ } from './state';
6
14
  import { fromSqlValue, quoteIdent, SYNC_VERSION_COLUMN } from './schema';
7
15
  import type { CompiledClientSchema, JsonRowValue } from './schema';
8
16
 
@@ -127,7 +135,8 @@ function readAuthoritySnapshot(
127
135
  'authority revision is missing or invalid',
128
136
  );
129
137
  const revision = getLocalRevision(db);
130
- const subscriptions = loadSubscriptions(db);
138
+ const units = loadUnits(db);
139
+ const cursor = replicaCursor(db);
131
140
  const tables = declarations.map((read) => {
132
141
  const table = schema.tables.get(read.table)!;
133
142
  const columns = [
@@ -259,23 +268,23 @@ function readAuthoritySnapshot(
259
268
  },
260
269
  ];
261
270
  });
262
- const persisted = subscriptions
263
- .filter((s) => s.table === read.table)
264
- .map((s) => {
265
- const effective = s.effectiveScopes;
266
- const complete =
267
- effective !== undefined &&
268
- Object.keys(effective).length === Object.keys(read.scopes).length &&
269
- s.status === 'active' &&
270
- s.cursor >= 0 &&
271
- s.bootstrapState === undefined &&
272
- s.params === undefined;
271
+ // Every unit covering the table, as its (unit, table) pair (§4.4).
272
+ const persisted = units
273
+ .filter((unit) => covers(table, unit.scopes))
274
+ .map((unit) => {
275
+ const effective =
276
+ unit.echo === undefined
277
+ ? undefined
278
+ : pairScopes(unit.scopes, read.table, unit.echo);
273
279
  return {
274
280
  requestedScopes: Object.fromEntries(
275
- Object.keys(read.scopes).map((v) => [v, s.scopes[v] ?? []]),
281
+ Object.keys(read.scopes).map((v) => [
282
+ v,
283
+ unit.scopes[v] === undefined ? [] : [unit.scopes[v]],
284
+ ]),
276
285
  ),
277
- status: s.status,
278
- cursor: s.cursor,
286
+ status: unit.status,
287
+ cursor: unit.cursor ?? cursor,
279
288
  effectiveScopes:
280
289
  effective === undefined
281
290
  ? null
@@ -285,7 +294,12 @@ function readAuthoritySnapshot(
285
294
  effective[v] ?? [],
286
295
  ]),
287
296
  ),
288
- complete,
297
+ complete:
298
+ effective !== undefined &&
299
+ Object.keys(effective).length ===
300
+ Object.keys(read.scopes).length &&
301
+ unit.status === 'active' &&
302
+ !bootstrapping(unit),
289
303
  };
290
304
  });
291
305
  const selectors = Object.entries(read.scopes);
package/src/blob.ts CHANGED
@@ -45,7 +45,7 @@ export type BlobUploadGrant =
45
45
  /**
46
46
  * The transport seam for blob upload/download (§5.9.3/§5.9.5). The upload
47
47
  * calls receive the round's `signal`, which aborts when the `syncUntilIdle`
48
- * deadline elapses (§7.7).
48
+ * deadline elapses (§7.8).
49
49
  */
50
50
  export interface BlobTransport {
51
51
  /** `PUT <mount>/blobs/{blobId}` — host-authenticated direct upload (§5.9.3). */
@@ -84,11 +84,12 @@ export interface BlobTransport {
84
84
  /**
85
85
  * §5.9.3 direct-to-storage PUT of the granted `url`. MUST attach NO host
86
86
  * authentication — the presigned URL is the entire grant (§5.4) — and MUST
87
- * send `x-amz-checksum-sha256` (base64 of the body's SHA-256), which the
88
- * grant signs beside `content-length`. Only called when `uploadGrant`
87
+ * send `x-amz-checksum-sha256` (base64 of the digest `blobId` names), which
88
+ * the grant signs beside `content-length`. Only called when `uploadGrant`
89
89
  * returned a `url` arm.
90
90
  */
91
91
  uploadToUrl?(
92
+ blobId: string,
92
93
  url: string,
93
94
  bytes: Uint8Array,
94
95
  mediaType?: string,
@@ -15,7 +15,7 @@ import {
15
15
  type SqlRow,
16
16
  type SqlValue,
17
17
  } from './database';
18
- import { prepareReadOnly, refuseRawSql } from './query-guard';
18
+ import { prepareReadOnly, runReadOnly } from './query-guard';
19
19
 
20
20
  declare module 'bun:sqlite' {
21
21
  interface Database {
@@ -35,6 +35,7 @@ function coerceParams(params: readonly SqlValue[]): BunParam[] {
35
35
  export class BunClientDatabase implements ClientDatabase {
36
36
  readonly db: Database;
37
37
  readonly #path: string;
38
+ readonly #proven = new Set<string>();
38
39
  #tx = { depth: 0 };
39
40
 
40
41
  constructor(path = ':memory:') {
@@ -78,19 +79,13 @@ export class BunClientDatabase implements ClientDatabase {
78
79
  prepared.columnNames.length > 0,
79
80
  ] as const;
80
81
  });
81
- // bun:sqlite exposes `sqlite3_stmt_readonly` only from Bun 1.4.4, so
82
- // SQLite refuses a write when the statement runs: under `query_only` a
83
- // write transaction fails before it changes anything.
84
- this.db.run('PRAGMA query_only = ON');
85
- try {
86
- return statement.all(...coerceParams(params)) as SqlRow[];
87
- } catch (error) {
88
- if ((error as { code?: unknown }).code === 'SQLITE_READONLY')
89
- refuseRawSql();
90
- throw error;
91
- } finally {
92
- this.db.run('PRAGMA query_only = OFF');
93
- }
82
+ return runReadOnly(
83
+ this.#proven,
84
+ sql,
85
+ (pragma) => this.db.run(pragma),
86
+ (error) => (error as { code?: unknown }).code === 'SQLITE_READONLY',
87
+ () => statement.all(...coerceParams(params)) as SqlRow[],
88
+ );
94
89
  }
95
90
 
96
91
  /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */