@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,14 +1,16 @@
1
1
  import { peerIdFromString } from "../network/types.js";
2
2
  import type { PeerId } from "../network/types.js";
3
- import { highestStaleAt, isConflictFailure, isExpiryFailure } from "../network/stale-failure.js";
3
+ import { highestStaleAt, isConflictFailure, isExpiryFailure, isRejectedFailure, isShortfallFailure } from "../network/stale-failure.js";
4
4
  import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
5
5
  import { mergeDurability, withTornBlocks } from "../network/durability.js";
6
6
  import { judgeCohortLineage, type CohortLineage, type MemberLineage } from "../network/lineage.js";
7
+ import { assertTransactionFits, transactionBytes, MAX_TRANSACTION_BYTES } from "../network/transaction-size.js";
7
8
  import type { ActionTransforms, ActionBlocks, ActionLineage, BlockActionStatus, ITransactor, PendSuccess, CommitSuccess, StaleFailure, WriteFailure, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, Transforms, CommitRequest, ActionId, RepoCommitRequest, ClusterNomineesResult, CollectionId, IBlock, GetBlockResult, CoordinatorIntent, BlockUnavailableReason, BlockContentDigests, BlockBaseRevs, WriteDurability } from "../index.js";
8
9
  import type { IBlockChangeNotifier, CollectionChangeListener } from "./change-notifier.js";
9
10
  import { transformForBlockId, concatTransforms, concatTransform, transformsFromTransform, blockIdsForTransforms } from "../transform/helpers.js";
10
11
  import { Tracker } from "../transform/tracker.js";
11
12
  import { blockDigestsField, baseRevsField } from "../transform/digest.js";
13
+ import { refuseSoloField } from "../network/refuse-solo.js";
12
14
  import { CacheSource } from "../transform/cache-source.js";
13
15
  import { TransactorSource, servedRevision } from "./transactor-source.js";
14
16
  import { Log } from "../log/log.js";
@@ -424,21 +426,35 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
424
426
  }
425
427
  }
426
428
  }
427
- // Ensure we have at least one response per requested block id
428
- const missingIds = distinctBlockIds.filter(bid => !resultEntries.has(bid));
429
- if (missingIds.length > 0) {
430
- log('get:missing blockIds=%o', missingIds);
429
+ // A block with no entry is one of two things. When no batch carrying it got any response — each
430
+ // threw, timed out or was still in flight at the deadline — no coordinator was heard from, the
431
+ // `'peers-unreachable'` answer `CoordinatorRepo` gives for a consult that threw: flagged, so the
432
+ // read of THAT block fails typed (`BlockUnavailableError`) while its siblings are returned. When
433
+ // some coordinator responded and left it out, that is a protocol fault, not unreachability, and
434
+ // fails the whole read as it always has. Flagged entries are added after the merge, so they
435
+ // never compete with a real answer.
436
+ const responded = respondedBlocks(batches);
437
+ const omittedIds = distinctBlockIds.filter(bid => !resultEntries.has(bid) && responded.has(bid));
438
+ const unansweredIds = distinctBlockIds.filter(bid => !resultEntries.has(bid) && !responded.has(bid));
439
+ const rootCause = firstBatchError(batches) ?? error;
440
+ if (omittedIds.length > 0) {
441
+ log('get:missing blockIds=%o', omittedIds);
431
442
  const details = this.formatBatchStatuses(batches,
432
443
  b => {
433
444
  const status = b.request == null ? 'no-response' : (b.request.isResponse ? 'response' : 'in-flight')
434
445
  const errMsg = b.request?.isError ? ` cause=${errorMessage(b.request.error)}` : ''
435
446
  return `${b.peerId.toString()}[block:${b.blockId}](${status})${errMsg}`
436
447
  });
437
- const rootCause = firstBatchError(batches) ?? error;
438
448
  const aggregate = new Error(`Some peers did not complete: ${details}${rootCause ? `; root: ${rootCause.message}` : ''}`);
439
449
  (aggregate as any).cause = rootCause;
440
450
  throw aggregate;
441
451
  }
452
+ if (unansweredIds.length > 0) {
453
+ log('get:unanswered blockIds=%o root=%s', unansweredIds, errorMessage(rootCause));
454
+ for (const bid of unansweredIds) {
455
+ resultEntries.set(bid, { state: {}, unavailable: 'peers-unreachable' } satisfies GetBlockResult);
456
+ }
457
+ }
442
458
 
443
459
  log('get:done blockIds=%d ms=%d', distinctBlockIds.length, Date.now() - t0);
444
460
  return Object.fromEntries(resultEntries) as GetBlockResults;
@@ -640,16 +656,13 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
640
656
  return judgeCohortLineage(members);
641
657
  }
642
658
 
643
- private async consolidateCoordinators(
644
- blockIds: BlockId[],
645
- transforms: Transforms,
646
- transformForBlock: (payload: Transforms, blockId: BlockId, mergeWith?: Transforms) => Transforms
647
- ): Promise<CoordinatorBatch<Transforms, PendResult>[]> {
648
- // Use cluster intersections to minimize the number of coordinators.
649
- // For each block, find its full cluster, then greedily assign blocks to
650
- // peers that appear in the most clusters — reducing round trips when
651
- // blocks share cluster members.
652
-
659
+ /**
660
+ * Which coordinator drives which blocks, keyed by peer id string. For each block, find its full
661
+ * cluster, then greedily assign blocks to the peer appearing in the most clusters
662
+ * ({@link bestCoveringPeer}), reducing round trips when blocks share cluster members; a block whose
663
+ * cluster could not be looked up, or that no member covers, goes to `findCoordinator`.
664
+ */
665
+ private async coordinatorCover(blockIds: readonly BlockId[]): Promise<Map<string, BlockId[]>> {
653
666
  // Step 1: Get cluster peer sets for each block
654
667
  const blockClusterPeerIds: Map<BlockId, Set<string>> = new Map();
655
668
  const fallbackBlocks: BlockId[] = [];
@@ -699,8 +712,16 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
699
712
  existing.push(blockId);
700
713
  assignments.set(key, existing);
701
714
  }
715
+ return assignments;
716
+ }
702
717
 
703
- // Step 5: Convert assignments to batches
718
+ /** One pend batch per coordinator of {@link coordinatorCover}, carrying that coordinator's share of `transforms`. */
719
+ private async consolidateCoordinators(
720
+ blockIds: BlockId[],
721
+ transforms: Transforms,
722
+ transformForBlock: (payload: Transforms, blockId: BlockId, mergeWith?: Transforms) => Transforms
723
+ ): Promise<CoordinatorBatch<Transforms, PendResult>[]> {
724
+ const assignments = await this.coordinatorCover(blockIds);
704
725
  const batches: CoordinatorBatch<Transforms, PendResult>[] = [];
705
726
  for (const [peerIdStr, consolidatedBlocks] of assignments) {
706
727
  const peerId = peerIdFromString(peerIdStr);
@@ -724,6 +745,9 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
724
745
  }
725
746
 
726
747
  async pend(blockAction: PendRequest): Promise<PendResult> {
748
+ // Refused before anything is sent, so no cancel is owed. The whole pend is judged, not each
749
+ // coordinator's share: a share is a subset, so a whole that fits means every share does.
750
+ assertTransactionFits([blockAction]);
727
751
  const t0 = Date.now();
728
752
  const transformForBlock = (payload: Transforms, blockId: BlockId, mergeWithPayload: Transforms | undefined): Transforms => {
729
753
  const filteredTransform = transformForBlockId(payload, blockId);
@@ -769,11 +793,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
769
793
  this.retryBackoff
770
794
  );
771
795
  // Cache resolved coordinators for follow-up commit to hit the same peers
772
- try {
773
- for (const b of Array.from(allBatches(batches))) {
774
- this.keyNetwork.recordCoordinator?.(routingKeyForBlock(b.blockId), b.peerId);
775
- }
776
- } catch (e) { log('WARN: Failed to record coordinator hint %o', e); }
796
+ this.recordCoordinatorHints(Array.from(allBatches(batches), b => [b.blockId, b.peerId] as const));
777
797
  } catch (e) {
778
798
  error = e as Error;
779
799
  }
@@ -860,6 +880,116 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
860
880
  };
861
881
  }
862
882
 
883
+ /**
884
+ * Pends every request as ONE request to the one coordinator covering all their blocks — one consensus
885
+ * record, answered together (`IRepo.pendMany`). Each request goes whole, `soleReservation` and bases
886
+ * exactly as given, with one expiration and the union of their blocks as the blocks that coordinator
887
+ * drives.
888
+ *
889
+ * Returns `undefined` before sending anything when they cannot go as one: their blocks need more than
890
+ * one coordinator by the cover {@link pend} computes ({@link coordinatorCover}), a lookup failed, that
891
+ * coordinator's repo takes no batch, or together they are over the per-transaction size limit (which
892
+ * binds one record, so each may still fit on its own). The caller then pends them its usual way, and
893
+ * each of those pends repeats the lookups and the size check for itself.
894
+ *
895
+ * Answered as {@link pend} answers, cancelling every block first on a failure: a RETURNED refusal is
896
+ * rebuilt by {@link refusalFrom}. A THROW returns `undefined` too: unlike a pend's batches, this one
897
+ * request cannot be re-batched onto other coordinators, so it is the caller's per-request pends —
898
+ * which {@link processBatches} retries elsewhere — that try again. A cancel that did not discharge is
899
+ * owed ({@link owedCancels}), and those pends, of the same action, supersede it on the blocks they
900
+ * write afresh.
901
+ */
902
+ async pendMany(requests: readonly PendRequest[]): Promise<PendResult | undefined> {
903
+ if (requests.length === 0) throw new Error('pendMany: no requests to pend');
904
+ const actionId = requests[0]!.actionId;
905
+ const blockIds = requests.flatMap(request => blockIdsForTransforms(request.transforms));
906
+ if (transactionBytes(requests) > MAX_TRANSACTION_BYTES) {
907
+ log('pendMany:inapplicable actionId=%s reason=too-large', actionId);
908
+ return undefined;
909
+ }
910
+ const coordinator = await this.solePendCoordinator(blockIds, actionId);
911
+ const repo = coordinator === undefined ? undefined : this.getRepo(coordinator);
912
+ if (coordinator === undefined || !repo?.pendMany) {
913
+ if (coordinator !== undefined) log('pendMany:inapplicable actionId=%s reason=no-batch-repo', actionId);
914
+ return undefined;
915
+ }
916
+ await this.owedCancels.beforePend(actionId, blockIds);
917
+ log('pendMany actionId=%s requests=%d blockIds=%d', actionId, requests.length, blockIds.length);
918
+
919
+ let answer: PendResult;
920
+ try {
921
+ answer = await repo.pendMany(requests, {
922
+ expiration: Date.now() + this.timeoutMs,
923
+ dialTimeoutMs: this.dialTimeoutMs,
924
+ coordinatingBlockIds: blockIds
925
+ });
926
+ } catch (e) {
927
+ log('WARN: batched pend threw; pending each request on its own: actionId=%s peer=%s error=%s',
928
+ actionId, coordinator.toString(), errorMessage(e));
929
+ await this.cancelBatchedPend(coordinator, actionId, blockIds);
930
+ return undefined;
931
+ }
932
+ if (!answer.success) {
933
+ await this.cancelBatchedPend(coordinator, actionId, blockIds);
934
+ return refusalFrom([answer]);
935
+ }
936
+
937
+ const txnCoordinators = this.txnCoordinatorsFor(actionId);
938
+ for (const bid of blockIds) txnCoordinators.set(bid, coordinator);
939
+ this.recordCoordinatorHints([[blockIds[0]!, coordinator]]);
940
+ return { success: true, pending: answer.pending, blockIds, durability: mergeDurability([answer.durability]) };
941
+ }
942
+
943
+ /**
944
+ * The one coordinator {@link coordinatorCover} assigns every block in `blockIds` to, or `undefined`
945
+ * when it assigns more than one, or a lookup failed (logged).
946
+ */
947
+ private async solePendCoordinator(blockIds: BlockId[], actionId: ActionId): Promise<PeerId | undefined> {
948
+ let cover: Map<string, BlockId[]>;
949
+ try {
950
+ cover = await this.coordinatorCover(blockIds);
951
+ } catch (e) {
952
+ log('pendMany:unplanned actionId=%s error=%s', actionId, errorMessage(e));
953
+ return undefined;
954
+ }
955
+ const [only, ...others] = cover.keys();
956
+ if (only === undefined || others.length > 0) {
957
+ log('pendMany:inapplicable actionId=%s coordinators=%d', actionId, cover.size);
958
+ return undefined;
959
+ }
960
+ return peerIdFromString(only);
961
+ }
962
+
963
+ /**
964
+ * Discharges every block a batched pend named, its first round sent to the coordinator the pend went
965
+ * to. Awaited, and never thrown: as in {@link pend}'s failure path, a cancel that did not discharge is
966
+ * logged and owed, and must not replace the pend's own answer.
967
+ */
968
+ private async cancelBatchedPend(coordinator: PeerId, actionId: ActionId, blockIds: BlockId[]): Promise<void> {
969
+ const seed: CoordinatorBatch<BlockId[], PendResult> = {
970
+ peerId: coordinator,
971
+ blockId: blockIds[0]!,
972
+ payload: blockIds,
973
+ coordinatingBlockIds: blockIds,
974
+ excludedPeers: []
975
+ };
976
+ try {
977
+ await this.cancelBatch([seed], { actionId, blockIds });
978
+ } catch (cancelError) {
979
+ log('WARN: cancel after batched pend did not discharge: %o', cancelError);
980
+ }
981
+ }
982
+
983
+ /** Tells the key network which coordinator answered for each block, so later requests reach the same
984
+ * peer. A hint: a failure is logged, never thrown. */
985
+ private recordCoordinatorHints(hints: Iterable<readonly [BlockId, PeerId]>): void {
986
+ try {
987
+ for (const [blockId, peerId] of hints) {
988
+ this.keyNetwork.recordCoordinator?.(routingKeyForBlock(blockId), peerId);
989
+ }
990
+ } catch (e) { log('WARN: Failed to record coordinator hint %o', e); }
991
+ }
992
+
863
993
  /**
864
994
  * Discharges every pending record `actionRef` left behind, and THROWS if it could not.
865
995
  *
@@ -967,6 +1097,47 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
967
1097
  : refusalFrom([result]);
968
1098
  }
969
1099
 
1100
+ /**
1101
+ * Commits every request as ONE request to the one coordinator covering all their blocks — one
1102
+ * consensus record, answered together (`IRepo.commitMany`). Each request lists its tail first and its
1103
+ * other blocks after, as {@link commitInOneRound} sends one action's, and is built where every commit
1104
+ * request is ({@link repoCommitRequest}), so its digests name only its own blocks.
1105
+ *
1106
+ * Returns `undefined` when they cannot go as one — their blocks need more than one coordinator
1107
+ * ({@link soleCommitCoordinator}, which prefers what {@link pendMany} cached), or that coordinator's
1108
+ * repo takes no batch — and when the one request THREW: the caller's per-request commits then re-send
1109
+ * everything, and whatever the thrown request landed is this action's own revision, which storage
1110
+ * treats as already done (`isOwnRevision`), the reasoning {@link commitInOneRound}'s fallback rests on.
1111
+ * A RETURNED answer is the batch's verdict.
1112
+ */
1113
+ async commitMany(requests: readonly CommitRequest[]): Promise<CommitResult | undefined> {
1114
+ if (requests.length === 0) throw new Error('commitMany: no requests to commit');
1115
+ const actionId = requests[0]!.actionId;
1116
+ const blockLists = requests.map(tailFirst);
1117
+ const coordinator = await this.soleCommitCoordinator(blockLists.flat(), actionId);
1118
+ const repo = coordinator === undefined ? undefined : this.getRepo(coordinator);
1119
+ if (coordinator === undefined || !repo?.commitMany) {
1120
+ if (coordinator !== undefined) log('commitMany:inapplicable actionId=%s reason=no-batch-repo', actionId);
1121
+ return undefined;
1122
+ }
1123
+ log('commitMany actionId=%s requests=%d', actionId, requests.length);
1124
+
1125
+ let answer: CommitResult;
1126
+ try {
1127
+ answer = await repo.commitMany(
1128
+ requests.map((request, i) => repoCommitRequest(blockLists[i]!, request)),
1129
+ { expiration: Date.now() + this.timeoutMs, dialTimeoutMs: this.dialTimeoutMs }
1130
+ );
1131
+ } catch (e) {
1132
+ log('WARN: batched commit threw; committing each request on its own: actionId=%s peer=%s error=%s',
1133
+ actionId, coordinator.toString(), errorMessage(e));
1134
+ return undefined;
1135
+ }
1136
+ return answer.success
1137
+ ? { success: true, durability: mergeDurability([answer.durability]) }
1138
+ : refusalFrom([answer]);
1139
+ }
1140
+
970
1141
  /**
971
1142
  * The one coordinator covering every block in `blockIds` — resolved as {@link commitBlocks}
972
1143
  * resolves them, preferring what the pend already resolved — or `undefined` when they need more
@@ -994,7 +1165,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
994
1165
  * its tail, and for a {@link commitInOneRound} that threw.
995
1166
  */
996
1167
  private async commitTailThenSweep(request: CommitRequest, remainingBlocks: BlockId[]): Promise<CommitResult> {
997
- const tailResult = await this.commitBlock(request.tailId, request.actionId, request.rev, request.tailId, request.blockDigests);
1168
+ const tailResult = await this.commitBlock(commitOf(request, [request.tailId]));
998
1169
  if (!tailResult.success) {
999
1170
  // NOTE: a refused tail is NOT an absent tail. The coordinator's durability gate answers
1000
1171
  // `commit-not-durable` whenever fewer than a majority hold the revision — even though
@@ -1026,7 +1197,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
1026
1197
  // walk. Sweeping before the tail would also let a committed header point at a never-committed
1027
1198
  // tail: a dangling pointer, strictly worse than an orphaned block.
1028
1199
  if (remainingBlocks.length > 0) {
1029
- const { batches, error } = await this.commitBlocks({ blockIds: remainingBlocks, actionId: request.actionId, rev: request.rev, tailId: request.tailId, blockDigests: request.blockDigests });
1200
+ const { batches, error } = await this.commitBlocks(commitOf(request, remainingBlocks));
1030
1201
  cohortReports.push(...confirmedDurabilities(batches));
1031
1202
  if (error) {
1032
1203
  // Split by the failure's NATURE, exactly as commitBlock does for the tail: a RETURNED
@@ -1140,8 +1311,9 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
1140
1311
  return abandoned;
1141
1312
  }
1142
1313
 
1143
- private async commitBlock(blockId: BlockId, actionId: ActionId, rev: number, tailId?: BlockId, blockDigests?: BlockContentDigests): Promise<CommitResult> {
1144
- const { batches: tailBatches, error: tailError } = await this.commitBlocks({ blockIds: [blockId], actionId, rev, tailId, blockDigests });
1314
+ /** Commits `request`'s one block (the tail), returning a confirmed conflict and throwing a transient fault. */
1315
+ private async commitBlock(request: RepoCommitRequest): Promise<CommitResult> {
1316
+ const { batches: tailBatches, error: tailError } = await this.commitBlocks(request);
1145
1317
  if (tailError) {
1146
1318
  // commit is a pure attempt: stale → { success:false }, transient → throw. Cancellation
1147
1319
  // is the CALLER's responsibility (coordinator cancelPhase; TransactorSource.transact),
@@ -1169,19 +1341,9 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
1169
1341
  return stale.length === 0 ? undefined : refusalFrom(stale.map(b => b.request!.response! as WriteFailure));
1170
1342
  }
1171
1343
 
1172
- /**
1173
- * The one place a commit request to a coordinator is built — shared by {@link commitInOneRound}
1174
- * and {@link commitBlocks}. `blockDigests` arrives as the action's FULL declaration map and is
1175
- * narrowed to `blockIds` here, at send time, never up front: each request becomes its own cluster
1176
- * record, so shipping the whole map would make one cohort sign for blocks it is not responsible
1177
- * for; and `processBatches` re-batches failed blocks onto different coordinators, so only a
1178
- * send-time subset stays correct across retries.
1179
- */
1180
- private sendCommit(peerId: PeerId, blockIds: BlockId[], { actionId, rev, tailId, blockDigests }: RepoCommitRequest, expiration: number): Promise<CommitResult> {
1181
- return this.getRepo(peerId).commit(
1182
- { actionId, blockIds, rev, tailId, ...digestsFor(blockDigests, blockIds) },
1183
- { expiration, dialTimeoutMs: this.dialTimeoutMs }
1184
- );
1344
+ /** Sends `request`'s commit of `blockIds` to `peerId` — shared by {@link commitInOneRound} and {@link commitBlocks}. */
1345
+ private sendCommit(peerId: PeerId, blockIds: BlockId[], request: RepoCommitRequest, expiration: number): Promise<CommitResult> {
1346
+ return this.getRepo(peerId).commit(repoCommitRequest(blockIds, request), { expiration, dialTimeoutMs: this.dialTimeoutMs });
1185
1347
  }
1186
1348
 
1187
1349
  /** Attempts to commit a set of blocks, and handles failures and errors. */
@@ -1462,7 +1624,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
1462
1624
  } catch (e) {
1463
1625
  error = asError(e);
1464
1626
  }
1465
- return { batches, discharged: dischargedBlocks(batches), error };
1627
+ return { batches, discharged: respondedBlocks(batches), error };
1466
1628
  }
1467
1629
 
1468
1630
  /**
@@ -1518,17 +1680,18 @@ function bestCoveringPeer(peerBlocks: Map<string, BlockId[]>, uncovered: Set<Blo
1518
1680
  }
1519
1681
 
1520
1682
  /**
1521
- * The block ids some batch in the tree got an ANSWER for. A cancel batch that errored, or never
1522
- * responded, discharged nothing — its blocks' pending records are still standing. Batch payloads
1523
- * are block-id lists (built with {@link mergeBlocks}), including the retry batches
1524
- * `processBatches` re-homes, so the union across the whole tree is the discharged set.
1683
+ * The block ids some batch in the tree got an ANSWER for, whatever the answer said. A cancel batch
1684
+ * that errored, or never responded, discharged nothing — its blocks' pending records are still
1685
+ * standing — so for a cancel this is the discharged set. For a read it separates a block no
1686
+ * coordinator answered from one a coordinator answered without. Batch payloads are block-id lists,
1687
+ * including the retry batches `processBatches` re-homes, so the union across the whole tree counts.
1525
1688
  */
1526
- function dischargedBlocks(batches: CoordinatorBatch<BlockId[], void>[]): Set<BlockId> {
1527
- const discharged = new Set<BlockId>();
1689
+ function respondedBlocks<TResponse>(batches: CoordinatorBatch<BlockId[], TResponse>[]): Set<BlockId> {
1690
+ const responded = new Set<BlockId>();
1528
1691
  for (const b of allBatches(batches, bb => bb.request?.isResponse === true)) {
1529
- for (const bid of b.payload) discharged.add(bid);
1692
+ for (const bid of b.payload) responded.add(bid);
1530
1693
  }
1531
- return discharged;
1694
+ return responded;
1532
1695
  }
1533
1696
 
1534
1697
  /**
@@ -1547,9 +1710,16 @@ function confirmedDurabilities(batches: CoordinatorBatch<BlockId[], CommitResult
1547
1710
  * {@link NetworkTransactor.pend} and the commit paths use, since the action-level answer is rebuilt
1548
1711
  * from per-batch ones rather than forwarded, and anything not carried here is lost.
1549
1712
  *
1550
- * - An **expiry** anywhere ({@link isExpiryFailure}) is the answer, verbatim — the first one. No
1551
- * retry can succeed while that cohort's clocks disagree with the writer's, so a conflict beside it
1552
- * must not make the write look retryable, and its numbers must reach the writer whole.
1713
+ * - A **validity rejection** anywhere ({@link isRejectedFailure}) is the answer, verbatim — the first
1714
+ * one. Members judged the content, which no retry changes. Above an expiry for the reason a cohort
1715
+ * that judged the content outranks clock votes inside one record: reporting the verdict as a clock
1716
+ * problem would invite a retry the verdict already refuses.
1717
+ * - Otherwise an **expiry** anywhere ({@link isExpiryFailure}) is the answer, verbatim — the first
1718
+ * one. No retry can succeed while that cohort's clocks disagree with the writer's, so a conflict
1719
+ * beside it must not make the write look retryable, and its numbers must reach the writer whole.
1720
+ * - Otherwise a **promise shortfall** anywhere ({@link isShortfallFailure}) is the answer, verbatim —
1721
+ * the first one, for the same reason: no retry can succeed while that cohort's members are silent.
1722
+ * Below an expiry because a shortfall clears when the members come back, and an expiry does not.
1553
1723
  * - Otherwise a {@link StaleFailure}: `reason` is the first one any response gave (the only diagnostic
1554
1724
  * that survives an exhausted retry budget and the coordinator's error text — a refusal whose reason
1555
1725
  * is `commit-not-durable` must not read as "stale commit", a rival's win); `staleAt` is the highest
@@ -1566,9 +1736,9 @@ function confirmedDurabilities(batches: CoordinatorBatch<BlockId[], CommitResult
1566
1736
  * or if mixed-outcome writes show up as wasted retry latency in practice.
1567
1737
  */
1568
1738
  function refusalFrom(responses: WriteFailure[]): WriteFailure {
1569
- const expired = responses.find(isExpiryFailure);
1570
- if (expired !== undefined) {
1571
- return expired;
1739
+ const unretryable = responses.find(isRejectedFailure) ?? responses.find(isExpiryFailure) ?? responses.find(isShortfallFailure);
1740
+ if (unretryable !== undefined) {
1741
+ return unretryable;
1572
1742
  }
1573
1743
  const staleAt = highestStaleAt(responses.map(r => r.staleAt));
1574
1744
  const reason = responses.map(r => r.reason).find(r => r !== undefined);
@@ -1581,6 +1751,31 @@ function refusalFrom(responses: WriteFailure[]): WriteFailure {
1581
1751
  };
1582
1752
  }
1583
1753
 
1754
+ /**
1755
+ * The one place a commit request to a coordinator is built, for `blockIds` of `request`'s action —
1756
+ * every commit {@link NetworkTransactor} sends, batched or not. `blockDigests` arrives as the action's
1757
+ * FULL declaration map and is narrowed to `blockIds` here, at send time, never up front: each request
1758
+ * becomes its own cluster record, or its own operation of one, so shipping the whole map would make a
1759
+ * cohort sign for blocks the request is not committing; and `processBatches` re-batches failed blocks
1760
+ * onto different coordinators, so only a send-time subset stays correct across retries.
1761
+ */
1762
+ function repoCommitRequest(blockIds: BlockId[], { actionId, rev, tailId, blockDigests, refuseSolo }: RepoCommitRequest): RepoCommitRequest {
1763
+ return { actionId, blockIds, rev, tailId, ...digestsFor(blockDigests, blockIds), ...refuseSoloField(refuseSolo) };
1764
+ }
1765
+
1766
+ /** `request`'s commit of `blockIds` alone, for {@link NetworkTransactor}'s two-step path to hand to its
1767
+ * batching: everything the write carries, with its declarations still action-wide — every send goes
1768
+ * through {@link repoCommitRequest}, which narrows them to the blocks that send commits. */
1769
+ function commitOf(request: CommitRequest, blockIds: BlockId[]): RepoCommitRequest {
1770
+ return { blockIds, actionId: request.actionId, rev: request.rev, tailId: request.tailId, blockDigests: request.blockDigests,
1771
+ ...refuseSoloField(request.refuseSolo) };
1772
+ }
1773
+
1774
+ /** `request`'s blocks with its log tail first, each once — the order a coordinator commits them in. */
1775
+ function tailFirst(request: CommitRequest): BlockId[] {
1776
+ return [request.tailId, ...new Set(request.blockIds)].filter((blockId, i) => i === 0 || blockId !== request.tailId);
1777
+ }
1778
+
1584
1779
  /** The entries of `all` whose ids appear in `batchBlockIds` — the per-batch narrowing both
1585
1780
  * per-block declarations share ({@link digestsFor}, {@link baseRevsFor}). */
1586
1781
  function subsetOf<T>(all: Record<BlockId, T>, batchBlockIds: BlockId[]): Record<BlockId, T> {
@@ -1614,7 +1809,9 @@ function baseRevsFor(all: BlockBaseRevs | undefined, batchBlockIds: BlockId[]):
1614
1809
  *
1615
1810
  * `soleReservation` survives only on a batch carrying every block of the action: a pend split across
1616
1811
  * coordinators — by `consolidateCoordinators`, or by `processBatches` re-batching a failed batch — is
1617
- * several reservations, which the field must never claim to be. Decided per send, like the bases. */
1812
+ * several reservations, which the field must never claim to be. Decided per send, like the bases.
1813
+ * Every other field goes on every batch as given — `refuseSolo` included, whose loss on one batch would
1814
+ * let that coordinator's share be written by a lone node the write asked not to be written by. */
1618
1815
  function pendRequestForBatch(action: PendRequest, payload: Transforms): PendRequest {
1619
1816
  const { baseRevs, soleReservation, ...rest } = action;
1620
1817
  const batchBlockIds = blockIdsForTransforms(payload);
@@ -6,11 +6,32 @@ import { withBlockRevs } from "../network/durability.js";
6
6
  import type { ReadDependency } from "../transaction/transaction.js";
7
7
  import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
8
8
  import { blockDigestsField, baseRevsField } from "../transform/digest.js";
9
+ import { refuseSoloField } from "../network/refuse-solo.js";
9
10
  import type { BlockFloorCheck } from "./block-floors.js";
10
11
  import { createLogger } from "../logger.js";
11
12
 
12
13
  const log = createLogger('transactor-source');
13
14
 
15
+ /** {@link TransactorSource.transact}'s optional parts of one attempt. Each is omitted from the
16
+ * request it rides on when unset, so a caller that sets nothing sends exactly the requests it always
17
+ * did — every one of them is hashed verbatim into the cohort signature preimages. */
18
+ export type TransactOptions = {
19
+ /** Aged, advisory retry priority (default 0). Rides on the pend so a repeatedly-losing
20
+ * single-collection sync out-ranks fresh rivals in a concurrent race (`resolveRace`);
21
+ * fairness-only, never affects validity. Omitted from the pend when 0. */
22
+ readonly priority?: number;
23
+ /** Per-block content declarations for the commit (see {@link BlockContentDigests}), computed by
24
+ * the caller from the same tracker that produced the transforms. */
25
+ readonly blockDigests?: BlockContentDigests;
26
+ /** Per-block base revisions for the pend (see `PendRequest.baseRevs`): the committed revision each
27
+ * update-only block's operations were computed against, from the same tracker
28
+ * (`Tracker.stagedBaseRevs`). */
29
+ readonly baseRevs?: BlockBaseRevs;
30
+ /** Refuse to be committed by a lone coordinator that knows it is not alone
31
+ * (`SyncOptions.refuseSoloCommit`): set on both the pend and the commit as `refuseSolo`. */
32
+ readonly refuseSolo?: boolean;
33
+ };
34
+
14
35
  /** The block `entry` answers for `id`, for a read at `context` (`undefined` for an unpinned "give me
15
36
  * latest" read) — `undefined` when the block is absent — or a throw when the entry is not an answer
16
37
  * that read may use. Every read that consumes a raw {@link GetBlockResult} goes through here, so a
@@ -218,16 +239,8 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
218
239
  * that creates it.
219
240
  * @param tailId - The Id of the collection's log tail block. This block's transform is committed FIRST
220
241
  * (prior to the rest of the block operations), to resolve the "winner" of a race to commit to the collection.
221
- * @param priority - Aged, advisory retry priority (default 0). Rides on the pend so a repeatedly-losing
222
- * single-collection sync out-ranks fresh rivals in a concurrent race (`resolveRace`); fairness-only, never
223
- * affects validity. Omitted from the pend when 0 so the common first-attempt pend serializes exactly as before.
224
- * @param blockDigests - Optional per-block content declarations for this commit (see {@link BlockContentDigests}),
225
- * computed by the caller from the same tracker that produced `transform`. Omitted from the commit request when
226
- * undefined, so a caller that declares nothing produces exactly the request shape as before — the field rides
227
- * inside every cohort signature's hash preimage, so keeping the shape clean keeps those preimages clean.
228
- * @param baseRevs - Optional per-block base revisions for the pend (see {@link PendRequest.baseRevs}): the
229
- * committed revision each update-only block's operations were computed against, from the same tracker
230
- * (`Tracker.stagedBaseRevs`). Omitted from the pend request when empty, for the same preimage reason.
242
+ * @param options - The attempt's optional parts ({@link TransactOptions}); each is left off the request it
243
+ * rides on when unset.
231
244
  * @returns The transactor's own verdict, unflattened: a {@link CommitSuccess} carrying the
232
245
  * {@link WriteDurability} of the committed revision — naming every block it committed at `rev`
233
246
  * (`blockRevs`) — or a {@link StaleFailure} if the pend or the commit was refused. Success is
@@ -236,13 +249,15 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
236
249
  * `result.success`. Test "is this completely saved" through `isFullyDurable`, never
237
250
  * by comparing `quorum` (see {@link WriteDurability}).
238
251
  */
239
- async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId, priority = 0, blockDigests?: BlockContentDigests, baseRevs?: BlockBaseRevs): Promise<CommitResult> {
252
+ async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId, options: TransactOptions = {}): Promise<CommitResult> {
253
+ const { priority = 0, blockDigests, baseRevs, refuseSolo } = options;
240
254
  const pendResult = await this.transactor.pend({
241
255
  transforms: transform, actionId, rev, policy: 'r',
242
256
  ...(priority > 0 ? { priority } : {}),
243
257
  ...baseRevsField(baseRevs),
244
258
  // One collection, pended whole and then committed: the shape `PendRequest.soleReservation` names.
245
- soleReservation: true
259
+ soleReservation: true,
260
+ ...refuseSoloField(refuseSolo)
246
261
  });
247
262
  if (!pendResult.success) {
248
263
  return pendResult;
@@ -255,7 +270,8 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
255
270
  blockIds: pendResult.blockIds,
256
271
  actionId,
257
272
  rev,
258
- ...blockDigestsField(blockDigests)
273
+ ...blockDigestsField(blockDigests),
274
+ ...refuseSoloField(refuseSolo)
259
275
  });
260
276
  if (!commitResult.success) {
261
277
  // A confirmed conflict has to be RETURNED as the StaleFailure, because `Collection.sync`
@@ -58,4 +58,20 @@ export type ITransactor = {
58
58
  unable to establish the outcome, which it reports as such rather than guessing either way.
59
59
  */
60
60
  getLineage?(ref: ActionBlocks & { rev: number }): Promise<ActionLineage>;
61
+
62
+ /** Pend every request (one action's, disjoint blocks) as ONE request to one coordinator, answered
63
+ together — one consensus record for the whole set (`IRepo.pendMany`).
64
+ - `undefined`: they could not go as one — nothing of them is left pended by this call, and the
65
+ caller pends them its usual way. Never a verdict.
66
+ - Optional: without it, or without {@link commitMany} beside it, a writer pends each request on its
67
+ own — a batched pend promises its commit goes as one request too (`PendRequest.soleReservation`).
68
+ */
69
+ pendMany?(requests: readonly PendRequest[]): Promise<PendResult | undefined>;
70
+
71
+ /** Commit every request as ONE request to one coordinator, answered together (`IRepo.commitMany`).
72
+ - `undefined`: they could not go as one, or the one request threw; the caller commits them its
73
+ usual way. Never a verdict.
74
+ - Optional, like {@link pendMany}.
75
+ */
76
+ commitMany?(requests: readonly CommitRequest[]): Promise<CommitResult | undefined>;
61
77
  }
@@ -1,6 +1,6 @@
1
1
  import type { BlockId, IBlock } from "../index.js";
2
2
  import type { BlockBaseRevs, BlockContentDigests } from "../network/struct.js";
3
- import { canonicalBlockHash } from "../blocks/helpers.js";
3
+ import { canonicalBlockHashAndBytes } from "../blocks/helpers.js";
4
4
  import { createLogger } from "../logger.js";
5
5
  import { isRecordEmpty } from "../utility/is-record-empty.js";
6
6
  import type { Tracker } from "./tracker.js";
@@ -32,16 +32,49 @@ export async function computeBlockContentDigests<T extends IBlock>(
32
32
  tracker: Tracker<T>,
33
33
  blockIds: BlockId[]
34
34
  ): Promise<BlockContentDigests> {
35
+ return (await describeTouchedBlocks(tracker, blockIds)).digests;
36
+ }
37
+
38
+ /** What a writer can say about the blocks a write touches, from one local materialization of each. */
39
+ export type TouchedBlocks = {
40
+ /** The commit's declaration of what each block will contain ({@link computeBlockContentDigests}). */
41
+ digests: BlockContentDigests;
42
+ /** What each of the same blocks' post-write content encodes to, by `jsonEncodedBytes` — the measure
43
+ * `oversizedBlock` judges against `MAX_BLOCK_BYTES`. */
44
+ bytes: Record<BlockId, number>;
45
+ };
46
+
47
+ /** {@link computeBlockContentDigests}, plus the size of every block it declares, taken from the
48
+ * serialization the digest already hashes — the one pass both write paths make over their touched
49
+ * blocks before anything is sent. Judging the sizes is the caller's separate step (`oversizedBlock`),
50
+ * so declaring content still never breaks committing it.
51
+ *
52
+ * A block this pass cannot materialize is in neither map: neither declared nor measured. Those are the
53
+ * omissions listed at {@link computeBlockContentDigests} — a deleted block, a blind update to a block
54
+ * this node never read, an update whose base was evicted before it was staged, a base that moved under
55
+ * its staged operations — and a base the staged operations would not apply to (`peekOrSkip`). So the
56
+ * per-block size bound has the same gaps as the declaration: a block that outgrows `MAX_BLOCK_BYTES`
57
+ * through an update this node cannot materialize is not refused by the writer. */
58
+ // NOTE: if a block is ever seen past MAX_BLOCK_BYTES after growing through one of those gaps, measure an
59
+ // unmeasured update-only block here by reading its base — the one exception that would make to a commit
60
+ // never paying a network read to describe itself. Its digest can stay undeclared.
61
+ export async function describeTouchedBlocks<T extends IBlock>(
62
+ tracker: Tracker<T>,
63
+ blockIds: BlockId[]
64
+ ): Promise<TouchedBlocks> {
35
65
  const digests: BlockContentDigests = {};
66
+ const bytes: Record<BlockId, number> = {};
36
67
  for (const id of blockIds) {
37
68
  const peeked = peekOrSkip(tracker, id);
38
69
  if (!peeked) continue;
70
+ const described = await canonicalBlockHashAndBytes(peeked.block);
39
71
  digests[id] = {
40
- digest: await canonicalBlockHash(peeked.block),
72
+ digest: described.hash,
41
73
  ...(peeked.baseRev !== undefined ? { baseRev: peeked.baseRev } : {}),
42
74
  };
75
+ bytes[id] = described.bytes;
43
76
  }
44
- return digests;
77
+ return { digests, bytes };
45
78
  }
46
79
 
47
80
  /** Wraps `blockDigests` so it spreads onto a request only when there is something to declare. The
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Visit every item in turn, letting no throw stop the rest, and throw the FIRST error once every
3
+ * item has been visited. Sequential on purpose: each visit must finish before the next starts.
4
+ *
5
+ * For a round of independent per-collection steps — a rollback's restores, a commit's unwinding of
6
+ * its failed participants — where stopping at the first throw would leave every later collection
7
+ * untouched, and silently: the caller sees one error and has no way to tell which collections it
8
+ * reached. Each step being independent (its own instance, its own state) is what makes the first
9
+ * error the right one to report; a step whose failure should change how the next is handled does
10
+ * not belong in this loop. `TransactionCoordinator.refreshBetweenAttempts` is the same idiom with
11
+ * a per-error classification this helper does not carry.
12
+ */
13
+ export async function visitEveryThenThrow<T>(items: Iterable<T>, visit: (item: T) => Promise<void>): Promise<void> {
14
+ let first: { error: unknown } | undefined;
15
+ for (const item of items) {
16
+ try {
17
+ await visit(item);
18
+ } catch (error) {
19
+ first ??= { error };
20
+ }
21
+ }
22
+ if (first !== undefined) {
23
+ throw first.error;
24
+ }
25
+ }