@syncular/client 0.86.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 (45) hide show
  1. package/README.md +3 -1
  2. package/dist/blob.d.ts +0 -4
  3. package/dist/blob.js +7 -22
  4. package/dist/client.d.ts +12 -1
  5. package/dist/client.js +441 -422
  6. package/dist/diagnostics.d.ts +2 -4
  7. package/dist/diagnostics.js +3 -17
  8. package/dist/encryption.js +2 -21
  9. package/dist/errors.d.ts +2 -0
  10. package/dist/errors.js +4 -0
  11. package/dist/failed-overlay.js +2 -2
  12. package/dist/local-purge.d.ts +1 -0
  13. package/dist/local-purge.js +1 -1
  14. package/dist/local-rebootstrap-receipt.js +2 -2
  15. package/dist/local-rebootstrap.js +1 -1
  16. package/dist/native-bridge.d.ts +6 -2
  17. package/dist/native-bridge.js +24 -11
  18. package/dist/outcomes.d.ts +11 -0
  19. package/dist/outcomes.js +19 -16
  20. package/dist/previous-version.js +23 -35
  21. package/dist/schema.js +14 -13
  22. package/dist/state.d.ts +16 -4
  23. package/dist/state.js +83 -44
  24. package/dist/worker-core.js +7 -8
  25. package/dist/worker-host.d.ts +5 -2
  26. package/dist/worker-host.js +9 -0
  27. package/dist/worker-protocol.d.ts +2 -1
  28. package/package.json +3 -3
  29. package/src/blob.ts +7 -24
  30. package/src/client.ts +615 -501
  31. package/src/diagnostics.ts +3 -19
  32. package/src/encryption.ts +7 -25
  33. package/src/errors.ts +5 -0
  34. package/src/failed-overlay.ts +2 -6
  35. package/src/local-purge.ts +1 -1
  36. package/src/local-rebootstrap-receipt.ts +2 -5
  37. package/src/local-rebootstrap.ts +1 -2
  38. package/src/native-bridge.ts +35 -13
  39. package/src/outcomes.ts +34 -25
  40. package/src/previous-version.ts +31 -40
  41. package/src/schema.ts +13 -13
  42. package/src/state.ts +107 -64
  43. package/src/worker-core.ts +9 -16
  44. package/src/worker-host.ts +17 -1
  45. package/src/worker-protocol.ts +2 -0
@@ -6,6 +6,7 @@
6
6
  * diagnostic prose.
7
7
  */
8
8
  import type { SecurityLifecycle } from './client.js';
9
+ import { ChangeEmitter } from './invalidation.js';
9
10
  export declare const CLIENT_DIAGNOSTICS_VERSION: 2;
10
11
  export declare const MAX_DIAGNOSTIC_DOMAINS = 256;
11
12
  export declare const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
@@ -147,11 +148,8 @@ export interface ClientDiagnosticsSnapshot {
147
148
  readonly queryFailures: readonly DiagnosticQueryFailure[];
148
149
  }
149
150
  export type ClientDiagnosticsListener = (snapshot: ClientDiagnosticsSnapshot) => void;
150
- export declare class ClientDiagnosticsEmitter {
151
- #private;
151
+ export declare class ClientDiagnosticsEmitter extends ChangeEmitter<ClientDiagnosticsSnapshot> {
152
152
  get observed(): boolean;
153
- on(listener: ClientDiagnosticsListener): () => void;
154
- emit(snapshot: ClientDiagnosticsSnapshot): void;
155
153
  }
156
154
  /** Host wrappers replace topology facts without changing core evidence. */
157
155
  export declare function withClientDiagnosticsHost(snapshot: ClientDiagnosticsSnapshot, host: ClientDiagnosticsHost): ClientDiagnosticsSnapshot;
@@ -1,24 +1,10 @@
1
+ import { ChangeEmitter } from './invalidation.js';
1
2
  export const CLIENT_DIAGNOSTICS_VERSION = 2;
2
3
  export const MAX_DIAGNOSTIC_DOMAINS = 256;
3
4
  export const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
4
- export class ClientDiagnosticsEmitter {
5
- #listeners = new Set();
5
+ export class ClientDiagnosticsEmitter extends ChangeEmitter {
6
6
  get observed() {
7
- return this.#listeners.size > 0;
8
- }
9
- on(listener) {
10
- this.#listeners.add(listener);
11
- return () => this.#listeners.delete(listener);
12
- }
13
- emit(snapshot) {
14
- for (const listener of this.#listeners) {
15
- try {
16
- listener(snapshot);
17
- }
18
- catch {
19
- // Diagnostics observers cannot alter sync correctness.
20
- }
21
- }
7
+ return this.size > 0;
22
8
  }
23
9
  }
24
10
  /** Host wrappers replace topology facts without changing core evidence. */
@@ -66,22 +66,10 @@ function declaredTypeOf(column) {
66
66
  * unencrypted (§5.11).
67
67
  */
68
68
  export async function encryptRowValues(config, table, rowId, values, storedKeyId) {
69
- if (!table.hasEncryptedColumns)
70
- return values.slice();
71
69
  const out = values.slice();
72
70
  // Sparse semantics: absent (undefined) and NULL columns are never
73
71
  // re-encrypted, so a patch that presents no encrypted value needs no key.
74
- let hasPresentEncrypted = false;
75
- for (let i = 0; i < table.columns.length; i++) {
76
- if (table.columns[i]?.encrypted !== true)
77
- continue;
78
- const value = out[i];
79
- if (value !== undefined && value !== null) {
80
- hasPresentEncrypted = true;
81
- break;
82
- }
83
- }
84
- if (!hasPresentEncrypted)
72
+ if (!table.columns.some((column, i) => column.encrypted && out[i] != null))
85
73
  return out;
86
74
  if (config === undefined) {
87
75
  throw new EncryptError('encrypted columns need an encryption config');
@@ -156,8 +144,6 @@ export async function decryptOrSealRowValues(config, table, values) {
156
144
  * wrong key or malformed envelope throws `client.decrypt_failed` (§5.11).
157
145
  */
158
146
  export async function decryptRowValues(config, table, values) {
159
- if (!table.hasEncryptedColumns)
160
- return values.slice();
161
147
  const out = values.slice();
162
148
  for (let i = 0; i < table.columns.length; i++) {
163
149
  const column = table.columns[i];
@@ -172,12 +158,7 @@ export async function decryptRowValues(config, table, values) {
172
158
  if (config === undefined) {
173
159
  throw new DecryptError('encrypted columns need an encryption config');
174
160
  }
175
- out[i] = deserializeGuard(await decryptValue(declaredTypeOf(column), value, config.keyProvider, table.name));
161
+ out[i] = await decryptValue(declaredTypeOf(column), value, config.keyProvider, table.name);
176
162
  }
177
163
  return out;
178
164
  }
179
- // decryptValue already returns a PlainValue; RowValue is a superset, so this
180
- // is just the type widening (kept explicit for clarity at the seam).
181
- function deserializeGuard(value) {
182
- return value;
183
- }
package/dist/errors.d.ts CHANGED
@@ -33,6 +33,8 @@ export declare class ClientSyncError extends Error {
33
33
  readonly recommendedAction: string | undefined;
34
34
  constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>, recommendedAction?: string);
35
35
  }
36
+ /** `sync.local_corrupt`: persisted local state this client cannot read. */
37
+ export declare function localStateCorrupt(message: string): ClientSyncError;
36
38
  /** Shared invalid-request construction for client validators and transport guards. */
37
39
  export declare function invalidRequest(message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>): ClientSyncError;
38
40
  /** Shared retryable `sync.transport_failed` construction for client transports. */
package/dist/errors.js CHANGED
@@ -39,6 +39,10 @@ export class ClientSyncError extends Error {
39
39
  this.recommendedAction = recommendedAction;
40
40
  }
41
41
  }
42
+ /** `sync.local_corrupt`: persisted local state this client cannot read. */
43
+ export function localStateCorrupt(message) {
44
+ return new ClientSyncError('sync.local_corrupt', message);
45
+ }
42
46
  /** Shared invalid-request construction for client validators and transport guards. */
43
47
  export function invalidRequest(message, retryable = false, details) {
44
48
  return new ClientSyncError('sync.invalid_request', message, retryable, details);
@@ -2,7 +2,7 @@ import { hasUniqueIndex } from './schema.js';
2
2
  import { OUTCOMES_TABLE } from './outcomes.js';
3
3
  import { OUTBOX_IMAGES } from './outbox.js';
4
4
  export const RETAINED_ROWS = '_syncular_failed_rows';
5
- import { ClientSyncError } from './errors.js';
5
+ import { localStateCorrupt } from './errors.js';
6
6
  import { mapRowValues, fromSqlValue, jsonToRowValue, pkSqlValue, quoteIdent, rowValueToJson, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
7
7
  import { deleteLocalRow, upsertLocalRow } from './apply.js';
8
8
  /** Protected failure state. The server base advances independently of intent. */
@@ -70,7 +70,7 @@ export function retainFailedRows(db, commit, images, commitSeq) {
70
70
  ? { ...image?.values, ...operation.values }
71
71
  : undefined;
72
72
  if (!image)
73
- throw new ClientSyncError('sync.local_corrupt', 'missing intent before-image');
73
+ throw localStateCorrupt('missing intent before-image');
74
74
  db.exec(`INSERT INTO ${RETAINED_ROWS}(commit_id,idx,tbl,id,at,op,intent,base,version,commit_seq)VALUES(?,?,?,?,?,?,?,?,?,?)`, [
75
75
  commit.clientCommitId,
76
76
  index,
@@ -8,6 +8,7 @@
8
8
  * generated FTS projections, doomed optimistic commits, and blob references.
9
9
  */
10
10
  import type { CompiledClientSchema, CompiledClientTable } from './schema.js';
11
+ export declare const CODE_LIKE_VALUE: RegExp;
11
12
  /** One AND-combined selector set. Targets are OR-combined. */
12
13
  export interface LocalDataPurgeTarget {
13
14
  readonly table: string;
@@ -12,7 +12,7 @@ const MAX_TARGETS = 64;
12
12
  const MAX_SELECTORS_PER_TARGET = 8;
13
13
  const MAX_VALUES_PER_SELECTOR = 128;
14
14
  const MAX_ROUTING_VALUE_LENGTH = 256;
15
- const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
15
+ export const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
16
16
  function compareCodeLike(left, right) {
17
17
  return left < right ? -1 : left > right ? 1 : 0;
18
18
  }
@@ -1,4 +1,4 @@
1
- import { ClientSyncError } from './errors.js';
1
+ import { localStateCorrupt } from './errors.js';
2
2
  const LEGACY_MARKER = 'v1';
3
3
  const RECEIPT_VERSION = 2;
4
4
  const RECEIPT_KEYS = [
@@ -7,7 +7,7 @@ const RECEIPT_KEYS = [
7
7
  'version',
8
8
  ];
9
9
  function invalidReceipt() {
10
- throw new ClientSyncError('sync.local_corrupt', 'persisted local rebootstrap receipt is invalid');
10
+ throw localStateCorrupt('persisted local rebootstrap receipt is invalid');
11
11
  }
12
12
  function isCount(value) {
13
13
  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
@@ -7,7 +7,7 @@
7
7
  * projection state so the registered subscriptions can bootstrap it again.
8
8
  */
9
9
  import { ClientSyncError, invalidRequest } from './errors.js';
10
- const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
10
+ import { CODE_LIKE_VALUE } from './local-purge.js';
11
11
  const RESULT_KEYS = [
12
12
  'alreadyApplied',
13
13
  'resetSubscriptions',
@@ -11,7 +11,7 @@
11
11
  * `{$bigint: decimal}`, the convention of the Rust command router. The browser
12
12
  * client and worker entries never import this module.
13
13
  */
14
- import { type ClientSnapshotMethods, type CurrentBaseProof, type MutationInput, type PresencePeer, type PromiseMethods, type QueryReadSpec, type QuerySnapshot, type SecurityLifecycle, type SnapshotRead, type SnapshotReadRequest, type SyncClient, type SyncClientConfig, type SyncIdleOptions, type UnitCatchup, type WindowState } from './client.js';
14
+ import { type ClientSnapshotMethods, type CommitDelivery, type CurrentBaseProof, type MutationInput, type ReplaceCommitOutcomeInput, type PresencePeer, type PromiseMethods, type QueryReadSpec, type QuerySnapshot, type SecurityLifecycle, type SnapshotRead, type SnapshotReadRequest, type SyncClient, type SyncClientConfig, type SyncIdleOptions, type UnitCatchup, type WindowState } from './client.js';
15
15
  import type { SqlRow, SqlValue } from './database.js';
16
16
  import type { PresenceErrorCode, UnitScopes } from '@syncular/core';
17
17
  export { unitId, type UnitScopes } from '@syncular/core';
@@ -24,6 +24,7 @@ import type { CommitOutcome, CommitOutcomeQuery, ConflictRecord, RejectionRecord
24
24
  import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
25
25
  import { type SyncProgress, type SyncProgressListener } from './progress.js';
26
26
  import type { UnitRecord } from './state.js';
27
+ import type { OutboxCommit } from './outbox.js';
27
28
  import type { WindowBase } from './window.js';
28
29
  /** A driver-protocol reply: `{result}` on success or `{error}` on failure. */
29
30
  export interface NativeReply {
@@ -213,6 +214,8 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
213
214
  unit(id: string): Promise<UnitRecord | undefined>;
214
215
  /** §7.5: one unit's persisted catch-up state (never the owner cache). */
215
216
  unitCatchup(id: string): Promise<UnitCatchup>;
217
+ /** §7.5: one client commit's delivery status, from the same snapshot read. */
218
+ commitDelivery(id: string): Promise<CommitDelivery>;
216
219
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
217
220
  windowState(base: WindowBase): Promise<WindowState>;
218
221
  sync(): Promise<unknown>;
@@ -224,7 +227,8 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
224
227
  commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
225
228
  commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
226
229
  resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
227
- pendingCommits(): Promise<unknown[]>;
230
+ replaceCommitOutcome({ clientCommitId, sequence, replacement, }: ReplaceCommitOutcomeInput): Promise<string>;
231
+ pendingCommits(): Promise<OutboxCommit[]>;
228
232
  presence(scopeKey: string): Promise<readonly PresencePeer[]>;
229
233
  setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
230
234
  connectRealtime(): Promise<void>;
@@ -496,7 +496,7 @@ export class NativeBridgeClient {
496
496
  sql: spec.sql,
497
497
  params: encodeValue(spec.params ?? []),
498
498
  coverage: spec.coverage ?? [],
499
- ...(spec.owner !== undefined ? { owner: spec.owner } : {}),
499
+ owner: spec.owner,
500
500
  })));
501
501
  return {
502
502
  revision: BigInt(result.revision),
@@ -517,7 +517,7 @@ export class NativeBridgeClient {
517
517
  coverage: request.coverage ?? [],
518
518
  units: request.units ?? [],
519
519
  commitIds: request.commitIds ?? [],
520
- ...(request.owner !== undefined ? { owner: request.owner } : {}),
520
+ owner: request.owner,
521
521
  }));
522
522
  return {
523
523
  revision: BigInt(result.revision),
@@ -660,10 +660,8 @@ export class NativeBridgeClient {
660
660
  async uploadBlob(bytes, options) {
661
661
  const result = (await this.command('uploadBlob', {
662
662
  bytes: encodeValue(bytes),
663
- ...(options?.mediaType !== undefined
664
- ? { mediaType: options.mediaType }
665
- : {}),
666
- ...(options?.name !== undefined ? { name: options.name } : {}),
663
+ mediaType: options?.mediaType,
664
+ name: options?.name,
667
665
  }));
668
666
  return result.ref;
669
667
  }
@@ -709,6 +707,11 @@ export class NativeBridgeClient {
709
707
  async unitCatchup(id) {
710
708
  return (await this.snapshotRead({ statements: [], units: [id] })).units[0];
711
709
  }
710
+ /** §7.5: one client commit's delivery status, from the same snapshot read. */
711
+ async commitDelivery(id) {
712
+ return (await this.snapshotRead({ statements: [], commitIds: [id] }))
713
+ .deliveries[0];
714
+ }
712
715
  async setWindow(base, units) {
713
716
  await this.command('setWindow', { base, units });
714
717
  }
@@ -725,8 +728,8 @@ export class NativeBridgeClient {
725
728
  if (typeof options === 'object')
726
729
  timeoutMs = options.timeoutMs;
727
730
  return this.command('syncUntilIdle', {
728
- ...(maxRounds !== undefined ? { maxRounds } : {}),
729
- ...(timeoutMs !== undefined ? { timeoutMs } : {}),
731
+ maxRounds,
732
+ timeoutMs,
730
733
  });
731
734
  }
732
735
  async proveCurrentBase(outcome, maxRounds) {
@@ -738,7 +741,7 @@ export class NativeBridgeClient {
738
741
  clientCommitId: outcome.clientCommitId,
739
742
  sequence: outcome.sequence,
740
743
  },
741
- ...(maxRounds !== undefined ? { maxRounds } : {}),
744
+ maxRounds,
742
745
  }));
743
746
  return proof.proven
744
747
  ? { proven: true, rows: this.#retainedRows(proof.rows) }
@@ -770,9 +773,19 @@ export class NativeBridgeClient {
770
773
  }));
771
774
  return this.#commitOutcome(result.outcome);
772
775
  }
776
+ async replaceCommitOutcome({ clientCommitId, sequence, replacement, }) {
777
+ const result = (await this.command('replaceCommitOutcome', {
778
+ clientCommitId,
779
+ sequence,
780
+ ...(replacement === undefined
781
+ ? {}
782
+ : { replacement: encodeValue(replacement) }),
783
+ }));
784
+ return result.clientCommitId;
785
+ }
773
786
  async pendingCommits() {
774
- const result = (await this.command('pendingCommitIds', {}));
775
- return result.ids;
787
+ const result = (await this.command('pendingCommits', {}));
788
+ return result.commits;
776
789
  }
777
790
  async presence(scopeKey) {
778
791
  const result = (await this.command('presence', { scopeKey }));
@@ -84,8 +84,19 @@ export interface CommitOutcome {
84
84
  readonly retainedRows?: readonly RetainedCommitRow[];
85
85
  readonly resolution: CommitOutcomeResolution;
86
86
  readonly resolvedAtMs?: number;
87
+ /**
88
+ * The replacement commit of a `superseded` outcome; on an `active`
89
+ * outcome, the replacement of a pending decision (§7.2.2).
90
+ */
87
91
  readonly replacementClientCommitId?: string;
88
92
  }
93
+ export interface PendingDecision {
94
+ readonly clientCommitId: string;
95
+ readonly sequence: number;
96
+ readonly replacementClientCommitId: string;
97
+ }
98
+ /** §7.2.2: active outcomes whose replacement waits for a proven base. */
99
+ export declare function pendingDecisions(db: ClientDatabase): PendingDecision[];
89
100
  export interface CommitOutcomeQuery {
90
101
  /** Newest-first result cap. Defaults to all retained entries. */
91
102
  readonly limit?: number;
package/dist/outcomes.js CHANGED
@@ -10,8 +10,18 @@ import { RETAINED_ROWS } from './failed-overlay.js';
10
10
  * deliberately stay local; retention never deletes an unresolved failure.
11
11
  */
12
12
  import { normalizeRejectionDetails, } from '@syncular/core';
13
- import { ClientSyncError, invalidRequest } from './errors.js';
13
+ import { invalidRequest, localStateCorrupt } from './errors.js';
14
14
  import { isBytesEnvelope, mapRowValues, jsonToRowValue, rowValueToJson, } from './schema.js';
15
+ /** §7.2.2: active outcomes whose replacement waits for a proven base. */
16
+ export function pendingDecisions(db) {
17
+ return db
18
+ .query(`SELECT seq,client_commit_id,replacement_client_commit_id FROM ${OUTCOMES_TABLE} WHERE resolution='active' AND replacement_client_commit_id IS NOT NULL`)
19
+ .map((row) => ({
20
+ clientCommitId: row.client_commit_id,
21
+ sequence: row.seq,
22
+ replacementClientCommitId: row.replacement_client_commit_id,
23
+ }));
24
+ }
15
25
  function encodeResults(results) {
16
26
  const stored = results.map((result) => {
17
27
  if (result.status !== 'conflict')
@@ -51,10 +61,12 @@ export function isStoredOperation(value) {
51
61
  value.values === undefined &&
52
62
  value.insert === undefined)));
53
63
  }
64
+ function corrupt() {
65
+ throw localStateCorrupt('persisted commit outcome is invalid');
66
+ }
54
67
  function decodeResults(raw) {
55
- function corrupt() {
56
- throw new ClientSyncError('sync.local_corrupt', 'persisted commit outcome is invalid');
57
- }
68
+ // §6.1 op indexes are i32.
69
+ const badIndex = (index) => !Number.isInteger(index) || index < -2147483648 || index > 2147483647;
58
70
  const stored = JSON.parse(raw);
59
71
  if (!Array.isArray(stored))
60
72
  corrupt();
@@ -62,9 +74,7 @@ function decodeResults(raw) {
62
74
  if (!isRecord(result))
63
75
  corrupt();
64
76
  if (result.status === 'applied') {
65
- if (!Number.isInteger(result.opIndex) ||
66
- result.opIndex < -2147483648 ||
67
- result.opIndex > 2147483647)
77
+ if (badIndex(result.opIndex))
68
78
  corrupt();
69
79
  return result;
70
80
  }
@@ -73,9 +83,7 @@ function decodeResults(raw) {
73
83
  if (!isRecord(conflict) ||
74
84
  !isStoredRow(conflict.serverRow) ||
75
85
  typeof conflict.clientCommitId !== 'string' ||
76
- !Number.isInteger(conflict.opIndex) ||
77
- conflict.opIndex < -2147483648 ||
78
- conflict.opIndex > 2147483647 ||
86
+ badIndex(conflict.opIndex) ||
79
87
  typeof conflict.table !== 'string' ||
80
88
  typeof conflict.rowId !== 'string' ||
81
89
  typeof conflict.code !== 'string' ||
@@ -102,9 +110,7 @@ function decodeResults(raw) {
102
110
  const rejection = result.rejection;
103
111
  if (!isRecord(rejection) ||
104
112
  typeof rejection.clientCommitId !== 'string' ||
105
- !Number.isInteger(rejection.opIndex) ||
106
- rejection.opIndex < -2147483648 ||
107
- rejection.opIndex > 2147483647 ||
113
+ badIndex(rejection.opIndex) ||
108
114
  typeof rejection.code !== 'string' ||
109
115
  typeof rejection.message !== 'string' ||
110
116
  typeof rejection.retryable !== 'boolean' ||
@@ -206,9 +212,6 @@ export function persistedCommitOutcome(db, clientCommitId) {
206
212
  const row = outcomeRow(db, clientCommitId);
207
213
  if (row === undefined)
208
214
  return undefined;
209
- function corrupt() {
210
- throw new ClientSyncError('sync.local_corrupt', 'persisted commit outcome is invalid');
211
- }
212
215
  const status = row.status;
213
216
  const resolution = row.resolution;
214
217
  if ((status !== 'applied' &&
@@ -1,6 +1,6 @@
1
- import { ClientSyncError } from './errors.js';
1
+ import { ClientSyncError, localStateCorrupt } from './errors.js';
2
2
  import { INVALID_HOST_RESPONSE_CODE } from './local-rebootstrap.js';
3
- import { fromSqlValue, jsonToRowValue, localColumnType, quoteIdent, rowValueToJson, tableExists, } from './schema.js';
3
+ import { bytesToHex, fromSqlValue, jsonToRowValue, localColumnType, quoteIdent, rowValueToJson, tableExists, } from './schema.js';
4
4
  import { getMeta, setMeta, META_TABLE } from './state.js';
5
5
  /** `_syncular_meta` key holding the persisted {@link LocalSchemaDescriptor}. */
6
6
  const LOCAL_SCHEMA_DESCRIPTOR_KEY = 'localSchemaDescriptor';
@@ -94,7 +94,7 @@ function hasExactKeys(record, expected) {
94
94
  expected.every((key) => Object.hasOwn(record, key)));
95
95
  }
96
96
  function localCorrupt(what) {
97
- throw new ClientSyncError('sync.local_corrupt', `persisted ${what} is invalid`);
97
+ throw localStateCorrupt(`persisted ${what} is invalid`);
98
98
  }
99
99
  // ---------------------------------------------------------------------------
100
100
  // Descriptor (D1)
@@ -382,12 +382,7 @@ function rowIdText(table, row) {
382
382
  const value = row[table.primaryKey] ?? null;
383
383
  if (value === null)
384
384
  return '';
385
- if (value instanceof Uint8Array) {
386
- return [...value]
387
- .map((byte) => byte.toString(16).padStart(2, '0'))
388
- .join('');
389
- }
390
- return String(value);
385
+ return value instanceof Uint8Array ? bytesToHex(value) : String(value);
391
386
  }
392
387
  function decodePreviousVersionPayload(table, payload) {
393
388
  const record = parseJsonObject(payload);
@@ -490,36 +485,29 @@ function firstIncompatibility(schema, commit) {
490
485
  if (operation.op === 'delete')
491
486
  continue;
492
487
  const table = schema.tables.get(operation.table);
493
- if (table === undefined) {
488
+ const column = table &&
489
+ Object.keys(operation.values ?? {}).find((key) => !table.columnIndex.has(key));
490
+ // §7.1: an insert-intent operation presents every current column, so a
491
+ // non-nullable column it lacks leaves the commit unencodable.
492
+ const missing = operation.insert === true
493
+ ? table?.columns.find((entry) => !entry.nullable && operation.values?.[entry.name] === undefined)
494
+ : undefined;
495
+ const refusal = table === undefined
496
+ ? { reason: 'unknown-table' }
497
+ : column !== undefined
498
+ ? { reason: 'unknown-column', column }
499
+ : missing !== undefined
500
+ ? {
501
+ reason: 'missing-required-column',
502
+ column: missing.name,
503
+ }
504
+ : undefined;
505
+ if (refusal !== undefined)
494
506
  return {
495
507
  commitId: commit.clientCommitId,
496
508
  table: operation.table,
497
- reason: 'unknown-table',
509
+ ...refusal,
498
510
  };
499
- }
500
- for (const key of Object.keys(operation.values ?? {})) {
501
- if (!table.columnIndex.has(key)) {
502
- return {
503
- commitId: commit.clientCommitId,
504
- table: operation.table,
505
- reason: 'unknown-column',
506
- column: key,
507
- };
508
- }
509
- }
510
- // §7.1: an insert-intent operation presents every current column, so a
511
- // non-nullable column it lacks leaves the commit unencodable.
512
- if (operation.insert === true) {
513
- const missing = table.columns.find((column) => !column.nullable && operation.values?.[column.name] === undefined);
514
- if (missing !== undefined) {
515
- return {
516
- commitId: commit.clientCommitId,
517
- table: operation.table,
518
- reason: 'missing-required-column',
519
- column: missing.name,
520
- };
521
- }
522
- }
523
511
  }
524
512
  return undefined;
525
513
  }
package/dist/schema.js CHANGED
@@ -5,7 +5,7 @@ import { OUTBOX_TABLE, OUTBOX_IMAGES } from './outbox.js';
5
5
  import { OUTCOMES_TABLE } from './outcomes.js';
6
6
  import { META_TABLE, pruneUnknownUnits, resetUnits, UNITS_TABLE, } from './state.js';
7
7
  import { ensureFailedOverlaySchema, RETAINED_ROWS } from './failed-overlay.js';
8
- import { ClientSyncError, invalidRequest } from './errors.js';
8
+ import { invalidRequest, localStateCorrupt } from './errors.js';
9
9
  import { snakeToCamel } from './naming.js';
10
10
  const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
11
11
  const ALLOWED_FTS_TOKENIZERS = new Set([
@@ -239,11 +239,10 @@ function sqlType(column) {
239
239
  case 'blob_ref':
240
240
  return 'TEXT';
241
241
  case 'integer':
242
+ case 'boolean':
242
243
  return 'INTEGER';
243
244
  case 'float':
244
245
  return 'REAL';
245
- case 'boolean':
246
- return 'INTEGER';
247
246
  case 'bytes':
248
247
  case 'crdt':
249
248
  // §5.10: a crdt column stores its opaque bytes locally, exactly like
@@ -478,13 +477,15 @@ export function ensureLocalBookkeepingSchema(db) {
478
477
  }
479
478
  db.exec(`CREATE INDEX IF NOT EXISTS ${OUTCOMES_TABLE}_resolution_seq ON ${OUTCOMES_TABLE}(resolution,seq)`);
480
479
  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");
481
- // §5.6 applied-segment record, added after the table shipped.
482
- try {
483
- db.exec(`ALTER TABLE ${UNITS_TABLE} ADD COLUMN applied TEXT`);
484
- }
485
- catch {
486
- // column already exists
487
- }
480
+ // §5.6 applied-segment record and §7.4.3 restriction, added after the
481
+ // table shipped.
482
+ for (const column of ['applied', 'restriction'])
483
+ try {
484
+ db.exec(`ALTER TABLE ${UNITS_TABLE} ADD COLUMN ${column} TEXT`);
485
+ }
486
+ catch {
487
+ // column already exists
488
+ }
488
489
  // §4.8 window registry: base + value → the unit it holds, the
489
490
  // completeness oracle and one of a unit's references (§4.1).
490
491
  createTable(WINDOWS_TABLE, 'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)');
@@ -498,7 +499,7 @@ export function ensureLocalBookkeepingSchema(db) {
498
499
  const legacyEvictions = '_syncular_window_pending_evict';
499
500
  if (tableExists(db, legacyEvictions)) {
500
501
  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)
501
- throw new ClientSyncError('sync.local_corrupt', 'a version 3 pending eviction cannot be upgraded');
502
+ throw localStateCorrupt('a version 3 pending eviction cannot be upgraded');
502
503
  db.exec(`INSERT OR REPLACE INTO ${PENDING_EVICTIONS} SELECT sub_id,tbl,effective_scopes FROM ${legacyEvictions}`);
503
504
  db.exec(`DROP TABLE ${legacyEvictions}`);
504
505
  db.exec('DROP TABLE IF EXISTS _syncular_subscriptions');
@@ -530,7 +531,7 @@ const RESERVED_TABLE_PREFIX = '_syncular_';
530
531
  export function resetLocalReplica(db, schema, bump = false) {
531
532
  const kept = bump
532
533
  ? pruneUnknownUnits(db, schema, true)
533
- : { tables: new Set(), units: [] };
534
+ : { tables: new Set(), units: [], restricts: undefined };
534
535
  const keptNames = [...kept.tables];
535
536
  db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl NOT IN(${keptNames.map(() => '?')})`, keptNames);
536
537
  // Drop virtual tables first. SQLite then removes their shadow tables as one
@@ -550,7 +551,7 @@ export function resetLocalReplica(db, schema, bump = false) {
550
551
  for (const table of schema.tables.values())
551
552
  for (const index of table.ftsIndexes)
552
553
  createFtsProjection(db, table, index);
553
- resetUnits(db, kept.units);
554
+ resetUnits(db, kept.units, kept.restricts);
554
555
  return [...schema.tables.keys()].filter((name) => !kept.tables.has(name));
555
556
  }
556
557
  // ---------------------------------------------------------------------------
package/dist/state.d.ts CHANGED
@@ -7,7 +7,7 @@ export declare const UNITS_TABLE = "_syncular_units";
7
7
  * contract is keyed on. The replica cursor, the echo digest and the
8
8
  * registration digest the server holds live in meta.
9
9
  */
10
- import type { FencedRecord, ScopeMap, UnitScopes } from '@syncular/core';
10
+ import { type FencedRecord, type ScopeMap, type UnitScopes } from '@syncular/core';
11
11
  import type { CompiledClientSchema, CompiledClientTable } from './schema.js';
12
12
  import type { ClientDatabase } from './database.js';
13
13
  import type { LocalRevision } from './invalidation.js';
@@ -41,6 +41,12 @@ export interface UnitRecord {
41
41
  /** §5.6 applied-segment record: segment id → rows applied at the unit's
42
42
  * current cursor and token. */
43
43
  readonly applied?: Readonly<Record<string, number>> | undefined;
44
+ /** §7.4.3 restriction: the kept cursor and the tables to bootstrap. */
45
+ readonly restrict?: Restriction | undefined;
46
+ }
47
+ export interface Restriction {
48
+ readonly cursor: number;
49
+ readonly tables: readonly string[];
44
50
  }
45
51
  /** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
46
52
  export declare function bootstrapping(unit: UnitRecord): boolean;
@@ -55,8 +61,12 @@ export declare function covers(table: CompiledClientTable, scopes: UnitScopes):
55
61
  */
56
62
  export declare function pairScopes(scopes: UnitScopes, table: string, echo: readonly FencedRecord[] | undefined): ScopeMap | undefined;
57
63
  /** §3.3 row ownership: the pair scopes of every owner of `table` but one.
58
- * A bootstrapping unit owns the tables its current bootstrap seeded. */
64
+ * A bootstrapping unit owns the tables its current bootstrap seeded, and a
65
+ * restricted one the tables outside its restriction. */
59
66
  export declare function unitOwners(units: readonly UnitRecord[], table: CompiledClientTable, exceptId: string): ScopeMap[];
67
+ /** A unit row; every persisted field must have its stored type and shape,
68
+ * otherwise the row is `sync.local_corrupt` (§7.5). */
69
+ export declare const unitStateCorrupt: () => import("./errors.js").ClientSyncError;
60
70
  /** Every unit in registration order (§4.1). */
61
71
  export declare function loadUnits(db: ClientDatabase): UnitRecord[];
62
72
  export declare function getUnit(db: ClientDatabase, id: string): UnitRecord | undefined;
@@ -71,10 +81,11 @@ export declare function deleteUnit(db: ClientDatabase, id: string): void;
71
81
  * §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
72
82
  * registrations (the app's declared intent) and discard the synced state of
73
83
  * every unit outside `keep`, so the next round sends the list and
74
- * fresh-bootstraps those units. The replica cursor survives only while a
84
+ * fresh-bootstraps those units. A bump (`restricts` given) keeps every echo
85
+ * and restricts the units it names. The replica cursor survives only while a
75
86
  * kept unit is live. Caller owns the transaction.
76
87
  */
77
- export declare function resetUnits(db: ClientDatabase, keep?: readonly string[]): void;
88
+ export declare function resetUnits(db: ClientDatabase, keep?: readonly string[], restricts?: ReadonlyMap<string, Restriction>): void;
78
89
  /** §4.5: the replica cursor, `-1` while no unit is live. */
79
90
  export declare function replicaCursor(db: ClientDatabase): number;
80
91
  /** §7.4.3 declaration evidence and table generations, persisted beside the
@@ -91,6 +102,7 @@ export declare function saveUnitScopeSchema(db: ClientDatabase, schema: Compiled
91
102
  export declare function pruneUnknownUnits(db: ClientDatabase, schema: CompiledClientSchema, bump?: boolean): {
92
103
  readonly tables: ReadonlySet<string>;
93
104
  readonly units: string[];
105
+ readonly restricts: Map<string, Restriction>;
94
106
  };
95
107
  export declare function getMeta(db: ClientDatabase, key: string): string | undefined;
96
108
  export declare function setMeta(db: ClientDatabase, key: string, value: string): void;