@syncular/client 0.75.0 → 0.77.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.d.ts CHANGED
@@ -89,6 +89,11 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
89
89
  readonly isCurrent?: () => boolean;
90
90
  /** Monotonic milliseconds that time each chunk. */
91
91
  readonly now?: () => number;
92
+ /**
93
+ * Table → its next chunk size, carried from one range image of a table
94
+ * to the next (§5.3).
95
+ */
96
+ readonly chunkRows?: Map<string, number>;
92
97
  }): Promise<number>;
93
98
  /**
94
99
  * Apply a decoded rows segment: each block in one local transaction
package/dist/apply.js CHANGED
@@ -364,11 +364,12 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
364
364
  };
365
365
  let [boundary, where, params] = range(undefined, 1024);
366
366
  let applied = 0;
367
- // §5.3: the first chunk holds 1,024 rows. A later chunk holds at least
367
+ // §5.3: a table's first chunk holds 1,024 rows; a later range image
368
+ // starts at the size its previous range reached. A later chunk holds at least
368
369
  // 1,024 rows, at most twice the rows of the one before, at most 65,536,
369
370
  // and at most the rows the one before applied per 250 ms from its start
370
371
  // to its COMMIT; a replaying chunk holds one statement.
371
- for (let size = 1024;;) {
372
+ for (let size = (!options.clearFirst && options.chunkRows?.get(table.name)) || 1024;;) {
372
373
  if (options.isCurrent?.() === false)
373
374
  return applied;
374
375
  const started = now();
@@ -424,6 +425,7 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
424
425
  if (boundary === undefined || applied === count)
425
426
  break;
426
427
  size = Math.max(1024, Math.min(2 * chunk, 65_536, Math.floor((chunk * 250) / duration)));
428
+ options.chunkRows?.set(table.name, size);
427
429
  [boundary, where, params] = range(boundary, Math.min(1024, size));
428
430
  }
429
431
  if (applied !== count)
package/dist/client.js CHANGED
@@ -29,8 +29,8 @@ import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, }
29
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, scrubPurgedOutcomes, } 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
- import { bytesToHex, compileClientSchema, hexToBytes, matchesLocalScopes, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, localColumnType, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SEALED_COLUMN, SEALED_KEY_COLUMN, SYNC_VERSION_COLUMN, stripSyncColumns, toSqlValue, } from './schema.js';
33
- import { bootstrapping, bumpLocalRevision, covers, deleteUnit, ECHO_DIGEST_KEY, getLocalRevision, getMeta, getUnit, loadUnits, META_TABLE, owning, pairScopes, pruneUnknownUnits, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY, replicaCursor, resetUnits, saveUnit, saveUnitScopeSchema, setMeta, unitOwners, } from './state.js';
32
+ import { bytesToHex, compileClientSchema, hexToBytes, matchesLocalScopes, resetLocalReplica, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, localColumnType, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SEALED_COLUMN, SEALED_KEY_COLUMN, SYNC_VERSION_COLUMN, stripSyncColumns, toSqlValue, } from './schema.js';
33
+ import { bootstrapping, bumpLocalRevision, covers, deleteUnit, ECHO_DIGEST_KEY, getLocalRevision, getMeta, getUnit, loadUnits, META_TABLE, owning, pairScopes, pruneUnknownUnits, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY, replicaCursor, saveUnit, saveUnitScopeSchema, setMeta, unitOwners, } from './state.js';
34
34
  import { deletePendingEviction, loadPendingEvictions, loadWindowUnits, savePendingEviction, windowBaseKey, windowRefs, WINDOWS_TABLE, windowUnitScopes, } from './window.js';
35
35
  /** Stable client-local error while protected operations are preflight-gated. */
36
36
  export const SECURITY_PREFLIGHT_REQUIRED_CODE = 'client.security_preflight_required';
@@ -69,6 +69,10 @@ async function sha256Hex(bytes) {
69
69
  .map((b) => b.toString(16).padStart(2, '0'))
70
70
  .join('');
71
71
  }
72
+ const invalidHostResponse = (message) => new ClientSyncError('client.invalid_host_response', message);
73
+ const outcomeNotFound = () => new ClientSyncError('sync.outcome_not_found', 'no durable outcome exists for the commit');
74
+ /** The position a unit presents in a pull (§5.6 applied-segment rule). */
75
+ const position = (unit) => JSON.stringify([unit.id, unit.cursor, unit.bootstrapState]);
72
76
  function emptySummary(pushed) {
73
77
  return {
74
78
  pushed,
@@ -192,6 +196,13 @@ export class SyncClient {
192
196
  #pendingRound;
193
197
  #needsPull = false;
194
198
  #progress = new ProgressEmitter();
199
+ /**
200
+ * §5.6 applied-segment rule: unit position → the segments applied in
201
+ * sections whose SUB_END did not persist.
202
+ */
203
+ #appliedSegments = new Map();
204
+ /** §5.3: a table's next image chunk size, carried across its ranges. */
205
+ #chunkRows = new Map();
195
206
  #progressAttempt = 0;
196
207
  /**
197
208
  * True from the synchronous entry of `sync()` until its serialized round
@@ -526,8 +537,9 @@ export class SyncClient {
526
537
  }
527
538
  /**
528
539
  * §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
529
- * and leaseState. Drops/recreates every synced table from the new schema,
530
- * resets subscription sync-state (keeping registrations), clears any
540
+ * leaseState, and the tables and units a bump keeps (equal generations).
541
+ * Drops/recreates every other synced table from the new schema, resets the
542
+ * other units' sync-state (keeping registrations), clears any
531
543
  * schema-floor stop state, rewrites the marker, and raises `upgrading`.
532
544
  * The bump is idempotent by the marker (rewritten last).
533
545
  */
@@ -541,23 +553,21 @@ export class SyncClient {
541
553
  // existing marker, with no cross-file transaction.
542
554
  this.#sweepPreviousVersionContainer();
543
555
  this.#capturePreviousVersion(previousVersion);
556
+ let changed = [];
544
557
  this.#applyBatch((batch) => {
545
558
  this.#db.transaction(() => {
546
559
  if (this.#previousVersion !== undefined) {
547
560
  writePreviousVersionAudit(this.#db, buildPreviousVersionAudit(this.#schema, listOutbox(this.#db), previousVersion, this.#schema.version, this.#now()));
548
561
  }
549
- pruneUnknownUnits(this.#db, this.#schema, true);
550
- this.#discardAcknowledgedRows();
551
- dropAndRecreateSyncedTables(this.#db, this.#schema);
552
- resetUnits(this.#db);
562
+ changed = resetLocalReplica(this.#db, this.#schema, true);
553
563
  this.#replayOutbox();
554
564
  setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
555
565
  setLocalSchemaDescriptor(this.#db, this.#schema);
556
566
  saveUnitScopeSchema(this.#db, this.#schema);
557
567
  });
558
- // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
559
- for (const table of this.#schema.tables.values())
560
- batch.table(table.name);
568
+ // Every table the reset dropped changed (I1 eviction-shaped).
569
+ for (const table of changed)
570
+ batch.table(table);
561
571
  });
562
572
  // The stop state is over: this client now ships a servable schema.
563
573
  // The reset transaction already replayed pending intent before committing
@@ -636,9 +646,7 @@ export class SyncClient {
636
646
  const priorRejections = [...this.#rejections];
637
647
  this.#applyBatch((batch) => {
638
648
  this.#db.transaction(() => {
639
- this.#discardAcknowledgedRows();
640
- dropAndRecreateSyncedTables(this.#db, this.#schema);
641
- resetUnits(this.#db);
649
+ resetLocalReplica(this.#db, this.#schema);
642
650
  setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
643
651
  // §7.1/§7.4.4: recover codec-invalid persisted values in this reset
644
652
  // transaction before they replay, so the reset boundary never fails on
@@ -648,8 +656,8 @@ export class SyncClient {
648
656
  this.#applyOperationsLocally(commit.operations, batch);
649
657
  }
650
658
  });
651
- for (const table of this.#schema.tables.values())
652
- batch.table(table.name);
659
+ for (const table of this.#schema.tables.keys())
660
+ batch.table(table);
653
661
  }, undefined, (error) => {
654
662
  // A failure after the recovery drop, including the reset's revision or
655
663
  // COMMIT, rolls the database back: mirror that for the in-memory
@@ -1847,7 +1855,7 @@ export class SyncClient {
1847
1855
  this.#requireActive();
1848
1856
  const current = readCommitOutcome(this.#db, input.clientCommitId);
1849
1857
  if (current === undefined) {
1850
- throw new ClientSyncError('sync.outcome_not_found', `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`);
1858
+ throw outcomeNotFound();
1851
1859
  }
1852
1860
  if (current.resolution !== 'active')
1853
1861
  return current;
@@ -1879,7 +1887,7 @@ export class SyncClient {
1879
1887
  ]);
1880
1888
  const resolved = persistCommitOutcomeResolution(this.#db, input, this.#now());
1881
1889
  if (resolved === undefined) {
1882
- throw new ClientSyncError('sync.outcome_not_found', `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`);
1890
+ throw outcomeNotFound();
1883
1891
  }
1884
1892
  this.#conflicts = this.#conflicts.filter((record) => record.clientCommitId !== input.clientCommitId);
1885
1893
  this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== input.clientCommitId);
@@ -2628,12 +2636,8 @@ export class SyncClient {
2628
2636
  this.#upgrading = true;
2629
2637
  this.#needsPull = true;
2630
2638
  batch.status();
2631
- this.#discardAcknowledgedRows();
2632
- dropAndRecreateSyncedTables(this.#db, this.#schema);
2633
- resetUnits(this.#db);
2634
- for (const table of this.#schema.tables.values()) {
2635
- batch.table(table.name);
2636
- }
2639
+ for (const table of resetLocalReplica(this.#db, this.#schema))
2640
+ batch.table(table);
2637
2641
  for (const commit of pending) {
2638
2642
  this.#applyOperationsLocally(commit.operations, batch);
2639
2643
  }
@@ -3850,7 +3854,7 @@ export class SyncClient {
3850
3854
  const currentLogEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
3851
3855
  if (header.resetRequired) {
3852
3856
  if (mode !== 'pull' || message.frames.length !== 1) {
3853
- throw new ClientSyncError('client.invalid_host_response', 'a log-epoch reset response must contain only RESP_HEADER');
3857
+ throw invalidHostResponse('a log-epoch reset response must contain only RESP_HEADER');
3854
3858
  }
3855
3859
  return {
3856
3860
  ...summary,
@@ -3859,7 +3863,7 @@ export class SyncClient {
3859
3863
  };
3860
3864
  }
3861
3865
  if (currentLogEpoch === undefined || currentLogEpoch !== header.logEpoch) {
3862
- throw new ClientSyncError('client.invalid_host_response', 'the server changed logEpoch without requiring a reset');
3866
+ throw invalidHostResponse('the server changed logEpoch without requiring a reset');
3863
3867
  }
3864
3868
  let section;
3865
3869
  let errorFrame;
@@ -3874,7 +3878,9 @@ export class SyncClient {
3874
3878
  // bootstrap overlaps its page fetches instead of paying one blocking round
3875
3879
  // trip per page. At most four downloads run at once, the Rust native
3876
3880
  // transport's pool size: enough to overlap round trips, while the client
3877
- // holds at most four bodies, the one being applied and three ahead. The
3881
+ // holds at most four bodies, the one being applied and three ahead. An
3882
+ // image starts only beside at most one other body, so at most two are
3883
+ // images (§5.3 client memory); later descriptors wait in order. The
3878
3884
  // loop takes each body out of the map before applying it and tops the
3879
3885
  // window up at the next descriptor. Eligibility mirrors the loop: a
3880
3886
  // descriptor outside an applied section or from an unconfigured
@@ -3884,7 +3890,9 @@ export class SyncClient {
3884
3890
  const queued = [];
3885
3891
  const prefetched = new Map();
3886
3892
  const prefetch = () => {
3887
- for (let next; prefetched.size < 4 && (next = queued.shift());) {
3893
+ for (let next; prefetched.size < 4 &&
3894
+ !(queued[0]?.[0].mediaType === 'sqlite' && prefetched.size > 1) &&
3895
+ (next = queued.shift());) {
3888
3896
  const [frame, scopes] = next;
3889
3897
  const pending = this.#downloadSegment(frame, scopes, (bytes) => {
3890
3898
  // Only the descriptor the loop is applying reports bytes; a
@@ -3913,8 +3921,7 @@ export class SyncClient {
3913
3921
  else if (frame.type === 'SEGMENT_REF' &&
3914
3922
  open !== undefined &&
3915
3923
  this.#config.segments !== undefined &&
3916
- !(frame.mediaType === 'sqlite' &&
3917
- (this.#acceptMask() & ACCEPT_SQLITE) === 0)) {
3924
+ !this.#appliedSegments.get(position(open))?.has(frame.segmentId)) {
3918
3925
  queued.push([frame, open.scopes]);
3919
3926
  }
3920
3927
  }
@@ -4009,10 +4016,21 @@ export class SyncClient {
4009
4016
  if (section === undefined || section.skip)
4010
4017
  break;
4011
4018
  const unitId = section.unit.id;
4012
- if (frame.type === 'SEGMENT_REF' &&
4013
- frame.mediaType === 'sqlite' &&
4014
- (this.#acceptMask() & ACCEPT_SQLITE) === 0) {
4015
- throw invalidRequest('SEGMENT_REF mediaType sqlite was not advertised in accept (§4.2)');
4019
+ const image = frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite'
4020
+ ? frame
4021
+ : undefined;
4022
+ // §4.2, §5.3: an image needs accept bit 2 and carries no cursors.
4023
+ if (image !== undefined &&
4024
+ ((this.#acceptMask() & ACCEPT_SQLITE) === 0 ||
4025
+ image.rowCursor !== undefined ||
4026
+ image.nextRowCursor !== undefined))
4027
+ throw invalidRequest('unadvertised or paged sqlite segment (§4.2, §5.3)');
4028
+ const applied = this.#appliedSegments.get(position(section.unit)) ??
4029
+ new Set();
4030
+ if (frame.type === 'SEGMENT_REF' && applied.has(frame.segmentId)) {
4031
+ // §5.6: applied in an earlier attempt at this position.
4032
+ section.seeded.add(frame.table);
4033
+ break;
4016
4034
  }
4017
4035
  let bytes;
4018
4036
  if (frame.type === 'SEGMENT_REF') {
@@ -4052,14 +4070,6 @@ export class SyncClient {
4052
4070
  else {
4053
4071
  bytes = frame.payload;
4054
4072
  }
4055
- const image = frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite'
4056
- ? frame
4057
- : undefined;
4058
- // Images are whole-table; paged image descriptors are invalid.
4059
- if (image !== undefined &&
4060
- (image.rowCursor !== undefined ||
4061
- image.nextRowCursor !== undefined))
4062
- throw invalidRequest('sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)');
4063
4073
  const segment = image === undefined ? decodeRowsSegment(bytes) : undefined;
4064
4074
  if (frame.type === 'SEGMENT_INLINE' && segment !== undefined)
4065
4075
  this.#progress.update({
@@ -4079,6 +4089,8 @@ export class SyncClient {
4079
4089
  ? applySqliteSegment(this.#db, this.#schema, table, bytes, image, options)
4080
4090
  : applyRowsSegment(this.#db, this.#schema, table, segment, options, this.#encryption);
4081
4091
  });
4092
+ if (frame.type === 'SEGMENT_REF' && !section.skip)
4093
+ this.#appliedSegments.set(position(section.unit), applied.add(frame.segmentId));
4082
4094
  break;
4083
4095
  }
4084
4096
  case 'SUB_END': {
@@ -4087,8 +4099,10 @@ export class SyncClient {
4087
4099
  // unpersisted so the next round runs the fresh bootstrap.
4088
4100
  if (section !== undefined &&
4089
4101
  !section.skip &&
4090
- this.#localResetEpoch === resetEpoch)
4102
+ this.#localResetEpoch === resetEpoch) {
4091
4103
  this.#finishSection(section, frame, summary);
4104
+ this.#appliedSegments.delete(position(section.unit));
4105
+ }
4092
4106
  section = undefined;
4093
4107
  // The counters stay: `complete` and `failed` report them.
4094
4108
  this.#progress.update({
@@ -4283,7 +4297,7 @@ export class SyncClient {
4283
4297
  // §6.3: applied and cached both drain the outbox — cached means
4284
4298
  // "already applied, you may have missed the ack".
4285
4299
  if (frame.commitSeq === undefined)
4286
- throw new ClientSyncError('client.invalid_host_response', 'ACK lacks a commit sequence');
4300
+ throw invalidHostResponse('ACK lacks a commit sequence');
4287
4301
  retainFailedRows(this.#db, commit, listOutboxBeforeImages(this.#db, commit.clientCommitId), frame.commitSeq);
4288
4302
  this.#setSyncNeeded(true);
4289
4303
  recordCommitOutcome(this.#db, {
@@ -4488,6 +4502,7 @@ export class SyncClient {
4488
4502
  let writeMs = 0;
4489
4503
  let commitMs = 0;
4490
4504
  return {
4505
+ chunkRows: this.#chunkRows,
4491
4506
  clearFirst,
4492
4507
  effective,
4493
4508
  owners,
@@ -4608,7 +4623,7 @@ export class SyncClient {
4608
4623
  onProgress(bytes.byteLength);
4609
4624
  const hash = await sha256Hex(bytes);
4610
4625
  if (`sha256:${hash}` !== frame.segmentId) {
4611
- throw invalidRequest(`segment ${frame.segmentId} failed content-address verification (§5.1)`, true);
4626
+ throw invalidRequest('segment failed content-address verification (§5.1)', true);
4612
4627
  }
4613
4628
  return bytes;
4614
4629
  }
@@ -4974,9 +4989,6 @@ export class SyncClient {
4974
4989
  }
4975
4990
  }
4976
4991
  /** Re-apply every pending outbox commit on top of server state (§7.1). */
4977
- #discardAcknowledgedRows() {
4978
- this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL`);
4979
- }
4980
4992
  #dropRetainedRows(batch, matches) {
4981
4993
  const scope = [];
4982
4994
  for (const commit of dropFailedRows(this.#db, this.#schema, matches)) {
package/dist/schema.d.ts CHANGED
@@ -25,6 +25,10 @@ export interface ClientFtsIndexSpec {
25
25
  }
26
26
  export interface ClientTableSchema {
27
27
  readonly name: string;
28
+ /** §7.4.3 table generation from `typegen`: a schema bump keeps the table
29
+ * while it equals the generation the replica persisted. Absent in a
30
+ * hand-written schema, whose bumps reset every table. */
31
+ readonly generation?: string;
28
32
  /** Columns in schema-IR declaration order (the row-codec order, §2.4). */
29
33
  readonly columns: readonly RowColumn[];
30
34
  readonly primaryKey: string;
@@ -42,6 +46,7 @@ export interface ClientSchema {
42
46
  }
43
47
  export interface CompiledClientTable {
44
48
  readonly name: string;
49
+ readonly generation?: string;
45
50
  readonly columns: readonly RowColumn[];
46
51
  readonly primaryKey: string;
47
52
  readonly primaryKeyIndex: number;
@@ -129,16 +134,19 @@ export declare function ensureLocalBookkeepingSchema(db: ClientDatabase): void;
129
134
  /** Create both application and protected bookkeeping tables. */
130
135
  export declare function ensureLocalSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
131
136
  /**
132
- * §7.4.3 reset: drop every synced local table (whatever the *previous*
133
- * generated schema created — discovered from `sqlite_master`, since a
134
- * bump may add/remove tables) and recreate the synced tables from the
135
- * NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
136
- * units, blob cache) are preserved. RFC 0005's container is not
137
- * reachable from here: it lives in its own database file, so this reset cannot
138
- * see or destroy it. Caller owns the surrounding transaction and the
139
- * unit-state reset (state.ts).
137
+ * §7.4.3 reset, §2.1 log reset and local rebootstrap: drop every synced local
138
+ * table (whatever the *previous* generated schema created, discovered from
139
+ * `sqlite_master`, since a bump may add/remove tables) with its acknowledged
140
+ * retained rows, recreate the synced tables from the NEW schema, and reset
141
+ * every unit to a fresh bootstrap. A bump first prunes incompatible units and
142
+ * keeps each table whose generation is unchanged, with its rows and indexes
143
+ * (its FTS projections are rebuilt from the kept rows), and each unit that
144
+ * covers only kept tables. Bookkeeping
145
+ * tables (`_syncular_*`: outbox, meta, units, blob cache) are preserved; RFC
146
+ * 0005's container lives in its own database file. Returns the tables whose
147
+ * rows changed. Caller owns the surrounding transaction.
140
148
  */
141
- export declare function dropAndRecreateSyncedTables(db: ClientDatabase, schema: CompiledClientSchema): void;
149
+ export declare function resetLocalReplica(db: ClientDatabase, schema: CompiledClientSchema, bump?: boolean): string[];
142
150
  /** RowValue → SQL bind value for the local mirror tables. */
143
151
  export declare function toSqlValue(value: RowValue): SqlValue;
144
152
  /** SQL cell → RowValue per the column's declared type. */
package/dist/schema.js CHANGED
@@ -3,8 +3,8 @@ 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 { META_TABLE, resetUnits, UNITS_TABLE } from './state.js';
7
- import { ensureFailedOverlaySchema } from './failed-overlay.js';
6
+ import { META_TABLE, pruneUnknownUnits, resetUnits, UNITS_TABLE, } from './state.js';
7
+ import { ensureFailedOverlaySchema, RETAINED_ROWS } from './failed-overlay.js';
8
8
  import { ClientSyncError, invalidRequest } from './errors.js';
9
9
  import { snakeToCamel } from './naming.js';
10
10
  const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
@@ -40,6 +40,9 @@ export function compileClientSchema(schema) {
40
40
  invalidSchema(`table ${JSON.stringify(table.name)} conflicts with an index or FTS projection`);
41
41
  }
42
42
  schemaObjectNames.add(table.name);
43
+ if (table.generation !== undefined &&
44
+ (typeof table.generation !== 'string' || table.generation === ''))
45
+ invalidSchema(`${tableLabel}: generation must be a non-empty string`);
43
46
  const columnIndex = new Map();
44
47
  table.columns.forEach((column, index) => {
45
48
  if (columnIndex.has(column.name)) {
@@ -124,6 +127,9 @@ export function compileClientSchema(schema) {
124
127
  }
125
128
  tables.set(table.name, {
126
129
  name: table.name,
130
+ ...(table.generation !== undefined
131
+ ? { generation: table.generation }
132
+ : {}),
127
133
  columns: table.columns,
128
134
  primaryKey: table.primaryKey,
129
135
  primaryKeyIndex,
@@ -487,35 +493,43 @@ export function ensureLocalSchema(db, schema) {
487
493
  /** Bookkeeping tables the schema-bump reset (§7.4.3) MUST NOT drop. */
488
494
  const RESERVED_TABLE_PREFIX = '_syncular_';
489
495
  /**
490
- * §7.4.3 reset: drop every synced local table (whatever the *previous*
491
- * generated schema created — discovered from `sqlite_master`, since a
492
- * bump may add/remove tables) and recreate the synced tables from the
493
- * NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
494
- * units, blob cache) are preserved. RFC 0005's container is not
495
- * reachable from here: it lives in its own database file, so this reset cannot
496
- * see or destroy it. Caller owns the surrounding transaction and the
497
- * unit-state reset (state.ts).
496
+ * §7.4.3 reset, §2.1 log reset and local rebootstrap: drop every synced local
497
+ * table (whatever the *previous* generated schema created, discovered from
498
+ * `sqlite_master`, since a bump may add/remove tables) with its acknowledged
499
+ * retained rows, recreate the synced tables from the NEW schema, and reset
500
+ * every unit to a fresh bootstrap. A bump first prunes incompatible units and
501
+ * keeps each table whose generation is unchanged, with its rows and indexes
502
+ * (its FTS projections are rebuilt from the kept rows), and each unit that
503
+ * covers only kept tables. Bookkeeping
504
+ * tables (`_syncular_*`: outbox, meta, units, blob cache) are preserved; RFC
505
+ * 0005's container lives in its own database file. Returns the tables whose
506
+ * rows changed. Caller owns the surrounding transaction.
498
507
  */
499
- export function dropAndRecreateSyncedTables(db, schema) {
508
+ export function resetLocalReplica(db, schema, bump = false) {
509
+ const kept = bump
510
+ ? pruneUnknownUnits(db, schema, true)
511
+ : { tables: new Set(), units: [] };
512
+ const keptNames = [...kept.tables];
513
+ db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl NOT IN(${keptNames.map(() => '?')})`, keptNames);
500
514
  // Drop virtual tables first. SQLite then removes their shadow tables as one
501
515
  // unit, so the generic discovery below never tears an FTS5 projection apart.
502
- const virtualTables = db.query(`SELECT name FROM sqlite_master WHERE type='table' AND sql LIKE 'CREATE VIRTUAL TABLE%' AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%'`);
503
- for (const row of virtualTables) {
504
- db.exec(`DROP TABLE IF EXISTS ${quoteIdent(`_syncular_fts_${String(row.name)}`)}`);
505
- db.exec(`DROP TABLE IF EXISTS ${quoteIdent(String(row.name))}`);
516
+ for (const row of db.query(`SELECT name FROM sqlite_master WHERE type='table' AND sql LIKE 'CREATE VIRTUAL TABLE%' AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%'`)) {
517
+ const name = String(row.name);
518
+ db.exec(`DROP TABLE IF EXISTS ${quoteIdent(`_syncular_fts_${name}`)}`);
519
+ db.exec(`DROP TABLE IF EXISTS ${quoteIdent(name)}`);
506
520
  }
507
- const existing = db.query(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%' AND name NOT LIKE 'sqlite_%'`);
508
- for (const row of existing) {
509
- db.exec(`DROP TABLE IF EXISTS ${quoteIdent(String(row.name))}`);
521
+ for (const row of db.query(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%' AND name NOT LIKE 'sqlite_%'`)) {
522
+ const name = String(row.name);
523
+ if (!kept.tables.has(name))
524
+ db.exec(`DROP TABLE IF EXISTS ${quoteIdent(name)}`);
510
525
  }
511
- for (const table of schema.tables.values()) {
526
+ for (const table of schema.tables.values())
512
527
  createSyncedTable(db, table);
513
- }
514
- for (const table of schema.tables.values()) {
515
- for (const index of table.ftsIndexes) {
528
+ for (const table of schema.tables.values())
529
+ for (const index of table.ftsIndexes)
516
530
  createFtsProjection(db, table, index);
517
- }
518
- }
531
+ resetUnits(db, kept.units);
532
+ return [...schema.tables.keys()].filter((name) => !kept.tables.has(name));
519
533
  }
520
534
  // ---------------------------------------------------------------------------
521
535
  // Value conversion
package/dist/state.d.ts CHANGED
@@ -62,22 +62,29 @@ export declare function saveUnit(db: ClientDatabase, record: UnitRecord): void;
62
62
  export declare function deleteUnit(db: ClientDatabase, id: string): void;
63
63
  /**
64
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.
65
+ * registrations (the app's declared intent) and discard the synced state of
66
+ * every unit outside `keep`, so the next round sends the list and
67
+ * fresh-bootstraps those units. The replica cursor survives only while a
68
+ * kept unit is live. Caller owns the transaction.
68
69
  */
69
- export declare function resetUnits(db: ClientDatabase): void;
70
+ export declare function resetUnits(db: ClientDatabase, keep?: readonly string[]): void;
70
71
  /** §4.5: the replica cursor, `-1` while no unit is live. */
71
72
  export declare function replicaCursor(db: ClientDatabase): number;
72
- /** §7.4.3 declaration evidence, persisted beside the schema marker. */
73
+ /** §7.4.3 declaration evidence and table generations, persisted beside the
74
+ * schema marker. */
73
75
  export declare function saveUnitScopeSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
74
76
  /**
75
77
  * Drop units that cover no table of the running schema, with their window
76
78
  * registry rows and pending evictions; never translate scopes. At a bump
77
79
  * (§7.4.3) a unit also needs every variable unchanged in prefix and column on
78
- * every table it covered before.
80
+ * every table it covered before, and the bump keeps each table whose
81
+ * generation is unchanged and each unit that covers only kept tables, before
82
+ * and after. Runs before the reset rewrites the evidence.
79
83
  */
80
- export declare function pruneUnknownUnits(db: ClientDatabase, schema: CompiledClientSchema, bump?: boolean): void;
84
+ export declare function pruneUnknownUnits(db: ClientDatabase, schema: CompiledClientSchema, bump?: boolean): {
85
+ readonly tables: ReadonlySet<string>;
86
+ readonly units: string[];
87
+ };
81
88
  export declare function getMeta(db: ClientDatabase, key: string): string | undefined;
82
89
  export declare function setMeta(db: ClientDatabase, key: string, value: string): void;
83
90
  /** Read the durable client-local observer revision (SPEC §7.5). */
package/dist/state.js CHANGED
@@ -140,44 +140,66 @@ export function deleteUnit(db, id) {
140
140
  }
141
141
  /**
142
142
  * §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
143
- * registrations (the app's declared intent) and discard every synced state,
144
- * so the next round sends the list and fresh-bootstraps every unit. Caller
145
- * owns the transaction.
143
+ * registrations (the app's declared intent) and discard the synced state of
144
+ * every unit outside `keep`, so the next round sends the list and
145
+ * fresh-bootstraps those units. The replica cursor survives only while a
146
+ * kept unit is live. Caller owns the transaction.
146
147
  */
147
- export function resetUnits(db) {
148
- db.exec(`UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL`);
149
- db.exec(`DELETE FROM ${META_TABLE} WHERE key IN(?,?,?)`, [
150
- REPLICA_CURSOR_KEY,
151
- ECHO_DIGEST_KEY,
152
- REGISTERED_DIGEST_KEY,
153
- ]);
148
+ export function resetUnits(db, keep = []) {
149
+ db.exec(`UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL WHERE id NOT IN(${keep.map(() => '?').join(',')})`, [...keep]);
150
+ db.exec(`DELETE FROM ${META_TABLE} WHERE key IN(?,?) OR key=? AND NOT EXISTS(SELECT 1 FROM ${UNITS_TABLE} WHERE cursor IS NULL)`, [ECHO_DIGEST_KEY, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY]);
154
151
  }
155
152
  /** §4.5: the replica cursor, `-1` while no unit is live. */
156
153
  export function replicaCursor(db) {
157
154
  return Number(getMeta(db, REPLICA_CURSOR_KEY) ?? -1);
158
155
  }
159
- /** §7.4.3 declaration evidence, persisted beside the schema marker. */
156
+ /** §7.4.3 declaration evidence and table generations, persisted beside the
157
+ * schema marker. */
160
158
  export function saveUnitScopeSchema(db, schema) {
161
159
  const declarations = {};
160
+ const generations = {};
162
161
  for (const table of schema.tables.values()) {
162
+ if (table.generation !== undefined)
163
+ generations[table.name] = table.generation;
163
164
  declarations[table.name] = Object.fromEntries([...table.scopeColumnByVariable].map(([variable, column]) => [
164
165
  variable,
165
166
  [table.scopePrefixByVariable.get(variable), column],
166
167
  ]));
167
168
  }
168
169
  setMeta(db, 'subscriptionScopeSchema', JSON.stringify(declarations));
170
+ setMeta(db, 'localTableGenerations', JSON.stringify(generations));
169
171
  }
170
172
  /**
171
173
  * Drop units that cover no table of the running schema, with their window
172
174
  * registry rows and pending evictions; never translate scopes. At a bump
173
175
  * (§7.4.3) a unit also needs every variable unchanged in prefix and column on
174
- * every table it covered before.
176
+ * every table it covered before, and the bump keeps each table whose
177
+ * generation is unchanged and each unit that covers only kept tables, before
178
+ * and after. Runs before the reset rewrites the evidence.
175
179
  */
176
180
  export function pruneUnknownUnits(db, schema, bump = false) {
177
181
  const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
178
182
  const previous = stored === undefined
179
183
  ? undefined
180
184
  : JSON.parse(stored);
185
+ let generations = {};
186
+ try {
187
+ if (bump)
188
+ generations = JSON.parse(getMeta(db, 'localTableGenerations') ?? '{}');
189
+ }
190
+ catch {
191
+ generations = null;
192
+ }
193
+ if (typeof generations !== 'object' ||
194
+ generations === null ||
195
+ Array.isArray(generations) ||
196
+ Object.values(generations).some((value) => typeof value !== 'string'))
197
+ throw new ClientSyncError('sync.local_corrupt', 'invalid persisted table generations');
198
+ const kept = new Set([...schema.tables.values()]
199
+ .filter((table) => table.generation !== undefined &&
200
+ generations[table.name] ===
201
+ table.generation)
202
+ .map((table) => table.name));
181
203
  // A table keeps the variables' meaning when each has the same prefix and
182
204
  // column as before. An old binary stored no declaration evidence; matching
183
205
  // names cannot prove unchanged meaning, so the app registers again.
@@ -219,6 +241,14 @@ export function pruneUnknownUnits(db, schema, bump = false) {
219
241
  db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?`, [id]);
220
242
  deleteUnit(db, id);
221
243
  }
244
+ return {
245
+ tables: kept,
246
+ units: loadUnits(db)
247
+ .filter(({ scopes }) => Object.entries(previous ?? {}).every(([name, old]) => kept.has(name) ||
248
+ !Object.keys(scopes).every((v) => old[v] !== undefined)) &&
249
+ [...schema.tables.values()].every((table) => kept.has(table.name) || !covers(table, scopes)))
250
+ .map((unit) => unit.id),
251
+ };
222
252
  }
223
253
  export function getMeta(db, key) {
224
254
  const row = db.query(`SELECT value FROM ${META_TABLE} WHERE key=?`, [key])[0];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.75.0",
3
+ "version": "0.77.0",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -121,11 +121,11 @@
121
121
  },
122
122
  "dependencies": {
123
123
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
124
- "@syncular/core": "0.75.0"
124
+ "@syncular/core": "0.77.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.75.0",
128
+ "@syncular/server": "0.77.0",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/apply.ts CHANGED
@@ -521,6 +521,11 @@ export async function applySqliteSegment(
521
521
  readonly isCurrent?: () => boolean;
522
522
  /** Monotonic milliseconds that time each chunk. */
523
523
  readonly now?: () => number;
524
+ /**
525
+ * Table → its next chunk size, carried from one range image of a table
526
+ * to the next (§5.3).
527
+ */
528
+ readonly chunkRows?: Map<string, number>;
524
529
  },
525
530
  ): Promise<number> {
526
531
  const now = options.now ?? (() => performance.now());
@@ -616,11 +621,16 @@ export async function applySqliteSegment(
616
621
  };
617
622
  let [boundary, where, params] = range(undefined, 1024);
618
623
  let applied = 0;
619
- // §5.3: the first chunk holds 1,024 rows. A later chunk holds at least
624
+ // §5.3: a table's first chunk holds 1,024 rows; a later range image
625
+ // starts at the size its previous range reached. A later chunk holds at least
620
626
  // 1,024 rows, at most twice the rows of the one before, at most 65,536,
621
627
  // and at most the rows the one before applied per 250 ms from its start
622
628
  // to its COMMIT; a replaying chunk holds one statement.
623
- for (let size = 1024; ;) {
629
+ for (
630
+ let size =
631
+ (!options.clearFirst && options.chunkRows?.get(table.name)) || 1024;
632
+ ;
633
+ ) {
624
634
  if (options.isCurrent?.() === false) return applied;
625
635
  const started = now();
626
636
  let chunk = 0;
@@ -710,6 +720,7 @@ export async function applySqliteSegment(
710
720
  1024,
711
721
  Math.min(2 * chunk, 65_536, Math.floor((chunk * 250) / duration)),
712
722
  );
723
+ options.chunkRows?.set(table.name, size);
713
724
  [boundary, where, params] = range(boundary, Math.min(1024, size));
714
725
  }
715
726
  if (applied !== count)
package/src/client.ts CHANGED
@@ -225,7 +225,7 @@ import {
225
225
  compileClientSchema,
226
226
  hexToBytes,
227
227
  matchesLocalScopes,
228
- dropAndRecreateSyncedTables,
228
+ resetLocalReplica,
229
229
  ensureLocalBookkeepingSchema,
230
230
  ensureLocalSyncedSchema,
231
231
  fromSqlValue,
@@ -262,7 +262,6 @@ import {
262
262
  REGISTERED_DIGEST_KEY,
263
263
  REPLICA_CURSOR_KEY,
264
264
  replicaCursor,
265
- resetUnits,
266
265
  saveUnit,
267
266
  saveUnitScopeSchema,
268
267
  setMeta,
@@ -738,6 +737,19 @@ async function sha256Hex(bytes: Uint8Array): Promise<string> {
738
737
  .join('');
739
738
  }
740
739
 
740
+ const invalidHostResponse = (message: string) =>
741
+ new ClientSyncError('client.invalid_host_response', message);
742
+
743
+ const outcomeNotFound = () =>
744
+ new ClientSyncError(
745
+ 'sync.outcome_not_found',
746
+ 'no durable outcome exists for the commit',
747
+ );
748
+
749
+ /** The position a unit presents in a pull (§5.6 applied-segment rule). */
750
+ const position = (unit: UnitRecord) =>
751
+ JSON.stringify([unit.id, unit.cursor, unit.bootstrapState]);
752
+
741
753
  interface OpenSection {
742
754
  readonly start: SubStartFrame;
743
755
  readonly unit: UnitRecord;
@@ -970,6 +982,13 @@ export class SyncClient {
970
982
  #pendingRound: PendingRound | undefined;
971
983
  #needsPull = false;
972
984
  readonly #progress = new ProgressEmitter();
985
+ /**
986
+ * §5.6 applied-segment rule: unit position → the segments applied in
987
+ * sections whose SUB_END did not persist.
988
+ */
989
+ readonly #appliedSegments = new Map<string, Set<string>>();
990
+ /** §5.3: a table's next image chunk size, carried across its ranges. */
991
+ readonly #chunkRows = new Map<string, number>();
973
992
  #progressAttempt = 0;
974
993
  /**
975
994
  * True from the synchronous entry of `sync()` until its serialized round
@@ -1365,8 +1384,9 @@ export class SyncClient {
1365
1384
 
1366
1385
  /**
1367
1386
  * §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
1368
- * and leaseState. Drops/recreates every synced table from the new schema,
1369
- * resets subscription sync-state (keeping registrations), clears any
1387
+ * leaseState, and the tables and units a bump keeps (equal generations).
1388
+ * Drops/recreates every other synced table from the new schema, resets the
1389
+ * other units' sync-state (keeping registrations), clears any
1370
1390
  * schema-floor stop state, rewrites the marker, and raises `upgrading`.
1371
1391
  * The bump is idempotent by the marker (rewritten last).
1372
1392
  */
@@ -1382,6 +1402,7 @@ export class SyncClient {
1382
1402
  // existing marker, with no cross-file transaction.
1383
1403
  this.#sweepPreviousVersionContainer();
1384
1404
  this.#capturePreviousVersion(previousVersion);
1405
+ let changed: string[] = [];
1385
1406
  this.#applyBatch((batch) => {
1386
1407
  this.#db.transaction(() => {
1387
1408
  if (this.#previousVersion !== undefined) {
@@ -1396,10 +1417,7 @@ export class SyncClient {
1396
1417
  ),
1397
1418
  );
1398
1419
  }
1399
- pruneUnknownUnits(this.#db, this.#schema, true);
1400
- this.#discardAcknowledgedRows();
1401
- dropAndRecreateSyncedTables(this.#db, this.#schema);
1402
- resetUnits(this.#db);
1420
+ changed = resetLocalReplica(this.#db, this.#schema, true);
1403
1421
  this.#replayOutbox();
1404
1422
  setMeta(
1405
1423
  this.#db,
@@ -1409,8 +1427,8 @@ export class SyncClient {
1409
1427
  setLocalSchemaDescriptor(this.#db, this.#schema);
1410
1428
  saveUnitScopeSchema(this.#db, this.#schema);
1411
1429
  });
1412
- // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
1413
- for (const table of this.#schema.tables.values()) batch.table(table.name);
1430
+ // Every table the reset dropped changed (I1 eviction-shaped).
1431
+ for (const table of changed) batch.table(table);
1414
1432
  });
1415
1433
  // The stop state is over: this client now ships a servable schema.
1416
1434
  // The reset transaction already replayed pending intent before committing
@@ -1506,9 +1524,7 @@ export class SyncClient {
1506
1524
  this.#applyBatch(
1507
1525
  (batch) => {
1508
1526
  this.#db.transaction(() => {
1509
- this.#discardAcknowledgedRows();
1510
- dropAndRecreateSyncedTables(this.#db, this.#schema);
1511
- resetUnits(this.#db);
1527
+ resetLocalReplica(this.#db, this.#schema);
1512
1528
  setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
1513
1529
  // §7.1/§7.4.4: recover codec-invalid persisted values in this reset
1514
1530
  // transaction before they replay, so the reset boundary never fails on
@@ -1518,8 +1534,7 @@ export class SyncClient {
1518
1534
  this.#applyOperationsLocally(commit.operations, batch);
1519
1535
  }
1520
1536
  });
1521
- for (const table of this.#schema.tables.values())
1522
- batch.table(table.name);
1537
+ for (const table of this.#schema.tables.keys()) batch.table(table);
1523
1538
  },
1524
1539
  undefined,
1525
1540
  (error) => {
@@ -2945,10 +2960,7 @@ export class SyncClient {
2945
2960
  this.#requireActive();
2946
2961
  const current = readCommitOutcome(this.#db, input.clientCommitId);
2947
2962
  if (current === undefined) {
2948
- throw new ClientSyncError(
2949
- 'sync.outcome_not_found',
2950
- `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`,
2951
- );
2963
+ throw outcomeNotFound();
2952
2964
  }
2953
2965
  if (current.resolution !== 'active') return current;
2954
2966
  const replacement = input.replacementClientCommitId;
@@ -2993,10 +3005,7 @@ export class SyncClient {
2993
3005
  this.#now(),
2994
3006
  );
2995
3007
  if (resolved === undefined) {
2996
- throw new ClientSyncError(
2997
- 'sync.outcome_not_found',
2998
- `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`,
2999
- );
3008
+ throw outcomeNotFound();
3000
3009
  }
3001
3010
  this.#conflicts = this.#conflicts.filter(
3002
3011
  (record) => record.clientCommitId !== input.clientCommitId,
@@ -3926,12 +3935,8 @@ export class SyncClient {
3926
3935
  this.#upgrading = true;
3927
3936
  this.#needsPull = true;
3928
3937
  batch.status();
3929
- this.#discardAcknowledgedRows();
3930
- dropAndRecreateSyncedTables(this.#db, this.#schema);
3931
- resetUnits(this.#db);
3932
- for (const table of this.#schema.tables.values()) {
3933
- batch.table(table.name);
3934
- }
3938
+ for (const table of resetLocalReplica(this.#db, this.#schema))
3939
+ batch.table(table);
3935
3940
  for (const commit of pending) {
3936
3941
  this.#applyOperationsLocally(commit.operations, batch);
3937
3942
  }
@@ -5380,8 +5385,7 @@ export class SyncClient {
5380
5385
  const currentLogEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
5381
5386
  if (header.resetRequired) {
5382
5387
  if (mode !== 'pull' || message.frames.length !== 1) {
5383
- throw new ClientSyncError(
5384
- 'client.invalid_host_response',
5388
+ throw invalidHostResponse(
5385
5389
  'a log-epoch reset response must contain only RESP_HEADER',
5386
5390
  );
5387
5391
  }
@@ -5392,8 +5396,7 @@ export class SyncClient {
5392
5396
  };
5393
5397
  }
5394
5398
  if (currentLogEpoch === undefined || currentLogEpoch !== header.logEpoch) {
5395
- throw new ClientSyncError(
5396
- 'client.invalid_host_response',
5399
+ throw invalidHostResponse(
5397
5400
  'the server changed logEpoch without requiring a reset',
5398
5401
  );
5399
5402
  }
@@ -5412,7 +5415,9 @@ export class SyncClient {
5412
5415
  // bootstrap overlaps its page fetches instead of paying one blocking round
5413
5416
  // trip per page. At most four downloads run at once, the Rust native
5414
5417
  // transport's pool size: enough to overlap round trips, while the client
5415
- // holds at most four bodies, the one being applied and three ahead. The
5418
+ // holds at most four bodies, the one being applied and three ahead. An
5419
+ // image starts only beside at most one other body, so at most two are
5420
+ // images (§5.3 client memory); later descriptors wait in order. The
5416
5421
  // loop takes each body out of the map before applying it and tops the
5417
5422
  // window up at the next descriptor. Eligibility mirrors the loop: a
5418
5423
  // descriptor outside an applied section or from an unconfigured
@@ -5422,7 +5427,12 @@ export class SyncClient {
5422
5427
  const queued: [SegmentRefFrame, UnitScopes][] = [];
5423
5428
  const prefetched = new Map<SegmentRefFrame, Promise<Uint8Array>>();
5424
5429
  const prefetch = () => {
5425
- for (let next; prefetched.size < 4 && (next = queued.shift());) {
5430
+ for (
5431
+ let next;
5432
+ prefetched.size < 4 &&
5433
+ !(queued[0]?.[0].mediaType === 'sqlite' && prefetched.size > 1) &&
5434
+ (next = queued.shift());
5435
+ ) {
5426
5436
  const [frame, scopes] = next;
5427
5437
  const pending = this.#downloadSegment(
5428
5438
  frame,
@@ -5454,10 +5464,7 @@ export class SyncClient {
5454
5464
  frame.type === 'SEGMENT_REF' &&
5455
5465
  open !== undefined &&
5456
5466
  this.#config.segments !== undefined &&
5457
- !(
5458
- frame.mediaType === 'sqlite' &&
5459
- (this.#acceptMask() & ACCEPT_SQLITE) === 0
5460
- )
5467
+ !this.#appliedSegments.get(position(open))?.has(frame.segmentId)
5461
5468
  ) {
5462
5469
  queued.push([frame, open.scopes]);
5463
5470
  }
@@ -5575,14 +5582,27 @@ export class SyncClient {
5575
5582
  case 'SEGMENT_REF': {
5576
5583
  if (section === undefined || section.skip) break;
5577
5584
  const unitId = section.unit.id;
5585
+ const image =
5586
+ frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite'
5587
+ ? frame
5588
+ : undefined;
5589
+ // §4.2, §5.3: an image needs accept bit 2 and carries no cursors.
5578
5590
  if (
5579
- frame.type === 'SEGMENT_REF' &&
5580
- frame.mediaType === 'sqlite' &&
5581
- (this.#acceptMask() & ACCEPT_SQLITE) === 0
5582
- ) {
5591
+ image !== undefined &&
5592
+ ((this.#acceptMask() & ACCEPT_SQLITE) === 0 ||
5593
+ image.rowCursor !== undefined ||
5594
+ image.nextRowCursor !== undefined)
5595
+ )
5583
5596
  throw invalidRequest(
5584
- 'SEGMENT_REF mediaType sqlite was not advertised in accept (§4.2)',
5597
+ 'unadvertised or paged sqlite segment (§4.2, §5.3)',
5585
5598
  );
5599
+ const applied =
5600
+ this.#appliedSegments.get(position(section.unit)) ??
5601
+ new Set<string>();
5602
+ if (frame.type === 'SEGMENT_REF' && applied.has(frame.segmentId)) {
5603
+ // §5.6: applied in an earlier attempt at this position.
5604
+ section.seeded.add(frame.table);
5605
+ break;
5586
5606
  }
5587
5607
  let bytes: Uint8Array;
5588
5608
  if (frame.type === 'SEGMENT_REF') {
@@ -5626,19 +5646,6 @@ export class SyncClient {
5626
5646
  } else {
5627
5647
  bytes = frame.payload;
5628
5648
  }
5629
- const image =
5630
- frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite'
5631
- ? frame
5632
- : undefined;
5633
- // Images are whole-table; paged image descriptors are invalid.
5634
- if (
5635
- image !== undefined &&
5636
- (image.rowCursor !== undefined ||
5637
- image.nextRowCursor !== undefined)
5638
- )
5639
- throw invalidRequest(
5640
- 'sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)',
5641
- );
5642
5649
  const segment =
5643
5650
  image === undefined ? decodeRowsSegment(bytes) : undefined;
5644
5651
  if (frame.type === 'SEGMENT_INLINE' && segment !== undefined)
@@ -5689,6 +5696,11 @@ export class SyncClient {
5689
5696
  );
5690
5697
  },
5691
5698
  );
5699
+ if (frame.type === 'SEGMENT_REF' && !section.skip)
5700
+ this.#appliedSegments.set(
5701
+ position(section.unit),
5702
+ applied.add(frame.segmentId),
5703
+ );
5692
5704
  break;
5693
5705
  }
5694
5706
  case 'SUB_END': {
@@ -5699,8 +5711,10 @@ export class SyncClient {
5699
5711
  section !== undefined &&
5700
5712
  !section.skip &&
5701
5713
  this.#localResetEpoch === resetEpoch
5702
- )
5714
+ ) {
5703
5715
  this.#finishSection(section, frame, summary);
5716
+ this.#appliedSegments.delete(position(section.unit));
5717
+ }
5704
5718
  section = undefined;
5705
5719
  // The counters stay: `complete` and `failed` report them.
5706
5720
  this.#progress.update({
@@ -5918,10 +5932,7 @@ export class SyncClient {
5918
5932
  // §6.3: applied and cached both drain the outbox — cached means
5919
5933
  // "already applied, you may have missed the ack".
5920
5934
  if (frame.commitSeq === undefined)
5921
- throw new ClientSyncError(
5922
- 'client.invalid_host_response',
5923
- 'ACK lacks a commit sequence',
5924
- );
5935
+ throw invalidHostResponse('ACK lacks a commit sequence');
5925
5936
  retainFailedRows(
5926
5937
  this.#db,
5927
5938
  commit,
@@ -6186,10 +6197,11 @@ export class SyncClient {
6186
6197
  hasRows: boolean,
6187
6198
  resetEpoch: number,
6188
6199
  image: boolean,
6189
- ): Parameters<typeof applyRowsSegment>[4] {
6200
+ ): Parameters<typeof applySqliteSegment>[5] {
6190
6201
  let writeMs = 0;
6191
6202
  let commitMs = 0;
6192
6203
  return {
6204
+ chunkRows: this.#chunkRows,
6193
6205
  clearFirst,
6194
6206
  effective,
6195
6207
  owners,
@@ -6354,7 +6366,7 @@ export class SyncClient {
6354
6366
  const hash = await sha256Hex(bytes);
6355
6367
  if (`sha256:${hash}` !== frame.segmentId) {
6356
6368
  throw invalidRequest(
6357
- `segment ${frame.segmentId} failed content-address verification (§5.1)`,
6369
+ 'segment failed content-address verification (§5.1)',
6358
6370
  true,
6359
6371
  );
6360
6372
  }
@@ -6827,10 +6839,6 @@ export class SyncClient {
6827
6839
  }
6828
6840
 
6829
6841
  /** Re-apply every pending outbox commit on top of server state (§7.1). */
6830
- #discardAcknowledgedRows(): void {
6831
- this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL`);
6832
- }
6833
-
6834
6842
  #dropRetainedRows(
6835
6843
  batch: ChangeAccumulator,
6836
6844
  matches: (
package/src/schema.ts CHANGED
@@ -3,8 +3,13 @@ import { PENDING_EVICTIONS } from './window';
3
3
  import { WINDOWS_TABLE } from './window';
4
4
  import { OUTBOX_TABLE, OUTBOX_IMAGES } from './outbox';
5
5
  import { OUTCOMES_TABLE } from './outcomes';
6
- import { META_TABLE, resetUnits, UNITS_TABLE } from './state';
7
- import { ensureFailedOverlaySchema } from './failed-overlay';
6
+ import {
7
+ META_TABLE,
8
+ pruneUnknownUnits,
9
+ resetUnits,
10
+ UNITS_TABLE,
11
+ } from './state';
12
+ import { ensureFailedOverlaySchema, RETAINED_ROWS } from './failed-overlay';
8
13
  /**
9
14
  * Client schema IR (SPEC.md §2.4, §3.1) — the same shape the server
10
15
  * compiles and is emitted by codegen. Drives local table
@@ -35,6 +40,10 @@ export interface ClientFtsIndexSpec {
35
40
 
36
41
  export interface ClientTableSchema {
37
42
  readonly name: string;
43
+ /** §7.4.3 table generation from `typegen`: a schema bump keeps the table
44
+ * while it equals the generation the replica persisted. Absent in a
45
+ * hand-written schema, whose bumps reset every table. */
46
+ readonly generation?: string;
38
47
  /** Columns in schema-IR declaration order (the row-codec order, §2.4). */
39
48
  readonly columns: readonly RowColumn[];
40
49
  readonly primaryKey: string;
@@ -54,6 +63,7 @@ export interface ClientSchema {
54
63
 
55
64
  export interface CompiledClientTable {
56
65
  readonly name: string;
66
+ readonly generation?: string;
57
67
  readonly columns: readonly RowColumn[];
58
68
  readonly primaryKey: string;
59
69
  readonly primaryKeyIndex: number;
@@ -131,6 +141,11 @@ export function compileClientSchema(
131
141
  );
132
142
  }
133
143
  schemaObjectNames.add(table.name);
144
+ if (
145
+ table.generation !== undefined &&
146
+ (typeof table.generation !== 'string' || table.generation === '')
147
+ )
148
+ invalidSchema(`${tableLabel}: generation must be a non-empty string`);
134
149
  const columnIndex = new Map<string, number>();
135
150
  table.columns.forEach((column, index) => {
136
151
  if (columnIndex.has(column.name)) {
@@ -235,6 +250,9 @@ export function compileClientSchema(
235
250
  }
236
251
  tables.set(table.name, {
237
252
  name: table.name,
253
+ ...(table.generation !== undefined
254
+ ? { generation: table.generation }
255
+ : {}),
238
256
  columns: table.columns,
239
257
  primaryKey: table.primaryKey,
240
258
  primaryKeyIndex,
@@ -736,44 +754,52 @@ export function ensureLocalSchema(
736
754
  const RESERVED_TABLE_PREFIX = '_syncular_';
737
755
 
738
756
  /**
739
- * §7.4.3 reset: drop every synced local table (whatever the *previous*
740
- * generated schema created — discovered from `sqlite_master`, since a
741
- * bump may add/remove tables) and recreate the synced tables from the
742
- * NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
743
- * units, blob cache) are preserved. RFC 0005's container is not
744
- * reachable from here: it lives in its own database file, so this reset cannot
745
- * see or destroy it. Caller owns the surrounding transaction and the
746
- * unit-state reset (state.ts).
757
+ * §7.4.3 reset, §2.1 log reset and local rebootstrap: drop every synced local
758
+ * table (whatever the *previous* generated schema created, discovered from
759
+ * `sqlite_master`, since a bump may add/remove tables) with its acknowledged
760
+ * retained rows, recreate the synced tables from the NEW schema, and reset
761
+ * every unit to a fresh bootstrap. A bump first prunes incompatible units and
762
+ * keeps each table whose generation is unchanged, with its rows and indexes
763
+ * (its FTS projections are rebuilt from the kept rows), and each unit that
764
+ * covers only kept tables. Bookkeeping
765
+ * tables (`_syncular_*`: outbox, meta, units, blob cache) are preserved; RFC
766
+ * 0005's container lives in its own database file. Returns the tables whose
767
+ * rows changed. Caller owns the surrounding transaction.
747
768
  */
748
- export function dropAndRecreateSyncedTables(
769
+ export function resetLocalReplica(
749
770
  db: ClientDatabase,
750
771
  schema: CompiledClientSchema,
751
- ): void {
772
+ bump = false,
773
+ ): string[] {
774
+ const kept = bump
775
+ ? pruneUnknownUnits(db, schema, true)
776
+ : { tables: new Set<string>(), units: [] };
777
+ const keptNames = [...kept.tables];
778
+ db.exec(
779
+ `DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl NOT IN(${keptNames.map(() => '?')})`,
780
+ keptNames,
781
+ );
752
782
  // Drop virtual tables first. SQLite then removes their shadow tables as one
753
783
  // unit, so the generic discovery below never tears an FTS5 projection apart.
754
- const virtualTables = db.query(
784
+ for (const row of db.query(
755
785
  `SELECT name FROM sqlite_master WHERE type='table' AND sql LIKE 'CREATE VIRTUAL TABLE%' AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%'`,
756
- );
757
- for (const row of virtualTables) {
758
- db.exec(
759
- `DROP TABLE IF EXISTS ${quoteIdent(`_syncular_fts_${String(row.name)}`)}`,
760
- );
761
- db.exec(`DROP TABLE IF EXISTS ${quoteIdent(String(row.name))}`);
786
+ )) {
787
+ const name = String(row.name);
788
+ db.exec(`DROP TABLE IF EXISTS ${quoteIdent(`_syncular_fts_${name}`)}`);
789
+ db.exec(`DROP TABLE IF EXISTS ${quoteIdent(name)}`);
762
790
  }
763
- const existing = db.query(
791
+ for (const row of db.query(
764
792
  `SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%' AND name NOT LIKE 'sqlite_%'`,
765
- );
766
- for (const row of existing) {
767
- db.exec(`DROP TABLE IF EXISTS ${quoteIdent(String(row.name))}`);
768
- }
769
- for (const table of schema.tables.values()) {
770
- createSyncedTable(db, table);
771
- }
772
- for (const table of schema.tables.values()) {
773
- for (const index of table.ftsIndexes) {
774
- createFtsProjection(db, table, index);
775
- }
793
+ )) {
794
+ const name = String(row.name);
795
+ if (!kept.tables.has(name))
796
+ db.exec(`DROP TABLE IF EXISTS ${quoteIdent(name)}`);
776
797
  }
798
+ for (const table of schema.tables.values()) createSyncedTable(db, table);
799
+ for (const table of schema.tables.values())
800
+ for (const index of table.ftsIndexes) createFtsProjection(db, table, index);
801
+ resetUnits(db, kept.units);
802
+ return [...schema.tables.keys()].filter((name) => !kept.tables.has(name));
777
803
  }
778
804
 
779
805
  // ---------------------------------------------------------------------------
package/src/state.ts CHANGED
@@ -215,19 +215,23 @@ export function deleteUnit(db: ClientDatabase, id: string): void {
215
215
 
216
216
  /**
217
217
  * §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
218
- * registrations (the app's declared intent) and discard every synced state,
219
- * so the next round sends the list and fresh-bootstraps every unit. Caller
220
- * owns the transaction.
218
+ * registrations (the app's declared intent) and discard the synced state of
219
+ * every unit outside `keep`, so the next round sends the list and
220
+ * fresh-bootstraps those units. The replica cursor survives only while a
221
+ * kept unit is live. Caller owns the transaction.
221
222
  */
222
- export function resetUnits(db: ClientDatabase): void {
223
+ export function resetUnits(
224
+ db: ClientDatabase,
225
+ keep: readonly string[] = [],
226
+ ): void {
223
227
  db.exec(
224
- `UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL`,
228
+ `UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL WHERE id NOT IN(${keep.map(() => '?').join(',')})`,
229
+ [...keep],
230
+ );
231
+ db.exec(
232
+ `DELETE FROM ${META_TABLE} WHERE key IN(?,?) OR key=? AND NOT EXISTS(SELECT 1 FROM ${UNITS_TABLE} WHERE cursor IS NULL)`,
233
+ [ECHO_DIGEST_KEY, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY],
225
234
  );
226
- db.exec(`DELETE FROM ${META_TABLE} WHERE key IN(?,?,?)`, [
227
- REPLICA_CURSOR_KEY,
228
- ECHO_DIGEST_KEY,
229
- REGISTERED_DIGEST_KEY,
230
- ]);
231
235
  }
232
236
 
233
237
  /** §4.5: the replica cursor, `-1` while no unit is live. */
@@ -240,13 +244,17 @@ type ScopeDeclarations = Record<
240
244
  Record<string, readonly [string, string]>
241
245
  >;
242
246
 
243
- /** §7.4.3 declaration evidence, persisted beside the schema marker. */
247
+ /** §7.4.3 declaration evidence and table generations, persisted beside the
248
+ * schema marker. */
244
249
  export function saveUnitScopeSchema(
245
250
  db: ClientDatabase,
246
251
  schema: CompiledClientSchema,
247
252
  ): void {
248
253
  const declarations: ScopeDeclarations = {};
254
+ const generations: Record<string, string> = {};
249
255
  for (const table of schema.tables.values()) {
256
+ if (table.generation !== undefined)
257
+ generations[table.name] = table.generation;
250
258
  declarations[table.name] = Object.fromEntries(
251
259
  [...table.scopeColumnByVariable].map(([variable, column]) => [
252
260
  variable,
@@ -255,24 +263,54 @@ export function saveUnitScopeSchema(
255
263
  );
256
264
  }
257
265
  setMeta(db, 'subscriptionScopeSchema', JSON.stringify(declarations));
266
+ setMeta(db, 'localTableGenerations', JSON.stringify(generations));
258
267
  }
259
268
 
260
269
  /**
261
270
  * Drop units that cover no table of the running schema, with their window
262
271
  * registry rows and pending evictions; never translate scopes. At a bump
263
272
  * (§7.4.3) a unit also needs every variable unchanged in prefix and column on
264
- * every table it covered before.
273
+ * every table it covered before, and the bump keeps each table whose
274
+ * generation is unchanged and each unit that covers only kept tables, before
275
+ * and after. Runs before the reset rewrites the evidence.
265
276
  */
266
277
  export function pruneUnknownUnits(
267
278
  db: ClientDatabase,
268
279
  schema: CompiledClientSchema,
269
280
  bump = false,
270
- ): void {
281
+ ): { readonly tables: ReadonlySet<string>; readonly units: string[] } {
271
282
  const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
272
283
  const previous =
273
284
  stored === undefined
274
285
  ? undefined
275
286
  : (JSON.parse(stored) as ScopeDeclarations);
287
+ let generations: unknown = {};
288
+ try {
289
+ if (bump)
290
+ generations = JSON.parse(getMeta(db, 'localTableGenerations') ?? '{}');
291
+ } catch {
292
+ generations = null;
293
+ }
294
+ if (
295
+ typeof generations !== 'object' ||
296
+ generations === null ||
297
+ Array.isArray(generations) ||
298
+ Object.values(generations).some((value) => typeof value !== 'string')
299
+ )
300
+ throw new ClientSyncError(
301
+ 'sync.local_corrupt',
302
+ 'invalid persisted table generations',
303
+ );
304
+ const kept = new Set(
305
+ [...schema.tables.values()]
306
+ .filter(
307
+ (table) =>
308
+ table.generation !== undefined &&
309
+ (generations as Record<string, unknown>)[table.name] ===
310
+ table.generation,
311
+ )
312
+ .map((table) => table.name),
313
+ );
276
314
  // A table keeps the variables' meaning when each has the same prefix and
277
315
  // column as before. An old binary stored no declaration evidence; matching
278
316
  // names cannot prove unchanged meaning, so the app registers again.
@@ -329,6 +367,22 @@ export function pruneUnknownUnits(
329
367
  db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?`, [id]);
330
368
  deleteUnit(db, id);
331
369
  }
370
+ return {
371
+ tables: kept,
372
+ units: loadUnits(db)
373
+ .filter(
374
+ ({ scopes }) =>
375
+ Object.entries(previous ?? {}).every(
376
+ ([name, old]) =>
377
+ kept.has(name) ||
378
+ !Object.keys(scopes).every((v) => old[v] !== undefined),
379
+ ) &&
380
+ [...schema.tables.values()].every(
381
+ (table) => kept.has(table.name) || !covers(table, scopes),
382
+ ),
383
+ )
384
+ .map((unit) => unit.id),
385
+ };
332
386
  }
333
387
 
334
388
  export function getMeta(db: ClientDatabase, key: string): string | undefined {