@syncular/server 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 (54) hide show
  1. package/README.md +20 -16
  2. package/dist/admin.d.ts +32 -20
  3. package/dist/admin.js +42 -40
  4. package/dist/context.d.ts +6 -8
  5. package/dist/context.js +1 -3
  6. package/dist/d1-storage.js +42 -24
  7. package/dist/errors.js +8 -0
  8. package/dist/events.d.ts +35 -17
  9. package/dist/frame-bytes.js +24 -6
  10. package/dist/handler.js +486 -223
  11. package/dist/local-authority.js +7 -9
  12. package/dist/operations.d.ts +5 -2
  13. package/dist/operations.js +20 -29
  14. package/dist/postgres-storage.d.ts +24 -19
  15. package/dist/postgres-storage.js +249 -168
  16. package/dist/pull.d.ts +68 -53
  17. package/dist/pull.js +258 -287
  18. package/dist/push.d.ts +12 -3
  19. package/dist/push.js +95 -32
  20. package/dist/realtime.d.ts +17 -11
  21. package/dist/realtime.js +65 -90
  22. package/dist/relational-rows.d.ts +0 -57
  23. package/dist/relational-rows.js +4 -100
  24. package/dist/seed.js +10 -15
  25. package/dist/segment-download.d.ts +4 -1
  26. package/dist/segment-download.js +4 -2
  27. package/dist/sqlite-dialect.d.ts +36 -59
  28. package/dist/sqlite-dialect.js +255 -159
  29. package/dist/sqlite-storage.js +24 -20
  30. package/dist/storage-query.d.ts +30 -1
  31. package/dist/storage-query.js +68 -0
  32. package/dist/storage.d.ts +156 -54
  33. package/dist/storage.js +15 -0
  34. package/package.json +2 -2
  35. package/src/admin.ts +87 -59
  36. package/src/context.ts +7 -11
  37. package/src/d1-storage.ts +49 -33
  38. package/src/errors.ts +8 -0
  39. package/src/events.ts +36 -17
  40. package/src/frame-bytes.ts +26 -6
  41. package/src/handler.ts +628 -286
  42. package/src/local-authority.ts +10 -11
  43. package/src/operations.ts +44 -42
  44. package/src/postgres-storage.ts +336 -226
  45. package/src/pull.ts +394 -414
  46. package/src/push.ts +116 -21
  47. package/src/realtime.ts +85 -129
  48. package/src/relational-rows.ts +4 -107
  49. package/src/seed.ts +13 -19
  50. package/src/segment-download.ts +8 -3
  51. package/src/sqlite-dialect.ts +363 -204
  52. package/src/sqlite-storage.ts +45 -25
  53. package/src/storage-query.ts +102 -0
  54. package/src/storage.ts +185 -58
package/dist/push.d.ts CHANGED
@@ -21,7 +21,7 @@ import { type PushCommitFrame, type PushOperation, type PushResultFrame, type Ro
21
21
  import type { SyncRequestContext } from './context.js';
22
22
  import type { CompiledSchema, CompiledTable } from './schema.js';
23
23
  import type { ResolvedScopes } from './scopes.js';
24
- import type { StorageTransaction, StoredCommit } from './storage.js';
24
+ import type { OutboxSequence, OutboxSettlement, StorageTransaction, StoredCommit } from './storage.js';
25
25
  /**
26
26
  * Extract the blobIds a decoded row references through its `blob_ref`
27
27
  * columns (§5.9.4), skipping NULLs. Malformed BlobRefs already failed at
@@ -48,6 +48,15 @@ export interface ProcessedPushCommit {
48
48
  readonly replayed: boolean;
49
49
  readonly recordedAtMs?: number;
50
50
  readonly cacheIdentity?: string;
51
+ /** The outbox watermark `W` the commit's settlement read (§6.3.2). */
52
+ readonly watermark?: number;
53
+ }
54
+ /** A pushed commit's outbox position and the request's watermark (§6.3.2). */
55
+ export interface PushOutbox extends OutboxSequence {
56
+ /** `W` after the request's first commit. */
57
+ readonly watermark: number;
58
+ /** Present with the request's first commit: steps 1 and 2 run with it. */
59
+ readonly settlement?: OutboxSettlement;
51
60
  }
52
61
  export interface AppliedCommitEvent {
53
62
  readonly commit: StoredCommit;
@@ -62,7 +71,7 @@ export declare function processPushCommit(ctx: SyncRequestContext, schema: Compi
62
71
  * rejected replays as `status: rejected`; this companion result preserves the
63
72
  * cache provenance needed by structured events and server helpers.
64
73
  */
65
- export declare function processPushCommitWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame, wireSchema?: CompiledSchema): Promise<ProcessedPushCommit>;
74
+ export declare function processPushCommitWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame, wireSchema?: CompiledSchema, outbox?: PushOutbox): Promise<ProcessedPushCommit>;
66
75
  /**
67
76
  * Shared serialized apply path for SSP2 commits and authoritative commands.
68
77
  * The builder runs after the partition lock and idempotency re-check, so its
@@ -71,4 +80,4 @@ export declare function processPushCommitWithTrace(ctx: SyncRequestContext, sche
71
80
  export declare function processPushOperationsWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, clientCommitId: string, buildOperations: (tx: StorageTransaction) => Promise<readonly ApplyOperation[]>, wireSchema?: CompiledSchema, prefetchTargets?: readonly {
72
81
  readonly table: string;
73
82
  readonly rowIds: readonly string[];
74
- }[]): Promise<ProcessedPushCommit>;
83
+ }[], outbox?: PushOutbox): Promise<ProcessedPushCommit>;
package/dist/push.js CHANGED
@@ -173,7 +173,9 @@ async function mergeCrdtColumns(table, values, storedValues, present, opIndex, m
173
173
  }
174
174
  return { changed };
175
175
  }
176
- async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, actorId) {
176
+ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, actorId,
177
+ /** §2.2: the partition's delete floor, raised by this commit's deletes. */
178
+ deleteFloor) {
177
179
  const table = schema.tables.get(op.table);
178
180
  const wireTable = wireSchema.tables.get(op.table);
179
181
  if (table === undefined || wireTable === undefined) {
@@ -189,8 +191,9 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
189
191
  const stored = await tx.getRow(op.table, op.rowId);
190
192
  if (op.op === 'rescope') {
191
193
  // §2.2 explicit scope move. One stored row changes its scope values;
192
- // apply rewrites it in place, keeps `server_version`, and emits the
193
- // delete under the old scopes plus the upsert under the new ones.
194
+ // apply rewrites it in place, advances `server_version` by 1, and emits
195
+ // the delete under the old scopes plus the upsert under the new ones,
196
+ // both at the new version.
194
197
  if (stored === undefined) {
195
198
  return errorRecord(opIndex, 'sync.row_missing', 'rescope targets an absent row (§2.2)');
196
199
  }
@@ -252,17 +255,31 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
252
255
  if (blobCheck !== undefined)
253
256
  return blobCheck;
254
257
  const payload = encodeRow(table.columns, values);
258
+ // §2.2: the moved scope columns take the new version as their column
259
+ // version; every other column keeps its own (a row stored before column
260
+ // versions holds every column at its current version).
261
+ const movedVersion = stored.serverVersion + 1;
262
+ const storedVersions = decodeColumnVersions(stored.columnVersions);
263
+ const movedVersions = new Map();
264
+ for (let i = 0; i < table.columns.length; i++) {
265
+ const version = scopeIndexes.has(i) &&
266
+ !sameValue(values[i] ?? null, storedValues[i] ?? null)
267
+ ? movedVersion
268
+ : (storedVersions.get(i) ??
269
+ (stored.columnVersions === undefined ? stored.serverVersion : 1));
270
+ if (version > 1)
271
+ movedVersions.set(i, version);
272
+ }
273
+ const columnVersions = encodeColumnVersions(movedVersions);
255
274
  // The move clears any tombstone from an earlier incarnation: the row is
256
275
  // live at the end of this commit, so the next move must not hit §5.2.
257
276
  await tx.clearTombstone(op.table, op.rowId);
258
277
  await tx.upsertRow(op.table, {
259
278
  rowId: op.rowId,
260
- serverVersion: stored.serverVersion,
279
+ serverVersion: movedVersion,
261
280
  scopes: extracted.scopes,
262
281
  payload,
263
- ...(stored.columnVersions !== undefined
264
- ? { columnVersions: stored.columnVersions }
265
- : {}),
282
+ ...(columnVersions !== undefined ? { columnVersions } : {}),
266
283
  }, { opIndex });
267
284
  const storedRow = toValidateRow(table.columns, storedValues);
268
285
  return {
@@ -272,13 +289,14 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
272
289
  table: op.table,
273
290
  rowId: op.rowId,
274
291
  op: 'delete',
292
+ rowVersion: movedVersion,
275
293
  scopes: stored.scopes,
276
294
  },
277
295
  {
278
296
  table: op.table,
279
297
  rowId: op.rowId,
280
298
  op: 'upsert',
281
- rowVersion: stored.serverVersion,
299
+ rowVersion: movedVersion,
282
300
  scopes: extracted.scopes,
283
301
  payload,
284
302
  },
@@ -301,7 +319,7 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
301
319
  row: toValidateRow(table.columns, values),
302
320
  stored: storedRow,
303
321
  storedServerVersion: stored.serverVersion,
304
- nextServerVersion: stored.serverVersion,
322
+ nextServerVersion: movedVersion,
305
323
  },
306
324
  ],
307
325
  staged: {
@@ -362,7 +380,9 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
362
380
  table: op.table,
363
381
  rowId: op.rowId,
364
382
  op: 'delete',
365
- deletedVersion: stored.serverVersion,
383
+ // §2.2: a delete advances the version by 1; its tombstone records
384
+ // it and the delete floor rises to it.
385
+ rowVersion: stored.serverVersion + 1,
366
386
  scopes: stored.scopes,
367
387
  },
368
388
  ],
@@ -598,12 +618,12 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
598
618
  const insertReject = await runValidator(validators, table, 'upsert', op.rowId, values, undefined, opIndex, tx, partition, actorId);
599
619
  if (insertReject !== undefined)
600
620
  return insertReject;
601
- // §6.2: an insert recreates over the tombstone and starts above the
602
- // deleted row's version; without a column-versions blob every column sits
603
- // at that version.
621
+ // §2.2, §6.2: every insert starts one above the delete floor, over a
622
+ // tombstone or not; without a column-versions blob every column sits at
623
+ // that version.
604
624
  if (tombstone !== undefined)
605
625
  await tx.clearTombstone(op.table, op.rowId);
606
- const serverVersion = (deleted?.serverVersion ?? 0) + 1;
626
+ const serverVersion = deleteFloor + 1;
607
627
  const newRow = {
608
628
  rowId: op.rowId,
609
629
  serverVersion,
@@ -1021,7 +1041,7 @@ async function enforceReferences(tx, schema, resolved, staged, clientOpCount, ca
1021
1041
  table: child.name,
1022
1042
  rowId: childRow.rowId,
1023
1043
  op: 'delete',
1024
- deletedVersion: childRow.serverVersion,
1044
+ rowVersion: childRow.serverVersion + 1,
1025
1045
  scopes: childRow.scopes,
1026
1046
  });
1027
1047
  operations.push({
@@ -1108,10 +1128,11 @@ function resultFrame(clientCommitId, stored, replay) {
1108
1128
  results: [...stored.results],
1109
1129
  };
1110
1130
  }
1111
- function processedPushCommit(clientCommitId, stored, replayed) {
1131
+ function processedPushCommit(clientCommitId, stored, replayed, watermark) {
1112
1132
  return {
1113
1133
  frame: resultFrame(clientCommitId, stored, replayed),
1114
1134
  replayed,
1135
+ ...(watermark !== undefined ? { watermark } : {}),
1115
1136
  ...(stored.recordedAtMs !== undefined
1116
1137
  ? { recordedAtMs: stored.recordedAtMs }
1117
1138
  : {}),
@@ -1143,6 +1164,23 @@ function idempotencyCacheMissFrame(clientCommitId, error) {
1143
1164
  ],
1144
1165
  };
1145
1166
  }
1167
+ /** §6.3: the unpersisted refusal of a commit below its outbox's watermark. */
1168
+ function commitExpiredFrame(clientCommitId) {
1169
+ return {
1170
+ type: 'PUSH_RESULT',
1171
+ clientCommitId,
1172
+ status: 'rejected',
1173
+ results: [
1174
+ {
1175
+ opIndex: 0,
1176
+ status: 'error',
1177
+ code: 'sync.commit_expired',
1178
+ message: 'the commit lies below its outbox watermark (§6.3.2)',
1179
+ retryable: false,
1180
+ },
1181
+ ],
1182
+ };
1183
+ }
1146
1184
  /**
1147
1185
  * Process one `PUSH_COMMIT` frame: idempotency replay (§2.3), sequential
1148
1186
  * atomic apply (§6.4), realtime notification for applied commits.
@@ -1155,7 +1193,7 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
1155
1193
  * rejected replays as `status: rejected`; this companion result preserves the
1156
1194
  * cache provenance needed by structured events and server helpers.
1157
1195
  */
1158
- export async function processPushCommitWithTrace(ctx, schema, resolved, clientId, frame, wireSchema = schema) {
1196
+ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId, frame, wireSchema = schema, outbox) {
1159
1197
  // The frame names its rows before the transaction opens, so the admission
1160
1198
  // read carries the commit's read-ahead and the apply issues no separate
1161
1199
  // prefetch statement.
@@ -1171,14 +1209,14 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
1171
1209
  }
1172
1210
  return processPushOperationsWithTrace(ctx, schema, resolved, clientId, frame.clientCommitId, async () => frame.operations, wireSchema, targets.size === 0
1173
1211
  ? undefined
1174
- : [...targets].map(([table, rowIds]) => ({ table, rowIds })));
1212
+ : [...targets].map(([table, rowIds]) => ({ table, rowIds })), outbox);
1175
1213
  }
1176
1214
  /**
1177
1215
  * Shared serialized apply path for SSP2 commits and authoritative commands.
1178
1216
  * The builder runs after the partition lock and idempotency re-check, so its
1179
1217
  * reads and the returned operations share the transaction that is committed.
1180
1218
  */
1181
- export async function processPushOperationsWithTrace(ctx, schema, resolved, clientId, clientCommitId, buildOperations, wireSchema = schema, prefetchTargets) {
1219
+ export async function processPushOperationsWithTrace(ctx, schema, resolved, clientId, clientCommitId, buildOperations, wireSchema = schema, prefetchTargets, outbox) {
1182
1220
  const { partition } = ctx;
1183
1221
  const createdAtMs = clockOf(ctx)();
1184
1222
  const blobCtx = {
@@ -1191,6 +1229,11 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1191
1229
  const commitValidator = ctx.commitValidator;
1192
1230
  const reactionPlanner = ctx.reactionPlanner;
1193
1231
  const tx = await ctx.storage.begin(partition);
1232
+ // §6.3.2: the settlement's writes commit whatever the commit's outcome.
1233
+ const release = () => outbox?.settlement !== undefined ? tx.commit() : tx.rollback();
1234
+ const sequence = outbox === undefined
1235
+ ? undefined
1236
+ : { outboxId: outbox.outboxId, clientSeq: outbox.clientSeq };
1194
1237
  try {
1195
1238
  if (reactionPlanner !== undefined && tx.enqueueReactions === undefined) {
1196
1239
  throw new Error('storage transaction does not support configured durable reactions');
@@ -1203,14 +1246,14 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1203
1246
  // validator, or merge.
1204
1247
  let prepared;
1205
1248
  try {
1206
- prepared = await tx.preparePushApply(clientId, clientCommitId, schema.version, prefetchTargets);
1249
+ prepared = await tx.preparePushApply(clientId, clientCommitId, schema.version, prefetchTargets, outbox?.settlement);
1207
1250
  }
1208
1251
  catch (error) {
1209
1252
  if (error instanceof SyncError &&
1210
1253
  error.code === 'sync.idempotency_cache_miss') {
1211
1254
  // §6.3: answer the retryable cache-miss for this commit rather than
1212
1255
  // re-applying. Not persisted — a retry may find a readable record.
1213
- await tx.rollback();
1256
+ await release();
1214
1257
  return {
1215
1258
  frame: idempotencyCacheMissFrame(clientCommitId, error),
1216
1259
  replayed: false,
@@ -1223,9 +1266,10 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1223
1266
  // migration can interleave in between.
1224
1267
  const refusal = serveGateRefusal(prepared.gate, schema.version, ctx.checkpoints);
1225
1268
  if (refusal !== undefined) {
1226
- await tx.rollback();
1269
+ await release();
1227
1270
  throw serveNotReadyError(refusal);
1228
1271
  }
1272
+ const watermark = prepared.watermark ?? outbox?.watermark;
1229
1273
  if (prepared.persisted !== undefined) {
1230
1274
  const conflict = prepared.persisted.results.find((result) => result.status === 'conflict');
1231
1275
  const authorization = prepared.persisted.conflictAuthorization;
@@ -1235,7 +1279,7 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1235
1279
  authorization.schemaVersion !== schema.version ||
1236
1280
  table === undefined ||
1237
1281
  !authorizeWrite(table, authorization.scopes, resolved))) {
1238
- await tx.rollback();
1282
+ await release();
1239
1283
  return processedPushCommit(clientCommitId, {
1240
1284
  ...prepared.persisted,
1241
1285
  results: [
@@ -1247,10 +1291,21 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1247
1291
  retryable: false,
1248
1292
  },
1249
1293
  ],
1250
- }, true);
1294
+ }, true, watermark);
1251
1295
  }
1252
- await tx.rollback();
1253
- return processedPushCommit(clientCommitId, prepared.persisted, true);
1296
+ await release();
1297
+ return processedPushCommit(clientCommitId, prepared.persisted, true, watermark);
1298
+ }
1299
+ // §6.3.2 step 3: below the watermark without a retained result.
1300
+ if (outbox !== undefined &&
1301
+ watermark !== undefined &&
1302
+ outbox.clientSeq < watermark) {
1303
+ await release();
1304
+ return {
1305
+ frame: commitExpiredFrame(clientCommitId),
1306
+ replayed: false,
1307
+ watermark,
1308
+ };
1254
1309
  }
1255
1310
  const results = [];
1256
1311
  const changes = [];
@@ -1302,15 +1357,23 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1302
1357
  // §6.4: the row each touched (table, rowId) held before this commit, so a
1303
1358
  // conflict reports the row as stored once the commit rolls back.
1304
1359
  const storedBeforeCommit = new Map();
1360
+ // §2.2: inserts start above the floor, which this commit's deletes raise
1361
+ // as they stage.
1362
+ let deleteFloor = prepared.deleteFloor;
1305
1363
  for (let opIndex = 0; opIndex < operations.length; opIndex++) {
1306
1364
  const op = operations[opIndex];
1307
1365
  if (op === undefined)
1308
1366
  continue;
1309
- const outcome = await applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, ctx.actorId);
1367
+ const outcome = await applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, ctx.actorId, deleteFloor);
1310
1368
  if (outcome.kind === 'terminate') {
1311
1369
  terminated = outcome.record;
1312
1370
  break;
1313
1371
  }
1372
+ for (const change of outcome.changes) {
1373
+ if (change.op === 'delete') {
1374
+ deleteFloor = Math.max(deleteFloor, change.rowVersion);
1375
+ }
1376
+ }
1314
1377
  const rowKey = `${op.table}\u0000${op.rowId}`;
1315
1378
  if (!storedBeforeCommit.has(rowKey)) {
1316
1379
  storedBeforeCommit.set(rowKey, outcome.staged.stored);
@@ -1405,8 +1468,8 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1405
1468
  // Discard candidates and persist the rejection while retaining the same
1406
1469
  // partition lock. There is no unlock gap in which a duplicate can rerun,
1407
1470
  // and the finalization returns the canonical outcome it persisted.
1408
- const canonical = await tx.commitRejectedPushResult(clientId, clientCommitId, stored);
1409
- return processedPushCommit(clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
1471
+ const canonical = await tx.commitRejectedPushResult(clientId, clientCommitId, stored, sequence);
1472
+ return processedPushCommit(clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity, watermark);
1410
1473
  }
1411
1474
  const commitSeq = await tx.appendCommit({
1412
1475
  clientId,
@@ -1433,7 +1496,7 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1433
1496
  commitSeq,
1434
1497
  results,
1435
1498
  });
1436
- await tx.putPushResult(clientId, clientCommitId, stored);
1499
+ await tx.putPushResult(clientId, clientCommitId, stored, sequence);
1437
1500
  await tx.commit();
1438
1501
  if (ctx.events !== undefined) {
1439
1502
  const atMs = clockOf(ctx)();
@@ -1467,7 +1530,7 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1467
1530
  changes,
1468
1531
  });
1469
1532
  }
1470
- return processedPushCommit(clientCommitId, stored, false);
1533
+ return processedPushCommit(clientCommitId, stored, false, watermark);
1471
1534
  }
1472
1535
  catch (error) {
1473
1536
  if (error instanceof StorageConstraintError) {
@@ -1484,7 +1547,7 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1484
1547
  ],
1485
1548
  });
1486
1549
  try {
1487
- const canonical = await tx.commitRejectedPushResult(clientId, clientCommitId, stored);
1550
+ const canonical = await tx.commitRejectedPushResult(clientId, clientCommitId, stored, sequence);
1488
1551
  return processedPushCommit(clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
1489
1552
  }
1490
1553
  catch (finalizationError) {
@@ -7,8 +7,8 @@
7
7
  * queues the ack's cursor write without awaiting it, so `drain()` is the
8
8
  * awaitable boundary a host uses before closing its storage or ending a
9
9
  * hibernatable event (§8.2). Initial
10
- * subscription registration comes from the client's most recent pull
11
- * (§8.1, loaded from the client record); a sync round completed on the
10
+ * registration comes from the live units of the client record (§8.1); a sync
11
+ * round completed on the
12
12
  * connection replaces it at round end (§8.7). Deltas are complete SSP2
13
13
  * response messages pushed as `0x00`-tagged binary (§8.2/§8.7); sync
14
14
  * rounds ride the same socket as `0x01`-tagged byte-stream chunks driven
@@ -20,7 +20,7 @@ import { type PresenceKind, type ScopeMap, type WakeReason } from '@syncular/cor
20
20
  import type { ServerLimits, SyncRequestContext, SyncServerConfig } from './context.js';
21
21
  import { type SyncularErrorHandler, type SyncularErrorMapper } from './errors.js';
22
22
  import { type SyncularServerEvents } from './events.js';
23
- import { type CompiledTable } from './schema.js';
23
+ import { type CompiledSchema } from './schema.js';
24
24
  import type { ClientRecord, ServerStorage, StoredCommit } from './storage.js';
25
25
  /**
26
26
  * Realtime adds fanout/presence tuning to the canonical sync-server config;
@@ -79,8 +79,11 @@ export interface RealtimeConnectOptions {
79
79
  */
80
80
  readonly onPresence?: (presence: ReadonlyMap<string, string>) => void;
81
81
  }
82
+ /** One active (unit, table) pair of a live unit (§8.1). */
82
83
  interface Registration {
83
- readonly codec: CompiledTable;
84
+ /** The schema version of the client's latest round: the delta codec (§9). */
85
+ readonly schema: CompiledSchema;
86
+ /** The unit id (§4.1). */
84
87
  readonly id: string;
85
88
  readonly table: string;
86
89
  readonly schemaVersion: number;
@@ -174,8 +177,9 @@ export declare class RealtimeSession {
174
177
  * failed, because that round applied nothing.
175
178
  */
176
179
  /**
177
- * A pull outside this connection changed the client's subscriptions. A
178
- * round in flight on the connection reloads them at its end anyway.
180
+ * A pull outside this connection changed the client's registration list
181
+ * or live set. A round in flight on the connection reloads it at its end
182
+ * anyway.
179
183
  */
180
184
  refreshAfterPull(): Promise<void>;
181
185
  refreshRegistrations(failClosed: boolean): Promise<void>;
@@ -199,7 +203,8 @@ export declare class RealtimeHub {
199
203
  /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
200
204
  readonly presence: PresenceRegistry;
201
205
  constructor(config: RealtimeHubConfig);
202
- projectPayload(registration: Registration, payload: Uint8Array): Uint8Array;
206
+ /** The current compiled schema: the storage codec of fanned-out changes. */
207
+ get schema(): CompiledSchema;
203
208
  /**
204
209
  * Compose `sink` into the hub's `events`, so socket rounds and sessions
205
210
  * opened afterwards report to it as well. `createSyncularHono` uses it to
@@ -226,7 +231,7 @@ export declare class RealtimeHub {
226
231
  */
227
232
  fanoutPresence(origin: Pick<RealtimeSession, 'partition' | 'actorId' | 'clientId'>, scopeKey: string, kind: PresenceKind, doc: PresenceDoc | null): void;
228
233
  /**
229
- * Resolve the client record's subscription list into per-connection
234
+ * Resolve the client record's live units into per-connection
230
235
  * registrations (§8.1 at upgrade; §8.7 at socket-round end).
231
236
  */
232
237
  loadRegistrations(partition: string, actorId: string, clientId: string, record: ClientRecord | undefined): Promise<Registration[]>;
@@ -245,8 +250,8 @@ export declare class RealtimeHub {
245
250
  get mapError(): SyncularErrorMapper | undefined;
246
251
  requestContext(session: RealtimeSession): SyncRequestContext;
247
252
  /**
248
- * Register a connected socket (§8.1): load the client's last pull's
249
- * subscription list, resolve + intersect scopes, send `hello`.
253
+ * Register a connected socket (§8.1): load the client record's live
254
+ * units, resolve their effective scopes, send `hello`.
250
255
  */
251
256
  connect(options: RealtimeConnectOptions): Promise<RealtimeSession>;
252
257
  /**
@@ -269,7 +274,8 @@ export declare class RealtimeHub {
269
274
  /** RealtimeNotifier: fan an applied commit out to matching sessions. */
270
275
  notifyCommit(partition: string, commit: StoredCommit): Promise<void>;
271
276
  /**
272
- * RealtimeNotifier: a pull changed a client's subscription list (§8.7).
277
+ * RealtimeNotifier: a pull changed a client's registration list or live
278
+ * set (§8.1).
273
279
  * Its sockets reload their registrations with the round-end semantics, so
274
280
  * an unreadable record keeps the previous registrations.
275
281
  */