@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/dist/remote.js CHANGED
@@ -2,18 +2,15 @@
2
2
  * Database-less SSP2 producer (§6.10). It prepares and sends ordinary commits
3
3
  * through the existing push path without creating a local replica or outbox.
4
4
  */
5
- import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeSparseRow, normalizeRejectionDetails, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
5
+ import { decodeResponse, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeRequest, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeSparseRow, normalizeRejectionDetails, PROTOCOL_WIRE_VERSION, registrationDigest, } from '@syncular/core';
6
6
  import { encryptRowValues } from './encryption.js';
7
- import { ClientSyncError } from './errors.js';
7
+ import { ClientSyncError, invalidRequest } from './errors.js';
8
8
  import { compileClientSchema, recordToRowValues, normalizeRecordKeys, coerceSqlRepresentation, } from './schema.js';
9
9
  export function remoteCommand(id) {
10
10
  if (id.length === 0)
11
- throw invalid('remote command id must be non-empty');
11
+ throw invalidRequest('remote command id must be non-empty');
12
12
  return { id };
13
13
  }
14
- function invalid(message) {
15
- return new ClientSyncError('sync.invalid_request', message);
16
- }
17
14
  function operationResponse(bytes) {
18
15
  let response;
19
16
  try {
@@ -86,10 +83,10 @@ export class SyncRemoteClient {
86
83
  #logEpoch;
87
84
  constructor(config) {
88
85
  if (config.clientId.length === 0) {
89
- throw invalid('SyncRemoteClient clientId must be non-empty');
86
+ throw invalidRequest('SyncRemoteClient clientId must be non-empty');
90
87
  }
91
88
  if (config.logEpoch !== undefined && config.logEpoch.length === 0) {
92
- throw invalid('SyncRemoteClient logEpoch must be non-empty');
89
+ throw invalidRequest('SyncRemoteClient logEpoch must be non-empty');
93
90
  }
94
91
  this.#schema =
95
92
  config.schema === undefined
@@ -108,7 +105,7 @@ export class SyncRemoteClient {
108
105
  throw new ClientSyncError('client.remote_schema_unconfigured', 'SyncRemoteClient needs a schema to prepare ordinary commits');
109
106
  }
110
107
  if (input.requestId.length === 0) {
111
- throw invalid('remote commit requestId must be non-empty');
108
+ throw invalidRequest('remote commit requestId must be non-empty');
112
109
  }
113
110
  if (input.mutations.length === 0) {
114
111
  throw new ClientSyncError('sync.empty_commit', 'a remote commit must carry at least one mutation (§6.1)');
@@ -120,7 +117,7 @@ export class SyncRemoteClient {
120
117
  if (this.#transport === undefined) {
121
118
  throw new ClientSyncError('client.remote_sync_unconfigured', 'SyncRemoteClient has no sync transport for ordinary commits');
122
119
  }
123
- const acquisition = decodeMessage(await this.#transport(encodeMessage({
120
+ const acquisition = decodeResponse(await this.#transport(encodeRequest({
124
121
  wireVersion: PROTOCOL_WIRE_VERSION,
125
122
  msgKind: 'request',
126
123
  frames: [
@@ -136,13 +133,14 @@ export class SyncRemoteClient {
136
133
  limitSnapshotRows: 0,
137
134
  maxSnapshotPages: 0,
138
135
  accept: 0b0011,
136
+ cursor: -1,
137
+ registrationDigest: registrationDigest([]),
138
+ echoDigest: new Uint8Array(),
139
139
  },
140
140
  ],
141
141
  })));
142
142
  const acquisitionHeader = acquisition.frames[0];
143
- if (acquisition.msgKind !== 'response' ||
144
- acquisitionHeader?.type !== 'RESP_HEADER' ||
145
- acquisitionHeader.logEpoch === undefined) {
143
+ if (acquisitionHeader?.type !== 'RESP_HEADER') {
146
144
  throw new ClientSyncError('client.invalid_host_response', 'remote epoch acquisition returned an invalid response');
147
145
  }
148
146
  logEpoch = acquisitionHeader.logEpoch;
@@ -152,11 +150,11 @@ export class SyncRemoteClient {
152
150
  for (const mutation of input.mutations) {
153
151
  const table = schema.tables.get(mutation.table);
154
152
  if (table === undefined) {
155
- throw invalid('remote commit targets an unknown table');
153
+ throw invalidRequest('remote commit targets an unknown table');
156
154
  }
157
155
  if (mutation.op === 'delete') {
158
156
  if (mutation.rowId.length === 0) {
159
- throw invalid('remote delete rowId must be non-empty');
157
+ throw invalidRequest('remote delete rowId must be non-empty');
160
158
  }
161
159
  operations.push({
162
160
  table: mutation.table,
@@ -182,9 +180,9 @@ export class SyncRemoteClient {
182
180
  ? String(rawRowId)
183
181
  : undefined;
184
182
  if (rowId === undefined) {
185
- throw invalid('remote upsert requires a non-empty primary key');
183
+ throw invalidRequest('remote upsert requires a non-empty primary key');
186
184
  }
187
- if (this.#encryption !== undefined && table.hasEncryptedColumns) {
185
+ if (table.hasEncryptedColumns) {
188
186
  values = await encryptRowValues(this.#encryption, table, rowId, values);
189
187
  }
190
188
  operations.push({
@@ -199,7 +197,7 @@ export class SyncRemoteClient {
199
197
  }
200
198
  return {
201
199
  requestId: input.requestId,
202
- bytes: encodeMessage({
200
+ bytes: encodeRequest({
203
201
  wireVersion: PROTOCOL_WIRE_VERSION,
204
202
  msgKind: 'request',
205
203
  frames: [
@@ -212,6 +210,7 @@ export class SyncRemoteClient {
212
210
  {
213
211
  type: 'PUSH_COMMIT',
214
212
  clientCommitId: input.requestId,
213
+ clientSeq: 0,
215
214
  operations,
216
215
  },
217
216
  ],
@@ -222,10 +221,7 @@ export class SyncRemoteClient {
222
221
  if (this.#transport === undefined) {
223
222
  throw new ClientSyncError('client.remote_sync_unconfigured', 'SyncRemoteClient has no sync transport for ordinary commits');
224
223
  }
225
- const response = decodeMessage(await this.#transport(prepared.bytes));
226
- if (response.msgKind !== 'response') {
227
- throw new ClientSyncError('client.invalid_host_response', 'remote commit transport returned a non-response SSP2 message');
228
- }
224
+ const response = decodeResponse(await this.#transport(prepared.bytes));
229
225
  const error = response.frames.find((frame) => frame.type === 'ERROR');
230
226
  if (error?.type === 'ERROR') {
231
227
  throw new ClientSyncError(error.code, error.message, error.retryable);
@@ -288,7 +284,7 @@ export class SyncRemoteClient {
288
284
  throw new ClientSyncError('client.remote_operations_unconfigured', 'SyncRemoteClient has no remote operation transport');
289
285
  }
290
286
  if (requestId.length === 0) {
291
- throw invalid('remote command requestId must be non-empty');
287
+ throw invalidRequest('remote command requestId must be non-empty');
292
288
  }
293
289
  const response = operationResponse(await this.#operations(encodeRemoteOperationRequest({
294
290
  revision: 1,
package/dist/schema.d.ts CHANGED
@@ -130,10 +130,10 @@ export declare function ensureLocalSchema(db: ClientDatabase, schema: CompiledCl
130
130
  * generated schema created — discovered from `sqlite_master`, since a
131
131
  * bump may add/remove tables) and recreate the synced tables from the
132
132
  * NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
133
- * subscriptions, blob cache) are preserved. RFC 0005's container is not
133
+ * units, blob cache) are preserved. RFC 0005's container is not
134
134
  * reachable from here: it lives in its own database file, so this reset cannot
135
135
  * see or destroy it. Caller owns the surrounding transaction and the
136
- * subscription-state reset (state.ts).
136
+ * unit-state reset (state.ts).
137
137
  */
138
138
  export declare function dropAndRecreateSyncedTables(db: ClientDatabase, schema: CompiledClientSchema): void;
139
139
  /** RowValue → SQL bind value for the local mirror tables. */
@@ -165,6 +165,7 @@ export declare function recordToRowValues(table: CompiledClientTable, record: Re
165
165
  export type JsonRowValue = string | number | boolean | null | {
166
166
  readonly $bytes: string;
167
167
  };
168
+ export declare function bytesToHex(bytes: Uint8Array): string;
168
169
  /**
169
170
  * The canonical §7.1 byte envelope: exactly one `$bytes` key holding a string
170
171
  * of hexadecimal digit pairs. Uppercase digits are accepted; encoders emit
package/dist/schema.js CHANGED
@@ -3,9 +3,9 @@ import { PENDING_EVICTIONS } from './window.js';
3
3
  import { WINDOWS_TABLE } from './window.js';
4
4
  import { OUTBOX_TABLE, OUTBOX_IMAGES } from './outbox.js';
5
5
  import { OUTCOMES_TABLE } from './outcomes.js';
6
- import { SUBSCRIPTIONS_TABLE, META_TABLE } from './state.js';
6
+ import { META_TABLE, resetUnits, UNITS_TABLE } from './state.js';
7
7
  import { ensureFailedOverlaySchema } from './failed-overlay.js';
8
- import { invalidRequest } from './errors.js';
8
+ import { ClientSyncError, invalidRequest } from './errors.js';
9
9
  import { snakeToCamel } from './naming.js';
10
10
  const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
11
11
  const ALLOWED_FTS_TOKENIZERS = new Set([
@@ -65,15 +65,16 @@ export function compileClientSchema(schema) {
65
65
  const scopePrefixByVariable = new Map();
66
66
  for (const spec of table.scopes) {
67
67
  const pattern = typeof spec === 'string' ? spec : spec.pattern;
68
- const match = PATTERN_RE.exec(pattern);
69
- if (match === null || match[1] === undefined || match[2] === undefined) {
68
+ const [, prefix, variable] = PATTERN_RE.exec(pattern) ?? [];
69
+ if (!prefix || !variable) {
70
70
  invalidSchema(`${tableLabel}: scope pattern ${JSON.stringify(pattern)} must be 'prefix:{variable}'`);
71
71
  }
72
- const prefix = match[1];
73
- const variable = match[2];
74
72
  const column = typeof spec === 'string' ? variable : spec.column;
75
- if (!columnIndex.has(column)) {
76
- invalidSchema(`${tableLabel}: scope pattern ${JSON.stringify(pattern)} names unknown column ${JSON.stringify(column)}`);
73
+ // §3.1: a scope value is an authorization key; only these two types
74
+ // render identically in every implementation.
75
+ const type = table.columns[columnIndex.get(column) ?? -1]?.type;
76
+ if (type !== 'string' && type !== 'integer') {
77
+ invalidSchema(`${tableLabel}: scope column ${JSON.stringify(column)} must be string or integer (§3.1)`);
77
78
  }
78
79
  const existing = scopeColumnByVariable.get(variable);
79
80
  if (existing !== undefined && existing !== column) {
@@ -404,12 +405,20 @@ export function ensureLocalBookkeepingSchema(db) {
404
405
  createTable(BLOB_COMMIT_REFS, 'commit_id TEXT NOT NULL,blob_id TEXT NOT NULL,PRIMARY KEY(commit_id,blob_id)');
405
406
  db.exec(`CREATE INDEX IF NOT EXISTS ${BLOB_COMMIT_REFS}_body ON ${BLOB_COMMIT_REFS}(blob_id)`);
406
407
  db.exec(`INSERT OR IGNORE INTO ${META_TABLE}(key,value)VALUES('localRevision','0')`);
408
+ const outboxExisted = db.query(`SELECT 1 FROM sqlite_master WHERE type='table' AND name='${OUTBOX_TABLE}'`).length > 0;
407
409
  createTable(OUTBOX_TABLE, 'seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,created_at_ms INTEGER NOT NULL,operations TEXT NOT NULL');
410
+ // §7.1: `outboxId` names the outbox sequence. A new outbox table starts
411
+ // a new sequence, so it replaces the id in the same transaction.
412
+ db.exec(`INSERT OR ${outboxExisted ? 'IGNORE' : 'REPLACE'} INTO ${META_TABLE}(key,value)VALUES('outboxId',?)`, [crypto.randomUUID()]);
408
413
  createTable(OUTBOX_IMAGES, 'client_commit_id TEXT NOT NULL,op_index INTEGER NOT NULL,existed INTEGER NOT NULL CHECK(existed IN (0,1)),sync_version INTEGER,values_json TEXT,PRIMARY KEY(client_commit_id,op_index)');
409
- if (!db
410
- .query(`PRAGMA table_info(${OUTBOX_IMAGES})`)
411
- .some((row) => row.name === 'delivery_seq'))
412
- db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN delivery_seq INTEGER`);
414
+ const imageColumns = db.query(`PRAGMA table_info(${OUTBOX_IMAGES})`);
415
+ for (const column of ['delivery_seq INTEGER', 'tbl TEXT', 'row_id TEXT'])
416
+ if (!imageColumns.some((row) => row.name === column.split(' ')[0]))
417
+ db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN ${column}`);
418
+ // Images written before the row key existed take it from their operation.
419
+ if (!imageColumns.some((row) => row.name === 'row_id'))
420
+ db.exec(`UPDATE ${OUTBOX_IMAGES} SET (tbl,row_id)=(SELECT json_extract(operations,'$['||op_index||'].table'),json_extract(operations,'$['||op_index||'].rowId') FROM ${OUTBOX_TABLE} WHERE client_commit_id=${OUTBOX_IMAGES}.client_commit_id)`);
421
+ db.exec(`CREATE INDEX IF NOT EXISTS ${OUTBOX_IMAGES}_row ON ${OUTBOX_IMAGES}(tbl,row_id)`);
413
422
  createTable(OUTCOMES_TABLE, "seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,status TEXT NOT NULL CHECK(status IN ('applied','cached','conflict','rejected')),recorded_at_ms INTEGER NOT NULL,results TEXT NOT NULL,operations TEXT,resolution TEXT NOT NULL DEFAULT 'active' CHECK(resolution IN ('active','resolved_keep_server','superseded','dismissed')),resolved_at_ms INTEGER,replacement_client_commit_id TEXT");
414
423
  // Outcomes created before durable aggregate recovery retain no commit
415
424
  // envelope. New failed outcomes store it in the protected client DB.
@@ -420,14 +429,26 @@ export function ensureLocalBookkeepingSchema(db) {
420
429
  // column already exists — the CREATE above included it
421
430
  }
422
431
  db.exec(`CREATE INDEX IF NOT EXISTS ${OUTCOMES_TABLE}_resolution_seq ON ${OUTCOMES_TABLE}(resolution,seq)`);
423
- createTable(SUBSCRIPTIONS_TABLE, "id TEXT PRIMARY KEY,tbl TEXT NOT NULL,requested_scopes TEXT NOT NULL,params TEXT,cursor INTEGER NOT NULL DEFAULT -1,bootstrap_state TEXT,effective_scopes TEXT,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT");
424
- // §4.8 window registry: which units (scope values) of a window base are
425
- // live locally — the completeness oracle (I3) and the shrink driver
426
- // (a unit's omission from the next pull unregisters it, §4.1).
432
+ createTable(UNITS_TABLE, "id TEXT PRIMARY KEY,scopes TEXT NOT NULL,explicit INTEGER NOT NULL DEFAULT 0,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT,cursor INTEGER DEFAULT -1,bootstrap_state TEXT,seeded TEXT NOT NULL DEFAULT '[]',echo TEXT");
433
+ // §4.8 window registry: base + value → the unit it holds, the
434
+ // completeness oracle and one of a unit's references (§4.1).
427
435
  createTable(WINDOWS_TABLE, 'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)');
428
- // §4.8 E1: units that left the window but still had outbox-pinned rows.
429
- // Retried when the outbox drains; cancelled if the unit re-enters.
430
- createTable(PENDING_EVICTIONS, 'sub_id TEXT PRIMARY KEY,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL');
436
+ // §4.8 E1: per-table scopes of units that left with pinned or unevicted
437
+ // rows. Retried when the outbox drains; cancelled when the unit re-enters.
438
+ createTable(PENDING_EVICTIONS, 'unit_id TEXT NOT NULL,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL,PRIMARY KEY(unit_id,tbl)');
439
+ // §9: a replica written under wire version 3 keeps its outbox, journal,
440
+ // rows and pending evictions and registers its units fresh. Its
441
+ // subscriptions, cursors, echoes, resume tokens and window entries go.
442
+ const legacyEvictions = '_syncular_window_pending_evict';
443
+ if (db.query(`SELECT 1 FROM sqlite_master WHERE type='table' AND name='${legacyEvictions}'`).length > 0) {
444
+ if (db.query(`SELECT 1 FROM ${legacyEvictions} WHERE NOT json_valid(effective_scopes) OR json_type(effective_scopes)<>'object' OR EXISTS(SELECT 1 FROM json_each(effective_scopes) WHERE json_type(value)<>'array' OR EXISTS(SELECT 1 FROM json_each(value) v WHERE v.type<>'text'))`).length > 0)
445
+ throw new ClientSyncError('sync.local_corrupt', 'a version 3 pending eviction cannot be upgraded');
446
+ db.exec(`INSERT OR REPLACE INTO ${PENDING_EVICTIONS} SELECT sub_id,tbl,effective_scopes FROM ${legacyEvictions}`);
447
+ db.exec(`DROP TABLE ${legacyEvictions}`);
448
+ db.exec('DROP TABLE IF EXISTS _syncular_subscriptions');
449
+ db.exec(`DELETE FROM ${WINDOWS_TABLE}`);
450
+ resetUnits(db);
451
+ }
431
452
  });
432
453
  }
433
454
  /** Create both application and protected bookkeeping tables. */
@@ -442,10 +463,10 @@ const RESERVED_TABLE_PREFIX = '_syncular_';
442
463
  * generated schema created — discovered from `sqlite_master`, since a
443
464
  * bump may add/remove tables) and recreate the synced tables from the
444
465
  * NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
445
- * subscriptions, blob cache) are preserved. RFC 0005's container is not
466
+ * units, blob cache) are preserved. RFC 0005's container is not
446
467
  * reachable from here: it lives in its own database file, so this reset cannot
447
468
  * see or destroy it. Caller owns the surrounding transaction and the
448
- * subscription-state reset (state.ts).
469
+ * unit-state reset (state.ts).
449
470
  */
450
471
  export function dropAndRecreateSyncedTables(db, schema) {
451
472
  // Drop virtual tables first. SQLite then removes their shadow tables as one
@@ -557,7 +578,7 @@ export function recordToRowValues(table, record) {
557
578
  return coerceSqlRepresentation(column, value);
558
579
  });
559
580
  }
560
- function bytesToHex(bytes) {
581
+ export function bytesToHex(bytes) {
561
582
  let out = '';
562
583
  for (const byte of bytes)
563
584
  out += byte.toString(16).padStart(2, '0');
package/dist/state.d.ts CHANGED
@@ -1,50 +1,83 @@
1
1
  export declare const META_TABLE = "_syncular_meta";
2
- export declare const SUBSCRIPTIONS_TABLE = "_syncular_subscriptions";
2
+ export declare const UNITS_TABLE = "_syncular_units";
3
3
  /**
4
- * Durable client sync state: per-subscription cursor, bootstrap resume
5
- * token (round-tripped opaquely, §4.7), and the last-echoed effective
6
- * scopes the §3.3 purge contract is keyed on — persisted per subscription
7
- * exactly for that purpose.
4
+ * Durable unit state (SPEC.md §4.1): per unit its scope map, status, live
5
+ * membership, catch-up cursor and opaque resume token (§4.7), the tables its
6
+ * current bootstrap seeded (§5.6) and the last echo (§4.4) the §3.3 purge
7
+ * contract is keyed on. The replica cursor, the echo digest and the
8
+ * registration digest the server holds live in meta.
8
9
  */
9
- import type { ScopeMap } from '@syncular/core';
10
- import type { CompiledClientSchema } from './schema.js';
10
+ import type { FencedRecord, ScopeMap, UnitScopes } from '@syncular/core';
11
+ import type { CompiledClientSchema, CompiledClientTable } from './schema.js';
11
12
  import type { ClientDatabase } from './database.js';
12
13
  import type { LocalRevision } from './invalidation.js';
13
14
  export declare const LOCAL_REVISION_KEY = "localRevision";
14
- export type SubscriptionStatus = 'active' | 'revoked' | 'failed';
15
- export interface SubscriptionRecord {
15
+ /** §4.5 replica cursor; absent means `-1`. */
16
+ export declare const REPLICA_CURSOR_KEY = "replicaCursor";
17
+ /** Hex of the last pull `LIVE_END.echoDigest` (§4.2); absent means empty. */
18
+ export declare const ECHO_DIGEST_KEY = "echoDigest";
19
+ /** Hex of the registration digest of the list the server stores (§4.1). */
20
+ export declare const REGISTERED_DIGEST_KEY = "registrationDigest";
21
+ export type UnitStatus = 'active' | 'revoked' | 'failed';
22
+ export interface UnitRecord {
23
+ /** §4.1: derived from the scope map. */
16
24
  readonly id: string;
17
- readonly table: string;
18
- /** Requested scopes (§3.2), chosen by the app. */
19
- readonly scopes: ScopeMap;
20
- /** Host-opaque JSON params, preserved verbatim. */
21
- readonly params?: string;
22
- /** Last fully-applied commitSeq; -1 = never synced (§4.3). */
23
- readonly cursor: number;
25
+ readonly scopes: UnitScopes;
26
+ /** An explicit `subscribe` holds the unit; window bases hold it through
27
+ * the window registry (§4.1 references). */
28
+ readonly explicit: boolean;
29
+ readonly status: UnitStatus;
30
+ /** §10 code when not active, or `sync.cursor_expired` after a reset. */
31
+ readonly reasonCode?: string | undefined;
32
+ /** Absent while the unit is live (§4.5); otherwise `-1`, the pin, or the
33
+ * post-bootstrap cursor `P`. */
34
+ readonly cursor?: number | undefined;
24
35
  /** Opaque resume token from `SUB_END` (§4.7); present mid-bootstrap. */
25
- readonly bootstrapState?: string;
26
- /** Last effective scopes echoed while active (§3.3 purge key). */
27
- readonly effectiveScopes?: ScopeMap;
28
- readonly status: SubscriptionStatus;
29
- /** §10 code when not active (`sync.scope_revoked`, …). */
30
- readonly reasonCode?: string;
36
+ readonly bootstrapState?: string | undefined;
37
+ /** Tables that received a segment in the current bootstrap (§5.6). */
38
+ readonly seeded: readonly string[];
39
+ /** The echo persisted at the last `SUB_END` (§4.4). */
40
+ readonly echo?: readonly FencedRecord[] | undefined;
31
41
  }
32
- export declare function loadSubscriptions(db: ClientDatabase): SubscriptionRecord[];
33
- export declare function getSubscription(db: ClientDatabase, id: string): SubscriptionRecord | undefined;
34
- export declare function saveSubscription(db: ClientDatabase, record: SubscriptionRecord): void;
35
- export declare function deleteSubscription(db: ClientDatabase, id: string): void;
42
+ /** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
43
+ export declare function bootstrapping(unit: UnitRecord): boolean;
44
+ /** §3.3 row ownership: active, live or post-bootstrap, with an echo. */
45
+ export declare function owning(unit: UnitRecord): boolean;
46
+ /** §4.1: the unit covers every table declaring all of its variables. */
47
+ export declare function covers(table: CompiledClientTable, scopes: UnitScopes): boolean;
36
48
  /**
37
- * §7.4.3 reset: keep compatible subscription REGISTRATIONS (id, table,
38
- * requested scopes, params — the app's declared intent) but discard all
39
- * synced state (cursor → -1, no resume token, no effective-scope map,
40
- * status → active), so the next round fresh-bootstraps exactly the
41
- * subscriptions the app still wants. Caller owns the transaction.
49
+ * §4.4: the effective scopes of the (unit, table) pair under `echo`: the
50
+ * scope map as one-element lists plus the fenced lists. Undefined when the
51
+ * fence revoked the pair.
42
52
  */
43
- export declare function resetSubscriptionsForBump(db: ClientDatabase): void;
44
- /** Persist declarations separately from the previous-version row descriptor. */
45
- export declare function saveSubscriptionScopeSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
46
- /** Drop incompatible registrations and their windows; never translate scopes. */
47
- export declare function pruneUnknownSubscriptions(db: ClientDatabase, subscriptions: readonly SubscriptionRecord[], schema: CompiledClientSchema, bump?: boolean): SubscriptionRecord[];
53
+ export declare function pairScopes(scopes: UnitScopes, table: string, echo: readonly FencedRecord[] | undefined): ScopeMap | undefined;
54
+ /** §3.3 row ownership: the pair scopes of every owner of `table` but one.
55
+ * A bootstrapping unit owns the tables its current bootstrap seeded. */
56
+ export declare function unitOwners(units: readonly UnitRecord[], table: CompiledClientTable, exceptId: string): ScopeMap[];
57
+ /** Every unit in registration order (§4.1). */
58
+ export declare function loadUnits(db: ClientDatabase): UnitRecord[];
59
+ export declare function getUnit(db: ClientDatabase, id: string): UnitRecord | undefined;
60
+ /** Insert or update in place: an update keeps the registration order. */
61
+ export declare function saveUnit(db: ClientDatabase, record: UnitRecord): void;
62
+ export declare function deleteUnit(db: ClientDatabase, id: string): void;
63
+ /**
64
+ * §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
65
+ * registrations (the app's declared intent) and discard every synced state,
66
+ * so the next round sends the list and fresh-bootstraps every unit. Caller
67
+ * owns the transaction.
68
+ */
69
+ export declare function resetUnits(db: ClientDatabase): void;
70
+ /** §4.5: the replica cursor, `-1` while no unit is live. */
71
+ export declare function replicaCursor(db: ClientDatabase): number;
72
+ /** §7.4.3 declaration evidence, persisted beside the schema marker. */
73
+ export declare function saveUnitScopeSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
74
+ /**
75
+ * Drop units that cover no table of the running schema, with their window
76
+ * registry rows and pending evictions; never translate scopes. At a bump
77
+ * (§7.4.3) a unit also needs every variable unchanged in prefix and column on
78
+ * every table it covered before.
79
+ */
80
+ export declare function pruneUnknownUnits(db: ClientDatabase, schema: CompiledClientSchema, bump?: boolean): void;
48
81
  export declare function getMeta(db: ClientDatabase, key: string): string | undefined;
49
82
  export declare function setMeta(db: ClientDatabase, key: string, value: string): void;
50
83
  /** Read the durable client-local observer revision (SPEC §7.5). */