@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,11 +1,13 @@
1
1
  import { peerIdFromString } from "../network/types.js";
2
- import { highestStaleAt, isConflictFailure, isExpiryFailure } from "../network/stale-failure.js";
2
+ import { highestStaleAt, isConflictFailure, isExpiryFailure, isRejectedFailure, isShortfallFailure } from "../network/stale-failure.js";
3
3
  import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
4
4
  import { mergeDurability, withTornBlocks } from "../network/durability.js";
5
5
  import { judgeCohortLineage } from "../network/lineage.js";
6
+ import { assertTransactionFits, transactionBytes, MAX_TRANSACTION_BYTES } from "../network/transaction-size.js";
6
7
  import { transformForBlockId, concatTransforms, concatTransform, transformsFromTransform, blockIdsForTransforms } from "../transform/helpers.js";
7
8
  import { Tracker } from "../transform/tracker.js";
8
9
  import { blockDigestsField, baseRevsField } from "../transform/digest.js";
10
+ import { refuseSoloField } from "../network/refuse-solo.js";
9
11
  import { CacheSource } from "../transform/cache-source.js";
10
12
  import { TransactorSource, servedRevision } from "./transactor-source.js";
11
13
  import { Log } from "../log/log.js";
@@ -318,20 +320,34 @@ export class NetworkTransactor {
318
320
  }
319
321
  }
320
322
  }
321
- // Ensure we have at least one response per requested block id
322
- const missingIds = distinctBlockIds.filter(bid => !resultEntries.has(bid));
323
- if (missingIds.length > 0) {
324
- log('get:missing blockIds=%o', missingIds);
323
+ // A block with no entry is one of two things. When no batch carrying it got any response — each
324
+ // threw, timed out or was still in flight at the deadline — no coordinator was heard from, the
325
+ // `'peers-unreachable'` answer `CoordinatorRepo` gives for a consult that threw: flagged, so the
326
+ // read of THAT block fails typed (`BlockUnavailableError`) while its siblings are returned. When
327
+ // some coordinator responded and left it out, that is a protocol fault, not unreachability, and
328
+ // fails the whole read as it always has. Flagged entries are added after the merge, so they
329
+ // never compete with a real answer.
330
+ const responded = respondedBlocks(batches);
331
+ const omittedIds = distinctBlockIds.filter(bid => !resultEntries.has(bid) && responded.has(bid));
332
+ const unansweredIds = distinctBlockIds.filter(bid => !resultEntries.has(bid) && !responded.has(bid));
333
+ const rootCause = firstBatchError(batches) ?? error;
334
+ if (omittedIds.length > 0) {
335
+ log('get:missing blockIds=%o', omittedIds);
325
336
  const details = this.formatBatchStatuses(batches, b => {
326
337
  const status = b.request == null ? 'no-response' : (b.request.isResponse ? 'response' : 'in-flight');
327
338
  const errMsg = b.request?.isError ? ` cause=${errorMessage(b.request.error)}` : '';
328
339
  return `${b.peerId.toString()}[block:${b.blockId}](${status})${errMsg}`;
329
340
  });
330
- const rootCause = firstBatchError(batches) ?? error;
331
341
  const aggregate = new Error(`Some peers did not complete: ${details}${rootCause ? `; root: ${rootCause.message}` : ''}`);
332
342
  aggregate.cause = rootCause;
333
343
  throw aggregate;
334
344
  }
345
+ if (unansweredIds.length > 0) {
346
+ log('get:unanswered blockIds=%o root=%s', unansweredIds, errorMessage(rootCause));
347
+ for (const bid of unansweredIds) {
348
+ resultEntries.set(bid, { state: {}, unavailable: 'peers-unreachable' });
349
+ }
350
+ }
335
351
  log('get:done blockIds=%d ms=%d', distinctBlockIds.length, Date.now() - t0);
336
352
  return Object.fromEntries(resultEntries);
337
353
  }
@@ -513,11 +529,13 @@ export class NetworkTransactor {
513
529
  }));
514
530
  return judgeCohortLineage(members);
515
531
  }
516
- async consolidateCoordinators(blockIds, transforms, transformForBlock) {
517
- // Use cluster intersections to minimize the number of coordinators.
518
- // For each block, find its full cluster, then greedily assign blocks to
519
- // peers that appear in the most clusters — reducing round trips when
520
- // blocks share cluster members.
532
+ /**
533
+ * Which coordinator drives which blocks, keyed by peer id string. For each block, find its full
534
+ * cluster, then greedily assign blocks to the peer appearing in the most clusters
535
+ * ({@link bestCoveringPeer}), reducing round trips when blocks share cluster members; a block whose
536
+ * cluster could not be looked up, or that no member covers, goes to `findCoordinator`.
537
+ */
538
+ async coordinatorCover(blockIds) {
521
539
  // Step 1: Get cluster peer sets for each block
522
540
  const blockClusterPeerIds = new Map();
523
541
  const fallbackBlocks = [];
@@ -563,7 +581,11 @@ export class NetworkTransactor {
563
581
  existing.push(blockId);
564
582
  assignments.set(key, existing);
565
583
  }
566
- // Step 5: Convert assignments to batches
584
+ return assignments;
585
+ }
586
+ /** One pend batch per coordinator of {@link coordinatorCover}, carrying that coordinator's share of `transforms`. */
587
+ async consolidateCoordinators(blockIds, transforms, transformForBlock) {
588
+ const assignments = await this.coordinatorCover(blockIds);
567
589
  const batches = [];
568
590
  for (const [peerIdStr, consolidatedBlocks] of assignments) {
569
591
  const peerId = peerIdFromString(peerIdStr);
@@ -583,6 +605,9 @@ export class NetworkTransactor {
583
605
  return batches;
584
606
  }
585
607
  async pend(blockAction) {
608
+ // Refused before anything is sent, so no cancel is owed. The whole pend is judged, not each
609
+ // coordinator's share: a share is a subset, so a whole that fits means every share does.
610
+ assertTransactionFits([blockAction]);
586
611
  const t0 = Date.now();
587
612
  const transformForBlock = (payload, blockId, mergeWithPayload) => {
588
613
  const filteredTransform = transformForBlockId(payload, blockId);
@@ -616,14 +641,7 @@ export class NetworkTransactor {
616
641
  coordinatingBlockIds: batch.coordinatingBlockIds
617
642
  }), batch => blockIdsForTransforms(batch.payload), transformForBlock, expiration, (blockId, options) => this.keyNetwork.findCoordinator(routingKeyForBlock(blockId), options), this.retryBackoff);
618
643
  // Cache resolved coordinators for follow-up commit to hit the same peers
619
- try {
620
- for (const b of Array.from(allBatches(batches))) {
621
- this.keyNetwork.recordCoordinator?.(routingKeyForBlock(b.blockId), b.peerId);
622
- }
623
- }
624
- catch (e) {
625
- log('WARN: Failed to record coordinator hint %o', e);
626
- }
644
+ this.recordCoordinatorHints(Array.from(allBatches(batches), b => [b.blockId, b.peerId]));
627
645
  }
628
646
  catch (e) {
629
647
  error = e;
@@ -705,6 +723,118 @@ export class NetworkTransactor {
705
723
  durability: mergeDurability(completed.map(b => b.request.response.durability))
706
724
  };
707
725
  }
726
+ /**
727
+ * Pends every request as ONE request to the one coordinator covering all their blocks — one consensus
728
+ * record, answered together (`IRepo.pendMany`). Each request goes whole, `soleReservation` and bases
729
+ * exactly as given, with one expiration and the union of their blocks as the blocks that coordinator
730
+ * drives.
731
+ *
732
+ * Returns `undefined` before sending anything when they cannot go as one: their blocks need more than
733
+ * one coordinator by the cover {@link pend} computes ({@link coordinatorCover}), a lookup failed, that
734
+ * coordinator's repo takes no batch, or together they are over the per-transaction size limit (which
735
+ * binds one record, so each may still fit on its own). The caller then pends them its usual way, and
736
+ * each of those pends repeats the lookups and the size check for itself.
737
+ *
738
+ * Answered as {@link pend} answers, cancelling every block first on a failure: a RETURNED refusal is
739
+ * rebuilt by {@link refusalFrom}. A THROW returns `undefined` too: unlike a pend's batches, this one
740
+ * request cannot be re-batched onto other coordinators, so it is the caller's per-request pends —
741
+ * which {@link processBatches} retries elsewhere — that try again. A cancel that did not discharge is
742
+ * owed ({@link owedCancels}), and those pends, of the same action, supersede it on the blocks they
743
+ * write afresh.
744
+ */
745
+ async pendMany(requests) {
746
+ if (requests.length === 0)
747
+ throw new Error('pendMany: no requests to pend');
748
+ const actionId = requests[0].actionId;
749
+ const blockIds = requests.flatMap(request => blockIdsForTransforms(request.transforms));
750
+ if (transactionBytes(requests) > MAX_TRANSACTION_BYTES) {
751
+ log('pendMany:inapplicable actionId=%s reason=too-large', actionId);
752
+ return undefined;
753
+ }
754
+ const coordinator = await this.solePendCoordinator(blockIds, actionId);
755
+ const repo = coordinator === undefined ? undefined : this.getRepo(coordinator);
756
+ if (coordinator === undefined || !repo?.pendMany) {
757
+ if (coordinator !== undefined)
758
+ log('pendMany:inapplicable actionId=%s reason=no-batch-repo', actionId);
759
+ return undefined;
760
+ }
761
+ await this.owedCancels.beforePend(actionId, blockIds);
762
+ log('pendMany actionId=%s requests=%d blockIds=%d', actionId, requests.length, blockIds.length);
763
+ let answer;
764
+ try {
765
+ answer = await repo.pendMany(requests, {
766
+ expiration: Date.now() + this.timeoutMs,
767
+ dialTimeoutMs: this.dialTimeoutMs,
768
+ coordinatingBlockIds: blockIds
769
+ });
770
+ }
771
+ catch (e) {
772
+ log('WARN: batched pend threw; pending each request on its own: actionId=%s peer=%s error=%s', actionId, coordinator.toString(), errorMessage(e));
773
+ await this.cancelBatchedPend(coordinator, actionId, blockIds);
774
+ return undefined;
775
+ }
776
+ if (!answer.success) {
777
+ await this.cancelBatchedPend(coordinator, actionId, blockIds);
778
+ return refusalFrom([answer]);
779
+ }
780
+ const txnCoordinators = this.txnCoordinatorsFor(actionId);
781
+ for (const bid of blockIds)
782
+ txnCoordinators.set(bid, coordinator);
783
+ this.recordCoordinatorHints([[blockIds[0], coordinator]]);
784
+ return { success: true, pending: answer.pending, blockIds, durability: mergeDurability([answer.durability]) };
785
+ }
786
+ /**
787
+ * The one coordinator {@link coordinatorCover} assigns every block in `blockIds` to, or `undefined`
788
+ * when it assigns more than one, or a lookup failed (logged).
789
+ */
790
+ async solePendCoordinator(blockIds, actionId) {
791
+ let cover;
792
+ try {
793
+ cover = await this.coordinatorCover(blockIds);
794
+ }
795
+ catch (e) {
796
+ log('pendMany:unplanned actionId=%s error=%s', actionId, errorMessage(e));
797
+ return undefined;
798
+ }
799
+ const [only, ...others] = cover.keys();
800
+ if (only === undefined || others.length > 0) {
801
+ log('pendMany:inapplicable actionId=%s coordinators=%d', actionId, cover.size);
802
+ return undefined;
803
+ }
804
+ return peerIdFromString(only);
805
+ }
806
+ /**
807
+ * Discharges every block a batched pend named, its first round sent to the coordinator the pend went
808
+ * to. Awaited, and never thrown: as in {@link pend}'s failure path, a cancel that did not discharge is
809
+ * logged and owed, and must not replace the pend's own answer.
810
+ */
811
+ async cancelBatchedPend(coordinator, actionId, blockIds) {
812
+ const seed = {
813
+ peerId: coordinator,
814
+ blockId: blockIds[0],
815
+ payload: blockIds,
816
+ coordinatingBlockIds: blockIds,
817
+ excludedPeers: []
818
+ };
819
+ try {
820
+ await this.cancelBatch([seed], { actionId, blockIds });
821
+ }
822
+ catch (cancelError) {
823
+ log('WARN: cancel after batched pend did not discharge: %o', cancelError);
824
+ }
825
+ }
826
+ /** Tells the key network which coordinator answered for each block, so later requests reach the same
827
+ * peer. A hint: a failure is logged, never thrown. */
828
+ recordCoordinatorHints(hints) {
829
+ try {
830
+ for (const [blockId, peerId] of hints) {
831
+ this.keyNetwork.recordCoordinator?.(routingKeyForBlock(blockId), peerId);
832
+ }
833
+ }
834
+ catch (e) {
835
+ log('WARN: Failed to record coordinator hint %o', e);
836
+ }
837
+ }
708
838
  /**
709
839
  * Discharges every pending record `actionRef` left behind, and THROWS if it could not.
710
840
  *
@@ -807,6 +937,44 @@ export class NetworkTransactor {
807
937
  ? { success: true, durability: mergeDurability([result.durability]) }
808
938
  : refusalFrom([result]);
809
939
  }
940
+ /**
941
+ * Commits every request as ONE request to the one coordinator covering all their blocks — one
942
+ * consensus record, answered together (`IRepo.commitMany`). Each request lists its tail first and its
943
+ * other blocks after, as {@link commitInOneRound} sends one action's, and is built where every commit
944
+ * request is ({@link repoCommitRequest}), so its digests name only its own blocks.
945
+ *
946
+ * Returns `undefined` when they cannot go as one — their blocks need more than one coordinator
947
+ * ({@link soleCommitCoordinator}, which prefers what {@link pendMany} cached), or that coordinator's
948
+ * repo takes no batch — and when the one request THREW: the caller's per-request commits then re-send
949
+ * everything, and whatever the thrown request landed is this action's own revision, which storage
950
+ * treats as already done (`isOwnRevision`), the reasoning {@link commitInOneRound}'s fallback rests on.
951
+ * A RETURNED answer is the batch's verdict.
952
+ */
953
+ async commitMany(requests) {
954
+ if (requests.length === 0)
955
+ throw new Error('commitMany: no requests to commit');
956
+ const actionId = requests[0].actionId;
957
+ const blockLists = requests.map(tailFirst);
958
+ const coordinator = await this.soleCommitCoordinator(blockLists.flat(), actionId);
959
+ const repo = coordinator === undefined ? undefined : this.getRepo(coordinator);
960
+ if (coordinator === undefined || !repo?.commitMany) {
961
+ if (coordinator !== undefined)
962
+ log('commitMany:inapplicable actionId=%s reason=no-batch-repo', actionId);
963
+ return undefined;
964
+ }
965
+ log('commitMany actionId=%s requests=%d', actionId, requests.length);
966
+ let answer;
967
+ try {
968
+ answer = await repo.commitMany(requests.map((request, i) => repoCommitRequest(blockLists[i], request)), { expiration: Date.now() + this.timeoutMs, dialTimeoutMs: this.dialTimeoutMs });
969
+ }
970
+ catch (e) {
971
+ log('WARN: batched commit threw; committing each request on its own: actionId=%s peer=%s error=%s', actionId, coordinator.toString(), errorMessage(e));
972
+ return undefined;
973
+ }
974
+ return answer.success
975
+ ? { success: true, durability: mergeDurability([answer.durability]) }
976
+ : refusalFrom([answer]);
977
+ }
810
978
  /**
811
979
  * The one coordinator covering every block in `blockIds` — resolved as {@link commitBlocks}
812
980
  * resolves them, preferring what the pend already resolved — or `undefined` when they need more
@@ -834,7 +1002,7 @@ export class NetworkTransactor {
834
1002
  * its tail, and for a {@link commitInOneRound} that threw.
835
1003
  */
836
1004
  async commitTailThenSweep(request, remainingBlocks) {
837
- const tailResult = await this.commitBlock(request.tailId, request.actionId, request.rev, request.tailId, request.blockDigests);
1005
+ const tailResult = await this.commitBlock(commitOf(request, [request.tailId]));
838
1006
  if (!tailResult.success) {
839
1007
  // NOTE: a refused tail is NOT an absent tail. The coordinator's durability gate answers
840
1008
  // `commit-not-durable` whenever fewer than a majority hold the revision — even though
@@ -865,7 +1033,7 @@ export class NetworkTransactor {
865
1033
  // walk. Sweeping before the tail would also let a committed header point at a never-committed
866
1034
  // tail: a dangling pointer, strictly worse than an orphaned block.
867
1035
  if (remainingBlocks.length > 0) {
868
- const { batches, error } = await this.commitBlocks({ blockIds: remainingBlocks, actionId: request.actionId, rev: request.rev, tailId: request.tailId, blockDigests: request.blockDigests });
1036
+ const { batches, error } = await this.commitBlocks(commitOf(request, remainingBlocks));
869
1037
  cohortReports.push(...confirmedDurabilities(batches));
870
1038
  if (error) {
871
1039
  // Split by the failure's NATURE, exactly as commitBlock does for the tail: a RETURNED
@@ -984,8 +1152,9 @@ export class NetworkTransactor {
984
1152
  }
985
1153
  return abandoned;
986
1154
  }
987
- async commitBlock(blockId, actionId, rev, tailId, blockDigests) {
988
- const { batches: tailBatches, error: tailError } = await this.commitBlocks({ blockIds: [blockId], actionId, rev, tailId, blockDigests });
1155
+ /** Commits `request`'s one block (the tail), returning a confirmed conflict and throwing a transient fault. */
1156
+ async commitBlock(request) {
1157
+ const { batches: tailBatches, error: tailError } = await this.commitBlocks(request);
989
1158
  if (tailError) {
990
1159
  // commit is a pure attempt: stale → { success:false }, transient → throw. Cancellation
991
1160
  // is the CALLER's responsibility (coordinator cancelPhase; TransactorSource.transact),
@@ -1011,16 +1180,9 @@ export class NetworkTransactor {
1011
1180
  const stale = Array.from(allBatches(batches, b => b.request?.isResponse && !b.request.response.success));
1012
1181
  return stale.length === 0 ? undefined : refusalFrom(stale.map(b => b.request.response));
1013
1182
  }
1014
- /**
1015
- * The one place a commit request to a coordinator is built — shared by {@link commitInOneRound}
1016
- * and {@link commitBlocks}. `blockDigests` arrives as the action's FULL declaration map and is
1017
- * narrowed to `blockIds` here, at send time, never up front: each request becomes its own cluster
1018
- * record, so shipping the whole map would make one cohort sign for blocks it is not responsible
1019
- * for; and `processBatches` re-batches failed blocks onto different coordinators, so only a
1020
- * send-time subset stays correct across retries.
1021
- */
1022
- sendCommit(peerId, blockIds, { actionId, rev, tailId, blockDigests }, expiration) {
1023
- return this.getRepo(peerId).commit({ actionId, blockIds, rev, tailId, ...digestsFor(blockDigests, blockIds) }, { expiration, dialTimeoutMs: this.dialTimeoutMs });
1183
+ /** Sends `request`'s commit of `blockIds` to `peerId` — shared by {@link commitInOneRound} and {@link commitBlocks}. */
1184
+ sendCommit(peerId, blockIds, request, expiration) {
1185
+ return this.getRepo(peerId).commit(repoCommitRequest(blockIds, request), { expiration, dialTimeoutMs: this.dialTimeoutMs });
1024
1186
  }
1025
1187
  /** Attempts to commit a set of blocks, and handles failures and errors. */
1026
1188
  async commitBlocks(request) {
@@ -1245,7 +1407,7 @@ export class NetworkTransactor {
1245
1407
  catch (e) {
1246
1408
  error = asError(e);
1247
1409
  }
1248
- return { batches, discharged: dischargedBlocks(batches), error };
1410
+ return { batches, discharged: respondedBlocks(batches), error };
1249
1411
  }
1250
1412
  /**
1251
1413
  * One re-send of a cancel {@link dischargeCancel} gave up on, for {@link owedCancels}: a single
@@ -1294,18 +1456,19 @@ function bestCoveringPeer(peerBlocks, uncovered, localPeerId) {
1294
1456
  return best;
1295
1457
  }
1296
1458
  /**
1297
- * The block ids some batch in the tree got an ANSWER for. A cancel batch that errored, or never
1298
- * responded, discharged nothing — its blocks' pending records are still standing. Batch payloads
1299
- * are block-id lists (built with {@link mergeBlocks}), including the retry batches
1300
- * `processBatches` re-homes, so the union across the whole tree is the discharged set.
1459
+ * The block ids some batch in the tree got an ANSWER for, whatever the answer said. A cancel batch
1460
+ * that errored, or never responded, discharged nothing — its blocks' pending records are still
1461
+ * standing — so for a cancel this is the discharged set. For a read it separates a block no
1462
+ * coordinator answered from one a coordinator answered without. Batch payloads are block-id lists,
1463
+ * including the retry batches `processBatches` re-homes, so the union across the whole tree counts.
1301
1464
  */
1302
- function dischargedBlocks(batches) {
1303
- const discharged = new Set();
1465
+ function respondedBlocks(batches) {
1466
+ const responded = new Set();
1304
1467
  for (const b of allBatches(batches, bb => bb.request?.isResponse === true)) {
1305
1468
  for (const bid of b.payload)
1306
- discharged.add(bid);
1469
+ responded.add(bid);
1307
1470
  }
1308
- return discharged;
1471
+ return responded;
1309
1472
  }
1310
1473
  /**
1311
1474
  * The durability report off every commit batch in the tree that answered `success: true` — the
@@ -1322,9 +1485,16 @@ function confirmedDurabilities(batches) {
1322
1485
  * {@link NetworkTransactor.pend} and the commit paths use, since the action-level answer is rebuilt
1323
1486
  * from per-batch ones rather than forwarded, and anything not carried here is lost.
1324
1487
  *
1325
- * - An **expiry** anywhere ({@link isExpiryFailure}) is the answer, verbatim — the first one. No
1326
- * retry can succeed while that cohort's clocks disagree with the writer's, so a conflict beside it
1327
- * must not make the write look retryable, and its numbers must reach the writer whole.
1488
+ * - A **validity rejection** anywhere ({@link isRejectedFailure}) is the answer, verbatim — the first
1489
+ * one. Members judged the content, which no retry changes. Above an expiry for the reason a cohort
1490
+ * that judged the content outranks clock votes inside one record: reporting the verdict as a clock
1491
+ * problem would invite a retry the verdict already refuses.
1492
+ * - Otherwise an **expiry** anywhere ({@link isExpiryFailure}) is the answer, verbatim — the first
1493
+ * one. No retry can succeed while that cohort's clocks disagree with the writer's, so a conflict
1494
+ * beside it must not make the write look retryable, and its numbers must reach the writer whole.
1495
+ * - Otherwise a **promise shortfall** anywhere ({@link isShortfallFailure}) is the answer, verbatim —
1496
+ * the first one, for the same reason: no retry can succeed while that cohort's members are silent.
1497
+ * Below an expiry because a shortfall clears when the members come back, and an expiry does not.
1328
1498
  * - Otherwise a {@link StaleFailure}: `reason` is the first one any response gave (the only diagnostic
1329
1499
  * that survives an exhausted retry budget and the coordinator's error text — a refusal whose reason
1330
1500
  * is `commit-not-durable` must not read as "stale commit", a rival's win); `staleAt` is the highest
@@ -1341,9 +1511,9 @@ function confirmedDurabilities(batches) {
1341
1511
  * or if mixed-outcome writes show up as wasted retry latency in practice.
1342
1512
  */
1343
1513
  function refusalFrom(responses) {
1344
- const expired = responses.find(isExpiryFailure);
1345
- if (expired !== undefined) {
1346
- return expired;
1514
+ const unretryable = responses.find(isRejectedFailure) ?? responses.find(isExpiryFailure) ?? responses.find(isShortfallFailure);
1515
+ if (unretryable !== undefined) {
1516
+ return unretryable;
1347
1517
  }
1348
1518
  const staleAt = highestStaleAt(responses.map(r => r.staleAt));
1349
1519
  const reason = responses.map(r => r.reason).find(r => r !== undefined);
@@ -1355,6 +1525,28 @@ function refusalFrom(responses) {
1355
1525
  success: false
1356
1526
  };
1357
1527
  }
1528
+ /**
1529
+ * The one place a commit request to a coordinator is built, for `blockIds` of `request`'s action —
1530
+ * every commit {@link NetworkTransactor} sends, batched or not. `blockDigests` arrives as the action's
1531
+ * FULL declaration map and is narrowed to `blockIds` here, at send time, never up front: each request
1532
+ * becomes its own cluster record, or its own operation of one, so shipping the whole map would make a
1533
+ * cohort sign for blocks the request is not committing; and `processBatches` re-batches failed blocks
1534
+ * onto different coordinators, so only a send-time subset stays correct across retries.
1535
+ */
1536
+ function repoCommitRequest(blockIds, { actionId, rev, tailId, blockDigests, refuseSolo }) {
1537
+ return { actionId, blockIds, rev, tailId, ...digestsFor(blockDigests, blockIds), ...refuseSoloField(refuseSolo) };
1538
+ }
1539
+ /** `request`'s commit of `blockIds` alone, for {@link NetworkTransactor}'s two-step path to hand to its
1540
+ * batching: everything the write carries, with its declarations still action-wide — every send goes
1541
+ * through {@link repoCommitRequest}, which narrows them to the blocks that send commits. */
1542
+ function commitOf(request, blockIds) {
1543
+ return { blockIds, actionId: request.actionId, rev: request.rev, tailId: request.tailId, blockDigests: request.blockDigests,
1544
+ ...refuseSoloField(request.refuseSolo) };
1545
+ }
1546
+ /** `request`'s blocks with its log tail first, each once — the order a coordinator commits them in. */
1547
+ function tailFirst(request) {
1548
+ return [request.tailId, ...new Set(request.blockIds)].filter((blockId, i) => i === 0 || blockId !== request.tailId);
1549
+ }
1358
1550
  /** The entries of `all` whose ids appear in `batchBlockIds` — the per-batch narrowing both
1359
1551
  * per-block declarations share ({@link digestsFor}, {@link baseRevsFor}). */
1360
1552
  function subsetOf(all, batchBlockIds) {
@@ -1386,7 +1578,9 @@ function baseRevsFor(all, batchBlockIds) {
1386
1578
  *
1387
1579
  * `soleReservation` survives only on a batch carrying every block of the action: a pend split across
1388
1580
  * coordinators — by `consolidateCoordinators`, or by `processBatches` re-batching a failed batch — is
1389
- * several reservations, which the field must never claim to be. Decided per send, like the bases. */
1581
+ * several reservations, which the field must never claim to be. Decided per send, like the bases.
1582
+ * Every other field goes on every batch as given — `refuseSolo` included, whose loss on one batch would
1583
+ * let that coordinator's share be written by a lone node the write asked not to be written by. */
1390
1584
  function pendRequestForBatch(action, payload) {
1391
1585
  const { baseRevs, soleReservation, ...rest } = action;
1392
1586
  const batchBlockIds = blockIdsForTransforms(payload);