@optimystic/db-core 1.17.0 → 1.19.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 (96) hide show
  1. package/README.md +2 -1
  2. package/dist/src/blocks/helpers.d.ts +7 -0
  3. package/dist/src/blocks/helpers.d.ts.map +1 -1
  4. package/dist/src/blocks/helpers.js +7 -1
  5. package/dist/src/blocks/helpers.js.map +1 -1
  6. package/dist/src/btree/btree.d.ts +100 -4
  7. package/dist/src/btree/btree.d.ts.map +1 -1
  8. package/dist/src/btree/btree.js +252 -90
  9. package/dist/src/btree/btree.js.map +1 -1
  10. package/dist/src/btree/node-division.d.ts +37 -0
  11. package/dist/src/btree/node-division.d.ts.map +1 -0
  12. package/dist/src/btree/node-division.js +133 -0
  13. package/dist/src/btree/node-division.js.map +1 -0
  14. package/dist/src/chain/chain.d.ts +23 -0
  15. package/dist/src/chain/chain.d.ts.map +1 -1
  16. package/dist/src/chain/chain.js +43 -6
  17. package/dist/src/chain/chain.js.map +1 -1
  18. package/dist/src/collection/collection.d.ts +38 -5
  19. package/dist/src/collection/collection.d.ts.map +1 -1
  20. package/dist/src/collection/collection.js +126 -11
  21. package/dist/src/collection/collection.js.map +1 -1
  22. package/dist/src/collection/struct.d.ts +20 -0
  23. package/dist/src/collection/struct.d.ts.map +1 -1
  24. package/dist/src/collection/struct.js.map +1 -1
  25. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  26. package/dist/src/collections/tree/tree.js +5 -3
  27. package/dist/src/collections/tree/tree.js.map +1 -1
  28. package/dist/src/log/log.d.ts +5 -1
  29. package/dist/src/log/log.d.ts.map +1 -1
  30. package/dist/src/log/log.js +7 -1
  31. package/dist/src/log/log.js.map +1 -1
  32. package/dist/src/network/block-size.d.ts +67 -0
  33. package/dist/src/network/block-size.d.ts.map +1 -0
  34. package/dist/src/network/block-size.js +82 -0
  35. package/dist/src/network/block-size.js.map +1 -0
  36. package/dist/src/network/index.d.ts +2 -0
  37. package/dist/src/network/index.d.ts.map +1 -1
  38. package/dist/src/network/index.js +2 -0
  39. package/dist/src/network/index.js.map +1 -1
  40. package/dist/src/network/struct.d.ts +13 -11
  41. package/dist/src/network/struct.d.ts.map +1 -1
  42. package/dist/src/network/struct.js.map +1 -1
  43. package/dist/src/network/transaction-size.d.ts +59 -0
  44. package/dist/src/network/transaction-size.d.ts.map +1 -0
  45. package/dist/src/network/transaction-size.js +74 -0
  46. package/dist/src/network/transaction-size.js.map +1 -0
  47. package/dist/src/reactivity/config.d.ts +8 -4
  48. package/dist/src/reactivity/config.d.ts.map +1 -1
  49. package/dist/src/reactivity/config.js +7 -3
  50. package/dist/src/reactivity/config.js.map +1 -1
  51. package/dist/src/reactivity/rotation.d.ts +9 -3
  52. package/dist/src/reactivity/rotation.d.ts.map +1 -1
  53. package/dist/src/reactivity/rotation.js +8 -2
  54. package/dist/src/reactivity/rotation.js.map +1 -1
  55. package/dist/src/testing/test-transactor.d.ts +2 -0
  56. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  57. package/dist/src/testing/test-transactor.js +10 -0
  58. package/dist/src/testing/test-transactor.js.map +1 -1
  59. package/dist/src/transaction/coordinator.d.ts +72 -3
  60. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  61. package/dist/src/transaction/coordinator.js +320 -146
  62. package/dist/src/transaction/coordinator.js.map +1 -1
  63. package/dist/src/transactor/change-notifier.d.ts +19 -8
  64. package/dist/src/transactor/change-notifier.d.ts.map +1 -1
  65. package/dist/src/transactor/change-notifier.js.map +1 -1
  66. package/dist/src/transactor/network-transactor.d.ts +57 -8
  67. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  68. package/dist/src/transactor/network-transactor.js +185 -24
  69. package/dist/src/transactor/network-transactor.js.map +1 -1
  70. package/dist/src/transactor/transactor.d.ts +14 -0
  71. package/dist/src/transactor/transactor.d.ts.map +1 -1
  72. package/dist/src/transform/digest.d.ts +20 -0
  73. package/dist/src/transform/digest.d.ts.map +1 -1
  74. package/dist/src/transform/digest.js +23 -3
  75. package/dist/src/transform/digest.js.map +1 -1
  76. package/package.json +1 -1
  77. package/src/blocks/helpers.ts +8 -1
  78. package/src/btree/btree.ts +266 -88
  79. package/src/btree/node-division.ts +155 -0
  80. package/src/chain/chain.ts +55 -6
  81. package/src/collection/collection.ts +135 -13
  82. package/src/collection/struct.ts +18 -0
  83. package/src/collections/tree/tree.ts +4 -2
  84. package/src/log/log.ts +7 -1
  85. package/src/network/block-size.ts +81 -0
  86. package/src/network/index.ts +2 -0
  87. package/src/network/struct.ts +15 -13
  88. package/src/network/transaction-size.ts +73 -0
  89. package/src/reactivity/config.ts +8 -4
  90. package/src/reactivity/rotation.ts +9 -3
  91. package/src/testing/test-transactor.ts +12 -0
  92. package/src/transaction/coordinator.ts +383 -154
  93. package/src/transactor/change-notifier.ts +19 -8
  94. package/src/transactor/network-transactor.ts +192 -29
  95. package/src/transactor/transactor.ts +16 -0
  96. package/src/transform/digest.ts +36 -3
@@ -1,11 +1,13 @@
1
1
  import { isConflictFailure, isExpiryFailure } from "../network/stale-failure.js";
2
2
  import { withBlockRevs } from "../network/durability.js";
3
3
  import { TransactionExpiredError } from "../network/transaction-expired-error.js";
4
+ import { TransactionTooLargeError } from "../network/transaction-size.js";
5
+ import { BlockTooLargeError, oversizedBlock } from "../network/block-size.js";
4
6
  import { TornActionError } from "../collection/struct.js";
5
7
  import { isTransactionExpired, clampPriority } from "./transaction.js";
6
8
  import { Log } from "../log/log.js";
7
9
  import { blockIdsForTransforms, copyTransforms } from "../transform/helpers.js";
8
- import { computeBlockContentDigests, blockDigestsField, baseRevsField } from "../transform/digest.js";
10
+ import { describeTouchedBlocks, blockDigestsField, baseRevsField } from "../transform/digest.js";
9
11
  import { collectOperations, hashOperations } from "./operations-hash.js";
10
12
  import { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from "./errors.js";
11
13
  import { recordCollectionDurability, transactionDurability } from "./durability.js";
@@ -22,23 +24,88 @@ const DefaultMaxBackoffMs = 5000;
22
24
  /**
23
25
  * A pend that failed. `conflict` marks the retryable class — an optimistic-concurrency collision that
24
26
  * a re-read + re-pend can clear — as decided by `isConflictFailure` over the failure response. A hard
25
- * rejection (storage full, policy) is NOT a conflict and is not worth re-driving. Thrown by
26
- * {@link TransactionCoordinator.pendCollection} so the fan-out in pendPhase can settle it and read
27
- * the flag off the rejection.
27
+ * rejection (storage full, policy) is NOT a conflict and is not worth re-driving. Built by
28
+ * {@link pendRefusalError} for one collection's pend, or for every collection of a batched one, and
29
+ * classified by {@link pendFailure}, which reads the flag off it.
28
30
  */
29
31
  class PendRejectedError extends Error {
30
32
  conflict;
31
- constructor(collectionId, conflict, reason,
33
+ constructor(collectionIds, conflict, reason,
32
34
  /** Confirmed revision the responder holds, from `StaleFailure.staleAt`. Folded into the
33
35
  * message because pendPhase collapses this error to its `.message` string, which is the only
34
36
  * form that reaches an embedder through the transaction result's `error` field. */
35
37
  staleAt) {
36
- super(`Pend failed for collection ${collectionId}: ${reason ?? (conflict ? 'stale conflict' : 'rejected')}`
38
+ super(`Pend failed for ${collectionIds.length === 1 ? 'collection' : 'collections'} ${collectionIds.join(', ')}: ${reason ?? (conflict ? 'stale conflict' : 'rejected')}`
37
39
  + (staleAt ? ` (block ${staleAt.blockId} at rev ${staleAt.rev})` : ''));
38
40
  this.conflict = conflict;
39
41
  this.name = 'PendRejectedError';
40
42
  }
41
43
  }
44
+ /** The error a refused pend of `collectionIds` stands for: its expiry — never retried, since a re-drive's
45
+ * expiration comes from the same clock — or a rejection carrying whether a re-read can clear it.
46
+ * Retryability comes from the response itself: a producer that classified the failure sets `conflict`,
47
+ * and only where none did is it inferred from `missing`/`pending` (`isConflictFailure`). */
48
+ function pendRefusalError(collectionIds, refusal) {
49
+ return isExpiryFailure(refusal)
50
+ ? new TransactionExpiredError(refusal.expired)
51
+ : new PendRejectedError(collectionIds, isConflictFailure(refusal), refusal.reason, refusal.staleAt);
52
+ }
53
+ /**
54
+ * The pend phase's failure for `reasons` — what every failed pend threw or stood for, at least one.
55
+ * The error text is the first reason's. The attempt is a retryable clean stale loss only if at least one
56
+ * reason was a conflicting pend ({@link PendRejectedError}`.conflict`) AND none was a hard failure: a
57
+ * single hard failure (storage/policy rejection, or a thrown/unavailable transactor) will not clear on a
58
+ * re-read, so re-driving it would just burn the retry budget. An expiry, and a pend or a block too large
59
+ * to send, are hard failures carried whole: each is the error the commit surfaces.
60
+ */
61
+ function pendFailure(reasons) {
62
+ const first = reasons[0];
63
+ const conflicts = reasons.filter(reason => reason instanceof PendRejectedError && reason.conflict);
64
+ const expired = reasons.find((reason) => reason instanceof TransactionExpiredError);
65
+ const tooLarge = reasons.find((reason) => reason instanceof TransactionTooLargeError || reason instanceof BlockTooLargeError);
66
+ return {
67
+ success: false,
68
+ error: first instanceof Error ? first.message : String(first),
69
+ staleLoss: conflicts.length > 0 && conflicts.length === reasons.length,
70
+ ...(expired === undefined ? {} : { expired }),
71
+ ...(tooLarge === undefined ? {} : { tooLarge }),
72
+ };
73
+ }
74
+ /**
75
+ * How `collectionId`'s commit ended when `result` answered its `request` — the answer to its own
76
+ * commit, or, in a batched commit, the batch's one answer for every collection of it. A success is
77
+ * stamped with the collection's own blocks at its own revision (`withBlockRevs`).
78
+ */
79
+ function collectionCommitOutcome(collectionId, request, result) {
80
+ if (result.success) {
81
+ return { collectionId, committed: true, durability: withBlockRevs(result.durability, request.blockIds, request.rev) };
82
+ }
83
+ if (isExpiryFailure(result)) {
84
+ // Not a stale loss: a re-drive's expiration comes from the same clock.
85
+ const expired = new TransactionExpiredError(result.expired);
86
+ return { collectionId, committed: false, error: expired.message, expired };
87
+ }
88
+ // Permanent stale failure: never retried verbatim. It IS a clean stale loss, though, so mark it
89
+ // retryable at the coordinator level (after a re-read advances the rev).
90
+ // NOTE: deliberately does NOT consult `isConflictFailure` / `StaleFailure.conflict` like the pend
91
+ // path does. Once the pend succeeded, a returned commit failure means the revision slot moved, or a
92
+ // member behind on the base refused — the durability gate's `commit-not-durable` (which does set
93
+ // `conflict`) or a solo StorageRepo's `missing-base-revision` (a bare `reason`, no `conflict`). All of
94
+ // these clear on a re-drive, so gating on `conflict` here would fail the last of them fast. One commit
95
+ // producer DOES set `conflict` now — db-p2p's CoordinatorRepo.commit returns lost commit-consensus
96
+ // races and classified stale-commit rejections as `{ success:false, conflict:true }` (returning, not
97
+ // throwing, is what keeps them out of commitCollection's verbatim retry) — but every returned failure
98
+ // still maps to `stale: true` here, and `isConflictFailure` covers that new shape, so no behavior
99
+ // change is needed. The one returned refusal that is NOT a stale loss, an expiry, is split off above.
100
+ // If a commit producer ever starts returning other hard commit rejections (validator policy, storage
101
+ // fault) as results too, gate `stale` on isConflictFailure here.
102
+ return {
103
+ collectionId,
104
+ committed: false,
105
+ stale: true,
106
+ error: result.reason ?? `Stale commit for collection ${collectionId}`
107
+ };
108
+ }
42
109
  /** What a successful commit wrote: `written` folded into one report, or `undefined` when it holds
43
110
  * nothing (nothing was staged, so there was no pend and no commit — the same hole
44
111
  * `Collection.sync` has). */
@@ -679,9 +746,9 @@ export class TransactionCoordinator {
679
746
  // the next refresh of that participant finds this transaction's own log entry, these are
680
747
  // the transforms that finish it (Collection.completeOwnEntry) — without them the refresh
681
748
  // can only refuse the write as torn, never save it. Copied, because until the restore
682
- // this is the participant's LIVE tracker state. No block digests are retained: they are
683
- // computed per commit from the live tracker (commitCollection), which is gone by the time
684
- // a refresh re-sends, and an undeclared block falls back to member-side corroboration.
749
+ // this is the participant's LIVE tracker state. No block digests are retained: the
750
+ // declaration taken before the pend (declareTouchedBlocks) stays inside coordinateTransaction,
751
+ // so a re-send declares none, and an undeclared block falls back to member-side corroboration.
685
752
  for (const { collectionId, collection } of collectionData) {
686
753
  if (committed.has(collectionId))
687
754
  continue;
@@ -771,6 +838,9 @@ export class TransactionCoordinator {
771
838
  if (coordResult.expired !== undefined) {
772
839
  throw coordResult.expired;
773
840
  }
841
+ if (coordResult.tooLarge !== undefined) {
842
+ throw coordResult.tooLarge;
843
+ }
774
844
  throw new Error(`Transaction commit failed: ${coordResult.error}`);
775
845
  }
776
846
  // Advance actionContext, fold the committed transforms into each
@@ -1269,6 +1339,13 @@ export class TransactionCoordinator {
1269
1339
  async coordinateTransaction(transaction, validation, collectionTransforms, criticalBlocks, pendedRevs) {
1270
1340
  const trxId = transaction.id;
1271
1341
  const t0 = Date.now();
1342
+ // Before anything is sent: one materialization of every block the transaction touches, measured
1343
+ // against MAX_BLOCK_BYTES here and declared on the commit below.
1344
+ const described = await this.declareTouchedBlocks(collectionTransforms);
1345
+ if (!described.success) {
1346
+ log('trx:phases trxId=%s refused before sending: %s', trxId, described.error);
1347
+ return described;
1348
+ }
1272
1349
  // 1. GATHER phase: collect critical cluster nominees (skip if single collection)
1273
1350
  const criticalBlockIds = Array.from(criticalBlocks.values());
1274
1351
  const tGather = Date.now();
@@ -1284,7 +1361,7 @@ export class TransactionCoordinator {
1284
1361
  }
1285
1362
  // 3. COMMIT phase: commit to all critical blocks (with retry for forward recovery)
1286
1363
  const tCommit = Date.now();
1287
- const commitResult = await this.commitPhase(transaction.id, criticalBlockIds, pendResult.pendedBlockIds, pendedRevs);
1364
+ const commitResult = await this.commitPhase(transaction.id, criticalBlockIds, pendResult.pendedBlockIds, pendedRevs, described.declared);
1288
1365
  const commitMs = Date.now() - tCommit;
1289
1366
  if (!commitResult.success) {
1290
1367
  // Targeted cancel: only cancel collections that are still pending (not already committed)
@@ -1338,9 +1415,39 @@ export class TransactionCoordinator {
1338
1415
  }, new Map());
1339
1416
  return new Set(byId.values());
1340
1417
  }
1418
+ /**
1419
+ * One local materialization of every block each collection's transforms touch
1420
+ * ({@link describeTouchedBlocks}), taken before anything is sent. A block the write would leave
1421
+ * over `MAX_BLOCK_BYTES` refuses the transaction here, as a pend-phase failure carrying the
1422
+ * {@link BlockTooLargeError} — the same shape as a pend too large to send, so `commit` throws it by
1423
+ * name and `execute` reports it as a failure. Otherwise each collection's digests are kept as its
1424
+ * commit's declaration ({@link commitRequestFor}), so the commit does not materialize again.
1425
+ *
1426
+ * Purely local: each collection's tracker holds this transaction's staged transforms until the commit
1427
+ * succeeds, under the instance latch the commit span holds, and the pend names its bases from the
1428
+ * same pins ({@link pendRequestFor}). A collection missing from the registry is skipped, for the pend
1429
+ * to report as it always has.
1430
+ */
1431
+ async declareTouchedBlocks(collectionTransforms) {
1432
+ const declared = new Map();
1433
+ for (const [collectionId, transforms] of collectionTransforms) {
1434
+ const collection = this.collections.get(collectionId);
1435
+ if (!collection)
1436
+ continue;
1437
+ const touched = await describeTouchedBlocks(collection.tracker, blockIdsForTransforms(transforms));
1438
+ const tooLarge = oversizedBlock(touched.bytes);
1439
+ if (tooLarge)
1440
+ return pendFailure([tooLarge]);
1441
+ declared.set(collectionId, touched.digests);
1442
+ }
1443
+ return { success: true, declared };
1444
+ }
1341
1445
  /**
1342
1446
  * PEND phase: Distribute transaction to all affected block clusters.
1343
1447
  *
1448
+ * Two or more collections go as ONE request when the transactor can send them so
1449
+ * ({@link pendTogether}); otherwise, and for one collection, each collection is pended on its own.
1450
+ *
1344
1451
  * @param transaction - The transaction being pended (its id names the action; its aged
1345
1452
  * priority rides on an unvalidated pend)
1346
1453
  * @param validation - What every pend carries for members to re-check, or undefined for an
@@ -1357,10 +1464,17 @@ export class TransactionCoordinator {
1357
1464
  }
1358
1465
  const actionId = transaction.id;
1359
1466
  const nominees = superclusterNominees ? Array.from(superclusterNominees) : undefined;
1467
+ // Both methods, never the pend alone: the batched pend's mark promises that the commit goes as one
1468
+ // request too (`PendRequest.soleReservation`), which only `commitMany` can keep.
1469
+ if (collectionTransforms.size > 1 && this.transactor.pendMany && this.transactor.commitMany) {
1470
+ const together = await this.pendTogether(transaction, validation, collectionTransforms, pendedRevs, actionId, nominees);
1471
+ if (together !== undefined)
1472
+ return together;
1473
+ }
1360
1474
  // A one-collection transaction pends once and commits that one collection (commitPhase), as a
1361
1475
  // `Collection.sync` write does, so its pend may say so (`PendRequest.soleReservation`). Two or
1362
- // more never may: each collection's commit lands on its own, and a late refusal of another
1363
- // collection's pend would surface after it.
1476
+ // more pended one by one never may: each collection's commit can land on its own, and a late
1477
+ // refusal of another collection's pend would surface after it.
1364
1478
  const sole = collectionTransforms.size === 1;
1365
1479
  // Fan out the independent per-collection pends concurrently. Each settles to a
1366
1480
  // { collectionId, blockIds } on success, or rejects with the per-collection reason.
@@ -1368,45 +1482,72 @@ export class TransactionCoordinator {
1368
1482
  // Transactions touch few collections today; if one ever spans very many, bound this
1369
1483
  // with a concurrency limiter so peak in-flight round-trips stays sane. Same for commitPhase.
1370
1484
  const outcomes = await Promise.allSettled(Array.from(collectionTransforms.entries()).map(([collectionId, transforms]) => this.pendCollection(transaction, validation, collectionId, transforms, pendedRevs.get(collectionId), actionId, nominees, sole)));
1371
- // Partition settled results: every collection that DID pend (keyed with its block
1372
- // ids), plus the first failure reason if any collection failed.
1485
+ // Partition settled results: every collection that DID pend (keyed with its block ids), and
1486
+ // every reason one did not, classified together (pendFailure) independent of iteration order.
1373
1487
  const pendedBlockIds = new Map();
1374
- let failure;
1375
- // Classify across ALL failures (mirroring commitPhase, and independent of iteration order):
1376
- // the pend is a retryable clean stale loss only if at least one failure was a conflicting pend
1377
- // (PendRejectedError.conflict) AND none was a hard failure. A single hard failure (storage/
1378
- // policy rejection, or a thrown/unavailable transactor) will not clear on a re-read, so
1379
- // re-driving it would just burn the retry budget — fail fast instead.
1380
- let anyConflict = false;
1381
- let anyHard = false;
1382
- // An expiry is a hard failure too, and is carried whole: it is the error the commit surfaces.
1383
- let expired;
1488
+ const reasons = [];
1384
1489
  for (const outcome of outcomes) {
1385
1490
  if (outcome.status === 'fulfilled') {
1386
1491
  pendedBlockIds.set(outcome.value.collectionId, outcome.value.blockIds);
1387
1492
  }
1388
1493
  else {
1389
- if (failure === undefined) {
1390
- failure = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
1391
- }
1392
- if (outcome.reason instanceof PendRejectedError && outcome.reason.conflict)
1393
- anyConflict = true;
1394
- else
1395
- anyHard = true;
1396
- if (outcome.reason instanceof TransactionExpiredError)
1397
- expired ??= outcome.reason;
1494
+ reasons.push(outcome.reason);
1398
1495
  }
1399
1496
  }
1400
- if (failure !== undefined) {
1497
+ if (reasons.length > 0) {
1401
1498
  // Any failure aborts the whole pend. With concurrency several collections may
1402
1499
  // have pended in parallel, so cancel EVERY successfully-pended collection — not
1403
1500
  // only those started before the failure. Cancels are best-effort (cancelPhase
1404
1501
  // swallows their errors) so they cannot mask the original pend failure.
1405
1502
  await this.cancelPhase(actionId, pendedBlockIds);
1406
- return { success: false, error: failure, staleLoss: anyConflict && !anyHard, ...(expired === undefined ? {} : { expired }) };
1503
+ return pendFailure(reasons);
1407
1504
  }
1408
1505
  return { success: true, pendedBlockIds };
1409
1506
  }
1507
+ /**
1508
+ * Pends every collection as ONE request ({@link ITransactor.pendMany}): one consensus record,
1509
+ * answered together. Every request is marked the action's only reservation
1510
+ * (`PendRequest.soleReservation`) — together they are, and their commit goes as one request to the
1511
+ * same coordinator ({@link commitTogether}) — so a coordinator may hold the pend's decision back for
1512
+ * the commit to carry, and a member that refuses any collection's pend late refuses the action's one
1513
+ * commit record before anything of it is durable.
1514
+ *
1515
+ * - **Success**: every collection is pended, with its own blocks.
1516
+ * - **Refusal**: classified as one collection's refusal is ({@link pendRefusalError}), once for the
1517
+ * batch. `pendMany` cancelled every block, so nothing is left pended.
1518
+ * - **Throw** (a transactor other than `NetworkTransactor`, which answers a throw with `undefined`):
1519
+ * a hard failure, as a thrown pend is. What was pended is unknown, so every collection's blocks are
1520
+ * cancelled.
1521
+ * - **`undefined`**: they could not go as one, and nothing of them is pended. {@link pendPhase} then
1522
+ * pends each collection on its own with requests rebuilt WITHOUT the mark. The marked requests are
1523
+ * never re-sent one by one: each carries every block of its collection, so `NetworkTransactor.pend`
1524
+ * would keep the mark, and one collection's late refusal could then surface after a sibling's commit
1525
+ * landed — the tear the mark exists to prevent. Also `undefined` when a collection is missing from
1526
+ * the registry, so that the per-collection path reports it as it always has.
1527
+ */
1528
+ async pendTogether(transaction, validation, collectionTransforms, pendedRevs, actionId, nominees) {
1529
+ const requests = [];
1530
+ for (const [collectionId, transforms] of collectionTransforms) {
1531
+ const collection = this.collections.get(collectionId);
1532
+ if (!collection)
1533
+ return undefined;
1534
+ requests.push(this.pendRequestFor(transaction, validation, collection, transforms, pendedRevs.get(collectionId), actionId, nominees, true));
1535
+ }
1536
+ const blockIds = new Map(Array.from(collectionTransforms, ([collectionId, transforms]) => [collectionId, blockIdsForTransforms(transforms)]));
1537
+ let result;
1538
+ try {
1539
+ result = await this.transactor.pendMany(requests);
1540
+ }
1541
+ catch (e) {
1542
+ await this.cancelPhase(actionId, blockIds);
1543
+ return pendFailure([e]);
1544
+ }
1545
+ if (result === undefined)
1546
+ return undefined;
1547
+ return result.success
1548
+ ? { success: true, pendedBlockIds: blockIds }
1549
+ : pendFailure([pendRefusalError(Array.from(collectionTransforms.keys()), result)]);
1550
+ }
1410
1551
  /**
1411
1552
  * Pend a single collection's transforms. Resolves with the collection id and its
1412
1553
  * pended block ids on success; throws with a per-collection reason on failure so the
@@ -1423,21 +1564,38 @@ export class TransactionCoordinator {
1423
1564
  if (!collection) {
1424
1565
  throw new Error(`Collection not found: ${collectionId}`);
1425
1566
  }
1426
- // Create the pend request. This is the only producer of PendRequest.validation, and it
1427
- // always sends the pair whole (transaction + operations hash) or not at all. The aged
1428
- // priority has one carrier per shape — inside the transaction when the pend carries it,
1429
- // on the pend itself when it does not — because a member's race resolution reads the
1430
- // transaction's priority first and falls back to the pend's (recordPriority in db-p2p's
1431
- // race-resolution.ts); an unvalidated pend that left both empty would never age. Omitted
1432
- // at 0, exactly as the single-collection path sends it (TransactorSource.transact), so
1433
- // the common first-attempt pend is indistinguishable from a Collection.sync pend.
1567
+ const pendResult = await this.transactor.pend(this.pendRequestFor(transaction, validation, collection, transforms, rev, actionId, nominees, sole));
1568
+ if (!pendResult.success) {
1569
+ throw pendRefusalError([collectionId], pendResult);
1570
+ }
1571
+ return { collectionId, blockIds: pendResult.blockIds };
1572
+ }
1573
+ /**
1574
+ * The pend request for one collection's transforms — the one place a pend request is built, whether it
1575
+ * goes on its own ({@link pendCollection}) or with its siblings ({@link pendTogether}).
1576
+ */
1577
+ pendRequestFor(transaction, validation, collection, transforms,
1578
+ /** The revision the log entry was stamped with (see {@link pendCollection}). */
1579
+ rev, actionId, nominees,
1580
+ /** Whether this request is the action's whole reservation, alone or with the siblings it is sent
1581
+ * with (`PendRequest.soleReservation`). */
1582
+ sole) {
1583
+ // This is the only producer of PendRequest.validation, and it always sends the pair whole
1584
+ // (transaction + operations hash) or not at all. The aged priority has one carrier per shape —
1585
+ // inside the transaction when the pend carries it, on the pend itself when it does not — because a
1586
+ // member's race resolution reads the transaction's priority first and falls back to the pend's
1587
+ // (recordPriority in db-p2p's race-resolution.ts); an unvalidated pend that left both empty would
1588
+ // never age. Omitted at 0, exactly as the single-collection path sends it
1589
+ // (TransactorSource.transact), so the common first-attempt pend is indistinguishable from a
1590
+ // Collection.sync pend.
1434
1591
  const priority = clampPriority(transaction.priority);
1435
1592
  // The base each update-only block's operations were computed against, read from the same
1436
- // tracker the commit side digests (commitCollection); it still holds this transaction's staged
1437
- // transforms and pins. Storage keeps it with the pending record so the record is never applied
1438
- // to a different version of the block (see PendRequest.baseRevs). Omitted when empty.
1593
+ // tracker the commit's declaration was taken from (declareTouchedBlocks); it still holds this
1594
+ // transaction's staged transforms and pins. Storage keeps it with the pending record so the
1595
+ // record is never applied to a different version of the block (see PendRequest.baseRevs).
1596
+ // Omitted when empty.
1439
1597
  const baseRevs = collection.tracker.stagedBaseRevs(blockIdsForTransforms(transforms));
1440
- const pendRequest = {
1598
+ return {
1441
1599
  actionId,
1442
1600
  rev,
1443
1601
  transforms,
@@ -1449,33 +1607,34 @@ export class TransactionCoordinator {
1449
1607
  superclusterNominees: nominees,
1450
1608
  ...(sole ? { soleReservation: true } : {})
1451
1609
  };
1452
- const pendResult = await this.transactor.pend(pendRequest);
1453
- if (!pendResult.success) {
1454
- if (isExpiryFailure(pendResult)) {
1455
- throw new TransactionExpiredError(pendResult.expired);
1456
- }
1457
- // Retryability comes from the response itself: a producer that classified the failure sets
1458
- // `conflict`, and only where no producer set it do we fall back to inferring from
1459
- // `missing`/`pending`. Either way a conflict is an optimistic-concurrency loss, clearable
1460
- // by a re-read; anything else is a hard rejection (storage/policy) that re-driving won't fix.
1461
- throw new PendRejectedError(collectionId, isConflictFailure(pendResult), pendResult.reason, pendResult.staleAt);
1462
- }
1463
- return { collectionId, blockIds: pendResult.blockIds };
1464
1610
  }
1465
1611
  /**
1466
1612
  * COMMIT phase: Commit to all critical blocks with retry for transient failures.
1467
1613
  *
1468
1614
  * Once all collections are pended (Phase 1 passes), the coordinator has decided
1469
- * to commit. Failed commits are retried (forward recovery) before giving up.
1470
- * Returns which collections committed vs failed so the caller can do targeted cancel.
1615
+ * to commit. Two or more collections go as ONE request when the transactor can send them so
1616
+ * ({@link commitTogether}); otherwise each collection commits on its own, its transient failures
1617
+ * retried (forward recovery) before giving up. Returns which collections committed vs failed so
1618
+ * the caller can do targeted cancel.
1471
1619
  */
1472
- async commitPhase(actionId, criticalBlockIds, pendedBlockIds, pendedRevs) {
1473
- // Fan out the independent per-collection commit-with-retry concurrently, then
1474
- // aggregate the committed/failed partition from the settled results.
1475
- const outcomes = await Promise.allSettled(Array.from(pendedBlockIds.entries()).map(([collectionId, blockIds]) => this.commitCollection(actionId, criticalBlockIds, collectionId, blockIds, pendedRevs.get(collectionId))));
1620
+ async commitPhase(actionId, criticalBlockIds, pendedBlockIds, pendedRevs, declared) {
1621
+ const together = pendedBlockIds.size > 1 && this.transactor.commitMany
1622
+ ? await this.commitTogether(actionId, criticalBlockIds, pendedBlockIds, pendedRevs, declared)
1623
+ : undefined;
1624
+ // NOTE: a fallback after a batched pend leaves the multi-collection residual in place: the
1625
+ // pend's decision may have been held back for a commit that now goes per collection, so a member
1626
+ // that refuses one collection's pend late can do so after a sibling collection's commit landed —
1627
+ // reported by forward recovery or `CoordinatorPartialCommitError`. Reached through a thrown
1628
+ // batched commit (`NetworkTransactor.commitMany` answers `undefined` for that). Anything else that
1629
+ // keeps a batch from going as one would have kept the batched pend from going too, except one
1630
+ // case: the coordinator `pendMany` cached for every block evicted before the commit ran (the
1631
+ // cache's TTL is at least a minute, its size cap 1000 transactions), so a live lookup can split
1632
+ // the blocks. If that ever shows up, pin the commit to the coordinator the batched pend answered
1633
+ // from. See docs/correctness.md §2 Definitions.
1634
+ const outcomes = together ?? await this.commitEach(actionId, criticalBlockIds, pendedBlockIds, pendedRevs, declared);
1476
1635
  const committedCollections = new Map();
1477
1636
  const failedCollections = new Set();
1478
- const errors = [];
1637
+ const errors = new Set();
1479
1638
  // Classify failures: a returned stale loss (someone committed a newer rev) is retryable after
1480
1639
  // a re-read; a thrown/transient-exhausted or structural failure is not. staleLoss holds only
1481
1640
  // if EVERY failure was a stale loss — a single hard failure makes the whole attempt not worth
@@ -1483,33 +1642,25 @@ export class TransactionCoordinator {
1483
1642
  let anyStale = false;
1484
1643
  let anyHard = false;
1485
1644
  let expired;
1486
- for (const outcome of outcomes) {
1487
- if (outcome.status === 'fulfilled') {
1488
- const result = outcome.value;
1489
- if (result.committed) {
1490
- committedCollections.set(result.collectionId, result.durability);
1491
- }
1492
- else {
1493
- failedCollections.add(result.collectionId);
1494
- errors.push(result.error);
1495
- if (result.stale)
1496
- anyStale = true;
1497
- else
1498
- anyHard = true;
1499
- expired ??= result.expired;
1500
- }
1645
+ for (const result of outcomes) {
1646
+ if (result.committed) {
1647
+ committedCollections.set(result.collectionId, result.durability);
1501
1648
  }
1502
1649
  else {
1503
- // commitCollection resolves rather than rejects, but treat any unexpected
1504
- // rejection as a (hard) failure so the partitioned sets stay honest.
1505
- errors.push(outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason));
1506
- anyHard = true;
1650
+ failedCollections.add(result.collectionId);
1651
+ // A set: a batched refusal answers every collection with the one reason.
1652
+ errors.add(result.error);
1653
+ if (result.stale)
1654
+ anyStale = true;
1655
+ else
1656
+ anyHard = true;
1657
+ expired ??= result.expired;
1507
1658
  }
1508
1659
  }
1509
- if (failedCollections.size > 0 || errors.length > 0) {
1660
+ if (failedCollections.size > 0) {
1510
1661
  return {
1511
1662
  success: false,
1512
- error: errors.join('; ') || 'Commit failed',
1663
+ error: Array.from(errors).join('; ') || 'Commit failed',
1513
1664
  committedCollections,
1514
1665
  failedCollections,
1515
1666
  staleLoss: anyStale && !anyHard,
@@ -1518,40 +1669,63 @@ export class TransactionCoordinator {
1518
1669
  }
1519
1670
  return { success: true, committedCollections, failedCollections };
1520
1671
  }
1672
+ /**
1673
+ * Commits every collection as ONE request ({@link ITransactor.commitMany}): one consensus record,
1674
+ * decided together — the commit half of {@link pendTogether}. Every collection gets the batch's one
1675
+ * answer ({@link collectionCommitOutcome}): committed, each stamped with its own blocks and revision;
1676
+ * or refused, every collection alike. A refused collection's attempt is then retained by
1677
+ * `commitOnceLatched`, and the refresh between attempts finishes any collection whose log entry did
1678
+ * land (`Collection.completeOwnEntry`) — the path a refused one-collection commit already takes.
1679
+ *
1680
+ * `undefined` when they could not go as one, when the request threw, or when a collection's request
1681
+ * could not be built (missing from the registry, or no log tail among its pended blocks):
1682
+ * {@link commitPhase} then commits each collection on its own, which re-sends everything and reports
1683
+ * a request it cannot build as it always has. The batch is never retried here: a returned refusal
1684
+ * cannot be won by the identical request, and a throw is the per-collection path's to retry.
1685
+ */
1686
+ async commitTogether(actionId, criticalBlockIds, pendedBlockIds, pendedRevs, declared) {
1687
+ const requests = [];
1688
+ for (const [collectionId, blockIds] of pendedBlockIds) {
1689
+ const request = this.commitRequestFor(actionId, criticalBlockIds, collectionId, blockIds, pendedRevs.get(collectionId), declared);
1690
+ if (typeof request === 'string')
1691
+ return undefined;
1692
+ requests.push({ collectionId, request });
1693
+ }
1694
+ let result;
1695
+ try {
1696
+ result = await this.transactor.commitMany(requests.map(({ request }) => request));
1697
+ }
1698
+ catch (e) {
1699
+ log('commitTogether: batched commit threw; committing each collection on its own actionId=%s: %o', actionId, e);
1700
+ return undefined;
1701
+ }
1702
+ return result === undefined
1703
+ ? undefined
1704
+ : requests.map(({ collectionId, request }) => collectionCommitOutcome(collectionId, request, result));
1705
+ }
1706
+ /** Commits each collection on its own, concurrently ({@link commitCollection}), one outcome per collection. */
1707
+ async commitEach(actionId, criticalBlockIds, pendedBlockIds, pendedRevs, declared) {
1708
+ const entries = Array.from(pendedBlockIds.entries());
1709
+ const settled = await Promise.allSettled(entries.map(([collectionId, blockIds]) => this.commitCollection(actionId, criticalBlockIds, collectionId, blockIds, pendedRevs.get(collectionId), declared)));
1710
+ // commitCollection resolves rather than rejects, but treat any unexpected rejection as a (hard)
1711
+ // failure of its collection so the partitioned sets stay honest.
1712
+ return settled.map((outcome, i) => outcome.status === 'fulfilled'
1713
+ ? outcome.value
1714
+ : { collectionId: entries[i][0], committed: false, error: outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason) });
1715
+ }
1521
1716
  /**
1522
1717
  * Commit a single collection's pended blocks, retrying transient failures up to three
1523
1718
  * times (forward recovery). Always resolves — success is carried in the returned
1524
1719
  * `committed` flag, with the commit's `durability` beside it — so the fan-out in
1525
- * {@link commitPhase} can aggregate every result.
1720
+ * {@link commitEach} can aggregate every result.
1526
1721
  */
1527
1722
  async commitCollection(actionId, criticalBlockIds, collectionId, blockIds,
1528
- /** The revision this collection PENDED at, threaded from the log append — the same bug
1529
- * family as pendCollection's: recomputing `getNextRev()` here, after the pend round
1530
- * trips, could stamp the CommitRequest with a different number than the pend named. */
1531
- rev) {
1532
- const collection = this.collections.get(collectionId);
1533
- if (!collection) {
1534
- return { collectionId, committed: false, error: `Collection not found: ${collectionId}` };
1723
+ /** The revision this collection PENDED at (see {@link commitRequestFor}). */
1724
+ rev, declared) {
1725
+ const commitRequest = this.commitRequestFor(actionId, criticalBlockIds, collectionId, blockIds, rev, declared);
1726
+ if (typeof commitRequest === 'string') {
1727
+ return { collectionId, committed: false, error: commitRequest };
1535
1728
  }
1536
- // Find the critical block (log tail) for this collection
1537
- const logTailBlockId = criticalBlockIds.find(blockId => blockIds.includes(blockId));
1538
- if (!logTailBlockId) {
1539
- return { collectionId, committed: false, error: `Log tail block not found for collection ${collectionId}` };
1540
- }
1541
- // Declare what each pended block will contain once committed. The collection's tracker still
1542
- // holds this transaction's staged transforms (it is reset only after commit succeeds) and
1543
- // layers over the collection's CacheSource, so this is a purely local computation; an id whose
1544
- // base is not cached is omitted and falls back to corroboration on the member side. Only the
1545
- // client can declare this — CoordinatorRepo.commit forwards without materializing.
1546
- const blockDigests = await computeBlockContentDigests(collection.tracker, blockIds);
1547
- // Create commit request
1548
- const commitRequest = {
1549
- actionId,
1550
- blockIds,
1551
- tailId: logTailBlockId,
1552
- rev,
1553
- ...blockDigestsField(blockDigests)
1554
- };
1555
1729
  // Retry ONLY transient/thrown failures (unreachable peers, timeout) — forward recovery.
1556
1730
  // A returned { success:false } is a refusal the IDENTICAL request can never win (a rival
1557
1731
  // committed a newer rev, or a member behind on the base refused and dropped its pending
@@ -1564,38 +1738,7 @@ export class TransactionCoordinator {
1564
1738
  let lastTransientError;
1565
1739
  for (let attempt = 0; attempt < 3; attempt++) {
1566
1740
  try {
1567
- const commitResult = await this.transactor.commit(commitRequest);
1568
- if (commitResult.success) {
1569
- return { collectionId, committed: true, durability: withBlockRevs(commitResult.durability, blockIds, rev) };
1570
- }
1571
- if (isExpiryFailure(commitResult)) {
1572
- // Not a stale loss: a re-drive's expiration comes from the same clock.
1573
- const expired = new TransactionExpiredError(commitResult.expired);
1574
- return { collectionId, committed: false, error: expired.message, expired };
1575
- }
1576
- // Permanent stale failure: do not retry here. It IS a clean stale loss, though, so
1577
- // mark it retryable at the coordinator level (after a re-read advances the rev).
1578
- // NOTE: deliberately does NOT consult `isConflictFailure` / `StaleFailure.conflict`
1579
- // like the pend path does. Once the pend succeeded, a returned commit failure means
1580
- // the revision slot moved, or a member behind on the base refused — the durability
1581
- // gate's `commit-not-durable` (which does set `conflict`) or a solo StorageRepo's
1582
- // `missing-base-revision` (a bare `reason`, no `conflict`). All of these clear on a
1583
- // re-drive, so gating on `conflict` here would fail the last of them fast. One commit
1584
- // producer DOES set `conflict` now —
1585
- // db-p2p's CoordinatorRepo.commit returns lost commit-consensus races and classified
1586
- // stale-commit rejections as `{ success:false, conflict:true }` (returning, not
1587
- // throwing, is what keeps them out of the verbatim retry above) — but every returned
1588
- // failure still maps to `stale: true` here, and `isConflictFailure` covers that new
1589
- // shape, so no behavior change is needed. The one returned refusal that is NOT a stale
1590
- // loss, an expiry, is split off above. If a commit producer ever starts returning other
1591
- // hard commit rejections (validator policy, storage fault) as results too, gate
1592
- // `stale` on isConflictFailure here.
1593
- return {
1594
- collectionId,
1595
- committed: false,
1596
- stale: true,
1597
- error: commitResult.reason ?? `Stale commit for collection ${collectionId}`
1598
- };
1741
+ return collectionCommitOutcome(collectionId, commitRequest, await this.transactor.commit(commitRequest));
1599
1742
  }
1600
1743
  catch (e) {
1601
1744
  lastTransientError = e instanceof Error ? e.message : String(e);
@@ -1603,6 +1746,37 @@ export class TransactionCoordinator {
1603
1746
  }
1604
1747
  return { collectionId, committed: false, error: `Commit failed for collection ${collectionId} after 3 attempts: ${lastTransientError}` };
1605
1748
  }
1749
+ /**
1750
+ * The commit request for one collection's pended blocks — the one place a commit request is built,
1751
+ * whether it goes on its own ({@link commitCollection}) or with its siblings ({@link commitTogether})
1752
+ * — or, as a string, why there is none.
1753
+ */
1754
+ commitRequestFor(actionId, criticalBlockIds, collectionId, blockIds,
1755
+ /** The revision this collection PENDED at, threaded from the log append — the same bug
1756
+ * family as pendCollection's: recomputing `getNextRev()` here, after the pend round
1757
+ * trips, could stamp the CommitRequest with a different number than the pend named. */
1758
+ rev, declared) {
1759
+ const collection = this.collections.get(collectionId);
1760
+ if (!collection) {
1761
+ return `Collection not found: ${collectionId}`;
1762
+ }
1763
+ // Find the critical block (log tail) for this collection
1764
+ const logTailBlockId = criticalBlockIds.find(blockId => blockIds.includes(blockId));
1765
+ if (!logTailBlockId) {
1766
+ return `Log tail block not found for collection ${collectionId}`;
1767
+ }
1768
+ // Declare what each pended block will contain once committed: the description taken before the
1769
+ // pend (declareTouchedBlocks), over the blocks the pend carried. An id whose base was not cached
1770
+ // is omitted and falls back to corroboration on the member side. Only the client can declare
1771
+ // this — CoordinatorRepo.commit forwards without materializing.
1772
+ return {
1773
+ actionId,
1774
+ blockIds,
1775
+ tailId: logTailBlockId,
1776
+ rev,
1777
+ ...blockDigestsField(declared.get(collectionId))
1778
+ };
1779
+ }
1606
1780
  /**
1607
1781
  * CANCEL phase: Cancel pending actions on affected blocks.
1608
1782
  *