@syncular/client 0.59.0 → 0.60.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.
Files changed (66) hide show
  1. package/README.md +27 -27
  2. package/dist/apply.d.ts +6 -5
  3. package/dist/apply.js +52 -25
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +4 -4
  6. package/dist/bun-database.js +3 -16
  7. package/dist/client.d.ts +57 -66
  8. package/dist/client.js +701 -796
  9. package/dist/devtools.d.ts +2 -2
  10. package/dist/devtools.js +3 -3
  11. package/dist/diagnostics.d.ts +17 -28
  12. package/dist/diagnostics.js +1 -2
  13. package/dist/errors.d.ts +1 -1
  14. package/dist/errors.js +1 -1
  15. package/dist/failed-overlay.js +4 -1
  16. package/dist/http.js +19 -5
  17. package/dist/invalidation.d.ts +3 -4
  18. package/dist/invalidation.js +9 -22
  19. package/dist/native-bridge.d.ts +7 -16
  20. package/dist/native-bridge.js +16 -41
  21. package/dist/node-database.js +16 -25
  22. package/dist/outbox.js +1 -0
  23. package/dist/progress.d.ts +2 -2
  24. package/dist/query-guard.d.ts +15 -6
  25. package/dist/query-guard.js +38 -6
  26. package/dist/reactive-store.js +2 -2
  27. package/dist/remote.js +9 -9
  28. package/dist/schema.d.ts +3 -2
  29. package/dist/schema.js +28 -12
  30. package/dist/state.d.ts +69 -36
  31. package/dist/state.js +178 -89
  32. package/dist/sync-scheduler.js +2 -2
  33. package/dist/transport.d.ts +2 -2
  34. package/dist/window.d.ts +30 -52
  35. package/dist/window.js +33 -77
  36. package/dist/worker-core.js +6 -6
  37. package/dist/worker-host.d.ts +9 -8
  38. package/dist/worker-host.js +23 -14
  39. package/dist/worker-protocol.d.ts +9 -8
  40. package/package.json +3 -3
  41. package/src/apply.ts +87 -33
  42. package/src/authority.ts +31 -17
  43. package/src/blob.ts +4 -3
  44. package/src/bun-database.ts +9 -14
  45. package/src/client.ts +886 -1037
  46. package/src/devtools.ts +5 -5
  47. package/src/diagnostics.ts +17 -37
  48. package/src/errors.ts +1 -1
  49. package/src/failed-overlay.ts +6 -1
  50. package/src/http.ts +22 -9
  51. package/src/invalidation.ts +9 -29
  52. package/src/native-bridge.ts +22 -58
  53. package/src/node-database.ts +26 -27
  54. package/src/outbox.ts +1 -0
  55. package/src/progress.ts +2 -2
  56. package/src/query-guard.ts +45 -8
  57. package/src/reactive-store.ts +2 -2
  58. package/src/remote.ts +12 -16
  59. package/src/schema.ts +48 -13
  60. package/src/state.ts +246 -125
  61. package/src/sync-scheduler.ts +2 -2
  62. package/src/transport.ts +2 -2
  63. package/src/window.ts +55 -134
  64. package/src/worker-core.ts +6 -6
  65. package/src/worker-host.ts +27 -19
  66. package/src/worker-protocol.ts +8 -8
package/src/remote.ts CHANGED
@@ -3,10 +3,10 @@
3
3
  * through the existing push path without creating a local replica or outbox.
4
4
  */
5
5
  import {
6
- decodeMessage,
6
+ decodeResponse,
7
7
  decodeRemoteOperationResponse,
8
8
  decodeRemoteOperationRealtimeMessage,
9
- encodeMessage,
9
+ encodeRequest,
10
10
  encodeRemoteOperationRequest,
11
11
  encodeRemoteOperationRealtimeMessage,
12
12
  encodeSparseRow,
@@ -18,6 +18,7 @@ import {
18
18
  type PushResultFrame,
19
19
  type RowValue,
20
20
  type RemoteOperationResponse,
21
+ registrationDigest,
21
22
  } from '@syncular/core';
22
23
  import type { MutationInput } from './client';
23
24
  import type { EncryptionConfig } from './encryption';
@@ -280,9 +281,9 @@ export class SyncRemoteClient {
280
281
  'SyncRemoteClient has no sync transport for ordinary commits',
281
282
  );
282
283
  }
283
- const acquisition = decodeMessage(
284
+ const acquisition = decodeResponse(
284
285
  await this.#transport(
285
- encodeMessage({
286
+ encodeRequest({
286
287
  wireVersion: PROTOCOL_WIRE_VERSION,
287
288
  msgKind: 'request',
288
289
  frames: [
@@ -298,16 +299,16 @@ export class SyncRemoteClient {
298
299
  limitSnapshotRows: 0,
299
300
  maxSnapshotPages: 0,
300
301
  accept: 0b0011,
302
+ cursor: -1,
303
+ registrationDigest: registrationDigest([]),
304
+ echoDigest: new Uint8Array(),
301
305
  },
302
306
  ],
303
307
  }),
304
308
  ),
305
309
  );
306
310
  const acquisitionHeader = acquisition.frames[0];
307
- if (
308
- acquisition.msgKind !== 'response' ||
309
- acquisitionHeader?.type !== 'RESP_HEADER'
310
- ) {
311
+ if (acquisitionHeader?.type !== 'RESP_HEADER') {
311
312
  throw new ClientSyncError(
312
313
  'client.invalid_host_response',
313
314
  'remote epoch acquisition returned an invalid response',
@@ -374,7 +375,7 @@ export class SyncRemoteClient {
374
375
  }
375
376
  return {
376
377
  requestId: input.requestId,
377
- bytes: encodeMessage({
378
+ bytes: encodeRequest({
378
379
  wireVersion: PROTOCOL_WIRE_VERSION,
379
380
  msgKind: 'request',
380
381
  frames: [
@@ -387,6 +388,7 @@ export class SyncRemoteClient {
387
388
  {
388
389
  type: 'PUSH_COMMIT',
389
390
  clientCommitId: input.requestId,
391
+ clientSeq: 0,
390
392
  operations,
391
393
  },
392
394
  ],
@@ -403,13 +405,7 @@ export class SyncRemoteClient {
403
405
  'SyncRemoteClient has no sync transport for ordinary commits',
404
406
  );
405
407
  }
406
- const response = decodeMessage(await this.#transport(prepared.bytes));
407
- if (response.msgKind !== 'response') {
408
- throw new ClientSyncError(
409
- 'client.invalid_host_response',
410
- 'remote commit transport returned a non-response SSP2 message',
411
- );
412
- }
408
+ const response = decodeResponse(await this.#transport(prepared.bytes));
413
409
  const error = response.frames.find((frame) => frame.type === 'ERROR');
414
410
  if (error?.type === 'ERROR') {
415
411
  throw new ClientSyncError(error.code, error.message, error.retryable);
package/src/schema.ts CHANGED
@@ -3,7 +3,7 @@ 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 { SUBSCRIPTIONS_TABLE, META_TABLE } from './state';
6
+ import { META_TABLE, resetUnits, UNITS_TABLE } from './state';
7
7
  import { ensureFailedOverlaySchema } from './failed-overlay';
8
8
  /**
9
9
  * Client schema IR (SPEC.md §2.4, §3.1) — the same shape the server
@@ -13,7 +13,7 @@ import { ensureFailedOverlaySchema } from './failed-overlay';
13
13
  */
14
14
  import type { RowColumn, RowValue } from '@syncular/core';
15
15
  import type { ClientDatabase, SqlRow, SqlValue } from './database';
16
- import { invalidRequest } from './errors';
16
+ import { ClientSyncError, invalidRequest } from './errors';
17
17
  import { snakeToCamel } from './naming';
18
18
 
19
19
  /** `'prefix:{variable}'` shorthand (column name = variable) or explicit. */
@@ -592,10 +592,20 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
592
592
  db.exec(
593
593
  `INSERT OR IGNORE INTO ${META_TABLE}(key,value)VALUES('localRevision','0')`,
594
594
  );
595
+ const outboxExisted =
596
+ db.query(
597
+ `SELECT 1 FROM sqlite_master WHERE type='table' AND name='${OUTBOX_TABLE}'`,
598
+ ).length > 0;
595
599
  createTable(
596
600
  OUTBOX_TABLE,
597
601
  'seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,created_at_ms INTEGER NOT NULL,operations TEXT NOT NULL',
598
602
  );
603
+ // §7.1: `outboxId` names the outbox sequence. A new outbox table starts
604
+ // a new sequence, so it replaces the id in the same transaction.
605
+ db.exec(
606
+ `INSERT OR ${outboxExisted ? 'IGNORE' : 'REPLACE'} INTO ${META_TABLE}(key,value)VALUES('outboxId',?)`,
607
+ [crypto.randomUUID()],
608
+ );
599
609
  createTable(
600
610
  OUTBOX_IMAGES,
601
611
  'client_commit_id TEXT NOT NULL,op_index INTEGER NOT NULL,existed INTEGER NOT NULL CHECK(existed IN (0,1)),sync_version INTEGER,values_json TEXT,PRIMARY KEY(client_commit_id,op_index)',
@@ -627,22 +637,47 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
627
637
  `CREATE INDEX IF NOT EXISTS ${OUTCOMES_TABLE}_resolution_seq ON ${OUTCOMES_TABLE}(resolution,seq)`,
628
638
  );
629
639
  createTable(
630
- SUBSCRIPTIONS_TABLE,
631
- "id TEXT PRIMARY KEY,tbl TEXT NOT NULL,requested_scopes TEXT NOT NULL,params TEXT,cursor INTEGER NOT NULL DEFAULT -1,bootstrap_state TEXT,effective_scopes TEXT,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT",
640
+ UNITS_TABLE,
641
+ "id TEXT PRIMARY KEY,scopes TEXT NOT NULL,explicit INTEGER NOT NULL DEFAULT 0,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT,cursor INTEGER DEFAULT -1,bootstrap_state TEXT,seeded TEXT NOT NULL DEFAULT '[]',echo TEXT",
632
642
  );
633
- // §4.8 window registry: which units (scope values) of a window base are
634
- // live locally — the completeness oracle (I3) and the shrink driver
635
- // (a unit's omission from the next pull unregisters it, §4.1).
643
+ // §4.8 window registry: base + value → the unit it holds, the
644
+ // completeness oracle and one of a unit's references (§4.1).
636
645
  createTable(
637
646
  WINDOWS_TABLE,
638
647
  'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)',
639
648
  );
640
- // §4.8 E1: units that left the window but still had outbox-pinned rows.
641
- // Retried when the outbox drains; cancelled if the unit re-enters.
649
+ // §4.8 E1: per-table scopes of units that left with pinned or unevicted
650
+ // rows. Retried when the outbox drains; cancelled when the unit re-enters.
642
651
  createTable(
643
652
  PENDING_EVICTIONS,
644
- 'sub_id TEXT PRIMARY KEY,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL',
653
+ 'unit_id TEXT NOT NULL,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL,PRIMARY KEY(unit_id,tbl)',
645
654
  );
655
+ // §9: a replica written under wire version 3 keeps its outbox, journal,
656
+ // rows and pending evictions and registers its units fresh. Its
657
+ // subscriptions, cursors, echoes, resume tokens and window entries go.
658
+ const legacyEvictions = '_syncular_window_pending_evict';
659
+ if (
660
+ db.query(
661
+ `SELECT 1 FROM sqlite_master WHERE type='table' AND name='${legacyEvictions}'`,
662
+ ).length > 0
663
+ ) {
664
+ if (
665
+ db.query(
666
+ `SELECT 1 FROM ${legacyEvictions} WHERE NOT json_valid(effective_scopes) OR json_type(effective_scopes)<>'object' OR EXISTS(SELECT 1 FROM json_each(effective_scopes) WHERE json_type(value)<>'array' OR EXISTS(SELECT 1 FROM json_each(value) v WHERE v.type<>'text'))`,
667
+ ).length > 0
668
+ )
669
+ throw new ClientSyncError(
670
+ 'sync.local_corrupt',
671
+ 'a version 3 pending eviction cannot be upgraded',
672
+ );
673
+ db.exec(
674
+ `INSERT OR REPLACE INTO ${PENDING_EVICTIONS} SELECT sub_id,tbl,effective_scopes FROM ${legacyEvictions}`,
675
+ );
676
+ db.exec(`DROP TABLE ${legacyEvictions}`);
677
+ db.exec('DROP TABLE IF EXISTS _syncular_subscriptions');
678
+ db.exec(`DELETE FROM ${WINDOWS_TABLE}`);
679
+ resetUnits(db);
680
+ }
646
681
  });
647
682
  }
648
683
 
@@ -663,10 +698,10 @@ const RESERVED_TABLE_PREFIX = '_syncular_';
663
698
  * generated schema created — discovered from `sqlite_master`, since a
664
699
  * bump may add/remove tables) and recreate the synced tables from the
665
700
  * NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
666
- * subscriptions, blob cache) are preserved. RFC 0005's container is not
701
+ * units, blob cache) are preserved. RFC 0005's container is not
667
702
  * reachable from here: it lives in its own database file, so this reset cannot
668
703
  * see or destroy it. Caller owns the surrounding transaction and the
669
- * subscription-state reset (state.ts).
704
+ * unit-state reset (state.ts).
670
705
  */
671
706
  export function dropAndRecreateSyncedTables(
672
707
  db: ClientDatabase,
@@ -821,7 +856,7 @@ export type JsonRowValue =
821
856
  | null
822
857
  | { readonly $bytes: string };
823
858
 
824
- function bytesToHex(bytes: Uint8Array): string {
859
+ export function bytesToHex(bytes: Uint8Array): string {
825
860
  let out = '';
826
861
  for (const byte of bytes) out += byte.toString(16).padStart(2, '0');
827
862
  return out;
package/src/state.ts CHANGED
@@ -1,119 +1,238 @@
1
1
  export const META_TABLE = '_syncular_meta';
2
2
  import { PENDING_EVICTIONS } from './window';
3
3
  import { WINDOWS_TABLE } from './window';
4
- export const SUBSCRIPTIONS_TABLE = '_syncular_subscriptions';
4
+ export const UNITS_TABLE = '_syncular_units';
5
5
  /**
6
- * Durable client sync state: per-subscription cursor, bootstrap resume
7
- * token (round-tripped opaquely, §4.7), and the last-echoed effective
8
- * scopes the §3.3 purge contract is keyed on — persisted per subscription
9
- * exactly for that purpose.
6
+ * Durable unit state (SPEC.md §4.1): per unit its scope map, status, live
7
+ * membership, catch-up cursor and opaque resume token (§4.7), the tables its
8
+ * current bootstrap seeded (§5.6) and the last echo (§4.4) the §3.3 purge
9
+ * contract is keyed on. The replica cursor, the echo digest and the
10
+ * registration digest the server holds live in meta.
10
11
  */
11
- import type { ScopeMap } from '@syncular/core';
12
+ import type { FencedRecord, ScopeMap, UnitScopes } from '@syncular/core';
12
13
  import { ClientSyncError } from './errors';
13
- import type { CompiledClientSchema } from './schema';
14
+ import type { CompiledClientSchema, CompiledClientTable } from './schema';
14
15
  import type { ClientDatabase } from './database';
15
16
  import type { LocalRevision } from './invalidation';
16
17
 
17
18
  export const LOCAL_REVISION_KEY = 'localRevision';
19
+ /** §4.5 replica cursor; absent means `-1`. */
20
+ export const REPLICA_CURSOR_KEY = 'replicaCursor';
21
+ /** Hex of the last pull `LIVE_END.echoDigest` (§4.2); absent means empty. */
22
+ export const ECHO_DIGEST_KEY = 'echoDigest';
23
+ /** Hex of the registration digest of the list the server stores (§4.1). */
24
+ export const REGISTERED_DIGEST_KEY = 'registrationDigest';
18
25
  const MAX_U64 = 18_446_744_073_709_551_615n;
19
26
 
20
- export type SubscriptionStatus = 'active' | 'revoked' | 'failed';
27
+ export type UnitStatus = 'active' | 'revoked' | 'failed';
21
28
 
22
- export interface SubscriptionRecord {
29
+ export interface UnitRecord {
30
+ /** §4.1: derived from the scope map. */
23
31
  readonly id: string;
24
- readonly table: string;
25
- /** Requested scopes (§3.2), chosen by the app. */
26
- readonly scopes: ScopeMap;
27
- /** Host-opaque JSON params, preserved verbatim. */
28
- readonly params?: string;
29
- /** Last fully-applied commitSeq; -1 = never synced (§4.3). */
30
- readonly cursor: number;
32
+ readonly scopes: UnitScopes;
33
+ /** An explicit `subscribe` holds the unit; window bases hold it through
34
+ * the window registry (§4.1 references). */
35
+ readonly explicit: boolean;
36
+ readonly status: UnitStatus;
37
+ /** §10 code when not active, or `sync.cursor_expired` after a reset. */
38
+ readonly reasonCode?: string | undefined;
39
+ /** Absent while the unit is live (§4.5); otherwise `-1`, the pin, or the
40
+ * post-bootstrap cursor `P`. */
41
+ readonly cursor?: number | undefined;
31
42
  /** Opaque resume token from `SUB_END` (§4.7); present mid-bootstrap. */
32
- readonly bootstrapState?: string;
33
- /** Last effective scopes echoed while active (§3.3 purge key). */
34
- readonly effectiveScopes?: ScopeMap;
35
- readonly status: SubscriptionStatus;
36
- /** §10 code when not active (`sync.scope_revoked`, …). */
37
- readonly reasonCode?: string;
43
+ readonly bootstrapState?: string | undefined;
44
+ /** Tables that received a segment in the current bootstrap (§5.6). */
45
+ readonly seeded: readonly string[];
46
+ /** The echo persisted at the last `SUB_END` (§4.4). */
47
+ readonly echo?: readonly FencedRecord[] | undefined;
38
48
  }
39
49
 
40
- function rowToRecord(row: Record<string, unknown>): SubscriptionRecord {
41
- return {
42
- id: row.id as string,
43
- table: row.tbl as string,
44
- scopes: JSON.parse(row.requested_scopes as string) as ScopeMap,
45
- ...(row.params !== null ? { params: row.params as string } : {}),
46
- cursor: row.cursor as number,
47
- ...(row.bootstrap_state !== null
48
- ? { bootstrapState: row.bootstrap_state as string }
49
- : {}),
50
- ...(row.effective_scopes !== null
51
- ? {
52
- effectiveScopes: JSON.parse(
53
- row.effective_scopes as string,
54
- ) as ScopeMap,
55
- }
56
- : {}),
57
- status: row.status as SubscriptionStatus,
58
- ...(row.reason_code !== null
59
- ? { reasonCode: row.reason_code as string }
60
- : {}),
50
+ /** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
51
+ export function bootstrapping(unit: UnitRecord): boolean {
52
+ return (
53
+ unit.cursor !== undefined &&
54
+ (unit.cursor < 0 || unit.bootstrapState !== undefined)
55
+ );
56
+ }
57
+
58
+ /** §3.3 row ownership: active, live or post-bootstrap, with an echo. */
59
+ export function owning(unit: UnitRecord): boolean {
60
+ return (
61
+ unit.status === 'active' && unit.echo !== undefined && !bootstrapping(unit)
62
+ );
63
+ }
64
+
65
+ /** §4.1: the unit covers every table declaring all of its variables. */
66
+ export function covers(
67
+ table: CompiledClientTable,
68
+ scopes: UnitScopes,
69
+ ): boolean {
70
+ return Object.keys(scopes).every((variable) =>
71
+ table.scopeColumnByVariable.has(variable),
72
+ );
73
+ }
74
+
75
+ /**
76
+ * §4.4: the effective scopes of the (unit, table) pair under `echo`: the
77
+ * scope map as one-element lists plus the fenced lists. Undefined when the
78
+ * fence revoked the pair.
79
+ */
80
+ export function pairScopes(
81
+ scopes: UnitScopes,
82
+ table: string,
83
+ echo: readonly FencedRecord[] | undefined,
84
+ ): ScopeMap | undefined {
85
+ const fenced = echo?.find((record) => record.table === table);
86
+ if (fenced?.status === 'revoked') return undefined;
87
+ const effective: ScopeMap = { ...fenced?.scopes };
88
+ for (const [variable, value] of Object.entries(scopes))
89
+ effective[variable] = [value];
90
+ return effective;
91
+ }
92
+
93
+ /** §3.3 row ownership: the pair scopes of every owner of `table` but one.
94
+ * A bootstrapping unit owns the tables its current bootstrap seeded. */
95
+ export function unitOwners(
96
+ units: readonly UnitRecord[],
97
+ table: CompiledClientTable,
98
+ exceptId: string,
99
+ ): ScopeMap[] {
100
+ return units.flatMap((unit) => {
101
+ const scopes =
102
+ unit.id !== exceptId &&
103
+ (owning(unit) ||
104
+ (unit.status === 'active' &&
105
+ unit.echo !== undefined &&
106
+ unit.seeded.includes(table.name))) &&
107
+ covers(table, unit.scopes)
108
+ ? pairScopes(unit.scopes, table.name, unit.echo)
109
+ : undefined;
110
+ return scopes === undefined ? [] : [scopes];
111
+ });
112
+ }
113
+
114
+ /** A unit row; every persisted field must have its stored type and shape,
115
+ * otherwise the row is `sync.local_corrupt` (§7.5). */
116
+ function rowToRecord(row: Record<string, unknown>): UnitRecord {
117
+ const corrupt = () =>
118
+ new ClientSyncError(
119
+ 'sync.local_corrupt',
120
+ 'persisted unit state is invalid',
121
+ );
122
+ const json = (raw: unknown): unknown => {
123
+ if (typeof raw !== 'string') throw corrupt();
124
+ try {
125
+ return JSON.parse(raw);
126
+ } catch {
127
+ throw corrupt();
128
+ }
129
+ };
130
+ const isMap = (value: unknown): value is Record<string, unknown> =>
131
+ typeof value === 'object' && value !== null && !Array.isArray(value);
132
+ const isStrings = (value: unknown): value is string[] =>
133
+ Array.isArray(value) && value.every((item) => typeof item === 'string');
134
+ const optionalText = (value: unknown) => {
135
+ if (value !== null && typeof value !== 'string') throw corrupt();
136
+ return value ?? undefined;
61
137
  };
138
+ const scopes = json(row.scopes);
139
+ const seeded = json(row.seeded);
140
+ const echo = row.echo === null ? undefined : json(row.echo);
141
+ const { id, status, cursor } = row;
142
+ if (
143
+ typeof id !== 'string' ||
144
+ !isMap(scopes) ||
145
+ !Object.values(scopes).every((value) => typeof value === 'string') ||
146
+ (status !== 'active' && status !== 'revoked' && status !== 'failed') ||
147
+ (cursor !== null && !Number.isInteger(cursor)) ||
148
+ !isStrings(seeded) ||
149
+ (echo !== undefined &&
150
+ !(
151
+ Array.isArray(echo) &&
152
+ echo.every(
153
+ (record) =>
154
+ isMap(record) &&
155
+ typeof record.table === 'string' &&
156
+ (record.status === 'active' || record.status === 'revoked') &&
157
+ isMap(record.scopes) &&
158
+ Object.values(record.scopes).every(isStrings),
159
+ )
160
+ ))
161
+ )
162
+ throw corrupt();
163
+ const record: { -readonly [K in keyof UnitRecord]: UnitRecord[K] } = {
164
+ id,
165
+ scopes: scopes as UnitScopes,
166
+ explicit: row.explicit === 1,
167
+ status,
168
+ seeded,
169
+ };
170
+ const reasonCode = optionalText(row.reason_code);
171
+ if (reasonCode !== undefined) record.reasonCode = reasonCode;
172
+ if (typeof cursor === 'number') record.cursor = cursor;
173
+ const bootstrapState = optionalText(row.bootstrap_state);
174
+ if (bootstrapState !== undefined) record.bootstrapState = bootstrapState;
175
+ if (echo !== undefined) record.echo = echo as FencedRecord[];
176
+ return record;
62
177
  }
63
178
 
64
- export function loadSubscriptions(db: ClientDatabase): SubscriptionRecord[] {
179
+ /** Every unit in registration order (§4.1). */
180
+ export function loadUnits(db: ClientDatabase): UnitRecord[] {
65
181
  return db
66
- .query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} ORDER BY rowid ASC`)
182
+ .query(`SELECT * FROM ${UNITS_TABLE} ORDER BY rowid ASC`)
67
183
  .map(rowToRecord);
68
184
  }
69
185
 
70
- export function getSubscription(
186
+ export function getUnit(
71
187
  db: ClientDatabase,
72
188
  id: string,
73
- ): SubscriptionRecord | undefined {
74
- const row = db.query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [
75
- id,
76
- ])[0];
189
+ ): UnitRecord | undefined {
190
+ const row = db.query(`SELECT * FROM ${UNITS_TABLE} WHERE id=?`, [id])[0];
77
191
  return row === undefined ? undefined : rowToRecord(row);
78
192
  }
79
193
 
80
- export function saveSubscription(
81
- db: ClientDatabase,
82
- record: SubscriptionRecord,
83
- ): void {
194
+ /** Insert or update in place: an update keeps the registration order. */
195
+ export function saveUnit(db: ClientDatabase, record: UnitRecord): void {
84
196
  db.exec(
85
- `INSERT OR REPLACE INTO ${SUBSCRIPTIONS_TABLE}(id,tbl,requested_scopes,params,cursor,bootstrap_state,effective_scopes,status,reason_code)VALUES(?,?,?,?,?,?,?,?,?)`,
197
+ `INSERT INTO ${UNITS_TABLE}(id,scopes,explicit,status,reason_code,cursor,bootstrap_state,seeded,echo)VALUES(?,?,?,?,?,?,?,?,?)ON CONFLICT(id)DO UPDATE SET explicit=excluded.explicit,status=excluded.status,reason_code=excluded.reason_code,cursor=excluded.cursor,bootstrap_state=excluded.bootstrap_state,seeded=excluded.seeded,echo=excluded.echo`,
86
198
  [
87
199
  record.id,
88
- record.table,
89
200
  JSON.stringify(record.scopes),
90
- record.params ?? null,
91
- record.cursor,
92
- record.bootstrapState ?? null,
93
- record.effectiveScopes === undefined
94
- ? null
95
- : JSON.stringify(record.effectiveScopes),
201
+ record.explicit ? 1 : 0,
96
202
  record.status,
97
203
  record.reasonCode ?? null,
204
+ record.cursor ?? null,
205
+ record.bootstrapState ?? null,
206
+ JSON.stringify(record.seeded),
207
+ record.echo === undefined ? null : JSON.stringify(record.echo),
98
208
  ],
99
209
  );
100
210
  }
101
211
 
102
- export function deleteSubscription(db: ClientDatabase, id: string): void {
103
- db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
212
+ export function deleteUnit(db: ClientDatabase, id: string): void {
213
+ db.exec(`DELETE FROM ${UNITS_TABLE} WHERE id=?`, [id]);
104
214
  }
105
215
 
106
216
  /**
107
- * §7.4.3 reset: keep compatible subscription REGISTRATIONS (id, table,
108
- * requested scopes, params — the app's declared intent) but discard all
109
- * synced state (cursor → -1, no resume token, no effective-scope map,
110
- * status → active), so the next round fresh-bootstraps exactly the
111
- * subscriptions the app still wants. Caller owns the transaction.
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.
112
221
  */
113
- export function resetSubscriptionsForBump(db: ClientDatabase): void {
222
+ export function resetUnits(db: ClientDatabase): void {
114
223
  db.exec(
115
- `UPDATE ${SUBSCRIPTIONS_TABLE} SET cursor=-1,bootstrap_state=NULL,effective_scopes=NULL,status='active',reason_code=NULL`,
224
+ `UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL`,
116
225
  );
226
+ db.exec(`DELETE FROM ${META_TABLE} WHERE key IN(?,?,?)`, [
227
+ REPLICA_CURSOR_KEY,
228
+ ECHO_DIGEST_KEY,
229
+ REGISTERED_DIGEST_KEY,
230
+ ]);
231
+ }
232
+
233
+ /** §4.5: the replica cursor, `-1` while no unit is live. */
234
+ export function replicaCursor(db: ClientDatabase): number {
235
+ return Number(getMeta(db, REPLICA_CURSOR_KEY) ?? -1);
117
236
  }
118
237
 
119
238
  type ScopeDeclarations = Record<
@@ -121,8 +240,8 @@ type ScopeDeclarations = Record<
121
240
  Record<string, readonly [string, string]>
122
241
  >;
123
242
 
124
- /** Persist declarations separately from the previous-version row descriptor. */
125
- export function saveSubscriptionScopeSchema(
243
+ /** §7.4.3 declaration evidence, persisted beside the schema marker. */
244
+ export function saveUnitScopeSchema(
126
245
  db: ClientDatabase,
127
246
  schema: CompiledClientSchema,
128
247
  ): void {
@@ -138,76 +257,78 @@ export function saveSubscriptionScopeSchema(
138
257
  setMeta(db, 'subscriptionScopeSchema', JSON.stringify(declarations));
139
258
  }
140
259
 
141
- /** Drop incompatible registrations and their windows; never translate scopes. */
142
- export function pruneUnknownSubscriptions(
260
+ /**
261
+ * Drop units that cover no table of the running schema, with their window
262
+ * registry rows and pending evictions; never translate scopes. At a bump
263
+ * (§7.4.3) a unit also needs every variable unchanged in prefix and column on
264
+ * every table it covered before.
265
+ */
266
+ export function pruneUnknownUnits(
143
267
  db: ClientDatabase,
144
- subscriptions: readonly SubscriptionRecord[],
145
268
  schema: CompiledClientSchema,
146
269
  bump = false,
147
- ): SubscriptionRecord[] {
270
+ ): void {
148
271
  const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
149
272
  const previous =
150
273
  stored === undefined
151
274
  ? undefined
152
275
  : (JSON.parse(stored) as ScopeDeclarations);
153
- const compatible = (
154
- record: Pick<SubscriptionRecord, 'table' | 'scopes'>,
155
- ): boolean => {
156
- const table = schema.tables.get(record.table);
157
- if (table === undefined) return false;
158
- const variables = Object.keys(record.scopes);
159
- if (
160
- !variables.every((variable) => table.scopeColumnByVariable.has(variable))
161
- )
276
+ // A table keeps the variables' meaning when each has the same prefix and
277
+ // column as before. An old binary stored no declaration evidence; matching
278
+ // names cannot prove unchanged meaning, so the app registers again.
279
+ const unchanged = (name: string, variables: readonly string[]): boolean => {
280
+ const old = previous?.[name];
281
+ const table = schema.tables.get(name);
282
+ return (
283
+ old !== undefined &&
284
+ table !== undefined &&
285
+ variables.every(
286
+ (variable) =>
287
+ old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
288
+ old[variable]?.[1] === table.scopeColumnByVariable.get(variable),
289
+ )
290
+ );
291
+ };
292
+ const compatible = (scopes: UnitScopes): boolean => {
293
+ const variables = Object.keys(scopes);
294
+ if (![...schema.tables.values()].some((table) => covers(table, scopes)))
162
295
  return false;
163
296
  if (!bump) return true;
164
- // An old binary stored no declaration evidence. Re-registration is required
165
- // at a bump: matching names cannot prove unchanged column/prefix meaning.
166
- const old = previous?.[record.table];
167
- if (old === undefined) return false;
168
- const compared =
169
- variables.length === 0
170
- ? [
171
- ...new Set([
172
- ...Object.keys(old),
173
- ...table.scopeColumnByVariable.keys(),
174
- ]),
175
- ]
176
- : variables;
177
- return compared.every(
178
- (variable) =>
179
- old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
180
- old[variable]?.[1] === table.scopeColumnByVariable.get(variable),
297
+ if (previous === undefined) return false;
298
+ return Object.entries(previous).every(
299
+ ([name, old]) =>
300
+ !variables.every((variable) => old[variable] !== undefined) ||
301
+ unchanged(name, variables),
181
302
  );
182
303
  };
183
- const retained = subscriptions.filter(compatible);
184
- const staleIds = new Set(
185
- subscriptions
186
- .filter((record) => !compatible(record))
187
- .map((record) => record.id),
304
+ const stale = new Set(
305
+ loadUnits(db)
306
+ .filter((unit) => !compatible(unit.scopes))
307
+ .map((unit) => unit.id),
188
308
  );
189
- // Shrinking a pinned window already removed its registration. Its deferred
190
- // eviction still carries the old scope declaration and needs the same fence.
309
+ // A shrunk window's deferred eviction outlives its unit row and keeps its
310
+ // per-table scopes. A table the schema no longer has cannot be evicted, and
311
+ // at a bump a table whose scope declarations changed must not be evicted by
312
+ // the outdated rule.
191
313
  for (const row of db.query(
192
- `SELECT sub_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`,
314
+ `SELECT unit_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`,
193
315
  )) {
316
+ const table = String(row.tbl);
194
317
  if (
195
- !compatible({
196
- table: String(row.tbl),
197
- scopes: JSON.parse(String(row.effective_scopes)) as ScopeMap,
198
- })
318
+ !schema.tables.has(table) ||
319
+ (bump &&
320
+ !unchanged(
321
+ table,
322
+ Object.keys(JSON.parse(String(row.effective_scopes)) as ScopeMap),
323
+ ))
199
324
  )
200
- staleIds.add(String(row.sub_id));
325
+ stale.add(String(row.unit_id));
326
+ }
327
+ for (const id of stale) {
328
+ db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
329
+ db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?`, [id]);
330
+ deleteUnit(db, id);
201
331
  }
202
- if (staleIds.size === 0) return retained;
203
- db.transaction(() => {
204
- for (const id of staleIds) {
205
- db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
206
- db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id=?`, [id]);
207
- db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
208
- }
209
- });
210
- return retained;
211
332
  }
212
333
 
213
334
  export function getMeta(db: ClientDatabase, key: string): string | undefined {