@syncular/client 0.85.0 → 0.90.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 (58) hide show
  1. package/README.md +13 -4
  2. package/dist/apply.d.ts +1 -1
  3. package/dist/apply.js +25 -26
  4. package/dist/blob.d.ts +0 -4
  5. package/dist/blob.js +7 -22
  6. package/dist/client.d.ts +31 -10
  7. package/dist/client.js +501 -465
  8. package/dist/diagnostics.d.ts +2 -4
  9. package/dist/diagnostics.js +3 -17
  10. package/dist/encryption.js +5 -30
  11. package/dist/errors.d.ts +2 -0
  12. package/dist/errors.js +4 -0
  13. package/dist/failed-overlay.d.ts +8 -2
  14. package/dist/failed-overlay.js +33 -22
  15. package/dist/local-purge.d.ts +1 -0
  16. package/dist/local-purge.js +1 -1
  17. package/dist/local-rebootstrap-receipt.js +2 -2
  18. package/dist/local-rebootstrap.js +1 -1
  19. package/dist/native-bridge.d.ts +8 -3
  20. package/dist/native-bridge.js +29 -12
  21. package/dist/outcomes.d.ts +13 -1
  22. package/dist/outcomes.js +21 -20
  23. package/dist/previous-version.js +23 -35
  24. package/dist/progress.d.ts +4 -0
  25. package/dist/progress.js +14 -2
  26. package/dist/realtime-supervisor.d.ts +4 -1
  27. package/dist/realtime-supervisor.js +2 -2
  28. package/dist/schema.js +14 -13
  29. package/dist/state.d.ts +16 -4
  30. package/dist/state.js +83 -44
  31. package/dist/sync-scheduler.d.ts +8 -2
  32. package/dist/sync-scheduler.js +11 -3
  33. package/dist/worker-core.js +14 -10
  34. package/dist/worker-host.d.ts +10 -2
  35. package/dist/worker-host.js +15 -0
  36. package/dist/worker-protocol.d.ts +4 -1
  37. package/package.json +3 -3
  38. package/src/apply.ts +34 -47
  39. package/src/blob.ts +7 -24
  40. package/src/client.ts +699 -553
  41. package/src/diagnostics.ts +3 -19
  42. package/src/encryption.ts +15 -40
  43. package/src/errors.ts +5 -0
  44. package/src/failed-overlay.ts +39 -29
  45. package/src/local-purge.ts +1 -1
  46. package/src/local-rebootstrap-receipt.ts +2 -5
  47. package/src/local-rebootstrap.ts +1 -2
  48. package/src/native-bridge.ts +40 -14
  49. package/src/outcomes.ts +36 -31
  50. package/src/previous-version.ts +31 -40
  51. package/src/progress.ts +18 -2
  52. package/src/realtime-supervisor.ts +7 -3
  53. package/src/schema.ts +13 -13
  54. package/src/state.ts +107 -64
  55. package/src/sync-scheduler.ts +17 -5
  56. package/src/worker-core.ts +14 -18
  57. package/src/worker-host.ts +30 -1
  58. package/src/worker-protocol.ts +4 -0
package/README.md CHANGED
@@ -430,7 +430,9 @@ results, or app state alongside it. See SPEC §7.6.
430
430
  ## Durable commit outcomes
431
431
 
432
432
  `SyncClient` and every host bridge expose `commitOutcome(id)`,
433
- `commitOutcomes({ limit?, activeOnly? })`, and `resolveCommitOutcome(input)`.
433
+ `commitOutcomes({ limit?, activeOnly? })`, `commitDelivery(id)`, and
434
+ `resolveCommitOutcome(input)`. `commitDelivery` answers `pending`, `known` with
435
+ the outcome, or `unknown` when neither the outbox nor the journal holds the ID.
434
436
  Final `applied`, `cached`, `conflict`, and `rejected` results are journaled in
435
437
  the same SQLite transaction that drains their outbox commit. Conflict entries
436
438
  retain the losing operation plus `serverVersion`/`serverRow`; active failures
@@ -676,12 +678,13 @@ directory or IndexedDB store. This is the pinned decision (SPEC §5.9.7 B1):
676
678
 
677
679
  ### Size cap
678
680
 
679
- Pass `blobCacheMaxBytes` to cap the on-device cache. When the sum of cached body
681
+ Set `limits.blobCacheMaxBytes` to cap the on-device cache. The worker handle
682
+ forwards `limits` to its core, and the native core reads the same key. When the sum of cached body
680
683
  sizes exceeds the cap, the client evicts bodies with no visible row or pending
681
684
  commit by creation timestamp, then blob ID, until back under the cap:
682
685
 
683
686
  ```ts
684
- new SyncClient({ /* … */, blobCacheMaxBytes: 256 * 1024 * 1024 }); // 256 MiB
687
+ new SyncClient({ /* … */, limits: { blobCacheMaxBytes: 256 * 1024 * 1024 } }); // 256 MiB
685
688
  ```
686
689
 
687
690
  - A body **referenced by a live row** is **never** evicted. It
@@ -691,7 +694,7 @@ new SyncClient({ /* … */, blobCacheMaxBytes: 256 * 1024 * 1024 }); // 256 MiB
691
694
  - Evicting an unreferenced body only costs a future re-download, never correctness:
692
695
  any surviving `blob_ref` value re-enables the fetch (§5.9.7 B3). If every
693
696
  over-cap body is referenced or pinned, the cache stays over the cap
694
- (correctness beats the cap). Absent `blobCacheMaxBytes` ⇒ retain until storage
697
+ (correctness beats the cap). Absent `limits.blobCacheMaxBytes` ⇒ retain until storage
695
698
  pressure (the default).
696
699
 
697
700
  ### Very large media — the escape hatch
@@ -846,6 +849,12 @@ under a new `epoch`. `phase` is `request`,
846
849
  `download`, or `import`; `state` is `running`, `complete`, or `failed`. Unknown
847
850
  totals remain absent. A new attempt clears prior errors and counters.
848
851
 
852
+ `unitRowsTotal` and `unitRowsProcessed` cover the bootstrap of the unit in
853
+ `unitId` as a whole: the rows the server counted when the bootstrap started and
854
+ the rows imported since, across segments and rounds. The count only rises and
855
+ ends equal to the total; both are absent when the server states no count
856
+ (SPEC §7.7).
857
+
849
858
  HTTP downloads report decoded body bytes at 64 KiB intervals or larger network
850
859
  chunks. Custom segment downloaders receive `request.onProgress`; signed-URL
851
860
  implementations receive an optional second callback argument. Call it with the
package/dist/apply.d.ts CHANGED
@@ -10,7 +10,7 @@ import type { EncryptionConfig, SealedRow } from './encryption.js';
10
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
- export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number, serverWrite?: boolean, sealed?: SealedRow): void;
13
+ export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number, sealed?: SealedRow): void;
14
14
  export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClientTable, rowId: string, serverWrite?: boolean): void;
15
15
  /**
16
16
  * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4) under the
package/dist/apply.js CHANGED
@@ -9,7 +9,7 @@ import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
9
9
  */
10
10
  import { decodeRow, } from '@syncular/core';
11
11
  import { ClientSyncError, invalidRequest } from './errors.js';
12
- import { quoteIdent, matchesLocalScopes, pkSqlValue, SEALED_COLUMN, SEALED_KEY_COLUMN, SYNC_VERSION_COLUMN, toSqlValue, rowValueToJson, } from './schema.js';
12
+ import { quoteIdent, matchesLocalScopes, pkSqlValue, SEALED_COLUMN, SEALED_KEY_COLUMN, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
13
13
  function upsertSql(table) {
14
14
  const names = [
15
15
  ...table.columns.map((column) => quoteIdent(column.name)),
@@ -25,7 +25,7 @@ function upsertSql(table) {
25
25
  .join(', ');
26
26
  return `INSERT INTO ${quoteIdent(table.name)}(${names.join(', ')})VALUES(${placeholders})ON CONFLICT(${quoteIdent(table.primaryKey)})DO UPDATE SET ${updates}`;
27
27
  }
28
- export function upsertLocalRow(db, table, values, syncVersion, serverWrite = true, sealed) {
28
+ export function upsertLocalRow(db, table, values, syncVersion, sealed) {
29
29
  db.exec(upsertSql(table), [
30
30
  ...values.map(toSqlValue),
31
31
  syncVersion,
@@ -33,16 +33,11 @@ export function upsertLocalRow(db, table, values, syncVersion, serverWrite = tru
33
33
  ? [sealed?.keyId ?? null, sealed?.envelopes ?? null]
34
34
  : []),
35
35
  ]);
36
- if (serverWrite)
37
- retainedBaseWrite(db, table, String(values[table.primaryKeyIndex]), Object.fromEntries(table.columns.map((column, index) => [
38
- column.name,
39
- rowValueToJson(values[index] ?? null),
40
- ])), syncVersion);
41
36
  }
42
37
  export function deleteLocalRow(db, table, rowId, serverWrite = true) {
43
- if (serverWrite)
44
- retainedBaseWrite(db, table, rowId);
45
38
  db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, rowId)]);
39
+ if (serverWrite)
40
+ retainedBaseWrite(db, table, new Map([[rowId, undefined]]));
46
41
  }
47
42
  /**
48
43
  * §4.5 version guard for one server row: whether a write at `version` lands.
@@ -139,8 +134,10 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
139
134
  continue;
140
135
  if (change.op === 'delete')
141
136
  deleteLocalRow(db, change.table, rowId);
142
- else
143
- upsertLocalRow(db, change.table, change.values, rowVersion, true, change.sealed);
137
+ else {
138
+ upsertLocalRow(db, change.table, change.values, rowVersion, change.sealed);
139
+ retainedBaseWrite(db, change.table, new Map([[rowId, [change.values, rowVersion]]]));
140
+ }
144
141
  }
145
142
  return rebaseScope(scope, kept, skipped);
146
143
  });
@@ -240,11 +237,9 @@ export function deleteScopedRows(db, table, effective, owners) {
240
237
  if (!scope)
241
238
  return;
242
239
  const { sql, params } = scope;
243
- if (retainsRows(db, table))
244
- for (const row of scopedRows(db, table, scope)) {
245
- retainedBaseWrite(db, table, String(row.id));
246
- }
240
+ const retained = retainsRows(db, table) ? scopedRows(db, table, scope) : [];
247
241
  db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${sql}`, params);
242
+ retainedBaseWrite(db, table, new Map(retained.map((row) => [String(row.id), undefined])));
248
243
  }
249
244
  /**
250
245
  * §4.8 window eviction: delete rows matching a departing unit's effective
@@ -396,7 +391,7 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
396
391
  : []),
397
392
  ...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
398
393
  ];
399
- const protectedRows = restoreFailedBases(db, schema, scope);
394
+ restoreFailedBases(db, schema, scope);
400
395
  if (first && options.clearFirst)
401
396
  deleteScopedRows(db, table, options.effective, options.owners());
402
397
  const kept = new Set();
@@ -415,13 +410,13 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
415
410
  break;
416
411
  [boundary, where, params] = range(boundary, Math.min(1024, size - chunk));
417
412
  }
418
- if (protectedRows)
419
- for (const row of landing) {
420
- retainedBaseWrite(db, table, String(row[table.primaryKey]), Object.fromEntries(table.columns.map((column) => [
421
- column.name,
422
- rowValueToJson(row[column.name]),
423
- ])), Number(row._syncular_version));
424
- }
413
+ retainedBaseWrite(db, table, new Map(landing.map((row) => [
414
+ String(row[table.primaryKey]),
415
+ [
416
+ table.columns.map((column) => row[column.name]),
417
+ Number(row._syncular_version),
418
+ ],
419
+ ])));
425
420
  options.onChunk?.(applied);
426
421
  return rebaseScope(scope, kept, skipped);
427
422
  });
@@ -489,20 +484,24 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
489
484
  String(row.values[table.primaryKeyIndex]),
490
485
  ])),
491
486
  ];
492
- const protectedRows = restoreFailedBases(db, schema, scope);
487
+ restoreFailedBases(db, schema, scope);
493
488
  if (clearThisBlock) {
494
489
  deleteScopedRows(db, table, options.effective, options.owners());
495
490
  }
496
491
  const kept = new Set();
497
492
  const skipped = new Set();
493
+ const written = new Map();
498
494
  for (const row of rows) {
499
495
  const rowId = String(row.values[table.primaryKeyIndex]);
500
- if (lands(db, table, rowId, row.serverVersion, kept, skipped))
501
- upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows, row.sealed);
496
+ if (lands(db, table, rowId, row.serverVersion, kept, skipped)) {
497
+ upsertLocalRow(db, table, row.values, row.serverVersion, row.sealed);
498
+ written.set(rowId, [row.values, row.serverVersion]);
499
+ }
502
500
  applied += 1;
503
501
  if (applied % 1024 === 0)
504
502
  options.onProgress?.(applied);
505
503
  }
504
+ retainedBaseWrite(db, table, written);
506
505
  return rebaseScope(scope, kept, skipped);
507
506
  });
508
507
  options.onProgress?.(applied);
package/dist/blob.d.ts CHANGED
@@ -101,10 +101,6 @@ export declare function listPendingUploads(db: ClientDatabase): {
101
101
  }[];
102
102
  export declare function recordPendingUpload(db: ClientDatabase, blobId: string, nowMs: number, mediaType?: string): void;
103
103
  export declare function clearPendingUpload(db: ClientDatabase, blobId: string): void;
104
- /**
105
- * All `blob_ref` column names per table.
106
- */
107
- export declare function blobRefColumnsBySchema(schema: CompiledClientSchema): Map<string, string[]>;
108
104
  export declare function schemaHasBlobs(schema: CompiledClientSchema): boolean;
109
105
  export declare function deleteUnreferencedCachedBlobs(db: ClientDatabase, schema: CompiledClientSchema): void;
110
106
  export type { BlobRef };
package/dist/blob.js CHANGED
@@ -7,18 +7,15 @@ export const BLOB_COMMIT_REFS = '_syncular_blob_commit_refs';
7
7
  * A small upload row queues each staged body for transfer before push.
8
8
  */
9
9
  import { parseBlobRef, serializeBlobRef } from '@syncular/core';
10
- import { ClientSyncError } from './errors.js';
11
- import { quoteIdent, tableExists } from './schema.js';
10
+ import { ClientSyncError, localStateCorrupt } from './errors.js';
11
+ import { bytesToHex, quoteIdent, tableExists } from './schema.js';
12
12
  /** `"sha256:" + hex` of the bytes — the content address (§5.9.1). */
13
13
  export async function computeBlobId(bytes) {
14
14
  const input = bytes.buffer instanceof ArrayBuffer
15
15
  ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
16
16
  : bytes.slice();
17
17
  const digest = await crypto.subtle.digest('SHA-256', input);
18
- const hex = [...new Uint8Array(digest)]
19
- .map((b) => b.toString(16).padStart(2, '0'))
20
- .join('');
21
- return `sha256:${hex}`;
18
+ return `sha256:${bytesToHex(new Uint8Array(digest))}`;
22
19
  }
23
20
  export function ensureBlobSchema(db) {
24
21
  if (tableExists(db, '_syncular_blobs')) {
@@ -26,15 +23,7 @@ export function ensureBlobSchema(db) {
26
23
  .query('PRAGMA table_info(_syncular_blobs)')
27
24
  .map((row) => row.name)
28
25
  .sort();
29
- const expected = [
30
- 'blob_id',
31
- 'byte_length',
32
- 'bytes',
33
- 'created_at_ms',
34
- 'media_type',
35
- ].sort();
36
- if (columns.length !== expected.length ||
37
- columns.some((column, index) => column !== expected[index])) {
26
+ if (columns.join() !== 'blob_id,byte_length,bytes,created_at_ms,media_type') {
38
27
  throw new ClientSyncError('sync.schema_mismatch', 'Local blob schema is incompatible');
39
28
  }
40
29
  }
@@ -90,7 +79,7 @@ export function listPendingUploads(db) {
90
79
  .map((row) => {
91
80
  if (typeof row.blob_id !== 'string' ||
92
81
  (row.media_type !== null && typeof row.media_type !== 'string')) {
93
- throw new ClientSyncError('sync.local_corrupt', 'Pending blob upload metadata is invalid');
82
+ throw localStateCorrupt('Pending blob upload metadata is invalid');
94
83
  }
95
84
  return {
96
85
  blobId: row.blob_id,
@@ -107,7 +96,7 @@ export function clearPendingUpload(db, blobId) {
107
96
  /**
108
97
  * All `blob_ref` column names per table.
109
98
  */
110
- export function blobRefColumnsBySchema(schema) {
99
+ function blobRefColumnsBySchema(schema) {
111
100
  const out = new Map();
112
101
  for (const table of schema.tables.values()) {
113
102
  const cols = table.columns
@@ -119,11 +108,7 @@ export function blobRefColumnsBySchema(schema) {
119
108
  return out;
120
109
  }
121
110
  export function schemaHasBlobs(schema) {
122
- for (const table of schema.tables.values()) {
123
- if (table.columns.some((c) => c.type === 'blob_ref'))
124
- return true;
125
- }
126
- return false;
111
+ return blobRefColumnsBySchema(schema).size > 0;
127
112
  }
128
113
  /** The cached bodies no upload, pending commit, or visible row references. */
129
114
  function unreferencedBlobsSql(schema) {
package/dist/client.d.ts CHANGED
@@ -39,6 +39,12 @@ export type MutationInput = {
39
39
  readonly baseVersion?: number;
40
40
  };
41
41
  export type { CommitOperationOutcome, CommitOutcome, CommitOutcomeQuery, RetainedCommitRow, ConflictRecord, RejectionRecord, ResolveCommitOutcomeInput, } from './outcomes.js';
42
+ /** §7.2.2: without `replacement`, the decision keeps the local intent. */
43
+ export interface ReplaceCommitOutcomeInput {
44
+ readonly clientCommitId: string;
45
+ readonly sequence: number;
46
+ readonly replacement?: readonly MutationInput[] | undefined;
47
+ }
42
48
  export interface SchemaFloor {
43
49
  readonly requiredSchemaVersion?: number;
44
50
  readonly latestSchemaVersion?: number;
@@ -99,7 +105,7 @@ export interface SyncIdleResult extends SyncSummary {
99
105
  }
100
106
  export interface SyncIdleOptions {
101
107
  /** §7.8: a strict positive round count. Default: 20. */
102
- readonly maxRounds?: number;
108
+ readonly maxRounds?: number | undefined;
103
109
  /**
104
110
  * Total budget for one drive, across every round, on the client clock. A
105
111
  * drive past it after a completed round resolves with `budgetExhausted`.
@@ -108,6 +114,12 @@ export interface SyncIdleOptions {
108
114
  * `Infinity` disables the bound.
109
115
  */
110
116
  readonly timeoutMs?: number;
117
+ /**
118
+ * §8.4 host policy: end the drive without a round when the replica has no
119
+ * unit, no outbox commit, and no unit list to clear on the server. The
120
+ * shipped host loops pass it; the native bridge ignores it.
121
+ */
122
+ readonly skipEmpty?: boolean;
111
123
  }
112
124
  export type CurrentBaseProof = {
113
125
  readonly proven: true;
@@ -149,6 +161,18 @@ export interface SyncClientLimits {
149
161
  * raises `client.push_request_too_large` and stays queued.
150
162
  */
151
163
  readonly maxPushRequestBytes?: number;
164
+ /**
165
+ * §5.4: rows segment downloads one pull response runs at once. Default 4.
166
+ * SQLite images keep their own bound of two (§5.3).
167
+ */
168
+ readonly segmentPrefetch?: number;
169
+ /**
170
+ * §5.9.7 B1 blob-cache size cap (bytes). When the sum of cached body sizes
171
+ * exceeds it, unreferenced bodies without pending work are evicted oldest
172
+ * first after each cache write. Referenced bodies stay cached even past the
173
+ * cap. Absent: retain until storage pressure.
174
+ */
175
+ readonly blobCacheMaxBytes?: number;
152
176
  }
153
177
  export interface SyncClientConfig {
154
178
  /** Explicit development console registry; absent means no registration. */
@@ -162,14 +186,6 @@ export interface SyncClientConfig {
162
186
  readonly segments?: SegmentDownloader;
163
187
  /** Blob upload/download (§5.9). Required to use `uploadBlob`/`fetchBlob`. */
164
188
  readonly blobs?: BlobTransport;
165
- /**
166
- * §5.9.7 B1 blob-cache size cap (bytes). When the sum of cached body sizes
167
- * exceeds this, unreferenced bodies without pending work are evicted in
168
- * creation timestamp order after each cache write. Referenced bodies remain cached
169
- * even when that exceeds the cap. Absent means retain until storage pressure (the shipped
170
- * default; a referenced body always stays resolvable without a re-download).
171
- */
172
- readonly blobCacheMaxBytes?: number;
173
189
  readonly realtime?: RealtimeConnector;
174
190
  /**
175
191
  * SPEC §8.8: how sync rounds treat the realtime binding. `optional`
@@ -399,7 +415,7 @@ export interface SnapshotRead<Row = SqlRow> {
399
415
  */
400
416
  export declare function windowComplete(state: WindowState, unit: string): boolean;
401
417
  /** Canonical client reads, shared by synchronous cores and promise hosts. */
402
- export type ClientSnapshotMethods = Pick<SyncClient, 'querySnapshot' | 'snapshotRead' | 'statusSnapshot' | 'diagnosticsSnapshot' | 'conflicts' | 'rejections' | 'commitOutcome' | 'commitOutcomes' | 'resolveCommitOutcome'>;
418
+ export type ClientSnapshotMethods = Pick<SyncClient, 'querySnapshot' | 'snapshotRead' | 'statusSnapshot' | 'diagnosticsSnapshot' | 'conflicts' | 'rejections' | 'commitOutcome' | 'commitOutcomes' | 'resolveCommitOutcome' | 'commitDelivery'>;
403
419
  /** Project a method contract across an asynchronous host boundary. */
404
420
  export type PromiseMethods<Methods> = {
405
421
  [Key in keyof Methods]: Methods[Key] extends (...args: infer Args) => infer Result ? (...args: Args) => Promise<Awaited<Result>> : never;
@@ -564,6 +580,11 @@ export declare class SyncClient {
564
580
  * dismissed. The transition is one-way and survives restart.
565
581
  */
566
582
  resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome;
583
+ /**
584
+ * §7.2.2: record a decision against an active failure as a held
585
+ * replacement commit, written once a later drive proves its base.
586
+ */
587
+ replaceCommitOutcome(input: ReplaceCommitOutcomeInput): string;
567
588
  /** True when syncing is stopped pending a client upgrade. */
568
589
  get stopped(): boolean;
569
590
  /**