@optimystic/db-core 1.18.0 → 1.20.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 (229) 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/cluster/structs.d.ts +41 -8
  19. package/dist/src/cluster/structs.d.ts.map +1 -1
  20. package/dist/src/cluster/structs.js +18 -7
  21. package/dist/src/cluster/structs.js.map +1 -1
  22. package/dist/src/collection/action.d.ts +29 -0
  23. package/dist/src/collection/action.d.ts.map +1 -1
  24. package/dist/src/collection/action.js +6 -0
  25. package/dist/src/collection/action.js.map +1 -1
  26. package/dist/src/collection/collection.d.ts +566 -120
  27. package/dist/src/collection/collection.d.ts.map +1 -1
  28. package/dist/src/collection/collection.js +1084 -495
  29. package/dist/src/collection/collection.js.map +1 -1
  30. package/dist/src/collection/head-commit.d.ts +110 -0
  31. package/dist/src/collection/head-commit.d.ts.map +1 -0
  32. package/dist/src/collection/head-commit.js +65 -0
  33. package/dist/src/collection/head-commit.js.map +1 -0
  34. package/dist/src/collection/index.d.ts +2 -0
  35. package/dist/src/collection/index.d.ts.map +1 -1
  36. package/dist/src/collection/index.js +2 -0
  37. package/dist/src/collection/index.js.map +1 -1
  38. package/dist/src/collection/segments.d.ts +77 -0
  39. package/dist/src/collection/segments.d.ts.map +1 -0
  40. package/dist/src/collection/segments.js +110 -0
  41. package/dist/src/collection/segments.js.map +1 -0
  42. package/dist/src/collection/struct.d.ts +176 -1
  43. package/dist/src/collection/struct.d.ts.map +1 -1
  44. package/dist/src/collection/struct.js +70 -0
  45. package/dist/src/collection/struct.js.map +1 -1
  46. package/dist/src/collection/write-attempts.d.ts +245 -0
  47. package/dist/src/collection/write-attempts.d.ts.map +1 -0
  48. package/dist/src/collection/write-attempts.js +439 -0
  49. package/dist/src/collection/write-attempts.js.map +1 -0
  50. package/dist/src/collections/tree/struct.d.ts +100 -17
  51. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  52. package/dist/src/collections/tree/struct.js +38 -7
  53. package/dist/src/collections/tree/struct.js.map +1 -1
  54. package/dist/src/collections/tree/tree.d.ts +17 -5
  55. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  56. package/dist/src/collections/tree/tree.js +117 -29
  57. package/dist/src/collections/tree/tree.js.map +1 -1
  58. package/dist/src/index.d.ts +2 -0
  59. package/dist/src/index.d.ts.map +1 -1
  60. package/dist/src/index.js +2 -0
  61. package/dist/src/index.js.map +1 -1
  62. package/dist/src/log/log.d.ts +5 -1
  63. package/dist/src/log/log.d.ts.map +1 -1
  64. package/dist/src/log/log.js +7 -1
  65. package/dist/src/log/log.js.map +1 -1
  66. package/dist/src/network/block-size.d.ts +67 -0
  67. package/dist/src/network/block-size.d.ts.map +1 -0
  68. package/dist/src/network/block-size.js +82 -0
  69. package/dist/src/network/block-size.js.map +1 -0
  70. package/dist/src/network/i-repo.d.ts +3 -0
  71. package/dist/src/network/i-repo.d.ts.map +1 -1
  72. package/dist/src/network/index.d.ts +5 -0
  73. package/dist/src/network/index.d.ts.map +1 -1
  74. package/dist/src/network/index.js +5 -0
  75. package/dist/src/network/index.js.map +1 -1
  76. package/dist/src/network/promise-shortfall-error.d.ts +40 -0
  77. package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
  78. package/dist/src/network/promise-shortfall-error.js +67 -0
  79. package/dist/src/network/promise-shortfall-error.js.map +1 -0
  80. package/dist/src/network/refuse-solo.d.ts +8 -0
  81. package/dist/src/network/refuse-solo.d.ts.map +1 -0
  82. package/dist/src/network/refuse-solo.js +8 -0
  83. package/dist/src/network/refuse-solo.js.map +1 -0
  84. package/dist/src/network/stale-failure.d.ts +20 -3
  85. package/dist/src/network/stale-failure.d.ts.map +1 -1
  86. package/dist/src/network/stale-failure.js +24 -3
  87. package/dist/src/network/stale-failure.js.map +1 -1
  88. package/dist/src/network/struct.d.ts +161 -13
  89. package/dist/src/network/struct.d.ts.map +1 -1
  90. package/dist/src/network/struct.js.map +1 -1
  91. package/dist/src/network/transaction-size.d.ts +59 -0
  92. package/dist/src/network/transaction-size.d.ts.map +1 -0
  93. package/dist/src/network/transaction-size.js +74 -0
  94. package/dist/src/network/transaction-size.js.map +1 -0
  95. package/dist/src/network/validity-rejected-error.d.ts +28 -0
  96. package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
  97. package/dist/src/network/validity-rejected-error.js +51 -0
  98. package/dist/src/network/validity-rejected-error.js.map +1 -0
  99. package/dist/src/offline/entry.d.ts +72 -0
  100. package/dist/src/offline/entry.d.ts.map +1 -0
  101. package/dist/src/offline/entry.js +73 -0
  102. package/dist/src/offline/entry.js.map +1 -0
  103. package/dist/src/offline/index.d.ts +5 -0
  104. package/dist/src/offline/index.d.ts.map +1 -0
  105. package/dist/src/offline/index.js +5 -0
  106. package/dist/src/offline/index.js.map +1 -0
  107. package/dist/src/offline/journal.d.ts +61 -0
  108. package/dist/src/offline/journal.d.ts.map +1 -0
  109. package/dist/src/offline/journal.js +2 -0
  110. package/dist/src/offline/journal.js.map +1 -0
  111. package/dist/src/offline/queue.d.ts +484 -0
  112. package/dist/src/offline/queue.d.ts.map +1 -0
  113. package/dist/src/offline/queue.js +1236 -0
  114. package/dist/src/offline/queue.js.map +1 -0
  115. package/dist/src/offline/reachability.d.ts +25 -0
  116. package/dist/src/offline/reachability.d.ts.map +1 -0
  117. package/dist/src/offline/reachability.js +13 -0
  118. package/dist/src/offline/reachability.js.map +1 -0
  119. package/dist/src/offline/status.d.ts +148 -0
  120. package/dist/src/offline/status.d.ts.map +1 -0
  121. package/dist/src/offline/status.js +63 -0
  122. package/dist/src/offline/status.js.map +1 -0
  123. package/dist/src/offline/wake.d.ts +30 -0
  124. package/dist/src/offline/wake.d.ts.map +1 -0
  125. package/dist/src/offline/wake.js +68 -0
  126. package/dist/src/offline/wake.js.map +1 -0
  127. package/dist/src/reactivity/config.d.ts +8 -4
  128. package/dist/src/reactivity/config.d.ts.map +1 -1
  129. package/dist/src/reactivity/config.js +7 -3
  130. package/dist/src/reactivity/config.js.map +1 -1
  131. package/dist/src/reactivity/rotation.d.ts +9 -3
  132. package/dist/src/reactivity/rotation.d.ts.map +1 -1
  133. package/dist/src/reactivity/rotation.js +8 -2
  134. package/dist/src/reactivity/rotation.js.map +1 -1
  135. package/dist/src/testing/test-transactor.d.ts +31 -0
  136. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  137. package/dist/src/testing/test-transactor.js +60 -0
  138. package/dist/src/testing/test-transactor.js.map +1 -1
  139. package/dist/src/transaction/commit-failure-class.d.ts +103 -0
  140. package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
  141. package/dist/src/transaction/commit-failure-class.js +96 -0
  142. package/dist/src/transaction/commit-failure-class.js.map +1 -0
  143. package/dist/src/transaction/coordinator.d.ts +224 -31
  144. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  145. package/dist/src/transaction/coordinator.js +841 -362
  146. package/dist/src/transaction/coordinator.js.map +1 -1
  147. package/dist/src/transaction/entry-commit.d.ts +139 -0
  148. package/dist/src/transaction/entry-commit.d.ts.map +1 -0
  149. package/dist/src/transaction/entry-commit.js +199 -0
  150. package/dist/src/transaction/entry-commit.js.map +1 -0
  151. package/dist/src/transaction/index.d.ts +4 -1
  152. package/dist/src/transaction/index.d.ts.map +1 -1
  153. package/dist/src/transaction/index.js +1 -0
  154. package/dist/src/transaction/index.js.map +1 -1
  155. package/dist/src/transaction/transaction.d.ts +20 -0
  156. package/dist/src/transaction/transaction.d.ts.map +1 -1
  157. package/dist/src/transaction/validator.d.ts +7 -0
  158. package/dist/src/transaction/validator.d.ts.map +1 -1
  159. package/dist/src/transaction/validator.js +21 -12
  160. package/dist/src/transaction/validator.js.map +1 -1
  161. package/dist/src/transactor/change-notifier.d.ts +13 -4
  162. package/dist/src/transactor/change-notifier.d.ts.map +1 -1
  163. package/dist/src/transactor/change-notifier.js.map +1 -1
  164. package/dist/src/transactor/network-transactor.d.ts +58 -8
  165. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  166. package/dist/src/transactor/network-transactor.js +244 -50
  167. package/dist/src/transactor/network-transactor.js.map +1 -1
  168. package/dist/src/transactor/transactor-source.d.ts +22 -11
  169. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  170. package/dist/src/transactor/transactor-source.js +9 -13
  171. package/dist/src/transactor/transactor-source.js.map +1 -1
  172. package/dist/src/transactor/transactor.d.ts +14 -0
  173. package/dist/src/transactor/transactor.d.ts.map +1 -1
  174. package/dist/src/transform/digest.d.ts +20 -0
  175. package/dist/src/transform/digest.d.ts.map +1 -1
  176. package/dist/src/transform/digest.js +23 -3
  177. package/dist/src/transform/digest.js.map +1 -1
  178. package/dist/src/utility/visit-every.d.ts +14 -0
  179. package/dist/src/utility/visit-every.d.ts.map +1 -0
  180. package/dist/src/utility/visit-every.js +27 -0
  181. package/dist/src/utility/visit-every.js.map +1 -0
  182. package/package.json +1 -1
  183. package/src/blocks/helpers.ts +8 -1
  184. package/src/btree/btree.ts +266 -88
  185. package/src/btree/node-division.ts +155 -0
  186. package/src/chain/chain.ts +55 -6
  187. package/src/cluster/structs.ts +42 -7
  188. package/src/collection/action.ts +34 -0
  189. package/src/collection/collection.ts +1167 -540
  190. package/src/collection/head-commit.ts +148 -0
  191. package/src/collection/index.ts +2 -0
  192. package/src/collection/segments.ts +149 -0
  193. package/src/collection/struct.ts +201 -1
  194. package/src/collection/write-attempts.ts +506 -0
  195. package/src/collections/tree/struct.ts +97 -17
  196. package/src/collections/tree/tree.ts +129 -31
  197. package/src/index.ts +2 -0
  198. package/src/log/log.ts +7 -1
  199. package/src/network/block-size.ts +81 -0
  200. package/src/network/i-repo.ts +3 -0
  201. package/src/network/index.ts +5 -0
  202. package/src/network/promise-shortfall-error.ts +69 -0
  203. package/src/network/refuse-solo.ts +7 -0
  204. package/src/network/stale-failure.ts +27 -4
  205. package/src/network/struct.ts +169 -15
  206. package/src/network/transaction-size.ts +73 -0
  207. package/src/network/validity-rejected-error.ts +55 -0
  208. package/src/offline/entry.ts +127 -0
  209. package/src/offline/index.ts +4 -0
  210. package/src/offline/journal.ts +60 -0
  211. package/src/offline/queue.ts +1342 -0
  212. package/src/offline/reachability.ts +32 -0
  213. package/src/offline/status.ts +183 -0
  214. package/src/offline/wake.ts +67 -0
  215. package/src/reactivity/config.ts +8 -4
  216. package/src/reactivity/rotation.ts +9 -3
  217. package/src/testing/test-transactor.ts +65 -0
  218. package/src/transaction/commit-failure-class.ts +133 -0
  219. package/src/transaction/coordinator.ts +969 -393
  220. package/src/transaction/entry-commit.ts +285 -0
  221. package/src/transaction/index.ts +4 -0
  222. package/src/transaction/transaction.ts +21 -0
  223. package/src/transaction/validator.ts +22 -12
  224. package/src/transactor/change-notifier.ts +13 -4
  225. package/src/transactor/network-transactor.ts +252 -55
  226. package/src/transactor/transactor-source.ts +29 -13
  227. package/src/transactor/transactor.ts +16 -0
  228. package/src/transform/digest.ts +36 -3
  229. package/src/utility/visit-every.ts +25 -0
@@ -1,20 +1,30 @@
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
+ import type { BlockBaseRevs } from "../network/struct.js";
2
3
  import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions, ReadDependency } from "./transaction.js";
3
4
  import type { PeerId } from "../network/types.js";
4
- import { isConflictFailure, isExpiryFailure } from "../network/stale-failure.js";
5
+ import { isConflictFailure, isExpiryFailure, isRejectedFailure, isShortfallFailure } from "../network/stale-failure.js";
5
6
  import { withBlockRevs } from "../network/durability.js";
6
7
  import { TransactionExpiredError } from "../network/transaction-expired-error.js";
8
+ import { PromiseShortfallError } from "../network/promise-shortfall-error.js";
9
+ import { ValidityRejectedError } from "../network/validity-rejected-error.js";
10
+ import { refuseSoloField } from "../network/refuse-solo.js";
11
+ import { TransactionTooLargeError } from "../network/transaction-size.js";
12
+ import { BlockTooLargeError, oversizedBlock } from "../network/block-size.js";
7
13
  import type { Collection, CollectionSnapshot, RefreshReport } from "../collection/collection.js";
8
- import type { SyncOptions } from "../collection/index.js";
14
+ import type { InFlightCycle, SyncOptions } from "../collection/index.js";
15
+ import type { StagedAttempt } from "../collection/write-attempts.js";
9
16
  import { TornActionError } from "../collection/struct.js";
10
17
  import { isTransactionExpired, clampPriority } from "./transaction.js";
18
+ import { EntryParticipants, writeContextOf } from "./entry-commit.js";
19
+ import type { EntryCommit, RefreshParticipant, WriteContext } from "./entry-commit.js";
11
20
  import { Log } from "../log/log.js";
12
21
  import { blockIdsForTransforms, copyTransforms } from "../transform/helpers.js";
13
- import { computeBlockContentDigests, blockDigestsField, baseRevsField } from "../transform/digest.js";
22
+ import { describeTouchedBlocks, blockDigestsField, baseRevsField } from "../transform/digest.js";
14
23
  import { collectOperations, hashOperations } from "./operations-hash.js";
15
24
  import { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from "./errors.js";
16
25
  import { recordCollectionDurability, transactionDurability, type TransactionDurability } from "./durability.js";
17
26
  import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
27
+ import { visitEveryThenThrow } from "../utility/visit-every.js";
18
28
  import { createLogger } from "../logger.js";
19
29
 
20
30
  const log = createLogger('trx:coordinator');
@@ -30,13 +40,13 @@ const DefaultMaxBackoffMs = 5000;
30
40
  /**
31
41
  * A pend that failed. `conflict` marks the retryable class — an optimistic-concurrency collision that
32
42
  * 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.
43
+ * rejection (storage full, policy) is NOT a conflict and is not worth re-driving. Built by
44
+ * {@link pendRefusalError} for one collection's pend, or for every collection of a batched one, and
45
+ * classified by {@link pendFailure}, which reads the flag off it.
36
46
  */
37
47
  class PendRejectedError extends Error {
38
48
  constructor(
39
- collectionId: CollectionId,
49
+ collectionIds: readonly CollectionId[],
40
50
  readonly conflict: boolean,
41
51
  reason?: string,
42
52
  /** Confirmed revision the responder holds, from `StaleFailure.staleAt`. Folded into the
@@ -44,12 +54,90 @@ class PendRejectedError extends Error {
44
54
  * form that reaches an embedder through the transaction result's `error` field. */
45
55
  staleAt?: { blockId: BlockId; rev: number },
46
56
  ) {
47
- super(`Pend failed for collection ${collectionId}: ${reason ?? (conflict ? 'stale conflict' : 'rejected')}`
57
+ super(`Pend failed for ${collectionIds.length === 1 ? 'collection' : 'collections'} ${collectionIds.join(', ')}: ${reason ?? (conflict ? 'stale conflict' : 'rejected')}`
48
58
  + (staleAt ? ` (block ${staleAt.blockId} at rev ${staleAt.rev})` : ''));
49
59
  this.name = 'PendRejectedError';
50
60
  }
51
61
  }
52
62
 
63
+ /** The error a refused pend of `collectionIds` stands for: its validity rejection — never retried, since
64
+ * a re-drive sends the same content to the same checks — its expiry — never retried, since a re-drive's
65
+ * expiration comes from the same clock — or its promise shortfall — never retried, since a re-drive
66
+ * meets the same silent members — or a rejection carrying whether a re-read can clear it.
67
+ * Retryability comes from the response itself: a producer that classified the failure sets `conflict`,
68
+ * and only where none did is it inferred from `missing`/`pending` (`isConflictFailure`). */
69
+ function pendRefusalError(collectionIds: readonly CollectionId[], refusal: WriteFailure): ValidityRejectedError | TransactionExpiredError | PromiseShortfallError | PendRejectedError {
70
+ if (isRejectedFailure(refusal)) return new ValidityRejectedError(refusal.rejected);
71
+ if (isExpiryFailure(refusal)) return new TransactionExpiredError(refusal.expired);
72
+ if (isShortfallFailure(refusal)) return new PromiseShortfallError(refusal.shortfall);
73
+ return new PendRejectedError(collectionIds, isConflictFailure(refusal), refusal.reason, refusal.staleAt);
74
+ }
75
+
76
+ /** A transaction refused before anything was sent: its pend, or a block it would leave, too large to send. */
77
+ type TooLargeError = TransactionTooLargeError | BlockTooLargeError;
78
+
79
+ /** How the pend phase failed. */
80
+ type PendPhaseFailure = { success: false; error: string; staleLoss?: boolean; rejected?: ValidityRejectedError; expired?: TransactionExpiredError; shortfall?: PromiseShortfallError; tooLarge?: TooLargeError };
81
+
82
+ /**
83
+ * One collection's share of an attempt, as the phases send it. For a transaction's attempt it is
84
+ * described from the live tracker after the log append ({@link TransactionCoordinator.declareTouchedBlocks});
85
+ * for a queued entry's it is read off the head commit's `StagedAttempt` ({@link collectionAttemptOf}),
86
+ * which `stageAttempt` described the same way.
87
+ */
88
+ type CollectionAttempt = {
89
+ readonly transforms: Transforms;
90
+ /** The log tail block its entry was appended to — the critical block, committed first. */
91
+ readonly tailId: BlockId;
92
+ /** The revision its log entry was stamped with: the ONE number the pend, the commit and the
93
+ * local record must all repeat. Captured at the append, never recomputed after a round trip. */
94
+ readonly rev: number;
95
+ /** The base each of its update-only blocks' operations were computed against
96
+ * (`PendRequest.baseRevs`), from the tracker's pins. */
97
+ readonly baseRevs: BlockBaseRevs;
98
+ /** What its commit declares about its blocks (`CommitRequest.blockDigests`), or `undefined` when
99
+ * nothing could be described. */
100
+ readonly blockDigests: BlockContentDigests | undefined;
101
+ };
102
+
103
+ /** A head commit's staged attempt as the phases send it: its transforms are the attempt tracker's. */
104
+ function collectionAttemptOf(staged: StagedAttempt): CollectionAttempt {
105
+ return {
106
+ transforms: staged.tracker.transforms,
107
+ tailId: staged.tailId,
108
+ rev: staged.rev,
109
+ baseRevs: staged.baseRevs,
110
+ blockDigests: staged.blockDigests,
111
+ };
112
+ }
113
+
114
+ /**
115
+ * The pend phase's failure for `reasons` — what every failed pend threw or stood for, at least one.
116
+ * The error text is the first reason's. The attempt is a retryable clean stale loss only if at least one
117
+ * reason was a conflicting pend ({@link PendRejectedError}`.conflict`) AND none was a hard failure: a
118
+ * single hard failure (storage/policy rejection, or a thrown/unavailable transactor) will not clear on a
119
+ * re-read, so re-driving it would just burn the retry budget. A validity rejection, an expiry, a promise
120
+ * shortfall, and a pend or a block too large to send, are hard failures carried whole: each is the error
121
+ * the commit surfaces.
122
+ */
123
+ function pendFailure(reasons: readonly unknown[]): PendPhaseFailure {
124
+ const first = reasons[0];
125
+ const conflicts = reasons.filter(reason => reason instanceof PendRejectedError && reason.conflict);
126
+ const rejected = reasons.find((reason): reason is ValidityRejectedError => reason instanceof ValidityRejectedError);
127
+ const expired = reasons.find((reason): reason is TransactionExpiredError => reason instanceof TransactionExpiredError);
128
+ const shortfall = reasons.find((reason): reason is PromiseShortfallError => reason instanceof PromiseShortfallError);
129
+ const tooLarge = reasons.find((reason): reason is TooLargeError => reason instanceof TransactionTooLargeError || reason instanceof BlockTooLargeError);
130
+ return {
131
+ success: false,
132
+ error: first instanceof Error ? first.message : String(first),
133
+ staleLoss: conflicts.length > 0 && conflicts.length === reasons.length,
134
+ ...(rejected === undefined ? {} : { rejected }),
135
+ ...(expired === undefined ? {} : { expired }),
136
+ ...(shortfall === undefined ? {} : { shortfall }),
137
+ ...(tooLarge === undefined ? {} : { tooLarge }),
138
+ };
139
+ }
140
+
53
141
  /**
54
142
  * What one {@link TransactionCoordinator.commit} call keeps across all of its attempts. Created
55
143
  * once per commit, filled in by each attempt and by the refresh between attempts, and read when
@@ -78,13 +166,59 @@ type CommitCycle = {
78
166
  * carries who holds it, `undefined` where the refresh that saved it could not say (see
79
167
  * {@link TransactionDurability}). */
80
168
  saved: Map<CollectionId, WriteDurability | undefined>;
169
+ /** What every send of the commit carries ({@link InFlightCycle}) — recorded with each
170
+ * participant's in-flight mark, so a refresh that finishes a torn attempt re-sends it on the same
171
+ * terms, and read into every attempt's {@link WriteContext}. Taken from the commit's options. */
172
+ readonly inFlight: InFlightCycle;
81
173
  };
82
174
 
83
- /** How one collection's commit ended ({@link TransactionCoordinator.commitCollection}). */
175
+ /** What a commit's `options` ask of every send of its cycle. */
176
+ function inFlightCycleOf(options: SyncOptions | undefined): InFlightCycle {
177
+ return options?.refuseSoloCommit === true ? { refuseSolo: true } : {};
178
+ }
179
+
180
+ /** How one collection's commit ended ({@link TransactionCoordinator.commitCollection}, or its share of
181
+ * a batched commit's one answer). */
84
182
  type CollectionCommitOutcome =
85
183
  | { collectionId: CollectionId; committed: true; durability: WriteDurability }
86
184
  | { collectionId: CollectionId; committed: false; error: string; stale?: boolean; expired?: TransactionExpiredError };
87
185
 
186
+ /**
187
+ * How `collectionId`'s commit ended when `result` answered its `request` — the answer to its own
188
+ * commit, or, in a batched commit, the batch's one answer for every collection of it. A success is
189
+ * stamped with the collection's own blocks at its own revision (`withBlockRevs`).
190
+ */
191
+ function collectionCommitOutcome(collectionId: CollectionId, request: CommitRequest, result: CommitResult): CollectionCommitOutcome {
192
+ if (result.success) {
193
+ return { collectionId, committed: true, durability: withBlockRevs(result.durability, request.blockIds, request.rev) };
194
+ }
195
+ if (isExpiryFailure(result)) {
196
+ // Not a stale loss: a re-drive's expiration comes from the same clock.
197
+ const expired = new TransactionExpiredError(result.expired);
198
+ return { collectionId, committed: false, error: expired.message, expired };
199
+ }
200
+ // Permanent stale failure: never retried verbatim. It IS a clean stale loss, though, so mark it
201
+ // retryable at the coordinator level (after a re-read advances the rev).
202
+ // NOTE: deliberately does NOT consult `isConflictFailure` / `StaleFailure.conflict` like the pend
203
+ // path does. Once the pend succeeded, a returned commit failure means the revision slot moved, or a
204
+ // member behind on the base refused — the durability gate's `commit-not-durable` (which does set
205
+ // `conflict`) or a solo StorageRepo's `missing-base-revision` (a bare `reason`, no `conflict`). All of
206
+ // these clear on a re-drive, so gating on `conflict` here would fail the last of them fast. One commit
207
+ // producer DOES set `conflict` now — db-p2p's CoordinatorRepo.commit returns lost commit-consensus
208
+ // races and classified stale-commit rejections as `{ success:false, conflict:true }` (returning, not
209
+ // throwing, is what keeps them out of commitCollection's verbatim retry) — but every returned failure
210
+ // still maps to `stale: true` here, and `isConflictFailure` covers that new shape, so no behavior
211
+ // change is needed. The one returned refusal that is NOT a stale loss, an expiry, is split off above.
212
+ // If a commit producer ever starts returning other hard commit rejections (validator policy, storage
213
+ // fault) as results too, gate `stale` on isConflictFailure here.
214
+ return {
215
+ collectionId,
216
+ committed: false,
217
+ stale: true,
218
+ error: result.reason ?? `Stale commit for collection ${collectionId}`
219
+ };
220
+ }
221
+
88
222
  /** How one attempt's distributed phases ended ({@link TransactionCoordinator.coordinateTransaction}).
89
223
  * `committedCollections` carries who holds each collection that durably committed — every
90
224
  * participant on success, a subset (possibly empty) on failure. */
@@ -98,9 +232,18 @@ type CoordinationResult =
98
232
  /** True when the failure was a clean optimistic-concurrency conflict (stale loss / pending
99
233
  * contention) with nothing durable — i.e. safe to re-drive after a re-read. */
100
234
  staleLoss?: boolean;
235
+ /** Present when a pend was refused because the members that sank it judged the transaction
236
+ * invalid: the error the commit surfaces, never a stale loss. */
237
+ rejected?: ValidityRejectedError;
101
238
  /** Present when a pend or a commit was refused because the transaction had expired by the
102
239
  * cohort's clocks: the error the commit surfaces, never a stale loss. */
103
240
  expired?: TransactionExpiredError;
241
+ /** Present when a pend was refused because too few cohort members answered its promise round:
242
+ * the error the commit surfaces, never a stale loss. */
243
+ shortfall?: PromiseShortfallError;
244
+ /** Present when the transaction was refused before anything was sent because its pend, or a block
245
+ * it would leave, was too large to send: the error the commit surfaces, never a stale loss. */
246
+ tooLarge?: TooLargeError;
104
247
  };
105
248
 
106
249
  /** What a successful commit wrote: `written` folded into one report, or `undefined` when it holds
@@ -110,6 +253,135 @@ function writtenDurability(written: ReadonlyMap<CollectionId, WriteDurability |
110
253
  return written.size === 0 ? undefined : transactionDurability(written);
111
254
  }
112
255
 
256
+ /**
257
+ * The error an attempt whose phases failed with NOTHING committed is thrown as. A clean stale loss
258
+ * — every refusal a conflict a re-read can clear — is {@link CoordinatorStaleLossError}, which the
259
+ * retry loop re-drives. The four refusals a re-drive can never clear are thrown by name: a validity
260
+ * rejection (the retry's pend would send the same content to the same checks), an expiry (the
261
+ * retry's expiration comes from the same clock), a promise shortfall (the retry meets the same
262
+ * silent members), and a pend or block too large to send. Anything else is a plain error, the
263
+ * historical fail-fast for a hard failure.
264
+ */
265
+ function cleanFailureError(result: CoordinationResult & { success: false }, failed: readonly CollectionId[]): Error {
266
+ if (result.staleLoss) {
267
+ return new CoordinatorStaleLossError(failed, result.error);
268
+ }
269
+ return result.rejected ?? result.expired ?? result.shortfall ?? result.tooLarge
270
+ ?? new Error(`Transaction commit failed: ${result.error}`);
271
+ }
272
+
273
+ /**
274
+ * What one retry cycle ({@link TransactionCoordinator.commitAttempts}) drives: a transaction's
275
+ * whole-collection commit ({@link TransactionCoordinator.commit}) or a queued entry's slice commit
276
+ * ({@link TransactionCoordinator.commitEntry}). Each attempt and each refresh round is the driver's;
277
+ * the loop owns the budget, the backoff, and the exit where a refresh saved everything.
278
+ */
279
+ type AttemptDriver = {
280
+ /** Whether the cycle opens with a refresh round before its first attempt. The per-entry commit
281
+ * does, as `Collection.commitHead` does: the queue re-drives an entry under the id of an attempt
282
+ * that may have landed, and the opening refresh is what finds and finishes that attempt's entry
283
+ * instead of committing a second copy. A transaction's commit does not; its id is fresh. */
284
+ readonly opensWithRefresh: boolean;
285
+ /** One attempt under the aged retry `priority`: every collection it committed, with who holds
286
+ * it. Throws {@link CoordinatorStaleLossError} for a clean loss, and for a partial landing retried
287
+ * forward, whose committed participants it has already recorded in `cycle.saved`. */
288
+ attempt(priority: number): Promise<ReadonlyMap<CollectionId, WriteDurability>>;
289
+ /** The refresh round between attempts — see {@link TransactionCoordinator.refreshBetweenAttempts}. */
290
+ refresh(lastChance: boolean): Promise<TornActionError | undefined>;
291
+ /** Whether an attempt starting now would have nothing left to commit, so that once a refresh has
292
+ * saved a participant the write is finished without going round again. */
293
+ nothingLeft(): boolean;
294
+ };
295
+
296
+ /**
297
+ * The retry budget one {@link TransactionCoordinator.commitAttempts} cycle spends: attempts and
298
+ * refused refresh rounds alike are counted against `maxAttempts`, under the wall-clock `deadlineMs`
299
+ * and the abort `signal`, with the same jittered backoff policy `Collection.sync` uses between
300
+ * rounds. There is no forward-progress notion here (a commit either lands or it does not), so this
301
+ * simply bounds how many times a losing write is re-driven. The single-collection accounting
302
+ * (`AttemptCycle`) also checks for a wedged revision view; this one cannot yet, since the confirmed
303
+ * revision does not reach it (backlog `debt-multi-collection-retry-cannot-see-the-taken-revision`).
304
+ */
305
+ class RetryBudget {
306
+ private readonly maxAttempts: number;
307
+ private readonly backoff: { baseMs: number; capMs: number };
308
+ private readonly deadlineMs: number | undefined;
309
+ private readonly signal: AbortSignal | undefined;
310
+ private readonly rand: SyncOptions['rand'];
311
+ private readonly startedAt = Date.now();
312
+ /** Consecutive clean stale losses: attempts, and refresh rounds refused for a cause that can clear. */
313
+ private losses = 0;
314
+ private lastLoss: CoordinatorStaleLossError | undefined;
315
+
316
+ constructor(options?: SyncOptions) {
317
+ this.maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
318
+ this.backoff = {
319
+ baseMs: options?.baseBackoffMs ?? DefaultBaseBackoffMs,
320
+ capMs: options?.maxBackoffMs ?? DefaultMaxBackoffMs,
321
+ };
322
+ this.deadlineMs = options?.deadlineMs;
323
+ this.signal = options?.signal;
324
+ this.rand = options?.rand;
325
+ }
326
+
327
+ /** The checks before an attempt: the abort signal, and — a progress-agnostic ceiling, once at
328
+ * least one loss was taken — the wall-clock deadline, reported as that loss. */
329
+ assertOpen(): void {
330
+ if (this.signal?.aborted) {
331
+ throw makeAbortError(this.signal);
332
+ }
333
+ if (this.lastLoss !== undefined && this.pastDeadline()) {
334
+ throw this.lastLoss;
335
+ }
336
+ }
337
+
338
+ /** The aged retry priority for the next attempt, from the losses taken so far, so a
339
+ * repeatedly-losing write out-ranks fresh (priority-0) rivals in the cluster's `resolveRace`.
340
+ * Fairness-only and capped at `MaxPriority`; 0 on the first attempt, so the initial pend
341
+ * serializes exactly as before. */
342
+ priority(): number {
343
+ return clampPriority(this.losses);
344
+ }
345
+
346
+ /** Count a clean stale loss of an attempt; thrown back when that spends the budget. */
347
+ recordLoss(loss: CoordinatorStaleLossError): void {
348
+ this.lastLoss = loss;
349
+ this.losses++;
350
+ if (this.losses >= this.maxAttempts) {
351
+ throw loss;
352
+ }
353
+ }
354
+
355
+ /** The backoff before a refresh round: none ahead of a cycle's opening round, there being no
356
+ * race to space out; otherwise jittered and growing with the losses taken, so a herd of writers
357
+ * that lost the same race does not re-collide on the next tick. */
358
+ async pause(): Promise<void> {
359
+ if (this.losses === 0) {
360
+ return;
361
+ }
362
+ await abortableDelay(jitteredBackoffMs(this.losses - 1, this.backoff, this.rand), this.signal);
363
+ }
364
+
365
+ /** Whether the next refresh round spends the last of the budget, so a participant whose
366
+ * half-landed write is refused again settles it rather than ask for a round it will not get. */
367
+ lastChance(): boolean {
368
+ return this.losses + 1 >= this.maxAttempts;
369
+ }
370
+
371
+ /** Count a refresh round refused for a cause that can clear (a `completion-refused`
372
+ * {@link TornActionError}); thrown back when that spends the budget or passes the deadline. */
373
+ recordRefusedRound(refused: TornActionError): void {
374
+ this.losses++;
375
+ if (this.losses >= this.maxAttempts || this.pastDeadline()) {
376
+ throw refused;
377
+ }
378
+ }
379
+
380
+ private pastDeadline(): boolean {
381
+ return this.deadlineMs !== undefined && Date.now() - this.startedAt >= this.deadlineMs;
382
+ }
383
+ }
384
+
113
385
  /**
114
386
  * What a pend this coordinator sends carries for the receiving cluster members to re-check.
115
387
  *
@@ -342,7 +614,9 @@ export class TransactionCoordinator {
342
614
  * unavailable transactor, unreachable cluster) also propagates without retry — including a pend
343
615
  * or commit the cohort refused because the transaction had expired by its members' clocks, which
344
616
  * surfaces as {@link TransactionExpiredError} (inside a partial commit's `reason` once a sibling
345
- * has landed).
617
+ * has landed), a pend too few of the cohort's members answered, which surfaces as
618
+ * {@link PromiseShortfallError}, and a pend the members that sank it judged invalid, which surfaces
619
+ * as {@link ValidityRejectedError}.
346
620
  *
347
621
  * A participant can also be SAVED between attempts: an attempt that reported a loss may still
348
622
  * have stored that participant's log tail, and the refresh before the next attempt then finishes
@@ -380,13 +654,44 @@ export class TransactionCoordinator {
380
654
  inFlightDisposers: [],
381
655
  participants: new Set(),
382
656
  saved: new Map(),
657
+ inFlight: inFlightCycleOf(options),
658
+ };
659
+ const driver: AttemptDriver = {
660
+ opensWithRefresh: false,
661
+ attempt: priority => {
662
+ // Age the transaction's advisory priority by the losses taken so far (see
663
+ // RetryBudget.priority). Set on the transaction itself because a validated pend carries
664
+ // the transaction, and a member's race resolution reads the priority off it; excluded
665
+ // from the tx id / client signature, so bumping it does not churn identity. Left
666
+ // untouched on the first attempt so the initial pend serializes exactly as before.
667
+ if (priority > 0) {
668
+ transaction.priority = priority;
669
+ }
670
+ return this.commitOnce(transaction, cycle);
671
+ },
672
+ refresh: lastChance => this.refreshBetweenAttempts(this.registeredRefreshers(), cycle, lastChance),
673
+ // Tested on what is still STAGED, not on "every participant saved": a participant can be
674
+ // saved and still hold actions staged after the attempt began, and those the next attempt
675
+ // must commit.
676
+ nothingLeft: () => this.stagedCollections().length === 0,
383
677
  };
384
678
  try {
385
- return await this.commitAttempts(transaction, cycle, options);
679
+ const written = await this.commitAttempts(driver, cycle, options);
680
+ // Released on every successful exit. An attempt that commits releases it itself; this is
681
+ // for the exit where the refresh between attempts saved what was left, whose consume and
682
+ // replay already gave each saved participant the success path's local treatment.
683
+ this.stampData.delete(transaction.stamp.id);
684
+ return written;
386
685
  } catch (err) {
387
686
  // The ONE place a failure leaves this commit, so no exit — present or future — can skip
388
687
  // reporting a participant that is already saved.
389
- throw this.reportSaved(transaction, cycle, err);
688
+ const reported = this.reportSaved(transaction.id, cycle, err);
689
+ if (reported instanceof CoordinatorPartialCommitError) {
690
+ // The stamp is released, as on the attempt-level partial path (which has already
691
+ // released it): the transaction can no longer be cleanly rolled back.
692
+ this.stampData.delete(transaction.stamp.id);
693
+ }
694
+ throw reported;
390
695
  } finally {
391
696
  // The in-flight marks must outlive each individual attempt (see CommitCycle), so they are
392
697
  // cleared here, on every exit: return, stale-loss exhaustion, a partial landing, a hard
@@ -397,45 +702,32 @@ export class TransactionCoordinator {
397
702
  }
398
703
  }
399
704
 
400
- /** The retry loop behind {@link commit}: every attempt, and the refresh between them. Records
401
- * what it learns in `cycle`; {@link commit} owns turning a failure into the right report. On
402
- * success, reports every participant the cycle saved together with what the final attempt
403
- * committed (see {@link commit}'s return). */
404
- private async commitAttempts(transaction: Transaction, cycle: CommitCycle, options?: SyncOptions): Promise<TransactionDurability | undefined> {
405
- const maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
406
- const baseBackoffMs = options?.baseBackoffMs ?? DefaultBaseBackoffMs;
407
- const maxBackoffMs = options?.maxBackoffMs ?? DefaultMaxBackoffMs;
408
- const deadlineMs = options?.deadlineMs;
409
- const signal = options?.signal;
410
- const startedAt = Date.now();
411
-
412
- // Count of consecutive clean stale losses. There is no forward-progress notion here (a
413
- // single commit either lands or it does not), so this simply bounds how many times we
414
- // re-drive a losing transaction before surfacing a terminal error.
415
- let staleLosses = 0;
416
- let lastLoss: CoordinatorStaleLossError | undefined;
417
-
418
- for (;;) {
419
- if (signal?.aborted) {
420
- throw makeAbortError(signal);
421
- }
422
- // Progress-agnostic ceiling: once we've taken at least one loss, give up if the
423
- // wall-clock deadline passed (independent of the attempt cap).
424
- if (deadlineMs !== undefined && lastLoss && Date.now() - startedAt >= deadlineMs) {
425
- throw lastLoss;
426
- }
427
-
428
- // Age the transaction's advisory priority by the number of losses taken so far, so a
429
- // repeatedly-losing transaction out-ranks fresh (priority-0) rivals in the cluster's
430
- // resolveRace. Fairness-only and capped at MaxPriority; excluded from the tx id / client
431
- // signature, so bumping it here does not churn identity. Left untouched on the first
432
- // attempt (staleLosses == 0) so the initial pend serializes exactly as before.
433
- if (staleLosses > 0) {
434
- transaction.priority = clampPriority(staleLosses);
705
+ /**
706
+ * The retry loop behind {@link commit} and {@link commitEntry}: every attempt, and the refresh
707
+ * rounds between them, over the `driver`'s steps and the budget `options` sets
708
+ * ({@link RetryBudget}). Records what it learns in `cycle`; the caller owns turning a failure into
709
+ * the right report. On success, reports every participant the cycle saved together with what the
710
+ * final attempt committed (see {@link commit}'s return).
711
+ *
712
+ * Only a CLEAN stale loss is retried. A partial landing on a hard failure, an expired transaction,
713
+ * an unavailable transactor, etc. all propagate unchanged. Once a refresh round has saved a
714
+ * participant and the driver has nothing left to commit, the write is finished and the loop
715
+ * returns at once rather than going round again, where an abort, the deadline or an expiry check
716
+ * could still report failure for a write that is entirely saved.
717
+ */
718
+ private async commitAttempts(driver: AttemptDriver, cycle: CommitCycle, options?: SyncOptions): Promise<TransactionDurability | undefined> {
719
+ const budget = new RetryBudget(options);
720
+ if (driver.opensWithRefresh) {
721
+ budget.assertOpen();
722
+ await this.refreshRounds(driver, budget);
723
+ if (cycle.saved.size > 0 && driver.nothingLeft()) {
724
+ return transactionDurability(cycle.saved);
435
725
  }
436
-
726
+ }
727
+ for (;;) {
728
+ budget.assertOpen();
437
729
  try {
438
- const committed = await this.commitOnce(transaction, cycle);
730
+ const committed = await driver.attempt(budget.priority());
439
731
  // Merged, not overwritten, should one participant be both saved and committed (see the
440
732
  // NOTE in reportSaved).
441
733
  const written = new Map(cycle.saved);
@@ -444,58 +736,12 @@ export class TransactionCoordinator {
444
736
  }
445
737
  return writtenDurability(written);
446
738
  } catch (err) {
447
- // Only a CLEAN stale loss is retryable. A partial landing, an expired transaction, an
448
- // unavailable transactor, etc. all propagate unchanged.
449
739
  if (!(err instanceof CoordinatorStaleLossError)) {
450
740
  throw err;
451
741
  }
452
- lastLoss = err;
453
- staleLosses++;
454
- if (staleLosses >= maxAttempts) {
455
- throw err;
456
- }
457
- // Re-read fresh state before re-attempting so the next commit pends against current
458
- // revisions (mirrors how Collection.sync calls updateInternal() before retrying).
459
- //
460
- // A participant whose log tail landed despite the reported loss finds its own entry
461
- // here and FINISHES that action before consuming it (Collection.completeOwnEntry,
462
- // from the attempt commitOnceLatched retained). When finishing is refused for a cause
463
- // that can clear, the refresh — not the commit — is what gets retried: the
464
- // participant's log entry is already durable, and once a refresh adopts a newer
465
- // revision commitOnce appends a SECOND entry under this transaction's id. (At an
466
- // unchanged revision the re-append is byte-identical — see
467
- // Collection.logAppendBlockIds — so what is at stake is the duplicate entry, not two
468
- // versions of one tail block.)
469
- // Each such round counts against the same budget as a stale loss; a permanent
470
- // refusal (a rival holds the revision) escapes as the named TornActionError at once.
471
- // Re-refreshing collections an earlier round already refreshed is a no-op.
472
- // The round that would spend the last of the budget is told so, which makes each
473
- // participant SETTLE a half-landed write rather than ask for another round: the
474
- // error thrown below then says whether the write can still land (`final`). A
475
- // deadline cannot be foreseen the same way; a write given up on it stays unsettled.
476
- for (;;) {
477
- const delay = jitteredBackoffMs(staleLosses - 1, { baseMs: baseBackoffMs, capMs: maxBackoffMs }, options?.rand);
478
- await abortableDelay(delay, signal);
479
- const refused = await this.refreshBetweenAttempts(cycle, staleLosses + 1 >= maxAttempts);
480
- if (refused === undefined) {
481
- break;
482
- }
483
- staleLosses++;
484
- if (staleLosses >= maxAttempts
485
- || (deadlineMs !== undefined && Date.now() - startedAt >= deadlineMs)) {
486
- throw refused;
487
- }
488
- }
489
- if (cycle.saved.size > 0 && this.stagedCollections().length === 0) {
490
- // The refresh saved what was left: nothing is staged any more, so this transaction
491
- // is committed. Return now rather than go round again, where an abort, the deadline
492
- // or an expiry check could still report failure for a transaction that is entirely
493
- // saved. The refresh's consume and replay already gave each saved participant the
494
- // success path's local treatment, so only the stamp is left to release.
495
- // Tested on what is still STAGED, not on "every participant saved": a participant
496
- // can be saved and still hold actions staged after the attempt began, and those
497
- // the next attempt must commit.
498
- this.stampData.delete(transaction.stamp.id);
742
+ budget.recordLoss(err);
743
+ await this.refreshRounds(driver, budget);
744
+ if (cycle.saved.size > 0 && driver.nothingLeft()) {
499
745
  return transactionDurability(cycle.saved);
500
746
  }
501
747
  }
@@ -503,37 +749,82 @@ export class TransactionCoordinator {
503
749
  }
504
750
 
505
751
  /**
506
- * Refresh every registered collection between attempts, recording in `cycle.saved` each one
507
- * whose refresh finished this transaction's own log entry (see {@link Collection.refreshInFlight}),
508
- * with who holds it — `undefined` when the refresh could not say, which still records it as saved.
752
+ * Back off, refresh, and keep refreshing while a round reports that a participant's half-landed
753
+ * write could not be finished YET. Re-reading fresh state before re-attempting is what lets the
754
+ * next attempt pend against current revisions (mirrors how Collection.sync calls updateInternal()
755
+ * before retrying), and a participant whose log tail landed despite the reported loss finds its
756
+ * own entry here and FINISHES that action before consuming it (Collection.completeOwnEntry, from
757
+ * the attempt the previous one retained).
509
758
  *
510
- * Visits EVERY collection even after one throws. Stopping at the first throw would leave a
511
- * participant later in the map unfinished whenever an earlier one is torn — its log tail stored
759
+ * When finishing is refused for a cause that can clear, the refresh — not the commit — is what
760
+ * gets retried: the participant's log entry is already durable, and once a refresh adopts a newer
761
+ * revision the next attempt appends a SECOND entry under the write's id. (At an unchanged
762
+ * revision the re-append is byte-identical — see Collection.logAppendBlockIds — so what is at
763
+ * stake is the duplicate entry, not two versions of one tail block.) Each such round counts
764
+ * against the same budget as a stale loss; a permanent refusal (a rival holds the revision)
765
+ * escapes as the named TornActionError at once. Re-refreshing a collection an earlier round
766
+ * already refreshed is a no-op. The round that would spend the last of the budget is told so,
767
+ * which makes each participant SETTLE a half-landed write rather than ask for another round: the
768
+ * error thrown then says whether the write can still land (`final`). A deadline cannot be
769
+ * foreseen the same way; a write given up on it stays unsettled.
770
+ */
771
+ private async refreshRounds(driver: AttemptDriver, budget: RetryBudget): Promise<void> {
772
+ for (;;) {
773
+ await budget.pause();
774
+ const refused = await driver.refresh(budget.lastChance());
775
+ if (refused === undefined) {
776
+ return;
777
+ }
778
+ budget.recordRefusedRound(refused);
779
+ }
780
+ }
781
+
782
+ /** Every registered collection as a refresh-round participant of a transaction's commit.
783
+ *
784
+ * NOTE: EVERY registered collection, not only the participants of the transaction. Not free: a
785
+ * non-participant's refresh throws CollectionHeaderVanishedError if its header momentarily reads
786
+ * absent while it holds a committed revision, aborting this retry. And because a throw does not
787
+ * stop the round, an unreachable cluster costs one failed read per registered collection rather
788
+ * than one. The registered set is small today; if that (or retry latency) ever bites, narrow this
789
+ * to the transaction's participants. (The per-entry commit already refreshes its participants
790
+ * only, through their handles — see `EntryParticipants.refreshers`.) */
791
+ private registeredRefreshers(): RefreshParticipant[] {
792
+ return [...this.collections].map(([collectionId, collection]) => ({
793
+ collectionId,
794
+ refresh: (report, lastChance) => collection.refreshInFlight(report, lastChance),
795
+ }));
796
+ }
797
+
798
+ /**
799
+ * One refresh round between attempts: refresh every participant, recording in `cycle.saved` each
800
+ * one whose refresh finished the write's own log entry (see {@link Collection.refreshInFlight}),
801
+ * with who holds it — `undefined` when the refresh could not say, which still records it as
802
+ * saved — and telling the participant so (`RefreshParticipant.saved`).
803
+ *
804
+ * Visits EVERY participant even after one throws. Stopping at the first throw would leave a
805
+ * participant later in the round unfinished whenever an earlier one is torn — its log tail stored
512
806
  * and its other blocks never landed, the silent loss `Collection.completeOwnEntry` exists to
513
807
  * prevent — and unreported. Each refresh is independent (its own latch, its own instance state),
514
808
  * so one failing says nothing about the next.
515
809
  *
516
- * NOTE: refreshes EVERY registered collection, not only the participants of this transaction.
517
- * Not free: a non-participant's refresh throws CollectionHeaderVanishedError if its header
518
- * momentarily reads absent while it holds a committed revision, aborting this retry. And because
519
- * a throw no longer stops the round, an unreachable cluster costs one failed read per registered
520
- * collection rather than one. The registered set is small today; if that (or retry latency) ever
521
- * bites, narrow this to the transaction's participants.
810
+ * NOTE: no `tailFloor` is passed to any refresh — the coordinator's loop loses the confirmed
811
+ * revision before the round runs (backlog `debt-multi-collection-retry-cannot-see-the-taken-revision`);
812
+ * the per-entry commit has the same gap, through the same round.
522
813
  *
523
814
  * @param lastChance - this is the round that spends the last of the retry budget, so a
524
815
  * participant whose half-landed write is refused again settles it (`Collection.completeOwnEntry`)
525
816
  * rather than asking for a round it will not get; the error returned then carries `final`.
526
817
  * @returns the first `completion-refused` {@link TornActionError} when that is the only way any
527
818
  * refresh failed — the round is worth retrying; `undefined` when every refresh succeeded.
528
- * @throws the first other error, once every collection has been visited.
819
+ * @throws the first other error, once every participant has been visited.
529
820
  */
530
- private async refreshBetweenAttempts(cycle: CommitCycle, lastChance: boolean): Promise<TornActionError | undefined> {
821
+ private async refreshBetweenAttempts(participants: readonly RefreshParticipant[], cycle: CommitCycle, lastChance: boolean): Promise<TornActionError | undefined> {
531
822
  let terminal: { error: unknown } | undefined;
532
823
  let refused: TornActionError | undefined;
533
- for (const [collectionId, collection] of this.collections) {
824
+ for (const participant of participants) {
534
825
  const report: RefreshReport = {};
535
826
  try {
536
- await collection.refreshInFlight(report, lastChance);
827
+ await participant.refresh(report, lastChance);
537
828
  } catch (err) {
538
829
  if (err instanceof TornActionError && err.reason === 'completion-refused') {
539
830
  refused ??= err;
@@ -544,7 +835,8 @@ export class TransactionCoordinator {
544
835
  // Read after the try, not only on success: a refresh can throw AFTER it finished the
545
836
  // entry, and that participant is saved either way.
546
837
  if (report.ownEntryFinished !== undefined) {
547
- recordCollectionDurability(cycle.saved, collectionId, report.ownEntryFinished.durability);
838
+ recordCollectionDurability(cycle.saved, participant.collectionId, report.ownEntryFinished.durability);
839
+ participant.saved?.();
548
840
  }
549
841
  }
550
842
  if (terminal !== undefined) {
@@ -589,10 +881,11 @@ export class TransactionCoordinator {
589
881
  *
590
882
  * Local state already matches that report: a saved participant was consumed by its refresh, and
591
883
  * an unsaved one kept its staged actions (a failed finish throws before touching anything, and
592
- * commitOnceLatched restores every participant it did not commit). The stamp is released, as on
593
- * the existing partial path, because the transaction can no longer be cleanly rolled back.
884
+ * commitOnceLatched restores every participant it did not commit; the per-entry commit leaves a
885
+ * refused participant's segment sealed and first). Releasing a transaction's stamp on the partial
886
+ * report is {@link commit}'s, which reads the class of what this returns.
594
887
  */
595
- private reportSaved(transaction: Transaction, cycle: CommitCycle, err: unknown): unknown {
888
+ private reportSaved(actionId: ActionId, cycle: CommitCycle, err: unknown): unknown {
596
889
  if (cycle.saved.size === 0) {
597
890
  return err;
598
891
  }
@@ -609,9 +902,8 @@ export class TransactionCoordinator {
609
902
  // committed. Unreachable while a session stages and commits on one call path; if staging ever
610
903
  // races a commit, report such a participant in both lists.
611
904
  const failed = [...cycle.participants].filter(id => !committed.has(id));
612
- log('commit:partial-after-refresh tx=%s committed=%o failed=%o reason=%s', transaction.id,
905
+ log('commit:partial-after-refresh tx=%s committed=%o failed=%o reason=%s', actionId,
613
906
  [...committed.keys()], failed, reason instanceof Error ? reason.name : String(reason));
614
- this.stampData.delete(transaction.stamp.id);
615
907
  return new CoordinatorPartialCommitError(committed, failed, reason);
616
908
  }
617
909
 
@@ -696,7 +988,7 @@ export class TransactionCoordinator {
696
988
  // (Collection.completeOwnEntry). `transaction.id` is stable across retries, so re-marking on a
697
989
  // later attempt re-states the same fact. Only participants are marked; a registered
698
990
  // non-participant is left unmarked and its refresh behaves exactly as a reader's.
699
- cycle.inFlightDisposers.push(collection.beginInFlightAction(transaction.id));
991
+ cycle.inFlightDisposers.push(collection.beginInFlightAction(transaction.id, cycle.inFlight));
700
992
  }
701
993
  return await this.commitOnceLatched(transaction, collectionData, cycle);
702
994
  } finally {
@@ -766,12 +1058,14 @@ export class TransactionCoordinator {
766
1058
  preCommitSnapshots.set(collectionId, collection.snapshotPending());
767
1059
  }
768
1060
 
1061
+ // Read per attempt: commitAttempts ages the transaction's priority between attempts.
1062
+ const context = writeContextOf(transaction, cycle.inFlight);
769
1063
  let coordResult: CoordinationResult;
770
1064
  try {
771
1065
  for (const { collectionId, collection } of collectionData) {
772
1066
  const applyResult = await this.applyActionsToCollection(
773
1067
  { collectionId, actions: collection.getPendingActions() },
774
- transaction,
1068
+ context,
775
1069
  allCollectionIds
776
1070
  );
777
1071
  if (!applyResult.success) {
@@ -787,7 +1081,7 @@ export class TransactionCoordinator {
787
1081
 
788
1082
  // Execute consensus phases (GATHER, PEND, COMMIT)
789
1083
  coordResult = await this.coordinateTransaction(
790
- transaction,
1084
+ context,
791
1085
  validation,
792
1086
  collectionTransforms,
793
1087
  criticalBlocks,
@@ -800,7 +1094,7 @@ export class TransactionCoordinator {
800
1094
  // to its pre-append snapshot — a genuinely clean rollback that leaves each
801
1095
  // tracker pristine for retry (see txn-failed-commit-leaves-staged-log-entry).
802
1096
  for (const { collectionId, collection } of collectionData) {
803
- collection.restorePending(preCommitSnapshots.get(collectionId)!);
1097
+ await collection.restorePending(preCommitSnapshots.get(collectionId)!);
804
1098
  }
805
1099
  throw err;
806
1100
  }
@@ -814,12 +1108,13 @@ export class TransactionCoordinator {
814
1108
  // the next refresh of that participant finds this transaction's own log entry, these are
815
1109
  // the transforms that finish it (Collection.completeOwnEntry) — without them the refresh
816
1110
  // 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.
1111
+ // this is the participant's LIVE tracker state. No block digests are retained: the
1112
+ // declaration taken before the pend (declareTouchedBlocks) stays inside coordinateTransaction,
1113
+ // so a re-send declares none, and an undeclared block falls back to member-side corroboration.
820
1114
  for (const { collectionId, collection } of collectionData) {
821
1115
  if (committed.has(collectionId)) continue;
822
- collection.retainInFlightAttempt(transaction.id, {
1116
+ collection.retainInFlightAttempt({
1117
+ actionId: transaction.id,
823
1118
  rev: pendedRevs.get(collectionId)!,
824
1119
  transforms: copyTransforms(collectionTransforms.get(collectionId)!),
825
1120
  tailId: criticalBlocks.get(collectionId)!,
@@ -830,26 +1125,32 @@ export class TransactionCoordinator {
830
1125
  // while another failed permanently. A uniform pre-append restore would
831
1126
  // corrupt the committed half — re-staging its already-durable actions as
832
1127
  // still-pending, so tracker memory would disagree with cluster storage.
833
- // Split the local handling instead:
1128
+ // Split the local handling instead, in two passes: the committed half is folded
1129
+ // first, in one await-free pass (so a committed read observes every committed
1130
+ // participant pre-fold or post-fold, as the success fold below promises), and the
1131
+ // failed half is restored after it — a restore can replay, so it is awaited, which
1132
+ // admits no interleaved stage because every participant's latch is held across
1133
+ // this span.
834
1134
  for (const { collectionId, collection } of collectionData) {
835
- if (committed.has(collectionId)) {
836
- // Committed → the success-path local treatment (see below): fold the
837
- // committed transforms into the read cache BEFORE resetting the tracker,
838
- // then drop the now-durable pending actions so a retry cannot re-log them.
839
- // NOTE: no-double-apply on retry depends on clearPendingActions() running for
840
- // EVERY committed collection here before any re-drive of commit(). If a committed
841
- // collection kept its pending queue, a subsequent commit() would re-append and
842
- // re-log its already-durable actions — a duplicate log entry on the winner. The
843
- // no-double-apply-on-retry test in transaction.spec.ts locks this.
844
- const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId)!);
845
- collection.applyCommittedToCache(collectionTransforms.get(collectionId)!, rev);
846
- collection.tracker.reset();
847
- collection.clearPendingActions();
848
- } else {
849
- // Failed / never-committed → restore the pre-append snapshot so a retry
850
- // re-appends cleanly (no duplicate log entry).
851
- collection.restorePending(preCommitSnapshots.get(collectionId)!);
852
- }
1135
+ if (!committed.has(collectionId)) continue;
1136
+ // Committed → the success-path local treatment (see below): fold the
1137
+ // committed transforms into the read cache BEFORE resetting the tracker,
1138
+ // then drop the now-durable pending actions so a retry cannot re-log them.
1139
+ // NOTE: no-double-apply on retry depends on clearPendingActions() running for
1140
+ // EVERY committed collection here before any re-drive of commit(). If a committed
1141
+ // collection kept its pending queue, a subsequent commit() would re-append and
1142
+ // re-log its already-durable actions — a duplicate log entry on the winner. The
1143
+ // no-double-apply-on-retry test in transaction.spec.ts locks this.
1144
+ const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId)!);
1145
+ collection.applyCommittedToCache(collectionTransforms.get(collectionId)!, rev);
1146
+ collection.tracker.reset();
1147
+ collection.clearPendingActions();
1148
+ }
1149
+ for (const { collectionId, collection } of collectionData) {
1150
+ if (committed.has(collectionId)) continue;
1151
+ // Failed / never-committed → restore the pre-append snapshot so a retry
1152
+ // re-appends cleanly (no duplicate log entry).
1153
+ await collection.restorePending(preCommitSnapshots.get(collectionId)!);
853
1154
  }
854
1155
  const failed = [...(coordResult.failedCollections ?? new Set<CollectionId>())];
855
1156
  if (coordResult.staleLoss) {
@@ -890,22 +1191,14 @@ export class TransactionCoordinator {
890
1191
  // EMPTY committed set: PEND failed, or the whole commit failed cleanly with
891
1192
  // nothing durable. Restore every tracker so each is pristine for retry.
892
1193
  for (const { collectionId, collection } of collectionData) {
893
- collection.restorePending(preCommitSnapshots.get(collectionId)!);
1194
+ await collection.restorePending(preCommitSnapshots.get(collectionId)!);
894
1195
  }
895
1196
  // Distinguish a genuine optimistic-concurrency conflict (a stale loss / pending
896
1197
  // contention — retryable after a re-read) from a hard failure (unavailable transactor,
897
1198
  // storage rejection, expired). Only the former is worth re-driving; the retry wrapper in
898
1199
  // commit() catches CoordinatorStaleLossError and re-attempts, while a plain Error escapes
899
1200
  // immediately (preserving the historical fail-fast behaviour for hard failures).
900
- if (coordResult.staleLoss) {
901
- throw new CoordinatorStaleLossError([...(coordResult.failedCollections ?? new Set(allCollectionIds))], coordResult.error);
902
- }
903
- // An expiry is surfaced by name and never re-driven: the retry's pend would carry an
904
- // expiration from the same clock.
905
- if (coordResult.expired !== undefined) {
906
- throw coordResult.expired;
907
- }
908
- throw new Error(`Transaction commit failed: ${coordResult.error}`);
1201
+ throw cleanFailureError(coordResult, [...(coordResult.failedCollections ?? new Set(allCollectionIds))]);
909
1202
  }
910
1203
 
911
1204
  // Advance actionContext, fold the committed transforms into each
@@ -931,6 +1224,156 @@ export class TransactionCoordinator {
931
1224
  return coordResult.committedCollections;
932
1225
  }
933
1226
 
1227
+ /**
1228
+ * Commit one queued entry's slice of every collection it wrote, as ONE all-or-nothing round
1229
+ * (docs/offline-sync.md §One entry, one network transaction): for each collection in
1230
+ * `entry.collectionIds`, exactly its HEAD sealed segment, which must be `entry.entryId`, as one
1231
+ * log entry under `entry.actionId` and `entry.timestamp`. The offline-sync queue is the caller,
1232
+ * for an entry that wrote more than one collection; an entry that wrote one commits through
1233
+ * `Collection.commitHead`, whose steps this drives in lock-step across the participants
1234
+ * (`HeadCommitHandle` in collection/head-commit.ts): open a handle per participant, in sorted
1235
+ * collection-id order; the opening refresh, which finishes and consumes an entry an earlier
1236
+ * `commitEntry` under this action id left in a participant's log; then per attempt, build every
1237
+ * participant's attempt on its head tracker, record them through `entry.recordAttempt`, release
1238
+ * every latch, run the phases ({@link coordinateAttempts}: pend every participant, then commit),
1239
+ * retake every latch, and apply the outcome — fold then replay on a commit, the recorded refusal
1240
+ * re-checked and the attempt retained on a refusal — with the retry loop of {@link commit}
1241
+ * ({@link commitAttempts}) between attempts.
1242
+ *
1243
+ * What the slice deliberately does NOT do, where {@link commit} does: no pre-commit snapshots or
1244
+ * `restorePending` (an attempt never touches the live tracker; a failed one leaves it as it was
1245
+ * by construction); no `getPendingActions`, `clearPendingActions` or `tracker.reset` (the head
1246
+ * segment is dropped and folded through the handle); no stamp (the one-open-stamp rule is about
1247
+ * staged state, which a slice does not stage — a slice may run while a stamp is open on another
1248
+ * coordinator over the same collections, which is the plugin's open SQL transaction; the
1249
+ * collection latch is what serialises them); no expiry check (an entry has no stamp to expire).
1250
+ * Its refresh rounds refresh the entry's participants only, through their handles, never the
1251
+ * coordinator's whole map.
1252
+ *
1253
+ * Requires a coordinator built with `pendValidation: 'none'`, and throws before touching
1254
+ * anything otherwise: a queued entry has no statements for a member to re-execute, and the pend
1255
+ * carries bare transforms exactly as the plugin's `commitBatchLegacy` sends them. The queue builds
1256
+ * one coordinator per submission over exactly the entry's collections; running `commitEntry`
1257
+ * while a {@link commit} of the same coordinator is open is not a supported combination, and
1258
+ * nothing but the collection latches guards it.
1259
+ *
1260
+ * @returns who holds each collection the entry wrote, across every attempt, as {@link commit}
1261
+ * answers it — a participant the refresh saved included, listed with an `undefined` class (and
1262
+ * `overall` then absent) when the refresh established it was saved under `entry.actionId` without
1263
+ * re-sending (the status-read fallback of `Collection.completeOwnEntry`, where
1264
+ * `Collection.commitHead` answers `undefined`). Never `undefined`: a slice always writes at least
1265
+ * one collection, so the "nothing was written" answer `commit` has is unrepresentable here.
1266
+ * @throws what {@link commit} throws — a {@link CoordinatorStaleLossError} once the retry budget
1267
+ * is spent, a {@link CoordinatorPartialCommitError} for a partial landing (every participant it
1268
+ * names as committed has had its head consumed; every failed one's head is still sealed and
1269
+ * first, its attempt retained), the named refusals, `TornActionError` out of a refresh — plus the
1270
+ * recorded refusal of any participant's head (an `ActionRefusedError`), thrown with every other
1271
+ * participant's segment intact since nothing was sent or the send was refused, and
1272
+ * `SealedSegmentsError` from `Collection.openHeadCommit`'s preconditions, before anything is done.
1273
+ */
1274
+ async commitEntry(entry: EntryCommit, options?: SyncOptions): Promise<TransactionDurability> {
1275
+ if (this.pendValidation !== 'none') {
1276
+ throw new Error(`commitEntry ${entry.entryId}: a queued entry commits through a coordinator built with `
1277
+ + `pendValidation: 'none' — it has no statements for a member to re-execute`);
1278
+ }
1279
+ const inFlight = inFlightCycleOf(options);
1280
+ const participants = await EntryParticipants.open(this.collections, entry, inFlight);
1281
+ const cycle: CommitCycle = {
1282
+ // The handles own the in-flight marks (closed with them), so none to dispose here.
1283
+ inFlightDisposers: [],
1284
+ participants: new Set(participants.ids()),
1285
+ saved: new Map(),
1286
+ inFlight,
1287
+ };
1288
+ const driver: AttemptDriver = {
1289
+ opensWithRefresh: true,
1290
+ attempt: priority => this.commitEntryOnce(entry, participants, cycle, priority),
1291
+ refresh: lastChance => this.refreshBetweenAttempts(participants.refreshers(), cycle, lastChance),
1292
+ nothingLeft: () => participants.size === 0,
1293
+ };
1294
+ try {
1295
+ const written = await this.commitAttempts(driver, cycle, options);
1296
+ if (written === undefined) {
1297
+ throw new Error(`commitEntry ${entry.entryId}: the cycle ended with nothing committed and nothing saved`);
1298
+ }
1299
+ return written;
1300
+ } catch (err) {
1301
+ throw this.reportSaved(entry.actionId, cycle, err);
1302
+ } finally {
1303
+ participants.close();
1304
+ }
1305
+ }
1306
+
1307
+ /**
1308
+ * One attempt of {@link commitEntry}, under the latches `participants` hold: every remaining
1309
+ * participant's attempt is built (`HeadCommitHandle.stage`, which re-checks the head's recorded
1310
+ * refusal and throws it), recorded through the write-ahead hook — a throw there aborts with
1311
+ * nothing sent and nothing changed — then sent as one round with every latch released, and the
1312
+ * outcome applied under the retaken latches:
1313
+ *
1314
+ * - a commit: fold every participant in one await-free pass, then replay each
1315
+ * (`EntryParticipants.landed`); the attempt's durability per collection is the answer;
1316
+ * - a partial landing: the committed participants folded, replayed and recorded in `cycle.saved`
1317
+ * — before their local treatment, so a throw in it is still reported over the right committed
1318
+ * set — and the rest refused (their recorded refusal re-checked, their attempt retained); then
1319
+ * {@link CoordinatorStaleLossError} when every refusal was a returned one, so the retry loop
1320
+ * finishes the refused participants forward over what is left (as `commitOnceLatched`'s
1321
+ * partial-retry branch does), or {@link CoordinatorPartialCommitError} on a hard failure;
1322
+ * - nothing committed: every participant refused, then the failure thrown by its class
1323
+ * ({@link cleanFailureError}).
1324
+ *
1325
+ * The refusal re-check runs after the committed participants are folded, never before: a
1326
+ * sibling's recorded refusal must not keep a durable commit from being applied locally.
1327
+ */
1328
+ private async commitEntryOnce(
1329
+ entry: EntryCommit,
1330
+ participants: EntryParticipants,
1331
+ cycle: CommitCycle,
1332
+ priority: number
1333
+ ): Promise<ReadonlyMap<CollectionId, WriteDurability>> {
1334
+ const staged = await participants.stage();
1335
+ if (entry.recordAttempt !== undefined) {
1336
+ await entry.recordAttempt(participants.retainedAttempts(staged));
1337
+ }
1338
+ const context: WriteContext = {
1339
+ actionId: entry.actionId,
1340
+ timestamp: entry.timestamp,
1341
+ reads: [],
1342
+ priority,
1343
+ ...refuseSoloField(cycle.inFlight.refuseSolo),
1344
+ };
1345
+ const attempts = new Map(Array.from(staged, ([collectionId, attempt]) => [collectionId, collectionAttemptOf(attempt)]));
1346
+
1347
+ participants.release();
1348
+ let coordResult: CoordinationResult;
1349
+ try {
1350
+ coordResult = await this.coordinateAttempts(context, undefined, attempts);
1351
+ } finally {
1352
+ await participants.retake();
1353
+ }
1354
+
1355
+ if (coordResult.success) {
1356
+ await participants.landed(staged, participants.ids());
1357
+ return coordResult.committedCollections;
1358
+ }
1359
+ const committed = coordResult.committedCollections ?? new Map<CollectionId, WriteDurability>();
1360
+ const failed = participants.ids().filter(collectionId => !committed.has(collectionId));
1361
+ if (committed.size === 0) {
1362
+ participants.refused(staged, failed);
1363
+ throw cleanFailureError(coordResult, failed);
1364
+ }
1365
+ for (const [collectionId, durability] of committed) {
1366
+ recordCollectionDurability(cycle.saved, collectionId, durability);
1367
+ }
1368
+ await participants.landed(staged, committed.keys());
1369
+ participants.refused(staged, failed);
1370
+ if (coordResult.staleLoss) {
1371
+ log('commitEntry:partial-retry entry=%s action=%s committed=%o failed=%o reason=%s', entry.entryId, entry.actionId, [...committed.keys()], failed, coordResult.error);
1372
+ throw new CoordinatorStaleLossError(failed, coordResult.error);
1373
+ }
1374
+ throw new CoordinatorPartialCommitError(committed, failed, coordResult.expired ?? coordResult.error);
1375
+ }
1376
+
934
1377
  /**
935
1378
  * Rollback a transaction (undo only the given stampId's applied actions).
936
1379
  *
@@ -978,9 +1421,14 @@ export class TransactionCoordinator {
978
1421
  // Accepted: the tracker half already discards their transforms, and symmetric is the safer
979
1422
  // state — leaving such an action queued while its transforms are gone is exactly the
980
1423
  // phantom that a conflicting sync's replayActions would resurrect as live data.
981
- for (const [collection, snapshot] of data.preSnapshot) {
982
- collection.restorePending(snapshot);
983
- }
1424
+ // Awaited: a restore across a change to the collection's sealed segments replays them
1425
+ // (Collection.restorePending), and the single-call-path assumption above is what keeps a
1426
+ // stage from landing on the collection while that replay runs. Every participant is
1427
+ // restored even after one throws (a refusal of the restored open segment, or a failed
1428
+ // re-read inside the replay): each restore is independent, and stopping at the first throw
1429
+ // would leave the later participants holding the rolled-back stamp's actions, which the
1430
+ // next transaction would then log as its own.
1431
+ await visitEveryThenThrow(data.preSnapshot, ([collection, snapshot]) => collection.restorePending(snapshot));
984
1432
  }
985
1433
 
986
1434
  /**
@@ -1200,10 +1648,11 @@ export class TransactionCoordinator {
1200
1648
  // Released in the finally: execute has early failure returns.
1201
1649
  const latchReleases: (() => void)[] = [];
1202
1650
  try {
1203
- // NOTE: deadlock-freedom against a concurrent commitOnce needs BOTH paths to acquire in
1204
- // the SAME order, not merely each in a sorted one. `CollectionId` is a string, so this
1205
- // default `.sort()` and commitOnce's explicit `<`/`>` comparator agree today. If either
1206
- // spelling changes — a custom comparator, a non-string id — change both together.
1651
+ // NOTE: deadlock-freedom against a concurrent commitOnce or commitEntry needs ALL three
1652
+ // paths to acquire in the SAME order, not merely each in a sorted one. `CollectionId` is a
1653
+ // string, so this default `.sort()`, commitOnce's explicit `<`/`>` comparator and
1654
+ // `compareCollectionIds` in entry-commit.ts agree today. If any spelling changes — a
1655
+ // custom comparator, a non-string id — change all three together.
1207
1656
  for (const collectionId of [...allCollectionIds].sort()) {
1208
1657
  const collection = this.collections.get(collectionId);
1209
1658
  if (collection) {
@@ -1217,10 +1666,11 @@ export class TransactionCoordinator {
1217
1666
  await this.collections.get(collectionId)?.restageIfBasesMoved();
1218
1667
  }
1219
1668
 
1669
+ const context = writeContextOf(transaction);
1220
1670
  for (const [collectionId, actions] of batches) {
1221
1671
  const applyResult = await this.applyActionsToCollection(
1222
1672
  { collectionId, actions },
1223
- transaction,
1673
+ context,
1224
1674
  allCollectionIds
1225
1675
  );
1226
1676
 
@@ -1242,7 +1692,7 @@ export class TransactionCoordinator {
1242
1692
  // 4. Coordinate (GATHER if multi-collection)
1243
1693
  const tCoord = Date.now();
1244
1694
  const coordResult = await this.coordinateTransaction(
1245
- transaction,
1695
+ context,
1246
1696
  validation,
1247
1697
  collectionTransforms,
1248
1698
  criticalBlocks,
@@ -1259,8 +1709,12 @@ export class TransactionCoordinator {
1259
1709
  // pending queues aren't left mis-tracking already-durable state; the failed subset
1260
1710
  // is unwound to its pre-staging snapshot, and the stamp tracking is dropped so no
1261
1711
  // unsafe all-or-nothing undo handle survives (rollback() would rewind the winner).
1262
- // Kept await-free for the same reason the success fold is — restorePending is
1263
- // synchronous and latch-free by contract, so it is safe inside this latched span.
1712
+ // Two passes, as in commitOnceLatched: the committed subset's fold is kept
1713
+ // await-free for the same reason the success fold is, and the failed subset's
1714
+ // restore comes after it. That restore is awaited — it can replay the collection's
1715
+ // sealed segments — and the await admits no interleaved stage, because every
1716
+ // participant's latch is held across this span (restorePending stays latch-free by
1717
+ // contract and relies on exactly that).
1264
1718
  // NOTE: execute() has no retry loop at all, so a returned refusal after a sibling
1265
1719
  // committed is reported here at once, where commit() would re-drive the refused
1266
1720
  // collection forward (the partial-retry branch of commitOnceLatched). No production
@@ -1273,23 +1727,24 @@ export class TransactionCoordinator {
1273
1727
  if (committed.size > 0) {
1274
1728
  for (const collectionId of batches.keys()) {
1275
1729
  const collection = this.collections.get(collectionId);
1276
- if (!collection) continue;
1277
- if (committed.has(collectionId)) {
1278
- const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId)!);
1279
- collection.applyCommittedToCache(collectionTransforms.get(collectionId)!, rev);
1280
- collection.tracker.reset();
1281
- collection.clearPendingActions();
1282
- } else {
1283
- // NOTE: blind overwrite of this collection's staged state — anything
1284
- // staged on it between the pre-stage snapshot above and here is discarded.
1285
- // No sibling stamp can be that writer (at most one stamp is open), so the
1286
- // only source is the untracked Tree.stage / Collection.act path, and this
1287
- // is the same single-call-path assumption rollback() documents. It cannot
1288
- // be softened by re-applying those actions here: collection.act takes the
1289
- // same non-reentrant instance latch this span already holds.
1290
- const snapshot = preStageSnapshots.get(collectionId);
1291
- if (snapshot) collection.restorePending(snapshot);
1292
- }
1730
+ if (!collection || !committed.has(collectionId)) continue;
1731
+ const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId)!);
1732
+ collection.applyCommittedToCache(collectionTransforms.get(collectionId)!, rev);
1733
+ collection.tracker.reset();
1734
+ collection.clearPendingActions();
1735
+ }
1736
+ for (const collectionId of batches.keys()) {
1737
+ const collection = this.collections.get(collectionId);
1738
+ if (!collection || committed.has(collectionId)) continue;
1739
+ // NOTE: blind overwrite of this collection's staged state — anything
1740
+ // staged on it between the pre-stage snapshot above and here is discarded.
1741
+ // No sibling stamp can be that writer (at most one stamp is open), so the
1742
+ // only source is the untracked Tree.stage / Collection.act path, and this
1743
+ // is the same single-call-path assumption rollback() documents. It cannot
1744
+ // be softened by re-applying those actions here: collection.act takes the
1745
+ // same non-reentrant instance latch this span already holds.
1746
+ const snapshot = preStageSnapshots.get(collectionId);
1747
+ if (snapshot) await collection.restorePending(snapshot);
1293
1748
  }
1294
1749
  // The undo handle is now unsafe: rollback() is all-or-nothing and would rewind
1295
1750
  // the collections that DID durably commit. Drop it, matching commitOnceLatched.
@@ -1354,11 +1809,12 @@ export class TransactionCoordinator {
1354
1809
  /**
1355
1810
  * Apply actions to a collection.
1356
1811
  *
1357
- * This runs the action handlers, writes to the log, and collects transforms.
1812
+ * This runs the action handlers, writes to the log, and collects transforms. The log entry is
1813
+ * written under `context`: its action id, its timestamp and its reads.
1358
1814
  */
1359
1815
  private async applyActionsToCollection(
1360
1816
  collectionActions: CollectionActions,
1361
- transaction: Transaction,
1817
+ context: WriteContext,
1362
1818
  allCollectionIds: CollectionId[]
1363
1819
  ): Promise<{
1364
1820
  success: boolean;
@@ -1385,8 +1841,7 @@ export class TransactionCoordinator {
1385
1841
  // Get transforms from the collection's tracker
1386
1842
  const transforms = collection.tracker.transforms;
1387
1843
 
1388
- // Generate action ID from transaction ID
1389
- const actionId = transaction.id;
1844
+ const actionId = context.actionId;
1390
1845
  const newRev = collection.getNextRev();
1391
1846
 
1392
1847
  // Write actions to the collection's log to get the log tail block ID. The append must be a
@@ -1436,7 +1891,7 @@ export class TransactionCoordinator {
1436
1891
  actionId,
1437
1892
  newRev,
1438
1893
  () => blockIdsForTransforms(transforms),
1439
- { collectionIds: allCollectionIds, reads: transaction.reads, timestamp: transaction.stamp.timestamp }
1894
+ { collectionIds: allCollectionIds, reads: [...context.reads], timestamp: context.timestamp }
1440
1895
  );
1441
1896
 
1442
1897
  // Return the transforms and log tail block ID
@@ -1450,9 +1905,11 @@ export class TransactionCoordinator {
1450
1905
  }
1451
1906
 
1452
1907
  /**
1453
- * Coordinate a transaction across multiple collections.
1908
+ * Coordinate a transaction's attempt across multiple collections: describe what each collection's
1909
+ * staged transforms send ({@link declareTouchedBlocks}), then run the phases
1910
+ * ({@link coordinateAttempts}).
1454
1911
  *
1455
- * @param transaction - The transaction to coordinate
1912
+ * @param context - The write being coordinated (its action id and aged priority)
1456
1913
  * @param validation - What every pend carries for members to re-check, or undefined for an
1457
1914
  * unvalidated pend (see {@link pendValidationFor})
1458
1915
  * @param collectionTransforms - Map of collectionId to its transforms
@@ -1462,30 +1919,45 @@ export class TransactionCoordinator {
1462
1919
  * and the local record name the same number.
1463
1920
  */
1464
1921
  private async coordinateTransaction(
1465
- transaction: Transaction,
1922
+ context: WriteContext,
1466
1923
  validation: PendRequest['validation'],
1467
1924
  collectionTransforms: Map<CollectionId, Transforms>,
1468
1925
  criticalBlocks: Map<CollectionId, BlockId>,
1469
1926
  pendedRevs: ReadonlyMap<CollectionId, number>
1470
1927
  ): Promise<CoordinationResult> {
1471
- const trxId = transaction.id;
1928
+ // Before anything is sent: one materialization of every block the transaction touches, measured
1929
+ // against MAX_BLOCK_BYTES here and declared on the commit below.
1930
+ const described = await this.declareTouchedBlocks(collectionTransforms, criticalBlocks, pendedRevs);
1931
+ if (!described.success) {
1932
+ log('trx:phases trxId=%s refused before sending: %s', context.actionId, described.error);
1933
+ return described;
1934
+ }
1935
+ return this.coordinateAttempts(context, validation, described.attempts);
1936
+ }
1937
+
1938
+ /**
1939
+ * The distributed phases of one attempt — GATHER, PEND, COMMIT, and the CANCEL of what a failed
1940
+ * commit left pending — over every collection's share of it, already described
1941
+ * (`CollectionAttempt`). Run by {@link coordinateTransaction} for a transaction's attempt and by
1942
+ * {@link commitEntryOnce} for a queued entry's, whose attempts the head commit described.
1943
+ */
1944
+ private async coordinateAttempts(
1945
+ context: WriteContext,
1946
+ validation: PendRequest['validation'],
1947
+ attempts: ReadonlyMap<CollectionId, CollectionAttempt>
1948
+ ): Promise<CoordinationResult> {
1949
+ const trxId = context.actionId;
1472
1950
  const t0 = Date.now();
1473
1951
 
1474
1952
  // 1. GATHER phase: collect critical cluster nominees (skip if single collection)
1475
- const criticalBlockIds = Array.from(criticalBlocks.values());
1953
+ const criticalBlockIds = Array.from(attempts.values(), attempt => attempt.tailId);
1476
1954
  const tGather = Date.now();
1477
1955
  const superclusterNominees = await this.gatherPhase(criticalBlockIds);
1478
1956
  const gatherMs = Date.now() - tGather;
1479
1957
 
1480
1958
  // 2. PEND phase: distribute to all block clusters
1481
1959
  const tPend = Date.now();
1482
- const pendResult = await this.pendPhase(
1483
- transaction,
1484
- validation,
1485
- collectionTransforms,
1486
- pendedRevs,
1487
- superclusterNominees
1488
- );
1960
+ const pendResult = await this.pendPhase(context, validation, attempts, superclusterNominees);
1489
1961
  const pendMs = Date.now() - tPend;
1490
1962
  if (!pendResult.success) {
1491
1963
  log('trx:phases trxId=%s gather=%dms pend=%dms (failed) total=%dms', trxId, gatherMs, pendMs, Date.now() - t0);
@@ -1494,17 +1966,12 @@ export class TransactionCoordinator {
1494
1966
 
1495
1967
  // 3. COMMIT phase: commit to all critical blocks (with retry for forward recovery)
1496
1968
  const tCommit = Date.now();
1497
- const commitResult = await this.commitPhase(
1498
- transaction.id as ActionId,
1499
- criticalBlockIds,
1500
- pendResult.pendedBlockIds,
1501
- pendedRevs
1502
- );
1969
+ const commitResult = await this.commitPhase(context, attempts, pendResult.pendedBlockIds);
1503
1970
  const commitMs = Date.now() - tCommit;
1504
1971
  if (!commitResult.success) {
1505
1972
  // Targeted cancel: only cancel collections that are still pending (not already committed)
1506
1973
  await this.cancelPhase(
1507
- transaction.id as ActionId,
1974
+ context.actionId,
1508
1975
  pendResult.pendedBlockIds,
1509
1976
  commitResult.committedCollections
1510
1977
  );
@@ -1572,40 +2039,87 @@ export class TransactionCoordinator {
1572
2039
  return new Set(byId.values());
1573
2040
  }
1574
2041
 
2042
+ /**
2043
+ * What each collection's staged transforms send, described from its live tracker after the log
2044
+ * append: one local materialization of every block the transforms touch
2045
+ * ({@link describeTouchedBlocks}), taken before anything is sent. A block the write would leave
2046
+ * over `MAX_BLOCK_BYTES` refuses the transaction here, as a pend-phase failure carrying the
2047
+ * {@link BlockTooLargeError} — the same shape as a pend too large to send, so `commit` throws it by
2048
+ * name and `execute` reports it as a failure. Otherwise each collection's digests are kept as its
2049
+ * commit's declaration ({@link commitRequestFor}), so the commit does not materialize again, and
2050
+ * the base each update-only block's operations were computed against is read from the same
2051
+ * tracker's pins for its pend (`PendRequest.baseRevs`; storage keeps it with the pending record so
2052
+ * the record is never applied to a different version of the block).
2053
+ *
2054
+ * Purely local: each collection's tracker holds this transaction's staged transforms until the commit
2055
+ * succeeds, under the instance latch the commit span holds. A collection missing from the registry
2056
+ * is a defect here: {@link applyActionsToCollection} has already refused it.
2057
+ */
2058
+ private async declareTouchedBlocks(
2059
+ collectionTransforms: ReadonlyMap<CollectionId, Transforms>,
2060
+ criticalBlocks: ReadonlyMap<CollectionId, BlockId>,
2061
+ pendedRevs: ReadonlyMap<CollectionId, number>
2062
+ ): Promise<{ success: true; attempts: Map<CollectionId, CollectionAttempt> } | PendPhaseFailure> {
2063
+ const attempts = new Map<CollectionId, CollectionAttempt>();
2064
+ for (const [collectionId, transforms] of collectionTransforms) {
2065
+ const collection = this.collections.get(collectionId);
2066
+ if (!collection) {
2067
+ throw new Error(`Collection not found: ${collectionId}`);
2068
+ }
2069
+ const blockIds = blockIdsForTransforms(transforms);
2070
+ const touched = await describeTouchedBlocks(collection.tracker, blockIds);
2071
+ const tooLarge = oversizedBlock(touched.bytes);
2072
+ if (tooLarge) return pendFailure([tooLarge]);
2073
+ attempts.set(collectionId, {
2074
+ transforms,
2075
+ tailId: criticalBlocks.get(collectionId)!,
2076
+ rev: pendedRevs.get(collectionId)!,
2077
+ baseRevs: collection.tracker.stagedBaseRevs(blockIds),
2078
+ blockDigests: touched.digests,
2079
+ });
2080
+ }
2081
+ return { success: true, attempts };
2082
+ }
2083
+
1575
2084
  /**
1576
2085
  * PEND phase: Distribute transaction to all affected block clusters.
1577
2086
  *
1578
- * @param transaction - The transaction being pended (its id names the action; its aged
1579
- * priority rides on an unvalidated pend)
2087
+ * Two or more collections go as ONE request when the transactor can send them so
2088
+ * ({@link pendTogether}); otherwise, and for one collection, each collection is pended on its own.
2089
+ *
2090
+ * @param context - The write being pended (its action id names the action; its aged priority
2091
+ * rides on an unvalidated pend)
1580
2092
  * @param validation - What every pend carries for members to re-check, or undefined for an
1581
2093
  * unvalidated pend (see {@link pendValidationFor})
1582
- * @param collectionTransforms - Map of collectionId to its transforms
1583
- * @param pendedRevs - Per collection, the revision its log entry was stamped with — the pend
1584
- * request repeats it verbatim rather than recomputing from the collection (a recompute after
1585
- * the append could name a different number if the collection refreshed in between).
2094
+ * @param attempts - Per collection, its share of the attempt: its transforms, and the revision
2095
+ * its log entry was stamped with — the pend request repeats it verbatim rather than recomputing
2096
+ * from the collection (a recompute after the append could name a different number if the
2097
+ * collection refreshed in between).
1586
2098
  * @param superclusterNominees - Nominees for multi-collection consensus (null for single-collection)
1587
2099
  */
1588
2100
  private async pendPhase(
1589
- transaction: Transaction,
2101
+ context: WriteContext,
1590
2102
  validation: PendRequest['validation'],
1591
- collectionTransforms: ReadonlyMap<CollectionId, Transforms>,
1592
- pendedRevs: ReadonlyMap<CollectionId, number>,
2103
+ attempts: ReadonlyMap<CollectionId, CollectionAttempt>,
1593
2104
  superclusterNominees: ReadonlySet<PeerId> | null
1594
- ): Promise<
1595
- | { success: true; pendedBlockIds: Map<CollectionId, BlockId[]> }
1596
- | { success: false; error: string; staleLoss?: boolean; expired?: TransactionExpiredError }
1597
- > {
1598
- if (collectionTransforms.size === 0) {
2105
+ ): Promise<{ success: true; pendedBlockIds: Map<CollectionId, BlockId[]> } | PendPhaseFailure> {
2106
+ if (attempts.size === 0) {
1599
2107
  return { success: false, error: 'No transforms to pend' };
1600
2108
  }
1601
2109
 
1602
- const actionId = transaction.id as ActionId;
1603
2110
  const nominees = superclusterNominees ? Array.from(superclusterNominees) : undefined;
2111
+ // Both methods, never the pend alone: the batched pend's mark promises that the commit goes as one
2112
+ // request too (`PendRequest.soleReservation`), which only `commitMany` can keep.
2113
+ if (attempts.size > 1 && this.transactor.pendMany && this.transactor.commitMany) {
2114
+ const together = await this.pendTogether(context, validation, attempts, nominees);
2115
+ if (together !== undefined) return together;
2116
+ }
2117
+
1604
2118
  // A one-collection transaction pends once and commits that one collection (commitPhase), as a
1605
2119
  // `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.
1608
- const sole = collectionTransforms.size === 1;
2120
+ // more pended one by one never may: each collection's commit can land on its own, and a late
2121
+ // refusal of another collection's pend would surface after it.
2122
+ const sole = attempts.size === 1;
1609
2123
 
1610
2124
  // Fan out the independent per-collection pends concurrently. Each settles to a
1611
2125
  // { collectionId, blockIds } on success, or rejects with the per-collection reason.
@@ -1613,127 +2127,155 @@ export class TransactionCoordinator {
1613
2127
  // Transactions touch few collections today; if one ever spans very many, bound this
1614
2128
  // with a concurrency limiter so peak in-flight round-trips stays sane. Same for commitPhase.
1615
2129
  const outcomes = await Promise.allSettled(
1616
- Array.from(collectionTransforms.entries()).map(([collectionId, transforms]) =>
1617
- this.pendCollection(transaction, validation, collectionId, transforms, pendedRevs.get(collectionId)!, actionId, nominees, sole)
2130
+ Array.from(attempts.entries()).map(([collectionId, attempt]) =>
2131
+ this.pendCollection(context, validation, collectionId, attempt, nominees, sole)
1618
2132
  )
1619
2133
  );
1620
2134
 
1621
- // Partition settled results: every collection that DID pend (keyed with its block
1622
- // ids), plus the first failure reason if any collection failed.
2135
+ // Partition settled results: every collection that DID pend (keyed with its block ids), and
2136
+ // every reason one did not, classified together (pendFailure) independent of iteration order.
1623
2137
  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;
2138
+ const reasons: unknown[] = [];
1634
2139
  for (const outcome of outcomes) {
1635
2140
  if (outcome.status === 'fulfilled') {
1636
2141
  pendedBlockIds.set(outcome.value.collectionId, outcome.value.blockIds);
1637
2142
  } 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;
2143
+ reasons.push(outcome.reason);
1644
2144
  }
1645
2145
  }
1646
2146
 
1647
- if (failure !== undefined) {
2147
+ if (reasons.length > 0) {
1648
2148
  // Any failure aborts the whole pend. With concurrency several collections may
1649
2149
  // have pended in parallel, so cancel EVERY successfully-pended collection — not
1650
2150
  // only those started before the failure. Cancels are best-effort (cancelPhase
1651
2151
  // swallows their errors) so they cannot mask the original pend failure.
1652
- await this.cancelPhase(actionId, pendedBlockIds);
1653
- return { success: false, error: failure, staleLoss: anyConflict && !anyHard, ...(expired === undefined ? {} : { expired }) };
2152
+ await this.cancelPhase(context.actionId, pendedBlockIds);
2153
+ return pendFailure(reasons);
1654
2154
  }
1655
2155
 
1656
2156
  return { success: true, pendedBlockIds };
1657
2157
  }
1658
2158
 
2159
+ /**
2160
+ * Pends every collection as ONE request ({@link ITransactor.pendMany}): one consensus record,
2161
+ * answered together. Every request is marked the action's only reservation
2162
+ * (`PendRequest.soleReservation`) — together they are, and their commit goes as one request to the
2163
+ * same coordinator ({@link commitTogether}) — so a coordinator may hold the pend's decision back for
2164
+ * the commit to carry, and a member that refuses any collection's pend late refuses the action's one
2165
+ * commit record before anything of it is durable.
2166
+ *
2167
+ * - **Success**: every collection is pended, with its own blocks.
2168
+ * - **Refusal**: classified as one collection's refusal is ({@link pendRefusalError}), once for the
2169
+ * batch. `pendMany` cancelled every block, so nothing is left pended.
2170
+ * - **Throw** (a transactor other than `NetworkTransactor`, which answers a throw with `undefined`):
2171
+ * a hard failure, as a thrown pend is. What was pended is unknown, so every collection's blocks are
2172
+ * cancelled.
2173
+ * - **`undefined`**: they could not go as one, and nothing of them is pended. {@link pendPhase} then
2174
+ * pends each collection on its own with requests rebuilt WITHOUT the mark. The marked requests are
2175
+ * never re-sent one by one: each carries every block of its collection, so `NetworkTransactor.pend`
2176
+ * would keep the mark, and one collection's late refusal could then surface after a sibling's commit
2177
+ * landed — the tear the mark exists to prevent.
2178
+ */
2179
+ private async pendTogether(
2180
+ context: WriteContext,
2181
+ validation: PendRequest['validation'],
2182
+ attempts: ReadonlyMap<CollectionId, CollectionAttempt>,
2183
+ nominees: PeerId[] | undefined
2184
+ ): Promise<{ success: true; pendedBlockIds: Map<CollectionId, BlockId[]> } | PendPhaseFailure | undefined> {
2185
+ const requests = Array.from(attempts.values(), attempt => this.pendRequestFor(context, validation, attempt, nominees, true));
2186
+ const blockIds = new Map(Array.from(attempts, ([collectionId, attempt]) => [collectionId, blockIdsForTransforms(attempt.transforms)]));
2187
+
2188
+ let result: PendResult | undefined;
2189
+ try {
2190
+ result = await this.transactor.pendMany!(requests);
2191
+ } catch (e) {
2192
+ await this.cancelPhase(context.actionId, blockIds);
2193
+ return pendFailure([e]);
2194
+ }
2195
+ if (result === undefined) return undefined;
2196
+ return result.success
2197
+ ? { success: true, pendedBlockIds: blockIds }
2198
+ : pendFailure([pendRefusalError(Array.from(attempts.keys()), result)]);
2199
+ }
2200
+
1659
2201
  /**
1660
2202
  * Pend a single collection's transforms. Resolves with the collection id and its
1661
2203
  * pended block ids on success; throws with a per-collection reason on failure so the
1662
2204
  * fan-out in {@link pendPhase} can settle it as a rejection.
1663
2205
  */
1664
2206
  private async pendCollection(
1665
- transaction: Transaction,
2207
+ context: WriteContext,
1666
2208
  validation: PendRequest['validation'],
1667
2209
  collectionId: CollectionId,
1668
- transforms: Transforms,
1669
- /** The revision the log entry was stamped with (threaded from applyActionsToCollection),
1670
- * NOT recomputed here: a `getNextRev()` after the append round trips could name a number
1671
- * a concurrent refresh already moved past. */
1672
- rev: number,
1673
- actionId: ActionId,
2210
+ /** Its revision is the one the log entry was stamped with (threaded from the append), NOT
2211
+ * recomputed here: a `getNextRev()` after the append round trips could name a number a
2212
+ * concurrent refresh already moved past. */
2213
+ attempt: CollectionAttempt,
1674
2214
  nominees: PeerId[] | undefined,
1675
2215
  /** Whether this is the transaction's only collection (see {@link pendPhase}). */
1676
2216
  sole: boolean
1677
2217
  ): Promise<{ collectionId: CollectionId; blockIds: BlockId[] }> {
1678
- const collection = this.collections.get(collectionId);
1679
- if (!collection) {
1680
- throw new Error(`Collection not found: ${collectionId}`);
1681
- }
1682
-
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.
1691
- const priority = clampPriority(transaction.priority);
1692
- // 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.
1696
- const baseRevs = collection.tracker.stagedBaseRevs(blockIdsForTransforms(transforms));
1697
- const pendRequest: PendRequest = {
1698
- actionId,
1699
- rev,
1700
- transforms,
2218
+ const pendResult = await this.transactor.pend(
2219
+ this.pendRequestFor(context, validation, attempt, nominees, sole)
2220
+ );
2221
+ if (!pendResult.success) {
2222
+ throw pendRefusalError([collectionId], pendResult);
2223
+ }
2224
+
2225
+ return { collectionId, blockIds: pendResult.blockIds };
2226
+ }
2227
+
2228
+ /**
2229
+ * The pend request for one collection's share of an attempt — the one place a pend request is built,
2230
+ * whether it goes on its own ({@link pendCollection}) or with its siblings ({@link pendTogether}).
2231
+ */
2232
+ private pendRequestFor(
2233
+ context: WriteContext,
2234
+ validation: PendRequest['validation'],
2235
+ attempt: CollectionAttempt,
2236
+ nominees: PeerId[] | undefined,
2237
+ /** Whether this request is the action's whole reservation, alone or with the siblings it is sent
2238
+ * with (`PendRequest.soleReservation`). */
2239
+ sole: boolean
2240
+ ): PendRequest {
2241
+ // This is the only producer of PendRequest.validation, and it always sends the pair whole
2242
+ // (transaction + operations hash) or not at all. The aged priority has one carrier per shape —
2243
+ // inside the transaction when the pend carries it, on the pend itself when it does not — because a
2244
+ // member's race resolution reads the transaction's priority first and falls back to the pend's
2245
+ // (recordPriority in db-p2p's race-resolution.ts); an unvalidated pend that left both empty would
2246
+ // never age. Omitted at 0, exactly as the single-collection path sends it
2247
+ // (TransactorSource.transact), so the common first-attempt pend is indistinguishable from a
2248
+ // Collection.sync pend.
2249
+ // The bases (`PendRequest.baseRevs`) were read from the same tracker the commit's declaration was
2250
+ // taken from, when the attempt was described; omitted when empty.
2251
+ return {
2252
+ actionId: context.actionId,
2253
+ rev: attempt.rev,
2254
+ transforms: attempt.transforms,
1701
2255
  policy: 'r', // Return policy: fail but return pending actions
1702
2256
  ...(validation === undefined
1703
- ? (priority > 0 ? { priority } : {})
2257
+ ? (context.priority > 0 ? { priority: context.priority } : {})
1704
2258
  : { validation }),
1705
- ...baseRevsField(baseRevs),
2259
+ ...baseRevsField(attempt.baseRevs),
1706
2260
  superclusterNominees: nominees,
1707
- ...(sole ? { soleReservation: true as const } : {})
2261
+ ...(sole ? { soleReservation: true as const } : {}),
2262
+ ...refuseSoloField(context.refuseSolo)
1708
2263
  };
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
2264
  }
1724
2265
 
1725
2266
  /**
1726
2267
  * COMMIT phase: Commit to all critical blocks with retry for transient failures.
1727
2268
  *
1728
2269
  * 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.
2270
+ * to commit. Two or more collections go as ONE request when the transactor can send them so
2271
+ * ({@link commitTogether}); otherwise each collection commits on its own, its transient failures
2272
+ * retried (forward recovery) before giving up. Returns which collections committed vs failed so
2273
+ * the caller can do targeted cancel.
1731
2274
  */
1732
2275
  private async commitPhase(
1733
- actionId: ActionId,
1734
- criticalBlockIds: BlockId[],
1735
- pendedBlockIds: Map<CollectionId, BlockId[]>,
1736
- pendedRevs: ReadonlyMap<CollectionId, number>
2276
+ context: WriteContext,
2277
+ attempts: ReadonlyMap<CollectionId, CollectionAttempt>,
2278
+ pendedBlockIds: Map<CollectionId, BlockId[]>
1737
2279
  ): Promise<{
1738
2280
  success: boolean;
1739
2281
  error?: string;
@@ -1743,17 +2285,24 @@ export class TransactionCoordinator {
1743
2285
  staleLoss?: boolean;
1744
2286
  expired?: TransactionExpiredError;
1745
2287
  }> {
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
- );
2288
+ const together = pendedBlockIds.size > 1 && this.transactor.commitMany
2289
+ ? await this.commitTogether(context, attempts, pendedBlockIds)
2290
+ : undefined;
2291
+ // NOTE: a fallback after a batched pend leaves the multi-collection residual in place: the
2292
+ // pend's decision may have been held back for a commit that now goes per collection, so a member
2293
+ // that refuses one collection's pend late can do so after a sibling collection's commit landed —
2294
+ // reported by forward recovery or `CoordinatorPartialCommitError`. Reached through a thrown
2295
+ // batched commit (`NetworkTransactor.commitMany` answers `undefined` for that). Anything else that
2296
+ // keeps a batch from going as one would have kept the batched pend from going too, except one
2297
+ // case: the coordinator `pendMany` cached for every block evicted before the commit ran (the
2298
+ // cache's TTL is at least a minute, its size cap 1000 transactions), so a live lookup can split
2299
+ // the blocks. If that ever shows up, pin the commit to the coordinator the batched pend answered
2300
+ // from. See docs/correctness.md §2 Definitions.
2301
+ const outcomes = together ?? await this.commitEach(context, attempts, pendedBlockIds);
1753
2302
 
1754
2303
  const committedCollections = new Map<CollectionId, WriteDurability>();
1755
2304
  const failedCollections = new Set<CollectionId>();
1756
- const errors: string[] = [];
2305
+ const errors = new Set<string>();
1757
2306
  // Classify failures: a returned stale loss (someone committed a newer rev) is retryable after
1758
2307
  // a re-read; a thrown/transient-exhausted or structural failure is not. staleLoss holds only
1759
2308
  // if EVERY failure was a stale loss — a single hard failure makes the whole attempt not worth
@@ -1761,29 +2310,22 @@ export class TransactionCoordinator {
1761
2310
  let anyStale = false;
1762
2311
  let anyHard = false;
1763
2312
  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
- }
2313
+ for (const result of outcomes) {
2314
+ if (result.committed) {
2315
+ committedCollections.set(result.collectionId, result.durability);
1775
2316
  } 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;
2317
+ failedCollections.add(result.collectionId);
2318
+ // A set: a batched refusal answers every collection with the one reason.
2319
+ errors.add(result.error);
2320
+ if (result.stale) anyStale = true; else anyHard = true;
2321
+ expired ??= result.expired;
1780
2322
  }
1781
2323
  }
1782
2324
 
1783
- if (failedCollections.size > 0 || errors.length > 0) {
2325
+ if (failedCollections.size > 0) {
1784
2326
  return {
1785
2327
  success: false,
1786
- error: errors.join('; ') || 'Commit failed',
2328
+ error: Array.from(errors).join('; ') || 'Commit failed',
1787
2329
  committedCollections,
1788
2330
  failedCollections,
1789
2331
  staleLoss: anyStale && !anyHard,
@@ -1794,49 +2336,80 @@ export class TransactionCoordinator {
1794
2336
  return { success: true, committedCollections, failedCollections };
1795
2337
  }
1796
2338
 
2339
+ /**
2340
+ * Commits every collection as ONE request ({@link ITransactor.commitMany}): one consensus record,
2341
+ * decided together — the commit half of {@link pendTogether}. Every collection gets the batch's one
2342
+ * answer ({@link collectionCommitOutcome}): committed, each stamped with its own blocks and revision;
2343
+ * or refused, every collection alike. A refused collection's attempt is then retained by
2344
+ * `commitOnceLatched`, and the refresh between attempts finishes any collection whose log entry did
2345
+ * land (`Collection.completeOwnEntry`) — the path a refused one-collection commit already takes.
2346
+ *
2347
+ * `undefined` when they could not go as one, when the request threw, or when a collection's request
2348
+ * could not be built (no log tail among its pended blocks): {@link commitPhase} then commits each
2349
+ * collection on its own, which re-sends everything and reports a request it cannot build as it
2350
+ * always has. The batch is never retried here: a returned refusal cannot be won by the identical
2351
+ * request, and a throw is the per-collection path's to retry.
2352
+ */
2353
+ private async commitTogether(
2354
+ context: WriteContext,
2355
+ attempts: ReadonlyMap<CollectionId, CollectionAttempt>,
2356
+ pendedBlockIds: Map<CollectionId, BlockId[]>
2357
+ ): Promise<CollectionCommitOutcome[] | undefined> {
2358
+ const actionId = context.actionId;
2359
+ const requests: { collectionId: CollectionId; request: CommitRequest }[] = [];
2360
+ for (const [collectionId, blockIds] of pendedBlockIds) {
2361
+ const request = this.commitRequestFor(context, collectionId, attempts.get(collectionId)!, blockIds);
2362
+ if (typeof request === 'string') return undefined;
2363
+ requests.push({ collectionId, request });
2364
+ }
2365
+
2366
+ let result: CommitResult | undefined;
2367
+ try {
2368
+ result = await this.transactor.commitMany!(requests.map(({ request }) => request));
2369
+ } catch (e) {
2370
+ log('commitTogether: batched commit threw; committing each collection on its own actionId=%s: %o', actionId, e);
2371
+ return undefined;
2372
+ }
2373
+ return result === undefined
2374
+ ? undefined
2375
+ : requests.map(({ collectionId, request }) => collectionCommitOutcome(collectionId, request, result));
2376
+ }
2377
+
2378
+ /** Commits each collection on its own, concurrently ({@link commitCollection}), one outcome per collection. */
2379
+ private async commitEach(
2380
+ context: WriteContext,
2381
+ attempts: ReadonlyMap<CollectionId, CollectionAttempt>,
2382
+ pendedBlockIds: Map<CollectionId, BlockId[]>
2383
+ ): Promise<CollectionCommitOutcome[]> {
2384
+ const entries = Array.from(pendedBlockIds.entries());
2385
+ const settled = await Promise.allSettled(entries.map(([collectionId, blockIds]) =>
2386
+ this.commitCollection(context, collectionId, attempts.get(collectionId)!, blockIds)
2387
+ ));
2388
+ // commitCollection resolves rather than rejects, but treat any unexpected rejection as a (hard)
2389
+ // failure of its collection so the partitioned sets stay honest.
2390
+ return settled.map((outcome, i) => outcome.status === 'fulfilled'
2391
+ ? outcome.value
2392
+ : { collectionId: entries[i]![0], committed: false, error: outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason) });
2393
+ }
2394
+
1797
2395
  /**
1798
2396
  * Commit a single collection's pended blocks, retrying transient failures up to three
1799
2397
  * times (forward recovery). Always resolves — success is carried in the returned
1800
2398
  * `committed` flag, with the commit's `durability` beside it — so the fan-out in
1801
- * {@link commitPhase} can aggregate every result.
2399
+ * {@link commitEach} can aggregate every result.
1802
2400
  */
1803
2401
  private async commitCollection(
1804
- actionId: ActionId,
1805
- criticalBlockIds: BlockId[],
2402
+ context: WriteContext,
1806
2403
  collectionId: CollectionId,
1807
- 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
2404
+ /** Its revision is the one this collection PENDED at (see {@link commitRequestFor}). */
2405
+ attempt: CollectionAttempt,
2406
+ blockIds: BlockId[]
1812
2407
  ): Promise<CollectionCommitOutcome> {
1813
- const collection = this.collections.get(collectionId);
1814
- if (!collection) {
1815
- return { collectionId, committed: false, error: `Collection not found: ${collectionId}` };
1816
- }
1817
-
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}` };
2408
+ const commitRequest = this.commitRequestFor(context, collectionId, attempt, blockIds);
2409
+ if (typeof commitRequest === 'string') {
2410
+ return { collectionId, committed: false, error: commitRequest };
1822
2411
  }
1823
2412
 
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
2413
  // Retry ONLY transient/thrown failures (unreachable peers, timeout) — forward recovery.
1841
2414
  // A returned { success:false } is a refusal the IDENTICAL request can never win (a rival
1842
2415
  // committed a newer rev, or a member behind on the base refused and dropped its pending
@@ -1849,38 +2422,7 @@ export class TransactionCoordinator {
1849
2422
  let lastTransientError: string | undefined;
1850
2423
  for (let attempt = 0; attempt < 3; attempt++) {
1851
2424
  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
- };
2425
+ return collectionCommitOutcome(collectionId, commitRequest, await this.transactor.commit(commitRequest));
1884
2426
  } catch (e) {
1885
2427
  lastTransientError = e instanceof Error ? e.message : String(e);
1886
2428
  }
@@ -1888,6 +2430,40 @@ export class TransactionCoordinator {
1888
2430
  return { collectionId, committed: false, error: `Commit failed for collection ${collectionId} after 3 attempts: ${lastTransientError}` };
1889
2431
  }
1890
2432
 
2433
+ /**
2434
+ * The commit request for one collection's pended blocks — the one place a commit request is built,
2435
+ * whether it goes on its own ({@link commitCollection}) or with its siblings ({@link commitTogether})
2436
+ * — or, as a string, why there is none.
2437
+ */
2438
+ private commitRequestFor(
2439
+ context: WriteContext,
2440
+ collectionId: CollectionId,
2441
+ /** Its revision is the one this collection PENDED at, threaded from the log append — the same
2442
+ * bug family as pendCollection's: recomputing `getNextRev()` here, after the pend round trips,
2443
+ * could stamp the CommitRequest with a different number than the pend named. */
2444
+ attempt: CollectionAttempt,
2445
+ blockIds: BlockId[]
2446
+ ): CommitRequest | string {
2447
+ // The critical block (log tail) for this collection must be among what the pend reserved.
2448
+ if (!blockIds.includes(attempt.tailId)) {
2449
+ return `Log tail block not found for collection ${collectionId}`;
2450
+ }
2451
+
2452
+ // Declare what each pended block will contain once committed: the description taken before the
2453
+ // pend (declareTouchedBlocks, or stageAttempt for a queued entry's), over the blocks the pend
2454
+ // carried. An id whose base was not cached is omitted and falls back to corroboration on the
2455
+ // member side. Only the client can declare this — CoordinatorRepo.commit forwards without
2456
+ // materializing.
2457
+ return {
2458
+ actionId: context.actionId,
2459
+ blockIds,
2460
+ tailId: attempt.tailId,
2461
+ rev: attempt.rev,
2462
+ ...blockDigestsField(attempt.blockDigests),
2463
+ ...refuseSoloField(context.refuseSolo)
2464
+ };
2465
+ }
2466
+
1891
2467
  /**
1892
2468
  * CANCEL phase: Cancel pending actions on affected blocks.
1893
2469
  *