@syncular/server 0.95.0 → 0.96.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/pull.js CHANGED
@@ -264,9 +264,9 @@ async function readTableStart(ctx, schema, limits, unit, pair, startRowCursor, i
264
264
  return { firstPage: await scan };
265
265
  }
266
266
  // §4.7: a sqlite-lane table pins at the newest commit carrying all of the
267
- // unit's values (never below the horizon, never above maxCommitSeq), so a
268
- // stored image stays the reuse key's match until this scope changes
269
- // (§5.3). The server computes the pin; a client token never supplies it.
267
+ // unit's values (never below the table's horizon, never above
268
+ // maxCommitSeq), so a stored image stays the reuse key's match until this
269
+ // scope changes (§5.3). The server computes the pin; a client token never supplies it.
270
270
  const [firstPage, latest] = await Promise.all([
271
271
  scan,
272
272
  ctx.storage.latestScopedChangeSeq(ctx.partition, {
@@ -474,7 +474,7 @@ async function* tableSegments(ctx, schema, limits, pair, pin, startRowCursor, st
474
474
  }
475
475
  else {
476
476
  // The page's put runs while the next page is scanned; the caller keeps
477
- // `maxConcurrentSegmentPuts` in flight and emits the frames in order.
477
+ // six puts in flight and emits the frames in order.
478
478
  trace?.segments.push({
479
479
  mediaType: 'rows',
480
480
  delivery: 'ref',
@@ -511,13 +511,14 @@ async function* tableSegments(ctx, schema, limits, pair, pin, startRowCursor, st
511
511
  * is awaited, so a storage that batches concurrent page reads (PostgreSQL,
512
512
  * D1) answers them in one statement per table.
513
513
  */
514
- export function planBootstrap(ctx, schema, limits, unit, bootstrapState, maxSeq, horizonSeq, logEpoch, keptCursor = 0) {
514
+ export function planBootstrap(ctx, schema, limits, unit, bootstrapState, maxSeq, horizon, logEpoch, keptCursor = 0) {
515
515
  // §4.7: resume at the token's pin unless the token is unusable, or the pin
516
- // fell behind the horizon or a restricted bootstrap's kept cursor; then
517
- // restart from a fresh pin.
516
+ // fell behind the horizon, the table horizon of a bootstrap table, or a
517
+ // restricted bootstrap's kept cursor; then restart from a fresh pin.
518
518
  const token = parseBootstrapToken(bootstrapState, unit.tables, maxSeq);
519
519
  const resume = token !== undefined &&
520
- token.asOfCommitSeq >= Math.max(horizonSeq, keptCursor)
520
+ token.asOfCommitSeq >=
521
+ Math.max(horizon.seq, keptCursor, ...unit.tables.map((table) => horizon.tables.get(table.name) ?? -1))
521
522
  ? token
522
523
  : undefined;
523
524
  const tableIndex = resume?.tableIndex ?? 0;
@@ -529,7 +530,7 @@ export function planBootstrap(ctx, schema, limits, unit, bootstrapState, maxSeq,
529
530
  const effective = unit.pairs.get(table.name);
530
531
  if (effective === undefined)
531
532
  continue;
532
- const start = readTableStart(ctx, schema, limits, unit, { table, effective }, index === tableIndex ? rowCursor : null, index === tableIndex && image, maxSeq, horizonSeq, logEpoch);
533
+ const start = readTableStart(ctx, schema, limits, unit, { table, effective }, index === tableIndex ? rowCursor : null, index === tableIndex && image, maxSeq, Math.max(horizon.seq, horizon.tables.get(table.name) ?? -1), logEpoch);
533
534
  // A section that stops early never awaits the later starts.
534
535
  start.catch(() => undefined);
535
536
  starts.set(index, start);
@@ -649,9 +650,9 @@ export async function publishSqliteImage(input) {
649
650
  accept: ACCEPT_SQLITE,
650
651
  };
651
652
  const maxSeq = await config.storage.getMaxCommitSeq(partition);
652
- const horizonSeq = await config.storage.getHorizonSeq(partition);
653
+ const horizons = await config.storage.getHorizons(partition);
653
654
  const trace = { segments: [] };
654
- const plan = planBootstrap(ctx, schema, limits, unit, undefined, maxSeq, horizonSeq, logEpoch);
655
+ const plan = planBootstrap(ctx, schema, limits, unit, undefined, maxSeq, horizons, logEpoch);
655
656
  const refs = [];
656
657
  for await (const frame of bootstrapSegments(ctx, schema, limits, plan, trace, logEpoch)) {
657
658
  if (frame.type === 'PENDING_REF')
package/dist/push.js CHANGED
@@ -92,20 +92,23 @@ async function resolveBlobPresence(blobCtx, blobIds) {
92
92
  }));
93
93
  }
94
94
  /**
95
- * §6.7: run the table's write-validation hook, if configured, on the row
96
- * that WILL persist (post scope-strip, post CRDT-merge — the values the
97
- * store receives). Returns a terminating outcome iff the validator rejects
98
- * (its `ValidationRejection` code, or `sync.constraint_violation` for a
99
- * non-`ValidationRejection` throw), else `undefined` (accept / no hook).
100
- * A no-op for tables with no validator — the `undefined` short-circuit
101
- * keeps the feature zero-cost when off.
95
+ * §6.7: run the table's row hook, if configured, on the row that will persist
96
+ * (post scope-strip, post CRDT-merge). With `present` (an accepted insert or
97
+ * update of a pushed commit or a registered command) the hook's returned
98
+ * values for server-owned columns land in `values` and are marked present, so
99
+ * their column versions advance; elsewhere (a delete, a rescope, a §6.11
100
+ * cascade) the server ignores them. Returns a terminating outcome iff the
101
+ * hook fails: a `ValidationRejection` keeps its host code, and any other
102
+ * throw, a returned column that is not server-owned, a value the column's
103
+ * type refuses or a changed scope column on an update is
104
+ * `sync.constraint_violation`.
102
105
  */
103
- async function runValidator(validators, table, op, rowId, values, storedValues, opIndex, tx, partition, actorId, context) {
106
+ async function runValidator(validators, tx, schema, table, op, rowId, values, storedValues, opIndex, partition, actorId, context, present) {
104
107
  const validator = validators?.[table.name];
105
108
  if (validator === undefined)
106
109
  return undefined;
107
110
  try {
108
- await validator({
111
+ const output = await validator({
109
112
  op,
110
113
  table: table.name,
111
114
  rowId,
@@ -115,61 +118,26 @@ async function runValidator(validators, table, op, rowId, values, storedValues,
115
118
  stored: storedValues !== undefined
116
119
  ? toValidateRow(table.columns, storedValues)
117
120
  : undefined,
118
- }, {
119
- actorId,
120
- partition,
121
- ...(context !== undefined ? { context } : {}),
122
- queryAuthoritative: (query) => transactionQuery(tx, query),
123
- });
124
- }
125
- catch (error) {
126
- if (error instanceof ValidationRejection) {
127
- return errorRecord(opIndex, error.code, error.message, false, error.details);
128
- }
129
- // §6.7: a non-ValidationRejection throw is still a rejection, mapped to
130
- // the generic server-side constraint code (§10.2) — the validator's
131
- // failure never crashes the request or leaks its message as a code.
132
- return errorRecord(opIndex, 'sync.constraint_violation', 'write validator failed');
133
- }
134
- return undefined;
135
- }
136
- /**
137
- * §6.12: complete an accepted upsert with the table's server column hook.
138
- * The returned values land in `values` and are marked present, so their
139
- * column versions advance. A `ValidationRejection` keeps its host code; any
140
- * other failure (an undeclared key, a value the column's type refuses, a
141
- * changed scope column on an update) is `sync.constraint_violation`.
142
- */
143
- async function runServerColumns(hooks, tx, schema, table, rowId, values, storedValues, present, opIndex, partition, actorId, context) {
144
- const hook = hooks?.[table.name];
145
- if (hook === undefined)
146
- return undefined;
147
- try {
148
- const output = await hook({
149
- table: table.name,
150
- rowId,
151
- row: toValidateRow(table.columns, values),
152
- stored: storedValues !== undefined
153
- ? toValidateRow(table.columns, storedValues)
154
- : undefined,
155
121
  }, {
156
122
  actorId,
157
123
  partition,
158
124
  ...(context !== undefined ? { context } : {}),
159
125
  read: commitValidationReader(tx, schema),
160
126
  });
127
+ if (output === undefined || present === undefined || values === undefined)
128
+ return undefined;
161
129
  for (const [name, value] of Object.entries(output)) {
162
130
  const index = table.columnIndex.get(name);
163
131
  if (index === undefined ||
164
132
  !table.serverOwnedColumnIndices.includes(index)) {
165
- throw new Error('server column hook returned a column that is not server-owned');
133
+ throw new Error('write validator returned a column that is not server-owned');
166
134
  }
167
135
  // The column's own codec refuses a value of the wrong type.
168
136
  encodeRow([table.columns[index]], [value]);
169
137
  if (storedValues !== undefined &&
170
138
  table.scopePatterns.some((pattern) => pattern.columnIndex === index) &&
171
139
  value !== (storedValues[index] ?? null)) {
172
- throw new Error('server column hook changed a scope column on update');
140
+ throw new Error('write validator changed a scope column on update');
173
141
  }
174
142
  values[index] = value;
175
143
  present[index] = true;
@@ -179,7 +147,10 @@ async function runServerColumns(hooks, tx, schema, table, rowId, values, storedV
179
147
  if (error instanceof ValidationRejection) {
180
148
  return errorRecord(opIndex, error.code, error.message, false, error.details);
181
149
  }
182
- return errorRecord(opIndex, 'sync.constraint_violation', 'server column hook failed');
150
+ // §6.7: any other failure is still a rejection, mapped to the generic
151
+ // server-side constraint code (§10.2); the hook's failure never crashes
152
+ // the request or leaks its message.
153
+ return errorRecord(opIndex, 'sync.constraint_violation', 'write validator failed');
183
154
  }
184
155
  return undefined;
185
156
  }
@@ -225,7 +196,7 @@ async function mergeCrdtColumns(table, values, storedValues, present, opIndex, m
225
196
  }
226
197
  return { changed };
227
198
  }
228
- async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, serverColumns, partition, actorId, context,
199
+ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, actorId, context,
229
200
  /** §2.2: the partition's delete floor, raised by this commit's deletes. */
230
201
  deleteFloor) {
231
202
  const table = schema.tables.get(op.table);
@@ -293,10 +264,10 @@ deleteFloor) {
293
264
  if (!authorizeWrite(table, extracted.scopes, resolved, true)) {
294
265
  return errorRecord(opIndex, 'sync.forbidden', 'rescope denied by scope authorization of the new scopes (§3.4)');
295
266
  }
296
- const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, storedValues, opIndex, tx, partition, actorId, context);
267
+ const deleteReject = await runValidator(validators, tx, schema, table, 'delete', op.rowId, undefined, storedValues, opIndex, partition, actorId, context);
297
268
  if (deleteReject !== undefined)
298
269
  return deleteReject;
299
- const upsertReject = await runValidator(validators, table, 'upsert', op.rowId, values, storedValues, opIndex, tx, partition, actorId, context);
270
+ const upsertReject = await runValidator(validators, tx, schema, table, 'upsert', op.rowId, values, storedValues, opIndex, partition, actorId, context);
300
271
  if (upsertReject !== undefined)
301
272
  return upsertReject;
302
273
  const blobCheck = await checkAndRecordBlobs(tx, table, op.rowId, values, opIndex, blobCtx);
@@ -413,7 +384,7 @@ deleteFloor) {
413
384
  // stored = the row about to be removed). Only reached for an existing
414
385
  // row — an absent-row delete is an idempotent no-op above.
415
386
  const storedValues = decodeRow(table.columns, stored.payload);
416
- const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, storedValues, opIndex, tx, partition, actorId, context);
387
+ const deleteReject = await runValidator(validators, tx, schema, table, 'delete', op.rowId, undefined, storedValues, opIndex, partition, actorId, context);
417
388
  if (deleteReject !== undefined)
418
389
  return deleteReject;
419
390
  await tx.deleteRow(op.table, op.rowId);
@@ -460,7 +431,7 @@ deleteFloor) {
460
431
  catch (error) {
461
432
  return errorRecord(opIndex, 'sync.invalid_request', `row payload failed row-codec decode (§1.7): ${error instanceof Error ? error.message : String(error)}`);
462
433
  }
463
- // §6.12: the server discards a pushed value of a server-owned column, so an
434
+ // §6.7: the server discards a pushed value of a server-owned column, so an
464
435
  // older client that still writes one stays valid.
465
436
  for (const index of table.serverOwnedColumnIndices) {
466
437
  sparse[index] = stored === undefined ? null : undefined;
@@ -538,9 +509,11 @@ deleteFloor) {
538
509
  const mergeOutcome = await mergeCrdtColumns(table, values, storedValues, present, opIndex, crdtMergers);
539
510
  if ('kind' in mergeOutcome)
540
511
  return mergeOutcome;
541
- const serverReject = await runServerColumns(serverColumns, tx, schema, table, op.rowId, values, storedValues, present, opIndex, partition, actorId, context);
542
- if (serverReject !== undefined)
543
- return serverReject;
512
+ // §6.7: validate the merged row that will persist (for a crdt column the
513
+ // MERGED value, §5.10.3) and take its server-owned values.
514
+ const updateReject = await runValidator(validators, tx, schema, table, 'upsert', op.rowId, values, storedValues, opIndex, partition, actorId, context, present);
515
+ if (updateReject !== undefined)
516
+ return updateReject;
544
517
  const newVersion = stored.serverVersion + 1;
545
518
  const nextVersions = new Map();
546
519
  for (let i = 0; i < table.columns.length; i++) {
@@ -559,12 +532,6 @@ deleteFloor) {
559
532
  const blobCheck = await checkAndRecordBlobs(tx, table, op.rowId, values, opIndex, blobCtx);
560
533
  if (blobCheck !== undefined)
561
534
  return blobCheck;
562
- // §6.7: validate the merged row that will persist — for a crdt column
563
- // the validator sees the MERGED value (§5.10.3), the state the store
564
- // holds, not the raw pushed update.
565
- const updateReject = await runValidator(validators, table, 'upsert', op.rowId, values, storedValues, opIndex, tx, partition, actorId, context);
566
- if (updateReject !== undefined)
567
- return updateReject;
568
535
  const columnVersions = encodeColumnVersions(nextVersions);
569
536
  const newRow = {
570
537
  rowId: op.rowId,
@@ -656,14 +623,17 @@ deleteFloor) {
656
623
  const insertMerge = await mergeCrdtColumns(table, values, undefined, present, opIndex, crdtMergers);
657
624
  if ('kind' in insertMerge)
658
625
  return insertMerge;
659
- const serverReject = await runServerColumns(serverColumns, tx, schema, table, op.rowId, values, undefined, present, opIndex, partition, actorId, context);
660
- if (serverReject !== undefined)
661
- return serverReject;
662
- // §6.12: the stored scopes and the change-scope index take the hook's
626
+ // §6.7: validate the insert row (stored = undefined, so a validator can
627
+ // distinguish create from update; crdt columns are already merged against
628
+ // the empty document) and take its server-owned values.
629
+ const insertReject = await runValidator(validators, tx, schema, table, 'upsert', op.rowId, values, undefined, opIndex, partition, actorId, context, present);
630
+ if (insertReject !== undefined)
631
+ return insertReject;
632
+ // §6.7: the stored scopes and the change-scope index take the validator's
663
633
  // values, so the row reaches a server-set scope's units in this commit.
664
634
  const scoped = storedScopesForRow(table, values);
665
635
  if ('missing' in scoped) {
666
- return errorRecord(opIndex, 'sync.constraint_violation', 'server column hook failed');
636
+ return errorRecord(opIndex, 'sync.constraint_violation', 'write validator failed');
667
637
  }
668
638
  // The stored payload is the full-row codec (§2.4); every column is
669
639
  // present on an insert.
@@ -672,12 +642,6 @@ deleteFloor) {
672
642
  const blobCheck = await checkAndRecordBlobs(tx, table, op.rowId, values, opIndex, blobCtx);
673
643
  if (blobCheck !== undefined)
674
644
  return blobCheck;
675
- // §6.7: validate the insert row (stored = undefined, so a validator can
676
- // distinguish create from update); crdt columns are already merged
677
- // against the empty document.
678
- const insertReject = await runValidator(validators, table, 'upsert', op.rowId, values, undefined, opIndex, tx, partition, actorId, context);
679
- if (insertReject !== undefined)
680
- return insertReject;
681
645
  // §2.2, §6.2: every insert starts one above the delete floor, over a
682
646
  // tombstone or not; without a column-versions blob every column sits at
683
647
  // that version.
@@ -1085,7 +1049,7 @@ async function enforceReferences(tx, schema, resolved, staged, clientOpCount, ca
1085
1049
  const syntheticIndex = clientOpCount + originByIndex.length;
1086
1050
  const storedValues = decodeRow(child.columns, childRow.payload);
1087
1051
  if (reference.onDelete === 'CASCADE') {
1088
- const reject = await runValidator(validators, child, 'delete', childRow.rowId, undefined, storedValues, item.originOpIndex, tx, partition, actorId, context);
1052
+ const reject = await runValidator(validators, tx, schema, child, 'delete', childRow.rowId, undefined, storedValues, item.originOpIndex, partition, actorId, context);
1089
1053
  if (reject !== undefined) {
1090
1054
  return { kind: 'terminate', record: reject.record };
1091
1055
  }
@@ -1110,7 +1074,7 @@ async function enforceReferences(tx, schema, resolved, staged, clientOpCount, ca
1110
1074
  else {
1111
1075
  const values = [...storedValues];
1112
1076
  values[reference.columnIndex] = null;
1113
- const reject = await runValidator(validators, child, 'upsert', childRow.rowId, values, storedValues, item.originOpIndex, tx, partition, actorId, context);
1077
+ const reject = await runValidator(validators, tx, schema, child, 'upsert', childRow.rowId, values, storedValues, item.originOpIndex, partition, actorId, context);
1114
1078
  if (reject !== undefined) {
1115
1079
  return { kind: 'terminate', record: reject.record };
1116
1080
  }
@@ -1468,7 +1432,7 @@ async function applyPushCommits(ctx, schema, resolved, clientId, commits, wireSc
1468
1432
  const op = operations[opIndex];
1469
1433
  if (op === undefined)
1470
1434
  continue;
1471
- const outcome = await applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, ctx.serverColumns, partition, ctx.actorId, ctx.context, deleteFloor);
1435
+ const outcome = await applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, ctx.actorId, ctx.context, deleteFloor);
1472
1436
  if (outcome.kind === 'terminate') {
1473
1437
  terminated = outcome.record;
1474
1438
  break;
@@ -304,9 +304,11 @@ export declare class RealtimeHub {
304
304
  notifySubscriptions(partition: string, clientId: string): Promise<void>;
305
305
  /**
306
306
  * Host-initiated, fail-closed registration refresh (§8.7). A host calls this
307
- * after it changes an actor's membership or connection state, so the
308
- * partition's connected sessions stop using grants the host already revoked
309
- * without waiting for the client to happen to run a round.
307
+ * after it changes an actor's grants, whether they shrank or grew. Each
308
+ * matching session re-resolves its registrations, so it stops using grants
309
+ * the host already revoked without waiting for its client to run a round,
310
+ * and then receives one `scopes` event, so its client's app runs its
311
+ * discovery and registers units it did not know.
310
312
  *
311
313
  * This differs deliberately from the round-end refresh
312
314
  * (`RealtimeSession.refreshRegistrations`), which keeps the previous
@@ -316,14 +318,6 @@ export declare class RealtimeHub {
316
318
  * on until the next round. Presence is reconciled exactly as at round end.
317
319
  */
318
320
  refreshScopes(partition: string, actorId?: string): Promise<void>;
319
- /**
320
- * Host announcement (§8.7): tell the connected sessions of `actorIds` on
321
- * the partition that their grant widened, so each client's app runs its
322
- * discovery and registers the units it did not know. Sends one `scopes`
323
- * event per session and changes no registration; a narrowed grant needs
324
- * `refreshScopes`.
325
- */
326
- announceScopes(partition: string, actorIds: readonly string[]): void;
327
321
  /** Broadcast a wake-up (host-initiated resync, schema rollover, §8.3). */
328
322
  wake(partition: string, reason: WakeReason): void;
329
323
  /** Wake every session on every partition (fanout listener gap, §8.3). */
package/dist/realtime.js CHANGED
@@ -531,8 +531,8 @@ export class RealtimeSession {
531
531
  step = await iterator.next();
532
532
  }
533
533
  catch (error) {
534
- // The generator builds the whole response (and runs the read-verify
535
- // refusal) on its first `next()`, before any chunk is yielded.
534
+ // The first `next()` waits until the response is built (and the
535
+ // read-verify refusal ran) or its first KEEPALIVE is due (§1.6).
536
536
  // Nothing has escaped, so a failure there is delivered as the same
537
537
  // §8.4 ERROR frame HTTP returns rather than a silent close; a
538
538
  // non-catalog exception is reported and answers
@@ -1203,9 +1203,11 @@ export class RealtimeHub {
1203
1203
  }
1204
1204
  /**
1205
1205
  * Host-initiated, fail-closed registration refresh (§8.7). A host calls this
1206
- * after it changes an actor's membership or connection state, so the
1207
- * partition's connected sessions stop using grants the host already revoked
1208
- * without waiting for the client to happen to run a round.
1206
+ * after it changes an actor's grants, whether they shrank or grew. Each
1207
+ * matching session re-resolves its registrations, so it stops using grants
1208
+ * the host already revoked without waiting for its client to run a round,
1209
+ * and then receives one `scopes` event, so its client's app runs its
1210
+ * discovery and registers units it did not know.
1209
1211
  *
1210
1212
  * This differs deliberately from the round-end refresh
1211
1213
  * (`RealtimeSession.refreshRegistrations`), which keeps the previous
@@ -1220,25 +1222,10 @@ export class RealtimeHub {
1220
1222
  continue;
1221
1223
  if (actorId !== undefined && session.actorId !== actorId)
1222
1224
  continue;
1223
- // Fail closed (see the doc above): an unreadable client record drops
1224
- // every grant on the connection. The session's generation guard keeps
1225
- // this revocation from being overwritten by a slower round-end reload.
1225
+ // The session's generation guard keeps this revocation from being
1226
+ // overwritten by a slower round-end reload.
1226
1227
  await session.refreshRegistrations(true);
1227
- }
1228
- }
1229
- /**
1230
- * Host announcement (§8.7): tell the connected sessions of `actorIds` on
1231
- * the partition that their grant widened, so each client's app runs its
1232
- * discovery and registers the units it did not know. Sends one `scopes`
1233
- * event per session and changes no registration; a narrowed grant needs
1234
- * `refreshScopes`.
1235
- */
1236
- announceScopes(partition, actorIds) {
1237
- for (const session of this.#sessions) {
1238
- if (session.partition !== partition)
1239
- continue;
1240
- if (actorIds.includes(session.actorId))
1241
- session.sendScopes();
1228
+ session.sendScopes();
1242
1229
  }
1243
1230
  }
1244
1231
  /** Broadcast a wake-up (host-initiated resync, schema rollover, §8.3). */
@@ -346,8 +346,10 @@ export declare function changedScopePatterns(schema: CompiledSchema, storedJson:
346
346
  export declare function assertStoredScopePatterns(schema: CompiledSchema, storedJson: string | null | undefined): boolean;
347
347
  /**
348
348
  * §3.1 re-key, before the row walk: drop the re-keyed tables' row scope index
349
- * entries and tombstones, and raise every partition's horizon past the
350
- * changes logged under the previous patterns. Empty when nothing re-keys.
349
+ * entries and tombstones. The re-key takes a commit sequence number of its
350
+ * own in every partition and records it as each re-keyed table's horizon
351
+ * (§4.6), past the changes logged under the previous patterns. Empty when
352
+ * nothing re-keys.
351
353
  */
352
354
  export declare function rekeyCleanupSql(tables: readonly string[]): string[];
353
355
  /**
@@ -816,8 +816,10 @@ export function assertStoredScopePatterns(schema, storedJson) {
816
816
  }
817
817
  /**
818
818
  * §3.1 re-key, before the row walk: drop the re-keyed tables' row scope index
819
- * entries and tombstones, and raise every partition's horizon past the
820
- * changes logged under the previous patterns. Empty when nothing re-keys.
819
+ * entries and tombstones. The re-key takes a commit sequence number of its
820
+ * own in every partition and records it as each re-keyed table's horizon
821
+ * (§4.6), past the changes logged under the previous patterns. Empty when
822
+ * nothing re-keys.
821
823
  */
822
824
  export function rekeyCleanupSql(tables) {
823
825
  if (tables.length === 0)
@@ -826,7 +828,10 @@ export function rekeyCleanupSql(tables) {
826
828
  return [
827
829
  `DELETE FROM sync_row_scopes WHERE tbl IN (${names.join(',')})`,
828
830
  `DELETE FROM sync_tombstones WHERE tbl IN (${names.join(',')})`,
829
- 'UPDATE sync_partitions SET horizon_seq=max_commit_seq WHERE horizon_seq<max_commit_seq',
831
+ 'UPDATE sync_partitions SET max_commit_seq=max_commit_seq+1',
832
+ ...names.map((name) => `INSERT INTO sync_table_horizons(partition, tbl, commit_seq)
833
+ SELECT partition, ${name}, max_commit_seq FROM sync_partitions WHERE true
834
+ ON CONFLICT(partition, tbl) DO UPDATE SET commit_seq=excluded.commit_seq`),
830
835
  ];
831
836
  }
832
837
  /**
@@ -19,7 +19,7 @@ export function schemaWindowOf(current, configured) {
19
19
  const next = head.tables.get(table.name);
20
20
  if (next === undefined ||
21
21
  table.columns.length > next.columns.length ||
22
- // §6.12: a version may mark an existing column server-owned; the flag
22
+ // §6.7: a version may mark an existing column server-owned; the flag
23
23
  // never reaches the wire.
24
24
  table.columns.some((column, i) => JSON.stringify({ ...column, serverOwned: undefined }) !==
25
25
  JSON.stringify({ ...next.columns[i], serverOwned: undefined })) ||
@@ -27,7 +27,7 @@ export function schemaWindowOf(current, configured) {
27
27
  .slice(table.columns.length)
28
28
  .some((column) => !column.nullable) ||
29
29
  table.primaryKeyIndex !== next.primaryKeyIndex ||
30
- // §6.12: a pattern over an appended server-owned column is new to the
30
+ // §6.7: a pattern over an appended server-owned column is new to the
31
31
  // current version; an older client neither holds nor writes it.
32
32
  JSON.stringify(table.scopePatterns) !==
33
33
  JSON.stringify(next.scopePatterns.filter((pattern) => pattern.columnIndex < table.columns.length ||
package/dist/schema.d.ts CHANGED
@@ -141,8 +141,8 @@ export interface CompiledTable {
141
141
  * image copies ciphertext wholesale with no per-row decrypt pass, so an
142
142
  * encrypted table MUST be served via the rows lane. Empty ⇒ no restriction. */
143
143
  readonly encryptedColumnIndices: readonly number[];
144
- /** §6.12: column indices marked `serverOwned`. Empty ⇒ no server column
145
- * hook output is accepted for the table. */
144
+ /** §6.7: column indices marked `serverOwned`. Empty ⇒ no server column
145
+ * values are accepted from the table's validator. */
146
146
  readonly serverOwnedColumnIndices: readonly number[];
147
147
  }
148
148
  export interface CompiledSchema {
package/dist/schema.js CHANGED
@@ -174,7 +174,7 @@ export function compileSchema(schema) {
174
174
  // §5.11: an encrypted column carries wire type `bytes` + `encrypted`.
175
175
  if (column.encrypted === true)
176
176
  encryptedColumnIndices.push(index);
177
- // §6.12: the hook never changes who may write the row (owner set), and
177
+ // §6.7: a validator never changes who may write the row (owner set), and
178
178
  // a client's optimistic row holds NULL until the server row arrives.
179
179
  if (column.serverOwned === true) {
180
180
  if (index === primaryKeyIndex ||
@@ -183,7 +183,7 @@ export function compileSchema(schema) {
183
183
  column.encrypted === true ||
184
184
  scopePatterns.some((pattern) => pattern.columnIndex === index &&
185
185
  writeScopeSets[0].includes(pattern.variable))) {
186
- throw new Error(`table ${table.name}: server-owned column ${JSON.stringify(column.name)} must be nullable and outside the primary key, the owner write set, crdt and encryption (§6.12)`);
186
+ throw new Error(`table ${table.name}: server-owned column ${JSON.stringify(column.name)} must be nullable and outside the primary key, the owner write set, crdt and encryption (§6.7)`);
187
187
  }
188
188
  serverOwnedColumnIndices.push(index);
189
189
  }
@@ -18,6 +18,7 @@ import type { UnitScopes } from '@syncular/core';
18
18
  import { type BoundAuthoritativeQuery } from './authoritative-query.js';
19
19
  import type { CompiledTable } from './schema.js';
20
20
  import type { SqliteValue } from './sqlite-driver.js';
21
+ import { type PartitionHorizons } from './storage.js';
21
22
  import type { AuthoritativeQueryRequest, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitPruneQuery, CommitPruneResult, IndexRowScanQuery, LiveWindow, LiveWindowQuery, NewCommit, OutboxSequence, OutboxSettlement, NewReaction, PartitionRegistryEntry, PartitionTouch, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, StoredPushResult, StoredReaction, StoredRow, Tombstone } from './storage.js';
22
23
  /**
23
24
  * Schema DDL, one statement per `;`-delimited chunk. Native SQLite applies
@@ -44,7 +45,7 @@ export declare const SQLITE_UPGRADE_PROBE: SqliteStatementSpec;
44
45
  /**
45
46
  * The statements that bring the core tables of a database from an earlier
46
47
  * release to the current DDL, given the `SQLITE_UPGRADE_PROBE` rows: missing
47
- * columns, dropped columns, dropped indexes, then missing indexes. Empty for
48
+ * tables and columns, dropped columns, dropped indexes, then missing indexes. Empty for
48
49
  * a current database. Run after `SQLITE_DDL`: on every `SqliteServerStorage`
49
50
  * construction, and on D1 in `migrate()`, the core phase of `migrateSchema`
50
51
  * and the first open of a database at the current schema version.
@@ -125,6 +126,7 @@ export declare abstract class SqliteFamilyStorage {
125
126
  getMaxCommitSeq(partition: string): Promise<number>;
126
127
  getPartitionLogEpoch(partition: string): Promise<string | undefined>;
127
128
  getHorizonSeq(partition: string): Promise<number>;
129
+ getHorizons(partition: string): Promise<PartitionHorizons>;
128
130
  setHorizonSeq(partition: string, seq: number): Promise<void>;
129
131
  pruneCommitsThrough(partition: string, query: CommitPruneQuery): Promise<CommitPruneResult>;
130
132
  getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
@@ -4,7 +4,7 @@ import { validateCommitPruneQuery } from './prune.js';
4
4
  import { StorageQueryError } from './storage-errors.js';
5
5
  import { deleteRowSql, deleteSqliteRowScopesSql, indexRowPageStatement, quoteIdent, countRowsSql, scanProbeSql, scanRowPageSql, rowsReferencingBlobSql, selectRowSql, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, upsertSql, upsertValues, } from './relational-rows.js';
6
6
  import { matchesEffective } from './scopes.js';
7
- import { CLIENT_RECORD_COLUMNS, PARTITION_TOUCH_INTERVAL_MS, pushResultFromJson, pushResultToJson, rowsLiveAfterDelete, toClientRecord, toStoredChange, toStoredReaction, toStoredRow, toTombstone, } from './storage.js';
7
+ import { asJson, CLIENT_RECORD_COLUMNS, PARTITION_TOUCH_INTERVAL_MS, pushResultFromJson, pushResultToJson, rowsLiveAfterDelete, toClientRecord, toStoredChange, toStoredReaction, toStoredRow, toTombstone, } from './storage.js';
8
8
  import { chooseScanVariable, readLiveWindowPages, resolveIndexRowScan, } from './storage-query.js';
9
9
  /**
10
10
  * Schema DDL, one statement per `;`-delimited chunk. Native SQLite applies
@@ -156,6 +156,19 @@ const SQLITE_ADDED_COLUMNS = [
156
156
  ['sync_push_results', 'client_seq', 'INTEGER'],
157
157
  ['sync_partitions', 'delete_floor', 'INTEGER NOT NULL DEFAULT 0'],
158
158
  ];
159
+ /**
160
+ * Core tables that `sqliteUpgradeDdl` creates, keyed by one of their columns,
161
+ * so a D1 database at an unchanged schema version gains them at its first
162
+ * open. `sync_table_horizons` holds the §4.6 table horizons.
163
+ */
164
+ const SQLITE_ADDED_TABLES = [
165
+ [
166
+ 'sync_table_horizons',
167
+ 'commit_seq',
168
+ // One line: D1's `exec` runs each line as a statement.
169
+ 'CREATE TABLE IF NOT EXISTS sync_table_horizons(partition TEXT NOT NULL, tbl TEXT NOT NULL, commit_seq INTEGER NOT NULL, PRIMARY KEY(partition, tbl))',
170
+ ],
171
+ ];
159
172
  /** Core-table columns wire version 4 deleted: the version 3 subscription list. */
160
173
  const SQLITE_DROPPED_COLUMNS = [['sync_clients', 'subscriptions']];
161
174
  /**
@@ -189,7 +202,11 @@ export const SQLITE_UPGRADE_PROBE = {
189
202
  WHERE type='index' AND name IN (SELECT value FROM json_each(?))`,
190
203
  params: [
191
204
  JSON.stringify([
192
- ...new Set([...SQLITE_ADDED_COLUMNS, ...SQLITE_DROPPED_COLUMNS].map(([table]) => table)),
205
+ ...new Set([
206
+ ...SQLITE_ADDED_COLUMNS,
207
+ ...SQLITE_DROPPED_COLUMNS,
208
+ ...SQLITE_ADDED_TABLES,
209
+ ].map(([table]) => table)),
193
210
  ]),
194
211
  JSON.stringify([
195
212
  ...SQLITE_ADDED_INDEXES.map(([name]) => name),
@@ -200,7 +217,7 @@ export const SQLITE_UPGRADE_PROBE = {
200
217
  /**
201
218
  * The statements that bring the core tables of a database from an earlier
202
219
  * release to the current DDL, given the `SQLITE_UPGRADE_PROBE` rows: missing
203
- * columns, dropped columns, dropped indexes, then missing indexes. Empty for
220
+ * tables and columns, dropped columns, dropped indexes, then missing indexes. Empty for
204
221
  * a current database. Run after `SQLITE_DDL`: on every `SqliteServerStorage`
205
222
  * construction, and on D1 in `migrate()`, the core phase of `migrateSchema`
206
223
  * and the first open of a database at the current schema version.
@@ -208,6 +225,7 @@ export const SQLITE_UPGRADE_PROBE = {
208
225
  export function sqliteUpgradeDdl(present) {
209
226
  const has = (table, name) => present.some((row) => row.tbl === table && row.name === name);
210
227
  return [
228
+ ...SQLITE_ADDED_TABLES.filter(([table, name]) => !has(table, name)).map(([, , ddl]) => ddl),
211
229
  ...SQLITE_ADDED_COLUMNS.filter(([table, name]) => !has(table, name)).map(([table, name, definition]) => `ALTER TABLE ${table} ADD COLUMN ${name} ${definition}`),
212
230
  // A database from before wire version 4 (and the delete floor) starts
213
231
  // the delete floor at the highest version its tombstones recorded
@@ -358,6 +376,14 @@ export class SqliteFamilyStorage {
358
376
  const [row] = await this.all('SELECT horizon_seq FROM sync_partitions WHERE partition=?', [partition]);
359
377
  return row?.horizon_seq ?? 0;
360
378
  }
379
+ async getHorizons(partition) {
380
+ const [row] = await this.all(`SELECT coalesce((SELECT horizon_seq FROM sync_partitions WHERE partition=?),0) AS seq,
381
+ (SELECT json_group_object(tbl, commit_seq) FROM sync_table_horizons WHERE partition=?) AS tables`, [partition, partition]);
382
+ return {
383
+ seq: row?.seq ?? 0,
384
+ tables: new Map(Object.entries(asJson(row?.tables ?? '{}'))),
385
+ };
386
+ }
361
387
  async setHorizonSeq(partition, seq) {
362
388
  await this.all(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?)
363
389
  ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)`, [partition, seq]);
@@ -393,8 +419,14 @@ export class SqliteFamilyStorage {
393
419
  AND ${epochGuard}`,
394
420
  params: [partition, partition, partition, query.logEpoch],
395
421
  },
396
- // §4.6: tombstones prune in the same pass as the commit log.
397
- ...['sync_commits', 'sync_changes', 'sync_tombstones'].map((table) => ({
422
+ // §4.6: tombstones and table horizons prune in the same pass as the
423
+ // commit log.
424
+ ...[
425
+ 'sync_commits',
426
+ 'sync_changes',
427
+ 'sync_tombstones',
428
+ 'sync_table_horizons',
429
+ ].map((table) => ({
398
430
  sql: `DELETE FROM ${table} WHERE partition=? AND commit_seq<=${horizon} AND ${epochGuard}`,
399
431
  params: [partition, partition, partition, query.logEpoch],
400
432
  })),
package/dist/storage.d.ts CHANGED
@@ -440,6 +440,16 @@ export declare function toStoredChange(record: StoredChangeRecord): StoredChange
440
440
  export declare function toStoredReaction(record: StoredReactionRecord): StoredReaction;
441
441
  export declare const CLIENT_RECORD_COLUMNS = "client_id, actor_id, wire_version, cursor, updated_at_ms, schema_version, units, registration_digest, catching_up, last_round_at_ms, last_error_code, consecutive_failures";
442
442
  export declare function toClientRecord(record: ClientRowRecord): ClientRecord;
443
+ /** A partition's pruning horizon and its table horizons (§4.6). */
444
+ export interface PartitionHorizons {
445
+ /** `horizonSeq`. */
446
+ readonly seq: number;
447
+ /**
448
+ * Re-keyed table → the commit sequence number its re-key took. The changes
449
+ * of a table at or below it are never served.
450
+ */
451
+ readonly tables: ReadonlyMap<string, number>;
452
+ }
443
453
  /** One unit of the §4.5 scan set. */
444
454
  export interface LiveScanUnit {
445
455
  /** The unit's scope map; its first variable (keys sorted) is its index key. */
@@ -866,6 +876,8 @@ export interface ServerStorage {
866
876
  begin(partition: string): Promise<StorageTransaction>;
867
877
  getMaxCommitSeq(partition: string): Promise<number>;
868
878
  getHorizonSeq(partition: string): Promise<number>;
879
+ /** `horizonSeq` and the table horizons (§4.6) in one read. */
880
+ getHorizons(partition: string): Promise<PartitionHorizons>;
869
881
  /** Monotonic within the current epoch; use atomic pruning for maintenance. */
870
882
  setHorizonSeq(partition: string, seq: number): Promise<void>;
871
883
  /**