@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,15 +1,22 @@
1
- import { isConflictFailure, isExpiryFailure } from "../network/stale-failure.js";
1
+ import { isConflictFailure, isExpiryFailure, isRejectedFailure, isShortfallFailure } from "../network/stale-failure.js";
2
2
  import { withBlockRevs } from "../network/durability.js";
3
3
  import { TransactionExpiredError } from "../network/transaction-expired-error.js";
4
+ import { PromiseShortfallError } from "../network/promise-shortfall-error.js";
5
+ import { ValidityRejectedError } from "../network/validity-rejected-error.js";
6
+ import { refuseSoloField } from "../network/refuse-solo.js";
7
+ import { TransactionTooLargeError } from "../network/transaction-size.js";
8
+ import { BlockTooLargeError, oversizedBlock } from "../network/block-size.js";
4
9
  import { TornActionError } from "../collection/struct.js";
5
10
  import { isTransactionExpired, clampPriority } from "./transaction.js";
11
+ import { EntryParticipants, writeContextOf } from "./entry-commit.js";
6
12
  import { Log } from "../log/log.js";
7
13
  import { blockIdsForTransforms, copyTransforms } from "../transform/helpers.js";
8
- import { computeBlockContentDigests, blockDigestsField, baseRevsField } from "../transform/digest.js";
14
+ import { describeTouchedBlocks, blockDigestsField, baseRevsField } from "../transform/digest.js";
9
15
  import { collectOperations, hashOperations } from "./operations-hash.js";
10
16
  import { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from "./errors.js";
11
17
  import { recordCollectionDurability, transactionDurability } from "./durability.js";
12
18
  import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
19
+ import { visitEveryThenThrow } from "../utility/visit-every.js";
13
20
  import { createLogger } from "../logger.js";
14
21
  const log = createLogger('trx:coordinator');
15
22
  /** Default max consecutive clean-stale-loss retries before {@link TransactionCoordinator.commit}
@@ -22,29 +29,215 @@ const DefaultMaxBackoffMs = 5000;
22
29
  /**
23
30
  * A pend that failed. `conflict` marks the retryable class — an optimistic-concurrency collision that
24
31
  * a re-read + re-pend can clear — as decided by `isConflictFailure` over the failure response. A hard
25
- * rejection (storage full, policy) is NOT a conflict and is not worth re-driving. Thrown by
26
- * {@link TransactionCoordinator.pendCollection} so the fan-out in pendPhase can settle it and read
27
- * the flag off the rejection.
32
+ * rejection (storage full, policy) is NOT a conflict and is not worth re-driving. Built by
33
+ * {@link pendRefusalError} for one collection's pend, or for every collection of a batched one, and
34
+ * classified by {@link pendFailure}, which reads the flag off it.
28
35
  */
29
36
  class PendRejectedError extends Error {
30
37
  conflict;
31
- constructor(collectionId, conflict, reason,
38
+ constructor(collectionIds, conflict, reason,
32
39
  /** Confirmed revision the responder holds, from `StaleFailure.staleAt`. Folded into the
33
40
  * message because pendPhase collapses this error to its `.message` string, which is the only
34
41
  * form that reaches an embedder through the transaction result's `error` field. */
35
42
  staleAt) {
36
- super(`Pend failed for collection ${collectionId}: ${reason ?? (conflict ? 'stale conflict' : 'rejected')}`
43
+ super(`Pend failed for ${collectionIds.length === 1 ? 'collection' : 'collections'} ${collectionIds.join(', ')}: ${reason ?? (conflict ? 'stale conflict' : 'rejected')}`
37
44
  + (staleAt ? ` (block ${staleAt.blockId} at rev ${staleAt.rev})` : ''));
38
45
  this.conflict = conflict;
39
46
  this.name = 'PendRejectedError';
40
47
  }
41
48
  }
49
+ /** The error a refused pend of `collectionIds` stands for: its validity rejection — never retried, since
50
+ * a re-drive sends the same content to the same checks — its expiry — never retried, since a re-drive's
51
+ * expiration comes from the same clock — or its promise shortfall — never retried, since a re-drive
52
+ * meets the same silent members — or a rejection carrying whether a re-read can clear it.
53
+ * Retryability comes from the response itself: a producer that classified the failure sets `conflict`,
54
+ * and only where none did is it inferred from `missing`/`pending` (`isConflictFailure`). */
55
+ function pendRefusalError(collectionIds, refusal) {
56
+ if (isRejectedFailure(refusal))
57
+ return new ValidityRejectedError(refusal.rejected);
58
+ if (isExpiryFailure(refusal))
59
+ return new TransactionExpiredError(refusal.expired);
60
+ if (isShortfallFailure(refusal))
61
+ return new PromiseShortfallError(refusal.shortfall);
62
+ return new PendRejectedError(collectionIds, isConflictFailure(refusal), refusal.reason, refusal.staleAt);
63
+ }
64
+ /** A head commit's staged attempt as the phases send it: its transforms are the attempt tracker's. */
65
+ function collectionAttemptOf(staged) {
66
+ return {
67
+ transforms: staged.tracker.transforms,
68
+ tailId: staged.tailId,
69
+ rev: staged.rev,
70
+ baseRevs: staged.baseRevs,
71
+ blockDigests: staged.blockDigests,
72
+ };
73
+ }
74
+ /**
75
+ * The pend phase's failure for `reasons` — what every failed pend threw or stood for, at least one.
76
+ * The error text is the first reason's. The attempt is a retryable clean stale loss only if at least one
77
+ * reason was a conflicting pend ({@link PendRejectedError}`.conflict`) AND none was a hard failure: a
78
+ * single hard failure (storage/policy rejection, or a thrown/unavailable transactor) will not clear on a
79
+ * re-read, so re-driving it would just burn the retry budget. A validity rejection, an expiry, a promise
80
+ * shortfall, and a pend or a block too large to send, are hard failures carried whole: each is the error
81
+ * the commit surfaces.
82
+ */
83
+ function pendFailure(reasons) {
84
+ const first = reasons[0];
85
+ const conflicts = reasons.filter(reason => reason instanceof PendRejectedError && reason.conflict);
86
+ const rejected = reasons.find((reason) => reason instanceof ValidityRejectedError);
87
+ const expired = reasons.find((reason) => reason instanceof TransactionExpiredError);
88
+ const shortfall = reasons.find((reason) => reason instanceof PromiseShortfallError);
89
+ const tooLarge = reasons.find((reason) => reason instanceof TransactionTooLargeError || reason instanceof BlockTooLargeError);
90
+ return {
91
+ success: false,
92
+ error: first instanceof Error ? first.message : String(first),
93
+ staleLoss: conflicts.length > 0 && conflicts.length === reasons.length,
94
+ ...(rejected === undefined ? {} : { rejected }),
95
+ ...(expired === undefined ? {} : { expired }),
96
+ ...(shortfall === undefined ? {} : { shortfall }),
97
+ ...(tooLarge === undefined ? {} : { tooLarge }),
98
+ };
99
+ }
100
+ /** What a commit's `options` ask of every send of its cycle. */
101
+ function inFlightCycleOf(options) {
102
+ return options?.refuseSoloCommit === true ? { refuseSolo: true } : {};
103
+ }
104
+ /**
105
+ * How `collectionId`'s commit ended when `result` answered its `request` — the answer to its own
106
+ * commit, or, in a batched commit, the batch's one answer for every collection of it. A success is
107
+ * stamped with the collection's own blocks at its own revision (`withBlockRevs`).
108
+ */
109
+ function collectionCommitOutcome(collectionId, request, result) {
110
+ if (result.success) {
111
+ return { collectionId, committed: true, durability: withBlockRevs(result.durability, request.blockIds, request.rev) };
112
+ }
113
+ if (isExpiryFailure(result)) {
114
+ // Not a stale loss: a re-drive's expiration comes from the same clock.
115
+ const expired = new TransactionExpiredError(result.expired);
116
+ return { collectionId, committed: false, error: expired.message, expired };
117
+ }
118
+ // Permanent stale failure: never retried verbatim. It IS a clean stale loss, though, so mark it
119
+ // retryable at the coordinator level (after a re-read advances the rev).
120
+ // NOTE: deliberately does NOT consult `isConflictFailure` / `StaleFailure.conflict` like the pend
121
+ // path does. Once the pend succeeded, a returned commit failure means the revision slot moved, or a
122
+ // member behind on the base refused — the durability gate's `commit-not-durable` (which does set
123
+ // `conflict`) or a solo StorageRepo's `missing-base-revision` (a bare `reason`, no `conflict`). All of
124
+ // these clear on a re-drive, so gating on `conflict` here would fail the last of them fast. One commit
125
+ // producer DOES set `conflict` now — db-p2p's CoordinatorRepo.commit returns lost commit-consensus
126
+ // races and classified stale-commit rejections as `{ success:false, conflict:true }` (returning, not
127
+ // throwing, is what keeps them out of commitCollection's verbatim retry) — but every returned failure
128
+ // still maps to `stale: true` here, and `isConflictFailure` covers that new shape, so no behavior
129
+ // change is needed. The one returned refusal that is NOT a stale loss, an expiry, is split off above.
130
+ // If a commit producer ever starts returning other hard commit rejections (validator policy, storage
131
+ // fault) as results too, gate `stale` on isConflictFailure here.
132
+ return {
133
+ collectionId,
134
+ committed: false,
135
+ stale: true,
136
+ error: result.reason ?? `Stale commit for collection ${collectionId}`
137
+ };
138
+ }
42
139
  /** What a successful commit wrote: `written` folded into one report, or `undefined` when it holds
43
140
  * nothing (nothing was staged, so there was no pend and no commit — the same hole
44
141
  * `Collection.sync` has). */
45
142
  function writtenDurability(written) {
46
143
  return written.size === 0 ? undefined : transactionDurability(written);
47
144
  }
145
+ /**
146
+ * The error an attempt whose phases failed with NOTHING committed is thrown as. A clean stale loss
147
+ * — every refusal a conflict a re-read can clear — is {@link CoordinatorStaleLossError}, which the
148
+ * retry loop re-drives. The four refusals a re-drive can never clear are thrown by name: a validity
149
+ * rejection (the retry's pend would send the same content to the same checks), an expiry (the
150
+ * retry's expiration comes from the same clock), a promise shortfall (the retry meets the same
151
+ * silent members), and a pend or block too large to send. Anything else is a plain error, the
152
+ * historical fail-fast for a hard failure.
153
+ */
154
+ function cleanFailureError(result, failed) {
155
+ if (result.staleLoss) {
156
+ return new CoordinatorStaleLossError(failed, result.error);
157
+ }
158
+ return result.rejected ?? result.expired ?? result.shortfall ?? result.tooLarge
159
+ ?? new Error(`Transaction commit failed: ${result.error}`);
160
+ }
161
+ /**
162
+ * The retry budget one {@link TransactionCoordinator.commitAttempts} cycle spends: attempts and
163
+ * refused refresh rounds alike are counted against `maxAttempts`, under the wall-clock `deadlineMs`
164
+ * and the abort `signal`, with the same jittered backoff policy `Collection.sync` uses between
165
+ * rounds. There is no forward-progress notion here (a commit either lands or it does not), so this
166
+ * simply bounds how many times a losing write is re-driven. The single-collection accounting
167
+ * (`AttemptCycle`) also checks for a wedged revision view; this one cannot yet, since the confirmed
168
+ * revision does not reach it (backlog `debt-multi-collection-retry-cannot-see-the-taken-revision`).
169
+ */
170
+ class RetryBudget {
171
+ maxAttempts;
172
+ backoff;
173
+ deadlineMs;
174
+ signal;
175
+ rand;
176
+ startedAt = Date.now();
177
+ /** Consecutive clean stale losses: attempts, and refresh rounds refused for a cause that can clear. */
178
+ losses = 0;
179
+ lastLoss;
180
+ constructor(options) {
181
+ this.maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
182
+ this.backoff = {
183
+ baseMs: options?.baseBackoffMs ?? DefaultBaseBackoffMs,
184
+ capMs: options?.maxBackoffMs ?? DefaultMaxBackoffMs,
185
+ };
186
+ this.deadlineMs = options?.deadlineMs;
187
+ this.signal = options?.signal;
188
+ this.rand = options?.rand;
189
+ }
190
+ /** The checks before an attempt: the abort signal, and — a progress-agnostic ceiling, once at
191
+ * least one loss was taken — the wall-clock deadline, reported as that loss. */
192
+ assertOpen() {
193
+ if (this.signal?.aborted) {
194
+ throw makeAbortError(this.signal);
195
+ }
196
+ if (this.lastLoss !== undefined && this.pastDeadline()) {
197
+ throw this.lastLoss;
198
+ }
199
+ }
200
+ /** The aged retry priority for the next attempt, from the losses taken so far, so a
201
+ * repeatedly-losing write out-ranks fresh (priority-0) rivals in the cluster's `resolveRace`.
202
+ * Fairness-only and capped at `MaxPriority`; 0 on the first attempt, so the initial pend
203
+ * serializes exactly as before. */
204
+ priority() {
205
+ return clampPriority(this.losses);
206
+ }
207
+ /** Count a clean stale loss of an attempt; thrown back when that spends the budget. */
208
+ recordLoss(loss) {
209
+ this.lastLoss = loss;
210
+ this.losses++;
211
+ if (this.losses >= this.maxAttempts) {
212
+ throw loss;
213
+ }
214
+ }
215
+ /** The backoff before a refresh round: none ahead of a cycle's opening round, there being no
216
+ * race to space out; otherwise jittered and growing with the losses taken, so a herd of writers
217
+ * that lost the same race does not re-collide on the next tick. */
218
+ async pause() {
219
+ if (this.losses === 0) {
220
+ return;
221
+ }
222
+ await abortableDelay(jitteredBackoffMs(this.losses - 1, this.backoff, this.rand), this.signal);
223
+ }
224
+ /** Whether the next refresh round spends the last of the budget, so a participant whose
225
+ * half-landed write is refused again settles it rather than ask for a round it will not get. */
226
+ lastChance() {
227
+ return this.losses + 1 >= this.maxAttempts;
228
+ }
229
+ /** Count a refresh round refused for a cause that can clear (a `completion-refused`
230
+ * {@link TornActionError}); thrown back when that spends the budget or passes the deadline. */
231
+ recordRefusedRound(refused) {
232
+ this.losses++;
233
+ if (this.losses >= this.maxAttempts || this.pastDeadline()) {
234
+ throw refused;
235
+ }
236
+ }
237
+ pastDeadline() {
238
+ return this.deadlineMs !== undefined && Date.now() - this.startedAt >= this.deadlineMs;
239
+ }
240
+ }
48
241
  /**
49
242
  * Coordinates multi-collection transactions.
50
243
  *
@@ -236,7 +429,9 @@ export class TransactionCoordinator {
236
429
  * unavailable transactor, unreachable cluster) also propagates without retry — including a pend
237
430
  * or commit the cohort refused because the transaction had expired by its members' clocks, which
238
431
  * surfaces as {@link TransactionExpiredError} (inside a partial commit's `reason` once a sibling
239
- * has landed).
432
+ * has landed), a pend too few of the cohort's members answered, which surfaces as
433
+ * {@link PromiseShortfallError}, and a pend the members that sank it judged invalid, which surfaces
434
+ * as {@link ValidityRejectedError}.
240
435
  *
241
436
  * A participant can also be SAVED between attempts: an attempt that reported a loss may still
242
437
  * have stored that participant's log tail, and the refresh before the next attempt then finishes
@@ -273,14 +468,45 @@ export class TransactionCoordinator {
273
468
  inFlightDisposers: [],
274
469
  participants: new Set(),
275
470
  saved: new Map(),
471
+ inFlight: inFlightCycleOf(options),
472
+ };
473
+ const driver = {
474
+ opensWithRefresh: false,
475
+ attempt: priority => {
476
+ // Age the transaction's advisory priority by the losses taken so far (see
477
+ // RetryBudget.priority). Set on the transaction itself because a validated pend carries
478
+ // the transaction, and a member's race resolution reads the priority off it; excluded
479
+ // from the tx id / client signature, so bumping it does not churn identity. Left
480
+ // untouched on the first attempt so the initial pend serializes exactly as before.
481
+ if (priority > 0) {
482
+ transaction.priority = priority;
483
+ }
484
+ return this.commitOnce(transaction, cycle);
485
+ },
486
+ refresh: lastChance => this.refreshBetweenAttempts(this.registeredRefreshers(), cycle, lastChance),
487
+ // Tested on what is still STAGED, not on "every participant saved": a participant can be
488
+ // saved and still hold actions staged after the attempt began, and those the next attempt
489
+ // must commit.
490
+ nothingLeft: () => this.stagedCollections().length === 0,
276
491
  };
277
492
  try {
278
- return await this.commitAttempts(transaction, cycle, options);
493
+ const written = await this.commitAttempts(driver, cycle, options);
494
+ // Released on every successful exit. An attempt that commits releases it itself; this is
495
+ // for the exit where the refresh between attempts saved what was left, whose consume and
496
+ // replay already gave each saved participant the success path's local treatment.
497
+ this.stampData.delete(transaction.stamp.id);
498
+ return written;
279
499
  }
280
500
  catch (err) {
281
501
  // The ONE place a failure leaves this commit, so no exit — present or future — can skip
282
502
  // reporting a participant that is already saved.
283
- throw this.reportSaved(transaction, cycle, err);
503
+ const reported = this.reportSaved(transaction.id, cycle, err);
504
+ if (reported instanceof CoordinatorPartialCommitError) {
505
+ // The stamp is released, as on the attempt-level partial path (which has already
506
+ // released it): the transaction can no longer be cleanly rolled back.
507
+ this.stampData.delete(transaction.stamp.id);
508
+ }
509
+ throw reported;
284
510
  }
285
511
  finally {
286
512
  // The in-flight marks must outlive each individual attempt (see CommitCycle), so they are
@@ -291,41 +517,32 @@ export class TransactionCoordinator {
291
517
  }
292
518
  }
293
519
  }
294
- /** The retry loop behind {@link commit}: every attempt, and the refresh between them. Records
295
- * what it learns in `cycle`; {@link commit} owns turning a failure into the right report. On
296
- * success, reports every participant the cycle saved together with what the final attempt
297
- * committed (see {@link commit}'s return). */
298
- async commitAttempts(transaction, cycle, options) {
299
- const maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
300
- const baseBackoffMs = options?.baseBackoffMs ?? DefaultBaseBackoffMs;
301
- const maxBackoffMs = options?.maxBackoffMs ?? DefaultMaxBackoffMs;
302
- const deadlineMs = options?.deadlineMs;
303
- const signal = options?.signal;
304
- const startedAt = Date.now();
305
- // Count of consecutive clean stale losses. There is no forward-progress notion here (a
306
- // single commit either lands or it does not), so this simply bounds how many times we
307
- // re-drive a losing transaction before surfacing a terminal error.
308
- let staleLosses = 0;
309
- let lastLoss;
310
- for (;;) {
311
- if (signal?.aborted) {
312
- throw makeAbortError(signal);
313
- }
314
- // Progress-agnostic ceiling: once we've taken at least one loss, give up if the
315
- // wall-clock deadline passed (independent of the attempt cap).
316
- if (deadlineMs !== undefined && lastLoss && Date.now() - startedAt >= deadlineMs) {
317
- throw lastLoss;
318
- }
319
- // Age the transaction's advisory priority by the number of losses taken so far, so a
320
- // repeatedly-losing transaction out-ranks fresh (priority-0) rivals in the cluster's
321
- // resolveRace. Fairness-only and capped at MaxPriority; excluded from the tx id / client
322
- // signature, so bumping it here does not churn identity. Left untouched on the first
323
- // attempt (staleLosses == 0) so the initial pend serializes exactly as before.
324
- if (staleLosses > 0) {
325
- transaction.priority = clampPriority(staleLosses);
520
+ /**
521
+ * The retry loop behind {@link commit} and {@link commitEntry}: every attempt, and the refresh
522
+ * rounds between them, over the `driver`'s steps and the budget `options` sets
523
+ * ({@link RetryBudget}). Records what it learns in `cycle`; the caller owns turning a failure into
524
+ * the right report. On success, reports every participant the cycle saved together with what the
525
+ * final attempt committed (see {@link commit}'s return).
526
+ *
527
+ * Only a CLEAN stale loss is retried. A partial landing on a hard failure, an expired transaction,
528
+ * an unavailable transactor, etc. all propagate unchanged. Once a refresh round has saved a
529
+ * participant and the driver has nothing left to commit, the write is finished and the loop
530
+ * returns at once rather than going round again, where an abort, the deadline or an expiry check
531
+ * could still report failure for a write that is entirely saved.
532
+ */
533
+ async commitAttempts(driver, cycle, options) {
534
+ const budget = new RetryBudget(options);
535
+ if (driver.opensWithRefresh) {
536
+ budget.assertOpen();
537
+ await this.refreshRounds(driver, budget);
538
+ if (cycle.saved.size > 0 && driver.nothingLeft()) {
539
+ return transactionDurability(cycle.saved);
326
540
  }
541
+ }
542
+ for (;;) {
543
+ budget.assertOpen();
327
544
  try {
328
- const committed = await this.commitOnce(transaction, cycle);
545
+ const committed = await driver.attempt(budget.priority());
329
546
  // Merged, not overwritten, should one participant be both saved and committed (see the
330
547
  // NOTE in reportSaved).
331
548
  const written = new Map(cycle.saved);
@@ -335,95 +552,92 @@ export class TransactionCoordinator {
335
552
  return writtenDurability(written);
336
553
  }
337
554
  catch (err) {
338
- // Only a CLEAN stale loss is retryable. A partial landing, an expired transaction, an
339
- // unavailable transactor, etc. all propagate unchanged.
340
555
  if (!(err instanceof CoordinatorStaleLossError)) {
341
556
  throw err;
342
557
  }
343
- lastLoss = err;
344
- staleLosses++;
345
- if (staleLosses >= maxAttempts) {
346
- throw err;
347
- }
348
- // Re-read fresh state before re-attempting so the next commit pends against current
349
- // revisions (mirrors how Collection.sync calls updateInternal() before retrying).
350
- //
351
- // A participant whose log tail landed despite the reported loss finds its own entry
352
- // here and FINISHES that action before consuming it (Collection.completeOwnEntry,
353
- // from the attempt commitOnceLatched retained). When finishing is refused for a cause
354
- // that can clear, the refresh — not the commit — is what gets retried: the
355
- // participant's log entry is already durable, and once a refresh adopts a newer
356
- // revision commitOnce appends a SECOND entry under this transaction's id. (At an
357
- // unchanged revision the re-append is byte-identical — see
358
- // Collection.logAppendBlockIds — so what is at stake is the duplicate entry, not two
359
- // versions of one tail block.)
360
- // Each such round counts against the same budget as a stale loss; a permanent
361
- // refusal (a rival holds the revision) escapes as the named TornActionError at once.
362
- // Re-refreshing collections an earlier round already refreshed is a no-op.
363
- // The round that would spend the last of the budget is told so, which makes each
364
- // participant SETTLE a half-landed write rather than ask for another round: the
365
- // error thrown below then says whether the write can still land (`final`). A
366
- // deadline cannot be foreseen the same way; a write given up on it stays unsettled.
367
- for (;;) {
368
- const delay = jitteredBackoffMs(staleLosses - 1, { baseMs: baseBackoffMs, capMs: maxBackoffMs }, options?.rand);
369
- await abortableDelay(delay, signal);
370
- const refused = await this.refreshBetweenAttempts(cycle, staleLosses + 1 >= maxAttempts);
371
- if (refused === undefined) {
372
- break;
373
- }
374
- staleLosses++;
375
- if (staleLosses >= maxAttempts
376
- || (deadlineMs !== undefined && Date.now() - startedAt >= deadlineMs)) {
377
- throw refused;
378
- }
379
- }
380
- if (cycle.saved.size > 0 && this.stagedCollections().length === 0) {
381
- // The refresh saved what was left: nothing is staged any more, so this transaction
382
- // is committed. Return now rather than go round again, where an abort, the deadline
383
- // or an expiry check could still report failure for a transaction that is entirely
384
- // saved. The refresh's consume and replay already gave each saved participant the
385
- // success path's local treatment, so only the stamp is left to release.
386
- // Tested on what is still STAGED, not on "every participant saved": a participant
387
- // can be saved and still hold actions staged after the attempt began, and those
388
- // the next attempt must commit.
389
- this.stampData.delete(transaction.stamp.id);
558
+ budget.recordLoss(err);
559
+ await this.refreshRounds(driver, budget);
560
+ if (cycle.saved.size > 0 && driver.nothingLeft()) {
390
561
  return transactionDurability(cycle.saved);
391
562
  }
392
563
  }
393
564
  }
394
565
  }
395
566
  /**
396
- * Refresh every registered collection between attempts, recording in `cycle.saved` each one
397
- * whose refresh finished this transaction's own log entry (see {@link Collection.refreshInFlight}),
398
- * with who holds it — `undefined` when the refresh could not say, which still records it as saved.
567
+ * Back off, refresh, and keep refreshing while a round reports that a participant's half-landed
568
+ * write could not be finished YET. Re-reading fresh state before re-attempting is what lets the
569
+ * next attempt pend against current revisions (mirrors how Collection.sync calls updateInternal()
570
+ * before retrying), and a participant whose log tail landed despite the reported loss finds its
571
+ * own entry here and FINISHES that action before consuming it (Collection.completeOwnEntry, from
572
+ * the attempt the previous one retained).
573
+ *
574
+ * When finishing is refused for a cause that can clear, the refresh — not the commit — is what
575
+ * gets retried: the participant's log entry is already durable, and once a refresh adopts a newer
576
+ * revision the next attempt appends a SECOND entry under the write's id. (At an unchanged
577
+ * revision the re-append is byte-identical — see Collection.logAppendBlockIds — so what is at
578
+ * stake is the duplicate entry, not two versions of one tail block.) Each such round counts
579
+ * against the same budget as a stale loss; a permanent refusal (a rival holds the revision)
580
+ * escapes as the named TornActionError at once. Re-refreshing a collection an earlier round
581
+ * already refreshed is a no-op. The round that would spend the last of the budget is told so,
582
+ * which makes each participant SETTLE a half-landed write rather than ask for another round: the
583
+ * error thrown then says whether the write can still land (`final`). A deadline cannot be
584
+ * foreseen the same way; a write given up on it stays unsettled.
585
+ */
586
+ async refreshRounds(driver, budget) {
587
+ for (;;) {
588
+ await budget.pause();
589
+ const refused = await driver.refresh(budget.lastChance());
590
+ if (refused === undefined) {
591
+ return;
592
+ }
593
+ budget.recordRefusedRound(refused);
594
+ }
595
+ }
596
+ /** Every registered collection as a refresh-round participant of a transaction's commit.
597
+ *
598
+ * NOTE: EVERY registered collection, not only the participants of the transaction. Not free: a
599
+ * non-participant's refresh throws CollectionHeaderVanishedError if its header momentarily reads
600
+ * absent while it holds a committed revision, aborting this retry. And because a throw does not
601
+ * stop the round, an unreachable cluster costs one failed read per registered collection rather
602
+ * than one. The registered set is small today; if that (or retry latency) ever bites, narrow this
603
+ * to the transaction's participants. (The per-entry commit already refreshes its participants
604
+ * only, through their handles — see `EntryParticipants.refreshers`.) */
605
+ registeredRefreshers() {
606
+ return [...this.collections].map(([collectionId, collection]) => ({
607
+ collectionId,
608
+ refresh: (report, lastChance) => collection.refreshInFlight(report, lastChance),
609
+ }));
610
+ }
611
+ /**
612
+ * One refresh round between attempts: refresh every participant, recording in `cycle.saved` each
613
+ * one whose refresh finished the write's own log entry (see {@link Collection.refreshInFlight}),
614
+ * with who holds it — `undefined` when the refresh could not say, which still records it as
615
+ * saved — and telling the participant so (`RefreshParticipant.saved`).
399
616
  *
400
- * Visits EVERY collection even after one throws. Stopping at the first throw would leave a
401
- * participant later in the map unfinished whenever an earlier one is torn — its log tail stored
617
+ * Visits EVERY participant even after one throws. Stopping at the first throw would leave a
618
+ * participant later in the round unfinished whenever an earlier one is torn — its log tail stored
402
619
  * and its other blocks never landed, the silent loss `Collection.completeOwnEntry` exists to
403
620
  * prevent — and unreported. Each refresh is independent (its own latch, its own instance state),
404
621
  * so one failing says nothing about the next.
405
622
  *
406
- * NOTE: refreshes EVERY registered collection, not only the participants of this transaction.
407
- * Not free: a non-participant's refresh throws CollectionHeaderVanishedError if its header
408
- * momentarily reads absent while it holds a committed revision, aborting this retry. And because
409
- * a throw no longer stops the round, an unreachable cluster costs one failed read per registered
410
- * collection rather than one. The registered set is small today; if that (or retry latency) ever
411
- * bites, narrow this to the transaction's participants.
623
+ * NOTE: no `tailFloor` is passed to any refresh — the coordinator's loop loses the confirmed
624
+ * revision before the round runs (backlog `debt-multi-collection-retry-cannot-see-the-taken-revision`);
625
+ * the per-entry commit has the same gap, through the same round.
412
626
  *
413
627
  * @param lastChance - this is the round that spends the last of the retry budget, so a
414
628
  * participant whose half-landed write is refused again settles it (`Collection.completeOwnEntry`)
415
629
  * rather than asking for a round it will not get; the error returned then carries `final`.
416
630
  * @returns the first `completion-refused` {@link TornActionError} when that is the only way any
417
631
  * refresh failed — the round is worth retrying; `undefined` when every refresh succeeded.
418
- * @throws the first other error, once every collection has been visited.
632
+ * @throws the first other error, once every participant has been visited.
419
633
  */
420
- async refreshBetweenAttempts(cycle, lastChance) {
634
+ async refreshBetweenAttempts(participants, cycle, lastChance) {
421
635
  let terminal;
422
636
  let refused;
423
- for (const [collectionId, collection] of this.collections) {
637
+ for (const participant of participants) {
424
638
  const report = {};
425
639
  try {
426
- await collection.refreshInFlight(report, lastChance);
640
+ await participant.refresh(report, lastChance);
427
641
  }
428
642
  catch (err) {
429
643
  if (err instanceof TornActionError && err.reason === 'completion-refused') {
@@ -436,7 +650,8 @@ export class TransactionCoordinator {
436
650
  // Read after the try, not only on success: a refresh can throw AFTER it finished the
437
651
  // entry, and that participant is saved either way.
438
652
  if (report.ownEntryFinished !== undefined) {
439
- recordCollectionDurability(cycle.saved, collectionId, report.ownEntryFinished.durability);
653
+ recordCollectionDurability(cycle.saved, participant.collectionId, report.ownEntryFinished.durability);
654
+ participant.saved?.();
440
655
  }
441
656
  }
442
657
  if (terminal !== undefined) {
@@ -479,10 +694,11 @@ export class TransactionCoordinator {
479
694
  *
480
695
  * Local state already matches that report: a saved participant was consumed by its refresh, and
481
696
  * an unsaved one kept its staged actions (a failed finish throws before touching anything, and
482
- * commitOnceLatched restores every participant it did not commit). The stamp is released, as on
483
- * the existing partial path, because the transaction can no longer be cleanly rolled back.
697
+ * commitOnceLatched restores every participant it did not commit; the per-entry commit leaves a
698
+ * refused participant's segment sealed and first). Releasing a transaction's stamp on the partial
699
+ * report is {@link commit}'s, which reads the class of what this returns.
484
700
  */
485
- reportSaved(transaction, cycle, err) {
701
+ reportSaved(actionId, cycle, err) {
486
702
  if (cycle.saved.size === 0) {
487
703
  return err;
488
704
  }
@@ -499,8 +715,7 @@ export class TransactionCoordinator {
499
715
  // committed. Unreachable while a session stages and commits on one call path; if staging ever
500
716
  // races a commit, report such a participant in both lists.
501
717
  const failed = [...cycle.participants].filter(id => !committed.has(id));
502
- log('commit:partial-after-refresh tx=%s committed=%o failed=%o reason=%s', transaction.id, [...committed.keys()], failed, reason instanceof Error ? reason.name : String(reason));
503
- this.stampData.delete(transaction.stamp.id);
718
+ log('commit:partial-after-refresh tx=%s committed=%o failed=%o reason=%s', actionId, [...committed.keys()], failed, reason instanceof Error ? reason.name : String(reason));
504
719
  return new CoordinatorPartialCommitError(committed, failed, reason);
505
720
  }
506
721
  /**
@@ -580,7 +795,7 @@ export class TransactionCoordinator {
580
795
  // (Collection.completeOwnEntry). `transaction.id` is stable across retries, so re-marking on a
581
796
  // later attempt re-states the same fact. Only participants are marked; a registered
582
797
  // non-participant is left unmarked and its refresh behaves exactly as a reader's.
583
- cycle.inFlightDisposers.push(collection.beginInFlightAction(transaction.id));
798
+ cycle.inFlightDisposers.push(collection.beginInFlightAction(transaction.id, cycle.inFlight));
584
799
  }
585
800
  return await this.commitOnceLatched(transaction, collectionData, cycle);
586
801
  }
@@ -643,10 +858,12 @@ export class TransactionCoordinator {
643
858
  for (const { collectionId, collection } of collectionData) {
644
859
  preCommitSnapshots.set(collectionId, collection.snapshotPending());
645
860
  }
861
+ // Read per attempt: commitAttempts ages the transaction's priority between attempts.
862
+ const context = writeContextOf(transaction, cycle.inFlight);
646
863
  let coordResult;
647
864
  try {
648
865
  for (const { collectionId, collection } of collectionData) {
649
- const applyResult = await this.applyActionsToCollection({ collectionId, actions: collection.getPendingActions() }, transaction, allCollectionIds);
866
+ const applyResult = await this.applyActionsToCollection({ collectionId, actions: collection.getPendingActions() }, context, allCollectionIds);
650
867
  if (!applyResult.success) {
651
868
  throw new Error(`Transaction commit failed: ${applyResult.error}`);
652
869
  }
@@ -657,7 +874,7 @@ export class TransactionCoordinator {
657
874
  // What each pend carries for members to re-check (post-log-append) — see pendValidationFor.
658
875
  const validation = await this.pendValidationFor(transaction, collectionTransforms);
659
876
  // Execute consensus phases (GATHER, PEND, COMMIT)
660
- coordResult = await this.coordinateTransaction(transaction, validation, collectionTransforms, criticalBlocks, pendedRevs);
877
+ coordResult = await this.coordinateTransaction(context, validation, collectionTransforms, criticalBlocks, pendedRevs);
661
878
  }
662
879
  catch (err) {
663
880
  // A throw here means the failure happened BEFORE any collection could
@@ -666,7 +883,7 @@ export class TransactionCoordinator {
666
883
  // to its pre-append snapshot — a genuinely clean rollback that leaves each
667
884
  // tracker pristine for retry (see txn-failed-commit-leaves-staged-log-entry).
668
885
  for (const { collectionId, collection } of collectionData) {
669
- collection.restorePending(preCommitSnapshots.get(collectionId));
886
+ await collection.restorePending(preCommitSnapshots.get(collectionId));
670
887
  }
671
888
  throw err;
672
889
  }
@@ -679,13 +896,14 @@ export class TransactionCoordinator {
679
896
  // the next refresh of that participant finds this transaction's own log entry, these are
680
897
  // the transforms that finish it (Collection.completeOwnEntry) — without them the refresh
681
898
  // can only refuse the write as torn, never save it. Copied, because until the restore
682
- // this is the participant's LIVE tracker state. No block digests are retained: they are
683
- // computed per commit from the live tracker (commitCollection), which is gone by the time
684
- // a refresh re-sends, and an undeclared block falls back to member-side corroboration.
899
+ // this is the participant's LIVE tracker state. No block digests are retained: the
900
+ // declaration taken before the pend (declareTouchedBlocks) stays inside coordinateTransaction,
901
+ // so a re-send declares none, and an undeclared block falls back to member-side corroboration.
685
902
  for (const { collectionId, collection } of collectionData) {
686
903
  if (committed.has(collectionId))
687
904
  continue;
688
- collection.retainInFlightAttempt(transaction.id, {
905
+ collection.retainInFlightAttempt({
906
+ actionId: transaction.id,
689
907
  rev: pendedRevs.get(collectionId),
690
908
  transforms: copyTransforms(collectionTransforms.get(collectionId)),
691
909
  tailId: criticalBlocks.get(collectionId),
@@ -696,27 +914,34 @@ export class TransactionCoordinator {
696
914
  // while another failed permanently. A uniform pre-append restore would
697
915
  // corrupt the committed half — re-staging its already-durable actions as
698
916
  // still-pending, so tracker memory would disagree with cluster storage.
699
- // Split the local handling instead:
917
+ // Split the local handling instead, in two passes: the committed half is folded
918
+ // first, in one await-free pass (so a committed read observes every committed
919
+ // participant pre-fold or post-fold, as the success fold below promises), and the
920
+ // failed half is restored after it — a restore can replay, so it is awaited, which
921
+ // admits no interleaved stage because every participant's latch is held across
922
+ // this span.
700
923
  for (const { collectionId, collection } of collectionData) {
701
- if (committed.has(collectionId)) {
702
- // Committed → the success-path local treatment (see below): fold the
703
- // committed transforms into the read cache BEFORE resetting the tracker,
704
- // then drop the now-durable pending actions so a retry cannot re-log them.
705
- // NOTE: no-double-apply on retry depends on clearPendingActions() running for
706
- // EVERY committed collection here before any re-drive of commit(). If a committed
707
- // collection kept its pending queue, a subsequent commit() would re-append and
708
- // re-log its already-durable actions — a duplicate log entry on the winner. The
709
- // no-double-apply-on-retry test in transaction.spec.ts locks this.
710
- const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId));
711
- collection.applyCommittedToCache(collectionTransforms.get(collectionId), rev);
712
- collection.tracker.reset();
713
- collection.clearPendingActions();
714
- }
715
- else {
716
- // Failed / never-committed → restore the pre-append snapshot so a retry
717
- // re-appends cleanly (no duplicate log entry).
718
- collection.restorePending(preCommitSnapshots.get(collectionId));
719
- }
924
+ if (!committed.has(collectionId))
925
+ continue;
926
+ // Committed → the success-path local treatment (see below): fold the
927
+ // committed transforms into the read cache BEFORE resetting the tracker,
928
+ // then drop the now-durable pending actions so a retry cannot re-log them.
929
+ // NOTE: no-double-apply on retry depends on clearPendingActions() running for
930
+ // EVERY committed collection here before any re-drive of commit(). If a committed
931
+ // collection kept its pending queue, a subsequent commit() would re-append and
932
+ // re-log its already-durable actions — a duplicate log entry on the winner. The
933
+ // no-double-apply-on-retry test in transaction.spec.ts locks this.
934
+ const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId));
935
+ collection.applyCommittedToCache(collectionTransforms.get(collectionId), rev);
936
+ collection.tracker.reset();
937
+ collection.clearPendingActions();
938
+ }
939
+ for (const { collectionId, collection } of collectionData) {
940
+ if (committed.has(collectionId))
941
+ continue;
942
+ // Failed / never-committed → restore the pre-append snapshot so a retry
943
+ // re-appends cleanly (no duplicate log entry).
944
+ await collection.restorePending(preCommitSnapshots.get(collectionId));
720
945
  }
721
946
  const failed = [...(coordResult.failedCollections ?? new Set())];
722
947
  if (coordResult.staleLoss) {
@@ -756,22 +981,14 @@ export class TransactionCoordinator {
756
981
  // EMPTY committed set: PEND failed, or the whole commit failed cleanly with
757
982
  // nothing durable. Restore every tracker so each is pristine for retry.
758
983
  for (const { collectionId, collection } of collectionData) {
759
- collection.restorePending(preCommitSnapshots.get(collectionId));
984
+ await collection.restorePending(preCommitSnapshots.get(collectionId));
760
985
  }
761
986
  // Distinguish a genuine optimistic-concurrency conflict (a stale loss / pending
762
987
  // contention — retryable after a re-read) from a hard failure (unavailable transactor,
763
988
  // storage rejection, expired). Only the former is worth re-driving; the retry wrapper in
764
989
  // commit() catches CoordinatorStaleLossError and re-attempts, while a plain Error escapes
765
990
  // immediately (preserving the historical fail-fast behaviour for hard failures).
766
- if (coordResult.staleLoss) {
767
- throw new CoordinatorStaleLossError([...(coordResult.failedCollections ?? new Set(allCollectionIds))], coordResult.error);
768
- }
769
- // An expiry is surfaced by name and never re-driven: the retry's pend would carry an
770
- // expiration from the same clock.
771
- if (coordResult.expired !== undefined) {
772
- throw coordResult.expired;
773
- }
774
- throw new Error(`Transaction commit failed: ${coordResult.error}`);
991
+ throw cleanFailureError(coordResult, [...(coordResult.failedCollections ?? new Set(allCollectionIds))]);
775
992
  }
776
993
  // Advance actionContext, fold the committed transforms into each
777
994
  // collection's read cache, reset the tracker, and drop the now-committed
@@ -794,6 +1011,150 @@ export class TransactionCoordinator {
794
1011
  this.stampData.delete(transaction.stamp.id);
795
1012
  return coordResult.committedCollections;
796
1013
  }
1014
+ /**
1015
+ * Commit one queued entry's slice of every collection it wrote, as ONE all-or-nothing round
1016
+ * (docs/offline-sync.md §One entry, one network transaction): for each collection in
1017
+ * `entry.collectionIds`, exactly its HEAD sealed segment, which must be `entry.entryId`, as one
1018
+ * log entry under `entry.actionId` and `entry.timestamp`. The offline-sync queue is the caller,
1019
+ * for an entry that wrote more than one collection; an entry that wrote one commits through
1020
+ * `Collection.commitHead`, whose steps this drives in lock-step across the participants
1021
+ * (`HeadCommitHandle` in collection/head-commit.ts): open a handle per participant, in sorted
1022
+ * collection-id order; the opening refresh, which finishes and consumes an entry an earlier
1023
+ * `commitEntry` under this action id left in a participant's log; then per attempt, build every
1024
+ * participant's attempt on its head tracker, record them through `entry.recordAttempt`, release
1025
+ * every latch, run the phases ({@link coordinateAttempts}: pend every participant, then commit),
1026
+ * retake every latch, and apply the outcome — fold then replay on a commit, the recorded refusal
1027
+ * re-checked and the attempt retained on a refusal — with the retry loop of {@link commit}
1028
+ * ({@link commitAttempts}) between attempts.
1029
+ *
1030
+ * What the slice deliberately does NOT do, where {@link commit} does: no pre-commit snapshots or
1031
+ * `restorePending` (an attempt never touches the live tracker; a failed one leaves it as it was
1032
+ * by construction); no `getPendingActions`, `clearPendingActions` or `tracker.reset` (the head
1033
+ * segment is dropped and folded through the handle); no stamp (the one-open-stamp rule is about
1034
+ * staged state, which a slice does not stage — a slice may run while a stamp is open on another
1035
+ * coordinator over the same collections, which is the plugin's open SQL transaction; the
1036
+ * collection latch is what serialises them); no expiry check (an entry has no stamp to expire).
1037
+ * Its refresh rounds refresh the entry's participants only, through their handles, never the
1038
+ * coordinator's whole map.
1039
+ *
1040
+ * Requires a coordinator built with `pendValidation: 'none'`, and throws before touching
1041
+ * anything otherwise: a queued entry has no statements for a member to re-execute, and the pend
1042
+ * carries bare transforms exactly as the plugin's `commitBatchLegacy` sends them. The queue builds
1043
+ * one coordinator per submission over exactly the entry's collections; running `commitEntry`
1044
+ * while a {@link commit} of the same coordinator is open is not a supported combination, and
1045
+ * nothing but the collection latches guards it.
1046
+ *
1047
+ * @returns who holds each collection the entry wrote, across every attempt, as {@link commit}
1048
+ * answers it — a participant the refresh saved included, listed with an `undefined` class (and
1049
+ * `overall` then absent) when the refresh established it was saved under `entry.actionId` without
1050
+ * re-sending (the status-read fallback of `Collection.completeOwnEntry`, where
1051
+ * `Collection.commitHead` answers `undefined`). Never `undefined`: a slice always writes at least
1052
+ * one collection, so the "nothing was written" answer `commit` has is unrepresentable here.
1053
+ * @throws what {@link commit} throws — a {@link CoordinatorStaleLossError} once the retry budget
1054
+ * is spent, a {@link CoordinatorPartialCommitError} for a partial landing (every participant it
1055
+ * names as committed has had its head consumed; every failed one's head is still sealed and
1056
+ * first, its attempt retained), the named refusals, `TornActionError` out of a refresh — plus the
1057
+ * recorded refusal of any participant's head (an `ActionRefusedError`), thrown with every other
1058
+ * participant's segment intact since nothing was sent or the send was refused, and
1059
+ * `SealedSegmentsError` from `Collection.openHeadCommit`'s preconditions, before anything is done.
1060
+ */
1061
+ async commitEntry(entry, options) {
1062
+ if (this.pendValidation !== 'none') {
1063
+ throw new Error(`commitEntry ${entry.entryId}: a queued entry commits through a coordinator built with `
1064
+ + `pendValidation: 'none' — it has no statements for a member to re-execute`);
1065
+ }
1066
+ const inFlight = inFlightCycleOf(options);
1067
+ const participants = await EntryParticipants.open(this.collections, entry, inFlight);
1068
+ const cycle = {
1069
+ // The handles own the in-flight marks (closed with them), so none to dispose here.
1070
+ inFlightDisposers: [],
1071
+ participants: new Set(participants.ids()),
1072
+ saved: new Map(),
1073
+ inFlight,
1074
+ };
1075
+ const driver = {
1076
+ opensWithRefresh: true,
1077
+ attempt: priority => this.commitEntryOnce(entry, participants, cycle, priority),
1078
+ refresh: lastChance => this.refreshBetweenAttempts(participants.refreshers(), cycle, lastChance),
1079
+ nothingLeft: () => participants.size === 0,
1080
+ };
1081
+ try {
1082
+ const written = await this.commitAttempts(driver, cycle, options);
1083
+ if (written === undefined) {
1084
+ throw new Error(`commitEntry ${entry.entryId}: the cycle ended with nothing committed and nothing saved`);
1085
+ }
1086
+ return written;
1087
+ }
1088
+ catch (err) {
1089
+ throw this.reportSaved(entry.actionId, cycle, err);
1090
+ }
1091
+ finally {
1092
+ participants.close();
1093
+ }
1094
+ }
1095
+ /**
1096
+ * One attempt of {@link commitEntry}, under the latches `participants` hold: every remaining
1097
+ * participant's attempt is built (`HeadCommitHandle.stage`, which re-checks the head's recorded
1098
+ * refusal and throws it), recorded through the write-ahead hook — a throw there aborts with
1099
+ * nothing sent and nothing changed — then sent as one round with every latch released, and the
1100
+ * outcome applied under the retaken latches:
1101
+ *
1102
+ * - a commit: fold every participant in one await-free pass, then replay each
1103
+ * (`EntryParticipants.landed`); the attempt's durability per collection is the answer;
1104
+ * - a partial landing: the committed participants folded, replayed and recorded in `cycle.saved`
1105
+ * — before their local treatment, so a throw in it is still reported over the right committed
1106
+ * set — and the rest refused (their recorded refusal re-checked, their attempt retained); then
1107
+ * {@link CoordinatorStaleLossError} when every refusal was a returned one, so the retry loop
1108
+ * finishes the refused participants forward over what is left (as `commitOnceLatched`'s
1109
+ * partial-retry branch does), or {@link CoordinatorPartialCommitError} on a hard failure;
1110
+ * - nothing committed: every participant refused, then the failure thrown by its class
1111
+ * ({@link cleanFailureError}).
1112
+ *
1113
+ * The refusal re-check runs after the committed participants are folded, never before: a
1114
+ * sibling's recorded refusal must not keep a durable commit from being applied locally.
1115
+ */
1116
+ async commitEntryOnce(entry, participants, cycle, priority) {
1117
+ const staged = await participants.stage();
1118
+ if (entry.recordAttempt !== undefined) {
1119
+ await entry.recordAttempt(participants.retainedAttempts(staged));
1120
+ }
1121
+ const context = {
1122
+ actionId: entry.actionId,
1123
+ timestamp: entry.timestamp,
1124
+ reads: [],
1125
+ priority,
1126
+ ...refuseSoloField(cycle.inFlight.refuseSolo),
1127
+ };
1128
+ const attempts = new Map(Array.from(staged, ([collectionId, attempt]) => [collectionId, collectionAttemptOf(attempt)]));
1129
+ participants.release();
1130
+ let coordResult;
1131
+ try {
1132
+ coordResult = await this.coordinateAttempts(context, undefined, attempts);
1133
+ }
1134
+ finally {
1135
+ await participants.retake();
1136
+ }
1137
+ if (coordResult.success) {
1138
+ await participants.landed(staged, participants.ids());
1139
+ return coordResult.committedCollections;
1140
+ }
1141
+ const committed = coordResult.committedCollections ?? new Map();
1142
+ const failed = participants.ids().filter(collectionId => !committed.has(collectionId));
1143
+ if (committed.size === 0) {
1144
+ participants.refused(staged, failed);
1145
+ throw cleanFailureError(coordResult, failed);
1146
+ }
1147
+ for (const [collectionId, durability] of committed) {
1148
+ recordCollectionDurability(cycle.saved, collectionId, durability);
1149
+ }
1150
+ await participants.landed(staged, committed.keys());
1151
+ participants.refused(staged, failed);
1152
+ if (coordResult.staleLoss) {
1153
+ log('commitEntry:partial-retry entry=%s action=%s committed=%o failed=%o reason=%s', entry.entryId, entry.actionId, [...committed.keys()], failed, coordResult.error);
1154
+ throw new CoordinatorStaleLossError(failed, coordResult.error);
1155
+ }
1156
+ throw new CoordinatorPartialCommitError(committed, failed, coordResult.expired ?? coordResult.error);
1157
+ }
797
1158
  /**
798
1159
  * Rollback a transaction (undo only the given stampId's applied actions).
799
1160
  *
@@ -840,9 +1201,14 @@ export class TransactionCoordinator {
840
1201
  // Accepted: the tracker half already discards their transforms, and symmetric is the safer
841
1202
  // state — leaving such an action queued while its transforms are gone is exactly the
842
1203
  // phantom that a conflicting sync's replayActions would resurrect as live data.
843
- for (const [collection, snapshot] of data.preSnapshot) {
844
- collection.restorePending(snapshot);
845
- }
1204
+ // Awaited: a restore across a change to the collection's sealed segments replays them
1205
+ // (Collection.restorePending), and the single-call-path assumption above is what keeps a
1206
+ // stage from landing on the collection while that replay runs. Every participant is
1207
+ // restored even after one throws (a refusal of the restored open segment, or a failed
1208
+ // re-read inside the replay): each restore is independent, and stopping at the first throw
1209
+ // would leave the later participants holding the rolled-back stamp's actions, which the
1210
+ // next transaction would then log as its own.
1211
+ await visitEveryThenThrow(data.preSnapshot, ([collection, snapshot]) => collection.restorePending(snapshot));
846
1212
  }
847
1213
  /**
848
1214
  * Get current transforms from all collections.
@@ -1050,10 +1416,11 @@ export class TransactionCoordinator {
1050
1416
  // Released in the finally: execute has early failure returns.
1051
1417
  const latchReleases = [];
1052
1418
  try {
1053
- // NOTE: deadlock-freedom against a concurrent commitOnce needs BOTH paths to acquire in
1054
- // the SAME order, not merely each in a sorted one. `CollectionId` is a string, so this
1055
- // default `.sort()` and commitOnce's explicit `<`/`>` comparator agree today. If either
1056
- // spelling changes — a custom comparator, a non-string id — change both together.
1419
+ // NOTE: deadlock-freedom against a concurrent commitOnce or commitEntry needs ALL three
1420
+ // paths to acquire in the SAME order, not merely each in a sorted one. `CollectionId` is a
1421
+ // string, so this default `.sort()`, commitOnce's explicit `<`/`>` comparator and
1422
+ // `compareCollectionIds` in entry-commit.ts agree today. If any spelling changes — a
1423
+ // custom comparator, a non-string id — change all three together.
1057
1424
  for (const collectionId of [...allCollectionIds].sort()) {
1058
1425
  const collection = this.collections.get(collectionId);
1059
1426
  if (collection) {
@@ -1065,8 +1432,9 @@ export class TransactionCoordinator {
1065
1432
  for (const collectionId of allCollectionIds) {
1066
1433
  await this.collections.get(collectionId)?.restageIfBasesMoved();
1067
1434
  }
1435
+ const context = writeContextOf(transaction);
1068
1436
  for (const [collectionId, actions] of batches) {
1069
- const applyResult = await this.applyActionsToCollection({ collectionId, actions }, transaction, allCollectionIds);
1437
+ const applyResult = await this.applyActionsToCollection({ collectionId, actions }, context, allCollectionIds);
1070
1438
  if (!applyResult.success) {
1071
1439
  return { success: false, error: applyResult.error };
1072
1440
  }
@@ -1080,7 +1448,7 @@ export class TransactionCoordinator {
1080
1448
  const applyMs = Date.now() - tApply;
1081
1449
  // 4. Coordinate (GATHER if multi-collection)
1082
1450
  const tCoord = Date.now();
1083
- const coordResult = await this.coordinateTransaction(transaction, validation, collectionTransforms, criticalBlocks, pendedRevs);
1451
+ const coordResult = await this.coordinateTransaction(context, validation, collectionTransforms, criticalBlocks, pendedRevs);
1084
1452
  const coordMs = Date.now() - tCoord;
1085
1453
  if (!coordResult.success) {
1086
1454
  log('execute:done trxId=%s engine=%dms apply=%dms coordinate=%dms success=false total=%dms', trxId, engineMs, applyMs, coordMs, Date.now() - t0);
@@ -1091,8 +1459,12 @@ export class TransactionCoordinator {
1091
1459
  // pending queues aren't left mis-tracking already-durable state; the failed subset
1092
1460
  // is unwound to its pre-staging snapshot, and the stamp tracking is dropped so no
1093
1461
  // unsafe all-or-nothing undo handle survives (rollback() would rewind the winner).
1094
- // Kept await-free for the same reason the success fold is — restorePending is
1095
- // synchronous and latch-free by contract, so it is safe inside this latched span.
1462
+ // Two passes, as in commitOnceLatched: the committed subset's fold is kept
1463
+ // await-free for the same reason the success fold is, and the failed subset's
1464
+ // restore comes after it. That restore is awaited — it can replay the collection's
1465
+ // sealed segments — and the await admits no interleaved stage, because every
1466
+ // participant's latch is held across this span (restorePending stays latch-free by
1467
+ // contract and relies on exactly that).
1096
1468
  // NOTE: execute() has no retry loop at all, so a returned refusal after a sibling
1097
1469
  // committed is reported here at once, where commit() would re-drive the refused
1098
1470
  // collection forward (the partial-retry branch of commitOnceLatched). No production
@@ -1105,26 +1477,27 @@ export class TransactionCoordinator {
1105
1477
  if (committed.size > 0) {
1106
1478
  for (const collectionId of batches.keys()) {
1107
1479
  const collection = this.collections.get(collectionId);
1108
- if (!collection)
1480
+ if (!collection || !committed.has(collectionId))
1481
+ continue;
1482
+ const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId));
1483
+ collection.applyCommittedToCache(collectionTransforms.get(collectionId), rev);
1484
+ collection.tracker.reset();
1485
+ collection.clearPendingActions();
1486
+ }
1487
+ for (const collectionId of batches.keys()) {
1488
+ const collection = this.collections.get(collectionId);
1489
+ if (!collection || committed.has(collectionId))
1109
1490
  continue;
1110
- if (committed.has(collectionId)) {
1111
- const rev = collection.recordCommitted(transaction.id, pendedRevs.get(collectionId));
1112
- collection.applyCommittedToCache(collectionTransforms.get(collectionId), rev);
1113
- collection.tracker.reset();
1114
- collection.clearPendingActions();
1115
- }
1116
- else {
1117
- // NOTE: blind overwrite of this collection's staged state — anything
1118
- // staged on it between the pre-stage snapshot above and here is discarded.
1119
- // No sibling stamp can be that writer (at most one stamp is open), so the
1120
- // only source is the untracked Tree.stage / Collection.act path, and this
1121
- // is the same single-call-path assumption rollback() documents. It cannot
1122
- // be softened by re-applying those actions here: collection.act takes the
1123
- // same non-reentrant instance latch this span already holds.
1124
- const snapshot = preStageSnapshots.get(collectionId);
1125
- if (snapshot)
1126
- collection.restorePending(snapshot);
1127
- }
1491
+ // NOTE: blind overwrite of this collection's staged state — anything
1492
+ // staged on it between the pre-stage snapshot above and here is discarded.
1493
+ // No sibling stamp can be that writer (at most one stamp is open), so the
1494
+ // only source is the untracked Tree.stage / Collection.act path, and this
1495
+ // is the same single-call-path assumption rollback() documents. It cannot
1496
+ // be softened by re-applying those actions here: collection.act takes the
1497
+ // same non-reentrant instance latch this span already holds.
1498
+ const snapshot = preStageSnapshots.get(collectionId);
1499
+ if (snapshot)
1500
+ await collection.restorePending(snapshot);
1128
1501
  }
1129
1502
  // The undo handle is now unsafe: rollback() is all-or-nothing and would rewind
1130
1503
  // the collections that DID durably commit. Drop it, matching commitOnceLatched.
@@ -1186,9 +1559,10 @@ export class TransactionCoordinator {
1186
1559
  /**
1187
1560
  * Apply actions to a collection.
1188
1561
  *
1189
- * This runs the action handlers, writes to the log, and collects transforms.
1562
+ * This runs the action handlers, writes to the log, and collects transforms. The log entry is
1563
+ * written under `context`: its action id, its timestamp and its reads.
1190
1564
  */
1191
- async applyActionsToCollection(collectionActions, transaction, allCollectionIds) {
1565
+ async applyActionsToCollection(collectionActions, context, allCollectionIds) {
1192
1566
  const collection = this.collections.get(collectionActions.collectionId);
1193
1567
  if (!collection) {
1194
1568
  return {
@@ -1201,8 +1575,7 @@ export class TransactionCoordinator {
1201
1575
  // already has the transforms, and the actions are in the pending buffer.
1202
1576
  // Get transforms from the collection's tracker
1203
1577
  const transforms = collection.tracker.transforms;
1204
- // Generate action ID from transaction ID
1205
- const actionId = transaction.id;
1578
+ const actionId = context.actionId;
1206
1579
  const newRev = collection.getNextRev();
1207
1580
  // Write actions to the collection's log to get the log tail block ID. The append must be a
1208
1581
  // fixed function of this write and the revision it requests, because a refused commit is
@@ -1244,7 +1617,7 @@ export class TransactionCoordinator {
1244
1617
  // correctness; a cross-collection invalidation cascade that treats it as "the definitive
1245
1618
  // participant set of this transaction" must union it across the transaction's entries
1246
1619
  // rather than trusting any single one.
1247
- const addResult = await log.addActions(collectionActions.actions, actionId, newRev, () => blockIdsForTransforms(transforms), { collectionIds: allCollectionIds, reads: transaction.reads, timestamp: transaction.stamp.timestamp });
1620
+ const addResult = await log.addActions(collectionActions.actions, actionId, newRev, () => blockIdsForTransforms(transforms), { collectionIds: allCollectionIds, reads: [...context.reads], timestamp: context.timestamp });
1248
1621
  // Return the transforms and log tail block ID
1249
1622
  return {
1250
1623
  success: true,
@@ -1255,9 +1628,11 @@ export class TransactionCoordinator {
1255
1628
  };
1256
1629
  }
1257
1630
  /**
1258
- * Coordinate a transaction across multiple collections.
1631
+ * Coordinate a transaction's attempt across multiple collections: describe what each collection's
1632
+ * staged transforms send ({@link declareTouchedBlocks}), then run the phases
1633
+ * ({@link coordinateAttempts}).
1259
1634
  *
1260
- * @param transaction - The transaction to coordinate
1635
+ * @param context - The write being coordinated (its action id and aged priority)
1261
1636
  * @param validation - What every pend carries for members to re-check, or undefined for an
1262
1637
  * unvalidated pend (see {@link pendValidationFor})
1263
1638
  * @param collectionTransforms - Map of collectionId to its transforms
@@ -1266,17 +1641,33 @@ export class TransactionCoordinator {
1266
1641
  * applyActionsToCollection) — repeated verbatim on the pend and commit requests so storage
1267
1642
  * and the local record name the same number.
1268
1643
  */
1269
- async coordinateTransaction(transaction, validation, collectionTransforms, criticalBlocks, pendedRevs) {
1270
- const trxId = transaction.id;
1644
+ async coordinateTransaction(context, validation, collectionTransforms, criticalBlocks, pendedRevs) {
1645
+ // Before anything is sent: one materialization of every block the transaction touches, measured
1646
+ // against MAX_BLOCK_BYTES here and declared on the commit below.
1647
+ const described = await this.declareTouchedBlocks(collectionTransforms, criticalBlocks, pendedRevs);
1648
+ if (!described.success) {
1649
+ log('trx:phases trxId=%s refused before sending: %s', context.actionId, described.error);
1650
+ return described;
1651
+ }
1652
+ return this.coordinateAttempts(context, validation, described.attempts);
1653
+ }
1654
+ /**
1655
+ * The distributed phases of one attempt — GATHER, PEND, COMMIT, and the CANCEL of what a failed
1656
+ * commit left pending — over every collection's share of it, already described
1657
+ * (`CollectionAttempt`). Run by {@link coordinateTransaction} for a transaction's attempt and by
1658
+ * {@link commitEntryOnce} for a queued entry's, whose attempts the head commit described.
1659
+ */
1660
+ async coordinateAttempts(context, validation, attempts) {
1661
+ const trxId = context.actionId;
1271
1662
  const t0 = Date.now();
1272
1663
  // 1. GATHER phase: collect critical cluster nominees (skip if single collection)
1273
- const criticalBlockIds = Array.from(criticalBlocks.values());
1664
+ const criticalBlockIds = Array.from(attempts.values(), attempt => attempt.tailId);
1274
1665
  const tGather = Date.now();
1275
1666
  const superclusterNominees = await this.gatherPhase(criticalBlockIds);
1276
1667
  const gatherMs = Date.now() - tGather;
1277
1668
  // 2. PEND phase: distribute to all block clusters
1278
1669
  const tPend = Date.now();
1279
- const pendResult = await this.pendPhase(transaction, validation, collectionTransforms, pendedRevs, superclusterNominees);
1670
+ const pendResult = await this.pendPhase(context, validation, attempts, superclusterNominees);
1280
1671
  const pendMs = Date.now() - tPend;
1281
1672
  if (!pendResult.success) {
1282
1673
  log('trx:phases trxId=%s gather=%dms pend=%dms (failed) total=%dms', trxId, gatherMs, pendMs, Date.now() - t0);
@@ -1284,11 +1675,11 @@ export class TransactionCoordinator {
1284
1675
  }
1285
1676
  // 3. COMMIT phase: commit to all critical blocks (with retry for forward recovery)
1286
1677
  const tCommit = Date.now();
1287
- const commitResult = await this.commitPhase(transaction.id, criticalBlockIds, pendResult.pendedBlockIds, pendedRevs);
1678
+ const commitResult = await this.commitPhase(context, attempts, pendResult.pendedBlockIds);
1288
1679
  const commitMs = Date.now() - tCommit;
1289
1680
  if (!commitResult.success) {
1290
1681
  // Targeted cancel: only cancel collections that are still pending (not already committed)
1291
- await this.cancelPhase(transaction.id, pendResult.pendedBlockIds, commitResult.committedCollections);
1682
+ await this.cancelPhase(context.actionId, pendResult.pendedBlockIds, commitResult.committedCollections);
1292
1683
  log('trx:phases trxId=%s gather=%dms pend=%dms commit=%dms (failed) total=%dms', trxId, gatherMs, pendMs, commitMs, Date.now() - t0);
1293
1684
  // Surface the committed/failed partition so commit()/execute() can report which
1294
1685
  // collections durably landed. A non-empty committedCollections is a PARTIAL commit:
@@ -1338,144 +1729,219 @@ export class TransactionCoordinator {
1338
1729
  }, new Map());
1339
1730
  return new Set(byId.values());
1340
1731
  }
1732
+ /**
1733
+ * What each collection's staged transforms send, described from its live tracker after the log
1734
+ * append: one local materialization of every block the transforms touch
1735
+ * ({@link describeTouchedBlocks}), taken before anything is sent. A block the write would leave
1736
+ * over `MAX_BLOCK_BYTES` refuses the transaction here, as a pend-phase failure carrying the
1737
+ * {@link BlockTooLargeError} — the same shape as a pend too large to send, so `commit` throws it by
1738
+ * name and `execute` reports it as a failure. Otherwise each collection's digests are kept as its
1739
+ * commit's declaration ({@link commitRequestFor}), so the commit does not materialize again, and
1740
+ * the base each update-only block's operations were computed against is read from the same
1741
+ * tracker's pins for its pend (`PendRequest.baseRevs`; storage keeps it with the pending record so
1742
+ * the record is never applied to a different version of the block).
1743
+ *
1744
+ * Purely local: each collection's tracker holds this transaction's staged transforms until the commit
1745
+ * succeeds, under the instance latch the commit span holds. A collection missing from the registry
1746
+ * is a defect here: {@link applyActionsToCollection} has already refused it.
1747
+ */
1748
+ async declareTouchedBlocks(collectionTransforms, criticalBlocks, pendedRevs) {
1749
+ const attempts = new Map();
1750
+ for (const [collectionId, transforms] of collectionTransforms) {
1751
+ const collection = this.collections.get(collectionId);
1752
+ if (!collection) {
1753
+ throw new Error(`Collection not found: ${collectionId}`);
1754
+ }
1755
+ const blockIds = blockIdsForTransforms(transforms);
1756
+ const touched = await describeTouchedBlocks(collection.tracker, blockIds);
1757
+ const tooLarge = oversizedBlock(touched.bytes);
1758
+ if (tooLarge)
1759
+ return pendFailure([tooLarge]);
1760
+ attempts.set(collectionId, {
1761
+ transforms,
1762
+ tailId: criticalBlocks.get(collectionId),
1763
+ rev: pendedRevs.get(collectionId),
1764
+ baseRevs: collection.tracker.stagedBaseRevs(blockIds),
1765
+ blockDigests: touched.digests,
1766
+ });
1767
+ }
1768
+ return { success: true, attempts };
1769
+ }
1341
1770
  /**
1342
1771
  * PEND phase: Distribute transaction to all affected block clusters.
1343
1772
  *
1344
- * @param transaction - The transaction being pended (its id names the action; its aged
1345
- * priority rides on an unvalidated pend)
1773
+ * Two or more collections go as ONE request when the transactor can send them so
1774
+ * ({@link pendTogether}); otherwise, and for one collection, each collection is pended on its own.
1775
+ *
1776
+ * @param context - The write being pended (its action id names the action; its aged priority
1777
+ * rides on an unvalidated pend)
1346
1778
  * @param validation - What every pend carries for members to re-check, or undefined for an
1347
1779
  * unvalidated pend (see {@link pendValidationFor})
1348
- * @param collectionTransforms - Map of collectionId to its transforms
1349
- * @param pendedRevs - Per collection, the revision its log entry was stamped with — the pend
1350
- * request repeats it verbatim rather than recomputing from the collection (a recompute after
1351
- * the append could name a different number if the collection refreshed in between).
1780
+ * @param attempts - Per collection, its share of the attempt: its transforms, and the revision
1781
+ * its log entry was stamped with — the pend request repeats it verbatim rather than recomputing
1782
+ * from the collection (a recompute after the append could name a different number if the
1783
+ * collection refreshed in between).
1352
1784
  * @param superclusterNominees - Nominees for multi-collection consensus (null for single-collection)
1353
1785
  */
1354
- async pendPhase(transaction, validation, collectionTransforms, pendedRevs, superclusterNominees) {
1355
- if (collectionTransforms.size === 0) {
1786
+ async pendPhase(context, validation, attempts, superclusterNominees) {
1787
+ if (attempts.size === 0) {
1356
1788
  return { success: false, error: 'No transforms to pend' };
1357
1789
  }
1358
- const actionId = transaction.id;
1359
1790
  const nominees = superclusterNominees ? Array.from(superclusterNominees) : undefined;
1791
+ // Both methods, never the pend alone: the batched pend's mark promises that the commit goes as one
1792
+ // request too (`PendRequest.soleReservation`), which only `commitMany` can keep.
1793
+ if (attempts.size > 1 && this.transactor.pendMany && this.transactor.commitMany) {
1794
+ const together = await this.pendTogether(context, validation, attempts, nominees);
1795
+ if (together !== undefined)
1796
+ return together;
1797
+ }
1360
1798
  // A one-collection transaction pends once and commits that one collection (commitPhase), as a
1361
1799
  // `Collection.sync` write does, so its pend may say so (`PendRequest.soleReservation`). Two or
1362
- // more never may: each collection's commit lands on its own, and a late refusal of another
1363
- // collection's pend would surface after it.
1364
- const sole = collectionTransforms.size === 1;
1800
+ // more pended one by one never may: each collection's commit can land on its own, and a late
1801
+ // refusal of another collection's pend would surface after it.
1802
+ const sole = attempts.size === 1;
1365
1803
  // Fan out the independent per-collection pends concurrently. Each settles to a
1366
1804
  // { collectionId, blockIds } on success, or rejects with the per-collection reason.
1367
1805
  // NOTE: unbounded fan-out — one concurrent coordinator round-trip per collection.
1368
1806
  // Transactions touch few collections today; if one ever spans very many, bound this
1369
1807
  // with a concurrency limiter so peak in-flight round-trips stays sane. Same for commitPhase.
1370
- const outcomes = await Promise.allSettled(Array.from(collectionTransforms.entries()).map(([collectionId, transforms]) => this.pendCollection(transaction, validation, collectionId, transforms, pendedRevs.get(collectionId), actionId, nominees, sole)));
1371
- // Partition settled results: every collection that DID pend (keyed with its block
1372
- // ids), plus the first failure reason if any collection failed.
1808
+ const outcomes = await Promise.allSettled(Array.from(attempts.entries()).map(([collectionId, attempt]) => this.pendCollection(context, validation, collectionId, attempt, nominees, sole)));
1809
+ // Partition settled results: every collection that DID pend (keyed with its block ids), and
1810
+ // every reason one did not, classified together (pendFailure) independent of iteration order.
1373
1811
  const pendedBlockIds = new Map();
1374
- let failure;
1375
- // Classify across ALL failures (mirroring commitPhase, and independent of iteration order):
1376
- // the pend is a retryable clean stale loss only if at least one failure was a conflicting pend
1377
- // (PendRejectedError.conflict) AND none was a hard failure. A single hard failure (storage/
1378
- // policy rejection, or a thrown/unavailable transactor) will not clear on a re-read, so
1379
- // re-driving it would just burn the retry budget — fail fast instead.
1380
- let anyConflict = false;
1381
- let anyHard = false;
1382
- // An expiry is a hard failure too, and is carried whole: it is the error the commit surfaces.
1383
- let expired;
1812
+ const reasons = [];
1384
1813
  for (const outcome of outcomes) {
1385
1814
  if (outcome.status === 'fulfilled') {
1386
1815
  pendedBlockIds.set(outcome.value.collectionId, outcome.value.blockIds);
1387
1816
  }
1388
1817
  else {
1389
- if (failure === undefined) {
1390
- failure = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
1391
- }
1392
- if (outcome.reason instanceof PendRejectedError && outcome.reason.conflict)
1393
- anyConflict = true;
1394
- else
1395
- anyHard = true;
1396
- if (outcome.reason instanceof TransactionExpiredError)
1397
- expired ??= outcome.reason;
1818
+ reasons.push(outcome.reason);
1398
1819
  }
1399
1820
  }
1400
- if (failure !== undefined) {
1821
+ if (reasons.length > 0) {
1401
1822
  // Any failure aborts the whole pend. With concurrency several collections may
1402
1823
  // have pended in parallel, so cancel EVERY successfully-pended collection — not
1403
1824
  // only those started before the failure. Cancels are best-effort (cancelPhase
1404
1825
  // swallows their errors) so they cannot mask the original pend failure.
1405
- await this.cancelPhase(actionId, pendedBlockIds);
1406
- return { success: false, error: failure, staleLoss: anyConflict && !anyHard, ...(expired === undefined ? {} : { expired }) };
1826
+ await this.cancelPhase(context.actionId, pendedBlockIds);
1827
+ return pendFailure(reasons);
1407
1828
  }
1408
1829
  return { success: true, pendedBlockIds };
1409
1830
  }
1831
+ /**
1832
+ * Pends every collection as ONE request ({@link ITransactor.pendMany}): one consensus record,
1833
+ * answered together. Every request is marked the action's only reservation
1834
+ * (`PendRequest.soleReservation`) — together they are, and their commit goes as one request to the
1835
+ * same coordinator ({@link commitTogether}) — so a coordinator may hold the pend's decision back for
1836
+ * the commit to carry, and a member that refuses any collection's pend late refuses the action's one
1837
+ * commit record before anything of it is durable.
1838
+ *
1839
+ * - **Success**: every collection is pended, with its own blocks.
1840
+ * - **Refusal**: classified as one collection's refusal is ({@link pendRefusalError}), once for the
1841
+ * batch. `pendMany` cancelled every block, so nothing is left pended.
1842
+ * - **Throw** (a transactor other than `NetworkTransactor`, which answers a throw with `undefined`):
1843
+ * a hard failure, as a thrown pend is. What was pended is unknown, so every collection's blocks are
1844
+ * cancelled.
1845
+ * - **`undefined`**: they could not go as one, and nothing of them is pended. {@link pendPhase} then
1846
+ * pends each collection on its own with requests rebuilt WITHOUT the mark. The marked requests are
1847
+ * never re-sent one by one: each carries every block of its collection, so `NetworkTransactor.pend`
1848
+ * would keep the mark, and one collection's late refusal could then surface after a sibling's commit
1849
+ * landed — the tear the mark exists to prevent.
1850
+ */
1851
+ async pendTogether(context, validation, attempts, nominees) {
1852
+ const requests = Array.from(attempts.values(), attempt => this.pendRequestFor(context, validation, attempt, nominees, true));
1853
+ const blockIds = new Map(Array.from(attempts, ([collectionId, attempt]) => [collectionId, blockIdsForTransforms(attempt.transforms)]));
1854
+ let result;
1855
+ try {
1856
+ result = await this.transactor.pendMany(requests);
1857
+ }
1858
+ catch (e) {
1859
+ await this.cancelPhase(context.actionId, blockIds);
1860
+ return pendFailure([e]);
1861
+ }
1862
+ if (result === undefined)
1863
+ return undefined;
1864
+ return result.success
1865
+ ? { success: true, pendedBlockIds: blockIds }
1866
+ : pendFailure([pendRefusalError(Array.from(attempts.keys()), result)]);
1867
+ }
1410
1868
  /**
1411
1869
  * Pend a single collection's transforms. Resolves with the collection id and its
1412
1870
  * pended block ids on success; throws with a per-collection reason on failure so the
1413
1871
  * fan-out in {@link pendPhase} can settle it as a rejection.
1414
1872
  */
1415
- async pendCollection(transaction, validation, collectionId, transforms,
1416
- /** The revision the log entry was stamped with (threaded from applyActionsToCollection),
1417
- * NOT recomputed here: a `getNextRev()` after the append round trips could name a number
1418
- * a concurrent refresh already moved past. */
1419
- rev, actionId, nominees,
1873
+ async pendCollection(context, validation, collectionId,
1874
+ /** Its revision is the one the log entry was stamped with (threaded from the append), NOT
1875
+ * recomputed here: a `getNextRev()` after the append round trips could name a number a
1876
+ * concurrent refresh already moved past. */
1877
+ attempt, nominees,
1420
1878
  /** Whether this is the transaction's only collection (see {@link pendPhase}). */
1421
1879
  sole) {
1422
- const collection = this.collections.get(collectionId);
1423
- if (!collection) {
1424
- throw new Error(`Collection not found: ${collectionId}`);
1425
- }
1426
- // Create the pend request. This is the only producer of PendRequest.validation, and it
1427
- // always sends the pair whole (transaction + operations hash) or not at all. The aged
1428
- // priority has one carrier per shape — inside the transaction when the pend carries it,
1429
- // on the pend itself when it does not — because a member's race resolution reads the
1430
- // transaction's priority first and falls back to the pend's (recordPriority in db-p2p's
1431
- // race-resolution.ts); an unvalidated pend that left both empty would never age. Omitted
1432
- // at 0, exactly as the single-collection path sends it (TransactorSource.transact), so
1433
- // the common first-attempt pend is indistinguishable from a Collection.sync pend.
1434
- const priority = clampPriority(transaction.priority);
1435
- // The base each update-only block's operations were computed against, read from the same
1436
- // tracker the commit side digests (commitCollection); it still holds this transaction's staged
1437
- // transforms and pins. Storage keeps it with the pending record so the record is never applied
1438
- // to a different version of the block (see PendRequest.baseRevs). Omitted when empty.
1439
- const baseRevs = collection.tracker.stagedBaseRevs(blockIdsForTransforms(transforms));
1440
- const pendRequest = {
1441
- actionId,
1442
- rev,
1443
- transforms,
1880
+ const pendResult = await this.transactor.pend(this.pendRequestFor(context, validation, attempt, nominees, sole));
1881
+ if (!pendResult.success) {
1882
+ throw pendRefusalError([collectionId], pendResult);
1883
+ }
1884
+ return { collectionId, blockIds: pendResult.blockIds };
1885
+ }
1886
+ /**
1887
+ * The pend request for one collection's share of an attempt — the one place a pend request is built,
1888
+ * whether it goes on its own ({@link pendCollection}) or with its siblings ({@link pendTogether}).
1889
+ */
1890
+ pendRequestFor(context, validation, attempt, nominees,
1891
+ /** Whether this request is the action's whole reservation, alone or with the siblings it is sent
1892
+ * with (`PendRequest.soleReservation`). */
1893
+ sole) {
1894
+ // This is the only producer of PendRequest.validation, and it always sends the pair whole
1895
+ // (transaction + operations hash) or not at all. The aged priority has one carrier per shape —
1896
+ // inside the transaction when the pend carries it, on the pend itself when it does not — because a
1897
+ // member's race resolution reads the transaction's priority first and falls back to the pend's
1898
+ // (recordPriority in db-p2p's race-resolution.ts); an unvalidated pend that left both empty would
1899
+ // never age. Omitted at 0, exactly as the single-collection path sends it
1900
+ // (TransactorSource.transact), so the common first-attempt pend is indistinguishable from a
1901
+ // Collection.sync pend.
1902
+ // The bases (`PendRequest.baseRevs`) were read from the same tracker the commit's declaration was
1903
+ // taken from, when the attempt was described; omitted when empty.
1904
+ return {
1905
+ actionId: context.actionId,
1906
+ rev: attempt.rev,
1907
+ transforms: attempt.transforms,
1444
1908
  policy: 'r', // Return policy: fail but return pending actions
1445
1909
  ...(validation === undefined
1446
- ? (priority > 0 ? { priority } : {})
1910
+ ? (context.priority > 0 ? { priority: context.priority } : {})
1447
1911
  : { validation }),
1448
- ...baseRevsField(baseRevs),
1912
+ ...baseRevsField(attempt.baseRevs),
1449
1913
  superclusterNominees: nominees,
1450
- ...(sole ? { soleReservation: true } : {})
1914
+ ...(sole ? { soleReservation: true } : {}),
1915
+ ...refuseSoloField(context.refuseSolo)
1451
1916
  };
1452
- const pendResult = await this.transactor.pend(pendRequest);
1453
- if (!pendResult.success) {
1454
- if (isExpiryFailure(pendResult)) {
1455
- throw new TransactionExpiredError(pendResult.expired);
1456
- }
1457
- // Retryability comes from the response itself: a producer that classified the failure sets
1458
- // `conflict`, and only where no producer set it do we fall back to inferring from
1459
- // `missing`/`pending`. Either way a conflict is an optimistic-concurrency loss, clearable
1460
- // by a re-read; anything else is a hard rejection (storage/policy) that re-driving won't fix.
1461
- throw new PendRejectedError(collectionId, isConflictFailure(pendResult), pendResult.reason, pendResult.staleAt);
1462
- }
1463
- return { collectionId, blockIds: pendResult.blockIds };
1464
1917
  }
1465
1918
  /**
1466
1919
  * COMMIT phase: Commit to all critical blocks with retry for transient failures.
1467
1920
  *
1468
1921
  * Once all collections are pended (Phase 1 passes), the coordinator has decided
1469
- * to commit. Failed commits are retried (forward recovery) before giving up.
1470
- * Returns which collections committed vs failed so the caller can do targeted cancel.
1922
+ * to commit. Two or more collections go as ONE request when the transactor can send them so
1923
+ * ({@link commitTogether}); otherwise each collection commits on its own, its transient failures
1924
+ * retried (forward recovery) before giving up. Returns which collections committed vs failed so
1925
+ * the caller can do targeted cancel.
1471
1926
  */
1472
- async commitPhase(actionId, criticalBlockIds, pendedBlockIds, pendedRevs) {
1473
- // Fan out the independent per-collection commit-with-retry concurrently, then
1474
- // aggregate the committed/failed partition from the settled results.
1475
- const outcomes = await Promise.allSettled(Array.from(pendedBlockIds.entries()).map(([collectionId, blockIds]) => this.commitCollection(actionId, criticalBlockIds, collectionId, blockIds, pendedRevs.get(collectionId))));
1927
+ async commitPhase(context, attempts, pendedBlockIds) {
1928
+ const together = pendedBlockIds.size > 1 && this.transactor.commitMany
1929
+ ? await this.commitTogether(context, attempts, pendedBlockIds)
1930
+ : undefined;
1931
+ // NOTE: a fallback after a batched pend leaves the multi-collection residual in place: the
1932
+ // pend's decision may have been held back for a commit that now goes per collection, so a member
1933
+ // that refuses one collection's pend late can do so after a sibling collection's commit landed —
1934
+ // reported by forward recovery or `CoordinatorPartialCommitError`. Reached through a thrown
1935
+ // batched commit (`NetworkTransactor.commitMany` answers `undefined` for that). Anything else that
1936
+ // keeps a batch from going as one would have kept the batched pend from going too, except one
1937
+ // case: the coordinator `pendMany` cached for every block evicted before the commit ran (the
1938
+ // cache's TTL is at least a minute, its size cap 1000 transactions), so a live lookup can split
1939
+ // the blocks. If that ever shows up, pin the commit to the coordinator the batched pend answered
1940
+ // from. See docs/correctness.md §2 Definitions.
1941
+ const outcomes = together ?? await this.commitEach(context, attempts, pendedBlockIds);
1476
1942
  const committedCollections = new Map();
1477
1943
  const failedCollections = new Set();
1478
- const errors = [];
1944
+ const errors = new Set();
1479
1945
  // Classify failures: a returned stale loss (someone committed a newer rev) is retryable after
1480
1946
  // a re-read; a thrown/transient-exhausted or structural failure is not. staleLoss holds only
1481
1947
  // if EVERY failure was a stale loss — a single hard failure makes the whole attempt not worth
@@ -1483,33 +1949,25 @@ export class TransactionCoordinator {
1483
1949
  let anyStale = false;
1484
1950
  let anyHard = false;
1485
1951
  let expired;
1486
- for (const outcome of outcomes) {
1487
- if (outcome.status === 'fulfilled') {
1488
- const result = outcome.value;
1489
- if (result.committed) {
1490
- committedCollections.set(result.collectionId, result.durability);
1491
- }
1492
- else {
1493
- failedCollections.add(result.collectionId);
1494
- errors.push(result.error);
1495
- if (result.stale)
1496
- anyStale = true;
1497
- else
1498
- anyHard = true;
1499
- expired ??= result.expired;
1500
- }
1952
+ for (const result of outcomes) {
1953
+ if (result.committed) {
1954
+ committedCollections.set(result.collectionId, result.durability);
1501
1955
  }
1502
1956
  else {
1503
- // commitCollection resolves rather than rejects, but treat any unexpected
1504
- // rejection as a (hard) failure so the partitioned sets stay honest.
1505
- errors.push(outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason));
1506
- anyHard = true;
1957
+ failedCollections.add(result.collectionId);
1958
+ // A set: a batched refusal answers every collection with the one reason.
1959
+ errors.add(result.error);
1960
+ if (result.stale)
1961
+ anyStale = true;
1962
+ else
1963
+ anyHard = true;
1964
+ expired ??= result.expired;
1507
1965
  }
1508
1966
  }
1509
- if (failedCollections.size > 0 || errors.length > 0) {
1967
+ if (failedCollections.size > 0) {
1510
1968
  return {
1511
1969
  success: false,
1512
- error: errors.join('; ') || 'Commit failed',
1970
+ error: Array.from(errors).join('; ') || 'Commit failed',
1513
1971
  committedCollections,
1514
1972
  failedCollections,
1515
1973
  staleLoss: anyStale && !anyHard,
@@ -1518,40 +1976,64 @@ export class TransactionCoordinator {
1518
1976
  }
1519
1977
  return { success: true, committedCollections, failedCollections };
1520
1978
  }
1979
+ /**
1980
+ * Commits every collection as ONE request ({@link ITransactor.commitMany}): one consensus record,
1981
+ * decided together — the commit half of {@link pendTogether}. Every collection gets the batch's one
1982
+ * answer ({@link collectionCommitOutcome}): committed, each stamped with its own blocks and revision;
1983
+ * or refused, every collection alike. A refused collection's attempt is then retained by
1984
+ * `commitOnceLatched`, and the refresh between attempts finishes any collection whose log entry did
1985
+ * land (`Collection.completeOwnEntry`) — the path a refused one-collection commit already takes.
1986
+ *
1987
+ * `undefined` when they could not go as one, when the request threw, or when a collection's request
1988
+ * could not be built (no log tail among its pended blocks): {@link commitPhase} then commits each
1989
+ * collection on its own, which re-sends everything and reports a request it cannot build as it
1990
+ * always has. The batch is never retried here: a returned refusal cannot be won by the identical
1991
+ * request, and a throw is the per-collection path's to retry.
1992
+ */
1993
+ async commitTogether(context, attempts, pendedBlockIds) {
1994
+ const actionId = context.actionId;
1995
+ const requests = [];
1996
+ for (const [collectionId, blockIds] of pendedBlockIds) {
1997
+ const request = this.commitRequestFor(context, collectionId, attempts.get(collectionId), blockIds);
1998
+ if (typeof request === 'string')
1999
+ return undefined;
2000
+ requests.push({ collectionId, request });
2001
+ }
2002
+ let result;
2003
+ try {
2004
+ result = await this.transactor.commitMany(requests.map(({ request }) => request));
2005
+ }
2006
+ catch (e) {
2007
+ log('commitTogether: batched commit threw; committing each collection on its own actionId=%s: %o', actionId, e);
2008
+ return undefined;
2009
+ }
2010
+ return result === undefined
2011
+ ? undefined
2012
+ : requests.map(({ collectionId, request }) => collectionCommitOutcome(collectionId, request, result));
2013
+ }
2014
+ /** Commits each collection on its own, concurrently ({@link commitCollection}), one outcome per collection. */
2015
+ async commitEach(context, attempts, pendedBlockIds) {
2016
+ const entries = Array.from(pendedBlockIds.entries());
2017
+ const settled = await Promise.allSettled(entries.map(([collectionId, blockIds]) => this.commitCollection(context, collectionId, attempts.get(collectionId), blockIds)));
2018
+ // commitCollection resolves rather than rejects, but treat any unexpected rejection as a (hard)
2019
+ // failure of its collection so the partitioned sets stay honest.
2020
+ return settled.map((outcome, i) => outcome.status === 'fulfilled'
2021
+ ? outcome.value
2022
+ : { collectionId: entries[i][0], committed: false, error: outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason) });
2023
+ }
1521
2024
  /**
1522
2025
  * Commit a single collection's pended blocks, retrying transient failures up to three
1523
2026
  * times (forward recovery). Always resolves — success is carried in the returned
1524
2027
  * `committed` flag, with the commit's `durability` beside it — so the fan-out in
1525
- * {@link commitPhase} can aggregate every result.
2028
+ * {@link commitEach} can aggregate every result.
1526
2029
  */
1527
- async commitCollection(actionId, criticalBlockIds, collectionId, blockIds,
1528
- /** The revision this collection PENDED at, threaded from the log append — the same bug
1529
- * family as pendCollection's: recomputing `getNextRev()` here, after the pend round
1530
- * trips, could stamp the CommitRequest with a different number than the pend named. */
1531
- rev) {
1532
- const collection = this.collections.get(collectionId);
1533
- if (!collection) {
1534
- return { collectionId, committed: false, error: `Collection not found: ${collectionId}` };
1535
- }
1536
- // Find the critical block (log tail) for this collection
1537
- const logTailBlockId = criticalBlockIds.find(blockId => blockIds.includes(blockId));
1538
- if (!logTailBlockId) {
1539
- return { collectionId, committed: false, error: `Log tail block not found for collection ${collectionId}` };
1540
- }
1541
- // Declare what each pended block will contain once committed. The collection's tracker still
1542
- // holds this transaction's staged transforms (it is reset only after commit succeeds) and
1543
- // layers over the collection's CacheSource, so this is a purely local computation; an id whose
1544
- // base is not cached is omitted and falls back to corroboration on the member side. Only the
1545
- // client can declare this — CoordinatorRepo.commit forwards without materializing.
1546
- const blockDigests = await computeBlockContentDigests(collection.tracker, blockIds);
1547
- // Create commit request
1548
- const commitRequest = {
1549
- actionId,
1550
- blockIds,
1551
- tailId: logTailBlockId,
1552
- rev,
1553
- ...blockDigestsField(blockDigests)
1554
- };
2030
+ async commitCollection(context, collectionId,
2031
+ /** Its revision is the one this collection PENDED at (see {@link commitRequestFor}). */
2032
+ attempt, blockIds) {
2033
+ const commitRequest = this.commitRequestFor(context, collectionId, attempt, blockIds);
2034
+ if (typeof commitRequest === 'string') {
2035
+ return { collectionId, committed: false, error: commitRequest };
2036
+ }
1555
2037
  // Retry ONLY transient/thrown failures (unreachable peers, timeout) — forward recovery.
1556
2038
  // A returned { success:false } is a refusal the IDENTICAL request can never win (a rival
1557
2039
  // committed a newer rev, or a member behind on the base refused and dropped its pending
@@ -1564,38 +2046,7 @@ export class TransactionCoordinator {
1564
2046
  let lastTransientError;
1565
2047
  for (let attempt = 0; attempt < 3; attempt++) {
1566
2048
  try {
1567
- const commitResult = await this.transactor.commit(commitRequest);
1568
- if (commitResult.success) {
1569
- return { collectionId, committed: true, durability: withBlockRevs(commitResult.durability, blockIds, rev) };
1570
- }
1571
- if (isExpiryFailure(commitResult)) {
1572
- // Not a stale loss: a re-drive's expiration comes from the same clock.
1573
- const expired = new TransactionExpiredError(commitResult.expired);
1574
- return { collectionId, committed: false, error: expired.message, expired };
1575
- }
1576
- // Permanent stale failure: do not retry here. It IS a clean stale loss, though, so
1577
- // mark it retryable at the coordinator level (after a re-read advances the rev).
1578
- // NOTE: deliberately does NOT consult `isConflictFailure` / `StaleFailure.conflict`
1579
- // like the pend path does. Once the pend succeeded, a returned commit failure means
1580
- // the revision slot moved, or a member behind on the base refused — the durability
1581
- // gate's `commit-not-durable` (which does set `conflict`) or a solo StorageRepo's
1582
- // `missing-base-revision` (a bare `reason`, no `conflict`). All of these clear on a
1583
- // re-drive, so gating on `conflict` here would fail the last of them fast. One commit
1584
- // producer DOES set `conflict` now —
1585
- // db-p2p's CoordinatorRepo.commit returns lost commit-consensus races and classified
1586
- // stale-commit rejections as `{ success:false, conflict:true }` (returning, not
1587
- // throwing, is what keeps them out of the verbatim retry above) — but every returned
1588
- // failure still maps to `stale: true` here, and `isConflictFailure` covers that new
1589
- // shape, so no behavior change is needed. The one returned refusal that is NOT a stale
1590
- // loss, an expiry, is split off above. If a commit producer ever starts returning other
1591
- // hard commit rejections (validator policy, storage fault) as results too, gate
1592
- // `stale` on isConflictFailure here.
1593
- return {
1594
- collectionId,
1595
- committed: false,
1596
- stale: true,
1597
- error: commitResult.reason ?? `Stale commit for collection ${collectionId}`
1598
- };
2049
+ return collectionCommitOutcome(collectionId, commitRequest, await this.transactor.commit(commitRequest));
1599
2050
  }
1600
2051
  catch (e) {
1601
2052
  lastTransientError = e instanceof Error ? e.message : String(e);
@@ -1603,6 +2054,34 @@ export class TransactionCoordinator {
1603
2054
  }
1604
2055
  return { collectionId, committed: false, error: `Commit failed for collection ${collectionId} after 3 attempts: ${lastTransientError}` };
1605
2056
  }
2057
+ /**
2058
+ * The commit request for one collection's pended blocks — the one place a commit request is built,
2059
+ * whether it goes on its own ({@link commitCollection}) or with its siblings ({@link commitTogether})
2060
+ * — or, as a string, why there is none.
2061
+ */
2062
+ commitRequestFor(context, collectionId,
2063
+ /** Its revision is the one this collection PENDED at, threaded from the log append — the same
2064
+ * bug family as pendCollection's: recomputing `getNextRev()` here, after the pend round trips,
2065
+ * could stamp the CommitRequest with a different number than the pend named. */
2066
+ attempt, blockIds) {
2067
+ // The critical block (log tail) for this collection must be among what the pend reserved.
2068
+ if (!blockIds.includes(attempt.tailId)) {
2069
+ return `Log tail block not found for collection ${collectionId}`;
2070
+ }
2071
+ // Declare what each pended block will contain once committed: the description taken before the
2072
+ // pend (declareTouchedBlocks, or stageAttempt for a queued entry's), over the blocks the pend
2073
+ // carried. An id whose base was not cached is omitted and falls back to corroboration on the
2074
+ // member side. Only the client can declare this — CoordinatorRepo.commit forwards without
2075
+ // materializing.
2076
+ return {
2077
+ actionId: context.actionId,
2078
+ blockIds,
2079
+ tailId: attempt.tailId,
2080
+ rev: attempt.rev,
2081
+ ...blockDigestsField(attempt.blockDigests),
2082
+ ...refuseSoloField(context.refuseSolo)
2083
+ };
2084
+ }
1606
2085
  /**
1607
2086
  * CANCEL phase: Cancel pending actions on affected blocks.
1608
2087
  *