@syncular/client 0.67.3 → 0.69.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.
package/dist/apply.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { hasUniqueIndex } from './schema.js';
2
- import { OUTBOX_IMAGES, countOutbox } from './outbox.js';
2
+ import { chainsOn, countOutbox, listOutbox, OUTBOX_IMAGES, OUTBOX_TABLE, } from './outbox.js';
3
3
  import { RETAINED_ROWS } from './failed-overlay.js';
4
4
  import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
5
5
  /**
@@ -108,6 +108,18 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
108
108
  const { rowId, rowVersion } = frame.changes[index];
109
109
  const land = lands(db, change.table, rowId, rowVersion, kept, skipped);
110
110
  db.exec(`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`, [frame.commitSeq, change.table.name, rowId]);
111
+ // §7.1 chained base: this change names the version an acknowledged own
112
+ // commit wrote; pending upserts chained on it move to that version.
113
+ for (const { op } of db.query(`SELECT op FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq=?`, [change.table.name, rowId, frame.commitSeq])) {
114
+ const earlier = JSON.parse(op);
115
+ for (const commit of listOutbox(db, scope))
116
+ db.exec(`UPDATE ${OUTBOX_TABLE} SET operations=? WHERE seq=?`, [
117
+ JSON.stringify(commit.operations.map((operation) => chainsOn(earlier, operation)
118
+ ? { ...operation, baseVersion: rowVersion }
119
+ : operation)),
120
+ commit.seq,
121
+ ]);
122
+ }
111
123
  db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [change.table.name, rowId, frame.commitSeq]);
112
124
  if (!land)
113
125
  continue;
package/dist/client.d.ts CHANGED
@@ -630,11 +630,16 @@ export declare class SyncClient {
630
630
  /**
631
631
  * Record one atomic local commit (§7.1): appended to the outbox in
632
632
  * schema-agnostic form and applied optimistically to the local mirror.
633
- * Returns the generated `clientCommitId`.
633
+ * Returns the generated `clientCommitId`, or the caller's unused one
634
+ * (`client.commit_id_reused` when this replica holds it).
634
635
  */
635
- mutate(mutations: readonly MutationInput[]): string;
636
+ mutate(mutations: readonly MutationInput[], options?: {
637
+ readonly clientCommitId?: string;
638
+ }): string;
636
639
  /** Host-facing mutation result with explicit network work intent (§7.5). */
637
- mutateCommand(mutations: readonly MutationInput[]): CommandResult<string>;
640
+ mutateCommand(mutations: readonly MutationInput[], options?: {
641
+ readonly clientCommitId?: string;
642
+ }): CommandResult<string>;
638
643
  /**
639
644
  * Partial update over the §6.1 sparse wire: record one upsert whose
640
645
  * presence set is the primary key plus the supplied non-scope columns.
package/dist/client.js CHANGED
@@ -14,7 +14,7 @@ import { ProgressEmitter, } from './progress.js';
14
14
  * ownership behind `LeaderLock`. One combined push+pull request per
15
15
  * `sync()` round (§7.2); local reads go straight to the database.
16
16
  */
17
- import { canonicalScopeJson, decodeResponse, DecodeError, decodeRow, decodeRowsSegment, encodeRequest, encodeRow, encodeSparseRow, encodePresencePublish, isRoundFailureCode, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseJsonDocument, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, registrationDigest, unitId, } from '@syncular/core';
17
+ import { canonicalScopeJson, decodeResponse, DecodeError, decodeRow, decodeRowsSegment, encodeRequest, encodeRow, encodeSparseRow, encodePresencePublish, isRoundFailureCode, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseJsonDocument, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, registrationDigest, unitId, definedObject, } from '@syncular/core';
18
18
  import { EncryptError } from '@syncular/core';
19
19
  import { EncodeError } from '@syncular/core';
20
20
  import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, ownsLocalRow, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
@@ -26,7 +26,7 @@ import { singleOwnerLock, } from './leader-lock.js';
26
26
  import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
27
27
  import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.js';
28
28
  import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, } from './local-rebootstrap-receipt.js';
29
- import { appendOutboxCommit, deleteOutboxCommit, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
29
+ import { appendOutboxCommit, chainsOn, deleteOutboxCommit, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
30
30
  import { activeFailureRecords, isStoredOperation, listCommitOutcomes, persistCommitOutcomeResolution, persistedCommitOutcome, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
31
31
  import { buildPreviousVersionAudit, capturePreviousVersion, clearPreviousVersionAudit, clearPreviousVersionRefusal, dropPreviousVersionContainer, loadLocalSchemaDescriptor, PREVIOUS_VERSION_CONTAINER_NAME, PREVIOUS_VERSION_MAX_LIMIT, readPreviousVersionContainer, readPreviousVersionRows, setLocalSchemaDescriptor, storedPreviousVersionAudit, storedPreviousVersionRefusal, withPreviousVersionContainer, writePreviousVersionAudit, writePreviousVersionRefusal, } from './previous-version.js';
32
32
  import { bytesToHex, compileClientSchema, hexToBytes, matchesLocalScopes, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, localColumnType, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
@@ -139,6 +139,17 @@ function realtimeErrorCode(error) {
139
139
  const code = error?.code;
140
140
  return typeof code === 'string' ? code : undefined;
141
141
  }
142
+ /** §7.7: progress fields of a payload; no payload is current. */
143
+ const NO_PAYLOAD = {
144
+ table: undefined,
145
+ segmentId: undefined,
146
+ bytesReceived: 0,
147
+ bytesTotal: undefined,
148
+ rowsProcessed: 0,
149
+ rowsTotal: undefined,
150
+ importWriteMs: undefined,
151
+ importCommitMs: undefined,
152
+ };
142
153
  export class SyncClient {
143
154
  #config;
144
155
  #authorityReads;
@@ -450,18 +461,17 @@ export class SyncClient {
450
461
  throw classifySqliteFailure(error).error;
451
462
  }
452
463
  this.#started = true;
464
+ // §4.8: an eviction a crash interrupted finishes before any read, with or
465
+ // without a transport; a preflight replica finishes it at activation.
466
+ if (this.#securityLifecycle === 'active')
467
+ await this.#serialize(() => this.#drainPendingEvictions());
453
468
  // A persisted active subscription needs one catch-up round on every open:
454
469
  // realtime only covers changes after the socket connects, and an
455
470
  // idempotent setWindow/subscribe call correctly creates no new command
456
471
  // effect. Pending outbox work has the same restart requirement. Surface
457
472
  // this as an exact core-owned intent so hosts never need a startup poll or
458
473
  // an application-issued sync() call.
459
- const startupWork = this.#schemaFloor === undefined &&
460
- (countOutbox(this.#db) > 0 ||
461
- this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`).length > 0 ||
462
- loadPendingEvictions(this.#db).length > 0 ||
463
- loadUnits(this.#db).some((unit) => unit.status === 'active'));
464
- if (startupWork && this.#securityLifecycle === 'active') {
474
+ if (this.#securityLifecycle === 'active' && this.#hasStartupWork()) {
465
475
  this.#needsPull = true;
466
476
  this.#emitSyncNeeded('startup');
467
477
  this.#emitSyncIntent({ kind: 'interactive' });
@@ -792,20 +802,25 @@ export class SyncClient {
792
802
  throw invalidRequest('activateSecurity requires the client to be in security preflight');
793
803
  }
794
804
  await (this.#preflightBarrier ?? this.#opChain);
805
+ // §4.8: an interrupted eviction finishes before protected reads open.
806
+ await this.#serialize(() => this.#drainPendingEvictions());
795
807
  this.#encryption = options.encryption;
796
808
  this.#securityLifecycle = 'active';
797
- const startupWork = this.#schemaFloor === undefined &&
798
- (countOutbox(this.#db) > 0 ||
799
- this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`).length > 0 ||
800
- loadPendingEvictions(this.#db).length > 0 ||
801
- loadUnits(this.#db).some((unit) => unit.status === 'active'));
802
- if (startupWork) {
809
+ if (this.#hasStartupWork()) {
803
810
  this.#setSyncNeeded(true);
804
811
  this.#emitSyncNeeded('startup');
805
812
  this.#emitSyncIntent({ kind: 'interactive' });
806
813
  }
807
814
  this.#emitDiagnostics();
808
815
  }
816
+ /** Persisted work an opened or activated replica owes one round (§8.4). */
817
+ #hasStartupWork() {
818
+ return (this.#schemaFloor === undefined &&
819
+ (countOutbox(this.#db) > 0 ||
820
+ this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`).length > 0 ||
821
+ loadPendingEvictions(this.#db).length > 0 ||
822
+ loadUnits(this.#db).some((unit) => unit.status === 'active')));
823
+ }
809
824
  // -- accessors ------------------------------------------------------------
810
825
  get clientId() {
811
826
  return this.#clientId;
@@ -926,8 +941,7 @@ export class SyncClient {
926
941
  });
927
942
  };
928
943
  const deliveryOf = (id) => {
929
- const pending = this.#db.query(`SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`, [id]).length > 0;
930
- if (pending)
944
+ if (this.#outboxCommitExists(id))
931
945
  return { status: 'pending', clientCommitId: id };
932
946
  const outcome = persistedCommitOutcome(this.#db, id);
933
947
  return outcome === undefined
@@ -2207,14 +2221,22 @@ export class SyncClient {
2207
2221
  /**
2208
2222
  * Record one atomic local commit (§7.1): appended to the outbox in
2209
2223
  * schema-agnostic form and applied optimistically to the local mirror.
2210
- * Returns the generated `clientCommitId`.
2224
+ * Returns the generated `clientCommitId`, or the caller's unused one
2225
+ * (`client.commit_id_reused` when this replica holds it).
2211
2226
  */
2212
- mutate(mutations) {
2213
- return this.#recordMutations(mutations);
2227
+ mutate(mutations, options) {
2228
+ return this.#recordMutations(mutations, options?.clientCommitId);
2214
2229
  }
2215
- #recordMutations(mutations) {
2230
+ #recordMutations(mutations, supplied) {
2216
2231
  this.#requireActive();
2217
- const clientCommitId = crypto.randomUUID();
2232
+ // §7.1: a supplied ID is non-empty (§6.1) and unknown to this replica.
2233
+ if (supplied === '')
2234
+ throw invalidRequest('clientCommitId is empty');
2235
+ if (supplied !== undefined &&
2236
+ (this.#outboxCommitExists(supplied) ||
2237
+ readCommitOutcome(this.#db, supplied)))
2238
+ throw new ClientSyncError('client.commit_id_reused', 'clientCommitId is held', false, { clientCommitId: supplied });
2239
+ const clientCommitId = supplied ?? crypto.randomUUID();
2218
2240
  const operations = mutations.map((mutation) => {
2219
2241
  const table = this.#table(mutation.table);
2220
2242
  if (mutation.op === 'delete') {
@@ -2244,6 +2266,7 @@ export class SyncClient {
2244
2266
  for (const column of table.columns) {
2245
2267
  if (!normalized.has(column.name))
2246
2268
  continue;
2269
+ const at = { table: table.name, column: column.name };
2247
2270
  // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
2248
2271
  // server accepts a present scope column whose value equals the
2249
2272
  // stored row and applies it as a no-op, so a decoded envelope
@@ -2256,14 +2279,14 @@ export class SyncClient {
2256
2279
  // proven equal already.
2257
2280
  if (scopeColumns.has(column.name) && column.name !== pkColumn.name) {
2258
2281
  if (!Object.is(rowValueToJson(fromSqlValue(column, local[column.name] ?? null)), rowValueToJson(coerceSqlRepresentation(column, normalized.get(column.name))))) {
2259
- throw invalidRequest(`table ${table.name}: patch cannot write scope column ${JSON.stringify(column.name)} (§3.4)`);
2282
+ throw invalidRequest('patch cannot write a scope column (§3.4)', false, at);
2260
2283
  }
2261
2284
  continue;
2262
2285
  }
2263
2286
  const value = normalized.get(column.name);
2264
2287
  if (value === undefined || value === null) {
2265
2288
  if (!column.nullable) {
2266
- throw invalidRequest(`table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1)`);
2289
+ throw invalidRequest('a non-nullable column is null (§6.1)', false, at);
2267
2290
  }
2268
2291
  json[column.name] = null;
2269
2292
  continue;
@@ -2348,9 +2371,9 @@ export class SyncClient {
2348
2371
  return clientCommitId;
2349
2372
  }
2350
2373
  /** Host-facing mutation result with explicit network work intent (§7.5). */
2351
- mutateCommand(mutations) {
2374
+ mutateCommand(mutations, options) {
2352
2375
  return {
2353
- value: this.mutate(mutations),
2376
+ value: this.mutate(mutations, options),
2354
2377
  effects: {
2355
2378
  sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
2356
2379
  },
@@ -2371,7 +2394,9 @@ export class SyncClient {
2371
2394
  const normalized = normalizeRecordKeys(compiled, partial);
2372
2395
  const pkOverride = normalized.get(pkColumn.name);
2373
2396
  if (pkOverride !== undefined && String(pkOverride) !== rowId) {
2374
- throw invalidRequest(`table ${compiled.name}: patch cannot change the primary key`);
2397
+ throw invalidRequest('patch cannot change the primary key', false, {
2398
+ table,
2399
+ });
2375
2400
  }
2376
2401
  const pkType = localColumnType(pkColumn);
2377
2402
  const typedPk = pkType === 'integer' &&
@@ -2682,7 +2707,10 @@ export class SyncClient {
2682
2707
  // §6.1/§7.1: the commit-count and operation caps are hard. A first
2683
2708
  // commit that alone exceeds the operation cap is a typed capacity error
2684
2709
  // and stays queued; a later one defers with the complete suffix.
2685
- if (maxCommits !== undefined && pushFrames.length >= maxCommits) {
2710
+ // §7.1 chained base: a commit chained on an earlier commit of this
2711
+ // request waits for that commit's change, which supplies its version.
2712
+ if ((maxCommits !== undefined && pushFrames.length >= maxCommits) ||
2713
+ outbox.some((earlier) => earlier.operations.some((prior) => commit.operations.some((operation) => chainsOn(prior, operation))))) {
2686
2714
  deferred = pendingCount - processed;
2687
2715
  break;
2688
2716
  }
@@ -2706,12 +2734,8 @@ export class SyncClient {
2706
2734
  });
2707
2735
  }
2708
2736
  catch (error) {
2709
- if (error instanceof OutboxEncodeError) {
2710
- this.#dropIncompatibleCommit(commit, error.message);
2711
- processed += 1;
2712
- continue;
2713
- }
2714
- if (error instanceof EncryptError) {
2737
+ if (error instanceof OutboxEncodeError ||
2738
+ error instanceof EncryptError) {
2715
2739
  this.#dropIncompatibleCommit(commit, error.message, error.code);
2716
2740
  processed += 1;
2717
2741
  continue;
@@ -3892,6 +3916,12 @@ export class SyncClient {
3892
3916
  skip: false,
3893
3917
  }
3894
3918
  : undefined;
3919
+ // §7.7: a section boundary ends the previous payload.
3920
+ this.#progress.update({
3921
+ ...NO_PAYLOAD,
3922
+ phase: 'import',
3923
+ unitId: section?.unit.id,
3924
+ });
3895
3925
  break;
3896
3926
  }
3897
3927
  case 'SEGMENT_INLINE':
@@ -3907,16 +3937,13 @@ export class SyncClient {
3907
3937
  let bytes;
3908
3938
  if (frame.type === 'SEGMENT_REF') {
3909
3939
  this.#progress.update({
3940
+ ...NO_PAYLOAD,
3910
3941
  phase: 'download',
3911
3942
  unitId,
3912
3943
  table: frame.table,
3913
3944
  segmentId: frame.segmentId,
3914
- bytesReceived: 0,
3915
3945
  bytesTotal: frame.byteLength,
3916
- rowsProcessed: 0,
3917
3946
  rowsTotal: frame.rowCount,
3918
- importWriteMs: undefined,
3919
- importCommitMs: undefined,
3920
3947
  });
3921
3948
  prefetch();
3922
3949
  const pending = prefetched.get(frame);
@@ -3941,16 +3968,13 @@ export class SyncClient {
3941
3968
  const segment = image === undefined ? decodeRowsSegment(bytes) : undefined;
3942
3969
  if (frame.type === 'SEGMENT_INLINE' && segment !== undefined)
3943
3970
  this.#progress.update({
3971
+ ...NO_PAYLOAD,
3944
3972
  phase: 'import',
3945
3973
  unitId,
3946
3974
  table: segment.table,
3947
- segmentId: undefined,
3948
3975
  bytesReceived: bytes.byteLength,
3949
3976
  bytesTotal: bytes.byteLength,
3950
- rowsProcessed: 0,
3951
3977
  rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
3952
- importWriteMs: undefined,
3953
- importCommitMs: undefined,
3954
3978
  });
3955
3979
  await this.#applySegmentOrFail(section, summary, image?.table ?? segment.table, (table, clearFirst, effective, owners) => {
3956
3980
  const options = this.#segmentApplyOptions(table, clearFirst, effective, owners, image !== undefined
@@ -3971,6 +3995,12 @@ export class SyncClient {
3971
3995
  this.#localResetEpoch === resetEpoch)
3972
3996
  this.#finishSection(section, frame, summary);
3973
3997
  section = undefined;
3998
+ // The counters stay: `complete` and `failed` report them.
3999
+ this.#progress.update({
4000
+ unitId: undefined,
4001
+ table: undefined,
4002
+ segmentId: undefined,
4003
+ });
3974
4004
  break;
3975
4005
  }
3976
4006
  case 'LIVE_START': {
@@ -5015,13 +5045,6 @@ export class SyncClient {
5015
5045
  }
5016
5046
  }
5017
5047
  }
5018
- function definedObject(record) {
5019
- for (const key of Object.keys(record)) {
5020
- if (record[key] === undefined)
5021
- delete record[key];
5022
- }
5023
- return record;
5024
- }
5025
5048
  function requireRowId(value) {
5026
5049
  if (typeof value === 'string' && value.length > 0)
5027
5050
  return value;
package/dist/errors.d.ts CHANGED
@@ -34,7 +34,7 @@ export declare class ClientSyncError extends Error {
34
34
  constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>, recommendedAction?: string);
35
35
  }
36
36
  /** Shared invalid-request construction for client validators and transport guards. */
37
- export declare function invalidRequest(message: string, retryable?: boolean): ClientSyncError;
37
+ export declare function invalidRequest(message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>): ClientSyncError;
38
38
  /** Shared retryable `sync.transport_failed` construction for client transports. */
39
39
  export declare function transportFailed(message: string, details?: Readonly<Record<string, unknown>>): ClientSyncError;
40
40
  /**
package/dist/errors.js CHANGED
@@ -40,8 +40,8 @@ export class ClientSyncError extends Error {
40
40
  }
41
41
  }
42
42
  /** Shared invalid-request construction for client validators and transport guards. */
43
- export function invalidRequest(message, retryable = false) {
44
- return new ClientSyncError('sync.invalid_request', message, retryable);
43
+ export function invalidRequest(message, retryable = false, details) {
44
+ return new ClientSyncError('sync.invalid_request', message, retryable, details);
45
45
  }
46
46
  /** Shared retryable `sync.transport_failed` construction for client transports. */
47
47
  export function transportFailed(message, details) {
@@ -4,7 +4,6 @@ import type { CompiledClientSchema, CompiledClientTable, JsonRowValue } from './
4
4
  import type { RowValue } from '@syncular/core';
5
5
  import type { RetainedCommitRow } from './outcomes.js';
6
6
  import type { OutboxCommit, OutboxBeforeImage } from './outbox.js';
7
- /** Protected failure state. The server base advances independently of intent. */
8
7
  export declare function ensureFailedOverlaySchema(db: ClientDatabase): void;
9
8
  export declare function retainedBaseWrite(db: ClientDatabase, table: CompiledClientTable, rowId: string, values?: Readonly<Record<string, JsonRowValue>>, version?: number): void;
10
9
  export declare function retainFailedRows(db: ClientDatabase, commit: OutboxCommit, images: readonly OutboxBeforeImage[], commitSeq?: number): void;
@@ -6,6 +6,7 @@ import { ClientSyncError } 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. */
9
+ const SET_UNIQUE_CONFLICTS = `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`;
9
10
  export function ensureFailedOverlaySchema(db) {
10
11
  db.exec(`CREATE TABLE IF NOT EXISTS ${RETAINED_ROWS}(commit_id TEXT NOT NULL,idx INTEGER NOT NULL,tbl TEXT NOT NULL,id TEXT NOT NULL,at INTEGER NOT NULL,op TEXT NOT NULL,intent TEXT,base TEXT,version INTEGER,unique_conflicts TEXT,commit_seq INTEGER,PRIMARY KEY(commit_id,idx))`);
11
12
  const columns = db.query(`PRAGMA table_info(${RETAINED_ROWS})`);
@@ -37,7 +38,7 @@ export function retainedBaseWrite(db, table, rowId, values, version) {
37
38
  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
38
39
  })));
39
40
  }
40
- db.exec(`UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`, [
41
+ db.exec(SET_UNIQUE_CONFLICTS, [
41
42
  conflicts.length
42
43
  ? JSON.stringify(conflicts.sort((a, b) => table.indexes.findIndex((index) => index.name === a.index) -
43
44
  table.indexes.findIndex((index) => index.name === b.index)))
@@ -143,7 +144,7 @@ export function failedOverlayCommits(db, acknowledged = false, scope, schema) {
143
144
  const authorized = uniqueConflicts(db, table, mapRowValues(values, jsonToRowValue)).filter((conflict) => conflict.serverVersion >= 0 &&
144
145
  !db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_IMAGES} WHERE tbl=? AND row_id=? LIMIT 1`, [table.name, conflict.rowId, table.name, conflict.rowId]).length);
145
146
  if (authorized.length)
146
- db.exec(`UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`, [
147
+ db.exec(SET_UNIQUE_CONFLICTS, [
147
148
  JSON.stringify(authorized.map((conflict) => ({
148
149
  ...conflict,
149
150
  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
package/dist/http.js CHANGED
@@ -264,15 +264,9 @@ export function httpBlobTransport(blobsBaseUrl, options) {
264
264
  catch {
265
265
  // Not JSON: inline bytes.
266
266
  }
267
- if (typeof envelope?.url === 'string') {
268
- return {
269
- kind: 'url',
270
- url: envelope.url,
271
- ...(typeof envelope.urlExpiresAtMs === 'number'
272
- ? { urlExpiresAtMs: envelope.urlExpiresAtMs }
273
- : {}),
274
- };
275
- }
267
+ const grant = envelope && urlGrant(envelope);
268
+ if (grant)
269
+ return grant;
276
270
  }
277
271
  return { kind: 'bytes', bytes };
278
272
  },
@@ -304,18 +298,8 @@ export function httpBlobTransport(blobsBaseUrl, options) {
304
298
  if (!response.ok)
305
299
  await throwHttpError(response);
306
300
  const body = (await transfer('blob grant read failed', () => response.json(), response.status));
307
- if (typeof body.url === 'string') {
308
- return {
309
- kind: 'url',
310
- url: body.url,
311
- ...(typeof body.urlExpiresAtMs === 'number'
312
- ? { urlExpiresAtMs: body.urlExpiresAtMs }
313
- : {}),
314
- };
315
- }
316
- if (body.present === true)
317
- return { kind: 'present' };
318
- return { kind: 'none' };
301
+ return (urlGrant(body) ??
302
+ (body.present === true ? { kind: 'present' } : { kind: 'none' }));
319
303
  },
320
304
  // §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
321
305
  uploadToUrl: async (blobId, url, bytes, mediaType, signal) => {
@@ -392,3 +376,15 @@ export function webSocketRealtimeConnector(realtimeUrl) {
392
376
  };
393
377
  });
394
378
  }
379
+ /** §5.9.3, §5.9.5: a JSON body with a string `url` is a presigned grant. */
380
+ function urlGrant(body) {
381
+ return typeof body.url === 'string'
382
+ ? {
383
+ kind: 'url',
384
+ url: body.url,
385
+ ...(typeof body.urlExpiresAtMs === 'number'
386
+ ? { urlExpiresAtMs: body.urlExpiresAtMs }
387
+ : {}),
388
+ }
389
+ : undefined;
390
+ }
@@ -84,11 +84,6 @@ export declare class NativeSyncError extends Error {
84
84
  * touched.
85
85
  */
86
86
  export declare function nativeCreateParams(config: NativeCreateConfig, ErrorType: typeof NativeSyncError): Record<string, unknown>;
87
- /**
88
- * The `SyncClientLike` proxy over a native core. Every snapshot method
89
- * returns a promise from one host round trip; React hooks accept the
90
- * canonical snapshot interface directly.
91
- */
92
87
  export declare abstract class NativeBridgeClient implements PromiseMethods<ClientSnapshotMethods & Pick<SyncClient, 'unit' | 'units' | 'unitCatchup'>> {
93
88
  #private;
94
89
  /**
@@ -106,8 +101,13 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
106
101
  protected abstract sendHeaders(headers: Readonly<Record<string, string>>): Promise<NativeReply>;
107
102
  /** Stop the native core. `close()` detaches listeners once it settles. */
108
103
  protected abstract shutdown(): Promise<void>;
109
- /** @internal Settle the native `create`; a failure detaches the listener. */
110
- __open(create: () => Promise<NativeReply>): Promise<void>;
104
+ /**
105
+ * @internal Settle the native `create`; a failure detaches the listener.
106
+ * `host` is the page's native host: its one core serves one live bridge
107
+ * client, so a second `create` before `close()` settles is refused
108
+ * instead of replacing the first client's core.
109
+ */
110
+ __open(create: () => Promise<NativeReply>, host: object): Promise<void>;
111
111
  /** Dispatch a command through the closed check and the preflight gate. */
112
112
  protected command(method: string, params: Record<string, unknown>): Promise<unknown>;
113
113
  /** Additional preflight operations a host subclass permits. */
@@ -149,7 +149,9 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
149
149
  localRevision(): Promise<bigint>;
150
150
  statusSnapshot(): Promise<SyncStatusSnapshot>;
151
151
  diagnosticsSnapshot(): Promise<ClientDiagnosticsSnapshot>;
152
- mutate(mutations: readonly MutationInput[]): Promise<string>;
152
+ mutate(mutations: readonly MutationInput[], options?: {
153
+ readonly clientCommitId?: string;
154
+ }): Promise<string>;
153
155
  patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
154
156
  readonly baseVersion?: number;
155
157
  }): Promise<string>;
@@ -171,6 +171,8 @@ export function nativeCreateParams(config, ErrorType) {
171
171
  * returns a promise from one host round trip; React hooks accept the
172
172
  * canonical snapshot interface directly.
173
173
  */
174
+ /** Native hosts whose one core a live bridge client of this page holds. */
175
+ const heldHosts = new WeakSet();
174
176
  export class NativeBridgeClient {
175
177
  #kind;
176
178
  #Error;
@@ -182,6 +184,7 @@ export class NativeBridgeClient {
182
184
  #presenceListeners = new Set();
183
185
  #closed = false;
184
186
  #closing;
187
+ #host;
185
188
  #securityLifecycle;
186
189
  #preflightBarrier;
187
190
  /**
@@ -208,15 +211,27 @@ export class NativeBridgeClient {
208
211
  }
209
212
  return reply.result;
210
213
  }
211
- /** @internal Settle the native `create`; a failure detaches the listener. */
212
- async __open(create) {
214
+ /**
215
+ * @internal Settle the native `create`; a failure detaches the listener.
216
+ * `host` is the page's native host: its one core serves one live bridge
217
+ * client, so a second `create` before `close()` settles is refused
218
+ * instead of replacing the first client's core.
219
+ */
220
+ async __open(create, host) {
221
+ if (heldHosts.has(host)) {
222
+ this.#release();
223
+ throw new this.#Error('client.native_client_exists', 'this page already holds the native client; close it before creating another');
224
+ }
225
+ heldHosts.add(host);
213
226
  try {
214
227
  await this.#reply(create);
215
228
  }
216
229
  catch (error) {
230
+ heldHosts.delete(host);
217
231
  this.#release();
218
232
  throw error;
219
233
  }
234
+ this.#host = host;
220
235
  }
221
236
  /** Dispatch a command through the closed check and the preflight gate. */
222
237
  async command(method, params) {
@@ -518,9 +533,12 @@ export class NativeBridgeClient {
518
533
  role: 'single',
519
534
  });
520
535
  }
521
- async mutate(mutations) {
536
+ async mutate(mutations, options) {
522
537
  const result = (await this.command('mutate', {
523
538
  mutations: encodeValue(mutations),
539
+ ...(options?.clientCommitId === undefined
540
+ ? {}
541
+ : { clientCommitId: options.clientCommitId }),
524
542
  }));
525
543
  return result.clientCommitId;
526
544
  }
@@ -764,6 +782,8 @@ export class NativeBridgeClient {
764
782
  const shutdown = this.shutdown();
765
783
  this.#closed = true;
766
784
  this.#closing = shutdown.finally(() => {
785
+ if (this.#host !== undefined)
786
+ heldHosts.delete(this.#host);
767
787
  this.#release();
768
788
  this.#invalidationListeners.clear();
769
789
  this.#progress.clear();
package/dist/outbox.d.ts CHANGED
@@ -38,6 +38,11 @@ export interface OutboxCommit {
38
38
  readonly createdAtMs: number;
39
39
  readonly operations: readonly OutboxOperation[];
40
40
  }
41
+ /**
42
+ * §7.1 chained base: `later` repeats `earlier`'s positive base on the same row
43
+ * and presents only columns `earlier` presents.
44
+ */
45
+ export declare function chainsOn(earlier: OutboxOperation, later: OutboxOperation): boolean;
41
46
  /** Protected local rollback image; never encoded or exposed in outcomes. */
42
47
  export interface OutboxBeforeImage {
43
48
  readonly opIndex: number;
@@ -68,7 +73,7 @@ export declare function replaceOutboxBeforeImages(db: ClientDatabase, commit: Pi
68
73
  * so the caller can drop the commit through the rejection channel.
69
74
  */
70
75
  export declare class OutboxEncodeError extends ClientSyncError {
71
- constructor(message: string);
76
+ constructor();
72
77
  }
73
78
  /**
74
79
  * Encode one outbox commit as a `PUSH_COMMIT` frame with the current