@syncular/client 0.58.0 → 0.59.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 (82) hide show
  1. package/README.md +7 -7
  2. package/dist/apply.d.ts +20 -11
  3. package/dist/apply.js +67 -45
  4. package/dist/blob.d.ts +17 -9
  5. package/dist/blob.js +5 -6
  6. package/dist/bun-database.d.ts +1 -0
  7. package/dist/bun-database.js +28 -0
  8. package/dist/client.d.ts +27 -10
  9. package/dist/client.js +357 -190
  10. package/dist/database.d.ts +5 -0
  11. package/dist/encryption.d.ts +2 -2
  12. package/dist/encryption.js +8 -2
  13. package/dist/errors.d.ts +2 -0
  14. package/dist/errors.js +4 -0
  15. package/dist/failed-overlay.d.ts +0 -1
  16. package/dist/failed-overlay.js +3 -6
  17. package/dist/http.d.ts +4 -1
  18. package/dist/http.js +61 -39
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +1 -1
  21. package/dist/invalidation.d.ts +11 -10
  22. package/dist/invalidation.js +15 -26
  23. package/dist/local-purge.js +9 -12
  24. package/dist/local-rebootstrap.js +2 -2
  25. package/dist/multi-tab.d.ts +89 -1
  26. package/dist/multi-tab.js +70 -31
  27. package/dist/native-bridge.d.ts +235 -0
  28. package/dist/native-bridge.js +789 -0
  29. package/dist/node-database.d.ts +1 -0
  30. package/dist/node-database.js +29 -0
  31. package/dist/outbox.d.ts +9 -12
  32. package/dist/outbox.js +19 -36
  33. package/dist/outcomes.js +3 -3
  34. package/dist/previous-version.js +96 -114
  35. package/dist/query-guard.d.ts +25 -24
  36. package/dist/query-guard.js +34 -191
  37. package/dist/reactive-store.js +53 -11
  38. package/dist/realtime-supervisor.d.ts +9 -2
  39. package/dist/realtime-supervisor.js +31 -7
  40. package/dist/remote.js +11 -15
  41. package/dist/schema.js +15 -10
  42. package/dist/sync-scheduler.js +28 -2
  43. package/dist/transport.d.ts +19 -4
  44. package/dist/wasm-database.js +58 -21
  45. package/dist/worker-core.d.ts +5 -0
  46. package/dist/worker-core.js +80 -72
  47. package/dist/worker-host.d.ts +10 -5
  48. package/dist/worker-host.js +64 -7
  49. package/dist/worker-local-authority.js +2 -2
  50. package/dist/worker-protocol.d.ts +6 -2
  51. package/package.json +11 -3
  52. package/src/apply.ts +91 -55
  53. package/src/blob.ts +27 -15
  54. package/src/bun-database.ts +29 -0
  55. package/src/client.ts +477 -261
  56. package/src/database.ts +5 -0
  57. package/src/encryption.ts +10 -5
  58. package/src/errors.ts +8 -0
  59. package/src/failed-overlay.ts +3 -7
  60. package/src/http.ts +90 -79
  61. package/src/index.ts +1 -1
  62. package/src/invalidation.ts +17 -32
  63. package/src/local-purge.ts +11 -13
  64. package/src/local-rebootstrap.ts +2 -3
  65. package/src/multi-tab.ts +88 -30
  66. package/src/native-bridge.ts +1189 -0
  67. package/src/node-database.ts +32 -0
  68. package/src/outbox.ts +19 -41
  69. package/src/outcomes.ts +3 -5
  70. package/src/previous-version.ts +103 -114
  71. package/src/query-guard.ts +43 -180
  72. package/src/reactive-store.ts +50 -10
  73. package/src/realtime-supervisor.ts +37 -12
  74. package/src/remote.ts +12 -16
  75. package/src/schema.ts +19 -12
  76. package/src/sync-scheduler.ts +31 -1
  77. package/src/transport.ts +21 -2
  78. package/src/wasm-database.ts +76 -27
  79. package/src/worker-core.ts +94 -74
  80. package/src/worker-host.ts +63 -16
  81. package/src/worker-local-authority.ts +2 -5
  82. package/src/worker-protocol.ts +6 -2
@@ -1,3 +1,76 @@
1
+ /**
2
+ * Multi-tab followers: one core per origin, N tabs.
3
+ *
4
+ * The leader tab holds the Web Locks lease and runs the worker core (the
5
+ * existing worker-host path, unchanged). Every OTHER tab is a FOLLOWER: it
6
+ * loses the lock election and, instead of a dead not-leader handle, opens a
7
+ * BroadcastChannel to the leader and proxies the whole logical API over it —
8
+ * one sync loop, one WebSocket, one DB, N tabs.
9
+ *
10
+ * Wire (all messages structured-clone-safe; `Set`/`Uint8Array`/`ArrayBuffer`
11
+ * survive `postMessage` on a BroadcastChannel):
12
+ *
13
+ * follower → leader
14
+ * hello {t,epoch?,fromId,protocol,schemaVersion}
15
+ * — "who's the leader?" on join,
16
+ * and the follower's liveness probe
17
+ * req {t,epoch,fromId,reqId,method,args,protocol,schemaVersion}
18
+ * leader → all
19
+ * announce {t,epoch,clientId,protocol,schemaVersion}
20
+ * — "I am the leader, this epoch";
21
+ * the answer to every hello
22
+ * res {t,epoch,to,reqId,ok,value|error}
23
+ * — reply to one req, for the
24
+ * follower `to` that sent it
25
+ * event {t,epoch,event,to?} — fan-out (invalidate/presence/…),
26
+ * or one tab's event when `to` is set
27
+ *
28
+ * Epoch (leader generation token): a monotonic counter carried in a shared
29
+ * BroadcastChannel and bumped by every promotion. Followers stamp requests
30
+ * with the epoch they last heard in an `announce`; a leader ignores requests
31
+ * from a stale epoch, and a follower discards any `res`/`event` that does not
32
+ * match its current epoch — so a late reply from a tab that has since died
33
+ * (or a duplicate from a previous leader) can never be mistaken for a live
34
+ * one. Every follower counts its `reqId`s from 1, so a follower also discards
35
+ * a `res` whose `to` names another tab. Epoch is derived deterministically
36
+ * from a per-origin clock: each promoter reads the highest epoch it has seen
37
+ * and adds one, so successive leaders always strictly increase it even across
38
+ * the lock-handover gap.
39
+ *
40
+ * Identity: every hello, req, and announce carries the sender's
41
+ * {@link MULTI_TAB_PROTOCOL_VERSION} and application schema version. A leader
42
+ * serves only requests with its own identity. A follower whose leader has a
43
+ * different identity goes `blocked` with `leader-incompatible` and sends it
44
+ * nothing. A leader that hears a hello from a newer tab closes its core and
45
+ * releases the lock, so the newer tab takes over. A newer follower sends one
46
+ * hello to every older leader it hears announce, so an older tab that promotes
47
+ * after the first one stepped down steps down as well. Tabs from before
48
+ * protocol 1 send no identity and count as older.
49
+ *
50
+ * Liveness is follower-driven: the leader runs no timer. Browsers throttle
51
+ * the timers of a hidden tab (Chrome's intensive throttling wakes them about
52
+ * once a minute) but still dispatch its BroadcastChannel messages, so a leader
53
+ * heartbeat misses its schedule in a background leader tab while that tab is
54
+ * alive. Instead, a bound follower that has heard no `announce` for a third of
55
+ * its call timeout posts a `hello`, and goes `blocked` only when that probe
56
+ * stays unanswered for the rest of the timeout. A leader tab whose main thread
57
+ * processes no messages (hung or frozen) therefore still blocks its followers
58
+ * within `callTimeoutMs`, and a closed leader hands over through the lock.
59
+ * A forwarded call has no deadline of its own: a live leader may run it behind
60
+ * a long sync round, exactly as it runs its own tab's calls. It rejects when
61
+ * the link blocks, when another leader announces, or when the link closes.
62
+ *
63
+ * Presence identity: all tabs share the leader's one connection, so a device
64
+ * is exactly ONE presence peer collectively — `(actorId, leaderClientId)`.
65
+ * A follower's `setPresence` forwards to the leader's single publisher; there
66
+ * is no per-tab presence peer (documented in the web-client README).
67
+ *
68
+ * Tab lifetime: every tab of a {@link TabCoordinator} holds an exclusive Web
69
+ * Lock named for its tab id until it closes. A leader whose core keeps per-tab
70
+ * state waits on that lock for each tab that called it; the grant means the
71
+ * tab is gone.
72
+ */
73
+ import { ClientSyncError } from './errors.js';
1
74
  import { type LeaderLease, type LeaderLock } from './leader-lock.js';
2
75
  import type { SyncWorkerEvent } from './worker-protocol.js';
3
76
  /** Client-local: a follower call could not reach a leader before its deadline. */
@@ -15,7 +88,7 @@ export declare const TAKEOVER_REFUSED_CODE = "client.takeover_refused";
15
88
  * with every change to a message shape or to a forwarded method's arguments
16
89
  * or result, so tabs of different builds never serve each other.
17
90
  */
18
- export declare const MULTI_TAB_PROTOCOL_VERSION = 2;
91
+ export declare const MULTI_TAB_PROTOCOL_VERSION = 3;
19
92
  /** What a tab must share with its leader to be served by it. */
20
93
  export interface TabIdentity {
21
94
  readonly protocol: number;
@@ -43,6 +116,19 @@ export type LeadershipState = {
43
116
  } | {
44
117
  readonly state: 'waiting';
45
118
  readonly reason: 'handover' | 'leader-announcement';
119
+ } | {
120
+ /**
121
+ * This tab won the lock after the leader left and its core failed to
122
+ * start. It released the lock and, while `retrying`, asks for it again
123
+ * behind every other waiting tab; after the third failed start it stops
124
+ * contesting and binds to whichever tab leads next.
125
+ */
126
+ readonly state: 'waiting';
127
+ readonly reason: 'leader-start-failed';
128
+ readonly error: ClientSyncError;
129
+ /** Failed starts of this tab's core so far. */
130
+ readonly attempt: number;
131
+ readonly retrying: boolean;
46
132
  } | {
47
133
  readonly state: 'blocked';
48
134
  readonly reason: 'leader-unreachable';
@@ -89,6 +175,8 @@ interface AnnounceMessage extends IdentityFields {
89
175
  interface ResMessage {
90
176
  readonly t: 'res';
91
177
  readonly epoch: number;
178
+ /** The follower that sent the request. */
179
+ readonly to: string;
92
180
  readonly reqId: number;
93
181
  readonly ok: boolean;
94
182
  readonly value?: unknown;
package/dist/multi-tab.js CHANGED
@@ -19,7 +19,9 @@
19
19
  * announce {t,epoch,clientId,protocol,schemaVersion}
20
20
  * — "I am the leader, this epoch";
21
21
  * the answer to every hello
22
- * res {t,epoch,reqId,ok,value|error} — reply to one req
22
+ * res {t,epoch,to,reqId,ok,value|error}
23
+ * — reply to one req, for the
24
+ * follower `to` that sent it
23
25
  * event {t,epoch,event,to?} — fan-out (invalidate/presence/…),
24
26
  * or one tab's event when `to` is set
25
27
  *
@@ -29,17 +31,21 @@
29
31
  * from a stale epoch, and a follower discards any `res`/`event` that does not
30
32
  * match its current epoch — so a late reply from a tab that has since died
31
33
  * (or a duplicate from a previous leader) can never be mistaken for a live
32
- * one. Epoch is derived deterministically from a per-origin clock: each
33
- * promoter reads the highest epoch it has seen and adds one, so successive
34
- * leaders always strictly increase it even across the lock-handover gap.
34
+ * one. Every follower counts its `reqId`s from 1, so a follower also discards
35
+ * a `res` whose `to` names another tab. Epoch is derived deterministically
36
+ * from a per-origin clock: each promoter reads the highest epoch it has seen
37
+ * and adds one, so successive leaders always strictly increase it even across
38
+ * the lock-handover gap.
35
39
  *
36
40
  * Identity: every hello, req, and announce carries the sender's
37
41
  * {@link MULTI_TAB_PROTOCOL_VERSION} and application schema version. A leader
38
42
  * serves only requests with its own identity. A follower whose leader has a
39
43
  * different identity goes `blocked` with `leader-incompatible` and sends it
40
44
  * nothing. A leader that hears a hello from a newer tab closes its core and
41
- * releases the lock, so the newer tab takes over. Tabs from before protocol 1
42
- * send no identity and count as older.
45
+ * releases the lock, so the newer tab takes over. A newer follower sends one
46
+ * hello to every older leader it hears announce, so an older tab that promotes
47
+ * after the first one stepped down steps down as well. Tabs from before
48
+ * protocol 1 send no identity and count as older.
43
49
  *
44
50
  * Liveness is follower-driven: the leader runs no timer. Browsers throttle
45
51
  * the timers of a hidden tab (Chrome's intensive throttling wakes them about
@@ -82,7 +88,7 @@ export const TAKEOVER_REFUSED_CODE = 'client.takeover_refused';
82
88
  * with every change to a message shape or to a forwarded method's arguments
83
89
  * or result, so tabs of different builds never serve each other.
84
90
  */
85
- export const MULTI_TAB_PROTOCOL_VERSION = 2;
91
+ export const MULTI_TAB_PROTOCOL_VERSION = 3;
86
92
  /**
87
93
  * Order a peer's identity against our own: -1 older, 0 same, 1 newer. A peer
88
94
  * from before protocol 1 sends no identity and is older.
@@ -202,6 +208,7 @@ export class LeaderBridge {
202
208
  this.#channel.postMessage({
203
209
  t: 'res',
204
210
  epoch: this.#epoch,
211
+ to: fromId,
205
212
  reqId,
206
213
  ok: false,
207
214
  error: {
@@ -223,6 +230,7 @@ export class LeaderBridge {
223
230
  this.#channel.postMessage({
224
231
  t: 'res',
225
232
  epoch: this.#epoch,
233
+ to: fromId,
226
234
  reqId,
227
235
  ok: true,
228
236
  value,
@@ -247,6 +255,7 @@ export class LeaderBridge {
247
255
  this.#channel.postMessage({
248
256
  t: 'res',
249
257
  epoch: this.#epoch,
258
+ to: fromId,
250
259
  reqId,
251
260
  ok: false,
252
261
  error: shape,
@@ -292,6 +301,8 @@ export class FollowerLink {
292
301
  #nextReqId = 1;
293
302
  #inFlight = new Map();
294
303
  #replayOnHandover;
304
+ /** `epoch:clientId` of every older leader this tab asked to step down. */
305
+ #deposed = new Set();
295
306
  #queue = [];
296
307
  #closed = false;
297
308
  #state = {
@@ -481,6 +492,13 @@ export class FollowerLink {
481
492
  return;
482
493
  const relation = compareTabIdentity(message, this.#identity);
483
494
  if (relation !== 0) {
495
+ // An older leader steps down for this tab's hello. Each one hears it
496
+ // once: an older tab that promotes later is another leader.
497
+ const leader = `${message.epoch}:${message.clientId}`;
498
+ if (relation < 0 && !this.#deposed.has(leader)) {
499
+ this.#deposed.add(leader);
500
+ this.#probe();
501
+ }
484
502
  this.#setIncompatible(relation < 0 ? 'older' : 'newer');
485
503
  return;
486
504
  }
@@ -509,8 +527,9 @@ export class FollowerLink {
509
527
  }
510
528
  if (message.t === 'res') {
511
529
  // Discard a reply for a stale epoch — the leader that produced it is
512
- // gone; the request (if still pending) is being retried elsewhere.
513
- if (message.epoch !== this.#epoch)
530
+ // gone; the request (if still pending) is being retried elsewhere. A
531
+ // reply for another follower carries a `reqId` of that tab's counter.
532
+ if (message.epoch !== this.#epoch || message.to !== this.#fromId)
514
533
  return;
515
534
  const inflight = this.#inFlight.get(message.reqId);
516
535
  if (inflight === undefined)
@@ -631,9 +650,9 @@ export class FollowerLink {
631
650
  });
632
651
  }
633
652
  /**
634
- * The leader runs another build. Send it nothing and stay unbound until a
635
- * leader with this tab's identity announces (a newer leader's own hello
636
- * already asked an older one to step down; see the module comment).
653
+ * The leader runs another build. Send it nothing but the one step-down
654
+ * hello for an older leader, and stay unbound until a leader with this
655
+ * tab's identity announces (see the module comment).
637
656
  */
638
657
  #setIncompatible(leader) {
639
658
  this.#clearReachabilityTimers();
@@ -996,27 +1015,47 @@ export async function createTabCoordinator(config) {
996
1015
  : {}),
997
1016
  });
998
1017
  follower = link;
1018
+ let failedStarts = 0;
999
1019
  // Granted only when the lock is released: the leader's tab closed, or this
1000
1020
  // tab's own failed takeover let go of it.
1001
- void lock.acquire(config.name).then(async (promoted) => {
1002
- if (closed || follower !== link) {
1003
- // Closed, or this tab already leads through takeOver(): promoting would
1004
- // hold the lock forever.
1005
- await promoted.release();
1006
- return;
1007
- }
1008
- // The new leader must exceed every epoch this tab saw, so stale replies
1009
- // and events are discarded everywhere.
1010
- const epoch = link.maxEpochSeen + 1;
1011
- link.unbind();
1012
- try {
1013
- await lead(promoted, epoch, false);
1014
- }
1015
- catch {
1016
- // The core failed to start: release so the next tab tries.
1017
- await promoted.release();
1018
- }
1019
- });
1021
+ const contest = () => {
1022
+ void lock.acquire(config.name).then(async (promoted) => {
1023
+ if (closed || follower !== link) {
1024
+ // Closed, or this tab already leads through takeOver(): promoting
1025
+ // would hold the lock forever.
1026
+ await promoted.release();
1027
+ return;
1028
+ }
1029
+ // The new leader must exceed every epoch this tab saw, so stale replies
1030
+ // and events are discarded everywhere.
1031
+ const epoch = link.maxEpochSeen + 1;
1032
+ link.unbind();
1033
+ try {
1034
+ await lead(promoted, epoch, false);
1035
+ }
1036
+ catch (error) {
1037
+ // Release so the next waiting tab tries, then queue behind it. Three
1038
+ // failed starts stop the contest: a core that fails the same way each
1039
+ // time (a changed worker bundle, an unreadable database) would
1040
+ // otherwise take and drop the lock in a loop while this tab is alone.
1041
+ await promoted.release();
1042
+ failedStarts += 1;
1043
+ const retrying = failedStarts < 3 && !closed;
1044
+ setState({
1045
+ state: 'waiting',
1046
+ reason: 'leader-start-failed',
1047
+ error: error instanceof ClientSyncError
1048
+ ? error
1049
+ : new ClientSyncError(WORKER_FAILED_CODE, 'the core failed to start'),
1050
+ attempt: failedStarts,
1051
+ retrying,
1052
+ });
1053
+ if (retrying)
1054
+ contest();
1055
+ }
1056
+ });
1057
+ };
1058
+ contest();
1020
1059
  // Return bound: an event the leader fans out before binding is dropped.
1021
1060
  try {
1022
1061
  await link.waitUntilBound();
@@ -0,0 +1,235 @@
1
+ /**
2
+ * The command bridge shared by the native hosts: `@syncular/tauri` (the Tauri
3
+ * plugin over IPC) and the React Native binding (the C-ABI core behind a
4
+ * TurboModule). Both drive one Rust core through the driver-protocol command
5
+ * envelope `{method, params}`, so the codec, the security preflight gate, the
6
+ * event fanout, and every command method live here. A host subclass supplies
7
+ * the transport: the generic command, the query fast path, the snapshot read,
8
+ * header replacement, and shutdown.
9
+ *
10
+ * Bytes cross as `{$bytes: hex}` and unsafe SQLite integers as
11
+ * `{$bigint: decimal}`, the convention of the Rust command router. The browser
12
+ * client and worker entries never import this module.
13
+ */
14
+ import { type ClientSnapshotMethods, type CurrentBaseProof, type MutationInput, type PresencePeer, type PromiseMethods, type QueryReadSpec, type QuerySnapshot, type SecurityLifecycle, type SnapshotRead, type SnapshotReadRequest, type SyncClientConfig, type WindowState } from './client.js';
15
+ import type { SqlRow, SqlValue } from './database.js';
16
+ import type { PresenceErrorCode } from '@syncular/core';
17
+ import { type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.js';
18
+ import type { EncryptionKeyringConfig } from './encryption.js';
19
+ import type { ClientChangeListener, InvalidationListener, SyncStatusSnapshot } from './invalidation.js';
20
+ import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
21
+ import { type LocalDataRebootstrapInput, type LocalDataRebootstrapResult } from './local-rebootstrap.js';
22
+ import type { CommitOutcome, CommitOutcomeQuery, ConflictRecord, RejectionRecord, ResolveCommitOutcomeInput } from './outcomes.js';
23
+ import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
24
+ import { type SyncProgress, type SyncProgressListener } from './progress.js';
25
+ import type { WindowBase } from './window.js';
26
+ /** A driver-protocol reply: `{result}` on success or `{error}` on failure. */
27
+ export interface NativeReply {
28
+ readonly result?: unknown;
29
+ readonly error?: {
30
+ readonly code: string;
31
+ readonly message: string;
32
+ readonly details?: Readonly<Record<string, unknown>> | null;
33
+ readonly retryable?: boolean;
34
+ };
35
+ }
36
+ /** One event the native core pushes (the derived client-observable set). */
37
+ export interface SyncularEvent {
38
+ readonly type: string;
39
+ readonly [key: string]: unknown;
40
+ }
41
+ /** The bytes envelope both sides share. */
42
+ export type BytesEnvelope = {
43
+ readonly $bytes: string;
44
+ };
45
+ /** The `create` options every native host forwards to the Rust core. */
46
+ export interface NativeCreateConfig {
47
+ /** The generated schema JSON (the app passes `schema` from typegen). */
48
+ readonly schema: unknown;
49
+ /**
50
+ * Client id for this device or actor. If omitted, the native core generates
51
+ * one and persists it in the database. Supplying a different id when opening
52
+ * an existing database fails with `client.identity_mismatch`.
53
+ */
54
+ readonly clientId?: string;
55
+ /** §4.2 client limits. */
56
+ readonly limits?: Record<string, unknown>;
57
+ /**
58
+ * SPEC §8.8 realtime policy. Absent ⇒ `optional`. `required` refuses a sync
59
+ * round while the socket is not connected instead of falling back to HTTP.
60
+ */
61
+ readonly realtimePolicy?: SyncClientConfig['realtimePolicy'];
62
+ /**
63
+ * Portable E2EE keys and declarative per-row key-id columns, installed in
64
+ * the Rust core. Raw keys are never sent to the server.
65
+ */
66
+ readonly encryption?: EncryptionKeyringConfig;
67
+ /** Open the native replica behind the fail-closed security gate. */
68
+ readonly securityPreflight?: boolean;
69
+ /** RFC 0005 previous-version context (default off). */
70
+ readonly previousVersionContext?: SyncClientConfig['previousVersionContext'];
71
+ }
72
+ /** The error a native `{error}` reply surfaces (mirrors `ClientSyncError`). */
73
+ export declare class NativeSyncError extends Error {
74
+ readonly code: string;
75
+ readonly details: Readonly<Record<string, unknown>> | undefined;
76
+ readonly retryable: boolean;
77
+ constructor(code: string, message: string, details?: Readonly<Record<string, unknown>>, retryable?: boolean);
78
+ }
79
+ /**
80
+ * The `create` params every native host sends. Keys cannot be installed
81
+ * before a security preflight; that combination fails before the host is
82
+ * touched.
83
+ */
84
+ export declare function nativeCreateParams(config: NativeCreateConfig, ErrorType: typeof NativeSyncError): Record<string, unknown>;
85
+ /**
86
+ * The `SyncClientLike` proxy over a native core. Every snapshot method
87
+ * returns a promise from one host round trip; React hooks accept the
88
+ * canonical snapshot interface directly.
89
+ */
90
+ export declare abstract class NativeBridgeClient implements PromiseMethods<ClientSnapshotMethods> {
91
+ #private;
92
+ /**
93
+ * `release` detaches the host event listener; the bridge calls it once,
94
+ * after shutdown or after a failed `create`.
95
+ */
96
+ constructor(kind: 'tauri' | 'react-native', ErrorType: typeof NativeSyncError, release: () => void, securityLifecycle: SecurityLifecycle);
97
+ /** Run one `{method, params}` command on the native core. */
98
+ protected abstract send(method: string, params: Record<string, unknown>): Promise<NativeReply>;
99
+ /** The read-only SQL fast path; `params` are already envelope-encoded. */
100
+ protected abstract sendQuery(sql: string, params: unknown): Promise<NativeReply>;
101
+ /** The atomic `querySnapshot` read. */
102
+ protected abstract sendQuerySnapshot(params: Record<string, unknown>): Promise<NativeReply>;
103
+ /** Replace the native transport's full header set. */
104
+ protected abstract sendHeaders(headers: Readonly<Record<string, string>>): Promise<NativeReply>;
105
+ /** Stop the native core. `close()` detaches listeners once it settles. */
106
+ protected abstract shutdown(): Promise<void>;
107
+ /** @internal Settle the native `create`; a failure detaches the listener. */
108
+ __open(create: () => Promise<NativeReply>): Promise<void>;
109
+ /** Dispatch a command through the closed check and the preflight gate. */
110
+ protected command(method: string, params: Record<string, unknown>): Promise<unknown>;
111
+ /** Additional preflight operations a host subclass permits. */
112
+ protected allowPreflightCommand(_method: string): boolean;
113
+ protected get closed(): boolean;
114
+ protected get preflight(): boolean;
115
+ protected requireOpen(): void;
116
+ /** Decode a native row. Reserved `_sync_*` columns stay engine-internal,
117
+ * so a `SELECT *` row round-trips into `mutate()` values. */
118
+ protected decodeRow(row: Readonly<Record<string, unknown>>): SqlRow;
119
+ /** @internal Fan an incoming native event out to the local listeners. */
120
+ __dispatchEvent(event: SyncularEvent): void;
121
+ securityLifecycle(): Promise<SecurityLifecycle>;
122
+ beginSecurityPreflight(): Promise<void>;
123
+ /**
124
+ * Complete the security preflight. `headers` optionally carries a fresh
125
+ * FULL transport header set that the native host applies atomically with
126
+ * the activation, before the startup sync it enqueues, so a preflight that
127
+ * outlives the boot token starts its first round with valid credentials
128
+ * (the direct `setHeaders` path stays refused while gated).
129
+ */
130
+ activateSecurity(options?: {
131
+ readonly encryption?: EncryptionKeyringConfig;
132
+ readonly headers?: Readonly<Record<string, string>>;
133
+ }): Promise<void>;
134
+ onInvalidate(listener: InvalidationListener): () => void;
135
+ onProgress(listener: SyncProgressListener): () => void;
136
+ progressSnapshot(): SyncProgress | undefined;
137
+ onChange(listener: ClientChangeListener): () => void;
138
+ onDiagnostics(listener: ClientDiagnosticsListener): () => void;
139
+ onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
140
+ query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
141
+ querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
142
+ /**
143
+ * §7.5: one atomic read. Every statement and every catch-up and delivery
144
+ * read shares one revision and one read transaction.
145
+ */
146
+ snapshotRead(request: SnapshotReadRequest): Promise<SnapshotRead>;
147
+ localRevision(): Promise<bigint>;
148
+ statusSnapshot(): Promise<SyncStatusSnapshot>;
149
+ diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;
150
+ mutate(mutations: readonly MutationInput[]): Promise<string>;
151
+ patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
152
+ readonly baseVersion?: number;
153
+ }): Promise<string>;
154
+ purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
155
+ rebootstrapLocalData(input: LocalDataRebootstrapInput): Promise<LocalDataRebootstrapResult>;
156
+ previousVersionSnapshot(spec: PreviousVersionReadSpec): Promise<PreviousVersionSnapshot>;
157
+ previousVersionAudit(): Promise<PreviousVersionAudit | undefined>;
158
+ previousVersionDiscard(): Promise<{
159
+ present: boolean;
160
+ discarded: boolean;
161
+ }>;
162
+ /**
163
+ * Replace the native transport's request headers at runtime, the auth
164
+ * rotation path. Pass the FULL header set: it replaces the current set.
165
+ * HTTP requests use the new set from the next call; the realtime socket
166
+ * applies it on its next (re)connect.
167
+ */
168
+ setHeaders(headers: Readonly<Record<string, string>>): Promise<void>;
169
+ /** Materialize a `crdt` column's collaborative text from the stored
170
+ * (server-merged) Yjs bytes. `name` selects the shared text (default
171
+ * `"text"`). An absent row or NULL column is the empty document. */
172
+ crdtText(table: string, rowId: string, column: string, name?: string): Promise<string>;
173
+ /** Insert `value` at UTF-16 offset `index` in a `crdt` column's text and
174
+ * push the resulting Yjs update (baseVersion-less). Returns the commit id. */
175
+ crdtInsertText(table: string, rowId: string, column: string, index: number, value: string, name?: string): Promise<string>;
176
+ /** Delete `len` UTF-16 code units at `index` in a `crdt` column's text. */
177
+ crdtDeleteText(table: string, rowId: string, column: string, index: number, len: number, name?: string): Promise<string>;
178
+ /** Apply an arbitrary Yjs update onto a `crdt` column. */
179
+ crdtApplyUpdate(table: string, rowId: string, column: string, update: Uint8Array): Promise<string>;
180
+ /**
181
+ * Stage a blob for attachment (§5.9.7) and return the canonical `BlobRef`
182
+ * string to store in a `blob_ref` column. The native core owns the upload
183
+ * queue; write the referencing row after this resolves (§5.9.3).
184
+ */
185
+ uploadBlob(bytes: Uint8Array, options?: {
186
+ readonly mediaType?: string;
187
+ readonly name?: string;
188
+ }): Promise<string>;
189
+ /**
190
+ * Resolve blob bytes for a `blob_ref` column value or a bare `blobId`
191
+ * (§5.9.7): the native core serves a local cache hit and otherwise
192
+ * downloads and verifies the content address.
193
+ */
194
+ fetchBlob(ref: string): Promise<{
195
+ readonly blobId: string;
196
+ readonly byteLength: number;
197
+ readonly bytes: Uint8Array;
198
+ readonly mediaType?: string;
199
+ }>;
200
+ subscribe(input: {
201
+ readonly id: string;
202
+ readonly table: string;
203
+ readonly scopes?: Record<string, readonly string[]>;
204
+ readonly params?: string;
205
+ }): Promise<void>;
206
+ /** Register several subscriptions in one local transaction. */
207
+ subscribeMany(inputs: readonly {
208
+ readonly id: string;
209
+ readonly table: string;
210
+ readonly scopes?: Record<string, readonly string[]>;
211
+ readonly params?: string;
212
+ }[]): Promise<void>;
213
+ unsubscribe(id: string): Promise<void>;
214
+ setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
215
+ windowState(base: WindowBase): Promise<WindowState>;
216
+ sync(): Promise<unknown>;
217
+ syncUntilIdle(maxRounds?: number, timeoutMs?: number): Promise<unknown>;
218
+ proveCurrentBase(outcome: Pick<CommitOutcome, 'clientCommitId' | 'sequence'>, maxRounds?: number): Promise<CurrentBaseProof>;
219
+ conflicts(): Promise<readonly ConflictRecord[]>;
220
+ rejections(): Promise<readonly RejectionRecord[]>;
221
+ commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
222
+ commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
223
+ resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
224
+ pendingCommits(): Promise<unknown[]>;
225
+ presence(scopeKey: string): Promise<readonly PresencePeer[]>;
226
+ setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
227
+ connectRealtime(): Promise<void>;
228
+ disconnectRealtime(): Promise<void>;
229
+ /**
230
+ * Shut down the native core, then detach listeners. Every call returns the
231
+ * same promise, so a concurrent or repeated close settles only when the one
232
+ * native shutdown settles, with its outcome.
233
+ */
234
+ close(): Promise<void>;
235
+ }