@optimystic/db-core 1.18.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 +13 -4
  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 +13 -4
  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,16 +1,18 @@
1
- import type { ITransactor, BlockId, CollectionId, Transforms, PendRequest, CommitRequest, ActionId, WriteDurability } from "../index.js";
1
+ import type { ITransactor, BlockId, CollectionId, Transforms, PendRequest, PendResult, CommitRequest, CommitResult, WriteFailure, ActionId, WriteDurability, BlockContentDigests } from "../index.js";
2
2
  import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions, ReadDependency } from "./transaction.js";
3
3
  import type { PeerId } from "../network/types.js";
4
4
  import { isConflictFailure, isExpiryFailure } from "../network/stale-failure.js";
5
5
  import { withBlockRevs } from "../network/durability.js";
6
6
  import { TransactionExpiredError } from "../network/transaction-expired-error.js";
7
+ import { TransactionTooLargeError } from "../network/transaction-size.js";
8
+ import { BlockTooLargeError, oversizedBlock } from "../network/block-size.js";
7
9
  import type { Collection, CollectionSnapshot, RefreshReport } from "../collection/collection.js";
8
10
  import type { SyncOptions } from "../collection/index.js";
9
11
  import { TornActionError } from "../collection/struct.js";
10
12
  import { isTransactionExpired, clampPriority } from "./transaction.js";
11
13
  import { Log } from "../log/log.js";
12
14
  import { blockIdsForTransforms, copyTransforms } from "../transform/helpers.js";
13
- import { computeBlockContentDigests, blockDigestsField, baseRevsField } from "../transform/digest.js";
15
+ import { describeTouchedBlocks, blockDigestsField, baseRevsField } from "../transform/digest.js";
14
16
  import { collectOperations, hashOperations } from "./operations-hash.js";
15
17
  import { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from "./errors.js";
16
18
  import { recordCollectionDurability, transactionDurability, type TransactionDurability } from "./durability.js";
@@ -30,13 +32,13 @@ const DefaultMaxBackoffMs = 5000;
30
32
  /**
31
33
  * A pend that failed. `conflict` marks the retryable class — an optimistic-concurrency collision that
32
34
  * a re-read + re-pend can clear — as decided by `isConflictFailure` over the failure response. A hard
33
- * rejection (storage full, policy) is NOT a conflict and is not worth re-driving. Thrown by
34
- * {@link TransactionCoordinator.pendCollection} so the fan-out in pendPhase can settle it and read
35
- * the flag off the rejection.
35
+ * rejection (storage full, policy) is NOT a conflict and is not worth re-driving. Built by
36
+ * {@link pendRefusalError} for one collection's pend, or for every collection of a batched one, and
37
+ * classified by {@link pendFailure}, which reads the flag off it.
36
38
  */
37
39
  class PendRejectedError extends Error {
38
40
  constructor(
39
- collectionId: CollectionId,
41
+ collectionIds: readonly CollectionId[],
40
42
  readonly conflict: boolean,
41
43
  reason?: string,
42
44
  /** Confirmed revision the responder holds, from `StaleFailure.staleAt`. Folded into the
@@ -44,12 +46,54 @@ class PendRejectedError extends Error {
44
46
  * form that reaches an embedder through the transaction result's `error` field. */
45
47
  staleAt?: { blockId: BlockId; rev: number },
46
48
  ) {
47
- super(`Pend failed for collection ${collectionId}: ${reason ?? (conflict ? 'stale conflict' : 'rejected')}`
49
+ super(`Pend failed for ${collectionIds.length === 1 ? 'collection' : 'collections'} ${collectionIds.join(', ')}: ${reason ?? (conflict ? 'stale conflict' : 'rejected')}`
48
50
  + (staleAt ? ` (block ${staleAt.blockId} at rev ${staleAt.rev})` : ''));
49
51
  this.name = 'PendRejectedError';
50
52
  }
51
53
  }
52
54
 
55
+ /** The error a refused pend of `collectionIds` stands for: its expiry — never retried, since a re-drive's
56
+ * expiration comes from the same clock — or a rejection carrying whether a re-read can clear it.
57
+ * Retryability comes from the response itself: a producer that classified the failure sets `conflict`,
58
+ * and only where none did is it inferred from `missing`/`pending` (`isConflictFailure`). */
59
+ function pendRefusalError(collectionIds: readonly CollectionId[], refusal: WriteFailure): TransactionExpiredError | PendRejectedError {
60
+ return isExpiryFailure(refusal)
61
+ ? new TransactionExpiredError(refusal.expired)
62
+ : new PendRejectedError(collectionIds, isConflictFailure(refusal), refusal.reason, refusal.staleAt);
63
+ }
64
+
65
+ /** A transaction refused before anything was sent: its pend, or a block it would leave, too large to send. */
66
+ type TooLargeError = TransactionTooLargeError | BlockTooLargeError;
67
+
68
+ /** How the pend phase failed. */
69
+ type PendPhaseFailure = { success: false; error: string; staleLoss?: boolean; expired?: TransactionExpiredError; tooLarge?: TooLargeError };
70
+
71
+ /** Per collection, what its commit declares about its blocks (`CommitRequest.blockDigests`), described
72
+ * once before the pend ({@link TransactionCoordinator.declareTouchedBlocks}). */
73
+ type DeclaredDigests = ReadonlyMap<CollectionId, BlockContentDigests>;
74
+
75
+ /**
76
+ * The pend phase's failure for `reasons` — what every failed pend threw or stood for, at least one.
77
+ * The error text is the first reason's. The attempt is a retryable clean stale loss only if at least one
78
+ * reason was a conflicting pend ({@link PendRejectedError}`.conflict`) AND none was a hard failure: a
79
+ * single hard failure (storage/policy rejection, or a thrown/unavailable transactor) will not clear on a
80
+ * re-read, so re-driving it would just burn the retry budget. An expiry, and a pend or a block too large
81
+ * to send, are hard failures carried whole: each is the error the commit surfaces.
82
+ */
83
+ function pendFailure(reasons: readonly unknown[]): PendPhaseFailure {
84
+ const first = reasons[0];
85
+ const conflicts = reasons.filter(reason => reason instanceof PendRejectedError && reason.conflict);
86
+ const expired = reasons.find((reason): reason is TransactionExpiredError => reason instanceof TransactionExpiredError);
87
+ const tooLarge = reasons.find((reason): reason is TooLargeError => reason instanceof TransactionTooLargeError || reason instanceof BlockTooLargeError);
88
+ return {
89
+ success: false,
90
+ error: first instanceof Error ? first.message : String(first),
91
+ staleLoss: conflicts.length > 0 && conflicts.length === reasons.length,
92
+ ...(expired === undefined ? {} : { expired }),
93
+ ...(tooLarge === undefined ? {} : { tooLarge }),
94
+ };
95
+ }
96
+
53
97
  /**
54
98
  * What one {@link TransactionCoordinator.commit} call keeps across all of its attempts. Created
55
99
  * once per commit, filled in by each attempt and by the refresh between attempts, and read when
@@ -80,11 +124,48 @@ type CommitCycle = {
80
124
  saved: Map<CollectionId, WriteDurability | undefined>;
81
125
  };
82
126
 
83
- /** How one collection's commit ended ({@link TransactionCoordinator.commitCollection}). */
127
+ /** How one collection's commit ended ({@link TransactionCoordinator.commitCollection}, or its share of
128
+ * a batched commit's one answer). */
84
129
  type CollectionCommitOutcome =
85
130
  | { collectionId: CollectionId; committed: true; durability: WriteDurability }
86
131
  | { collectionId: CollectionId; committed: false; error: string; stale?: boolean; expired?: TransactionExpiredError };
87
132
 
133
+ /**
134
+ * How `collectionId`'s commit ended when `result` answered its `request` — the answer to its own
135
+ * commit, or, in a batched commit, the batch's one answer for every collection of it. A success is
136
+ * stamped with the collection's own blocks at its own revision (`withBlockRevs`).
137
+ */
138
+ function collectionCommitOutcome(collectionId: CollectionId, request: CommitRequest, result: CommitResult): CollectionCommitOutcome {
139
+ if (result.success) {
140
+ return { collectionId, committed: true, durability: withBlockRevs(result.durability, request.blockIds, request.rev) };
141
+ }
142
+ if (isExpiryFailure(result)) {
143
+ // Not a stale loss: a re-drive's expiration comes from the same clock.
144
+ const expired = new TransactionExpiredError(result.expired);
145
+ return { collectionId, committed: false, error: expired.message, expired };
146
+ }
147
+ // Permanent stale failure: never retried verbatim. It IS a clean stale loss, though, so mark it
148
+ // retryable at the coordinator level (after a re-read advances the rev).
149
+ // NOTE: deliberately does NOT consult `isConflictFailure` / `StaleFailure.conflict` like the pend
150
+ // path does. Once the pend succeeded, a returned commit failure means the revision slot moved, or a
151
+ // member behind on the base refused — the durability gate's `commit-not-durable` (which does set
152
+ // `conflict`) or a solo StorageRepo's `missing-base-revision` (a bare `reason`, no `conflict`). All of
153
+ // these clear on a re-drive, so gating on `conflict` here would fail the last of them fast. One commit
154
+ // producer DOES set `conflict` now — db-p2p's CoordinatorRepo.commit returns lost commit-consensus
155
+ // races and classified stale-commit rejections as `{ success:false, conflict:true }` (returning, not
156
+ // throwing, is what keeps them out of commitCollection's verbatim retry) — but every returned failure
157
+ // still maps to `stale: true` here, and `isConflictFailure` covers that new shape, so no behavior
158
+ // change is needed. The one returned refusal that is NOT a stale loss, an expiry, is split off above.
159
+ // If a commit producer ever starts returning other hard commit rejections (validator policy, storage
160
+ // fault) as results too, gate `stale` on isConflictFailure here.
161
+ return {
162
+ collectionId,
163
+ committed: false,
164
+ stale: true,
165
+ error: result.reason ?? `Stale commit for collection ${collectionId}`
166
+ };
167
+ }
168
+
88
169
  /** How one attempt's distributed phases ended ({@link TransactionCoordinator.coordinateTransaction}).
89
170
  * `committedCollections` carries who holds each collection that durably committed — every
90
171
  * participant on success, a subset (possibly empty) on failure. */
@@ -101,6 +182,9 @@ type CoordinationResult =
101
182
  /** Present when a pend or a commit was refused because the transaction had expired by the
102
183
  * cohort's clocks: the error the commit surfaces, never a stale loss. */
103
184
  expired?: TransactionExpiredError;
185
+ /** Present when the transaction was refused before anything was sent because its pend, or a block
186
+ * it would leave, was too large to send: the error the commit surfaces, never a stale loss. */
187
+ tooLarge?: TooLargeError;
104
188
  };
105
189
 
106
190
  /** What a successful commit wrote: `written` folded into one report, or `undefined` when it holds
@@ -814,9 +898,9 @@ export class TransactionCoordinator {
814
898
  // the next refresh of that participant finds this transaction's own log entry, these are
815
899
  // the transforms that finish it (Collection.completeOwnEntry) — without them the refresh
816
900
  // can only refuse the write as torn, never save it. Copied, because until the restore
817
- // this is the participant's LIVE tracker state. No block digests are retained: they are
818
- // computed per commit from the live tracker (commitCollection), which is gone by the time
819
- // a refresh re-sends, and an undeclared block falls back to member-side corroboration.
901
+ // this is the participant's LIVE tracker state. No block digests are retained: the
902
+ // declaration taken before the pend (declareTouchedBlocks) stays inside coordinateTransaction,
903
+ // so a re-send declares none, and an undeclared block falls back to member-side corroboration.
820
904
  for (const { collectionId, collection } of collectionData) {
821
905
  if (committed.has(collectionId)) continue;
822
906
  collection.retainInFlightAttempt(transaction.id, {
@@ -905,6 +989,9 @@ export class TransactionCoordinator {
905
989
  if (coordResult.expired !== undefined) {
906
990
  throw coordResult.expired;
907
991
  }
992
+ if (coordResult.tooLarge !== undefined) {
993
+ throw coordResult.tooLarge;
994
+ }
908
995
  throw new Error(`Transaction commit failed: ${coordResult.error}`);
909
996
  }
910
997
 
@@ -1471,6 +1558,14 @@ export class TransactionCoordinator {
1471
1558
  const trxId = transaction.id;
1472
1559
  const t0 = Date.now();
1473
1560
 
1561
+ // Before anything is sent: one materialization of every block the transaction touches, measured
1562
+ // against MAX_BLOCK_BYTES here and declared on the commit below.
1563
+ const described = await this.declareTouchedBlocks(collectionTransforms);
1564
+ if (!described.success) {
1565
+ log('trx:phases trxId=%s refused before sending: %s', trxId, described.error);
1566
+ return described;
1567
+ }
1568
+
1474
1569
  // 1. GATHER phase: collect critical cluster nominees (skip if single collection)
1475
1570
  const criticalBlockIds = Array.from(criticalBlocks.values());
1476
1571
  const tGather = Date.now();
@@ -1498,7 +1593,8 @@ export class TransactionCoordinator {
1498
1593
  transaction.id as ActionId,
1499
1594
  criticalBlockIds,
1500
1595
  pendResult.pendedBlockIds,
1501
- pendedRevs
1596
+ pendedRevs,
1597
+ described.declared
1502
1598
  );
1503
1599
  const commitMs = Date.now() - tCommit;
1504
1600
  if (!commitResult.success) {
@@ -1572,9 +1668,40 @@ export class TransactionCoordinator {
1572
1668
  return new Set(byId.values());
1573
1669
  }
1574
1670
 
1671
+ /**
1672
+ * One local materialization of every block each collection's transforms touch
1673
+ * ({@link describeTouchedBlocks}), taken before anything is sent. A block the write would leave
1674
+ * over `MAX_BLOCK_BYTES` refuses the transaction here, as a pend-phase failure carrying the
1675
+ * {@link BlockTooLargeError} — the same shape as a pend too large to send, so `commit` throws it by
1676
+ * name and `execute` reports it as a failure. Otherwise each collection's digests are kept as its
1677
+ * commit's declaration ({@link commitRequestFor}), so the commit does not materialize again.
1678
+ *
1679
+ * Purely local: each collection's tracker holds this transaction's staged transforms until the commit
1680
+ * succeeds, under the instance latch the commit span holds, and the pend names its bases from the
1681
+ * same pins ({@link pendRequestFor}). A collection missing from the registry is skipped, for the pend
1682
+ * to report as it always has.
1683
+ */
1684
+ private async declareTouchedBlocks(
1685
+ collectionTransforms: ReadonlyMap<CollectionId, Transforms>
1686
+ ): Promise<{ success: true; declared: DeclaredDigests } | PendPhaseFailure> {
1687
+ const declared = new Map<CollectionId, BlockContentDigests>();
1688
+ for (const [collectionId, transforms] of collectionTransforms) {
1689
+ const collection = this.collections.get(collectionId);
1690
+ if (!collection) continue;
1691
+ const touched = await describeTouchedBlocks(collection.tracker, blockIdsForTransforms(transforms));
1692
+ const tooLarge = oversizedBlock(touched.bytes);
1693
+ if (tooLarge) return pendFailure([tooLarge]);
1694
+ declared.set(collectionId, touched.digests);
1695
+ }
1696
+ return { success: true, declared };
1697
+ }
1698
+
1575
1699
  /**
1576
1700
  * PEND phase: Distribute transaction to all affected block clusters.
1577
1701
  *
1702
+ * Two or more collections go as ONE request when the transactor can send them so
1703
+ * ({@link pendTogether}); otherwise, and for one collection, each collection is pended on its own.
1704
+ *
1578
1705
  * @param transaction - The transaction being pended (its id names the action; its aged
1579
1706
  * priority rides on an unvalidated pend)
1580
1707
  * @param validation - What every pend carries for members to re-check, or undefined for an
@@ -1591,20 +1718,24 @@ export class TransactionCoordinator {
1591
1718
  collectionTransforms: ReadonlyMap<CollectionId, Transforms>,
1592
1719
  pendedRevs: ReadonlyMap<CollectionId, number>,
1593
1720
  superclusterNominees: ReadonlySet<PeerId> | null
1594
- ): Promise<
1595
- | { success: true; pendedBlockIds: Map<CollectionId, BlockId[]> }
1596
- | { success: false; error: string; staleLoss?: boolean; expired?: TransactionExpiredError }
1597
- > {
1721
+ ): Promise<{ success: true; pendedBlockIds: Map<CollectionId, BlockId[]> } | PendPhaseFailure> {
1598
1722
  if (collectionTransforms.size === 0) {
1599
1723
  return { success: false, error: 'No transforms to pend' };
1600
1724
  }
1601
1725
 
1602
1726
  const actionId = transaction.id as ActionId;
1603
1727
  const nominees = superclusterNominees ? Array.from(superclusterNominees) : undefined;
1728
+ // Both methods, never the pend alone: the batched pend's mark promises that the commit goes as one
1729
+ // request too (`PendRequest.soleReservation`), which only `commitMany` can keep.
1730
+ if (collectionTransforms.size > 1 && this.transactor.pendMany && this.transactor.commitMany) {
1731
+ const together = await this.pendTogether(transaction, validation, collectionTransforms, pendedRevs, actionId, nominees);
1732
+ if (together !== undefined) return together;
1733
+ }
1734
+
1604
1735
  // A one-collection transaction pends once and commits that one collection (commitPhase), as a
1605
1736
  // `Collection.sync` write does, so its pend may say so (`PendRequest.soleReservation`). Two or
1606
- // more never may: each collection's commit lands on its own, and a late refusal of another
1607
- // collection's pend would surface after it.
1737
+ // more pended one by one never may: each collection's commit can land on its own, and a late
1738
+ // refusal of another collection's pend would surface after it.
1608
1739
  const sole = collectionTransforms.size === 1;
1609
1740
 
1610
1741
  // Fan out the independent per-collection pends concurrently. Each settles to a
@@ -1618,44 +1749,80 @@ export class TransactionCoordinator {
1618
1749
  )
1619
1750
  );
1620
1751
 
1621
- // Partition settled results: every collection that DID pend (keyed with its block
1622
- // ids), plus the first failure reason if any collection failed.
1752
+ // Partition settled results: every collection that DID pend (keyed with its block ids), and
1753
+ // every reason one did not, classified together (pendFailure) independent of iteration order.
1623
1754
  const pendedBlockIds = new Map<CollectionId, BlockId[]>();
1624
- let failure: string | undefined;
1625
- // Classify across ALL failures (mirroring commitPhase, and independent of iteration order):
1626
- // the pend is a retryable clean stale loss only if at least one failure was a conflicting pend
1627
- // (PendRejectedError.conflict) AND none was a hard failure. A single hard failure (storage/
1628
- // policy rejection, or a thrown/unavailable transactor) will not clear on a re-read, so
1629
- // re-driving it would just burn the retry budget — fail fast instead.
1630
- let anyConflict = false;
1631
- let anyHard = false;
1632
- // An expiry is a hard failure too, and is carried whole: it is the error the commit surfaces.
1633
- let expired: TransactionExpiredError | undefined;
1755
+ const reasons: unknown[] = [];
1634
1756
  for (const outcome of outcomes) {
1635
1757
  if (outcome.status === 'fulfilled') {
1636
1758
  pendedBlockIds.set(outcome.value.collectionId, outcome.value.blockIds);
1637
1759
  } else {
1638
- if (failure === undefined) {
1639
- failure = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
1640
- }
1641
- if (outcome.reason instanceof PendRejectedError && outcome.reason.conflict) anyConflict = true;
1642
- else anyHard = true;
1643
- if (outcome.reason instanceof TransactionExpiredError) expired ??= outcome.reason;
1760
+ reasons.push(outcome.reason);
1644
1761
  }
1645
1762
  }
1646
1763
 
1647
- if (failure !== undefined) {
1764
+ if (reasons.length > 0) {
1648
1765
  // Any failure aborts the whole pend. With concurrency several collections may
1649
1766
  // have pended in parallel, so cancel EVERY successfully-pended collection — not
1650
1767
  // only those started before the failure. Cancels are best-effort (cancelPhase
1651
1768
  // swallows their errors) so they cannot mask the original pend failure.
1652
1769
  await this.cancelPhase(actionId, pendedBlockIds);
1653
- return { success: false, error: failure, staleLoss: anyConflict && !anyHard, ...(expired === undefined ? {} : { expired }) };
1770
+ return pendFailure(reasons);
1654
1771
  }
1655
1772
 
1656
1773
  return { success: true, pendedBlockIds };
1657
1774
  }
1658
1775
 
1776
+ /**
1777
+ * Pends every collection as ONE request ({@link ITransactor.pendMany}): one consensus record,
1778
+ * answered together. Every request is marked the action's only reservation
1779
+ * (`PendRequest.soleReservation`) — together they are, and their commit goes as one request to the
1780
+ * same coordinator ({@link commitTogether}) — so a coordinator may hold the pend's decision back for
1781
+ * the commit to carry, and a member that refuses any collection's pend late refuses the action's one
1782
+ * commit record before anything of it is durable.
1783
+ *
1784
+ * - **Success**: every collection is pended, with its own blocks.
1785
+ * - **Refusal**: classified as one collection's refusal is ({@link pendRefusalError}), once for the
1786
+ * batch. `pendMany` cancelled every block, so nothing is left pended.
1787
+ * - **Throw** (a transactor other than `NetworkTransactor`, which answers a throw with `undefined`):
1788
+ * a hard failure, as a thrown pend is. What was pended is unknown, so every collection's blocks are
1789
+ * cancelled.
1790
+ * - **`undefined`**: they could not go as one, and nothing of them is pended. {@link pendPhase} then
1791
+ * pends each collection on its own with requests rebuilt WITHOUT the mark. The marked requests are
1792
+ * never re-sent one by one: each carries every block of its collection, so `NetworkTransactor.pend`
1793
+ * would keep the mark, and one collection's late refusal could then surface after a sibling's commit
1794
+ * landed — the tear the mark exists to prevent. Also `undefined` when a collection is missing from
1795
+ * the registry, so that the per-collection path reports it as it always has.
1796
+ */
1797
+ private async pendTogether(
1798
+ transaction: Transaction,
1799
+ validation: PendRequest['validation'],
1800
+ collectionTransforms: ReadonlyMap<CollectionId, Transforms>,
1801
+ pendedRevs: ReadonlyMap<CollectionId, number>,
1802
+ actionId: ActionId,
1803
+ nominees: PeerId[] | undefined
1804
+ ): Promise<{ success: true; pendedBlockIds: Map<CollectionId, BlockId[]> } | PendPhaseFailure | undefined> {
1805
+ const requests: PendRequest[] = [];
1806
+ for (const [collectionId, transforms] of collectionTransforms) {
1807
+ const collection = this.collections.get(collectionId);
1808
+ if (!collection) return undefined;
1809
+ requests.push(this.pendRequestFor(transaction, validation, collection, transforms, pendedRevs.get(collectionId)!, actionId, nominees, true));
1810
+ }
1811
+ const blockIds = new Map(Array.from(collectionTransforms, ([collectionId, transforms]) => [collectionId, blockIdsForTransforms(transforms)]));
1812
+
1813
+ let result: PendResult | undefined;
1814
+ try {
1815
+ result = await this.transactor.pendMany!(requests);
1816
+ } catch (e) {
1817
+ await this.cancelPhase(actionId, blockIds);
1818
+ return pendFailure([e]);
1819
+ }
1820
+ if (result === undefined) return undefined;
1821
+ return result.success
1822
+ ? { success: true, pendedBlockIds: blockIds }
1823
+ : pendFailure([pendRefusalError(Array.from(collectionTransforms.keys()), result)]);
1824
+ }
1825
+
1659
1826
  /**
1660
1827
  * Pend a single collection's transforms. Resolves with the collection id and its
1661
1828
  * pended block ids on success; throws with a per-collection reason on failure so the
@@ -1680,21 +1847,49 @@ export class TransactionCoordinator {
1680
1847
  throw new Error(`Collection not found: ${collectionId}`);
1681
1848
  }
1682
1849
 
1683
- // Create the pend request. This is the only producer of PendRequest.validation, and it
1684
- // always sends the pair whole (transaction + operations hash) or not at all. The aged
1685
- // priority has one carrier per shape — inside the transaction when the pend carries it,
1686
- // on the pend itself when it does not — because a member's race resolution reads the
1687
- // transaction's priority first and falls back to the pend's (recordPriority in db-p2p's
1688
- // race-resolution.ts); an unvalidated pend that left both empty would never age. Omitted
1689
- // at 0, exactly as the single-collection path sends it (TransactorSource.transact), so
1690
- // the common first-attempt pend is indistinguishable from a Collection.sync pend.
1850
+ const pendResult = await this.transactor.pend(
1851
+ this.pendRequestFor(transaction, validation, collection, transforms, rev, actionId, nominees, sole)
1852
+ );
1853
+ if (!pendResult.success) {
1854
+ throw pendRefusalError([collectionId], pendResult);
1855
+ }
1856
+
1857
+ return { collectionId, blockIds: pendResult.blockIds };
1858
+ }
1859
+
1860
+ /**
1861
+ * The pend request for one collection's transforms — the one place a pend request is built, whether it
1862
+ * goes on its own ({@link pendCollection}) or with its siblings ({@link pendTogether}).
1863
+ */
1864
+ private pendRequestFor(
1865
+ transaction: Transaction,
1866
+ validation: PendRequest['validation'],
1867
+ collection: Collection<any>,
1868
+ transforms: Transforms,
1869
+ /** The revision the log entry was stamped with (see {@link pendCollection}). */
1870
+ rev: number,
1871
+ actionId: ActionId,
1872
+ nominees: PeerId[] | undefined,
1873
+ /** Whether this request is the action's whole reservation, alone or with the siblings it is sent
1874
+ * with (`PendRequest.soleReservation`). */
1875
+ sole: boolean
1876
+ ): PendRequest {
1877
+ // This is the only producer of PendRequest.validation, and it always sends the pair whole
1878
+ // (transaction + operations hash) or not at all. The aged priority has one carrier per shape —
1879
+ // inside the transaction when the pend carries it, on the pend itself when it does not — because a
1880
+ // member's race resolution reads the transaction's priority first and falls back to the pend's
1881
+ // (recordPriority in db-p2p's race-resolution.ts); an unvalidated pend that left both empty would
1882
+ // never age. Omitted at 0, exactly as the single-collection path sends it
1883
+ // (TransactorSource.transact), so the common first-attempt pend is indistinguishable from a
1884
+ // Collection.sync pend.
1691
1885
  const priority = clampPriority(transaction.priority);
1692
1886
  // The base each update-only block's operations were computed against, read from the same
1693
- // tracker the commit side digests (commitCollection); it still holds this transaction's staged
1694
- // transforms and pins. Storage keeps it with the pending record so the record is never applied
1695
- // to a different version of the block (see PendRequest.baseRevs). Omitted when empty.
1887
+ // tracker the commit's declaration was taken from (declareTouchedBlocks); it still holds this
1888
+ // transaction's staged transforms and pins. Storage keeps it with the pending record so the
1889
+ // record is never applied to a different version of the block (see PendRequest.baseRevs).
1890
+ // Omitted when empty.
1696
1891
  const baseRevs = collection.tracker.stagedBaseRevs(blockIdsForTransforms(transforms));
1697
- const pendRequest: PendRequest = {
1892
+ return {
1698
1893
  actionId,
1699
1894
  rev,
1700
1895
  transforms,
@@ -1706,34 +1901,23 @@ export class TransactionCoordinator {
1706
1901
  superclusterNominees: nominees,
1707
1902
  ...(sole ? { soleReservation: true as const } : {})
1708
1903
  };
1709
-
1710
- const pendResult = await this.transactor.pend(pendRequest);
1711
- if (!pendResult.success) {
1712
- if (isExpiryFailure(pendResult)) {
1713
- throw new TransactionExpiredError(pendResult.expired);
1714
- }
1715
- // Retryability comes from the response itself: a producer that classified the failure sets
1716
- // `conflict`, and only where no producer set it do we fall back to inferring from
1717
- // `missing`/`pending`. Either way a conflict is an optimistic-concurrency loss, clearable
1718
- // by a re-read; anything else is a hard rejection (storage/policy) that re-driving won't fix.
1719
- throw new PendRejectedError(collectionId, isConflictFailure(pendResult), pendResult.reason, pendResult.staleAt);
1720
- }
1721
-
1722
- return { collectionId, blockIds: pendResult.blockIds };
1723
1904
  }
1724
1905
 
1725
1906
  /**
1726
1907
  * COMMIT phase: Commit to all critical blocks with retry for transient failures.
1727
1908
  *
1728
1909
  * Once all collections are pended (Phase 1 passes), the coordinator has decided
1729
- * to commit. Failed commits are retried (forward recovery) before giving up.
1730
- * Returns which collections committed vs failed so the caller can do targeted cancel.
1910
+ * to commit. Two or more collections go as ONE request when the transactor can send them so
1911
+ * ({@link commitTogether}); otherwise each collection commits on its own, its transient failures
1912
+ * retried (forward recovery) before giving up. Returns which collections committed vs failed so
1913
+ * the caller can do targeted cancel.
1731
1914
  */
1732
1915
  private async commitPhase(
1733
1916
  actionId: ActionId,
1734
1917
  criticalBlockIds: BlockId[],
1735
1918
  pendedBlockIds: Map<CollectionId, BlockId[]>,
1736
- pendedRevs: ReadonlyMap<CollectionId, number>
1919
+ pendedRevs: ReadonlyMap<CollectionId, number>,
1920
+ declared: DeclaredDigests
1737
1921
  ): Promise<{
1738
1922
  success: boolean;
1739
1923
  error?: string;
@@ -1743,17 +1927,24 @@ export class TransactionCoordinator {
1743
1927
  staleLoss?: boolean;
1744
1928
  expired?: TransactionExpiredError;
1745
1929
  }> {
1746
- // Fan out the independent per-collection commit-with-retry concurrently, then
1747
- // aggregate the committed/failed partition from the settled results.
1748
- const outcomes = await Promise.allSettled(
1749
- Array.from(pendedBlockIds.entries()).map(([collectionId, blockIds]) =>
1750
- this.commitCollection(actionId, criticalBlockIds, collectionId, blockIds, pendedRevs.get(collectionId)!)
1751
- )
1752
- );
1930
+ const together = pendedBlockIds.size > 1 && this.transactor.commitMany
1931
+ ? await this.commitTogether(actionId, criticalBlockIds, pendedBlockIds, pendedRevs, declared)
1932
+ : undefined;
1933
+ // NOTE: a fallback after a batched pend leaves the multi-collection residual in place: the
1934
+ // pend's decision may have been held back for a commit that now goes per collection, so a member
1935
+ // that refuses one collection's pend late can do so after a sibling collection's commit landed —
1936
+ // reported by forward recovery or `CoordinatorPartialCommitError`. Reached through a thrown
1937
+ // batched commit (`NetworkTransactor.commitMany` answers `undefined` for that). Anything else that
1938
+ // keeps a batch from going as one would have kept the batched pend from going too, except one
1939
+ // case: the coordinator `pendMany` cached for every block evicted before the commit ran (the
1940
+ // cache's TTL is at least a minute, its size cap 1000 transactions), so a live lookup can split
1941
+ // the blocks. If that ever shows up, pin the commit to the coordinator the batched pend answered
1942
+ // from. See docs/correctness.md §2 Definitions.
1943
+ const outcomes = together ?? await this.commitEach(actionId, criticalBlockIds, pendedBlockIds, pendedRevs, declared);
1753
1944
 
1754
1945
  const committedCollections = new Map<CollectionId, WriteDurability>();
1755
1946
  const failedCollections = new Set<CollectionId>();
1756
- const errors: string[] = [];
1947
+ const errors = new Set<string>();
1757
1948
  // Classify failures: a returned stale loss (someone committed a newer rev) is retryable after
1758
1949
  // a re-read; a thrown/transient-exhausted or structural failure is not. staleLoss holds only
1759
1950
  // if EVERY failure was a stale loss — a single hard failure makes the whole attempt not worth
@@ -1761,29 +1952,22 @@ export class TransactionCoordinator {
1761
1952
  let anyStale = false;
1762
1953
  let anyHard = false;
1763
1954
  let expired: TransactionExpiredError | undefined;
1764
- for (const outcome of outcomes) {
1765
- if (outcome.status === 'fulfilled') {
1766
- const result = outcome.value;
1767
- if (result.committed) {
1768
- committedCollections.set(result.collectionId, result.durability);
1769
- } else {
1770
- failedCollections.add(result.collectionId);
1771
- errors.push(result.error);
1772
- if (result.stale) anyStale = true; else anyHard = true;
1773
- expired ??= result.expired;
1774
- }
1955
+ for (const result of outcomes) {
1956
+ if (result.committed) {
1957
+ committedCollections.set(result.collectionId, result.durability);
1775
1958
  } else {
1776
- // commitCollection resolves rather than rejects, but treat any unexpected
1777
- // rejection as a (hard) failure so the partitioned sets stay honest.
1778
- errors.push(outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason));
1779
- anyHard = true;
1959
+ failedCollections.add(result.collectionId);
1960
+ // A set: a batched refusal answers every collection with the one reason.
1961
+ errors.add(result.error);
1962
+ if (result.stale) anyStale = true; else anyHard = true;
1963
+ expired ??= result.expired;
1780
1964
  }
1781
1965
  }
1782
1966
 
1783
- if (failedCollections.size > 0 || errors.length > 0) {
1967
+ if (failedCollections.size > 0) {
1784
1968
  return {
1785
1969
  success: false,
1786
- error: errors.join('; ') || 'Commit failed',
1970
+ error: Array.from(errors).join('; ') || 'Commit failed',
1787
1971
  committedCollections,
1788
1972
  failedCollections,
1789
1973
  staleLoss: anyStale && !anyHard,
@@ -1794,49 +1978,85 @@ export class TransactionCoordinator {
1794
1978
  return { success: true, committedCollections, failedCollections };
1795
1979
  }
1796
1980
 
1981
+ /**
1982
+ * Commits every collection as ONE request ({@link ITransactor.commitMany}): one consensus record,
1983
+ * decided together — the commit half of {@link pendTogether}. Every collection gets the batch's one
1984
+ * answer ({@link collectionCommitOutcome}): committed, each stamped with its own blocks and revision;
1985
+ * or refused, every collection alike. A refused collection's attempt is then retained by
1986
+ * `commitOnceLatched`, and the refresh between attempts finishes any collection whose log entry did
1987
+ * land (`Collection.completeOwnEntry`) — the path a refused one-collection commit already takes.
1988
+ *
1989
+ * `undefined` when they could not go as one, when the request threw, or when a collection's request
1990
+ * could not be built (missing from the registry, or no log tail among its pended blocks):
1991
+ * {@link commitPhase} then commits each collection on its own, which re-sends everything and reports
1992
+ * a request it cannot build as it always has. The batch is never retried here: a returned refusal
1993
+ * cannot be won by the identical request, and a throw is the per-collection path's to retry.
1994
+ */
1995
+ private async commitTogether(
1996
+ actionId: ActionId,
1997
+ criticalBlockIds: BlockId[],
1998
+ pendedBlockIds: Map<CollectionId, BlockId[]>,
1999
+ pendedRevs: ReadonlyMap<CollectionId, number>,
2000
+ declared: DeclaredDigests
2001
+ ): Promise<CollectionCommitOutcome[] | undefined> {
2002
+ const requests: { collectionId: CollectionId; request: CommitRequest }[] = [];
2003
+ for (const [collectionId, blockIds] of pendedBlockIds) {
2004
+ const request = this.commitRequestFor(actionId, criticalBlockIds, collectionId, blockIds, pendedRevs.get(collectionId)!, declared);
2005
+ if (typeof request === 'string') return undefined;
2006
+ requests.push({ collectionId, request });
2007
+ }
2008
+
2009
+ let result: CommitResult | undefined;
2010
+ try {
2011
+ result = await this.transactor.commitMany!(requests.map(({ request }) => request));
2012
+ } catch (e) {
2013
+ log('commitTogether: batched commit threw; committing each collection on its own actionId=%s: %o', actionId, e);
2014
+ return undefined;
2015
+ }
2016
+ return result === undefined
2017
+ ? undefined
2018
+ : requests.map(({ collectionId, request }) => collectionCommitOutcome(collectionId, request, result));
2019
+ }
2020
+
2021
+ /** Commits each collection on its own, concurrently ({@link commitCollection}), one outcome per collection. */
2022
+ private async commitEach(
2023
+ actionId: ActionId,
2024
+ criticalBlockIds: BlockId[],
2025
+ pendedBlockIds: Map<CollectionId, BlockId[]>,
2026
+ pendedRevs: ReadonlyMap<CollectionId, number>,
2027
+ declared: DeclaredDigests
2028
+ ): Promise<CollectionCommitOutcome[]> {
2029
+ const entries = Array.from(pendedBlockIds.entries());
2030
+ const settled = await Promise.allSettled(entries.map(([collectionId, blockIds]) =>
2031
+ this.commitCollection(actionId, criticalBlockIds, collectionId, blockIds, pendedRevs.get(collectionId)!, declared)
2032
+ ));
2033
+ // commitCollection resolves rather than rejects, but treat any unexpected rejection as a (hard)
2034
+ // failure of its collection so the partitioned sets stay honest.
2035
+ return settled.map((outcome, i) => outcome.status === 'fulfilled'
2036
+ ? outcome.value
2037
+ : { collectionId: entries[i]![0], committed: false, error: outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason) });
2038
+ }
2039
+
1797
2040
  /**
1798
2041
  * Commit a single collection's pended blocks, retrying transient failures up to three
1799
2042
  * times (forward recovery). Always resolves — success is carried in the returned
1800
2043
  * `committed` flag, with the commit's `durability` beside it — so the fan-out in
1801
- * {@link commitPhase} can aggregate every result.
2044
+ * {@link commitEach} can aggregate every result.
1802
2045
  */
1803
2046
  private async commitCollection(
1804
2047
  actionId: ActionId,
1805
2048
  criticalBlockIds: BlockId[],
1806
2049
  collectionId: CollectionId,
1807
2050
  blockIds: BlockId[],
1808
- /** The revision this collection PENDED at, threaded from the log append — the same bug
1809
- * family as pendCollection's: recomputing `getNextRev()` here, after the pend round
1810
- * trips, could stamp the CommitRequest with a different number than the pend named. */
1811
- rev: number
2051
+ /** The revision this collection PENDED at (see {@link commitRequestFor}). */
2052
+ rev: number,
2053
+ declared: DeclaredDigests
1812
2054
  ): Promise<CollectionCommitOutcome> {
1813
- const collection = this.collections.get(collectionId);
1814
- if (!collection) {
1815
- return { collectionId, committed: false, error: `Collection not found: ${collectionId}` };
2055
+ const commitRequest = this.commitRequestFor(actionId, criticalBlockIds, collectionId, blockIds, rev, declared);
2056
+ if (typeof commitRequest === 'string') {
2057
+ return { collectionId, committed: false, error: commitRequest };
1816
2058
  }
1817
2059
 
1818
- // Find the critical block (log tail) for this collection
1819
- const logTailBlockId = criticalBlockIds.find(blockId => blockIds.includes(blockId));
1820
- if (!logTailBlockId) {
1821
- return { collectionId, committed: false, error: `Log tail block not found for collection ${collectionId}` };
1822
- }
1823
-
1824
- // Declare what each pended block will contain once committed. The collection's tracker still
1825
- // holds this transaction's staged transforms (it is reset only after commit succeeds) and
1826
- // layers over the collection's CacheSource, so this is a purely local computation; an id whose
1827
- // base is not cached is omitted and falls back to corroboration on the member side. Only the
1828
- // client can declare this — CoordinatorRepo.commit forwards without materializing.
1829
- const blockDigests = await computeBlockContentDigests(collection.tracker, blockIds);
1830
-
1831
- // Create commit request
1832
- const commitRequest: CommitRequest = {
1833
- actionId,
1834
- blockIds,
1835
- tailId: logTailBlockId,
1836
- rev,
1837
- ...blockDigestsField(blockDigests)
1838
- };
1839
-
1840
2060
  // Retry ONLY transient/thrown failures (unreachable peers, timeout) — forward recovery.
1841
2061
  // A returned { success:false } is a refusal the IDENTICAL request can never win (a rival
1842
2062
  // committed a newer rev, or a member behind on the base refused and dropped its pending
@@ -1849,38 +2069,7 @@ export class TransactionCoordinator {
1849
2069
  let lastTransientError: string | undefined;
1850
2070
  for (let attempt = 0; attempt < 3; attempt++) {
1851
2071
  try {
1852
- const commitResult = await this.transactor.commit(commitRequest);
1853
- if (commitResult.success) {
1854
- return { collectionId, committed: true, durability: withBlockRevs(commitResult.durability, blockIds, rev) };
1855
- }
1856
- if (isExpiryFailure(commitResult)) {
1857
- // Not a stale loss: a re-drive's expiration comes from the same clock.
1858
- const expired = new TransactionExpiredError(commitResult.expired);
1859
- return { collectionId, committed: false, error: expired.message, expired };
1860
- }
1861
- // Permanent stale failure: do not retry here. It IS a clean stale loss, though, so
1862
- // mark it retryable at the coordinator level (after a re-read advances the rev).
1863
- // NOTE: deliberately does NOT consult `isConflictFailure` / `StaleFailure.conflict`
1864
- // like the pend path does. Once the pend succeeded, a returned commit failure means
1865
- // the revision slot moved, or a member behind on the base refused — the durability
1866
- // gate's `commit-not-durable` (which does set `conflict`) or a solo StorageRepo's
1867
- // `missing-base-revision` (a bare `reason`, no `conflict`). All of these clear on a
1868
- // re-drive, so gating on `conflict` here would fail the last of them fast. One commit
1869
- // producer DOES set `conflict` now —
1870
- // db-p2p's CoordinatorRepo.commit returns lost commit-consensus races and classified
1871
- // stale-commit rejections as `{ success:false, conflict:true }` (returning, not
1872
- // throwing, is what keeps them out of the verbatim retry above) — but every returned
1873
- // failure still maps to `stale: true` here, and `isConflictFailure` covers that new
1874
- // shape, so no behavior change is needed. The one returned refusal that is NOT a stale
1875
- // loss, an expiry, is split off above. If a commit producer ever starts returning other
1876
- // hard commit rejections (validator policy, storage fault) as results too, gate
1877
- // `stale` on isConflictFailure here.
1878
- return {
1879
- collectionId,
1880
- committed: false,
1881
- stale: true,
1882
- error: commitResult.reason ?? `Stale commit for collection ${collectionId}`
1883
- };
2072
+ return collectionCommitOutcome(collectionId, commitRequest, await this.transactor.commit(commitRequest));
1884
2073
  } catch (e) {
1885
2074
  lastTransientError = e instanceof Error ? e.message : String(e);
1886
2075
  }
@@ -1888,6 +2077,46 @@ export class TransactionCoordinator {
1888
2077
  return { collectionId, committed: false, error: `Commit failed for collection ${collectionId} after 3 attempts: ${lastTransientError}` };
1889
2078
  }
1890
2079
 
2080
+ /**
2081
+ * The commit request for one collection's pended blocks — the one place a commit request is built,
2082
+ * whether it goes on its own ({@link commitCollection}) or with its siblings ({@link commitTogether})
2083
+ * — or, as a string, why there is none.
2084
+ */
2085
+ private commitRequestFor(
2086
+ actionId: ActionId,
2087
+ criticalBlockIds: BlockId[],
2088
+ collectionId: CollectionId,
2089
+ blockIds: BlockId[],
2090
+ /** The revision this collection PENDED at, threaded from the log append — the same bug
2091
+ * family as pendCollection's: recomputing `getNextRev()` here, after the pend round
2092
+ * trips, could stamp the CommitRequest with a different number than the pend named. */
2093
+ rev: number,
2094
+ declared: DeclaredDigests
2095
+ ): CommitRequest | string {
2096
+ const collection = this.collections.get(collectionId);
2097
+ if (!collection) {
2098
+ return `Collection not found: ${collectionId}`;
2099
+ }
2100
+
2101
+ // Find the critical block (log tail) for this collection
2102
+ const logTailBlockId = criticalBlockIds.find(blockId => blockIds.includes(blockId));
2103
+ if (!logTailBlockId) {
2104
+ return `Log tail block not found for collection ${collectionId}`;
2105
+ }
2106
+
2107
+ // Declare what each pended block will contain once committed: the description taken before the
2108
+ // pend (declareTouchedBlocks), over the blocks the pend carried. An id whose base was not cached
2109
+ // is omitted and falls back to corroboration on the member side. Only the client can declare
2110
+ // this — CoordinatorRepo.commit forwards without materializing.
2111
+ return {
2112
+ actionId,
2113
+ blockIds,
2114
+ tailId: logTailBlockId,
2115
+ rev,
2116
+ ...blockDigestsField(declared.get(collectionId))
2117
+ };
2118
+ }
2119
+
1891
2120
  /**
1892
2121
  * CANCEL phase: Cancel pending actions on affected blocks.
1893
2122
  *