@optimystic/db-core 1.19.0 → 1.20.1

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 (171) hide show
  1. package/dist/src/cluster/structs.d.ts +41 -8
  2. package/dist/src/cluster/structs.d.ts.map +1 -1
  3. package/dist/src/cluster/structs.js +18 -7
  4. package/dist/src/cluster/structs.js.map +1 -1
  5. package/dist/src/collection/action.d.ts +29 -0
  6. package/dist/src/collection/action.d.ts.map +1 -1
  7. package/dist/src/collection/action.js +6 -0
  8. package/dist/src/collection/action.js.map +1 -1
  9. package/dist/src/collection/collection.d.ts +533 -120
  10. package/dist/src/collection/collection.d.ts.map +1 -1
  11. package/dist/src/collection/collection.js +974 -500
  12. package/dist/src/collection/collection.js.map +1 -1
  13. package/dist/src/collection/head-commit.d.ts +110 -0
  14. package/dist/src/collection/head-commit.d.ts.map +1 -0
  15. package/dist/src/collection/head-commit.js +65 -0
  16. package/dist/src/collection/head-commit.js.map +1 -0
  17. package/dist/src/collection/index.d.ts +2 -0
  18. package/dist/src/collection/index.d.ts.map +1 -1
  19. package/dist/src/collection/index.js +2 -0
  20. package/dist/src/collection/index.js.map +1 -1
  21. package/dist/src/collection/segments.d.ts +77 -0
  22. package/dist/src/collection/segments.d.ts.map +1 -0
  23. package/dist/src/collection/segments.js +110 -0
  24. package/dist/src/collection/segments.js.map +1 -0
  25. package/dist/src/collection/struct.d.ts +156 -1
  26. package/dist/src/collection/struct.d.ts.map +1 -1
  27. package/dist/src/collection/struct.js +70 -0
  28. package/dist/src/collection/struct.js.map +1 -1
  29. package/dist/src/collection/write-attempts.d.ts +245 -0
  30. package/dist/src/collection/write-attempts.d.ts.map +1 -0
  31. package/dist/src/collection/write-attempts.js +439 -0
  32. package/dist/src/collection/write-attempts.js.map +1 -0
  33. package/dist/src/collections/tree/struct.d.ts +100 -17
  34. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  35. package/dist/src/collections/tree/struct.js +38 -7
  36. package/dist/src/collections/tree/struct.js.map +1 -1
  37. package/dist/src/collections/tree/tree.d.ts +17 -5
  38. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  39. package/dist/src/collections/tree/tree.js +112 -26
  40. package/dist/src/collections/tree/tree.js.map +1 -1
  41. package/dist/src/index.d.ts +2 -0
  42. package/dist/src/index.d.ts.map +1 -1
  43. package/dist/src/index.js +2 -0
  44. package/dist/src/index.js.map +1 -1
  45. package/dist/src/network/i-repo.d.ts +3 -0
  46. package/dist/src/network/i-repo.d.ts.map +1 -1
  47. package/dist/src/network/index.d.ts +3 -0
  48. package/dist/src/network/index.d.ts.map +1 -1
  49. package/dist/src/network/index.js +3 -0
  50. package/dist/src/network/index.js.map +1 -1
  51. package/dist/src/network/promise-shortfall-error.d.ts +40 -0
  52. package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
  53. package/dist/src/network/promise-shortfall-error.js +67 -0
  54. package/dist/src/network/promise-shortfall-error.js.map +1 -0
  55. package/dist/src/network/refuse-solo.d.ts +8 -0
  56. package/dist/src/network/refuse-solo.d.ts.map +1 -0
  57. package/dist/src/network/refuse-solo.js +8 -0
  58. package/dist/src/network/refuse-solo.js.map +1 -0
  59. package/dist/src/network/stale-failure.d.ts +20 -3
  60. package/dist/src/network/stale-failure.d.ts.map +1 -1
  61. package/dist/src/network/stale-failure.js +24 -3
  62. package/dist/src/network/stale-failure.js.map +1 -1
  63. package/dist/src/network/struct.d.ts +148 -2
  64. package/dist/src/network/struct.d.ts.map +1 -1
  65. package/dist/src/network/struct.js.map +1 -1
  66. package/dist/src/network/validity-rejected-error.d.ts +28 -0
  67. package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
  68. package/dist/src/network/validity-rejected-error.js +51 -0
  69. package/dist/src/network/validity-rejected-error.js.map +1 -0
  70. package/dist/src/offline/entry.d.ts +72 -0
  71. package/dist/src/offline/entry.d.ts.map +1 -0
  72. package/dist/src/offline/entry.js +73 -0
  73. package/dist/src/offline/entry.js.map +1 -0
  74. package/dist/src/offline/index.d.ts +5 -0
  75. package/dist/src/offline/index.d.ts.map +1 -0
  76. package/dist/src/offline/index.js +5 -0
  77. package/dist/src/offline/index.js.map +1 -0
  78. package/dist/src/offline/journal.d.ts +61 -0
  79. package/dist/src/offline/journal.d.ts.map +1 -0
  80. package/dist/src/offline/journal.js +2 -0
  81. package/dist/src/offline/journal.js.map +1 -0
  82. package/dist/src/offline/queue.d.ts +484 -0
  83. package/dist/src/offline/queue.d.ts.map +1 -0
  84. package/dist/src/offline/queue.js +1236 -0
  85. package/dist/src/offline/queue.js.map +1 -0
  86. package/dist/src/offline/reachability.d.ts +25 -0
  87. package/dist/src/offline/reachability.d.ts.map +1 -0
  88. package/dist/src/offline/reachability.js +13 -0
  89. package/dist/src/offline/reachability.js.map +1 -0
  90. package/dist/src/offline/status.d.ts +148 -0
  91. package/dist/src/offline/status.d.ts.map +1 -0
  92. package/dist/src/offline/status.js +63 -0
  93. package/dist/src/offline/status.js.map +1 -0
  94. package/dist/src/offline/wake.d.ts +30 -0
  95. package/dist/src/offline/wake.d.ts.map +1 -0
  96. package/dist/src/offline/wake.js +68 -0
  97. package/dist/src/offline/wake.js.map +1 -0
  98. package/dist/src/testing/test-transactor.d.ts +29 -0
  99. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  100. package/dist/src/testing/test-transactor.js +50 -0
  101. package/dist/src/testing/test-transactor.js.map +1 -1
  102. package/dist/src/transaction/commit-failure-class.d.ts +103 -0
  103. package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
  104. package/dist/src/transaction/commit-failure-class.js +96 -0
  105. package/dist/src/transaction/commit-failure-class.js.map +1 -0
  106. package/dist/src/transaction/coordinator.d.ts +165 -41
  107. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  108. package/dist/src/transaction/coordinator.js +605 -300
  109. package/dist/src/transaction/coordinator.js.map +1 -1
  110. package/dist/src/transaction/entry-commit.d.ts +139 -0
  111. package/dist/src/transaction/entry-commit.d.ts.map +1 -0
  112. package/dist/src/transaction/entry-commit.js +199 -0
  113. package/dist/src/transaction/entry-commit.js.map +1 -0
  114. package/dist/src/transaction/index.d.ts +4 -1
  115. package/dist/src/transaction/index.d.ts.map +1 -1
  116. package/dist/src/transaction/index.js +1 -0
  117. package/dist/src/transaction/index.js.map +1 -1
  118. package/dist/src/transaction/transaction.d.ts +20 -0
  119. package/dist/src/transaction/transaction.d.ts.map +1 -1
  120. package/dist/src/transaction/validator.d.ts +7 -0
  121. package/dist/src/transaction/validator.d.ts.map +1 -1
  122. package/dist/src/transaction/validator.js +21 -12
  123. package/dist/src/transaction/validator.js.map +1 -1
  124. package/dist/src/transactor/network-transactor.d.ts +1 -0
  125. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  126. package/dist/src/transactor/network-transactor.js +61 -28
  127. package/dist/src/transactor/network-transactor.js.map +1 -1
  128. package/dist/src/transactor/transactor-source.d.ts +22 -11
  129. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  130. package/dist/src/transactor/transactor-source.js +9 -13
  131. package/dist/src/transactor/transactor-source.js.map +1 -1
  132. package/dist/src/utility/visit-every.d.ts +14 -0
  133. package/dist/src/utility/visit-every.d.ts.map +1 -0
  134. package/dist/src/utility/visit-every.js +27 -0
  135. package/dist/src/utility/visit-every.js.map +1 -0
  136. package/package.json +1 -1
  137. package/src/cluster/structs.ts +42 -7
  138. package/src/collection/action.ts +34 -0
  139. package/src/collection/collection.ts +1048 -543
  140. package/src/collection/head-commit.ts +148 -0
  141. package/src/collection/index.ts +2 -0
  142. package/src/collection/segments.ts +149 -0
  143. package/src/collection/struct.ts +183 -1
  144. package/src/collection/write-attempts.ts +506 -0
  145. package/src/collections/tree/struct.ts +97 -17
  146. package/src/collections/tree/tree.ts +125 -29
  147. package/src/index.ts +2 -0
  148. package/src/network/i-repo.ts +3 -0
  149. package/src/network/index.ts +3 -0
  150. package/src/network/promise-shortfall-error.ts +69 -0
  151. package/src/network/refuse-solo.ts +7 -0
  152. package/src/network/stale-failure.ts +27 -4
  153. package/src/network/struct.ts +154 -2
  154. package/src/network/validity-rejected-error.ts +55 -0
  155. package/src/offline/entry.ts +127 -0
  156. package/src/offline/index.ts +4 -0
  157. package/src/offline/journal.ts +60 -0
  158. package/src/offline/queue.ts +1342 -0
  159. package/src/offline/reachability.ts +32 -0
  160. package/src/offline/status.ts +183 -0
  161. package/src/offline/wake.ts +67 -0
  162. package/src/testing/test-transactor.ts +53 -0
  163. package/src/transaction/commit-failure-class.ts +133 -0
  164. package/src/transaction/coordinator.ts +696 -349
  165. package/src/transaction/entry-commit.ts +285 -0
  166. package/src/transaction/index.ts +4 -0
  167. package/src/transaction/transaction.ts +21 -0
  168. package/src/transaction/validator.ts +22 -12
  169. package/src/transactor/network-transactor.ts +62 -28
  170. package/src/transactor/transactor-source.ts +29 -13
  171. package/src/utility/visit-every.ts +25 -0
@@ -2,6 +2,7 @@ import type { ITransactor, CollectionId, Transforms } from "../index.js";
2
2
  import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions, ReadDependency } from "./transaction.js";
3
3
  import type { Collection } from "../collection/collection.js";
4
4
  import type { SyncOptions } from "../collection/index.js";
5
+ import type { EntryCommit } from "./entry-commit.js";
5
6
  import { type TransactionDurability } from "./durability.js";
6
7
  /**
7
8
  * What a pend this coordinator sends carries for the receiving cluster members to re-check.
@@ -161,7 +162,9 @@ export declare class TransactionCoordinator {
161
162
  * unavailable transactor, unreachable cluster) also propagates without retry — including a pend
162
163
  * or commit the cohort refused because the transaction had expired by its members' clocks, which
163
164
  * surfaces as {@link TransactionExpiredError} (inside a partial commit's `reason` once a sibling
164
- * has landed).
165
+ * has landed), a pend too few of the cohort's members answered, which surfaces as
166
+ * {@link PromiseShortfallError}, and a pend the members that sank it judged invalid, which surfaces
167
+ * as {@link ValidityRejectedError}.
165
168
  *
166
169
  * A participant can also be SAVED between attempts: an attempt that reported a loss may still
167
170
  * have stored that participant's log tail, and the refresh before the next attempt then finishes
@@ -185,35 +188,73 @@ export declare class TransactionCoordinator {
185
188
  * committed half's on {@link CoordinatorPartialCommitError.durability}.
186
189
  */
187
190
  commit(transaction: Transaction, options?: SyncOptions): Promise<TransactionDurability | undefined>;
188
- /** The retry loop behind {@link commit}: every attempt, and the refresh between them. Records
189
- * what it learns in `cycle`; {@link commit} owns turning a failure into the right report. On
190
- * success, reports every participant the cycle saved together with what the final attempt
191
- * committed (see {@link commit}'s return). */
191
+ /**
192
+ * The retry loop behind {@link commit} and {@link commitEntry}: every attempt, and the refresh
193
+ * rounds between them, over the `driver`'s steps and the budget `options` sets
194
+ * ({@link RetryBudget}). Records what it learns in `cycle`; the caller owns turning a failure into
195
+ * the right report. On success, reports every participant the cycle saved together with what the
196
+ * final attempt committed (see {@link commit}'s return).
197
+ *
198
+ * Only a CLEAN stale loss is retried. A partial landing on a hard failure, an expired transaction,
199
+ * an unavailable transactor, etc. all propagate unchanged. Once a refresh round has saved a
200
+ * participant and the driver has nothing left to commit, the write is finished and the loop
201
+ * returns at once rather than going round again, where an abort, the deadline or an expiry check
202
+ * could still report failure for a write that is entirely saved.
203
+ */
192
204
  private commitAttempts;
193
205
  /**
194
- * Refresh every registered collection between attempts, recording in `cycle.saved` each one
195
- * whose refresh finished this transaction's own log entry (see {@link Collection.refreshInFlight}),
196
- * with who holds it — `undefined` when the refresh could not say, which still records it as saved.
206
+ * Back off, refresh, and keep refreshing while a round reports that a participant's half-landed
207
+ * write could not be finished YET. Re-reading fresh state before re-attempting is what lets the
208
+ * next attempt pend against current revisions (mirrors how Collection.sync calls updateInternal()
209
+ * before retrying), and a participant whose log tail landed despite the reported loss finds its
210
+ * own entry here and FINISHES that action before consuming it (Collection.completeOwnEntry, from
211
+ * the attempt the previous one retained).
212
+ *
213
+ * When finishing is refused for a cause that can clear, the refresh — not the commit — is what
214
+ * gets retried: the participant's log entry is already durable, and once a refresh adopts a newer
215
+ * revision the next attempt appends a SECOND entry under the write's id. (At an unchanged
216
+ * revision the re-append is byte-identical — see Collection.logAppendBlockIds — so what is at
217
+ * stake is the duplicate entry, not two versions of one tail block.) Each such round counts
218
+ * against the same budget as a stale loss; a permanent refusal (a rival holds the revision)
219
+ * escapes as the named TornActionError at once. Re-refreshing a collection an earlier round
220
+ * already refreshed is a no-op. The round that would spend the last of the budget is told so,
221
+ * which makes each participant SETTLE a half-landed write rather than ask for another round: the
222
+ * error thrown then says whether the write can still land (`final`). A deadline cannot be
223
+ * foreseen the same way; a write given up on it stays unsettled.
224
+ */
225
+ private refreshRounds;
226
+ /** Every registered collection as a refresh-round participant of a transaction's commit.
227
+ *
228
+ * NOTE: EVERY registered collection, not only the participants of the transaction. Not free: a
229
+ * non-participant's refresh throws CollectionHeaderVanishedError if its header momentarily reads
230
+ * absent while it holds a committed revision, aborting this retry. And because a throw does not
231
+ * stop the round, an unreachable cluster costs one failed read per registered collection rather
232
+ * than one. The registered set is small today; if that (or retry latency) ever bites, narrow this
233
+ * to the transaction's participants. (The per-entry commit already refreshes its participants
234
+ * only, through their handles — see `EntryParticipants.refreshers`.) */
235
+ private registeredRefreshers;
236
+ /**
237
+ * One refresh round between attempts: refresh every participant, recording in `cycle.saved` each
238
+ * one whose refresh finished the write's own log entry (see {@link Collection.refreshInFlight}),
239
+ * with who holds it — `undefined` when the refresh could not say, which still records it as
240
+ * saved — and telling the participant so (`RefreshParticipant.saved`).
197
241
  *
198
- * Visits EVERY collection even after one throws. Stopping at the first throw would leave a
199
- * participant later in the map unfinished whenever an earlier one is torn — its log tail stored
242
+ * Visits EVERY participant even after one throws. Stopping at the first throw would leave a
243
+ * participant later in the round unfinished whenever an earlier one is torn — its log tail stored
200
244
  * and its other blocks never landed, the silent loss `Collection.completeOwnEntry` exists to
201
245
  * prevent — and unreported. Each refresh is independent (its own latch, its own instance state),
202
246
  * so one failing says nothing about the next.
203
247
  *
204
- * NOTE: refreshes EVERY registered collection, not only the participants of this transaction.
205
- * Not free: a non-participant's refresh throws CollectionHeaderVanishedError if its header
206
- * momentarily reads absent while it holds a committed revision, aborting this retry. And because
207
- * a throw no longer stops the round, an unreachable cluster costs one failed read per registered
208
- * collection rather than one. The registered set is small today; if that (or retry latency) ever
209
- * bites, narrow this to the transaction's participants.
248
+ * NOTE: no `tailFloor` is passed to any refresh — the coordinator's loop loses the confirmed
249
+ * revision before the round runs (backlog `debt-multi-collection-retry-cannot-see-the-taken-revision`);
250
+ * the per-entry commit has the same gap, through the same round.
210
251
  *
211
252
  * @param lastChance - this is the round that spends the last of the retry budget, so a
212
253
  * participant whose half-landed write is refused again settles it (`Collection.completeOwnEntry`)
213
254
  * rather than asking for a round it will not get; the error returned then carries `final`.
214
255
  * @returns the first `completion-refused` {@link TornActionError} when that is the only way any
215
256
  * refresh failed — the round is worth retrying; `undefined` when every refresh succeeded.
216
- * @throws the first other error, once every collection has been visited.
257
+ * @throws the first other error, once every participant has been visited.
217
258
  */
218
259
  private refreshBetweenAttempts;
219
260
  /** Every registered collection with something to push — the participants an attempt starting
@@ -243,8 +284,9 @@ export declare class TransactionCoordinator {
243
284
  *
244
285
  * Local state already matches that report: a saved participant was consumed by its refresh, and
245
286
  * an unsaved one kept its staged actions (a failed finish throws before touching anything, and
246
- * commitOnceLatched restores every participant it did not commit). The stamp is released, as on
247
- * the existing partial path, because the transaction can no longer be cleanly rolled back.
287
+ * commitOnceLatched restores every participant it did not commit; the per-entry commit leaves a
288
+ * refused participant's segment sealed and first). Releasing a transaction's stamp on the partial
289
+ * report is {@link commit}'s, which reads the class of what this returns.
248
290
  */
249
291
  private reportSaved;
250
292
  /**
@@ -289,6 +331,76 @@ export declare class TransactionCoordinator {
289
331
  * @returns on success, every participant with who holds it (see {@link commitOnce}).
290
332
  */
291
333
  private commitOnceLatched;
334
+ /**
335
+ * Commit one queued entry's slice of every collection it wrote, as ONE all-or-nothing round
336
+ * (docs/offline-sync.md §One entry, one network transaction): for each collection in
337
+ * `entry.collectionIds`, exactly its HEAD sealed segment, which must be `entry.entryId`, as one
338
+ * log entry under `entry.actionId` and `entry.timestamp`. The offline-sync queue is the caller,
339
+ * for an entry that wrote more than one collection; an entry that wrote one commits through
340
+ * `Collection.commitHead`, whose steps this drives in lock-step across the participants
341
+ * (`HeadCommitHandle` in collection/head-commit.ts): open a handle per participant, in sorted
342
+ * collection-id order; the opening refresh, which finishes and consumes an entry an earlier
343
+ * `commitEntry` under this action id left in a participant's log; then per attempt, build every
344
+ * participant's attempt on its head tracker, record them through `entry.recordAttempt`, release
345
+ * every latch, run the phases ({@link coordinateAttempts}: pend every participant, then commit),
346
+ * retake every latch, and apply the outcome — fold then replay on a commit, the recorded refusal
347
+ * re-checked and the attempt retained on a refusal — with the retry loop of {@link commit}
348
+ * ({@link commitAttempts}) between attempts.
349
+ *
350
+ * What the slice deliberately does NOT do, where {@link commit} does: no pre-commit snapshots or
351
+ * `restorePending` (an attempt never touches the live tracker; a failed one leaves it as it was
352
+ * by construction); no `getPendingActions`, `clearPendingActions` or `tracker.reset` (the head
353
+ * segment is dropped and folded through the handle); no stamp (the one-open-stamp rule is about
354
+ * staged state, which a slice does not stage — a slice may run while a stamp is open on another
355
+ * coordinator over the same collections, which is the plugin's open SQL transaction; the
356
+ * collection latch is what serialises them); no expiry check (an entry has no stamp to expire).
357
+ * Its refresh rounds refresh the entry's participants only, through their handles, never the
358
+ * coordinator's whole map.
359
+ *
360
+ * Requires a coordinator built with `pendValidation: 'none'`, and throws before touching
361
+ * anything otherwise: a queued entry has no statements for a member to re-execute, and the pend
362
+ * carries bare transforms exactly as the plugin's `commitBatchLegacy` sends them. The queue builds
363
+ * one coordinator per submission over exactly the entry's collections; running `commitEntry`
364
+ * while a {@link commit} of the same coordinator is open is not a supported combination, and
365
+ * nothing but the collection latches guards it.
366
+ *
367
+ * @returns who holds each collection the entry wrote, across every attempt, as {@link commit}
368
+ * answers it — a participant the refresh saved included, listed with an `undefined` class (and
369
+ * `overall` then absent) when the refresh established it was saved under `entry.actionId` without
370
+ * re-sending (the status-read fallback of `Collection.completeOwnEntry`, where
371
+ * `Collection.commitHead` answers `undefined`). Never `undefined`: a slice always writes at least
372
+ * one collection, so the "nothing was written" answer `commit` has is unrepresentable here.
373
+ * @throws what {@link commit} throws — a {@link CoordinatorStaleLossError} once the retry budget
374
+ * is spent, a {@link CoordinatorPartialCommitError} for a partial landing (every participant it
375
+ * names as committed has had its head consumed; every failed one's head is still sealed and
376
+ * first, its attempt retained), the named refusals, `TornActionError` out of a refresh — plus the
377
+ * recorded refusal of any participant's head (an `ActionRefusedError`), thrown with every other
378
+ * participant's segment intact since nothing was sent or the send was refused, and
379
+ * `SealedSegmentsError` from `Collection.openHeadCommit`'s preconditions, before anything is done.
380
+ */
381
+ commitEntry(entry: EntryCommit, options?: SyncOptions): Promise<TransactionDurability>;
382
+ /**
383
+ * One attempt of {@link commitEntry}, under the latches `participants` hold: every remaining
384
+ * participant's attempt is built (`HeadCommitHandle.stage`, which re-checks the head's recorded
385
+ * refusal and throws it), recorded through the write-ahead hook — a throw there aborts with
386
+ * nothing sent and nothing changed — then sent as one round with every latch released, and the
387
+ * outcome applied under the retaken latches:
388
+ *
389
+ * - a commit: fold every participant in one await-free pass, then replay each
390
+ * (`EntryParticipants.landed`); the attempt's durability per collection is the answer;
391
+ * - a partial landing: the committed participants folded, replayed and recorded in `cycle.saved`
392
+ * — before their local treatment, so a throw in it is still reported over the right committed
393
+ * set — and the rest refused (their recorded refusal re-checked, their attempt retained); then
394
+ * {@link CoordinatorStaleLossError} when every refusal was a returned one, so the retry loop
395
+ * finishes the refused participants forward over what is left (as `commitOnceLatched`'s
396
+ * partial-retry branch does), or {@link CoordinatorPartialCommitError} on a hard failure;
397
+ * - nothing committed: every participant refused, then the failure thrown by its class
398
+ * ({@link cleanFailureError}).
399
+ *
400
+ * The refusal re-check runs after the committed participants are folded, never before: a
401
+ * sibling's recorded refusal must not keep a durable commit from being applied locally.
402
+ */
403
+ private commitEntryOnce;
292
404
  /**
293
405
  * Rollback a transaction (undo only the given stampId's applied actions).
294
406
  *
@@ -346,13 +458,16 @@ export declare class TransactionCoordinator {
346
458
  /**
347
459
  * Apply actions to a collection.
348
460
  *
349
- * This runs the action handlers, writes to the log, and collects transforms.
461
+ * This runs the action handlers, writes to the log, and collects transforms. The log entry is
462
+ * written under `context`: its action id, its timestamp and its reads.
350
463
  */
351
464
  private applyActionsToCollection;
352
465
  /**
353
- * Coordinate a transaction across multiple collections.
466
+ * Coordinate a transaction's attempt across multiple collections: describe what each collection's
467
+ * staged transforms send ({@link declareTouchedBlocks}), then run the phases
468
+ * ({@link coordinateAttempts}).
354
469
  *
355
- * @param transaction - The transaction to coordinate
470
+ * @param context - The write being coordinated (its action id and aged priority)
356
471
  * @param validation - What every pend carries for members to re-check, or undefined for an
357
472
  * unvalidated pend (see {@link pendValidationFor})
358
473
  * @param collectionTransforms - Map of collectionId to its transforms
@@ -362,6 +477,13 @@ export declare class TransactionCoordinator {
362
477
  * and the local record name the same number.
363
478
  */
364
479
  private coordinateTransaction;
480
+ /**
481
+ * The distributed phases of one attempt — GATHER, PEND, COMMIT, and the CANCEL of what a failed
482
+ * commit left pending — over every collection's share of it, already described
483
+ * (`CollectionAttempt`). Run by {@link coordinateTransaction} for a transaction's attempt and by
484
+ * {@link commitEntryOnce} for a queued entry's, whose attempts the head commit described.
485
+ */
486
+ private coordinateAttempts;
365
487
  /**
366
488
  * GATHER phase: Collect nominees from critical clusters.
367
489
  *
@@ -372,17 +494,20 @@ export declare class TransactionCoordinator {
372
494
  */
373
495
  private gatherPhase;
374
496
  /**
375
- * One local materialization of every block each collection's transforms touch
497
+ * What each collection's staged transforms send, described from its live tracker after the log
498
+ * append: one local materialization of every block the transforms touch
376
499
  * ({@link describeTouchedBlocks}), taken before anything is sent. A block the write would leave
377
500
  * over `MAX_BLOCK_BYTES` refuses the transaction here, as a pend-phase failure carrying the
378
501
  * {@link BlockTooLargeError} — the same shape as a pend too large to send, so `commit` throws it by
379
502
  * name and `execute` reports it as a failure. Otherwise each collection's digests are kept as its
380
- * commit's declaration ({@link commitRequestFor}), so the commit does not materialize again.
503
+ * commit's declaration ({@link commitRequestFor}), so the commit does not materialize again, and
504
+ * the base each update-only block's operations were computed against is read from the same
505
+ * tracker's pins for its pend (`PendRequest.baseRevs`; storage keeps it with the pending record so
506
+ * the record is never applied to a different version of the block).
381
507
  *
382
508
  * Purely local: each collection's tracker holds this transaction's staged transforms until the commit
383
- * succeeds, under the instance latch the commit span holds, and the pend names its bases from the
384
- * same pins ({@link pendRequestFor}). A collection missing from the registry is skipped, for the pend
385
- * to report as it always has.
509
+ * succeeds, under the instance latch the commit span holds. A collection missing from the registry
510
+ * is a defect here: {@link applyActionsToCollection} has already refused it.
386
511
  */
387
512
  private declareTouchedBlocks;
388
513
  /**
@@ -391,14 +516,14 @@ export declare class TransactionCoordinator {
391
516
  * Two or more collections go as ONE request when the transactor can send them so
392
517
  * ({@link pendTogether}); otherwise, and for one collection, each collection is pended on its own.
393
518
  *
394
- * @param transaction - The transaction being pended (its id names the action; its aged
395
- * priority rides on an unvalidated pend)
519
+ * @param context - The write being pended (its action id names the action; its aged priority
520
+ * rides on an unvalidated pend)
396
521
  * @param validation - What every pend carries for members to re-check, or undefined for an
397
522
  * unvalidated pend (see {@link pendValidationFor})
398
- * @param collectionTransforms - Map of collectionId to its transforms
399
- * @param pendedRevs - Per collection, the revision its log entry was stamped with — the pend
400
- * request repeats it verbatim rather than recomputing from the collection (a recompute after
401
- * the append could name a different number if the collection refreshed in between).
523
+ * @param attempts - Per collection, its share of the attempt: its transforms, and the revision
524
+ * its log entry was stamped with — the pend request repeats it verbatim rather than recomputing
525
+ * from the collection (a recompute after the append could name a different number if the
526
+ * collection refreshed in between).
402
527
  * @param superclusterNominees - Nominees for multi-collection consensus (null for single-collection)
403
528
  */
404
529
  private pendPhase;
@@ -420,8 +545,7 @@ export declare class TransactionCoordinator {
420
545
  * pends each collection on its own with requests rebuilt WITHOUT the mark. The marked requests are
421
546
  * never re-sent one by one: each carries every block of its collection, so `NetworkTransactor.pend`
422
547
  * would keep the mark, and one collection's late refusal could then surface after a sibling's commit
423
- * landed — the tear the mark exists to prevent. Also `undefined` when a collection is missing from
424
- * the registry, so that the per-collection path reports it as it always has.
548
+ * landed — the tear the mark exists to prevent.
425
549
  */
426
550
  private pendTogether;
427
551
  /**
@@ -431,8 +555,8 @@ export declare class TransactionCoordinator {
431
555
  */
432
556
  private pendCollection;
433
557
  /**
434
- * The pend request for one collection's transforms — the one place a pend request is built, whether it
435
- * goes on its own ({@link pendCollection}) or with its siblings ({@link pendTogether}).
558
+ * The pend request for one collection's share of an attempt — the one place a pend request is built,
559
+ * whether it goes on its own ({@link pendCollection}) or with its siblings ({@link pendTogether}).
436
560
  */
437
561
  private pendRequestFor;
438
562
  /**
@@ -454,10 +578,10 @@ export declare class TransactionCoordinator {
454
578
  * land (`Collection.completeOwnEntry`) — the path a refused one-collection commit already takes.
455
579
  *
456
580
  * `undefined` when they could not go as one, when the request threw, or when a collection's request
457
- * could not be built (missing from the registry, or no log tail among its pended blocks):
458
- * {@link commitPhase} then commits each collection on its own, which re-sends everything and reports
459
- * a request it cannot build as it always has. The batch is never retried here: a returned refusal
460
- * cannot be won by the identical request, and a throw is the per-collection path's to retry.
581
+ * could not be built (no log tail among its pended blocks): {@link commitPhase} then commits each
582
+ * collection on its own, which re-sends everything and reports a request it cannot build as it
583
+ * always has. The batch is never retried here: a returned refusal cannot be won by the identical
584
+ * request, and a throw is the per-collection path's to retry.
461
585
  */
462
586
  private commitTogether;
463
587
  /** Commits each collection on its own, concurrently ({@link commitCollection}), one outcome per collection. */
@@ -1 +1 @@
1
- {"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/transaction/coordinator.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/transaction/coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAW,YAAY,EAAE,UAAU,EAAsH,MAAM,aAAa,CAAC;AAEtM,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAU5H,OAAO,KAAK,EAAE,UAAU,EAAqC,MAAM,6BAA6B,CAAC;AACjG,OAAO,KAAK,EAAiB,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAKzE,OAAO,KAAK,EAAE,WAAW,EAAoC,MAAM,mBAAmB,CAAC;AAMvF,OAAO,EAAqD,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAwWhH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,kBAAkB;IAClC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,qBAAa,sBAAsB;IA4CjC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW;IA5C7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2EAiCuE;IACvE,OAAO,CAAC,SAAS,CAEZ;IAEL;8BAC0B;IAC1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;gBAGlC,UAAU,EAAE,WAAW,EACvB,WAAW,EAAE,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,EAChE,OAAO,GAAE,kBAAuB;IAKjC;;;;;;;OAOG;YACW,iBAAiB;IAU/B;;;;;;;;;OASG;IACG,YAAY,CACjB,OAAO,EAAE,iBAAiB,EAAE,EAC5B,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAwBhB;;wCAEoC;IACpC,OAAO,CAAC,kBAAkB;IAO1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;;;;;;OASG;YACW,eAAe;IAiB7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACG,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC;IA+DzG;;;;;;;;;;;;OAYG;YACW,cAAc;IAiC5B;;;;;;;;;;;;;;;;;;;OAmBG;YACW,aAAa;IAW3B;;;;;;;;4EAQwE;IACxE,OAAO,CAAC,oBAAoB;IAO5B;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,sBAAsB;IA2BpC;;;;;;;;;6CASyC;IACzC,OAAO,CAAC,iBAAiB;IAUzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,WAAW;IAsBnB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;YACW,UAAU;IAgExB;;;;;;;;;;;;OAYG;YACW,iBAAiB;IAqN/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACG,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAiC5F;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,eAAe;IAiD7B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqC9C;;;;;;OAMG;IACH,aAAa,IAAI,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC;IAe9C;;;;;OAKG;IACH,eAAe,IAAI,IAAI;IAMvB;;OAEG;IACH,mBAAmB,IAAI,cAAc,EAAE;IAQvC;;OAEG;IACH,qBAAqB,IAAI,IAAI;IAM7B;;;;;;;;OAQG;IACG,OAAO,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;IAwT7F;;;;;OAKG;YACW,wBAAwB;IA4FtC;;;;;;;;;;;;;OAaG;YACW,qBAAqB;IAiBnC;;;;;OAKG;YACW,kBAAkB;IAuDhC;;;;;;;OAOG;YACW,WAAW;IAmCzB;;;;;;;;;;;;;;;OAeG;YACW,oBAAoB;IA0BlC;;;;;;;;;;;;;;;OAeG;YACW,SAAS;IA2DvB;;;;;;;;;;;;;;;;;;;OAmBG;YACW,YAAY;IAsB1B;;;;OAIG;YACW,cAAc;IAsB5B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAkCtB;;;;;;;;OAQG;YACW,WAAW;IAgEzB;;;;;;;;;;;;;OAaG;YACW,cAAc;IAyB5B,+GAA+G;YACjG,UAAU;IAgBxB;;;;;OAKG;YACW,gBAAgB;IAgC9B;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA6BxB;;;;;OAKG;YACW,WAAW;CAsBzB"}