@syncular/server 0.77.4 → 0.78.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.
@@ -22,9 +22,11 @@ var _a;
22
22
  *
23
23
  * - reads (`getRow`) execute immediately against D1 (autocommit);
24
24
  * - writes are **buffered** as prepared statements;
25
- * - `commit()` flushes the whole buffer as one `db.batch(...)` — the same
26
- * atomicity §6.4 requires (a rejected op rolls back by simply never
27
- * flushing);
25
+ * - `putPushResult` closes a push commit and flushes the buffer as one
26
+ * `db.batch(...)` (§6.4: one atomic batch per commit, because a later
27
+ * commit of the request must read the earlier one's writes from D1);
28
+ * `commit()` flushes whatever remains. A rejected commit rolls back by
29
+ * never flushing its part of the buffer;
28
30
  * - `rollback()` drops the buffer unsent.
29
31
  *
30
32
  * `appendCommit` allocates the dense per-partition `commitSeq` (§2.1) by
@@ -89,6 +91,8 @@ class D1Transaction extends SqliteFamilyTransaction {
89
91
  #prepareQuery;
90
92
  #pushApplySerialized;
91
93
  #scanVariables;
94
+ /** Each push commit reaches D1 as its own batch when it closes (§6.4). */
95
+ persistsCommitsOnClose = true;
92
96
  #buffer = [];
93
97
  /** Live snapshot of `max_commit_seq`, advanced within this transaction. */
94
98
  #maxCommitSeq;
@@ -323,18 +327,16 @@ class D1Transaction extends SqliteFamilyTransaction {
323
327
  }
324
328
  return queryAuthoritativeOn(this.#db, this.partition, this.#prepareQuery(query));
325
329
  }
326
- async preparePushApply(clientId, clientCommitId, runningSchemaVersion, _targets = [], outbox) {
330
+ async preparePushApply(clientId, commits, runningSchemaVersion, outbox) {
327
331
  this.assertOpen();
328
332
  if (!this.#pushApplySerialized) {
329
333
  throw new Error('D1 push apply requires externally serialized partition writes');
330
334
  }
331
335
  // D1 has no interactive lock. The caller explicitly asserted that every
332
336
  // write for this partition is already serialized (normally by its DO).
333
- // The settlement's writes sit below the checkpoint, so a rejection keeps
334
- // them.
335
- const settled = outbox === undefined
336
- ? undefined
337
- : await this.settleOutbox(clientId, clientCommitId, outbox);
337
+ // The settlement's writes sit below the first commit's checkpoint, so a
338
+ // rejection keeps them.
339
+ const admitted = await this.admitPushRequest(clientId, commits.map((commit) => commit.clientCommitId), outbox);
338
340
  this.#pushApplyCheckpoint = this.#buffer.length;
339
341
  // The serve gate and the delete floor (§2.2) in one round trip.
340
342
  const read = await this.#db
@@ -346,14 +348,7 @@ class D1Transaction extends SqliteFamilyTransaction {
346
348
  logEpoch: undefined,
347
349
  pending: [],
348
350
  };
349
- const deleteFloor = read?.delete_floor ?? 0;
350
- return settled === undefined
351
- ? {
352
- gate,
353
- deleteFloor,
354
- persisted: await this.getPushResult(clientId, clientCommitId),
355
- }
356
- : { gate, deleteFloor, ...settled };
351
+ return { gate, deleteFloor: read?.delete_floor ?? 0, ...admitted };
357
352
  }
358
353
  advanceCheckpoint(_name, _ownerEpoch, _watermark, _observedRows, _nowMs) {
359
354
  // D1 installs no fence and declares no checkpoints in this release.
@@ -370,7 +365,7 @@ class D1Transaction extends SqliteFamilyTransaction {
370
365
  pending: [],
371
366
  };
372
367
  }
373
- async commitRejectedPushResult(clientId, clientCommitId, result, sequence) {
368
+ async rejectPushCommit(clientId, clientCommitId, result, sequence) {
374
369
  this.assertOpen();
375
370
  const checkpoint = this.#pushApplyCheckpoint;
376
371
  if (checkpoint === undefined) {
@@ -382,10 +377,22 @@ class D1Transaction extends SqliteFamilyTransaction {
382
377
  this.#maxCommitSeq = undefined;
383
378
  this.#applicationOpIndexes.clear();
384
379
  await this.putPushResult(clientId, clientCommitId, result, sequence);
385
- await this.commit();
386
- // The idempotency re-check found no record under the serialized apply, so
387
- // the insert above is the canonical outcome.
388
- return result;
380
+ }
381
+ /**
382
+ * Closes the request's current commit (§6.4): its buffered writes and this
383
+ * result reach D1 as one atomic batch. A later commit of the request then
384
+ * reads its rows, tombstones and registered queries from D1 itself, which
385
+ * a buffer spanning commits could not answer.
386
+ */
387
+ async putPushResult(clientId, clientCommitId, result, sequence) {
388
+ await super.putPushResult(clientId, clientCommitId, result, sequence);
389
+ await this.#flush();
390
+ this.#pending.clear();
391
+ this.#clearedTombstones.clear();
392
+ this.#prefetched.clear();
393
+ this.#applicationOpIndexes.clear();
394
+ if (this.#pushApplyCheckpoint !== undefined)
395
+ this.#pushApplyCheckpoint = 0;
389
396
  }
390
397
  async #assertNoUniqueCollision(table, row, opIndex) {
391
398
  if (!table.materialize)
@@ -486,15 +493,17 @@ class D1Transaction extends SqliteFamilyTransaction {
486
493
  }
487
494
  async commit() {
488
495
  this.assertOpen();
489
- if (this.#buffer.length === 0) {
490
- this.open = false;
496
+ await this.#flush();
497
+ this.open = false;
498
+ }
499
+ /** Send the buffer as one atomic D1 batch: the §6.4 all-or-nothing write. */
500
+ async #flush() {
501
+ if (this.#buffer.length === 0)
491
502
  return;
492
- }
493
503
  const statements = this.#buffer.map((entry) => this.#db.prepare(entry.sql).bind(...entry.params));
494
- // One atomic D1 batch — the §6.4 all-or-nothing commit.
495
504
  try {
496
505
  await this.#db.batch(statements);
497
- this.open = false;
506
+ this.#buffer.length = 0;
498
507
  }
499
508
  catch (error) {
500
509
  if (isD1ConstraintError(error)) {
package/dist/handler.js CHANGED
@@ -15,7 +15,7 @@ import { reportError, SyncError, syncError } from './errors.js';
15
15
  import { emitEvent, } from './events.js';
16
16
  import { END_FRAME_BYTES, encodeResponseFrame, responseEnvelopeHeader, } from './frame-bytes.js';
17
17
  import { ACCEPT_EXTERNAL_ROWS, ACCEPT_INLINE_ROWS, bootstrapSegments, clampPullLimits, commitFrame, coveredTables, planBootstrap, planUnit, } from './pull.js';
18
- import { processPushCommitWithTrace } from './push.js';
18
+ import { processPushCommitsWithTrace } from './push.js';
19
19
  import { serveNotReadyError } from './readiness.js';
20
20
  import { compileSchema } from './schema.js';
21
21
  import { schemaWindowOf, projectRowPayload } from './schema-window.js';
@@ -381,31 +381,50 @@ async function* streamResponse(plan, ctx, schema, report) {
381
381
  }
382
382
  const { clientId, outboxId } = plan.header;
383
383
  try {
384
- // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
384
+ // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order,
385
+ // sent after the request's one transaction commits (§6.4).
385
386
  const currentSchema = compileSchema(ctx.schema);
386
387
  let acceptedThrough = 0;
387
- // §6.3.2: the request's first commit settles the outbox and reads `W`.
388
- let watermark = 0;
389
- for (const [index, push] of plan.pushes.entries()) {
390
- const processed = await processPushCommitWithTrace(ctx, currentSchema, plan.resolved, clientId, push, schema, outboxId === undefined
388
+ const pushed = plan.pushes.length === 0
389
+ ? []
390
+ : await processPushCommitsWithTrace(ctx, currentSchema, plan.resolved, clientId, plan.pushes.map((push) => {
391
+ // The frame names its rows before the transaction opens, so the
392
+ // admission read carries the commit's read-ahead. A rowId
393
+ // holding U+0000 is rejected per operation (§6.1) before any
394
+ // store reads it.
395
+ const targets = new Map();
396
+ for (const op of push.operations) {
397
+ if (!currentSchema.tables.has(op.table) ||
398
+ op.rowId.includes('\u0000')) {
399
+ continue;
400
+ }
401
+ const ids = targets.get(op.table) ?? [];
402
+ ids.push(op.rowId);
403
+ targets.set(op.table, ids);
404
+ }
405
+ return {
406
+ clientCommitId: push.clientCommitId,
407
+ buildOperations: async () => push.operations,
408
+ ...(targets.size === 0
409
+ ? {}
410
+ : {
411
+ targets: [...targets].map(([table, rowIds]) => ({
412
+ table,
413
+ rowIds,
414
+ })),
415
+ }),
416
+ };
417
+ }), schema, outboxId === undefined
391
418
  ? undefined
392
419
  : {
393
420
  outboxId,
394
- clientSeq: push.clientSeq,
395
- watermark,
396
- ...(index === 0
397
- ? {
398
- settlement: {
399
- outboxId,
400
- commits: plan.pushes.map((commit) => ({
401
- clientCommitId: commit.clientCommitId,
402
- clientSeq: commit.clientSeq,
403
- })),
404
- },
405
- }
406
- : {}),
421
+ commits: plan.pushes.map((commit) => ({
422
+ clientCommitId: commit.clientCommitId,
423
+ clientSeq: commit.clientSeq,
424
+ })),
407
425
  });
408
- watermark = processed.watermark ?? watermark;
426
+ for (const [index, push] of plan.pushes.entries()) {
427
+ const processed = pushed[index];
409
428
  acceptedThrough = Math.max(acceptedThrough, processed.frame.commitSeq ?? 0);
410
429
  const frame = {
411
430
  ...processed.frame,
@@ -332,22 +332,23 @@ async function readServeGateOn(client, partition, runningSchemaVersion) {
332
332
  }
333
333
  /**
334
334
  * The push admission read: the RFC 0007 serve gate, the §2.3 idempotency
335
- * record, and (when the caller already knows the commit's row targets) the
336
- * read-ahead rows, in one statement with one snapshot. The caller takes the
337
- * partition lock first: under READ COMMITTED a statement's snapshot is fixed
338
- * at its start, so the read must be the statement *after* the lock to observe
339
- * a duplicate that committed while this transaction waited for it.
335
+ * records of every commit of the request, and (when the caller already knows
336
+ * the commits' row targets) the read-ahead rows, in one statement with one
337
+ * snapshot. The caller takes the partition lock first: under READ COMMITTED a
338
+ * statement's snapshot is fixed at its start, so the read must be the
339
+ * statement *after* the lock to observe a duplicate that committed while this
340
+ * transaction waited for it.
340
341
  */
341
- async function readAdmissionOn(client, partition, clientId, clientCommitId, runningSchemaVersion, prefetch) {
342
+ async function readAdmissionOn(client, partition, clientId, clientCommitIds, runningSchemaVersion, prefetch) {
342
343
  const params = [
343
344
  partition,
344
345
  runningSchemaVersion,
345
346
  clientId,
346
- clientCommitId,
347
+ [...clientCommitIds],
347
348
  ];
348
349
  let statement = `SELECT ${SERVE_GATE_PROJECTION},
349
- (SELECT result FROM sync_push_results
350
- WHERE partition=$1 AND client_id=$3 AND client_commit_id=$4) AS result,
350
+ (SELECT jsonb_object_agg(client_commit_id, result) FROM sync_push_results
351
+ WHERE partition=$1 AND client_id=$3 AND client_commit_id = ANY($4::text[])) AS results,
351
352
  (SELECT delete_floor FROM sync_partitions WHERE partition=$1) AS delete_floor`;
352
353
  if (prefetch !== undefined && prefetch.specs.length > 0) {
353
354
  params.push(JSON.stringify(prefetch.specs));
@@ -371,9 +372,14 @@ async function readAdmissionOn(client, partition, clientId, clientCommitId, runn
371
372
  }
372
373
  const { rows } = await client.query(statement, params);
373
374
  const gateRow = rows.find((row) => row.tbl === null) ?? rows[0];
375
+ const results = gateRow?.results === null || gateRow?.results === undefined
376
+ ? {}
377
+ : asJson(gateRow.results);
374
378
  return {
375
379
  gate: toServeGate(gateRow),
376
- persisted: toPersistedPushResult(gateRow?.result),
380
+ persisted: new Map(typeof results === 'object' && results !== null
381
+ ? Object.entries(results)
382
+ : []),
377
383
  // asNumber maps the NULL of a partition without a commit to 0.
378
384
  deleteFloor: asNumber(gateRow?.delete_floor),
379
385
  prefetched: rows.filter((row) => row.tbl !== null && row.tbl !== undefined),
@@ -840,7 +846,14 @@ class PostgresTransaction {
840
846
  /** The storage's `chooseScanVariable` picks. */
841
847
  #scanVariables;
842
848
  #open = true;
849
+ /** True once the request's current commit has written behind its savepoint. */
843
850
  #pushApplySavepoint = false;
851
+ /**
852
+ * The request's §2.3 results, written as one statement at `commit()`
853
+ * (§6.4): each commit closes with its result, and none is read back before
854
+ * the transaction ends.
855
+ */
856
+ #pushResults = [];
844
857
  /**
845
858
  * `prefetchRows` results keyed `table\u0000rowId`; `null` records a row
846
859
  * (or tombstone) read as absent. A write in this transaction drops the
@@ -958,9 +971,12 @@ class PostgresTransaction {
958
971
  return Promise.all(writes);
959
972
  }
960
973
  /**
961
- * The candidate savepoint, taken before the transaction's first write.
962
- * Every candidate write must be undoable by `commitRejectedPushResult`, and
963
- * a refused commit that wrote nothing must not pay to create one.
974
+ * The current commit's candidate savepoint, taken before its first write.
975
+ * Every candidate write must be undoable by `rejectPushCommit`, and a
976
+ * refused commit that wrote nothing must not pay to create one. Each commit
977
+ * takes its own savepoint under the same name: `ROLLBACK TO` targets the
978
+ * newest, and an earlier commit's savepoint stays open until the
979
+ * transaction ends, so no `RELEASE` round trip is needed (§6.4).
964
980
  */
965
981
  #ensurePushSavepoint() {
966
982
  if (this.#pushApplySavepoint)
@@ -1102,7 +1118,7 @@ class PostgresTransaction {
1102
1118
  }
1103
1119
  return { rows: result.rows, maxCommitSeq: this.#cursorSeq };
1104
1120
  }
1105
- async preparePushApply(clientId, clientCommitId, runningSchemaVersion, targets = [], outbox) {
1121
+ async preparePushApply(clientId, commits, runningSchemaVersion, outbox) {
1106
1122
  this.#assertOpen();
1107
1123
  // The lock is its own statement: a READ COMMITTED statement's snapshot is
1108
1124
  // fixed at its start, so the admission read must run *after* a duplicate's
@@ -1112,40 +1128,44 @@ class PostgresTransaction {
1112
1128
  await this.lockPartition();
1113
1129
  const watermark = outbox === undefined
1114
1130
  ? undefined
1115
- : await this.#settleOutbox(clientId, clientCommitId, outbox);
1116
- const tables = [];
1117
- const specs = [];
1118
- for (const target of targets) {
1119
- const ids = [...new Set(target.rowIds)].filter((rowId) => !this.#prefetchedRows.has(`${target.table}\u0000${rowId}`));
1120
- if (ids.length === 0)
1121
- continue;
1122
- tables.push(this.#resolveTable(target.table));
1123
- specs.push({ tbl: target.table, ids });
1131
+ : await this.#settleOutbox(clientId, outbox);
1132
+ const ids = new Map();
1133
+ for (const commit of commits) {
1134
+ for (const target of commit.targets ?? []) {
1135
+ const table = ids.get(target.table) ?? new Set();
1136
+ for (const rowId of target.rowIds) {
1137
+ if (!this.#prefetchedRows.has(`${target.table}\u0000${rowId}`)) {
1138
+ table.add(rowId);
1139
+ }
1140
+ }
1141
+ if (table.size > 0)
1142
+ ids.set(target.table, table);
1143
+ }
1124
1144
  }
1125
- // One statement: the serve gate, the idempotency record, and the commit's
1126
- // read-ahead (when the caller already knows its targets).
1127
- const admission = await readAdmissionOn(this.#client, this.#partition, clientId, clientCommitId, runningSchemaVersion, specs.length === 0 ? undefined : { tables, specs });
1145
+ const tables = [...ids.keys()].map((table) => this.#resolveTable(table));
1146
+ const specs = [...ids].map(([tbl, rowIds]) => ({ tbl, ids: [...rowIds] }));
1147
+ // One statement for the whole request: the serve gate, every commit's
1148
+ // idempotency record, and the read-ahead of every commit's known rows.
1149
+ const admission = await readAdmissionOn(this.#client, this.#partition, clientId, commits.map((commit) => commit.clientCommitId), runningSchemaVersion, specs.length === 0 ? undefined : { tables, specs });
1128
1150
  this.#recordPrefetched(admission.prefetched);
1129
1151
  return {
1130
1152
  gate: admission.gate,
1131
- persisted: admission.persisted,
1153
+ persisted: (clientCommitId) => toPersistedPushResult(admission.persisted.get(clientCommitId)),
1132
1154
  deleteFloor: admission.deleteFloor,
1133
1155
  ...(watermark === undefined ? {} : { watermark }),
1134
1156
  };
1135
1157
  }
1136
1158
  /**
1137
1159
  * The §9 settlement and §6.3.2 steps 1 and 2 under the partition lock,
1138
- * before the candidate savepoint, so a rejection keeps them. Two
1160
+ * before the first commit's savepoint, so no rejection discards them. Two
1139
1161
  * statements: the settlement touches disjoint rows (outside and inside the
1140
1162
  * request), and the watermark delete must see its sequences.
1141
1163
  */
1142
- async #settleOutbox(clientId, clientCommitId, outbox) {
1164
+ async #settleOutbox(clientId, outbox) {
1143
1165
  const first = outbox.commits[0];
1144
1166
  const last = outbox.commits.at(-1);
1145
- if (first === undefined ||
1146
- last === undefined ||
1147
- first.clientCommitId !== clientCommitId) {
1148
- throw new Error("outbox settlement rides the request's first commit");
1167
+ if (first === undefined || last === undefined) {
1168
+ throw new Error('outbox settlement needs the request commits');
1149
1169
  }
1150
1170
  const commits = JSON.stringify(outbox.commits.map((commit) => ({
1151
1171
  id: commit.clientCommitId,
@@ -1204,44 +1224,27 @@ class PostgresTransaction {
1204
1224
  // transaction, so a migration cannot interleave between them.
1205
1225
  return readServeGateOn(this.#client, this.#partition, runningSchemaVersion);
1206
1226
  }
1207
- async commitRejectedPushResult(clientId, clientCommitId, result, sequence) {
1227
+ async rejectPushCommit(clientId, clientCommitId, result, sequence) {
1208
1228
  this.#assertOpen();
1209
1229
  // Candidate rows that never reached the database are discarded with the
1210
- // staging map; a savepoint exists only when one did.
1230
+ // staging map; a savepoint exists only when one did. It stays open: the
1231
+ // rollback returns the database to where the next commit starts (the
1232
+ // results wait in memory), so the next commit writes behind it.
1211
1233
  this.#staged.clear();
1212
1234
  this.#stagedBlobRefs.clear();
1213
1235
  if (this.#pushApplySavepoint) {
1214
- await this.#client.query('ROLLBACK TO SAVEPOINT syncular_push_candidate');
1215
- await this.#client.query('RELEASE SAVEPOINT syncular_push_candidate');
1216
- this.#pushApplySavepoint = false;
1236
+ await this.#serial.query('ROLLBACK TO SAVEPOINT syncular_push_candidate');
1217
1237
  }
1218
- const canonical = await this.#insertPushResult(clientId, clientCommitId, result, sequence);
1219
- await this.commit();
1220
- return canonical;
1221
- }
1222
- /** Insert the §2.3 outcome and return the canonical persisted value. */
1223
- async #insertPushResult(clientId, clientCommitId, result, sequence) {
1224
- const { rows } = await this.#client.query(`INSERT INTO sync_push_results(partition, client_id, client_commit_id, result, outbox_id, client_seq)
1225
- VALUES ($1,$2,$3,$4,$5,$6)
1226
- ON CONFLICT (partition, client_id, client_commit_id) DO NOTHING
1227
- RETURNING result`, [
1228
- this.#partition,
1229
- clientId,
1230
- clientCommitId,
1231
- JSON.stringify(serializePushResult(result)),
1232
- sequence?.outboxId ?? null,
1233
- sequence?.clientSeq ?? null,
1234
- ]);
1235
- if (rows[0] !== undefined) {
1236
- return toPersistedPushResult(rows[0].result) ?? result;
1237
- }
1238
- // `ON CONFLICT DO NOTHING` means a previously committed outcome won; read
1239
- // it rather than claiming this caller's candidate.
1240
- const existing = await getPushResultOn(this.#client, this.#partition, clientId, clientCommitId);
1241
- if (existing === undefined) {
1242
- throw new Error('push result insert did not persist an outcome');
1243
- }
1244
- return existing;
1238
+ this.#recordPushResult(clientId, clientCommitId, result, sequence);
1239
+ }
1240
+ #recordPushResult(clientId, clientCommitId, result, sequence) {
1241
+ this.#pushResults.push({
1242
+ client_id: clientId,
1243
+ client_commit_id: clientCommitId,
1244
+ result: serializePushResult(result),
1245
+ outbox_id: sequence?.outboxId ?? null,
1246
+ client_seq: sequence?.clientSeq ?? null,
1247
+ });
1245
1248
  }
1246
1249
  async upsertRow(table, row, context) {
1247
1250
  this.#assertOpen();
@@ -1312,8 +1315,13 @@ class PostgresTransaction {
1312
1315
  }
1313
1316
  async appendCommit(commit) {
1314
1317
  this.#assertOpen();
1315
- // The commit writes its delete tombstones below.
1316
- this.#prefetchedTombstones.clear();
1318
+ // The commit writes its delete tombstones below; every other prefetched
1319
+ // tombstone still holds for the request's later commits.
1320
+ for (const change of commit.changes) {
1321
+ if (change.op === 'delete') {
1322
+ this.#prefetchedTombstones.delete(`${change.table}\u0000${change.rowId}`);
1323
+ }
1324
+ }
1317
1325
  // The append advances the partition cursor; a registered query that runs
1318
1326
  // after it must read the new value.
1319
1327
  this.#cursorSeq = undefined;
@@ -1429,16 +1437,10 @@ class PostgresTransaction {
1429
1437
  }
1430
1438
  async putPushResult(clientId, clientCommitId, result, sequence) {
1431
1439
  this.#assertOpen();
1432
- await this.#client.query(`INSERT INTO sync_push_results(partition, client_id, client_commit_id, result, outbox_id, client_seq)
1433
- VALUES ($1,$2,$3,$4,$5,$6)
1434
- ON CONFLICT (partition, client_id, client_commit_id) DO NOTHING`, [
1435
- this.#partition,
1436
- clientId,
1437
- clientCommitId,
1438
- JSON.stringify(serializePushResult(result)),
1439
- sequence?.outboxId ?? null,
1440
- sequence?.clientSeq ?? null,
1441
- ]);
1440
+ this.#recordPushResult(clientId, clientCommitId, result, sequence);
1441
+ // The commit is closed: the next commit's first write takes its own
1442
+ // savepoint.
1443
+ this.#pushApplySavepoint = false;
1442
1444
  }
1443
1445
  async enqueueReactions(reactions) {
1444
1446
  this.#assertOpen();
@@ -1463,6 +1465,16 @@ class PostgresTransaction {
1463
1465
  }
1464
1466
  async commit() {
1465
1467
  this.#assertOpen();
1468
+ if (this.#pushResults.length > 0) {
1469
+ // Every result of the request in one statement; `#client` flushes the
1470
+ // staged writes first.
1471
+ await this.#client.query(`INSERT INTO sync_push_results(partition, client_id, client_commit_id, result, outbox_id, client_seq)
1472
+ SELECT $1, r.client_id, r.client_commit_id, r.result, r.outbox_id, r.client_seq
1473
+ FROM jsonb_to_recordset($2::text::jsonb)
1474
+ AS r(client_id text, client_commit_id text, result jsonb, outbox_id text, client_seq bigint)
1475
+ ON CONFLICT (partition, client_id, client_commit_id) DO NOTHING`, [this.#partition, JSON.stringify(this.#pushResults)]);
1476
+ this.#pushResults.length = 0;
1477
+ }
1466
1478
  await this.#writeStaged();
1467
1479
  this.#open = false;
1468
1480
  // Signal the transaction wrapper to COMMIT; wait for it to actually land.
package/dist/push.d.ts CHANGED
@@ -9,19 +9,20 @@
9
9
  * - a lost `baseVersion = 0` insert race re-authorizes the winner's row
10
10
  * before disclosing it in a conflict record (§6.2).
11
11
  *
12
- * Per-commit atomicity (§6.4): one storage transaction per commit; the
13
- * idempotency record persists in the same transaction as the writes.
12
+ * Atomicity (§6.4): one storage transaction per push request, one savepoint
13
+ * per commit; every idempotency record persists in the same transaction as
14
+ * the writes.
14
15
  *
15
16
  * Optional per-table write validation (§6.7) runs after decode + the §3.4
16
17
  * scope check, on the row that will persist (post scope-strip, post CRDT
17
18
  * merge); a validator throw rejects the whole commit atomically with a
18
19
  * host code.
19
20
  */
20
- import { type PushCommitFrame, type PushOperation, type PushResultFrame, type RowValue } from '@syncular/core';
21
+ import { type PushOperation, type PushResultFrame, type RowValue } from '@syncular/core';
21
22
  import type { SyncRequestContext } from './context.js';
22
23
  import type { CompiledSchema, CompiledTable } from './schema.js';
23
24
  import type { ResolvedScopes } from './scopes.js';
24
- import type { OutboxSequence, OutboxSettlement, StorageTransaction, StoredCommit } from './storage.js';
25
+ import type { OutboxSettlement, PushApplyCommit, StorageTransaction } from './storage.js';
25
26
  /**
26
27
  * Extract the blobIds a decoded row references through its `blob_ref`
27
28
  * columns (§5.9.4), skipping NULLs. Malformed BlobRefs already failed at
@@ -48,36 +49,33 @@ export interface ProcessedPushCommit {
48
49
  readonly replayed: boolean;
49
50
  readonly recordedAtMs?: number;
50
51
  readonly cacheIdentity?: string;
51
- /** The outbox watermark `W` the commit's settlement read (§6.3.2). */
52
- readonly watermark?: number;
53
52
  }
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;
53
+ /** One commit of a push request (§6.4). */
54
+ export interface PushRequestCommit {
55
+ readonly clientCommitId: string;
56
+ /**
57
+ * Runs after the partition lock and the idempotency read, inside the
58
+ * request's transaction, so its reads and the returned operations share
59
+ * the transaction that commits.
60
+ */
61
+ readonly buildOperations: (tx: StorageTransaction) => Promise<readonly ApplyOperation[]>;
62
+ /** The rows the commit names before its operations are built. */
63
+ readonly targets?: PushApplyCommit['targets'];
60
64
  }
61
- export interface AppliedCommitEvent {
62
- readonly commit: StoredCommit;
63
- }
64
- /**
65
- * Process one `PUSH_COMMIT` frame: idempotency replay (§2.3), sequential
66
- * atomic apply (§6.4), realtime notification for applied commits.
67
- */
68
- export declare function processPushCommit(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame): Promise<PushResultFrame>;
69
65
  /**
70
- * Host-observable variant of `processPushCommit`. The SSP2 wire frame keeps
71
- * rejected replays as `status: rejected`; this companion result preserves the
72
- * cache provenance needed by structured events and server helpers.
66
+ * The serialized apply of one commit outside an SSP2 request: an
67
+ * authoritative command or an erasure.
73
68
  */
74
- export declare function processPushCommitWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame, wireSchema?: CompiledSchema, outbox?: PushOutbox): Promise<ProcessedPushCommit>;
69
+ export declare function processPushOperationsWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, clientCommitId: string, buildOperations: PushRequestCommit['buildOperations'], wireSchema?: CompiledSchema): Promise<ProcessedPushCommit>;
75
70
  /**
76
- * Shared serialized apply path for SSP2 commits and authoritative commands.
77
- * The builder runs after the partition lock and idempotency re-check, so its
78
- * reads and the returned operations share the transaction that is committed.
71
+ * Apply one push request (§6.4): one storage transaction under one partition
72
+ * lock, one serve-gate and idempotency read for every commit, each commit
73
+ * inside its own savepoint in frame order. A commit's rejection rolls back
74
+ * only that commit; any other failure rolls back the whole request and
75
+ * throws. Reaction events and realtime notifications leave after the
76
+ * transaction commits, once per applied commit in `commitSeq` order.
77
+ *
78
+ * `outbox` lists every commit of the request in the same order as
79
+ * `commits`; it carries the §6.3.2 sequences and the §9 settlement.
79
80
  */
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 {
81
- readonly table: string;
82
- readonly rowIds: readonly string[];
83
- }[], outbox?: PushOutbox): Promise<ProcessedPushCommit>;
81
+ export declare function processPushCommitsWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, commits: readonly PushRequestCommit[], wireSchema?: CompiledSchema, outbox?: OutboxSettlement): Promise<ProcessedPushCommit[]>;