@syncular/client 0.76.0 → 0.77.1

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/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';
@@ -537,8 +537,9 @@ export class SyncClient {
537
537
  }
538
538
  /**
539
539
  * §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
540
- * and leaseState. Drops/recreates every synced table from the new schema,
541
- * 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
542
543
  * schema-floor stop state, rewrites the marker, and raises `upgrading`.
543
544
  * The bump is idempotent by the marker (rewritten last).
544
545
  */
@@ -552,23 +553,21 @@ export class SyncClient {
552
553
  // existing marker, with no cross-file transaction.
553
554
  this.#sweepPreviousVersionContainer();
554
555
  this.#capturePreviousVersion(previousVersion);
556
+ let changed = [];
555
557
  this.#applyBatch((batch) => {
556
558
  this.#db.transaction(() => {
557
559
  if (this.#previousVersion !== undefined) {
558
560
  writePreviousVersionAudit(this.#db, buildPreviousVersionAudit(this.#schema, listOutbox(this.#db), previousVersion, this.#schema.version, this.#now()));
559
561
  }
560
- pruneUnknownUnits(this.#db, this.#schema, true);
561
- this.#discardAcknowledgedRows();
562
- dropAndRecreateSyncedTables(this.#db, this.#schema);
563
- resetUnits(this.#db);
562
+ changed = resetLocalReplica(this.#db, this.#schema, true);
564
563
  this.#replayOutbox();
565
564
  setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
566
565
  setLocalSchemaDescriptor(this.#db, this.#schema);
567
566
  saveUnitScopeSchema(this.#db, this.#schema);
568
567
  });
569
- // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
570
- for (const table of this.#schema.tables.values())
571
- batch.table(table.name);
568
+ // Every table the reset dropped changed (I1 eviction-shaped).
569
+ for (const table of changed)
570
+ batch.table(table);
572
571
  });
573
572
  // The stop state is over: this client now ships a servable schema.
574
573
  // The reset transaction already replayed pending intent before committing
@@ -647,9 +646,7 @@ export class SyncClient {
647
646
  const priorRejections = [...this.#rejections];
648
647
  this.#applyBatch((batch) => {
649
648
  this.#db.transaction(() => {
650
- this.#discardAcknowledgedRows();
651
- dropAndRecreateSyncedTables(this.#db, this.#schema);
652
- resetUnits(this.#db);
649
+ resetLocalReplica(this.#db, this.#schema);
653
650
  setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
654
651
  // §7.1/§7.4.4: recover codec-invalid persisted values in this reset
655
652
  // transaction before they replay, so the reset boundary never fails on
@@ -659,8 +656,8 @@ export class SyncClient {
659
656
  this.#applyOperationsLocally(commit.operations, batch);
660
657
  }
661
658
  });
662
- for (const table of this.#schema.tables.values())
663
- batch.table(table.name);
659
+ for (const table of this.#schema.tables.keys())
660
+ batch.table(table);
664
661
  }, undefined, (error) => {
665
662
  // A failure after the recovery drop, including the reset's revision or
666
663
  // COMMIT, rolls the database back: mirror that for the in-memory
@@ -2639,12 +2636,8 @@ export class SyncClient {
2639
2636
  this.#upgrading = true;
2640
2637
  this.#needsPull = true;
2641
2638
  batch.status();
2642
- this.#discardAcknowledgedRows();
2643
- dropAndRecreateSyncedTables(this.#db, this.#schema);
2644
- resetUnits(this.#db);
2645
- for (const table of this.#schema.tables.values()) {
2646
- batch.table(table.name);
2647
- }
2639
+ for (const table of resetLocalReplica(this.#db, this.#schema))
2640
+ batch.table(table);
2648
2641
  for (const commit of pending) {
2649
2642
  this.#applyOperationsLocally(commit.operations, batch);
2650
2643
  }
@@ -4996,9 +4989,6 @@ export class SyncClient {
4996
4989
  }
4997
4990
  }
4998
4991
  /** Re-apply every pending outbox commit on top of server state (§7.1). */
4999
- #discardAcknowledgedRows() {
5000
- this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL`);
5001
- }
5002
4992
  #dropRetainedRows(batch, matches) {
5003
4993
  const scope = [];
5004
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.76.0",
3
+ "version": "0.77.1",
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.76.0"
124
+ "@syncular/core": "0.77.1"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.76.0",
128
+ "@syncular/server": "0.77.1",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
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,
@@ -1385,8 +1384,9 @@ export class SyncClient {
1385
1384
 
1386
1385
  /**
1387
1386
  * §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
1388
- * and leaseState. Drops/recreates every synced table from the new schema,
1389
- * 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
1390
1390
  * schema-floor stop state, rewrites the marker, and raises `upgrading`.
1391
1391
  * The bump is idempotent by the marker (rewritten last).
1392
1392
  */
@@ -1402,6 +1402,7 @@ export class SyncClient {
1402
1402
  // existing marker, with no cross-file transaction.
1403
1403
  this.#sweepPreviousVersionContainer();
1404
1404
  this.#capturePreviousVersion(previousVersion);
1405
+ let changed: string[] = [];
1405
1406
  this.#applyBatch((batch) => {
1406
1407
  this.#db.transaction(() => {
1407
1408
  if (this.#previousVersion !== undefined) {
@@ -1416,10 +1417,7 @@ export class SyncClient {
1416
1417
  ),
1417
1418
  );
1418
1419
  }
1419
- pruneUnknownUnits(this.#db, this.#schema, true);
1420
- this.#discardAcknowledgedRows();
1421
- dropAndRecreateSyncedTables(this.#db, this.#schema);
1422
- resetUnits(this.#db);
1420
+ changed = resetLocalReplica(this.#db, this.#schema, true);
1423
1421
  this.#replayOutbox();
1424
1422
  setMeta(
1425
1423
  this.#db,
@@ -1429,8 +1427,8 @@ export class SyncClient {
1429
1427
  setLocalSchemaDescriptor(this.#db, this.#schema);
1430
1428
  saveUnitScopeSchema(this.#db, this.#schema);
1431
1429
  });
1432
- // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
1433
- 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);
1434
1432
  });
1435
1433
  // The stop state is over: this client now ships a servable schema.
1436
1434
  // The reset transaction already replayed pending intent before committing
@@ -1526,9 +1524,7 @@ export class SyncClient {
1526
1524
  this.#applyBatch(
1527
1525
  (batch) => {
1528
1526
  this.#db.transaction(() => {
1529
- this.#discardAcknowledgedRows();
1530
- dropAndRecreateSyncedTables(this.#db, this.#schema);
1531
- resetUnits(this.#db);
1527
+ resetLocalReplica(this.#db, this.#schema);
1532
1528
  setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
1533
1529
  // §7.1/§7.4.4: recover codec-invalid persisted values in this reset
1534
1530
  // transaction before they replay, so the reset boundary never fails on
@@ -1538,8 +1534,7 @@ export class SyncClient {
1538
1534
  this.#applyOperationsLocally(commit.operations, batch);
1539
1535
  }
1540
1536
  });
1541
- for (const table of this.#schema.tables.values())
1542
- batch.table(table.name);
1537
+ for (const table of this.#schema.tables.keys()) batch.table(table);
1543
1538
  },
1544
1539
  undefined,
1545
1540
  (error) => {
@@ -3940,12 +3935,8 @@ export class SyncClient {
3940
3935
  this.#upgrading = true;
3941
3936
  this.#needsPull = true;
3942
3937
  batch.status();
3943
- this.#discardAcknowledgedRows();
3944
- dropAndRecreateSyncedTables(this.#db, this.#schema);
3945
- resetUnits(this.#db);
3946
- for (const table of this.#schema.tables.values()) {
3947
- batch.table(table.name);
3948
- }
3938
+ for (const table of resetLocalReplica(this.#db, this.#schema))
3939
+ batch.table(table);
3949
3940
  for (const commit of pending) {
3950
3941
  this.#applyOperationsLocally(commit.operations, batch);
3951
3942
  }
@@ -6848,10 +6839,6 @@ export class SyncClient {
6848
6839
  }
6849
6840
 
6850
6841
  /** Re-apply every pending outbox commit on top of server state (§7.1). */
6851
- #discardAcknowledgedRows(): void {
6852
- this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL`);
6853
- }
6854
-
6855
6842
  #dropRetainedRows(
6856
6843
  batch: ChangeAccumulator,
6857
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 {