@syncular/server 0.58.0 → 0.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +49 -36
  2. package/dist/admin.d.ts +32 -20
  3. package/dist/admin.js +46 -40
  4. package/dist/blob-handlers.d.ts +25 -31
  5. package/dist/blob-handlers.js +63 -41
  6. package/dist/blob-store.d.ts +42 -24
  7. package/dist/blob-store.js +0 -0
  8. package/dist/bucket-blob-store.d.ts +12 -8
  9. package/dist/bucket-blob-store.js +54 -45
  10. package/dist/bucket-segment-store.js +18 -16
  11. package/dist/content-encoding.d.ts +5 -2
  12. package/dist/content-encoding.js +42 -13
  13. package/dist/context.d.ts +19 -5
  14. package/dist/context.js +19 -1
  15. package/dist/d1-storage.d.ts +14 -98
  16. package/dist/d1-storage.js +249 -1119
  17. package/dist/errors.js +16 -0
  18. package/dist/events.d.ts +36 -18
  19. package/dist/frame-bytes.js +24 -6
  20. package/dist/handler.js +503 -208
  21. package/dist/local-authority.d.ts +2 -0
  22. package/dist/local-authority.js +24 -12
  23. package/dist/object-bucket.d.ts +2 -0
  24. package/dist/operations-realtime.js +69 -50
  25. package/dist/operations.d.ts +5 -2
  26. package/dist/operations.js +20 -29
  27. package/dist/pg-executor-pglite.d.ts +5 -6
  28. package/dist/pg-executor-pglite.js +22 -14
  29. package/dist/pg-executor.d.ts +4 -1
  30. package/dist/postgres-storage.d.ts +24 -19
  31. package/dist/postgres-storage.js +420 -262
  32. package/dist/pull.d.ts +70 -47
  33. package/dist/pull.js +270 -301
  34. package/dist/push.d.ts +12 -3
  35. package/dist/push.js +361 -173
  36. package/dist/realtime.d.ts +85 -39
  37. package/dist/realtime.js +355 -219
  38. package/dist/relational-rows.d.ts +21 -66
  39. package/dist/relational-rows.js +28 -109
  40. package/dist/s3-blob-store.d.ts +11 -12
  41. package/dist/s3-blob-store.js +20 -13
  42. package/dist/s3-object-bucket.d.ts +8 -1
  43. package/dist/s3-object-bucket.js +16 -3
  44. package/dist/schema.d.ts +14 -0
  45. package/dist/schema.js +23 -0
  46. package/dist/scopes.d.ts +6 -2
  47. package/dist/scopes.js +22 -4
  48. package/dist/seed.js +10 -16
  49. package/dist/segment-download.d.ts +4 -1
  50. package/dist/segment-download.js +22 -6
  51. package/dist/signed-url.d.ts +2 -2
  52. package/dist/signed-url.js +9 -2
  53. package/dist/sigv4.d.ts +8 -2
  54. package/dist/sigv4.js +8 -4
  55. package/dist/sqlite-blob-store.d.ts +1 -1
  56. package/dist/sqlite-blob-store.js +23 -22
  57. package/dist/sqlite-dialect.d.ts +164 -84
  58. package/dist/sqlite-dialect.js +1145 -150
  59. package/dist/sqlite-lease-store.js +13 -18
  60. package/dist/sqlite-storage.d.ts +9 -62
  61. package/dist/sqlite-storage.js +303 -1123
  62. package/dist/storage-query.d.ts +30 -1
  63. package/dist/storage-query.js +68 -0
  64. package/dist/storage.d.ts +185 -63
  65. package/dist/storage.js +15 -0
  66. package/package.json +2 -2
  67. package/src/admin.ts +99 -57
  68. package/src/blob-handlers.ts +91 -72
  69. package/src/blob-store.ts +0 -0
  70. package/src/bucket-blob-store.ts +75 -48
  71. package/src/bucket-segment-store.ts +20 -15
  72. package/src/content-encoding.ts +48 -16
  73. package/src/context.ts +33 -6
  74. package/src/d1-storage.ts +350 -1700
  75. package/src/errors.ts +16 -0
  76. package/src/events.ts +37 -18
  77. package/src/frame-bytes.ts +26 -6
  78. package/src/handler.ts +654 -261
  79. package/src/local-authority.ts +27 -14
  80. package/src/object-bucket.ts +2 -0
  81. package/src/operations-realtime.ts +85 -61
  82. package/src/operations.ts +44 -42
  83. package/src/pg-executor-pglite.ts +27 -23
  84. package/src/pg-executor.ts +5 -1
  85. package/src/postgres-storage.ts +557 -354
  86. package/src/pull.ts +406 -440
  87. package/src/push.ts +466 -220
  88. package/src/realtime.ts +447 -290
  89. package/src/relational-rows.ts +43 -121
  90. package/src/s3-blob-store.ts +23 -13
  91. package/src/s3-object-bucket.ts +20 -2
  92. package/src/schema.ts +31 -0
  93. package/src/scopes.ts +23 -3
  94. package/src/seed.ts +13 -20
  95. package/src/segment-download.ts +33 -7
  96. package/src/signed-url.ts +10 -4
  97. package/src/sigv4.ts +17 -4
  98. package/src/sqlite-blob-store.ts +27 -26
  99. package/src/sqlite-dialect.ts +1851 -199
  100. package/src/sqlite-lease-store.ts +12 -23
  101. package/src/sqlite-storage.ts +390 -1821
  102. package/src/storage-query.ts +102 -0
  103. package/src/storage.ts +215 -67
package/src/handler.ts CHANGED
@@ -11,7 +11,9 @@
11
11
  */
12
12
  import {
13
13
  DecodeError,
14
- decodeMessage,
14
+ decodeRequest,
15
+ echoDigest,
16
+ type ProgressFrame,
15
17
  type PullHeaderFrame,
16
18
  type PushCommitFrame,
17
19
  type PushResultDetailsFrame,
@@ -21,7 +23,10 @@ import {
21
23
  type ResponseFrame,
22
24
  type RoundFailureFrame,
23
25
  type ScopeMap,
24
- type SubscriptionFrame,
26
+ type UnitFrame,
27
+ type UnitScopes,
28
+ registrationDigest,
29
+ unitId,
25
30
  } from '@syncular/core';
26
31
  import type { SyncRequestContext } from './context';
27
32
  import {
@@ -34,7 +39,7 @@ import {
34
39
  import { reportError, SyncError, syncError } from './errors';
35
40
  import {
36
41
  emitEvent,
37
- type PullSubscriptionSummary,
42
+ type PullUnitSummary,
38
43
  type SyncularServerEvents,
39
44
  } from './events';
40
45
  import {
@@ -46,26 +51,48 @@ import type { LeaseRecord } from './lease-store';
46
51
  import {
47
52
  ACCEPT_EXTERNAL_ROWS,
48
53
  ACCEPT_INLINE_ROWS,
54
+ bootstrapSegments,
49
55
  clampPullLimits,
56
+ commitFrame,
57
+ coveredTables,
58
+ type PullLimits,
50
59
  type PullSectionTrace,
51
- prepareSections,
52
- preparedSection,
53
- type SubscriptionPlan,
60
+ planBootstrap,
61
+ planUnit,
62
+ type UnitPlan,
54
63
  } from './pull';
55
64
  import { type ProcessedPushCommit, processPushCommitWithTrace } from './push';
56
65
  import { serveNotReadyError } from './readiness';
57
- import type { CompiledSchema } from './schema';
66
+ import type { CompiledSchema, CompiledTable } from './schema';
58
67
  import { compileSchema } from './schema';
59
68
  import { schemaWindowOf, projectRowPayload } from './schema-window';
60
- import { computeEffective, type ResolvedScopes } from './scopes';
69
+ import type { ResolvedScopes } from './scopes';
61
70
  import { StorageQueryError } from './storage-errors';
62
71
  import {
63
- type ClientSubscription,
72
+ type CatchingUpUnit,
73
+ type ClientRecord,
74
+ type ClientRegistration,
75
+ type LiveWindow,
64
76
  type PartitionRegistryEntry,
65
77
  serveGateRefusal,
66
78
  serveGateTokenChanged,
67
79
  } from './storage';
68
80
 
81
+ interface PlannedUnit {
82
+ readonly plan: UnitPlan;
83
+ /** Absent for a live unit. */
84
+ readonly progress: ProgressFrame | undefined;
85
+ }
86
+
87
+ interface PullPlan {
88
+ readonly header: PullHeaderFrame;
89
+ readonly limits: PullLimits;
90
+ /** The traveling list (§4.1); absent when the request referred to it. */
91
+ readonly registration: ClientRegistration | undefined;
92
+ /** The effective list; absent when the answer is `unregistered`. */
93
+ readonly units: readonly PlannedUnit[] | undefined;
94
+ }
95
+
69
96
  interface RequestPlan {
70
97
  readonly wireVersion: number;
71
98
  readonly logEpoch: string;
@@ -74,8 +101,9 @@ interface RequestPlan {
74
101
  /** §1.5: the code this request reports for its last unseen round failure. */
75
102
  readonly roundFailure: RoundFailureFrame | undefined;
76
103
  readonly pushes: readonly PushCommitFrame[];
77
- readonly pull: PullHeaderFrame | undefined;
78
- readonly subscriptions: readonly SubscriptionPlan[];
104
+ readonly pull: PullPlan | undefined;
105
+ /** The client record read for the actor binding (§1.5, §4.5). */
106
+ readonly record: ClientRecord | undefined;
79
107
  readonly resolved: ResolvedScopes;
80
108
  readonly schemaFloor: boolean;
81
109
  /**
@@ -100,7 +128,11 @@ function validateResolvedKeys(allowed: ScopeMap, schema: CompiledSchema): void {
100
128
  // bug — fail the request, do not guess.
101
129
  throw syncError(
102
130
  'sync.invalid_subscription',
103
- `resolveScopes returned undeclared scope variable ${JSON.stringify(key)} (§3.2)`,
131
+ 'resolveScopes returned an undeclared scope variable (§3.2)',
132
+ JSON.stringify({
133
+ reason: 'undeclared_resolved_variable',
134
+ variable: key,
135
+ }),
104
136
  );
105
137
  }
106
138
  }
@@ -163,8 +195,8 @@ async function resolveOnce(
163
195
  });
164
196
  } catch (error) {
165
197
  if (error instanceof SyncError) throw error;
166
- // §3.2 rule 5 / §3.4 step 4: fail loud, never leak — subscriptions
167
- // revoke and writes reject with sync.forbidden. A throw is NOT an
198
+ // §3.2 rule 5 / §3.4 step 4: fail loud, never leak — units revoke and
199
+ // writes reject with sync.forbidden. A throw is NOT an
168
200
  // outage (§7.3.3): it never reaches the lease.
169
201
  const events = ctx.events;
170
202
  if (events !== undefined) {
@@ -216,61 +248,43 @@ async function planRequest(
216
248
  }
217
249
  const pushes: PushCommitFrame[] = [];
218
250
  let roundFailure: RoundFailureFrame | undefined;
219
- let pull: PullHeaderFrame | undefined;
220
- const subFrames: SubscriptionFrame[] = [];
251
+ let pullHeader: PullHeaderFrame | undefined;
252
+ const unitFrames: UnitFrame[] = [];
253
+ const progressFrames: ProgressFrame[] = [];
221
254
  for (const frame of request.frames) {
222
255
  if (frame.type === 'ROUND_FAILURE') roundFailure = frame;
223
256
  else if (frame.type === 'PUSH_COMMIT') pushes.push(frame);
224
- else if (frame.type === 'PULL_HEADER') pull = frame;
225
- else if (frame.type === 'SUBSCRIPTION') subFrames.push(frame);
257
+ else if (frame.type === 'PULL_HEADER') pullHeader = frame;
258
+ else if (frame.type === 'UNIT') unitFrames.push(frame);
259
+ else if (frame.type === 'PROGRESS') progressFrames.push(frame);
226
260
  }
227
261
 
228
- if (
229
- request.wireVersion >= 2 &&
230
- header.logEpoch === undefined &&
231
- pushes.length > 0
232
- ) {
262
+ if (header.logEpoch === undefined && pushes.length > 0) {
233
263
  throw syncError(
234
264
  'sync.invalid_request',
235
265
  'epoch acquisition requests must not carry push commits (§2.1)',
236
266
  );
237
267
  }
238
- const epochReset =
239
- request.wireVersion >= 2 && header.logEpoch !== registry.logEpoch;
268
+ const epochReset = header.logEpoch !== registry.logEpoch;
269
+ const unserved = {
270
+ wireVersion: request.wireVersion,
271
+ logEpoch: registry.logEpoch,
272
+ epochReset,
273
+ header,
274
+ roundFailure,
275
+ pushes: [],
276
+ pull: undefined,
277
+ record: undefined,
278
+ resolved: { ok: false },
279
+ leaseToEmit: undefined,
280
+ } as const;
240
281
 
241
282
  if (header.schemaVersion !== schema.version) {
242
283
  // §2.4: no degraded encoding — answer with the schema floor (§1.6).
243
284
  // No lease is issued on a floor round (§7.3.3).
244
- return {
245
- wireVersion: request.wireVersion,
246
- logEpoch: registry.logEpoch,
247
- epochReset,
248
- header,
249
- roundFailure,
250
- pushes,
251
- pull,
252
- subscriptions: [],
253
- resolved: { ok: false },
254
- schemaFloor: true,
255
- leaseToEmit: undefined,
256
- };
257
- }
258
-
259
- if (epochReset) {
260
- return {
261
- wireVersion: request.wireVersion,
262
- logEpoch: registry.logEpoch,
263
- epochReset: true,
264
- header,
265
- roundFailure,
266
- pushes: [],
267
- pull: undefined,
268
- subscriptions: [],
269
- resolved: { ok: false },
270
- schemaFloor: false,
271
- leaseToEmit: undefined,
272
- };
285
+ return { ...unserved, schemaFloor: true };
273
286
  }
287
+ if (epochReset) return { ...unserved, schemaFloor: false };
274
288
 
275
289
  if (header.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
276
290
  throw syncError(
@@ -297,55 +311,111 @@ async function planRequest(
297
311
  if (totalOperations > limits.maxOperationsPerRequest) {
298
312
  throw syncError(
299
313
  'sync.too_many_operations',
300
- `request carries ${totalOperations} operations (cap ${limits.maxOperationsPerRequest}, §6.1)`,
314
+ 'request carries more operations than the server accepts (§6.1)',
315
+ JSON.stringify({
316
+ max: limits.maxOperationsPerRequest,
317
+ actual: totalOperations,
318
+ }),
319
+ );
320
+ }
321
+ // §6.1 sequence rules: with an outbox every clientSeq is ≥ 1 and strictly
322
+ // increasing in frame order; without one every clientSeq is 0.
323
+ if (
324
+ pushes.some((push, i) =>
325
+ header.outboxId === undefined
326
+ ? push.clientSeq !== 0
327
+ : push.clientSeq < 1 ||
328
+ (i > 0 && push.clientSeq <= pushes[i - 1]!.clientSeq),
329
+ )
330
+ ) {
331
+ throw syncError(
332
+ 'sync.invalid_request',
333
+ 'push commits break the clientSeq rules (§6.1)',
334
+ JSON.stringify({
335
+ outbox: header.outboxId !== undefined,
336
+ clientSeqs: pushes.map((push) => push.clientSeq),
337
+ }),
338
+ );
339
+ }
340
+ // §1.7: the UNIT cap, checked before any unit is planned.
341
+ if (unitFrames.length > limits.maxSubscriptionsPerRequest) {
342
+ throw syncError(
343
+ 'sync.limit_exceeded',
344
+ 'request carries more units than the server accepts (§1.7)',
345
+ JSON.stringify({
346
+ limit: 'maxSubscriptionsPerRequest',
347
+ max: limits.maxSubscriptionsPerRequest,
348
+ actual: unitFrames.length,
349
+ }),
301
350
  );
302
351
  }
303
352
 
304
- if (pull !== undefined) {
305
- // §4.2: rows support is mandatory (bits 0 and 1) — reject its absence
306
- // as request validation (the MAY of §1.7).
307
- if ((pull.accept & (ACCEPT_INLINE_ROWS | ACCEPT_EXTERNAL_ROWS)) === 0) {
353
+ // §4.1: the effective list is the traveling list, or the stored list the
354
+ // digest names; a digest naming neither answers `unregistered`.
355
+ let list: { scopes: UnitScopes; tables: CompiledTable[] }[] | undefined;
356
+ let registration: ClientRegistration | undefined;
357
+ if (pullHeader !== undefined) {
358
+ // §4.2: rows support is mandatory (bits 0 and 1).
359
+ if (
360
+ (pullHeader.accept & (ACCEPT_INLINE_ROWS | ACCEPT_EXTERNAL_ROWS)) ===
361
+ 0
362
+ ) {
308
363
  throw syncError(
309
364
  'sync.invalid_request',
310
365
  'accept must include rows-segment support (bits 0 and 1, §4.2)',
311
366
  );
312
367
  }
313
- }
314
-
315
- // Request validation for subscriptions (§1.7): duplicate ids, unknown
316
- // tables, undeclared scope keys, requested '*'.
317
- const seenIds = new Set<string>();
318
- const validated: Array<{ frame: SubscriptionFrame; table: string }> = [];
319
- for (const frame of subFrames) {
320
- if (seenIds.has(frame.id)) {
321
- throw syncError(
322
- 'sync.invalid_subscription',
323
- `duplicate subscription id ${JSON.stringify(frame.id)} (§4.1)`,
324
- );
325
- }
326
- seenIds.add(frame.id);
327
- const table = schema.tables.get(frame.table);
328
- if (table === undefined) {
329
- throw syncError(
330
- 'sync.unknown_table',
331
- `subscription names unknown table ${JSON.stringify(frame.table)} (§4.3)`,
332
- );
333
- }
334
- for (const [key, values] of Object.entries(frame.scopes)) {
335
- if (!table.declaredVariables.has(key)) {
368
+ const traveling =
369
+ unitFrames.length > 0 ||
370
+ sameBytes(pullHeader.registrationDigest, registrationDigest([]));
371
+ if (traveling) {
372
+ const units = unitFrames.map((frame) => frame.scopes);
373
+ const digest = registrationDigest(units);
374
+ if (!sameBytes(digest, pullHeader.registrationDigest)) {
336
375
  throw syncError(
337
376
  'sync.invalid_subscription',
338
- `requested scope key ${JSON.stringify(key)} is not declared by table ${JSON.stringify(frame.table)} (§3.2)`,
377
+ 'the registration digest differs from the traveling list (§4.1)',
378
+ JSON.stringify({ reason: 'registration_digest' }),
339
379
  );
340
380
  }
341
- if (values.includes('*')) {
342
- throw syncError(
343
- 'sync.invalid_subscription',
344
- `requested scope value '*' is reserved for allowed scopes (§3.2)`,
345
- );
381
+ registration = { units, digest };
382
+ }
383
+ const units =
384
+ registration?.units ??
385
+ (record?.registration !== undefined &&
386
+ sameBytes(record.registration.digest, pullHeader.registrationDigest)
387
+ ? record.registration.units
388
+ : undefined);
389
+ if (units !== undefined) {
390
+ const ids = new Set<string>();
391
+ list = units.map((scopes) => {
392
+ const tables = coveredTables(schema, scopes);
393
+ const id = unitId(scopes);
394
+ if (ids.has(id)) {
395
+ throw syncError(
396
+ 'sync.invalid_subscription',
397
+ 'the registration list names a scope map twice (§4.1)',
398
+ JSON.stringify({ reason: 'duplicate_unit', scopes }),
399
+ );
400
+ }
401
+ ids.add(id);
402
+ return { scopes, tables };
403
+ });
404
+ const progressed = new Set<string>();
405
+ for (const frame of progressFrames) {
406
+ if (!ids.has(frame.id) || progressed.has(frame.id)) {
407
+ throw syncError(
408
+ 'sync.invalid_subscription',
409
+ 'a PROGRESS frame names no registered unit or repeats one (§4.1)',
410
+ JSON.stringify({
411
+ reason: ids.has(frame.id) ? 'duplicate_progress' : 'unknown_unit',
412
+ id: frame.id,
413
+ }),
414
+ );
415
+ }
416
+ progressed.add(frame.id);
346
417
  }
347
418
  }
348
- validated.push({ frame, table: frame.table });
349
419
  }
350
420
 
351
421
  const { resolved, leaseToEmit } = await resolveOnce(
@@ -353,17 +423,7 @@ async function planRequest(
353
423
  header.clientId,
354
424
  compileSchema(ctx.schema),
355
425
  );
356
-
357
- const subscriptions: SubscriptionPlan[] = validated.map(({ frame }) => {
358
- const table = schema.tables.get(frame.table);
359
- if (table === undefined) throw new Error('unreachable: validated table');
360
- const outcome = computeEffective(frame.scopes, resolved);
361
- if (outcome.status === 'active') {
362
- return { frame, table, status: 'active', effective: outcome.effective };
363
- }
364
- return { frame, table, status: 'revoked', effective: {} };
365
- });
366
-
426
+ const progress = new Map(progressFrames.map((frame) => [frame.id, frame]));
367
427
  return {
368
428
  wireVersion: request.wireVersion,
369
429
  logEpoch: registry.logEpoch,
@@ -371,18 +431,39 @@ async function planRequest(
371
431
  header,
372
432
  roundFailure,
373
433
  pushes,
374
- pull,
375
- subscriptions,
434
+ pull:
435
+ pullHeader === undefined
436
+ ? undefined
437
+ : {
438
+ header: pullHeader,
439
+ limits: clampPullLimits(pullHeader),
440
+ registration,
441
+ units: list?.map(({ scopes, tables }) => {
442
+ const plan = planUnit(scopes, tables, resolved);
443
+ return { plan, progress: progress.get(plan.id) };
444
+ }),
445
+ },
446
+ record,
376
447
  resolved,
377
448
  schemaFloor: false,
378
449
  leaseToEmit,
379
450
  };
380
451
  }
381
452
 
453
+ function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
454
+ return a.length === b.length && a.every((byte, i) => byte === b[i]);
455
+ }
456
+
382
457
  /** Mutable outcome box shared with the instrumented stream wrapper. */
383
458
  interface RequestReport {
384
459
  outcome: 'ok' | 'schema_floor' | 'epoch_acquired' | 'reset' | 'error';
385
460
  errorCode?: string;
461
+ /**
462
+ * The completed round's client-record write (§4.5, §8.1). Set only by a
463
+ * round that streamed without an in-band error; runs after the serve-gate
464
+ * verification.
465
+ */
466
+ persist?: () => Promise<void>;
386
467
  }
387
468
 
388
469
  function pushResultDetailsFrame(
@@ -470,12 +551,12 @@ async function* streamResponse(
470
551
  plan: RequestPlan,
471
552
  ctx: SyncRequestContext,
472
553
  schema: CompiledSchema,
473
- report?: RequestReport,
554
+ report: RequestReport,
474
555
  ): AsyncGenerator<Uint8Array> {
475
556
  const events = ctx.events;
476
557
  yield responseEnvelopeHeader(plan.wireVersion);
477
558
  if (plan.schemaFloor) {
478
- if (report !== undefined) report.outcome = 'schema_floor';
559
+ report.outcome = 'schema_floor';
479
560
  yield encodeResponseFrame(
480
561
  {
481
562
  type: 'RESP_HEADER',
@@ -483,9 +564,8 @@ async function* streamResponse(
483
564
  -1,
484
565
  )!.version,
485
566
  latestSchemaVersion: ctx.schema.version,
486
- ...(plan.wireVersion >= 2
487
- ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
488
- : {}),
567
+ logEpoch: plan.logEpoch,
568
+ resetRequired: plan.epochReset,
489
569
  },
490
570
  plan.wireVersion,
491
571
  );
@@ -496,17 +576,14 @@ async function* streamResponse(
496
576
  {
497
577
  type: 'RESP_HEADER',
498
578
  latestSchemaVersion: ctx.schema.version,
499
- ...(plan.wireVersion >= 2
500
- ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
501
- : {}),
579
+ logEpoch: plan.logEpoch,
580
+ resetRequired: plan.epochReset,
502
581
  },
503
582
  plan.wireVersion,
504
583
  );
505
584
  if (plan.epochReset) {
506
- if (report !== undefined) {
507
- report.outcome =
508
- plan.header.logEpoch === undefined ? 'epoch_acquired' : 'reset';
509
- }
585
+ report.outcome =
586
+ plan.header.logEpoch === undefined ? 'epoch_acquired' : 'reset';
510
587
  yield END_FRAME_BYTES;
511
588
  return;
512
589
  }
@@ -532,19 +609,41 @@ async function* streamResponse(
532
609
  });
533
610
  }
534
611
  }
612
+ const { clientId, outboxId } = plan.header;
535
613
  try {
536
614
  // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
537
615
  const currentSchema = compileSchema(ctx.schema);
538
616
  let acceptedThrough = 0;
539
- for (const push of plan.pushes) {
617
+ // §6.3.2: the request's first commit settles the outbox and reads `W`.
618
+ let watermark = 0;
619
+ for (const [index, push] of plan.pushes.entries()) {
540
620
  const processed = await processPushCommitWithTrace(
541
621
  ctx,
542
622
  currentSchema,
543
623
  plan.resolved,
544
- plan.header.clientId,
624
+ clientId,
545
625
  push,
546
626
  schema,
627
+ outboxId === undefined
628
+ ? undefined
629
+ : {
630
+ outboxId,
631
+ clientSeq: push.clientSeq,
632
+ watermark,
633
+ ...(index === 0
634
+ ? {
635
+ settlement: {
636
+ outboxId,
637
+ commits: plan.pushes.map((commit) => ({
638
+ clientCommitId: commit.clientCommitId,
639
+ clientSeq: commit.clientSeq,
640
+ })),
641
+ },
642
+ }
643
+ : {}),
644
+ },
547
645
  );
646
+ watermark = processed.watermark ?? watermark;
548
647
  acceptedThrough = Math.max(
549
648
  acceptedThrough,
550
649
  processed.frame.commitSeq ?? 0,
@@ -589,7 +688,7 @@ async function* streamResponse(
589
688
  }),
590
689
  };
591
690
  if (events !== undefined) {
592
- emitPushEvent(events, ctx, plan.header.clientId, push, processed);
691
+ emitPushEvent(events, ctx, clientId, push, processed);
593
692
  }
594
693
  yield encodeResponseFrame(frame, plan.wireVersion);
595
694
  const details = pushResultDetailsFrame(frame);
@@ -598,12 +697,34 @@ async function* streamResponse(
598
697
  }
599
698
  }
600
699
 
601
- // Pull half (§4): subscriptions echoed in request order.
602
- const cursors: number[] = [];
603
- if (plan.pull !== undefined) {
604
- const summaries: PullSubscriptionSummary[] | undefined =
605
- events !== undefined ? [] : undefined;
606
- const limits = clampPullLimits(plan.pull);
700
+ const previous = plan.record;
701
+ const base = {
702
+ clientId,
703
+ actorId: ctx.actorId,
704
+ wireVersion: plan.wireVersion,
705
+ schemaVersion: schema.version,
706
+ };
707
+ const pull = plan.pull;
708
+ if (pull === undefined) {
709
+ // A push-only round keeps the registration, its states and the cursor;
710
+ // its record binds the actor (§1.5) and anchors the watermark rows
711
+ // (§6.3.2).
712
+ report.persist = () =>
713
+ ctx.storage.putClientRecord(
714
+ ctx.partition,
715
+ {
716
+ ...base,
717
+ cursor: previous?.cursor ?? -1,
718
+ updatedAtMs: clockOf(ctx)(),
719
+ catchingUp: previous?.catchingUp ?? [],
720
+ },
721
+ plan.roundFailure !== undefined
722
+ ? { keepRoundOutcome: true }
723
+ : undefined,
724
+ );
725
+ } else {
726
+ // Pull half (§4): unit sections in registration order, then one live
727
+ // section.
607
728
  const maxSeq = await ctx.storage.getMaxCommitSeq(ctx.partition);
608
729
  if (maxSeq < acceptedThrough)
609
730
  throw syncError(
@@ -611,145 +732,423 @@ async function* streamResponse(
611
732
  'storage returned a commit sequence older than the accepted push; disable query caching for sync storage',
612
733
  JSON.stringify({ acceptedThrough, storageMaxCommitSeq: maxSeq }),
613
734
  );
614
- const horizonSeq = await ctx.storage.getHorizonSeq(ctx.partition);
615
- const prepared = await prepareSections(
616
- ctx,
617
- schema,
618
- limits,
619
- plan.subscriptions,
620
- maxSeq,
621
- horizonSeq,
622
- plan.logEpoch,
623
- );
624
- for (const [index, subscription] of plan.subscriptions.entries()) {
625
- const trace: PullSectionTrace | undefined =
626
- summaries !== undefined ? { segments: [] } : undefined;
627
- const reads = prepared[index];
628
- if (reads === undefined) throw new Error('prepareSections lost a plan');
629
- const section = preparedSection(
630
- ctx,
631
- schema,
632
- limits,
633
- subscription,
634
- maxSeq,
635
- reads,
636
- trace,
637
- plan.logEpoch,
735
+ const { limits } = pull;
736
+ const units = pull.units;
737
+ if (units === undefined) {
738
+ // §4.1: no unit section, no COMMIT; PROGRESS frames are ignored.
739
+ yield encodeResponseFrame(
740
+ { type: 'LIVE_START', status: 'unregistered', reasonCode: '' },
741
+ plan.wireVersion,
638
742
  );
639
- let status: 'active' | 'revoked' | 'reset' = 'active';
640
- let bootstrap = false;
641
- let commits = 0;
642
- let changes = 0;
643
- let effectiveScopes: ScopeMap = {};
644
- let firstCommitSeq: number | undefined;
645
- let lastCommitSeq: number | undefined;
646
- let step = await section.next();
647
- while (!step.done) {
648
- const frame = step.value as ResponseFrame;
649
- if (summaries !== undefined) {
650
- if (frame.type === 'SUB_START') {
651
- status = frame.status;
652
- bootstrap = frame.bootstrap;
653
- effectiveScopes = frame.effectiveScopes;
654
- } else if (frame.type === 'COMMIT') {
655
- commits += 1;
656
- changes += frame.changes.length;
657
- firstCommitSeq ??= frame.commitSeq;
658
- lastCommitSeq = frame.commitSeq;
743
+ yield encodeResponseFrame(
744
+ { type: 'LIVE_END', throughSeq: -1, echoDigest: new Uint8Array() },
745
+ plan.wireVersion,
746
+ );
747
+ if (events !== undefined) {
748
+ emitEvent(events, {
749
+ type: 'pull.served',
750
+ atMs: clockOf(ctx)(),
751
+ partition: ctx.partition,
752
+ actorId: ctx.actorId,
753
+ clientId,
754
+ acceptedThrough,
755
+ storageMaxCommitSeq: maxSeq,
756
+ registrationTraveled: false,
757
+ units: [],
758
+ live: {
759
+ status: 'unregistered',
760
+ fromCursor: pull.header.cursor,
761
+ throughSeq: -1,
762
+ commits: 0,
763
+ changes: 0,
764
+ },
765
+ });
766
+ }
767
+ // §4.5: an `unregistered` answer writes only the round outcome; the
768
+ // stored record keeps its cursor, timestamp and states.
769
+ if (previous !== undefined) {
770
+ report.persist = () =>
771
+ ctx.storage.putClientRecord(
772
+ ctx.partition,
773
+ {
774
+ clientId,
775
+ actorId: previous.actorId,
776
+ wireVersion: previous.wireVersion,
777
+ cursor: previous.cursor,
778
+ updatedAtMs: previous.updatedAtMs,
779
+ lastRoundAtMs: clockOf(ctx)(),
780
+ ...(previous.schemaVersion !== undefined
781
+ ? { schemaVersion: previous.schemaVersion }
782
+ : {}),
783
+ catchingUp: previous.catchingUp,
784
+ },
785
+ plan.roundFailure !== undefined
786
+ ? { keepRoundOutcome: true }
787
+ : undefined,
788
+ );
789
+ }
790
+ } else {
791
+ const horizonSeq = await ctx.storage.getHorizonSeq(ctx.partition);
792
+ const R = pull.header.cursor;
793
+ const echo = echoDigest(
794
+ units.map(({ plan: unit }) => ({
795
+ id: unit.id,
796
+ status: unit.status,
797
+ fenced: unit.fenced,
798
+ })),
799
+ );
800
+ // §4.4 rule 1: every unit gets a section when the list traveled or
801
+ // the client holds another echo.
802
+ const echoSections =
803
+ pull.registration !== undefined ||
804
+ !sameBytes(pull.header.echoDigest, echo);
805
+ const liveUnits = units.some(
806
+ (unit) =>
807
+ unit.progress === undefined && unit.plan.status === 'active',
808
+ );
809
+ // §4.6 replica reset: a live unit with R outside [horizon, max].
810
+ let liveReset = liveUnits && (R < horizonSeq || R > maxSeq);
811
+ // Per unit: its section kind and its scan-set bound (§4.5).
812
+ type UnitState =
813
+ | { kind: 'revoked' }
814
+ | { kind: 'reset' }
815
+ | { kind: 'live' }
816
+ | { kind: 'post'; cursor: number }
817
+ | {
818
+ kind: 'bootstrap';
819
+ pin: number;
820
+ frames: ResponseFrame[];
821
+ token: string | undefined;
822
+ };
823
+ const states: UnitState[] = units.map(({ plan: unit, progress }) => {
824
+ if (unit.status === 'revoked') return { kind: 'revoked' };
825
+ if (progress === undefined) return { kind: 'live' };
826
+ // §4.7: a token, cursor -1 or a cursor from the future bootstraps.
827
+ if (
828
+ progress.bootstrapState === undefined &&
829
+ progress.cursor >= 0 &&
830
+ progress.cursor <= maxSeq
831
+ ) {
832
+ return progress.cursor < horizonSeq
833
+ ? { kind: 'reset' }
834
+ : { kind: 'post', cursor: progress.cursor };
835
+ }
836
+ // Replaced by the section the bootstrap below produces.
837
+ return { kind: 'bootstrap', pin: -1, frames: [], token: '' };
838
+ });
839
+ const traces = units.map((): PullSectionTrace | undefined =>
840
+ events !== undefined ? { segments: [] } : undefined,
841
+ );
842
+ // Bootstrap sections run before the live read: a bootstrap that
843
+ // completes in this response enters the scan set at its pin (§4.5).
844
+ // A window of units runs its pre-frame reads together, so a
845
+ // batching storage answers them in one statement per table. A unit
846
+ // reads ahead the first page of at most `maxSnapshotPages` tables,
847
+ // and a window holds at most 100,000 first-page rows, so read memory
848
+ // follows the configured limits, never the unit count.
849
+ const bootstrapping = states.flatMap((state, index) =>
850
+ state.kind === 'bootstrap' ? [index] : [],
851
+ );
852
+ const firstPages = Math.max(
853
+ 1,
854
+ Math.floor(100_000 / (limits.limitSnapshotRows + 1)),
855
+ );
856
+ for (let next = 0; next < bootstrapping.length;) {
857
+ const window: number[] = [];
858
+ let pages = 0;
859
+ while (next < bootstrapping.length) {
860
+ const index = bootstrapping[next]!;
861
+ const reads = Math.min(
862
+ limits.maxSnapshotPages,
863
+ units[index]!.plan.pairs.size,
864
+ );
865
+ if (window.length > 0 && pages + reads > firstPages) break;
866
+ window.push(index);
867
+ pages += reads;
868
+ next += 1;
869
+ }
870
+ const batch = window.map((index) => ({
871
+ index,
872
+ plan: planBootstrap(
873
+ ctx,
874
+ schema,
875
+ limits,
876
+ units[index]!.plan,
877
+ units[index]!.progress?.bootstrapState,
878
+ maxSeq,
879
+ horizonSeq,
880
+ plan.logEpoch,
881
+ ),
882
+ }));
883
+ for (const { index, plan: bootstrap } of batch) {
884
+ const frames: ResponseFrame[] = [];
885
+ const segments = bootstrapSegments(
886
+ ctx,
887
+ schema,
888
+ limits,
889
+ bootstrap,
890
+ traces[index],
891
+ plan.logEpoch,
892
+ );
893
+ let step = await segments.next();
894
+ while (!step.done) {
895
+ frames.push(step.value);
896
+ step = await segments.next();
659
897
  }
898
+ states[index] = {
899
+ kind: 'bootstrap',
900
+ pin: bootstrap.pin,
901
+ frames,
902
+ token: step.value,
903
+ };
904
+ }
905
+ }
906
+ const bound = (state: UnitState): number | undefined =>
907
+ state.kind === 'live'
908
+ ? R
909
+ : state.kind === 'post'
910
+ ? state.cursor
911
+ : state.kind === 'bootstrap' && state.token === undefined
912
+ ? state.pin
913
+ : undefined;
914
+ // §4.5 order of work: read and buffer the live section, then recheck
915
+ // the horizon. A bound below it leaves the scan set (a live unit's
916
+ // resets the live section), and the section is read again.
917
+ let live: LiveWindow | undefined;
918
+ for (;;) {
919
+ const scan = units.flatMap(({ plan: unit }, index) => {
920
+ const afterSeq = bound(states[index]!);
921
+ return afterSeq === undefined
922
+ ? []
923
+ : [{ scopes: unit.scopes, afterSeq, tables: unit.pairs }];
924
+ });
925
+ if (liveReset || scan.length === 0) break;
926
+ live = await ctx.storage.readLiveWindow(ctx.partition, {
927
+ units: scan,
928
+ throughSeq: maxSeq,
929
+ limitChanges: limits.limitCommits,
930
+ });
931
+ const recheck = await ctx.storage.getHorizonSeq(ctx.partition);
932
+ let expired = false;
933
+ for (const [index, state] of states.entries()) {
934
+ const afterSeq = bound(state);
935
+ if (afterSeq === undefined || afterSeq >= recheck) continue;
936
+ expired = true;
937
+ if (state.kind === 'live') liveReset = true;
938
+ else states[index] = { kind: 'reset' };
660
939
  }
661
- yield encodeResponseFrame(frame, plan.wireVersion);
662
- step = await section.next();
940
+ if (!expired) break;
941
+ live = undefined;
663
942
  }
664
- if (step.value.active) cursors.push(step.value.nextCursor);
665
- if (summaries !== undefined && trace !== undefined) {
943
+ const T = liveReset ? -1 : (live?.throughSeq ?? maxSeq);
944
+
945
+ const summaries: PullUnitSummary[] = [];
946
+ for (const [index, { plan: unit, progress }] of units.entries()) {
947
+ const state = states[index]!;
948
+ const requestCursor = progress?.cursor ?? R;
949
+ const section =
950
+ state.kind === 'revoked' ||
951
+ state.kind === 'reset' ||
952
+ state.kind === 'bootstrap' ||
953
+ echoSections;
954
+ if (section) {
955
+ yield encodeResponseFrame(
956
+ state.kind === 'revoked'
957
+ ? {
958
+ type: 'SUB_START',
959
+ id: unit.id,
960
+ status: 'revoked',
961
+ reasonCode: 'sync.scope_revoked',
962
+ bootstrap: false,
963
+ fenced: [],
964
+ }
965
+ : state.kind === 'reset'
966
+ ? {
967
+ type: 'SUB_START',
968
+ id: unit.id,
969
+ status: 'reset',
970
+ reasonCode: 'sync.cursor_expired',
971
+ bootstrap: false,
972
+ fenced: [],
973
+ }
974
+ : {
975
+ type: 'SUB_START',
976
+ id: unit.id,
977
+ status: 'active',
978
+ reasonCode: '',
979
+ bootstrap: state.kind === 'bootstrap',
980
+ fenced: [...unit.fenced],
981
+ },
982
+ plan.wireVersion,
983
+ );
984
+ if (state.kind === 'bootstrap') {
985
+ for (const frame of state.frames) {
986
+ yield encodeResponseFrame(frame, plan.wireVersion);
987
+ }
988
+ }
989
+ yield encodeResponseFrame(
990
+ state.kind === 'bootstrap'
991
+ ? {
992
+ type: 'SUB_END',
993
+ nextCursor: state.pin,
994
+ ...(state.token !== undefined
995
+ ? { bootstrapState: state.token }
996
+ : {}),
997
+ }
998
+ : { type: 'SUB_END', nextCursor: requestCursor },
999
+ plan.wireVersion,
1000
+ );
1001
+ }
666
1002
  summaries.push({
667
- id: subscription.frame.id,
668
- table: subscription.frame.table,
669
- status,
1003
+ id: unit.id,
1004
+ scopes: unit.scopes,
1005
+ status:
1006
+ state.kind === 'revoked' || state.kind === 'reset'
1007
+ ? state.kind
1008
+ : 'active',
670
1009
  mode:
671
- status !== 'active'
1010
+ state.kind === 'revoked' || state.kind === 'reset'
672
1011
  ? 'none'
673
- : bootstrap
674
- ? 'bootstrap'
675
- : 'incremental',
676
- requestedScopes: subscription.frame.scopes,
677
- effectiveScopes,
678
- ...(firstCommitSeq !== undefined && lastCommitSeq !== undefined
679
- ? { firstCommitSeq, lastCommitSeq }
680
- : {}),
681
- fromCursor: subscription.frame.cursor,
682
- nextCursor: step.value.nextCursor,
683
- commits,
684
- changes,
685
- segments: trace.segments,
1012
+ : state.kind === 'post'
1013
+ ? 'catching-up'
1014
+ : state.kind,
1015
+ section,
1016
+ fenced: unit.fenced,
1017
+ fromCursor: requestCursor,
1018
+ segments: traces[index]?.segments ?? [],
1019
+ });
1020
+ }
1021
+ yield encodeResponseFrame(
1022
+ liveReset
1023
+ ? {
1024
+ type: 'LIVE_START',
1025
+ status: 'reset',
1026
+ reasonCode: 'sync.cursor_expired',
1027
+ }
1028
+ : { type: 'LIVE_START', status: 'active', reasonCode: '' },
1029
+ plan.wireVersion,
1030
+ );
1031
+ let changes = 0;
1032
+ for (const commit of live?.commits ?? []) {
1033
+ changes += commit.changes.length;
1034
+ yield encodeResponseFrame(
1035
+ commitFrame(commit, currentSchema, schema),
1036
+ plan.wireVersion,
1037
+ );
1038
+ }
1039
+ yield encodeResponseFrame(
1040
+ { type: 'LIVE_END', throughSeq: T, echoDigest: echo },
1041
+ plan.wireVersion,
1042
+ );
1043
+ if (events !== undefined) {
1044
+ const commits = live?.commits ?? [];
1045
+ emitEvent(events, {
1046
+ type: 'pull.served',
1047
+ atMs: clockOf(ctx)(),
1048
+ partition: ctx.partition,
1049
+ actorId: ctx.actorId,
1050
+ clientId,
1051
+ acceptedThrough,
1052
+ storageMaxCommitSeq: maxSeq,
1053
+ registrationTraveled: pull.registration !== undefined,
1054
+ units: summaries,
1055
+ live: {
1056
+ status: liveReset ? 'reset' : 'active',
1057
+ fromCursor: R,
1058
+ throughSeq: T,
1059
+ commits: commits.length,
1060
+ changes,
1061
+ ...(commits.length > 0
1062
+ ? {
1063
+ firstCommitSeq: commits[0]!.commitSeq,
1064
+ lastCommitSeq: commits.at(-1)!.commitSeq,
1065
+ }
1066
+ : {}),
1067
+ },
686
1068
  });
687
1069
  }
688
- }
689
- if (events !== undefined && summaries !== undefined) {
690
- emitEvent(events, {
691
- type: 'pull.served',
692
- atMs: clockOf(ctx)(),
693
- partition: ctx.partition,
694
- actorId: ctx.actorId,
695
- clientId: plan.header.clientId,
696
- acceptedThrough,
697
- storageMaxCommitSeq: maxSeq,
698
- subscriptions: summaries,
699
- });
700
- }
701
- }
702
1070
 
703
- // §4.5/§8.1: persist the cursor watermark and the request's
704
- // subscription list per (partition, clientId).
705
- const previous = await ctx.storage.getClientRecord(
706
- ctx.partition,
707
- plan.header.clientId,
708
- );
709
- const subscriptions: ClientSubscription[] =
710
- plan.pull !== undefined
711
- ? plan.subscriptions.map((s) => ({
712
- id: s.frame.id,
713
- table: s.frame.table,
714
- scopes: s.frame.scopes,
715
- schemaVersion: schema.version,
716
- }))
717
- : [...(previous?.subscriptions ?? [])];
718
- const cursor =
719
- cursors.length > 0 ? Math.min(...cursors) : (previous?.cursor ?? -1);
720
- await ctx.storage.putClientRecord(
721
- ctx.partition,
722
- {
723
- clientId: plan.header.clientId,
724
- actorId: ctx.actorId,
725
- wireVersion: plan.wireVersion,
726
- cursor,
727
- updatedAtMs: clockOf(ctx)(),
728
- subscriptions,
729
- },
730
- // §4.5: a round that carried a `ROUND_FAILURE` report completes without
731
- // clearing the reported code and streak; the next request without the
732
- // frame clears them as a plain completed round does.
733
- plan.roundFailure !== undefined ? { keepRoundOutcome: true } : undefined,
734
- );
735
- if (
736
- ctx.realtime?.notifySubscriptions !== undefined &&
737
- JSON.stringify(
738
- (previous?.subscriptions ?? []).map((s) => [s.id, s.table, s.scopes]),
739
- ) !== JSON.stringify(subscriptions.map((s) => [s.id, s.table, s.scopes]))
740
- ) {
741
- await ctx.realtime.notifySubscriptions(
742
- ctx.partition,
743
- plan.header.clientId,
744
- );
1071
+ // §4.5 join rule J and the record the round writes: the live units,
1072
+ // the catching-up ids with their cursors, and the record cursor.
1073
+ const joined = Math.max(R, T);
1074
+ let anyLive = false;
1075
+ const catchingUp: CatchingUpUnit[] = [];
1076
+ for (const [index, { plan: unit }] of units.entries()) {
1077
+ const state = states[index]!;
1078
+ const catching = (cursor: number): void => {
1079
+ catchingUp.push({ id: unit.id, cursor });
1080
+ };
1081
+ if (state.kind === 'live') {
1082
+ if (liveReset) catching(-1);
1083
+ else anyLive = true;
1084
+ } else if (state.kind === 'revoked' || state.kind === 'reset') {
1085
+ catching(-1);
1086
+ } else if (state.kind === 'bootstrap' && state.token !== undefined) {
1087
+ catching(state.pin);
1088
+ } else {
1089
+ // Post-bootstrap, or a bootstrap completed here at its pin.
1090
+ const cursor = state.kind === 'post' ? state.cursor : state.pin;
1091
+ if (liveReset) catching(cursor);
1092
+ else if (Math.max(cursor, T) >= joined) anyLive = true;
1093
+ else catching(Math.max(cursor, T));
1094
+ }
1095
+ }
1096
+ const held = [
1097
+ ...(anyLive ? [joined] : []),
1098
+ ...catchingUp.map((unit) => unit.cursor).filter((c) => c >= 0),
1099
+ ];
1100
+ const liveIds = (
1101
+ listed: readonly UnitScopes[],
1102
+ catching: readonly CatchingUpUnit[],
1103
+ ): string =>
1104
+ JSON.stringify(
1105
+ listed
1106
+ .map((scopes) => unitId(scopes))
1107
+ .filter((id) => !catching.some((unit) => unit.id === id)),
1108
+ );
1109
+ const next: ClientRecord = {
1110
+ ...base,
1111
+ cursor: held.length === 0 ? -1 : Math.min(...held),
1112
+ updatedAtMs: clockOf(ctx)(),
1113
+ ...(pull.registration !== undefined
1114
+ ? { registration: pull.registration }
1115
+ : {}),
1116
+ catchingUp,
1117
+ };
1118
+ report.persist = async () => {
1119
+ await ctx.storage.putClientRecord(
1120
+ ctx.partition,
1121
+ next,
1122
+ // §4.5: a round that carried a `ROUND_FAILURE` report completes
1123
+ // without clearing the reported code and streak.
1124
+ plan.roundFailure !== undefined
1125
+ ? { keepRoundOutcome: true }
1126
+ : undefined,
1127
+ );
1128
+ // §8.1: a traveled list or a changed live set re-registers the
1129
+ // client's sockets on this hub.
1130
+ if (
1131
+ ctx.realtime?.notifySubscriptions !== undefined &&
1132
+ (pull.registration !== undefined ||
1133
+ liveIds(
1134
+ previous?.registration?.units ?? [],
1135
+ previous?.catchingUp ?? [],
1136
+ ) !==
1137
+ liveIds(
1138
+ units.map(({ plan: unit }) => unit.scopes),
1139
+ catchingUp,
1140
+ ))
1141
+ ) {
1142
+ await ctx.realtime.notifySubscriptions(ctx.partition, clientId);
1143
+ }
1144
+ };
1145
+ }
745
1146
  }
746
1147
  } catch (error) {
747
1148
  if (error instanceof SyncError) {
748
- if (report !== undefined) {
749
- report.outcome = 'error';
750
- report.errorCode = error.code;
751
- }
752
- await recordRoundFailure(ctx, plan.header.clientId, error);
1149
+ report.outcome = 'error';
1150
+ report.errorCode = error.code;
1151
+ await recordRoundFailure(ctx, clientId, error);
753
1152
  // §1.6: in-band ERROR, then END, nothing else.
754
1153
  yield encodeResponseFrame(
755
1154
  {
@@ -817,7 +1216,7 @@ export async function createSyncResponseStream(
817
1216
  errorCode: error instanceof SyncError ? error.code : 'internal',
818
1217
  pushCommits: 0,
819
1218
  pulled: false,
820
- subscriptions: 0,
1219
+ units: 0,
821
1220
  });
822
1221
  await recordRoundFailure(ctx, clientId, error);
823
1222
  throw error;
@@ -827,11 +1226,8 @@ export async function createSyncResponseStream(
827
1226
  /** The `REQ_HEADER` clientId of a request that failed before planning. */
828
1227
  function requestClientId(bytes: Uint8Array): string | undefined {
829
1228
  try {
830
- const message = decodeMessage(bytes);
831
- const header = message.frames[0];
832
- return message.msgKind === 'request' && header?.type === 'REQ_HEADER'
833
- ? header.clientId
834
- : undefined;
1229
+ const header = decodeRequest(bytes).frames[0];
1230
+ return header?.type === 'REQ_HEADER' ? header.clientId : undefined;
835
1231
  } catch {
836
1232
  return undefined;
837
1233
  }
@@ -897,11 +1293,7 @@ async function createStreamCore(
897
1293
  ): Promise<AsyncIterable<Uint8Array>> {
898
1294
  let request: RequestMessage;
899
1295
  try {
900
- const message = decodeMessage(bytes);
901
- if (message.msgKind !== 'request') {
902
- throw syncError('sync.invalid_request', 'expected a request message');
903
- }
904
- request = message;
1296
+ request = decodeRequest(bytes);
905
1297
  } catch (error) {
906
1298
  if (error instanceof DecodeError) {
907
1299
  throw syncError(error.code, error.message);
@@ -982,6 +1374,7 @@ async function createStreamCore(
982
1374
  );
983
1375
  if (afterRefusal !== undefined) throw serveNotReadyError(afterRefusal);
984
1376
  if (changed !== undefined) throw serveNotReadyError(changed);
1377
+ await report.persist?.();
985
1378
  for (const chunk of buffered) yield chunk;
986
1379
  };
987
1380
  if (events === undefined) {
@@ -1032,7 +1425,7 @@ async function* instrumentedStream(
1032
1425
  : {}),
1033
1426
  pushCommits: plan.pushes.length,
1034
1427
  pulled: plan.pull !== undefined,
1035
- subscriptions: plan.subscriptions.length,
1428
+ units: plan.pull?.units?.length ?? 0,
1036
1429
  });
1037
1430
  };
1038
1431
  try {