@syncular/client 0.58.0 → 0.60.0

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 (99) hide show
  1. package/README.md +34 -34
  2. package/dist/apply.d.ts +24 -14
  3. package/dist/apply.js +119 -70
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +17 -9
  6. package/dist/blob.js +5 -6
  7. package/dist/bun-database.d.ts +1 -0
  8. package/dist/bun-database.js +15 -0
  9. package/dist/client.d.ts +83 -75
  10. package/dist/client.js +982 -910
  11. package/dist/database.d.ts +5 -0
  12. package/dist/devtools.d.ts +2 -2
  13. package/dist/devtools.js +3 -3
  14. package/dist/diagnostics.d.ts +17 -28
  15. package/dist/diagnostics.js +1 -2
  16. package/dist/encryption.d.ts +2 -2
  17. package/dist/encryption.js +8 -2
  18. package/dist/errors.d.ts +3 -1
  19. package/dist/errors.js +5 -1
  20. package/dist/failed-overlay.d.ts +0 -1
  21. package/dist/failed-overlay.js +6 -6
  22. package/dist/http.d.ts +4 -1
  23. package/dist/http.js +67 -39
  24. package/dist/index.d.ts +1 -1
  25. package/dist/index.js +1 -1
  26. package/dist/invalidation.d.ts +14 -14
  27. package/dist/invalidation.js +24 -48
  28. package/dist/local-purge.js +9 -12
  29. package/dist/local-rebootstrap.js +2 -2
  30. package/dist/multi-tab.d.ts +89 -1
  31. package/dist/multi-tab.js +70 -31
  32. package/dist/native-bridge.d.ts +226 -0
  33. package/dist/native-bridge.js +764 -0
  34. package/dist/node-database.d.ts +1 -0
  35. package/dist/node-database.js +21 -1
  36. package/dist/outbox.d.ts +9 -12
  37. package/dist/outbox.js +20 -36
  38. package/dist/outcomes.js +3 -3
  39. package/dist/previous-version.js +96 -114
  40. package/dist/progress.d.ts +2 -2
  41. package/dist/query-guard.d.ts +34 -24
  42. package/dist/query-guard.js +61 -186
  43. package/dist/reactive-store.js +55 -13
  44. package/dist/realtime-supervisor.d.ts +9 -2
  45. package/dist/realtime-supervisor.js +31 -7
  46. package/dist/remote.js +19 -23
  47. package/dist/schema.d.ts +3 -2
  48. package/dist/schema.js +43 -22
  49. package/dist/state.d.ts +69 -36
  50. package/dist/state.js +178 -89
  51. package/dist/sync-scheduler.js +28 -2
  52. package/dist/transport.d.ts +19 -4
  53. package/dist/wasm-database.js +58 -21
  54. package/dist/window.d.ts +30 -52
  55. package/dist/window.js +33 -77
  56. package/dist/worker-core.d.ts +5 -0
  57. package/dist/worker-core.js +83 -75
  58. package/dist/worker-host.d.ts +19 -13
  59. package/dist/worker-host.js +75 -18
  60. package/dist/worker-local-authority.js +2 -2
  61. package/dist/worker-protocol.d.ts +15 -10
  62. package/package.json +11 -3
  63. package/src/apply.ts +176 -86
  64. package/src/authority.ts +31 -17
  65. package/src/blob.ts +28 -15
  66. package/src/bun-database.ts +24 -0
  67. package/src/client.ts +1282 -1217
  68. package/src/database.ts +5 -0
  69. package/src/devtools.ts +5 -5
  70. package/src/diagnostics.ts +17 -37
  71. package/src/encryption.ts +10 -5
  72. package/src/errors.ts +9 -1
  73. package/src/failed-overlay.ts +8 -7
  74. package/src/http.ts +95 -79
  75. package/src/index.ts +1 -1
  76. package/src/invalidation.ts +26 -61
  77. package/src/local-purge.ts +11 -13
  78. package/src/local-rebootstrap.ts +2 -3
  79. package/src/multi-tab.ts +88 -30
  80. package/src/native-bridge.ts +1153 -0
  81. package/src/node-database.ts +32 -1
  82. package/src/outbox.ts +20 -41
  83. package/src/outcomes.ts +3 -5
  84. package/src/previous-version.ts +103 -114
  85. package/src/progress.ts +2 -2
  86. package/src/query-guard.ts +77 -177
  87. package/src/reactive-store.ts +52 -12
  88. package/src/realtime-supervisor.ts +37 -12
  89. package/src/remote.ts +23 -31
  90. package/src/schema.ts +67 -25
  91. package/src/state.ts +246 -125
  92. package/src/sync-scheduler.ts +31 -1
  93. package/src/transport.ts +21 -2
  94. package/src/wasm-database.ts +76 -27
  95. package/src/window.ts +55 -134
  96. package/src/worker-core.ts +97 -77
  97. package/src/worker-host.ts +76 -32
  98. package/src/worker-local-authority.ts +2 -5
  99. package/src/worker-protocol.ts +14 -10
package/README.md CHANGED
@@ -14,9 +14,9 @@ server-authoritative commands, and live query watches through the remote
14
14
  operation transport. See [remote server operations](https://syncular.dev/guide-remote-operations/).
15
15
  Its schema and sync transport are optional for query-only or command-only
16
16
  processes.
17
- Ordinary commits use wire version 1 until the caller supplies an acquired
18
- partition `logEpoch`. Set `logEpoch` after a restore rotation requires epoch
19
- validation.
17
+ Without a `logEpoch`, the first `prepareCommit` sends one empty pull to learn
18
+ the partition log epoch and binds every later commit to it; set `logEpoch` in
19
+ the constructor to skip that round.
20
20
 
21
21
  Applied and cached acknowledgements drain the send queue while protected local
22
22
  intent stays visible until the same row's server image arrives at that commit
@@ -75,7 +75,7 @@ if (handle.role === 'follower') {
75
75
  // Another tab owns the core for this origin. The default multi-tab mode
76
76
  // transparently proxies this handle to that leader.
77
77
  }
78
- await handle.subscribe({ id: 'todos', table: 'todos', scopes: { list_id: ['l1'] } });
78
+ await handle.subscribe({ list_id: 'l1' });
79
79
  await handle.syncUntilIdle();
80
80
  const rows = await handle.query('SELECT * FROM todos');
81
81
  ```
@@ -132,7 +132,7 @@ persists, on purpose, and that is the only main-thread mode.
132
132
 
133
133
  ## Supported realtime lifecycle
134
134
 
135
- Register subscriptions, then install the cross-host supervisor:
135
+ Register units, then install the cross-host supervisor:
136
136
 
137
137
  ```ts
138
138
  import {
@@ -141,7 +141,7 @@ import {
141
141
  installRealtimeSupervisor,
142
142
  } from '@syncular/client';
143
143
 
144
- await handle.subscribe({ id: 'todos', table: 'todos', scopes });
144
+ await handle.subscribe({ list_id: 'groceries' });
145
145
  installRealtimeSupervisor(handle, {
146
146
  connectivity: browserConnectivitySignal(),
147
147
  lifecycle: documentLifecycleSignal(),
@@ -315,8 +315,8 @@ stable code-like values (`A-Z`, `a-z`, `0-9`, dot, underscore, dash).
315
315
  During Vite development, retain the React client resource only while its
316
316
  captured generated schema version and published Syncular runtime identity both
317
317
  match. The
318
- [schema-and-runtime-aware Vite guide](https://syncular.dev/platform-web-install/#configure-vite) uses
319
- `retainViteSyncClientResource` to close the old worker before constructing a
318
+ [schema-and-runtime-aware Vite guide](https://syncular.dev/platform-web-realtime/#keep-one-owner-during-hmr) uses
319
+ `createViteSyncClientResource` to close the old worker before constructing a
320
320
  schema-bump or package-upgrade replacement; hot-reloading query code alone does
321
321
  not migrate the worker-owned database.
322
322
 
@@ -387,20 +387,18 @@ loading state.
387
387
  Every direct and Worker/multi-tab client exposes the same versioned snapshot:
388
388
 
389
389
  ```ts
390
- const snapshot = await client.diagnosticsSnapshot({
391
- expectedSubscriptions: [
392
- { id: 'membership-security', table: 'facility_memberships' },
393
- { id: 'scheduler-window', table: 'surgeries' },
394
- ],
395
- });
390
+ const snapshot = await client.diagnosticsSnapshot();
391
+ // snapshot.version === 2; snapshot.units, snapshot.activeUnits, snapshot.replicaCursor
396
392
 
397
393
  const off = client.onDiagnostics(() => refreshSupportView());
398
394
  ```
399
395
 
400
- `expectedSubscriptions` contains application intent only—stable PHI-free ids
401
- and generated table names, never scopes. It lets a support screen distinguish
402
- an absent registration from a legitimate zero-row completed bootstrap. The
403
- snapshot also distinguishes reset, revocation, failure, schema floor, lease
396
+ `units` counts the registered units per state (`bootstrapping`, `complete`,
397
+ `reset`, `revoked`, `failed`) with their distinct reason codes; `activeUnits`
398
+ is the number of units the next registration list carries, which the server's
399
+ `maxSubscriptionsPerRequest` counts; `replicaCursor` is the replica cursor,
400
+ `-1` while no unit is live. A unit id is a hash of scope values, so no unit id
401
+ enters the snapshot. The snapshot also distinguishes schema floor, lease
404
402
  stop, pending outbox, offline transport, and storage pressure/unreadability.
405
403
  Failed progress and `lastRound` diagnostics expose an optional bounded
406
404
  `causeKind` and HTTP status. Worker leaders and followers receive the same
@@ -417,8 +415,8 @@ role.
417
415
  The contract intentionally excludes scope values, rows and clinical row
418
416
  counts, SQL, paths, client/actor/lease ids, auth, keys, mutation bodies, stack
419
417
  traces, and arbitrary prose. It is safe to copy the JSON snapshot into a
420
- redacted support ticket as long as the application also keeps subscription ids
421
- free of patient/user data. Do not attach database files, console dumps, query
418
+ redacted support ticket as long as the application keeps query owner ids free
419
+ of patient/user data. Do not attach database files, console dumps, query
422
420
  results, or app state alongside it. See SPEC §7.6.
423
421
 
424
422
  ## Durable commit outcomes
@@ -480,7 +478,8 @@ security purge erase the retained aggregate's protected journal payloads.
480
478
  - `maxPushOperationsPerRequest`: operations across those commits. Default:
481
479
  500.
482
480
  - `maxPushRequestBytes`: bytes of the complete encoded SSP2 request, including
483
- the request header, pull header, subscriptions, framing, and E2EE ciphertext.
481
+ the request header, pull header, unit and progress frames, framing, and E2EE
482
+ ciphertext.
484
483
  Default: unbounded.
485
484
 
486
485
  The client sends whole commits in FIFO order and never splits one. A later
@@ -512,13 +511,13 @@ const result = await client.purgeLocalData({
512
511
  ```
513
512
 
514
513
  The host MUST first quarantine the affected feature and gate/remove any
515
- subscription that could download the protected rows again. This method does
514
+ unit that could download the protected rows again. This method does
516
515
  not authenticate a directive, revoke server authority, delete app-owned files,
517
516
  or remove a key from the OS secure store.
518
517
 
519
518
  For a race-free bootstrap, construct the client/worker handle with
520
519
  `securityPreflight: true`. Before activation, protected reads, writes,
521
- subscriptions, sync/realtime, blobs, and the automatic host loop fail with
520
+ unit registrations, sync/realtime, blobs, and the automatic host loop fail with
522
521
  `client.security_preflight_required`; status, local revision, lifecycle, and
523
522
  the exact local purge remain available.
524
523
 
@@ -552,10 +551,10 @@ counts only—never row ids or selector values.
552
551
 
553
552
  `rebootstrapLocalData({ rebootstrapId })` is the recovery primitive for a
554
553
  locally damaged or persistently inconsistent replicated projection. It drops
555
- and recreates only Syncular's server-derived tables, rewinds the existing
556
- subscription registrations, and requests a fresh bootstrap. It preserves the
557
- client id, lease state, pending outbox commits, commit outcomes, subscription
558
- intent, and protected bookkeeping.
554
+ and recreates only Syncular's server-derived tables, rewinds every registered
555
+ unit to cursor `-1`, and requests a fresh bootstrap. It preserves the client
556
+ id, lease state, pending outbox commits, commit outcomes, the registration
557
+ list, and protected bookkeeping.
559
558
 
560
559
  ```ts
561
560
  const result = await client.rebootstrapLocalData({
@@ -710,7 +709,8 @@ const client = new SyncClient({ database, schema, /* … */ });
710
709
  ```
711
710
 
712
711
  The export selects `bun:sqlite` on Bun and the built-in `node:sqlite` module on
713
- Node 22.13 or newer. No SQLite package or native addon is required. Both
712
+ Node 22.16 or newer. On an older Node, `openNodeDatabase()` throws
713
+ `client.storage_unavailable`. No SQLite package or native addon is required. Both
714
714
  adapters support synchronous `exec`, `query`, nested transactions, boolean
715
715
  bindings, `null`, `Uint8Array` BLOB values, and §5.3 SQLite-image attachment.
716
716
 
@@ -740,8 +740,8 @@ bun run build:packages && bun run verify:packages
740
740
 
741
741
  `init`, `call`, `ready`, `result`, `error`, `event` — every API method
742
742
  multiplexes over `call` (typed end-to-end from the single `WorkerApi`
743
- shape in `worker-protocol.ts`); `event` carries `sync-needed`,
744
- `change`, `conflict` and `synced`. Query-result blobs transfer (not copy) when
743
+ shape in `worker-protocol.ts`); `event` carries `progress`, `sync-needed`,
744
+ `conflict`, `synced`, `upgrading`, `presence`, `change` and `diagnostics`. Query-result blobs transfer (not copy) when
745
745
  they own their buffer.
746
746
 
747
747
  ## Package layout
@@ -779,7 +779,7 @@ bun run test:browser
779
779
 
780
780
  Each case reloads the page using the same replica identity and requires successful
781
781
  startup in the same browser session. It checks SQLite and FTS integrity, search
782
- results, exact rows, persisted client identity, and subscription checkpoints.
782
+ results, exact rows, persisted client identity, and unit checkpoints.
783
783
  Incomplete sections must download again; completed sections must not. A held
784
784
  synchronous test request after a physical page write keeps the mid-import crash
785
785
  boundary stable until worker termination. Two additional ownership cases verify
@@ -830,7 +830,7 @@ stop();
830
830
  ```
831
831
 
832
832
  Each snapshot identifies the round with `attempt`, and the current payload with
833
- `subscriptionId`, `table`, and optional `segmentId`. Counters reset for each
833
+ `unitId`, `table`, and optional `segmentId`. Counters reset for each
834
834
  payload; `syncUntilIdle` starts a new attempt for each round. `phase` is `request`,
835
835
  `download`, or `import`; `state` is `running`, `complete`, or `failed`. Unknown
836
836
  totals remain absent. A new attempt clears prior errors and counters.
@@ -846,7 +846,7 @@ inside the current transaction; a failed import can roll those rows back. SQLite
846
846
  images commit in chunks of at most 1,024 rows and yield after each commit.
847
847
  Earlier committed chunks survive a later interruption. `complete` follows checkpoint persistence
848
848
  and optimistic-state reconciliation for the round. More bootstrap pages can
849
- remain; use subscription coverage to determine whether a query is complete.
849
+ remain; use window coverage to determine whether a query is complete.
850
850
  Listener exceptions do not fail sync. Listeners should hand UI work off and avoid
851
851
  reentering database commands during an import.
852
852
 
@@ -916,7 +916,7 @@ creation to enable the zero-argument `authoritySnapshot()`. It reads approved
916
916
  plain authority columns and accepted bases with revision and persisted scope
917
917
  coverage from one SQLite snapshot, including during security preflight.
918
918
  Unaccepted local intent remains separate. The read changes no keys, transport,
919
- subscriptions or lifecycle. See the [authority contract](../../docs/SPEC.md)
919
+ units or lifecycle. See the [authority contract](../../docs/SPEC.md)
920
920
  and [native configuration](../tauri/README.md#authority-evidence-before-activation).
921
921
 
922
922
  Workers must opt in in their entry script:
package/dist/apply.d.ts CHANGED
@@ -7,15 +7,16 @@ import { type OverlayScope } from './failed-overlay.js';
7
7
  import { type CommitFrame, type RowsSegment, type RowValue, type ScopeMap } from '@syncular/core';
8
8
  import type { ClientDatabase } from './database.js';
9
9
  import type { EncryptionConfig } from './encryption.js';
10
- import { type CompiledClientSchema, type CompiledClientTable } from './schema.js';
10
+ import { type CompiledClientSchema, type CompiledClientTable, type JsonRowValue } from './schema.js';
11
11
  /** Lets the client wrap the physical write in its revision transaction. */
12
12
  export type ApplyTransaction = (fn: () => OverlayScope) => unknown;
13
13
  export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number, serverWrite?: boolean): void;
14
14
  export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClientTable, rowId: string, serverWrite?: boolean): void;
15
15
  /**
16
- * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4).
17
- * Upserts land with `_sync_version = rowVersion`; deletes remove the row.
18
- * Re-application is idempotent (§1.4 rule 5).
16
+ * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4) under the
17
+ * §4.5 version guard: a change lands only when its `rowVersion` exceeds the
18
+ * local row's `_sync_version`. Upserts land with `_sync_version = rowVersion`;
19
+ * deletes remove the row. Re-application changes nothing.
19
20
  *
20
21
  * §5.11: encrypted columns are decrypted here — the apply seam. Because
21
22
  * WebCrypto is async and the local transaction is synchronous, every row is
@@ -32,28 +33,33 @@ export declare function applyCommitFrame(db: ClientDatabase, schema: CompiledCli
32
33
  */
33
34
  export declare function validateSegmentColumns(schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment): void;
34
35
  /**
35
- * Scope-matched local delete (§3.3 purge / §5.6 first-page rule): delete
36
- * rows whose generated local scope columns match `effective` — every key's
37
- * column value must be in the key's value list. Fails closed
38
- * (`sync.scope_revoked`) when the table has no local mapping for a key:
39
- * precision or nothing, never clear-the-table.
36
+ * Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
37
+ * rule): delete rows whose generated local scope columns match `effective`
38
+ * (every key's column value must be in the key's value list) and that no
39
+ * entry of `owners` matches. `owners` holds the effective scopes of every
40
+ * other active subscription on the table that holds rows; a row one of them
41
+ * still covers is never removed. Fails closed (`sync.scope_revoked`) when
42
+ * the table has no local mapping for a key: precision or nothing, never
43
+ * clear-the-table.
40
44
  */
41
- export declare function localScopePredicate(table: CompiledClientTable, effective: ScopeMap): {
45
+ export declare function localScopePredicate(table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[]): {
42
46
  sql: string;
43
47
  params: string[];
44
48
  } | undefined;
45
- export declare function deleteScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap): void;
49
+ /** {@link localScopePredicate} over decoded row values (retained rows). */
50
+ export declare function ownsLocalRow(table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[], values: Readonly<Record<string, JsonRowValue>>): boolean;
51
+ export declare function deleteScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[]): void;
46
52
  /**
47
53
  * §4.8 window eviction: delete rows matching a departing unit's effective
48
- * scopes (same local-scope-column rule and fail-closed clause as
49
- * {@link deleteScopedRows}) EXCEPT rows whose primary key is in
54
+ * scopes (same local-scope-column rule, owner exclusion and fail-closed
55
+ * clause as {@link deleteScopedRows}) EXCEPT rows whose primary key is in
50
56
  * `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
51
57
  * whether unpinned work remains and whether any scoped rows remain. Each
52
58
  * call removes at most 1,024 rows; the caller commits before yielding. Also removes the
53
59
  * evicted rows' `server_version` with them (E2 — no residual version
54
60
  * cache), which is automatic since the version column is per-row.
55
61
  */
56
- export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, pinnedRowIds: ReadonlySet<string>): {
62
+ export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[], pinnedRowIds: ReadonlySet<string>): {
57
63
  remaining: boolean;
58
64
  deferred: boolean;
59
65
  };
@@ -75,6 +81,8 @@ export interface SqliteSegmentDescriptor {
75
81
  export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, bytes: Uint8Array, descriptor: SqliteSegmentDescriptor, options: {
76
82
  readonly clearFirst: boolean;
77
83
  readonly effective: ScopeMap;
84
+ /** Pair scopes of the units that own rows of the table (§3.3). */
85
+ readonly owners: readonly ScopeMap[];
78
86
  readonly transaction?: ApplyTransaction;
79
87
  readonly onProgress?: (rowsProcessed: number) => void;
80
88
  readonly isCurrent?: () => boolean;
@@ -90,6 +98,8 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
90
98
  export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment, options: {
91
99
  readonly clearFirst: boolean;
92
100
  readonly effective: ScopeMap;
101
+ /** Pair scopes of the units that own rows of the table (§3.3). */
102
+ readonly owners: readonly ScopeMap[];
93
103
  readonly transaction?: ApplyTransaction;
94
104
  readonly onProgress?: (rowsProcessed: number) => void;
95
105
  readonly isCurrent?: () => boolean;
package/dist/apply.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { hasUniqueIndex } from './schema.js';
2
- import { OUTBOX_TABLE, OUTBOX_IMAGES, countOutbox } from './outbox.js';
2
+ import { OUTBOX_IMAGES, countOutbox } from './outbox.js';
3
3
  import { RETAINED_ROWS } from './failed-overlay.js';
4
4
  import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
5
5
  /**
@@ -36,9 +36,29 @@ export function deleteLocalRow(db, table, rowId, serverWrite = true) {
36
36
  db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, rowId)]);
37
37
  }
38
38
  /**
39
- * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4).
40
- * Upserts land with `_sync_version = rowVersion`; deletes remove the row.
41
- * Re-application is idempotent (§1.4 rule 5).
39
+ * §4.5 version guard for one server row: whether a write at `version` lands.
40
+ * A skipped row keeps its overlay, so its key leaves the rebase scope unless a
41
+ * retained base was restored for it; `kept` and `skipped` collect the keys.
42
+ */
43
+ function lands(db, table, rowId, version, kept, skipped) {
44
+ const key = JSON.stringify([table.name, rowId]);
45
+ const local = db.query(`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)}=?`, [table.name, rowId, pkSqlValue(table, rowId)])[0];
46
+ const land = local === undefined || Number(local.v) < version;
47
+ if (land || local.retained)
48
+ kept.add(key);
49
+ else
50
+ skipped.add(key);
51
+ return land;
52
+ }
53
+ /** The scope a guarded write leaves for the overlay replay. */
54
+ function rebaseScope(scope, kept, skipped) {
55
+ return scope.filter((key) => kept.has(key) || !skipped.has(key));
56
+ }
57
+ /**
58
+ * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4) under the
59
+ * §4.5 version guard: a change lands only when its `rowVersion` exceeds the
60
+ * local row's `_sync_version`. Upserts land with `_sync_version = rowVersion`;
61
+ * deletes remove the row. Re-application changes nothing.
42
62
  *
43
63
  * §5.11: encrypted columns are decrypted here — the apply seam. Because
44
64
  * WebCrypto is async and the local transaction is synchronous, every row is
@@ -59,41 +79,44 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
59
79
  throw new ClientSyncError('sync.schema_mismatch', `COMMIT delivers unknown local table ${JSON.stringify(tableName)}`);
60
80
  }
61
81
  if (change.op === 'delete') {
62
- resolved.push({ op: 'delete', table, rowId: change.rowId });
82
+ resolved.push({ op: 'delete', table });
63
83
  continue;
64
84
  }
65
- if (change.row === undefined || change.rowVersion === undefined) {
85
+ if (change.row === undefined) {
66
86
  throw invalidRequest('upsert change without row payload');
67
87
  }
68
88
  let values = decodeRow(table.columns, change.row);
69
- if (encryption !== undefined && table.hasEncryptedColumns) {
89
+ if (table.hasEncryptedColumns) {
70
90
  const { decryptRowValues } = await import('./encryption.js');
71
91
  values = await decryptRowValues(encryption, table, values);
72
92
  }
73
- resolved.push({
74
- op: 'upsert',
75
- table,
76
- values,
77
- rowVersion: change.rowVersion,
78
- });
93
+ resolved.push({ op: 'upsert', table, values });
79
94
  }
80
95
  transaction(() => {
81
- const scope = resolved.map((change, index) => JSON.stringify(hasUniqueIndex(change.table)
82
- ? [change.table.name]
83
- : [change.table.name, frame.changes[index].rowId]));
96
+ // Exact keys name the rows this frame rebases; unique-key peers widen the
97
+ // replay to the table.
98
+ const scope = resolved.flatMap((change, index) => [
99
+ ...(hasUniqueIndex(change.table)
100
+ ? [JSON.stringify([change.table.name])]
101
+ : []),
102
+ JSON.stringify([change.table.name, frame.changes[index].rowId]),
103
+ ]);
84
104
  restoreFailedBases(db, schema, scope);
105
+ const kept = new Set();
106
+ const skipped = new Set();
85
107
  for (const [index, change] of resolved.entries()) {
86
- const rowId = frame.changes[index].rowId;
87
- db.exec(`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE (client_commit_id,op_index) IN(SELECT client_commit_id,json_each.key FROM ${OUTBOX_TABLE},json_each(operations) WHERE json_extract(value,'$.table')=? AND json_extract(value,'$.rowId')=?)`, [frame.commitSeq, change.table.name, rowId]);
108
+ const { rowId, rowVersion } = frame.changes[index];
109
+ const land = lands(db, change.table, rowId, rowVersion, kept, skipped);
110
+ db.exec(`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`, [frame.commitSeq, change.table.name, rowId]);
88
111
  db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [change.table.name, rowId, frame.commitSeq]);
89
- if (change.op === 'delete') {
90
- deleteLocalRow(db, change.table, change.rowId);
91
- }
92
- else {
93
- upsertLocalRow(db, change.table, change.values, change.rowVersion);
94
- }
112
+ if (!land)
113
+ continue;
114
+ if (change.op === 'delete')
115
+ deleteLocalRow(db, change.table, rowId);
116
+ else
117
+ upsertLocalRow(db, change.table, change.values, rowVersion);
95
118
  }
96
- return scope;
119
+ return rebaseScope(scope, kept, skipped);
97
120
  });
98
121
  }
99
122
  /**
@@ -127,13 +150,16 @@ export function validateSegmentColumns(schema, table, segment) {
127
150
  }
128
151
  }
129
152
  /**
130
- * Scope-matched local delete (§3.3 purge / §5.6 first-page rule): delete
131
- * rows whose generated local scope columns match `effective` — every key's
132
- * column value must be in the key's value list. Fails closed
133
- * (`sync.scope_revoked`) when the table has no local mapping for a key:
134
- * precision or nothing, never clear-the-table.
153
+ * Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
154
+ * rule): delete rows whose generated local scope columns match `effective`
155
+ * (every key's column value must be in the key's value list) and that no
156
+ * entry of `owners` matches. `owners` holds the effective scopes of every
157
+ * other active subscription on the table that holds rows; a row one of them
158
+ * still covers is never removed. Fails closed (`sync.scope_revoked`) when
159
+ * the table has no local mapping for a key: precision or nothing, never
160
+ * clear-the-table.
135
161
  */
136
- export function localScopePredicate(table, effective) {
162
+ export function localScopePredicate(table, effective, owners) {
137
163
  const entries = Object.entries(effective);
138
164
  if (!entries.length || entries.some(([, values]) => !values.length))
139
165
  return;
@@ -147,25 +173,37 @@ export function localScopePredicate(table, effective) {
147
173
  return `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`;
148
174
  })
149
175
  .join(' AND ');
150
- return { sql, params };
176
+ const kept = owners.flatMap((owner) => {
177
+ const scope = localScopePredicate(table, owner, []);
178
+ if (scope === undefined)
179
+ return [];
180
+ params.push(...scope.params);
181
+ return [` AND NOT (${scope.sql})`];
182
+ });
183
+ return { sql: sql + kept.join(''), params };
184
+ }
185
+ /** {@link localScopePredicate} over decoded row values (retained rows). */
186
+ export function ownsLocalRow(table, effective, owners, values) {
187
+ return (matchesLocalScopes(table, effective, values) &&
188
+ !owners.some((owner) => matchesLocalScopes(table, owner, values)));
151
189
  }
152
190
  function scopedRows(db, table, scope) {
153
191
  return scope
154
192
  ? db.query(`SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${scope.sql}`, scope.params)
155
193
  : [];
156
194
  }
157
- function bootstrapScope(db, table, effective) {
158
- const rows = scopedRows(db, table, localScopePredicate(table, effective));
195
+ function bootstrapScope(db, table, effective, owners) {
196
+ const rows = scopedRows(db, table, localScopePredicate(table, effective, owners));
159
197
  rows.push(...db
160
198
  .query(`SELECT id,base,intent FROM ${RETAINED_ROWS} WHERE tbl=?`, [
161
199
  table.name,
162
200
  ])
163
201
  .filter((row) => [row.base, row.intent].some((json) => json !== null &&
164
- matchesLocalScopes(table, effective, JSON.parse(json)))));
202
+ ownsLocalRow(table, effective, owners, JSON.parse(json)))));
165
203
  return rows.map((row) => JSON.stringify([table.name, String(row.id)]));
166
204
  }
167
- export function deleteScopedRows(db, table, effective) {
168
- const scope = localScopePredicate(table, effective);
205
+ export function deleteScopedRows(db, table, effective, owners) {
206
+ const scope = localScopePredicate(table, effective, owners);
169
207
  if (!scope)
170
208
  return;
171
209
  const { sql, params } = scope;
@@ -176,16 +214,16 @@ export function deleteScopedRows(db, table, effective) {
176
214
  }
177
215
  /**
178
216
  * §4.8 window eviction: delete rows matching a departing unit's effective
179
- * scopes (same local-scope-column rule and fail-closed clause as
180
- * {@link deleteScopedRows}) EXCEPT rows whose primary key is in
217
+ * scopes (same local-scope-column rule, owner exclusion and fail-closed
218
+ * clause as {@link deleteScopedRows}) EXCEPT rows whose primary key is in
181
219
  * `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
182
220
  * whether unpinned work remains and whether any scoped rows remain. Each
183
221
  * call removes at most 1,024 rows; the caller commits before yielding. Also removes the
184
222
  * evicted rows' `server_version` with them (E2 — no residual version
185
223
  * cache), which is automatic since the version column is per-row.
186
224
  */
187
- export function evictScopedRows(db, table, effective, pinnedRowIds) {
188
- const scope = localScopePredicate(table, effective);
225
+ export function evictScopedRows(db, table, effective, owners, pinnedRowIds) {
226
+ const scope = localScopePredicate(table, effective, owners);
189
227
  if (!scope)
190
228
  return { remaining: false, deferred: false };
191
229
  const { sql, params } = scope;
@@ -200,7 +238,7 @@ export function evictScopedRows(db, table, effective, pinnedRowIds) {
200
238
  for (const row of db.query(`SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl=?`, [table.name])) {
201
239
  if (!pinnedRowIds.has(row.id) &&
202
240
  [row.intent, row.base].some((json) => json !== null &&
203
- matchesLocalScopes(table, effective, JSON.parse(json))))
241
+ ownsLocalRow(table, effective, owners, JSON.parse(json))))
204
242
  db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq IS NOT NULL`, [table.name, row.id]);
205
243
  }
206
244
  db.exec(`DELETE FROM ${target} WHERE ${pk} IN(SELECT ${pk} FROM ${target} WHERE ${sql}${pinnedClause} LIMIT 1024)`, params);
@@ -229,6 +267,10 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
229
267
  if (descriptor.table !== table.name) {
230
268
  imageInvalid(`descriptor table ${JSON.stringify(descriptor.table)}`);
231
269
  }
270
+ // §5.11: an image bypasses the decrypt seam, so a server cannot serve one
271
+ // for a table with encrypted columns.
272
+ if (table.hasEncryptedColumns)
273
+ imageInvalid('table has encrypted columns');
232
274
  return withImage(bytes, IMAGE_ALIAS, async () => {
233
275
  // 1. Metadata vs descriptor (§5.3 rule 2). A file that is not a
234
276
  // SQLite database or lacks the metadata table fails right here.
@@ -286,6 +328,7 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
286
328
  .filter((name) => name !== primaryKey)
287
329
  .map((name) => `${name}=excluded.${name}`)
288
330
  .join(', ');
331
+ const version = quoteIdent(SYNC_VERSION_COLUMN);
289
332
  let after;
290
333
  let applied = 0;
291
334
  for (;;) {
@@ -314,27 +357,30 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
314
357
  (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
315
358
  const scope = !replay
316
359
  ? []
317
- : hasUniqueIndex(table)
318
- ? [JSON.stringify([table.name])]
319
- : [
320
- ...(after === undefined && options.clearFirst
321
- ? bootstrapScope(db, table, options.effective)
322
- : []),
323
- ...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
324
- ];
360
+ : [
361
+ ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
362
+ ...(after === undefined && options.clearFirst
363
+ ? bootstrapScope(db, table, options.effective, options.owners)
364
+ : []),
365
+ ...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
366
+ ];
325
367
  const protectedRows = restoreFailedBases(db, schema, scope);
326
368
  if (after === undefined && options.clearFirst)
327
- deleteScopedRows(db, table, options.effective);
328
- db.exec(`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}`, params);
329
- applied += Number(db.query('SELECT changes()AS n')[0]?.n ?? 0);
369
+ deleteScopedRows(db, table, options.effective, options.owners);
370
+ const kept = new Set();
371
+ const skipped = new Set();
372
+ const landing = rows.filter((row) => lands(db, table, String(row[table.primaryKey]), Number(row._syncular_version), kept, skipped));
373
+ const where = predicates.join(' AND ') || 'true';
374
+ db.exec(`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}`, params);
375
+ applied += Number(db.query(`SELECT count(*)AS n FROM ${source} WHERE ${where}`, params)[0]?.n);
330
376
  if (protectedRows)
331
- for (const row of rows) {
377
+ for (const row of landing) {
332
378
  retainedBaseWrite(db, table, String(row[table.primaryKey]), Object.fromEntries(table.columns.map((column) => [
333
379
  column.name,
334
380
  rowValueToJson(row[column.name]),
335
381
  ])), Number(row._syncular_version));
336
382
  }
337
- return scope;
383
+ return rebaseScope(scope, kept, skipped);
338
384
  });
339
385
  options.onProgress?.(applied);
340
386
  await yieldToHost();
@@ -368,7 +414,7 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
368
414
  // aborts before any write in this block.
369
415
  const rows = [];
370
416
  for (const row of block) {
371
- const values = encryption !== undefined && table.hasEncryptedColumns
417
+ const values = table.hasEncryptedColumns
372
418
  ? await (async () => {
373
419
  const { decryptRowValues } = await import('./encryption.js');
374
420
  return decryptRowValues(encryption, table, row.values);
@@ -383,28 +429,31 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
383
429
  if (!clearThisBlock && rows.length === 0)
384
430
  continue;
385
431
  (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
386
- const scope = hasUniqueIndex(table)
387
- ? [JSON.stringify([table.name])]
388
- : [
389
- ...(clearThisBlock
390
- ? bootstrapScope(db, table, options.effective)
391
- : []),
392
- ...rows.map((row) => JSON.stringify([
393
- table.name,
394
- String(row.values[table.primaryKeyIndex]),
395
- ])),
396
- ];
432
+ const scope = [
433
+ ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
434
+ ...(clearThisBlock
435
+ ? bootstrapScope(db, table, options.effective, options.owners)
436
+ : []),
437
+ ...rows.map((row) => JSON.stringify([
438
+ table.name,
439
+ String(row.values[table.primaryKeyIndex]),
440
+ ])),
441
+ ];
397
442
  const protectedRows = restoreFailedBases(db, schema, scope);
398
443
  if (clearThisBlock) {
399
- deleteScopedRows(db, table, options.effective);
444
+ deleteScopedRows(db, table, options.effective, options.owners);
400
445
  }
446
+ const kept = new Set();
447
+ const skipped = new Set();
401
448
  for (const row of rows) {
402
- upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
449
+ const rowId = String(row.values[table.primaryKeyIndex]);
450
+ if (lands(db, table, rowId, row.serverVersion, kept, skipped))
451
+ upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
403
452
  applied += 1;
404
453
  if (applied % 1024 === 0)
405
454
  options.onProgress?.(applied);
406
455
  }
407
- return scope;
456
+ return rebaseScope(scope, kept, skipped);
408
457
  });
409
458
  options.onProgress?.(applied);
410
459
  await yieldToHost();