@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
@@ -2,62 +2,21 @@ import { Log } from "../log/log.js";
2
2
  import { Atomic } from "../transform/atomic.js";
3
3
  import { Tracker } from "../transform/tracker.js";
4
4
  import { CacheSource } from "../transform/cache-source.js";
5
- import { computeBlockContentDigests, baseRevsField } from "../transform/digest.js";
6
- import { copyTransforms, isTransformsEmpty } from "../transform/helpers.js";
5
+ import { copyTransforms, emptyTransforms, isTransformsEmpty } from "../transform/helpers.js";
7
6
  import { TransactorSource, answeredBlock, servedRevision } from "../transactor/transactor-source.js";
8
7
  import { BlockFloors } from "../transactor/block-floors.js";
9
- import { mergeDurability, withBlockRevs } from "../network/durability.js";
10
- import { highestStaleAt, isExpiryFailure } from "../network/stale-failure.js";
11
- import { TransactionExpiredError } from "../network/transaction-expired-error.js";
12
- import { CollectionHeaderVanishedError, SyncRetryExhaustedError, SyncRevisionStalledError, TornActionError } from "./struct.js";
13
- import { actionIdAt } from "./action.js";
14
- import { clampPriority, SlotHoldAfterLosses } from "../transaction/transaction.js";
8
+ import { withBlockRevs } from "../network/durability.js";
9
+ import { ActionRefusedError, CollectionHeaderVanishedError, SealedSegmentsError, TornActionError } from "./struct.js";
10
+ import { SegmentList } from "./segments.js";
11
+ import { actionIdAt, addTallies, ZeroTally } from "./action.js";
12
+ import { AttemptCycle, resumedAttempt, retainedAttempt, stageAttempt } from "./write-attempts.js";
13
+ import { driveHeadCommit } from "./head-commit.js";
15
14
  import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
16
15
  import { randomBytes } from '@noble/hashes/utils.js';
17
16
  import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
18
17
  import { Latches } from "../utility/latches.js";
19
- import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
20
18
  import { createLogger } from "../logger.js";
21
19
  const log = createLogger('collection');
22
- /** Default base backoff (and historical fixed delay) between sync retries, in ms. */
23
- const PendingRetryDelayMs = 100;
24
- /** Default max consecutive no-progress stale-failure retries before {@link Collection.sync} gives up. */
25
- const DefaultMaxAttempts = 10;
26
- /** Default ceiling on a single exponential-backoff sleep, in ms. */
27
- const DefaultMaxBackoffMs = 5000;
28
- /** Default consecutive stalled refreshes — ones that moved this collection's revision NOWHERE
29
- * while a responder CONFIRMED a revision at or above the one being requested — before
30
- * {@link Collection.sync} gives up. Two, not one, so a single transiently-lagging read is absorbed.
31
- *
32
- * NOTE: two is a judgement call, not a measurement — nothing here counts how often a legitimate
33
- * loser reads a view that moves nowhere for two consecutive rounds. The check only strikes when the
34
- * refresh made NO progress at all, so a client merely catching up is already excluded; if a
35
- * spurious `SyncRevisionStalledError` ever shows up under real contention anyway, raise this. */
36
- const DefaultMaxStalledAttempts = 2;
37
- /**
38
- * The sleep before the refresh that follows a write's `failures`-th consecutive loss.
39
- *
40
- * The jittered backoff exists to separate a herd of writers that lost the SAME race, so they do not
41
- * re-collide on the next tick. A loss to a rival that had already committed (the refusal carried a
42
- * confirmed `staleAt`) is not a herd, and once this write has taken `SlotHoldAfterLosses` such losses
43
- * (`confirmedLosses`, counted over the whole write as a member counts its stale refusals of one
44
- * action) the members that refused it hold the next slot for it — so sleeping only spends that hold.
45
- * Both sides count the same refusals against the same constant, so the writer stops sleeping on the
46
- * loss after which a member holds, with nothing said over the wire. A loss the latest refusal did not
47
- * confirm (`latestConfirmed` false — a race against something still in flight) keeps the jitter.
48
- *
49
- * NOTE: against members that do not hold (an earlier release, `slotHoldWindowMs: 0`, or a member the
50
- * refused pends did not reach) this retries without sleeping and so spends the same attempt budget
51
- * sooner, at about twice one writer's pend rate (measured in the plan stage of
52
- * `slot-hold-for-an-aged-writer`). Accepted: the backoff bought that writer nothing either, it only
53
- * delayed the same give-up.
54
- */
55
- function retryBackoffMs(failures, confirmedLosses, latestConfirmed, config, rand) {
56
- if (latestConfirmed && confirmedLosses >= SlotHoldAfterLosses) {
57
- return 0;
58
- }
59
- return jitteredBackoffMs(failures - 1, config, rand);
60
- }
61
20
  export class Collection {
62
21
  id;
63
22
  transactor;
@@ -67,9 +26,23 @@ export class Collection {
67
26
  tracker;
68
27
  floors;
69
28
  filterConflict;
29
+ onSealedRefused;
70
30
  instanceTag;
71
- pending = [];
31
+ /** The staged actions: sealed segments, one per queued entry, ahead of the open segment the
32
+ * current transaction stages into (see {@link SegmentList}). While nothing is sealed this is
33
+ * exactly the one pending list it replaced, and every path behaves as it did then. */
34
+ segments = new SegmentList();
72
35
  latchId;
36
+ /** The transforms an INVENTED collection starts from — its header, its empty log block and (for
37
+ * a tree) its empty root, as {@link createOrOpen}'s create branch staged them. A replay resets
38
+ * the tracker to a copy of this, rather than to empty, for as long as no committed revision has
39
+ * been adopted: those blocks are then nowhere but the tracker, and resetting to empty would drop
40
+ * them and leave the collection unreadable (the hazard {@link mustReplay} and
41
+ * {@link snapshotPending} describe). Never cleared — it is read only while
42
+ * `source.actionContext` is undefined, and once a context is adopted the blocks are in storage
43
+ * and the empty reset is the right one. `undefined` for a collection opened over a committed
44
+ * header, which never replays from a baseline. */
45
+ inventedBaseline;
73
46
  /** The action id of a write currently in flight ON THIS INSTANCE'S BEHALF, or `undefined`
74
47
  * outside a write. Read by {@link updateInternal}: if the committed log now carries an entry
75
48
  * under this id, that action's LOG TAIL landed despite the failure answer that sent us back here
@@ -118,13 +91,40 @@ export class Collection {
118
91
  * Only the latest attempt is kept. An own entry can only be visible at the revision of an
119
92
  * attempt whose tail landed, and a later attempt at a DIFFERENT revision is only made after a
120
93
  * refresh adopted somebody else's entry at the earlier one — which is proof the earlier tail did
121
- * not land. {@link completeOwnEntry} still checks the revision and refuses on a mismatch. */
94
+ * not land. {@link completeOwnEntry} still checks the revision and refuses on a mismatch.
95
+ *
96
+ * A head commit may be opened with one already in hand ({@link openHeadCommit}'s `resume`): the
97
+ * attempt an earlier cycle under the same action id recorded through `HeadCommitOptions.recordAttempt`
98
+ * before sending it, which the cycle's opening refresh can then finish from. */
122
99
  inFlightAttempt;
123
100
  /** The log data-block ids the append of the action marked in {@link inFlightActionId} has
124
101
  * minted, in the order it minted them, together with the revision they were minted for. Set and
125
102
  * read by {@link logAppendBlockIds}, cleared with the rest of the in-flight state by
126
103
  * {@link beginInFlightAction} and its disposer. */
127
104
  mintedLogBlockIds;
105
+ /** What the cycle marked in {@link inFlightActionId} asked of every send it makes
106
+ * ({@link InFlightCycle}) — read by {@link send} and by the re-send {@link completeOwnEntry} makes
107
+ * to finish a torn attempt, so neither needs it threaded through. Set by
108
+ * {@link beginInFlightAction} and cleared by its disposer. */
109
+ inFlightCycle = {};
110
+ /** The head commit running on this instance ({@link openHeadCommit}), for the whole cycle — set and
111
+ * cleared beside {@link inFlightActionId}: the sealed segment it is committing, and the hook told
112
+ * what that segment accepted as already applied when it is dropped as committed
113
+ * ({@link HeadCommitOptions.onCommittedHead}). Read by {@link consumeOwnEntry}: the entry a head
114
+ * commit's own refresh finds under the in-flight action id records the HEAD segment's actions, not
115
+ * the open segment's, so consuming it removes that segment — and reports it through the hook, as
116
+ * the handle's `fold` does. */
117
+ headCommit;
118
+ /** Set only while a head commit has RELEASED the collection latch for its one network round trip
119
+ * ({@link HeadCommitHandle.release}), and cleared the moment it is retaken, so anything that runs under the
120
+ * latch in that window can tell. Two things must: a refresh ({@link updateInternal}) that walks
121
+ * into the in-flight entry returns without adopting it, since it can neither finish it as the
122
+ * write's own (nothing failed, nothing is retained) nor replay it as a stranger's (that would
123
+ * re-stage the head over state that already contains it); and {@link dropSealed} refuses to drop
124
+ * the segment the commit is carrying. A second {@link commitHead} meets it as its `in-flight`
125
+ * precondition. Gated on THIS field, not on {@link inFlightActionId}: the head commit's own
126
+ * refreshes run with it cleared and must take the own-entry path. */
127
+ headInFlight;
128
128
  /** The log tail block id the most recent header read named. A refresh asks for this block in the
129
129
  * same request as the header ({@link readLogEnds}): the tail id only changes when the tail block
130
130
  * fills, so an idle refresh is one request rather than two. A stale value costs one extra request
@@ -139,6 +139,8 @@ export class Collection {
139
139
  * {@link updateInternal}, and shared with every read source this handle builds (see
140
140
  * {@link BlockFloors}). */
141
141
  floors, filterConflict,
142
+ /** See {@link CollectionInitOptions.onSealedRefused}. */
143
+ onSealedRefused,
142
144
  /** Short random tag naming THIS instance (see {@link newInstanceTag}). Open paths generate
143
145
  * it BEFORE construction (so pre-construction diagnostics such as attachToLog can carry it);
144
146
  * the default covers direct construction in tests. */
@@ -151,6 +153,7 @@ export class Collection {
151
153
  this.tracker = tracker;
152
154
  this.floors = floors;
153
155
  this.filterConflict = filterConflict;
156
+ this.onSealedRefused = onSealedRefused;
154
157
  this.instanceTag = instanceTag;
155
158
  // Instance-scoped, deliberately NOT shared across instances of one collection id. The
156
159
  // latch protects per-instance state only — the tracker, the pending queue, and
@@ -195,7 +198,7 @@ export class Collection {
195
198
  return undefined;
196
199
  }
197
200
  await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends);
198
- const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, instanceTag);
201
+ const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, init.onSealedRefused, instanceTag);
199
202
  collection.logTailId = ends.header.tailId;
200
203
  return collection;
201
204
  }
@@ -209,6 +212,7 @@ export class Collection {
209
212
  // Pre-construction for the same reason as in open(): see the comment there.
210
213
  const instanceTag = Collection.newInstanceTag();
211
214
  const { source, sourceCache, tracker, floors, ends } = await Collection.probeHeader(transactor, id, instanceTag);
215
+ let inventedBaseline;
212
216
  if (ends) { // Collection already exists
213
217
  await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends);
214
218
  }
@@ -218,9 +222,14 @@ export class Collection {
218
222
  tracker.insert(headerBlock);
219
223
  source.actionContext = undefined;
220
224
  await Log.open(tracker, id);
225
+ // Everything staged so far — the header (with the tail id Log.open wrote into it), the
226
+ // empty log block, and whatever createHeaderBlock staged beside the header — is what a
227
+ // replay has to put back while this collection has no committed revision.
228
+ inventedBaseline = copyTransforms(tracker.transforms);
221
229
  }
222
- const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, instanceTag);
230
+ const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, init.onSealedRefused, instanceTag);
223
231
  collection.logTailId = ends?.header.tailId;
232
+ collection.inventedBaseline = inventedBaseline;
224
233
  return collection;
225
234
  }
226
235
  /** The committed tail of `id` — the tail block id its header names and that block's latest
@@ -239,8 +248,55 @@ export class Collection {
239
248
  static async readCommittedTail(transactor, id, knownTailId) {
240
249
  const ends = await Collection.readLogEnds(transactor, id, knownTailId);
241
250
  const tailId = ends?.header.tailId;
242
- const rev = ends?.tail?.state.latest?.rev;
243
- return tailId === undefined || rev === undefined ? undefined : { tailId, rev };
251
+ return tailId === undefined ? undefined : Collection.committedTailOf(tailId, ends?.tail);
252
+ }
253
+ /** {@link readCommittedTail} for several collections at once, answered per collection: what
254
+ * the single read would have resolved, as `tail`, or what it would have thrown, as `error`. A
255
+ * collection named twice is read once.
256
+ *
257
+ * One request names every header and every known tail id. A collection whose header names a
258
+ * different tail than its known one costs a second request, shared by every such collection. So
259
+ * a poll of many collections whose logs stayed on their blocks is one request, however many it
260
+ * names; the per-block judgement is {@link readLogEnds}'s, through the same helpers.
261
+ *
262
+ * A block no coordinator answered comes back flagged and fails only its own collection, through
263
+ * the per-block judgement. A request that throws as a whole — `NetworkTransactor.get` does when a
264
+ * coordinator's answer leaves a block out — is not every collection's failure either:
265
+ * {@link readAttributed} then reads each block alone and only the collections whose blocks failed
266
+ * report an error. That fallback costs what reading each collection separately costs, and only
267
+ * when a request fails. */
268
+ static async readCommittedTails(transactor, queries) {
269
+ const knownTails = new Map(queries.map(query => [query.id, query.knownTailId]));
270
+ const ends = await Collection.readAttributed(transactor, [...knownTails].flatMap(([id, knownTailId]) => knownTailId === undefined ? [id] : [id, knownTailId]));
271
+ const answers = new Map();
272
+ /** Collections whose header names a tail other than the known one, with the tail it names. */
273
+ const moved = new Map();
274
+ for (const [id, knownTailId] of knownTails) {
275
+ try {
276
+ const tailId = Collection.answeredHeader(id, Collection.entryIn(ends, id))?.header.tailId;
277
+ if (tailId === undefined || tailId === knownTailId) {
278
+ answers.set(id, { tail: Collection.judgedTail(tailId, ends) });
279
+ }
280
+ else {
281
+ moved.set(id, tailId);
282
+ }
283
+ }
284
+ catch (error) {
285
+ answers.set(id, { error });
286
+ }
287
+ }
288
+ if (moved.size > 0) {
289
+ const tails = await Collection.readAttributed(transactor, [...new Set(moved.values())]);
290
+ for (const [id, tailId] of moved) {
291
+ try {
292
+ answers.set(id, { tail: Collection.judgedTail(tailId, tails) });
293
+ }
294
+ catch (error) {
295
+ answers.set(id, { error });
296
+ }
297
+ }
298
+ }
299
+ return answers;
244
300
  }
245
301
  /** The per-instance read wiring every open path needs, plus the collection's log ends — the
246
302
  * header, then the log tail block it names — read by {@link readLogEnds}, the reader every
@@ -266,7 +322,8 @@ export class Collection {
266
322
  const ends = await Collection.readLogEnds(transactor, id, undefined);
267
323
  return { source, sourceCache, tracker, floors, ends };
268
324
  }
269
- /** A new handle's floors: none yet (opening walks no entries), wired to report every below-floor
325
+ /** A new handle's floors: none yet (an open raises them from its log tail,
326
+ * {@link floorTailEntries}), wired to report every below-floor
270
327
  * answer any of the handle's read sources receives. The line is the only trace such an answer
271
328
  * leaves — the read itself succeeds (see the accepted-tradeoff NOTE at
272
329
  * `TransactorSource.mayRetain`) — so repeated lines for one block with `servedRev` short of
@@ -289,6 +346,7 @@ export class Collection {
289
346
  // Bootstrap ActionContext from the committed tail before walking the chain.
290
347
  // This allows the transactor to serve pending non-tail blocks during Log.open.
291
348
  Collection.bootstrapContext(source, ends.tail);
349
+ Collection.floorTailEntries(floors, ends);
292
350
  // The walk starts from the header and the tail, which the probe just read: keep them, so the
293
351
  // walk reads neither again. Its first read of each through the cache then records the read
294
352
  // dependency the probe's own read of the header used to.
@@ -302,6 +360,30 @@ export class Collection {
302
360
  // bootstrapContext just read off the committed tail.
303
361
  Collection.advanceContext(source, id, instanceTag, 'attach', await collectionLog.getActionContext());
304
362
  }
363
+ /** Floor every block an action entry in the opened log's tail block names, at that entry's
364
+ * revision — what a refresh's walk does for the entries it walks ({@link raiseFloors}), for the
365
+ * entries an open has read but does not walk.
366
+ *
367
+ * An open adopts the revision the tail names, then reads each block it needs for the first time.
368
+ * When the answering repo's copy of such a block is older than an entry the tail holds — a node
369
+ * whose crash kept a commit's log tail but lost its other blocks within the store's durability
370
+ * window, or a coordinator that missed the commit — nothing else tells the read so, and the
371
+ * repo serves its held copy (a held block's first read after a restart is answered locally while
372
+ * the consult runs behind it). The handle then shows, say, a table row whose index entry is
373
+ * missing. With the floor, the read carries the revision the tail proves, so the repo consults
374
+ * its cohort before answering and the transactor re-asks another machine for an answer still
375
+ * below it (see {@link BlockFloors}).
376
+ *
377
+ * Only the tail block's entries: they are what the open read, and they hold the newest commits —
378
+ * the ones a durability window can tear. Invalidation entries set no floor, as on a refresh. */
379
+ static floorTailEntries(floors, ends) {
380
+ const tail = ends.tail?.block;
381
+ for (const entry of tail?.entries ?? []) {
382
+ if (entry.action !== undefined) {
383
+ floors.raise(entry.action.blockIds, { rev: entry.rev, actionId: entry.action.actionId });
384
+ }
385
+ }
386
+ }
305
387
  /** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
306
388
  *
307
389
  * The revision a collection last committed at is knowledge it earned; a read that found
@@ -465,18 +547,33 @@ export class Collection {
465
547
  }
466
548
  async actInternal(...actions) {
467
549
  await this.internalTransact(...actions);
468
- this.pending.push(...actions);
550
+ // Staging appends to the OPEN segment: a sealed segment is closed to further staging.
551
+ this.segments.open.push(...actions);
469
552
  }
470
- async internalTransact(...actions) {
471
- const atomic = new Atomic(this.tracker);
553
+ internalTransact(...actions) {
554
+ return this.stageInto(this.tracker, ...actions);
555
+ }
556
+ /** Run `actions` through their handlers over `tracker` as ONE atomic unit: a throw from any
557
+ * handler leaves none of their writes staged. The live tracker's path ({@link internalTransact})
558
+ * and a head commit's tracker ({@link buildHeadTracker}) share it.
559
+ *
560
+ * @returns the sum of what the handlers accepted as already applied ({@link AlreadyAppliedTally});
561
+ * a handler that answers nothing adds the zero tally. */
562
+ async stageInto(tracker, ...actions) {
563
+ const atomic = new Atomic(tracker);
564
+ let applied = ZeroTally;
472
565
  for (const action of actions) {
473
566
  const handler = this.handlers[action.type];
474
567
  if (!handler) {
475
568
  throw new Error(`No handler for action type ${action.type}`);
476
569
  }
477
- await handler(action, atomic);
570
+ const tally = await handler(action, atomic);
571
+ if (tally !== undefined) {
572
+ applied = addTallies(applied, tally);
573
+ }
478
574
  }
479
575
  atomic.commit();
576
+ return applied;
480
577
  }
481
578
  /** Load external changes and update our context to the latest log revision - resolve any conflicts with our pending actions. */
482
579
  async update() {
@@ -565,18 +662,23 @@ export class Collection {
565
662
  // finish. `getStatus` is the cheap first question; it judges a block by who holds its
566
663
  // LATEST revision, so a block this action landed and a later action has since built on
567
664
  // reads there as not committed — those are asked again, properly, by settleUnfinished.
568
- // Both write paths retain an attempt before any refresh can run, so production only
569
- // reaches this branch when the entry sits at a revision the retained attempt was not
570
- // made at — a forked lineage.
665
+ // A write's own cycle retains an attempt before any refresh can run, so from inside a cycle
666
+ // this branch is reached only when the entry sits at a revision the retained attempt was
667
+ // not made at — a forked lineage. The ordinary way here is a NEW cycle under an old id:
668
+ // the queue re-driving an entry whose earlier head commit ended in doubt without handing
669
+ // back the attempt it recorded ({@link openHeadCommit}, whose opening refresh runs with
670
+ // nothing retained unless `resume` seeds it).
571
671
  const [status] = await this.transactor.getStatus([{ actionId: entry.actionId, blockIds: entry.blockIds }]);
572
672
  if (entry.blockIds.every((_, i) => status?.statuses[i] === 'committed')) {
573
673
  // Whole, and saved: the refresh reports it as finished (see RefreshReport), so the
574
674
  // coordinator counts this participant as committed. Only WHO holds it is unknown.
575
- // NOTE: a sync whose only commit was recognised here therefore answers `undefined` —
576
- // the "nothing was written" answer — for a write that is saved, because the sync reads
577
- // the report's durability, not the finished flag. Reachable only on the forked-lineage
578
- // path above; if that path ever becomes ordinary, take the durability from
579
- // `getLineage` (as settleUnfinished does) instead of stopping at the status read.
675
+ // NOTE: a write whose only commit was recognised here therefore answers `undefined` for
676
+ // a write that is saved, because both write paths read the report's durability, not the
677
+ // finished flag. For a sync that is the "nothing was written" answer, reachable only on
678
+ // the forked-lineage path above; for a head commit it is unambiguous (a head segment is
679
+ // never empty) and is how a re-driven entry is answered. If the queue ever needs a
680
+ // durability class for a re-driven entry, take it from `getLineage` (as
681
+ // settleUnfinished does) instead of stopping at the status read.
580
682
  return undefined;
581
683
  }
582
684
  return await this.settleUnfinished(entry, rev, undefined, 'transforms-not-held', attempt === undefined
@@ -595,7 +697,11 @@ export class Collection {
595
697
  // pair is not obviously right either: a member re-executing the transaction after a sibling
596
698
  // participant has landed no longer sees the state it was staged against. Tracked as an arm
597
699
  // of tickets/backlog/feat-no-deployment-validates-transactions-at-pend.
598
- const result = await this.source.transact(attempt.transforms, entry.actionId, rev, this.id, attempt.tailId, 0, attempt.blockDigests, attempt.baseRevs);
700
+ const result = await this.source.transact(attempt.transforms, entry.actionId, rev, this.id, attempt.tailId, {
701
+ blockDigests: attempt.blockDigests,
702
+ baseRevs: attempt.baseRevs,
703
+ refuseSolo: this.inFlightCycle.refuseSolo
704
+ });
599
705
  if (result.success) {
600
706
  return result.durability;
601
707
  }
@@ -613,6 +719,13 @@ export class Collection {
613
719
  // needs the clocks to start disagreeing between a write's attempts, since an expiry on the
614
720
  // attempt itself ends the write before any refresh. If it is ever seen burning a budget,
615
721
  // settle it at once beside the confirmed rival.
722
+ // NOTE: a promise shortfall of the re-send (`isShortfallFailure`) lands in the same arm, and
723
+ // there it can genuinely clear (the silent members come back), so the write is re-sent each
724
+ // round until the budget's last round settles it — unlike a fresh attempt's shortfall, which
725
+ // ends the write at once. If a silent cohort is ever seen holding torn writes for the whole
726
+ // budget, settle it at once here too.
727
+ // A validity rejection (`isRejectedFailure`) cannot answer the re-send: it carries no
728
+ // `validation` pair (above), so no checker judges it.
616
729
  // NOTE: a confirmed rival settles at once, even with retry budget left: re-sending is
617
730
  // pointless, but the lineage question is asked only this once, so a member that is silent
618
731
  // just now makes the answer `final: false`. If unsettled outcomes ever show up often under
@@ -703,45 +816,115 @@ export class Collection {
703
816
  * {@link completeOwnEntry} has returned for this entry — the entry alone is not proof the write
704
817
  * is saved.
705
818
  *
706
- * `addActions` wrote exactly the snapshot pending list under this action id, and the entry's
707
- * actions are therefore the LEADING `entry.actions.length` items of `this.pending` — anything
708
- * staged since is behind them, because {@link actInternal} appends. Under
709
- * {@link syncInternal} nothing can even be staged mid-cycle (`act()` shares the collection
710
- * latch); under `TransactionCoordinator.commit` the mark spans a latch-free inter-attempt
711
- * window, so an `act()` there CAN grow `pending` — still only at the tail, so the slice stays
712
- * right.
713
- *
714
- * The guard below is the load-bearing part: `slice` fails SILENTLY if that correspondence ever
715
- * breaks, dropping actions that were never committed, so an entry longer than `pending` throws
716
- * instead of losing work. (See the sibling note on `syncInternal`'s post-commit replay, which
717
- * rests on the same invariant.) */
819
+ * A whole-collection write (`sync`) wrote exactly the snapshot of the OPEN segment under this
820
+ * action id, and the entry's actions are therefore the LEADING `entry.actions.length` items of
821
+ * the open segment — anything staged since is behind them, because {@link actInternal}
822
+ * appends. Under {@link syncInternal} nothing can even be staged mid-cycle (`act()` shares the
823
+ * collection latch); under `TransactionCoordinator.commit` the mark spans a latch-free
824
+ * inter-attempt window, so an `act()` there CAN grow the open segment — still only at the
825
+ * tail, so the slice stays right. No sealed segment can exist for such a write: every
826
+ * whole-collection path refuses while one does ({@link SealedSegmentsError}).
827
+ *
828
+ * A head commit ({@link commitHead}, which marks {@link headCommit} for its cycle) wrote the
829
+ * HEAD sealed segment's actions, so its entry is consumed by removing that segment — the open
830
+ * segment, which may have grown while the commit was on the network, is untouched. The sealed
831
+ * segments behind the head are never touched by either arm.
832
+ *
833
+ * The guards are the load-bearing part: `slice` fails SILENTLY if the open correspondence ever
834
+ * breaks, dropping actions that were never committed, so an entry longer than the open segment
835
+ * throws instead of losing work, and an entry whose action count is not the head's throws rather
836
+ * than removing a segment the entry does not record. (See the sibling note on `syncInternal`'s
837
+ * post-commit replay, which rests on the same invariant.)
838
+ *
839
+ * @returns whether the staged set changed — always true here: even for a zero-action entry the
840
+ * tracker still holds this action's staged transforms, and only the replay at the end of
841
+ * `updateInternal` — which resets the tracker and re-stages just what remains — drops them.
842
+ * That reset is what turns `hasUnsyncedChanges()` false so the sync loop exits reporting the
843
+ * success the writer is owed (the action IS durable). */
718
844
  consumeOwnEntry(entry) {
719
- if (entry.actions.length > this.pending.length) {
845
+ if (this.headCommit !== undefined) {
846
+ this.consumeHead(entry, this.headCommit.entryId);
847
+ }
848
+ else {
849
+ this.segments.open = this.consumedFromOpen(entry);
850
+ }
851
+ return true;
852
+ }
853
+ /** Remove the head segment `entryId` because `entry`, its own committed log entry, made it
854
+ * durable — the head arm of {@link consumeOwnEntry}. Bumps the segment version, so an outstanding
855
+ * snapshot restores by replay rather than putting the committed segment back, and reports the
856
+ * dropped segment's tally through the cycle's hook ({@link reportCommittedHead}), as the handle's
857
+ * `fold` does for an attempt that committed. */
858
+ consumeHead(entry, entryId) {
859
+ const head = this.segments.head();
860
+ if (head === undefined || head.entryId !== entryId) {
861
+ throw new Error(`Collection ${this.id}: own committed entry for action ${entry.actionId} records head segment `
862
+ + `${entryId}, but the head is ${head?.entryId ?? 'nothing'}`);
863
+ }
864
+ if (entry.actions.length !== head.actions.length) {
865
+ throw new Error(`Collection ${this.id}: own committed entry for action ${entry.actionId} holds `
866
+ + `${entry.actions.length} actions but head segment ${entryId} holds ${head.actions.length}; `
867
+ + `consuming it would drop actions that were never committed`);
868
+ }
869
+ this.reportCommittedHead(this.segments.drop(entryId));
870
+ }
871
+ /** Hand the tally recorded on `segment` — the head segment just made durable and dropped — to the
872
+ * cycle's `onCommittedHead` hook ({@link HeadCommitOptions.onCommittedHead}), under the latch, from
873
+ * the two places that drop a head segment as committed: the handle's `fold`, and
874
+ * {@link consumeHead}. A segment with no recorded tally is a defect, answered with the zero tally
875
+ * and logged rather than thrown: every sealed segment is staged by {@link buildHeadTracker} before
876
+ * its first send and by a replay when put back ({@link restoreSealed}), and the resume path that
877
+ * re-sends a recorded attempt verbatim runs after one of those. A throw out of the hook is logged,
878
+ * never raised — the commit is already durable. */
879
+ reportCommittedHead(segment) {
880
+ let applied = segment.applied;
881
+ if (applied === undefined) {
882
+ log('collection:committed-head-tally-missing id=%s tag=%s entry=%s: the head segment was committed without a recorded staging', this.id, this.instanceTag, segment.entryId);
883
+ applied = ZeroTally;
884
+ }
885
+ const hook = this.headCommit?.onCommitted;
886
+ if (hook === undefined) {
887
+ return;
888
+ }
889
+ try {
890
+ hook(applied);
891
+ }
892
+ catch (err) {
893
+ log('collection:committed-head-callback-threw id=%s tag=%s entry=%s error=%s', this.id, this.instanceTag, segment.entryId, err instanceof Error ? err.message : String(err));
894
+ }
895
+ }
896
+ /** The open segment with the leading actions `entry` made durable dropped off it. */
897
+ consumedFromOpen(entry) {
898
+ const open = this.segments.open;
899
+ if (entry.actions.length > open.length) {
720
900
  throw new Error(`Collection ${this.id}: own committed entry for action ${entry.actionId} holds `
721
- + `${entry.actions.length} actions but only ${this.pending.length} are pending; `
901
+ + `${entry.actions.length} actions but only ${open.length} are pending; `
722
902
  + `consuming it would drop actions that were never committed`);
723
903
  }
724
- // `mutated` is unconditional, even for a zero-action entry: the tracker still holds this
725
- // action's staged transforms, and only the replay at the end of `updateInternal` — which
726
- // resets the tracker and re-stages just what remains — drops them. That reset is what turns
727
- // `hasUnsyncedChanges()` false so the sync loop exits reporting the success the writer is
728
- // owed (the action IS durable).
729
- return { after: this.pending.slice(entry.actions.length), mutated: true };
904
+ return open.slice(entry.actions.length);
730
905
  }
731
- /** Maps each pending action to its effective form against a remote entry: the original, a
732
- * replacement, or dropped. A replacement or a discard changes the pending set; the tracker still
906
+ /** Maps each OPEN-segment action to its effective form against a remote entry: the original, a
907
+ * replacement, or dropped. A replacement or a discard changes the staged set; the tracker still
733
908
  * holds the pre-filter transforms, so report it as mutated to force a replay that re-stages
734
909
  * against the effective actions. Identity comparison per the contract: keep => same instance,
735
910
  * replace => new instance.
911
+ *
912
+ * A SEALED segment's action list is the queue entry's own and is never rewritten (invariant 3
913
+ * of docs/offline-sync.md §The segment model), so the hook is not offered them. `Tree` and
914
+ * `Diary` install no hook, so nothing observable changes for them either way.
915
+ *
736
916
  * NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead of
737
917
  * returning the same one forces a replay on every update — if that ever shows up as a hot path,
738
- * compare by value/id here instead of by reference. */
918
+ * compare by value/id here instead of by reference.
919
+ *
920
+ * @returns whether the open segment changed. */
739
921
  filterAgainstEntry(entry) {
740
- const before = this.pending;
922
+ const before = this.segments.open;
741
923
  const after = before
742
924
  .map(p => this.doFilterConflict(p, entry.actions))
743
925
  .filter((a) => a !== undefined);
744
- return { after, mutated: after.length !== before.length || after.some((a, i) => a !== before[i]) };
926
+ this.segments.open = after;
927
+ return after.length !== before.length || after.some((a, i) => a !== before[i]);
745
928
  }
746
929
  /** Refresh this instance against the stored log: adopt the latest committed revision, resolve
747
930
  * pending actions against everything that landed since, and replay them if anything conflicts.
@@ -826,6 +1009,19 @@ export class Collection {
826
1009
  // Get the latest entries from the log, starting from where we left off
827
1010
  const collectionLog = await Log.open(tracker, this.id);
828
1011
  const latest = collectionLog ? await collectionLog.getFrom(actionContext?.rev ?? 0) : undefined;
1012
+ // A refresh that runs while this instance's own head commit is on the network — a reader's,
1013
+ // the latch being released for that round trip — and walks into that commit's entry adopts
1014
+ // NOTHING (see {@link headInFlight}): the entry is not failed, so it is not finished and consumed
1015
+ // as the write's own below, and it is not a stranger's, so it is not filtered and replayed. The
1016
+ // head commit applies its own outcome when it retakes the latch, after which the next refresh
1017
+ // finds nothing new. The reader is served the state before this collection's own write, which it
1018
+ // sees staged anyway. Entries behind it in the same walk wait with it — an own entry is always
1019
+ // the first above the held revision, since the attempt requested exactly that revision.
1020
+ const headInFlight = this.headInFlight;
1021
+ if (headInFlight !== undefined && latest?.entries.some(entry => entry.actionId === headInFlight.actionId)) {
1022
+ log('collection:refresh-deferred-to-head-commit id=%s tag=%s entry=%s action=%s', this.id, this.instanceTag, headInFlight.entryId, headInFlight.actionId);
1023
+ return;
1024
+ }
829
1025
  // This write's own entry, if its log tail landed despite the failure that sent us here.
830
1026
  // Decided ONCE, here: the mark can be cleared latch-free while the completion below is
831
1027
  // awaiting (see {@link inFlightActionId}), and an entry that was finished as our own must
@@ -848,11 +1044,9 @@ export class Collection {
848
1044
  // Process the entries and track the blocks they affect
849
1045
  let anyConflicts = false;
850
1046
  for (const entry of latest?.entries ?? []) {
851
- const isOwnEntry = entry === ownEntry;
852
- const { after, mutated } = isOwnEntry
1047
+ const mutated = entry === ownEntry
853
1048
  ? this.consumeOwnEntry(entry)
854
1049
  : this.filterAgainstEntry(entry);
855
- this.pending = after;
856
1050
  anyConflicts = anyConflicts || mutated || this.tracker.conflicts(new Set(entry.blockIds)).length > 0;
857
1051
  }
858
1052
  // React to durable invalidations that landed since we last synced. getFrom intentionally skips
@@ -863,20 +1057,22 @@ export class Collection {
863
1057
  // block; over-inclusive by design (over-invalidation just resubmits — it never wrongly retains).
864
1058
  const invalidations = collectionLog ? await collectionLog.getInvalidationsFrom(actionContext?.rev ?? 0) : [];
865
1059
  const revertedBlockIds = [...new Set(invalidations.flatMap(inv => inv.reverted.map(r => r.blockId)))];
866
- if (invalidations.length > 0 && this.pending.length > 0) {
1060
+ if (invalidations.length > 0 && this.segments.replayableCount() > 0) {
867
1061
  anyConflicts = true;
868
1062
  }
869
1063
  this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
870
1064
  Collection.reportShortfall(this.id, this.instanceTag, tailRev, actionContext?.rev, this.source.actionContext?.rev);
871
- // Re-stage the pending actions against the adopted revision. The affected
1065
+ // Re-stage the staged actions against the adopted revision. The affected
872
1066
  // blocks were already dropped from sourceCache above (per log entry / per invalidation),
873
1067
  // so the replay's reads re-materialize from the transactor.
874
- // NOTE: a throw out of replayActions leaves the tracker holding only the transforms
875
- // replayed so far while `pending` still lists them all; the caller's error handling is
876
- // expected to abort/reset the collection rather than keep staging. The coordinator's partial
877
- // report after a refresh-saved sibling does not (backlog: debt-a-failed-refresh-can-leave-a-
878
- // collection-half-restaged). If replay ever gains a
879
- // routinely-throwing read path, rebuild into a scratch tracker and swap on success.
1068
+ // NOTE: a throw out of replayActions — a refusal of the OPEN segment, or any non-refusal
1069
+ // error — leaves the tracker holding only the transforms replayed so far while the open
1070
+ // segment still lists all of its actions; the caller's error handling is expected to
1071
+ // abort/reset the collection rather than keep staging. The coordinator's partial report
1072
+ // after a refresh-saved sibling does not (backlog: debt-a-failed-refresh-can-leave-a-
1073
+ // collection-half-restaged). A SEALED segment is not left half-replayed: it is staged
1074
+ // atomically, and a refusal of one is recorded and skipped rather than thrown. If replay ever
1075
+ // gains a routinely-throwing read path, rebuild into a scratch tracker and swap on success.
880
1076
  if (this.mustReplay(anyConflicts, actionContext)) {
881
1077
  await this.replayActions();
882
1078
  }
@@ -1081,8 +1277,8 @@ export class Collection {
1081
1277
  return loggedAction !== undefined && loggedAction !== entry.actionId;
1082
1278
  });
1083
1279
  }
1084
- /** Whether {@link updateInternal} must re-stage `pending` after adopting `latest`, given the
1085
- * context it held BEFORE the refresh.
1280
+ /** Whether {@link updateInternal} must re-stage the staged actions after adopting `latest`,
1281
+ * given the context it held BEFORE the refresh.
1086
1282
  *
1087
1283
  * The answer is deliberately NOT just "a conflict was found". A conflict is detected by an
1088
1284
  * incoming log entry naming a block this tracker already holds a transform for — so an action
@@ -1097,16 +1293,17 @@ export class Collection {
1097
1293
  * The advance test rests on {@link advanceContext} being monotonic (it refuses to lower), which
1098
1294
  * is what makes "the adopted rev differs from the held one" mean "it went up".
1099
1295
  *
1100
- * The second conjunct is `pending.length` and deliberately NOT {@link hasUnsyncedChanges},
1101
- * which also counts tracker transforms. A collection {@link createOrOpen} just INVENTED holds
1102
- * its staged header/root in the tracker with NO pending action naming them, and
1103
- * {@link replayActions} resets the tracker before re-staging — so counting transforms here
1104
- * would drop those blocks and leave a brand-new collection unreadable (the same hazard
1105
- * {@link snapshotPending} documents). Nothing to re-stage means nothing to replay.
1106
- *
1107
- * NOTE: this makes a refresh that adopts a newer revision O(pending) rather than free, so a
1108
- * read taken mid-transaction while a rival keeps committing re-stages every action staged so
1109
- * far, on each such read. Measured as no change to the storage-op budgets
1296
+ * The second conjunct counts the REPLAYABLE actions — every non-refused sealed segment's plus
1297
+ * the open segment's, since a refresh that adopts a newer revision must re-stage the sealed
1298
+ * segments too — and deliberately NOT {@link hasUnsyncedChanges}, which also counts tracker
1299
+ * transforms. A collection {@link createOrOpen} just INVENTED holds its staged header/root in
1300
+ * the tracker with NO staged action naming them; {@link replayActions} now restores them from
1301
+ * {@link inventedBaseline}, but nothing to re-stage still means nothing to replay, and a replay
1302
+ * over no actions would be a wasted tracker rebuild.
1303
+ *
1304
+ * NOTE: this makes a refresh that adopts a newer revision O(staged actions) rather than free,
1305
+ * so a read taken mid-transaction while a rival keeps committing re-stages every action staged
1306
+ * so far, on each such read. Measured as no change to the storage-op budgets
1110
1307
  * (`index-backfill-cost.spec.ts`, `cold-apply-cost.spec.ts`), because the replay's reads are
1111
1308
  * served from `sourceCache`. If a long transaction's reads ever show up as slow, narrow the
1112
1309
  * replay to the actions whose reads the adopted entries actually invalidated — NOT back to
@@ -1116,7 +1313,8 @@ export class Collection {
1116
1313
  return true;
1117
1314
  }
1118
1315
  const adoptedRev = this.source.actionContext?.rev;
1119
- if (adoptedRev !== undefined && adoptedRev !== priorContext?.rev && this.pending.length > 0) {
1316
+ const replayable = this.segments.replayableCount();
1317
+ if (adoptedRev !== undefined && adoptedRev !== priorContext?.rev && replayable > 0) {
1120
1318
  return true;
1121
1319
  }
1122
1320
  // Third reason: a staged block's base has MOVED — the read cache no longer describes it at
@@ -1124,21 +1322,18 @@ export class Collection {
1124
1322
  // that adopted nothing and found no conflict can still be standing over such a block: a
1125
1323
  // concurrent read served content the cache then kept at a newer revision, say. Re-staging
1126
1324
  // is the only repair; declaring the pinned revision on the pend would merely get it refused.
1127
- return this.pending.length > 0 && this.logMovedBases(this.tracker.movedBases()) > 0;
1325
+ return replayable > 0 && this.logMovedBases(this.tracker.movedBases()) > 0;
1128
1326
  }
1129
1327
  /** Re-judge every staged update's pinned base against the read cache and re-stage the pending
1130
1328
  * queue if any has moved. Runs immediately before each pend attempt — {@link syncAttempts} and
1131
- * the coordinator's commit span both call it — because that is the last moment before the
1132
- * base the pend declares is put on the wire, and nothing between a refused attempt and the
1133
- * re-pend reads the block again (the refresh may have moved nothing and so replayed nothing).
1329
+ * the coordinator's commit span both call it, and {@link headTrackerFor} re-judges a head
1330
+ * commit's tracker the same way — because that is the last moment before the base the pend
1331
+ * declares is put on the wire, and nothing between a refused attempt and the re-pend reads the
1332
+ * block again (the refresh may have moved nothing and so replayed nothing).
1134
1333
  *
1135
- * Two steps. First, one read for each pinned block the cache does NOT retain — content handed
1136
- * through unkept (a below-floor answer, which the cache re-asks for on every read anyway): the
1137
- * pin names the revision last served, storage may have caught up since without the log moving,
1138
- * and only a read can tell. An evicted-but-kept base needs no read: its content met every floor
1139
- * the handle knows, so storage cannot have moved it without a log entry the next refresh will
1140
- * walk (and the pend would be refused as stale on revision alone). Then, one cache probe per
1141
- * pinned block ({@link Tracker.movedBases}) and a replay if any moved.
1334
+ * Two steps. First, one read for each pinned block the cache does NOT retain
1335
+ * ({@link rereadUnretainedBases}). Then, one cache probe per pinned block
1336
+ * ({@link Tracker.movedBases}) and a replay if any moved.
1142
1337
  *
1143
1338
  * Latch-free by contract, like {@link snapshotPending}: the caller holds this instance's latch
1144
1339
  * ({@link replayActions} is always run under it).
@@ -1150,17 +1345,28 @@ export class Collection {
1150
1345
  *
1151
1346
  * @returns whether the pending queue was re-staged. */
1152
1347
  async restageIfBasesMoved() {
1153
- for (const id of this.tracker.unretainedBases()) {
1154
- // `navigation` never upgrades the purpose the original read recorded (value-wins), and
1155
- // the revision recorded is the one returned, which the replay below re-records anyway.
1156
- await this.sourceCache.tryGet(id, 'navigation');
1157
- }
1158
- if (this.pending.length === 0 || this.logMovedBases(this.tracker.movedBases()) === 0) {
1348
+ await this.rereadUnretainedBases(this.tracker);
1349
+ // Every replayable action counts, sealed segments included: a moved base under a sealed
1350
+ // segment's operations is re-staged the same way.
1351
+ if (this.segments.replayableCount() === 0 || this.logMovedBases(this.tracker.movedBases()) === 0) {
1159
1352
  return false;
1160
1353
  }
1161
1354
  await this.replayActions();
1162
1355
  return true;
1163
1356
  }
1357
+ /** One read for each of `tracker`'s pinned blocks the cache does NOT retain — content handed
1358
+ * through unkept (a below-floor answer, which the cache re-asks for on every read anyway): the
1359
+ * pin names the revision last served, storage may have caught up since without the log moving,
1360
+ * and only a read can tell. An evicted-but-kept base needs no read: its content met every floor
1361
+ * the handle knows, so storage cannot have moved it without a log entry the next refresh will
1362
+ * walk (and the pend would be refused as stale on revision alone). */
1363
+ async rereadUnretainedBases(tracker) {
1364
+ for (const id of tracker.unretainedBases()) {
1365
+ // `navigation` never upgrades the purpose the original read recorded (value-wins), and
1366
+ // the revision recorded is the one returned, which a replay re-records anyway.
1367
+ await this.sourceCache.tryGet(id, 'navigation');
1368
+ }
1369
+ }
1164
1370
  /** Report each moved base, naming the revision the operations were computed against and the
1165
1371
  * one the cache describes now, and return how many there were. */
1166
1372
  logMovedBases(moved) {
@@ -1188,7 +1394,8 @@ export class Collection {
1188
1394
  return {
1189
1395
  transforms: copyTransforms(this.tracker.transforms),
1190
1396
  pins: this.tracker.pins.copy(),
1191
- pending: [...this.pending],
1397
+ pending: [...this.segments.open],
1398
+ sealedVersion: this.segments.version,
1192
1399
  context: structuredClone(this.source.actionContext),
1193
1400
  };
1194
1401
  }
@@ -1196,41 +1403,81 @@ export class Collection {
1196
1403
  * mutations staged since. Reads through the collection then observe exactly the
1197
1404
  * snapshot state again; storage is untouched because nothing was ever synced.
1198
1405
  *
1199
- * A snapshot is only restorable VERBATIM onto the committed boundary it was captured
1200
- * on. If this collection has since ADOPTED a newer committed revision — a rival's
1201
- * commit folded in by a refresh while the snapshot's transaction was in flight, e.g.
1202
- * the conflict replay that refused a guarded insert (TreeKeyTakenError) — the
1203
- * snapshot's transforms describe block state at the OLD boundary, and reinstalling
1204
- * them would shadow committed blocks with stale structure. The observed case: an
1205
- * INVENTED collection's pre-commit header/root transforms restored over the rival's
1206
- * now-committed collection make every later read descend an empty tree, silently
1207
- * hiding the committed rows. When the snapshot's pending queue is empty (the
1208
- * transaction-rollback shape: the capture predates the transaction's first stage),
1209
- * the correct restore target IS the committed state — reset the tracker empty and
1210
- * let reads flow through to the adopted revision.
1211
- *
1212
- * NOTE: a snapshot that carries PENDING actions across a moved boundary (a
1213
- * mid-transaction savepoint captured before a mid-transaction refresh adopted a
1214
- * rival's commit) still restores verbatim below — rebasing it would require an async
1215
- * replay this synchronous method cannot run. That shape predates this guard and
1216
- * keeps its old behaviour; if it is ever observed producing stale reads, the rebase
1217
- * belongs in an async caller that can replay the pending queue (see replayActions).
1406
+ * The snapshot describes the OPEN segment only (docs/offline-sync.md §Rollback and savepoints
1407
+ * only touch the open segment): its `pending` is the open segment's actions, while its
1408
+ * `transforms` are the whole tracker at capture, the sealed segments' effects included. Which
1409
+ * arm a restore takes is decided from three facts — whether the sealed list has changed since
1410
+ * the capture ({@link CollectionSnapshot.sealedVersion} against {@link SegmentList.version}),
1411
+ * whether the committed boundary has moved (this collection has since ADOPTED a newer
1412
+ * revision), and whether any segment is sealed now:
1413
+ *
1414
+ * - **Verbatim**, when the sealed list is unchanged and the boundary has not moved: the tracker
1415
+ * is reset to a copy of the captured transforms, the captured pins are restored, and the open
1416
+ * segment is set to the captured actions. This keeps an INVENTED collection's header, log
1417
+ * block and root, which live in the tracker until the first sync and would be lost by a
1418
+ * reset. It is the arm every restore took before segments existed, so while nothing is ever
1419
+ * sealed nothing behaves differently.
1420
+ * - **Replay**, when the sealed list has changed — a segment sealed, dropped or refused while
1421
+ * the snapshot was outstanding — or when the boundary has moved while a segment is sealed:
1422
+ * the open segment is set to the captured actions and the tracker is rebuilt by
1423
+ * {@link replayActions}, the sealed segments as they are NOW (refused ones skipped, a newly
1424
+ * refused one recorded and reported) and then the restored open actions. Reinstating the
1425
+ * captured transforms would put a dropped segment's effects back — the drain removes the
1426
+ * head segment after committing it, and the next head commit would commit it a second time
1427
+ * — and a reset would drop the sealed segments' effects.
1428
+ * - A moved boundary with NOTHING sealed keeps the two arms it had before segments. An empty
1429
+ * captured open segment (the transaction-rollback shape: the capture predates the
1430
+ * transaction's first stage) resets the tracker empty, because the captured transforms
1431
+ * describe block state at the OLD boundary and reinstalling them would shadow committed
1432
+ * blocks with stale structure — the observed case being an INVENTED collection's pre-commit
1433
+ * header/root restored over a rival's now-committed collection, after the conflict replay
1434
+ * that refused a guarded insert (TreeKeyTakenError), making every later read descend an
1435
+ * empty tree. A non-empty one restores verbatim (the NOTE below).
1436
+ *
1437
+ * The staged-base rule (docs/internals.md §Staged Edits Keep Their Base: an update names the
1438
+ * base it was computed against, and a rollback never pairs operations with the bases of some
1439
+ * later re-stage) is met differently by the two arms. The verbatim arm restores the captured
1440
+ * pins beside the captured operations. The replay arm restores none: its reset clears the pin
1441
+ * store, and every re-staged update pins its base from the read cache as it is now, which IS
1442
+ * the base the re-staged operations were computed against.
1443
+ *
1444
+ * A refusal of the OPEN segment inside the replay arm propagates, as it would out of a
1445
+ * refresh's replay: the caller rolling back is told that its transaction's own actions no
1446
+ * longer apply at the boundary the collection is now at. Rare — it needs a sealed change, or a
1447
+ * sealed segment across a moved boundary, AND a rival between capture and restore — and the
1448
+ * honest answer; the tracker is then as {@link updateInternal}'s note on a throw out of
1449
+ * `replayActions` describes.
1450
+ *
1451
+ * Latch-free by contract, like {@link snapshotPending}: every caller holds this instance's
1452
+ * latch or runs on the single call path that excludes a concurrent stage (the coordinator's
1453
+ * `rollback` and the bridge's savepoint rollback document that assumption).
1454
+ *
1455
+ * NOTE: a snapshot that carries PENDING actions across a moved boundary with nothing sealed (a
1456
+ * mid-transaction savepoint captured before a mid-transaction refresh adopted a rival's commit)
1457
+ * still restores verbatim. That shape predates the moved-boundary guard and keeps its old
1458
+ * behaviour; if it is ever observed producing stale reads, route it through the replay arm too.
1218
1459
  * The WRITE side of that shape is closed here: the snapshot's base pins are restored with
1219
1460
  * its transforms, so the restored operations name the bases they were computed on, and the
1220
1461
  * pre-pend re-validation (restageIfBasesMoved) finds those bases moved and re-stages. */
1221
- restorePending(snapshot) {
1462
+ async restorePending(snapshot) {
1463
+ const sealedChanged = snapshot.sealedVersion !== undefined && snapshot.sealedVersion !== this.segments.version;
1222
1464
  const capturedRev = snapshot.context?.rev;
1223
1465
  const currentRev = this.source.actionContext?.rev;
1224
1466
  const boundaryMoved = currentRev !== undefined && (capturedRev === undefined || currentRev > capturedRev);
1467
+ if (sealedChanged || (boundaryMoved && this.segments.hasSealed())) {
1468
+ this.segments.open = [...snapshot.pending];
1469
+ await this.replayActions();
1470
+ return;
1471
+ }
1225
1472
  if (boundaryMoved && snapshot.pending.length === 0) {
1226
1473
  this.tracker.reset();
1227
- this.pending = [];
1474
+ this.segments.open = [];
1228
1475
  return;
1229
1476
  }
1230
1477
  this.tracker.reset(copyTransforms(snapshot.transforms));
1231
1478
  if (snapshot.pins)
1232
1479
  this.tracker.pins.replaceWith(snapshot.pins);
1233
- this.pending = [...snapshot.pending];
1480
+ this.segments.open = [...snapshot.pending];
1234
1481
  }
1235
1482
  /** A read-only {@link Tracker} pinned to this collection's committed state AS OF the
1236
1483
  * moment of this call, seeded with a (deep-copied) set of pre-transaction transforms.
@@ -1291,33 +1538,203 @@ export class Collection {
1291
1538
  const pinnedCache = new CacheSource(pinnedSource, undefined, collector, seed);
1292
1539
  return new Tracker(pinnedCache, copyTransforms(transforms));
1293
1540
  }
1294
- /** The staged (not-yet-synced) actions queued by {@link act}.
1541
+ /** The OPEN segment: the staged (not-yet-synced) actions queued by {@link act} that no
1542
+ * {@link sealPending} has closed off.
1295
1543
  *
1296
1544
  * Exposed so a {@link TransactionCoordinator} can append them to the log at
1297
1545
  * commit time — mirroring what {@link sync} does internally — when the actions
1298
1546
  * were staged directly into this collection (e.g. through a Tree's stage())
1299
- * rather than applied via the coordinator's own action path. */
1547
+ * rather than applied via the coordinator's own action path.
1548
+ *
1549
+ * @throws SealedSegmentsError while any segment is sealed: the coordinator's only use is a
1550
+ * whole-collection append, which would merge the sealed segments' effects (they are in the
1551
+ * tracker) into one entry under one action id. The throw lands in `commitOnceLatched`'s
1552
+ * existing catch, which restores every participant. */
1300
1553
  getPendingActions() {
1301
- return this.pending;
1554
+ this.assertNoSealedSegments();
1555
+ return this.segments.open;
1302
1556
  }
1303
- /** Drop the staged actions after they have been committed through a
1304
- * coordinator. Counterpart to {@link getPendingActions}; {@link sync} clears
1305
- * its own pending inline, so this is only needed when commit was orchestrated
1306
- * externally. */
1557
+ /** Drop the OPEN segment after it has been committed through a coordinator. Counterpart to
1558
+ * {@link getPendingActions}, which cannot have returned anything while a segment was sealed,
1559
+ * so only the open segment is ever cleared here; {@link sync} clears its own inline, so this
1560
+ * is only needed when commit was orchestrated externally. */
1307
1561
  clearPendingActions() {
1308
- this.pending = [];
1562
+ this.segments.open = [];
1309
1563
  }
1310
- /** Whether {@link sync} has anything to push: staged actions, or tracker transforms
1311
- * that were never committed (an INVENTED collection's header/root blocks live there
1312
- * until its first sync, with no pending action to name them).
1564
+ /** Whether {@link sync} has anything to push: staged actions in the open segment, or tracker
1565
+ * transforms that were never committed — an INVENTED collection's header/root blocks, which
1566
+ * live there until its first sync with no staged action to name them, and the effects of
1567
+ * every sealed segment.
1313
1568
  *
1314
1569
  * This is the exact predicate {@link syncInternal} loops on, so `false` means a sync
1315
1570
  * would commit nothing. Exposed so a caller that would otherwise flush
1316
1571
  * unconditionally can skip the round trip — note that {@link Tree.sync} routes
1317
1572
  * through {@link updateAndSync}, so an unnecessary flush still pays a full,
1318
- * cache-bypassing {@link update} before discovering it has nothing to do. */
1573
+ * cache-bypassing {@link update} before discovering it has nothing to do.
1574
+ *
1575
+ * `true` does not promise that {@link sync} can push it: while any segment is sealed, `sync`
1576
+ * refuses with {@link SealedSegmentsError} rather than committing the sealed effects as one
1577
+ * entry, so a caller that loops on this over a sealed collection gets that typed error, never
1578
+ * a silent no-op. Check {@link sealedEntries} first, or commit the head segment.
1579
+ *
1580
+ * Nor does `false` promise that nothing is sealed. A sealed segment leaves no tracker transform
1581
+ * when every one of its actions is refused, or wrote nothing (a blind delete of a key nobody
1582
+ * holds), so over an otherwise empty tracker this reads `false` while {@link sealedEntries} is
1583
+ * non-empty. The queue drives off {@link sealedEntries}, never off this predicate. */
1319
1584
  hasUnsyncedChanges() {
1320
- return this.pending.length > 0 || !isTransformsEmpty(this.tracker.transforms);
1585
+ return this.segments.open.length > 0 || !isTransformsEmpty(this.tracker.transforms);
1586
+ }
1587
+ /** Close the open segment into a sealed segment owned by `entryId` (see {@link SegmentList}).
1588
+ * Returns `false` and changes nothing when the open segment is empty: an invented collection's
1589
+ * header transforms are not an action and are not sealed, so an entry that staged nothing here
1590
+ * owns no segment here. Throws when `entryId` is already sealed in this collection.
1591
+ *
1592
+ * Synchronous and latch-free by contract, like {@link snapshotPending}: the caller brackets it
1593
+ * (no concurrent act or sync is in flight). */
1594
+ sealPending(entryId) {
1595
+ return this.segments.seal(entryId);
1596
+ }
1597
+ /** The entry ids of the sealed segments, oldest first — refused ones included, until dropped. */
1598
+ sealedEntries() {
1599
+ return this.segments.entryIds();
1600
+ }
1601
+ /** The log tail block id the most recent header read named ({@link logTailId}), for a caller that
1602
+ * resolves this collection's cohorts from routing keys without a read — the offline queue's
1603
+ * reachability gate (docs/offline-sync.md §When to submit). `undefined` before the first header
1604
+ * read of an invented collection; possibly stale by one roll-over, which costs that caller nothing
1605
+ * worse than asking about a block the collection has moved on from. */
1606
+ knownLogTailId() {
1607
+ return this.logTailId;
1608
+ }
1609
+ /** The refusal recorded for `entryId`'s segment by a replay that excluded it (see
1610
+ * {@link replayActions}), or `undefined` when the segment is not refused — or not sealed here. */
1611
+ sealedRefusal(entryId) {
1612
+ return this.segments.find(entryId)?.refused;
1613
+ }
1614
+ /** The sealed segment `entryId` owns here: its actions, the array the segment holds (never
1615
+ * mutated by a caller; the offline journal serialises it), or `undefined` when the entry is not
1616
+ * sealed here. Synchronous and latch-free, like {@link sealedEntries}. */
1617
+ sealedActions(entryId) {
1618
+ return this.segments.find(entryId)?.actions;
1619
+ }
1620
+ /** The OPEN segment's actions — what the current transaction has staged since the last seal — as
1621
+ * the array the segment holds (never mutated by a caller). Unlike {@link getPendingActions} it
1622
+ * answers while segments are sealed, for a reader that judges the open transaction beside the
1623
+ * queued ones (the Quereus plugin's `CommitOutlook()`). Synchronous and latch-free, like
1624
+ * {@link sealedActions}. */
1625
+ openActions() {
1626
+ return this.segments.open;
1627
+ }
1628
+ /** The exact inverse of {@link sealPending}, list-only and latch-free by the same contract: move
1629
+ * the segment's actions back into the open segment, for an enqueue whose journal write failed
1630
+ * after sealing (`OfflineQueue.enqueue`, which unseals every collection it sealed, in reverse
1631
+ * order, and rethrows). Requires the segment to be the NEWEST sealed one and the open segment to
1632
+ * be empty — both true at that one call site, which has just sealed and staged nothing since —
1633
+ * and throws otherwise (`SegmentList.unseal`). The tracker is untouched: its transforms are
1634
+ * already what they were before the seal. The segment version moves, so a snapshot taken before
1635
+ * the transaction restores by replay ({@link restorePending}), which ends with the transaction's
1636
+ * actions gone once the caller rolls it back. */
1637
+ unseal(entryId) {
1638
+ this.segments.unseal(entryId);
1639
+ }
1640
+ /** Whether this collection's committed context names `attempt.actionId` at `attempt.rev`: the
1641
+ * write that attempt sent is committed here, and this handle has adopted it. This is how a restore
1642
+ * after a restart recognises, before re-staging a journaled segment, that the segment's network
1643
+ * commit landed and the crash came after it (docs/offline-sync.md §Restore after a restart):
1644
+ * re-staging such a segment would run its own guards against its own committed rows (`absent`
1645
+ * refuses on a present key) and fail the entry with `constraint`, the opposite of the truth.
1646
+ * `false` for an invented collection, which has no context. Synchronous and latch-free.
1647
+ *
1648
+ * NOTE: `actionIdAt` reaches back only to the most recent checkpoint, and no checkpoint is written
1649
+ * today (backlog `debt-the-collection-log-never-writes-a-checkpoint`); if that changes, read the
1650
+ * log's entry at `attempt.rev` instead, since a committed attempt behind a checkpoint would
1651
+ * otherwise answer `false` and be re-staged against itself. */
1652
+ holdsCommitted(attempt) {
1653
+ const context = this.source.actionContext;
1654
+ return context !== undefined && context.rev >= attempt.rev && actionIdAt(context, attempt.rev) === attempt.actionId;
1655
+ }
1656
+ /**
1657
+ * Put a sealed segment back, holding `actions` under `entryId`, at `position` in the sealed list —
1658
+ * ahead of the segment `before` names, or last — and rebuild the tracker by replaying every
1659
+ * replayable segment in order ({@link replayActions}), for the offline queue's restore after a
1660
+ * restart (`OfflineQueue.restore`; docs/offline-sync.md §Restore after a restart). A record
1661
+ * restored late belongs ahead of entries queued since, in the queue and in each collection's
1662
+ * sealed list alike, or the head commit's "head is first" rule and the queue's order disagree;
1663
+ * hence insertion rather than appending, at the cost of the one replay every insertion costs.
1664
+ *
1665
+ * The replay records and reports each refusal it meets as a refresh's would — EXCEPT this
1666
+ * segment's own, which is recorded on the segment and RETURNED rather than reported through
1667
+ * `onSealedRefused`: the queue registers the entry and hears the result from its own `stage`
1668
+ * callback, since the collection cannot report it to a queue that does not yet list the entry. A
1669
+ * later segment the replay newly refuses (this segment inserts the key it also inserts, say) is
1670
+ * reported through `onSealedRefused` as any replay's would be.
1671
+ *
1672
+ * Takes the collection latch, like {@link dropSealed}. Throws before anything changes when the
1673
+ * open segment is non-empty (a transaction is open, and its actions were staged over state without
1674
+ * this segment; the only caller refuses to restore mid-transaction), when a head commit is in
1675
+ * flight ({@link SealedSegmentsError}, `in-flight`), when `entryId` is already sealed here, or when
1676
+ * `before` names no segment here. A replay error that is not a refusal (a block the replay could
1677
+ * not read, say) propagates with the segment REMOVED again: the caller's restore rolls back and
1678
+ * may try this entry again later, which would otherwise meet its own segment as "already sealed".
1679
+ * The tracker is then half re-staged, the state a refresh's replay that throws leaves too (backlog
1680
+ * `debt-a-failed-refresh-can-leave-a-collection-half-restaged`); the next replay rebuilds it.
1681
+ *
1682
+ * @returns this segment's own refusal, when the replay refused it; `undefined` when it staged. */
1683
+ async restoreSealed(entryId, actions, position) {
1684
+ const release = await Latches.acquire(this.latchId);
1685
+ try {
1686
+ if (this.segments.open.length > 0) {
1687
+ throw new Error(`Collection ${this.id}: cannot restore sealed segment ${entryId} while a transaction has `
1688
+ + `${this.segments.open.length} action(s) staged in the open segment`);
1689
+ }
1690
+ if (this.headInFlight !== undefined) {
1691
+ throw new SealedSegmentsError(this.id, this.segments.entryIds(), 'in-flight', this.headInFlight.entryId);
1692
+ }
1693
+ this.segments.insert(entryId, actions, position === 'last' ? undefined : position.before);
1694
+ try {
1695
+ await this.replayActions(entryId);
1696
+ }
1697
+ catch (err) {
1698
+ this.segments.drop(entryId);
1699
+ throw err;
1700
+ }
1701
+ return this.segments.find(entryId)?.refused;
1702
+ }
1703
+ finally {
1704
+ release();
1705
+ }
1706
+ }
1707
+ /** Remove the sealed segment owned by `entryId`, wherever it sits, and rebuild the tracker by
1708
+ * replaying what remains ({@link replayActions}). A later segment whose guard now refuses — one
1709
+ * that updated a row the dropped segment inserted, say — is recorded and reported through
1710
+ * `onSealedRefused` during that replay; cascading the removal through the queue's other
1711
+ * collections is the queue's job (docs/offline-sync.md §Removing an entry). Throws for an id
1712
+ * that is not sealed here, before anything changes, and {@link SealedSegmentsError} (`in-flight`)
1713
+ * for the segment a {@link commitHead} on this instance is carrying to the network — the only
1714
+ * segment that cannot be dropped while it waits, since the outcome being applied names it.
1715
+ * Another segment can be: the replay here rebuilds the live tracker, which the head commit's own
1716
+ * tracker does not depend on.
1717
+ *
1718
+ * Takes the collection latch, like {@link update}. */
1719
+ async dropSealed(entryId) {
1720
+ const release = await Latches.acquire(this.latchId);
1721
+ try {
1722
+ if (this.headInFlight?.entryId === entryId) {
1723
+ throw new SealedSegmentsError(this.id, this.segments.entryIds(), 'in-flight', entryId);
1724
+ }
1725
+ this.segments.drop(entryId);
1726
+ await this.replayActions();
1727
+ }
1728
+ finally {
1729
+ release();
1730
+ }
1731
+ }
1732
+ /** The refusal every whole-collection commit path makes while a segment is sealed (see
1733
+ * {@link SealedSegmentsError}). */
1734
+ assertNoSealedSegments() {
1735
+ if (this.segments.hasSealed()) {
1736
+ throw new SealedSegmentsError(this.id, this.segments.entryIds());
1737
+ }
1321
1738
  }
1322
1739
  /** The committed revision this collection currently READS at, or `undefined` for an
1323
1740
  * INVENTED collection that has never adopted a committed revision
@@ -1463,8 +1880,11 @@ export class Collection {
1463
1880
  * path, which is the same assumption the participant selection in
1464
1881
  * `TransactionCoordinator.commitOnce` and its `rollback` already rest on. If a second writer is
1465
1882
  * ever allowed to drive the SAME instance concurrently, this must become a per-attempt token (a
1466
- * mark object compared by identity, refusing to replace a live one) rather than a bare id. */
1467
- beginInFlightAction(actionId) {
1883
+ * mark object compared by identity, refusing to replace a live one) rather than a bare id.
1884
+ *
1885
+ * `cycle` is what every send of the cycle carries ({@link InFlightCycle}); a re-mark replaces it,
1886
+ * which is harmless because every caller re-marks with what it marked. */
1887
+ beginInFlightAction(actionId, cycle = {}) {
1468
1888
  if (this.inFlightActionId !== actionId) {
1469
1889
  // A different action's failed attempt cannot finish this one. Re-marking the SAME id (a
1470
1890
  // coordinator re-marks on every attempt) keeps what the previous attempt retained — that
@@ -1474,11 +1894,13 @@ export class Collection {
1474
1894
  this.mintedLogBlockIds = undefined;
1475
1895
  }
1476
1896
  this.inFlightActionId = actionId;
1897
+ this.inFlightCycle = cycle;
1477
1898
  return () => {
1478
1899
  if (this.inFlightActionId === actionId) {
1479
1900
  this.inFlightActionId = undefined;
1480
1901
  this.inFlightAttempt = undefined;
1481
1902
  this.mintedLogBlockIds = undefined;
1903
+ this.inFlightCycle = {};
1482
1904
  }
1483
1905
  };
1484
1906
  }
@@ -1489,12 +1911,12 @@ export class Collection {
1489
1911
  * a path that does not still never reports a half-landed write as saved (the refresh then
1490
1912
  * refuses with a `transforms-not-held` {@link TornActionError}), but it cannot recover from one.
1491
1913
  *
1492
- * A no-op unless `actionId` is the action currently marked, so a late call from an attempt whose
1493
- * cycle has already ended cannot plant transforms under somebody else's mark. Latch-free and
1914
+ * A no-op unless the attempt's action is the one currently marked, so a late call from an attempt
1915
+ * whose cycle has already ended cannot plant transforms under somebody else's mark. Latch-free and
1494
1916
  * synchronous, like the mark itself: `TransactionCoordinator` calls it from inside its commit
1495
1917
  * span, where it already holds this instance's latch. */
1496
- retainInFlightAttempt(actionId, attempt) {
1497
- if (this.inFlightActionId === actionId) {
1918
+ retainInFlightAttempt(attempt) {
1919
+ if (this.inFlightActionId === attempt.actionId) {
1498
1920
  this.inFlightAttempt = attempt;
1499
1921
  }
1500
1922
  }
@@ -1565,124 +1987,48 @@ export class Collection {
1565
1987
  release();
1566
1988
  }
1567
1989
  }
1990
+ /** The refresh a write's attempt cycle runs between attempts ({@link AttemptCycle.refreshUntilSettled}):
1991
+ * {@link updateInternal}, under the latch the write already holds and with its action marked in
1992
+ * flight, so the refresh recognises the write's own log entry. */
1993
+ refreshBetweenAttempts = (report, lastChance, tailFloor) => this.updateInternal(report, lastChance, tailFloor);
1568
1994
  /** Mints the one action id this sync reuses across all of its retry attempts, and owns it for
1569
1995
  * the WHOLE cycle — including the inter-attempt refresh, which is the only thing that reads it
1570
1996
  * (see {@link inFlightActionId}). `sync()`/`updateAndSync()` hold the collection latch across
1571
1997
  * all of this, so the mark's lifetime is contained inside the latched span here; the disposer
1572
1998
  * runs on every exit, including a throw out of retry exhaustion or an abort. */
1573
1999
  async syncInternal(options) {
1574
- const bytes = randomBytes(16);
1575
- const actionId = uint8ArrayToString(bytes, 'base64url');
1576
- // One timestamp for the WRITE, minted here beside the action id and for the same reason: an
1577
- // attempt that takes its own would make the retry's log block differ from the one the
1578
- // attempt it repeats may already have stored under this `(action id, revision)`.
1579
- const timestamp = Date.now();
1580
- const endInFlight = this.beginInFlightAction(actionId);
2000
+ // Before an action id is minted: a sync commits the whole tracker as one entry, and over
2001
+ // sealed segments that entry would carry several queue entries' effects.
2002
+ this.assertNoSealedSegments();
2003
+ const identity = {
2004
+ actionId: uint8ArrayToString(randomBytes(16), 'base64url'),
2005
+ // One timestamp for the WRITE, minted here beside the action id and for the same reason: an
2006
+ // attempt that takes its own would make the retry's log block differ from the one the
2007
+ // attempt it repeats may already have stored under this `(action id, revision)`.
2008
+ timestamp: Date.now(),
2009
+ };
2010
+ const endInFlight = this.beginInFlightAction(identity.actionId, { refuseSolo: options?.refuseSoloCommit });
1581
2011
  try {
1582
- return await this.syncAttempts(actionId, timestamp, options);
2012
+ return await this.syncAttempts(identity, options);
1583
2013
  }
1584
2014
  finally {
1585
2015
  endInFlight();
1586
2016
  }
1587
2017
  }
1588
- /** The retry loop behind {@link syncInternal}, run with `actionId` already marked in flight.
2018
+ /** The retry loop behind {@link syncInternal}, run with the action already marked in flight: the
2019
+ * attempt machinery of {@link AttemptCycle} and {@link stageAttempt}, aimed at the open segment
2020
+ * over the live tracker. {@link commitHead} drives the same machinery at the head segment.
1589
2021
  *
1590
- * @param timestamp the WRITE's time, stamped on the log entry every attempt appends — see
1591
- * {@link syncInternal}, which mints it.
1592
2022
  * @returns the durability of what this sync committed, or `undefined` when the loop never ran a
1593
2023
  * commit (nothing staged). See {@link sync}. */
1594
- async syncAttempts(actionId, timestamp, options) {
1595
- const maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
1596
- const baseBackoffMs = options?.baseBackoffMs ?? PendingRetryDelayMs;
1597
- const maxBackoffMs = options?.maxBackoffMs ?? DefaultMaxBackoffMs;
1598
- const maxStalledAttempts = options?.maxStalledAttempts ?? DefaultMaxStalledAttempts;
1599
- const deadlineMs = options?.deadlineMs;
1600
- const signal = options?.signal;
1601
- const startedAt = Date.now();
1602
- // Count of consecutive stale failures that made no forward progress. Reset to 0 on every
1603
- // successful transact, so the cap bounds only a persistently-failing sync — a legitimate
1604
- // large multi-batch sync (which iterates many times committing progress) never trips it.
1605
- let consecutiveFailures = 0;
1606
- let lastReason;
1607
- // Highest confirmed revision any responder has reported holding, accumulated with the
1608
- // codebase's single rule for picking among several candidates. Reported on the error, and
1609
- // the evidence the stall check below reasons from.
1610
- let lastStaleAt;
1611
- // Whether the failure most recently handled carried its OWN staleAt. A strike needs the
1612
- // responder to have re-confirmed the number this round, not merely an older observation
1613
- // left standing in `lastStaleAt`.
1614
- let lastFailureConfirmedStaleAt = false;
1615
- // Refused attempts of this write that carried their own staleAt. Never reset: a member counts
1616
- // its stale refusals per action for the action's whole life, and this is the writer's view of
1617
- // that count (see retryBackoffMs).
1618
- let confirmedLosses = 0;
1619
- // Consecutive refreshes that moved `getNextRev()` nowhere at all while a confirmed revision
1620
- // stood at or above it.
1621
- let consecutiveStalls = 0;
1622
- // The revision the PREVIOUS iteration would have requested, so the stall check can tell a
1623
- // refresh that moved nowhere from one that is still climbing toward the confirmed number.
1624
- let previousRequestedRev;
1625
- // Who holds what this sync has committed so far. Stays `undefined` while nothing has been
1626
- // committed, which is also the answer when the loop never runs at all — a sync with nothing
1627
- // staged writes nothing, and there is no durability to fabricate for it. Failed attempts never
1628
- // contribute: a refused attempt left nothing behind, so the answer is the committing attempt's.
1629
- let durability;
2024
+ async syncAttempts(identity, options) {
2025
+ const cycle = new AttemptCycle(this.id, this.instanceTag, options);
1630
2026
  while (this.hasUnsyncedChanges()) {
1631
- if (signal?.aborted) {
1632
- throw makeAbortError(signal);
1633
- }
1634
- // Progress-agnostic ceiling: give up if the wall-clock deadline passed. Deliberately
1635
- // ahead of the stall check: the deadline is the documented outer bound, so a sync that
1636
- // is both past it and stalled reports the deadline.
1637
- if (deadlineMs !== undefined && Date.now() - startedAt >= deadlineMs) {
1638
- throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason ?? 'deadline exceeded', lastStaleAt);
1639
- }
1640
- // Can the attempt about to run possibly differ from the one that just failed? Only when
1641
- // BOTH of these hold is the answer provably no:
1642
- //
1643
- // - The revision it would request is at or below one a responder CONFIRMED is taken. A
1644
- // producer sets `staleAt` only after reading that revision as durably held by someone
1645
- // else out of its own storage, revisions are one per-collection counter that every
1646
- // commit touches, and a confirmed revision never becomes un-taken (invalidation takes
1647
- // a NEW slot). So the request is already lost before it is sent.
1648
- // - The refresh in between moved the collection nowhere. `advanceContext` never lowers
1649
- // the held revision, so "nowhere" is exactly `requestedRev` unchanged since the last
1650
- // iteration. A refresh that moved forward WITHOUT clearing the confirmed number is a
1651
- // collection still climbing (it read a replica that lags the holder — the same
1652
- // partial catch-up `reportShortfall` exists to report), and its next attempt is a
1653
- // genuinely different request that may yet win.
1654
- //
1655
- // This is NOT a second answer to "is this failure retryable?" — `isConflictFailure`
1656
- // remains the sole rule for that, untouched. It only ever stops a loop that rule had
1657
- // already decided to continue.
1658
- const requestedRev = this.getNextRev();
1659
- const refreshMoved = previousRequestedRev !== undefined && requestedRev > previousRequestedRev;
1660
- previousRequestedRev = requestedRev;
1661
- if (lastStaleAt !== undefined) {
1662
- if (requestedRev > lastStaleAt.rev || refreshMoved) {
1663
- // Either the refresh adopted a revision above the confirmed one — ordinary
1664
- // contention, where the rival's commit is exactly what we just read — or it made
1665
- // partial forward progress. Both mean the next attempt differs. Not a stall.
1666
- consecutiveStalls = 0;
1667
- }
1668
- else if (lastFailureConfirmedStaleAt) {
1669
- consecutiveStalls++;
1670
- if (log.enabled) {
1671
- log('collection:sync-stalled id=%s tag=%s heldRev=%s requestedRev=%d staleBlock=%s staleRev=%d strike=%d of=%d', this.id, this.instanceTag, this.source.actionContext?.rev ?? 'none', requestedRev, lastStaleAt.blockId, lastStaleAt.rev, consecutiveStalls, maxStalledAttempts);
1672
- }
1673
- // Two strikes, not one: a legitimate loser can transiently read a view that has
1674
- // not yet caught up with the rival's commit, which looks identical for one round.
1675
- if (consecutiveStalls >= maxStalledAttempts) {
1676
- throw new SyncRevisionStalledError(this.id, consecutiveFailures, lastStaleAt, requestedRev, this.source.actionContext?.rev, lastReason);
1677
- }
1678
- }
1679
- // Else: the responder told us nothing new this round. No strike, and no reset either
1680
- // — the budget stays bounded by maxAttempts.
1681
- }
2027
+ cycle.beforeAttempt(this.getNextRev(), this.source.actionContext?.rev);
1682
2028
  // A pending action is never pended over a base that has moved under it — before EVERY
1683
2029
  // attempt, first and retries alike (see restageIfBasesMoved for why the retry needs it).
1684
- // NOTE: this is the one way the byte-identity the append below relies on can be broken at
1685
- // an UNCHANGED revision — a replay re-runs the action handlers, which mint fresh ids for
2030
+ // NOTE: this is the one way the byte-identity the append relies on can be broken at an
2031
+ // UNCHANGED revision — a replay re-runs the action handlers, which mint fresh ids for
1686
2032
  // whatever blocks they insert, so the retry sends different content under this write's
1687
2033
  // `(action id, revision)`. It needs a base to move without this collection adopting a
1688
2034
  // newer revision, which takes a block re-read that catches up while the log does not
@@ -1691,207 +2037,60 @@ export class Collection {
1691
2037
  // whose base moved. If that conjunction ever shows up in the field, the answer is to
1692
2038
  // abandon the action id and re-drive as a NEW write rather than to suppress the replay.
1693
2039
  await this.restageIfBasesMoved();
1694
- // Snapshot the pending actions so that any new actions aren't assumed to be part of this action
1695
- const pending = [...this.pending];
1696
- // Create a snapshot tracker for the action, so that we can ditch the log changes if we have to retry the action.
1697
- // It SHARES the live tracker's pin store: the snapshot inherits transforms by copy and never
1698
- // stages the data-block updates itself, so without the shared pins the digest pass below
1699
- // could only describe bases still resident in the read cache.
1700
- // NOTE: an attempt that ends in a stale failure is abandoned WITHOUT reset(), so the log
1701
- // tail/header bases its append pinned stay in the shared store until the live tracker's
1702
- // next reset. Bounded and harmless — a few log blocks per attempt, capped by maxAttempts,
1703
- // each re-validated against the source generation before any use — but if this loop ever
1704
- // grows a per-attempt footprint beyond the log blocks, reset the abandoned tracker on the
1705
- // stale-failure branch instead of letting the residue ride to the end of the sync.
1706
- const snapshot = copyTransforms(this.tracker.transforms);
1707
- const tracker = new Tracker(this.sourceCache, snapshot, this.tracker.pins);
1708
- // Add the action to the log (in local tracking space). The append is a fixed function of
1709
- // this write and the revision it is requesting: the timestamp was minted once for the
1710
- // whole write (syncInternal) and any data block the append has to mint takes the id an
1711
- // earlier attempt at this revision already minted (logAppendBlockIds).
1712
- const newRev = this.getNextRev();
1713
- const collectionLog = await Log.open(tracker, this.id, { newDataBlockId: this.logAppendBlockIds(tracker, actionId, newRev) });
1714
- if (!collectionLog) {
1715
- throw new Error(`Log not found for collection ${this.id}`);
1716
- }
1717
- const addResult = await collectionLog.addActions(pending, actionId, newRev, () => tracker.transformedBlockIds(), { timestamp });
1718
- // Declare what each touched block will contain once committed, computed from this snapshot
1719
- // tracker (which layers over `this.sourceCache`, so the peek/getCachedRevision probes are
1720
- // live). Purely local — an id whose base is not already cached is simply omitted and falls
1721
- // back to corroboration on the member side. Computed AFTER the log append so the log tail
1722
- // and header transforms this attempt just staged are digested too.
1723
- // NOTE: recomputed from scratch on every retry attempt (the snapshot tracker is rebuilt each
1724
- // iteration), so a sync that loses N races pays N full hashing passes over its touched
1725
- // blocks. Unmeasured and cheap relative to the round trips it is retrying; if a
1726
- // high-contention sync ever shows digest hashing in a profile, memoize per (id, staged ops).
1727
- const blockDigests = await computeBlockContentDigests(tracker, tracker.transformedBlockIds());
1728
- // The base each update-only block's operations were computed against, for the pend (see
1729
- // `PendRequest.baseRevs`): the tracker's pinned revisions, which `restageIfBasesMoved` at the
1730
- // top of this iteration has just re-judged, so a moved base was re-staged before it is named.
1731
- const baseRevs = tracker.stagedBaseRevs(tracker.transformedBlockIds());
1732
- // Commit the action to the transactor. Carry the aged retry priority derived from the
1733
- // consecutive-failure count so a sync that keeps losing concurrent races out-ranks fresh
1734
- // (priority-0) rivals in the cluster's resolveRace (fairness-only; capped at MaxPriority).
1735
- // First attempt has consecutiveFailures == 0, so priority 0 — the common pend is unchanged.
1736
- const attempt = await this.source.transact(tracker.transforms, actionId, newRev, this.id, addResult.tailPath.block.header.id, clampPriority(consecutiveFailures), blockDigests, baseRevs);
2040
+ // Snapshot the open segment so that any new actions aren't assumed to be part of this action
2041
+ // (no segment is sealed here — syncInternal refused if one was).
2042
+ const pending = [...this.segments.open];
2043
+ const staged = await this.buildAttempt({ actions: pending, transforms: this.tracker.transforms, pins: this.tracker.pins }, identity);
2044
+ const attempt = await this.send(staged, identity, cycle.priority());
1737
2045
  if (!attempt.success) {
1738
- if (isExpiryFailure(attempt)) {
1739
- // The next attempt's expiration comes from the same clock, so it would be refused the
1740
- // same way; stop here by name. Nothing on this instance has been touched — the attempt
1741
- // ran on a snapshot tracker — so the staged actions are still staged for a sync after
1742
- // the clock is fixed.
1743
- // NOTE: an expiry refusing a commit SWEEP (`NetworkTransactor.commitTailThenSweep`)
1744
- // arrives after the log tail was stored, and no refresh follows this throw, so that
1745
- // attempt's log entry stays behind with none of its data — the state the budget-exhausted
1746
- // exit below leaves too. Needs a sweep cohort whose clocks disagree while the tail's agree;
1747
- // tracked with the other leftover-entry exits in
1748
- // tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
1749
- throw new TransactionExpiredError(attempt.expired);
1750
- }
1751
- consecutiveFailures++;
1752
- lastReason = attempt.reason ?? lastReason;
1753
- // Highest-wins, not last-wins: the next request has to clear EVERY holder, so a later
1754
- // responder reporting a LOWER number understates the binding constraint. Same rule the
1755
- // producers and the transactor's aggregation already use.
1756
- lastStaleAt = highestStaleAt([lastStaleAt, attempt.staleAt]);
1757
- lastFailureConfirmedStaleAt = attempt.staleAt !== undefined;
1758
- if (lastFailureConfirmedStaleAt)
1759
- confirmedLosses++;
1760
- // Give up once the consecutive no-progress budget is exhausted, so a transactor that
1761
- // persistently rejects the sync can no longer hold the collection latch forever.
1762
- // NOTE: this also bounds the legitimate `pending`-wait case (retrying the same action
1763
- // while another commit is in flight), which used to retry indefinitely. Default 10
1764
- // attempts ≈ 21s of exponential backoff. If a high-contention workload legitimately
1765
- // needs to wait longer for a pending commit to clear, raise maxAttempts for that caller.
1766
- // NOTE: no refresh follows the LAST budgeted attempt, so if that attempt's log tail
1767
- // landed nobody finds out: the caller gets plain exhaustion over a log that holds an
1768
- // entry for this write. The write is still never reported saved, which is the rule; what
1769
- // is lost is the more specific name (TornActionError). The leftover entry itself is
1770
- // tracked in tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
1771
- if (consecutiveFailures >= maxAttempts) {
1772
- throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason, lastStaleAt);
1773
- }
1774
- // Keep exactly what this attempt sent. A refused commit is not proof nothing landed:
1775
- // the log tail is committed first and can be stored while the answer is still a
1776
- // failure, and `transact` has just cancelled every block that did not land. If the
1777
- // refresh below finds this attempt's own entry, these are the transforms that finish
1778
- // the action (see completeOwnEntry). The snapshot tracker is abandoned after this
1779
- // iteration, so its transforms are handed over as-is, uncopied.
1780
- this.retainInFlightAttempt(actionId, {
1781
- rev: newRev,
1782
- transforms: tracker.transforms,
1783
- tailId: addResult.tailPath.block.header.id,
1784
- ...(blockDigests === undefined ? {} : { blockDigests }),
1785
- ...baseRevsField(baseRevs),
1786
- });
1787
- // Refresh, and keep refreshing while it reports that this write's own half-landed
1788
- // action could not be finished YET. It must not fall through to a new attempt in that
1789
- // state: this action's log entry is already durable, and as soon as a refresh adopts a
1790
- // newer revision a new attempt appends a SECOND entry under the same action id — the
1791
- // duplicate consumeOwnEntry exists to prevent. (At an unchanged revision the rebuild
1792
- // is byte-identical — see logAppendBlockIds — so what is at stake is the second entry,
1793
- // not two versions of one tail block.) Each round is a failure against the same
1794
- // no-progress budget as a refused attempt.
1795
- // Whether the failure just handled was a loss to a rival already durably committed. Only
1796
- // the attempt's own refusal can say so; a refresh refused for a cause that can clear
1797
- // (below) is a race against something still in flight, and clears it.
1798
- let latestConfirmed = lastFailureConfirmedStaleAt;
1799
- for (;;) {
1800
- // Back off before every retry (any stale failure — reason/missing/pending), growing
1801
- // exponentially from the base delay up to the cap, with proportional random jitter so a
1802
- // herd of clients that lost the same race does not re-collide on the next tick (see
1803
- // utility/backoff.ts) — except once this write has lost to committed rivals often enough
1804
- // that a member holds the next slot for it (see retryBackoffMs). The abortable sleep lets
1805
- // an aborted sync reject promptly instead of finishing the sleep.
1806
- // NOTE: the `missing`/`reason` conflict paths now pay this backoff too (they previously
1807
- // retried with zero delay); that is what stops the persistent-`reason` hot spin. If a
1808
- // high-contention workload ever shows this base delay as recovery latency, lower
1809
- // baseBackoffMs for that caller rather than reintroducing the zero-delay retry.
1810
- const delay = retryBackoffMs(consecutiveFailures, confirmedLosses, latestConfirmed, { baseMs: baseBackoffMs, capMs: maxBackoffMs }, options?.rand);
1811
- await abortableDelay(delay, signal);
1812
- try {
1813
- // Fetch latest state - updateInternal() will call replayActions() if there are conflicts.
1814
- // This sync's actionId is marked in flight for the whole cycle (see syncInternal), so
1815
- // the refresh recognizes a log entry written by THIS action (its log tail landed but
1816
- // the commit answered failure), FINISHES that action from the attempt retained
1817
- // above, and only then consumes the entry rather than replaying it into a duplicate.
1818
- // The round that would spend the last of the budget settles a half-landed write
1819
- // instead of asking for another round, so the error that escapes below says
1820
- // whether the write can still land. (A deadline cannot be foreseen the same
1821
- // way; a write given up on it escapes unsettled, as `final: false`.)
1822
- // The highest revision a responder confirmed is taken rides out as the floor of
1823
- // the refresh's tail read, so a machine that has not caught up to it is not the
1824
- // last one asked (see updateInternal).
1825
- const report = {};
1826
- await this.updateInternal(report, consecutiveFailures + 1 >= maxAttempts, lastStaleAt?.rev);
1827
- const completed = report.ownEntryFinished?.durability;
1828
- if (completed !== undefined) {
1829
- // The refresh made this sync's write durable: that is a commit, and it is
1830
- // reported and counted exactly like one made by an attempt (see the success
1831
- // branch below for why batches fold to the weakest).
1832
- durability = durability === undefined ? completed : mergeDurability([durability, completed]);
1833
- consecutiveFailures = 0;
1834
- lastReason = undefined;
1835
- lastStaleAt = undefined;
1836
- lastFailureConfirmedStaleAt = false;
1837
- consecutiveStalls = 0;
1838
- }
1839
- break;
1840
- }
1841
- catch (err) {
1842
- if (!(err instanceof TornActionError) || err.reason !== 'completion-refused') {
1843
- throw err;
1844
- }
1845
- // Refused for a cause that can clear. The error already names the write as torn,
1846
- // which is the truth if the budget ends here — so it, not a plain exhaustion,
1847
- // is what escapes: the log holds an entry for a write that was not saved.
1848
- consecutiveFailures++;
1849
- lastReason = err.detail;
1850
- latestConfirmed = false;
1851
- if (consecutiveFailures >= maxAttempts
1852
- || (deadlineMs !== undefined && Date.now() - startedAt >= deadlineMs)) {
1853
- throw err;
1854
- }
1855
- }
1856
- }
2046
+ cycle.recordRefusal(attempt);
2047
+ this.retainInFlightAttempt(retainedAttempt(staged, identity.actionId));
2048
+ await cycle.refreshUntilSettled(this.refreshBetweenAttempts);
1857
2049
  }
1858
2050
  else {
1859
- // This attempt's commit landed, so its durability is the one to report. A sync that
1860
- // commits ONCE — every sync that has a caller today — reports exactly that answer,
1861
- // untouched. A sync whose loop commits more than one batch (the `hasUnsyncedChanges`
1862
- // condition re-entering after a successful commit) folds the batches with
1863
- // `mergeDurability`, whose scalar answer is the WEAKEST of them: one batch that only
1864
- // reached the writer makes the whole sync only-on-the-writer, and reporting the last
1865
- // batch's class instead would show such a write as saved.
1866
- durability = durability === undefined ? attempt.durability : mergeDurability([durability, attempt.durability]);
1867
- // Forward progress: reset the no-progress budget.
1868
- consecutiveFailures = 0;
1869
- lastReason = undefined;
1870
- lastStaleAt = undefined;
1871
- lastFailureConfirmedStaleAt = false;
1872
- consecutiveStalls = 0;
1873
- // Clear the pending actions that were part of this action
1874
- this.pending = this.pending.slice(pending.length);
1875
- // Reset cache and replay any actions that were added during the action
1876
- const transforms = tracker.reset();
1877
- // NOTE: this replay runs BEFORE the cache fold and the context bump below — the
1878
- // inverse of the order `updateInternal` and `TransactionCoordinator.commitOnce`
1879
- // both document as required, where the newly committed state must be visible
1880
- // before anything re-reads. Dormant today: `act()` and `syncInternal` take the
1881
- // same collection latch, so `this.pending` cannot grow during the transact above
1882
- // and the slice always leaves it empty, making this replay a no-op reset. If a
1883
- // path ever stages outside that latch, move the transformCache + actionContext
1884
- // lines above this replay — otherwise the replay re-reads at the superseded
1885
- // revision over a cache that has not yet seen the commit, and re-stages onto a
1886
- // root the commit already replaced.
2051
+ cycle.recordCommit(attempt.durability);
2052
+ // Clear the open-segment actions that were part of this action
2053
+ this.segments.open = this.segments.open.slice(pending.length);
2054
+ // Fold the committed transforms into the read cache and adopt the revision BEFORE
2055
+ // replaying whatever is still staged — the order `updateInternal` and
2056
+ // `TransactionCoordinator.commitOnceLatched` require, where the newly committed state
2057
+ // must be visible before anything re-reads. It is load-bearing here for an invented
2058
+ // collection's first commit: the replay resets to the invented baseline while no
2059
+ // context is adopted, so replaying first would reinstate the header insert over the
2060
+ // now-committed header and `hasUnsyncedChanges()` would never turn false. (While
2061
+ // `act()` shares this latch nothing new is staged mid-attempt, so the replay re-stages
2062
+ // nothing; {@link commitHead} stages while its transact is in flight and relies on
2063
+ // this order.)
2064
+ this.foldOwnCommit(staged, identity.actionId);
1887
2065
  await this.replayActions();
1888
- this.sourceCache.transformCache(transforms, newRev);
1889
- this.source.actionContext = this.source.actionContext
1890
- ? { committed: [...this.source.actionContext.committed, { actionId, rev: newRev }], rev: newRev }
1891
- : { committed: [{ actionId, rev: newRev }], rev: newRev };
1892
2066
  }
1893
2067
  }
1894
- return durability;
2068
+ return cycle.durability;
2069
+ }
2070
+ /** Build one attempt at the revision this collection would commit at next ({@link stageAttempt});
2071
+ * the ids its log append may have to mint come from {@link logAppendBlockIds}, so a retry at the
2072
+ * same revision appends the same entry. */
2073
+ buildAttempt(target, identity) {
2074
+ const rev = this.getNextRev();
2075
+ return stageAttempt(this.id, this.sourceCache, target, identity, rev, store => this.logAppendBlockIds(store, identity.actionId, rev));
2076
+ }
2077
+ /** Send one attempt — pend, then commit — under the cycle's aged retry `priority`, carrying what
2078
+ * the cycle asked of every send ({@link inFlightCycle}). */
2079
+ send(staged, identity, priority) {
2080
+ return this.source.transact(staged.tracker.transforms, identity.actionId, staged.rev, this.id, staged.tailId, {
2081
+ priority,
2082
+ blockDigests: staged.blockDigests,
2083
+ baseRevs: staged.baseRevs,
2084
+ refuseSolo: this.inFlightCycle.refuseSolo
2085
+ });
2086
+ }
2087
+ /** Fold a committed attempt's transforms — the log append included — into this instance's read
2088
+ * cache and adopt the revision it committed at. Every caller does this BEFORE replaying what is
2089
+ * still staged (see the note in {@link syncAttempts}). Takes the transforms out of the attempt's
2090
+ * tracker, which is finished with. */
2091
+ foldOwnCommit(staged, actionId) {
2092
+ this.sourceCache.transformCache(staged.tracker.reset(), staged.rev);
2093
+ this.recordCommitted(actionId, staged.rev);
1895
2094
  }
1896
2095
  /** Refresh from the transactor, then push. Same return contract as {@link sync}: the durability of
1897
2096
  * what was committed, or `undefined` when nothing was staged and so nothing was written. */
@@ -1905,6 +2104,282 @@ export class Collection {
1905
2104
  release();
1906
2105
  }
1907
2106
  }
2107
+ /** Commit exactly the head sealed segment — the oldest, `entryId` — as one log entry under the
2108
+ * action id and timestamp `options` supplies, for the offline-sync queue's drain
2109
+ * (docs/offline-sync.md §One entry, one network transaction): {@link openHeadCommit} followed by
2110
+ * the one-collection driver, `driveHeadCommit` in head-commit.ts, with the handle closed on every
2111
+ * exit. The attempt machinery is {@link syncAttempts}' ({@link AttemptCycle}, {@link stageAttempt});
2112
+ * what differs is the target — a head tracker ({@link headTrackerFor}) — and the latch, released
2113
+ * around the one network `await` ({@link HeadCommitHandle.release}). `options.recordAttempt` is
2114
+ * called with each attempt before it is sent, and `options.resume` hands back an attempt an
2115
+ * earlier cycle under the same action id recorded (see {@link HeadCommitOptions}).
2116
+ *
2117
+ * @returns what {@link sync} returns: who holds the commit, or `undefined` when the refresh
2118
+ * established that the write was already saved under `options.actionId` without re-sending.
2119
+ * @throws SealedSegmentsError before anything is done, when `entryId` is not the head segment
2120
+ * (`not-head`), carries a recorded refusal (`refused`), or a head commit is already in flight on
2121
+ * this instance (`in-flight`); the head segment's recorded refusal, an {@link ActionRefusedError},
2122
+ * when a refresh or the head tracker's staging refused it during the cycle; whatever
2123
+ * `options.recordAttempt` throws, before anything is sent; otherwise what {@link sync} throws. */
2124
+ async commitHead(entryId, options) {
2125
+ const handle = await this.openHeadCommit(entryId, { actionId: options.actionId, timestamp: options.timestamp }, {
2126
+ refuseSolo: options.refuseSoloCommit,
2127
+ ...(options.resume === undefined ? {} : { resume: options.resume }),
2128
+ ...(options.onCommittedHead === undefined ? {} : { onCommittedHead: options.onCommittedHead }),
2129
+ });
2130
+ try {
2131
+ return await driveHeadCommit(handle, options);
2132
+ }
2133
+ finally {
2134
+ handle.close();
2135
+ }
2136
+ }
2137
+ /** Open a head commit of `entryId` under `identity` and hand back the handle a driver runs it
2138
+ * through, step by step ({@link HeadCommitHandle}): this is {@link commitHead} with the loop left
2139
+ * to the caller, for the coordinator's per-entry commit over several collections, which runs each
2140
+ * step on every collection it wrote in lock-step. Takes the collection latch, which the handle
2141
+ * holds until its `close()` except around the network round trip; checks the three
2142
+ * preconditions; marks the action in flight for the whole cycle ({@link beginInFlightAction}), as
2143
+ * a sync's is, so the refresh between attempts recognises the write's own entry; sets
2144
+ * {@link headCommit}, which tells {@link consumeOwnEntry} that such an entry records the head
2145
+ * segment; and seeds the retained attempt with `options.resume` when one is given, so that the
2146
+ * opening refresh can finish an earlier cycle's torn attempt from it ({@link completeOwnEntry}) —
2147
+ * and `stage()` re-sends it verbatim while the next attempt would request its revision
2148
+ * ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}), recorded
2149
+ * with the in-flight mark, so the handle's `send()` and a refresh's re-send of a torn attempt both
2150
+ * carry it.
2151
+ *
2152
+ * **The target.** The live tracker holds every sealed segment and the open one, cumulatively, so
2153
+ * an attempt cannot run on a copy of it the way a sync's does. It runs on a HEAD TRACKER instead
2154
+ * ({@link headTrackerFor}): the head segment's actions alone, staged atomically over the
2155
+ * committed state, with pins of their own — built once per requested revision and reused across
2156
+ * attempts, since a rebuild mints fresh ids for the blocks the actions insert and would send
2157
+ * different content under one `(action id, revision)` (the rule {@link logAppendBlockIds}
2158
+ * closes). Staging runs the actions' guards against the committed state; a refusal there is the
2159
+ * segment's refusal, recorded and reported exactly as a replay's would be, and thrown out of
2160
+ * `stage()`.
2161
+ *
2162
+ * **The latch.** Held for every step EXCEPT the one `await` on the network, so `act`,
2163
+ * `sealPending`, `update` and the rest are not blocked behind a commit that can take seconds
2164
+ * (docs/offline-sync.md §The drain does not hold the collection latch across the network). While
2165
+ * it is released {@link headInFlight} is set: a refresh that walks into this commit's entry defers
2166
+ * to it, and `dropSealed` of the head refuses. A second head commit on this instance waits on the
2167
+ * latch and then meets the `in-flight` precondition.
2168
+ *
2169
+ * **The head's recorded refusal** is re-checked by `stage()` before every attempt and by
2170
+ * `refused()` after every refused send, because a refresh that adopted a rival — a reader's,
2171
+ * while the latch was released, or this cycle's own — may have replayed and refused it; each
2172
+ * throws the recorded refusal in place of another attempt. On success the driver calls `fold()`
2173
+ * (remove the head segment, bump the segment version, fold the attempt's transforms into the
2174
+ * cache and adopt its revision) and only THEN `replay()` (the remaining segments and the open
2175
+ * segment over the committed state that now holds the head) — the fold-before-replay order
2176
+ * {@link syncAttempts} takes, which anything staged while the commit was on the network relies on.
2177
+ *
2178
+ * A driver that opens handles on more than one collection opens them in sorted collection-id
2179
+ * order, the order `TransactionCoordinator.commitOnce` takes the same latches in; see the
2180
+ * interface.
2181
+ *
2182
+ * @throws Error before the latch is taken when `options.resume` was recorded under an action other than
2183
+ * `identity.actionId` — a caller defect, since the attempt would be re-sent under the wrong id;
2184
+ * SealedSegmentsError, with the latch released again, when `entryId` is not the head segment
2185
+ * (`not-head`), carries a recorded refusal (`refused`), or a head commit is already in flight on
2186
+ * this instance (`in-flight`). */
2187
+ async openHeadCommit(entryId, identity, options = {}) {
2188
+ const { resume, onCommittedHead, ...cycle } = options;
2189
+ if (resume !== undefined && resume.actionId !== identity.actionId) {
2190
+ throw new Error(`Collection ${this.id}: an attempt recorded under action ${resume.actionId} cannot resume `
2191
+ + `a head commit of ${entryId} under action ${identity.actionId}`);
2192
+ }
2193
+ const release = await Latches.acquire(this.latchId);
2194
+ try {
2195
+ this.assertHeadCommittable(entryId);
2196
+ }
2197
+ catch (err) {
2198
+ release();
2199
+ throw err;
2200
+ }
2201
+ const endInFlight = this.beginInFlightAction(identity.actionId, cycle);
2202
+ this.headCommit = { entryId, ...(onCommittedHead === undefined ? {} : { onCommitted: onCommittedHead }) };
2203
+ if (resume !== undefined) {
2204
+ this.retainInFlightAttempt(resume);
2205
+ }
2206
+ return this.headCommitHandle(entryId, identity, release, endInFlight, resume);
2207
+ }
2208
+ /** The handle {@link openHeadCommit} returns: closures over this instance's private state, so
2209
+ * nothing private becomes public. `release` is the latch release of the latch the caller took;
2210
+ * `endInFlight` the disposer of the in-flight mark. The head tracker lives here, per handle, so it
2211
+ * is reused across the attempts of one cycle exactly as the in-line loop reused it. `resume` is
2212
+ * the attempt the cycle was opened with, which `stage()` re-sends verbatim while the next attempt
2213
+ * would request its revision ({@link resumedAttempt}). */
2214
+ headCommitHandle(entryId, identity, release, endInFlight, resume) {
2215
+ let held = true;
2216
+ let closed = false;
2217
+ let head;
2218
+ const assertUsable = (step, needsLatch) => {
2219
+ if (closed) {
2220
+ throw new Error(`Collection ${this.id}: head commit of ${entryId} is closed; ${step}() is a defect`);
2221
+ }
2222
+ if (held !== needsLatch) {
2223
+ throw new Error(`Collection ${this.id}: head commit of ${entryId} ${held ? 'holds' : 'has released'} the latch; `
2224
+ + `${step}() is a defect here`);
2225
+ }
2226
+ };
2227
+ return {
2228
+ collectionId: this.id,
2229
+ instanceTag: this.instanceTag,
2230
+ entryId,
2231
+ refresh: (report, lastChance, tailFloor) => {
2232
+ assertUsable('refresh', true);
2233
+ return this.updateInternal(report, lastChance, tailFloor);
2234
+ },
2235
+ nextRev: () => this.getNextRev(),
2236
+ heldRev: () => this.source.actionContext?.rev,
2237
+ stage: async () => {
2238
+ assertUsable('stage', true);
2239
+ const segment = this.committableHead(entryId);
2240
+ const resumed = resumedAttempt(this.sourceCache, resume, this.getNextRev());
2241
+ if (resumed !== undefined) {
2242
+ return resumed;
2243
+ }
2244
+ head = await this.headTrackerFor(segment, head);
2245
+ return this.buildAttempt({ actions: segment.actions, transforms: head.tracker.transforms, pins: head.tracker.pins }, identity);
2246
+ },
2247
+ send: (staged, priority) => {
2248
+ assertUsable('send', false);
2249
+ return this.send(staged, identity, priority);
2250
+ },
2251
+ release: () => {
2252
+ assertUsable('release', true);
2253
+ this.headInFlight = { entryId, actionId: identity.actionId };
2254
+ held = false;
2255
+ release();
2256
+ },
2257
+ retake: async () => {
2258
+ assertUsable('retake', false);
2259
+ const retaken = await Latches.acquire(this.latchId);
2260
+ if (closed) {
2261
+ // close() ran while the latch was being acquired: it has already cleared the marks
2262
+ // latch-free, so keeping this latch would leak it for the life of the instance.
2263
+ retaken();
2264
+ throw new Error(`Collection ${this.id}: head commit of ${entryId} was closed while retake() was waiting; `
2265
+ + `a driver closes its handle only after retaking`);
2266
+ }
2267
+ release = retaken;
2268
+ held = true;
2269
+ this.headInFlight = undefined;
2270
+ },
2271
+ fold: (staged) => {
2272
+ assertUsable('fold', true);
2273
+ const dropped = this.segments.drop(this.headSegment(entryId).entryId);
2274
+ this.foldOwnCommit(staged, identity.actionId);
2275
+ this.reportCommittedHead(dropped);
2276
+ },
2277
+ replay: () => {
2278
+ assertUsable('replay', true);
2279
+ // NOTE: the remaining sealed segments and the open segment are replayed after EVERY head
2280
+ // commit, so draining a queue of n entries is quadratic in n (docs/offline-sync.md
2281
+ // §Failure modes and accepted tradeoffs). Negligible for tens of entries; if it shows up
2282
+ // for a device that queued thousands, keep per-segment trackers chained over the cache,
2283
+ // so a committed head is popped and folded instead of replayed.
2284
+ return this.replayActions();
2285
+ },
2286
+ refused: (staged) => {
2287
+ assertUsable('refused', true);
2288
+ this.committableHead(entryId);
2289
+ this.retainInFlightAttempt(retainedAttempt(staged, identity.actionId));
2290
+ },
2291
+ close: () => {
2292
+ if (closed)
2293
+ return;
2294
+ closed = true;
2295
+ this.headCommit = undefined;
2296
+ this.headInFlight = undefined;
2297
+ endInFlight();
2298
+ if (held) {
2299
+ held = false;
2300
+ release();
2301
+ }
2302
+ },
2303
+ };
2304
+ }
2305
+ /** {@link commitHead}'s preconditions, each a {@link SealedSegmentsError} naming its reason. */
2306
+ assertHeadCommittable(entryId) {
2307
+ const sealed = this.segments.entryIds();
2308
+ const head = this.segments.head();
2309
+ if (head === undefined || head.entryId !== entryId) {
2310
+ throw new SealedSegmentsError(this.id, sealed, 'not-head', entryId);
2311
+ }
2312
+ if (head.refused !== undefined) {
2313
+ throw new SealedSegmentsError(this.id, sealed, 'refused', entryId);
2314
+ }
2315
+ if (this.headInFlight !== undefined) {
2316
+ throw new SealedSegmentsError(this.id, sealed, 'in-flight', this.headInFlight.entryId);
2317
+ }
2318
+ }
2319
+ /** The head segment, which a running head commit may still commit: it is `entryId` — anything
2320
+ * else is a defect ({@link headSegment}) — and it has not been refused meanwhile. A refresh that
2321
+ * adopted a rival may have replayed and refused it, and that refusal, not another attempt, is
2322
+ * then the cycle's answer. */
2323
+ committableHead(entryId) {
2324
+ const head = this.headSegment(entryId);
2325
+ if (head.refused !== undefined) {
2326
+ throw head.refused;
2327
+ }
2328
+ return head;
2329
+ }
2330
+ /** The head segment, asserted to be `entryId`. Nothing may remove the head while a head commit
2331
+ * of it runs — a refresh that meets it defers, `dropSealed` of it refuses — so anything else here
2332
+ * is a defect, thrown as one. */
2333
+ headSegment(entryId) {
2334
+ const head = this.segments.head();
2335
+ if (head === undefined || head.entryId !== entryId) {
2336
+ throw new Error(`Collection ${this.id}: head segment ${entryId} was removed while its commit was running `
2337
+ + `(the head is ${head?.entryId ?? 'nothing'})`);
2338
+ }
2339
+ return head;
2340
+ }
2341
+ /** The tracker a head attempt is built from (see {@link commitHead}): `current`, while it was
2342
+ * built for the revision the next attempt requests and no base under it has moved; otherwise a
2343
+ * fresh one ({@link buildHeadTracker}). A revision that moved is a write that is genuinely
2344
+ * different. A base that moved at the same revision is re-judged exactly as
2345
+ * {@link restageIfBasesMoved} re-judges the live queue before an attempt, and rebuilds.
2346
+ * NOTE: that rebuild is the same exception to the byte-identical retry that {@link syncAttempts}
2347
+ * records at its `restageIfBasesMoved` call — fresh ids for the blocks the actions insert under
2348
+ * an unchanged `(action id, revision)` — reached the same narrow way and refused by storage's
2349
+ * base guard on the same machines; the same answer applies if it is ever seen. */
2350
+ async headTrackerFor(segment, current) {
2351
+ const rev = this.getNextRev();
2352
+ if (current?.rev === rev) {
2353
+ await this.rereadUnretainedBases(current.tracker);
2354
+ if (this.logMovedBases(current.tracker.movedBases()) === 0) {
2355
+ return current;
2356
+ }
2357
+ }
2358
+ return { rev, tracker: await this.buildHeadTracker(segment) };
2359
+ }
2360
+ /** A tracker over this instance's read cache, with pins of its own, holding `segment`'s actions
2361
+ * staged atomically over the committed state — from the invented baseline while this collection
2362
+ * has no committed revision ({@link replayBaseline}): its header, log block and root then exist
2363
+ * nowhere else, and the head's commit has to carry them. A refusal is the segment's own,
2364
+ * recorded and reported ({@link recordSealedRefusal}) and thrown; a live replay that found it
2365
+ * first has already done the recording, and the caller never gets here. */
2366
+ async buildHeadTracker(segment) {
2367
+ const tracker = new Tracker(this.sourceCache, this.replayBaseline());
2368
+ try {
2369
+ segment.applied = await this.stageInto(tracker, ...segment.actions);
2370
+ }
2371
+ catch (err) {
2372
+ if (err instanceof ActionRefusedError) {
2373
+ // NOTE: the live tracker still holds this segment's effects from its last replay, which
2374
+ // judged the same committed state and did not refuse; a reader sees them until the next
2375
+ // replay (the queue's drop of the refused segment). Reachable only if a base re-read
2376
+ // catches up between the two stagings; if that is ever seen, replay here after recording.
2377
+ this.recordSealedRefusal(segment, err);
2378
+ }
2379
+ throw err;
2380
+ }
2381
+ return tracker;
2382
+ }
1908
2383
  /** Stage `actions` and flush them as one call that either takes effect or leaves NOTHING behind:
1909
2384
  * when the flush throws, the actions this call staged are unstaged again before the error escapes.
1910
2385
  *
@@ -1926,6 +2401,9 @@ export class Collection {
1926
2401
  async actAndSync(actions, options) {
1927
2402
  const release = await Latches.acquire(this.latchId);
1928
2403
  try {
2404
+ // Refused before staging, so there is nothing to unstage: the sync below would refuse
2405
+ // anyway (syncInternal), and staging first would only have to be taken back.
2406
+ this.assertNoSealedSegments();
1929
2407
  const stagedBefore = copyTransforms(this.tracker.transforms);
1930
2408
  const revBefore = this.source.actionContext?.rev;
1931
2409
  await this.actInternal(...actions);
@@ -1947,18 +2425,19 @@ export class Collection {
1947
2425
  * revision from before the actions were staged.
1948
2426
  *
1949
2427
  * While the held revision has not moved, the earlier transforms are reinstated verbatim rather
1950
- * than rebuilt by replay: an INVENTED collection keeps its header and root in the tracker with
1951
- * no staged action naming them, and a replay (which resets the tracker first) would drop them —
1952
- * the hazard {@link mustReplay} and {@link snapshotPending} document. Once the revision has
1953
- * moved those transforms describe blocks at a revision this handle has left, so what remains is
1954
- * re-staged against the adopted one, exactly as a refresh would have done. */
2428
+ * than rebuilt by replay: they are exactly the state before the call, and reinstating them costs
2429
+ * no handler run (a replay would rebuild the same state from {@link inventedBaseline} and the
2430
+ * staged actions). Once the revision has moved those transforms describe blocks at a revision
2431
+ * this handle has left, so what remains is re-staged against the adopted one, exactly as a
2432
+ * refresh would have done. */
1955
2433
  async unstage(actions, stagedBefore, revBefore) {
1956
2434
  // NOTE: matched by identity, which is what `filterAgainstEntry` promises for a kept action.
1957
2435
  // A `filterConflict` hook that answers a REPLACEMENT instance for one of these actions would
1958
2436
  // leave the replacement staged here. No collection installs such a hook today (`Tree` and
1959
2437
  // `Diary` install none); if one ever does, carry a per-call token on the staged actions and
1960
2438
  // match on that instead.
1961
- this.pending = this.pending.filter(staged => !actions.includes(staged));
2439
+ // The actions were staged into the OPEN segment (actAndSync refuses over sealed segments).
2440
+ this.segments.open = this.segments.open.filter(staged => !actions.includes(staged));
1962
2441
  if (this.source.actionContext?.rev === revBefore) {
1963
2442
  this.tracker.reset(stagedBefore);
1964
2443
  }
@@ -1979,13 +2458,67 @@ export class Collection {
1979
2458
  }
1980
2459
  }
1981
2460
  }
1982
- async replayActions() {
1983
- this.tracker.reset();
1984
- // Replay pending actions against the fresh tracker state (always called under latch)
1985
- for (const action of this.pending) {
2461
+ /** Rebuild the tracker from the staged actions over the committed state this collection now
2462
+ * reads at (always called under latch): reset to {@link replayBaseline}, then every sealed
2463
+ * segment in order, then the open segment.
2464
+ *
2465
+ * A SEALED segment is staged as ONE atomic unit — one `internalTransact` call over all of its
2466
+ * actions — so a refusal of any action in it leaves none of its writes staged, and a refusal
2467
+ * ({@link ActionRefusedError}, the only class caught) is that segment's own: recorded on it,
2468
+ * reported through `onSealedRefused`, and the replay goes on to the next segment. A segment
2469
+ * already refused is skipped and not reported again; it stays listed until dropped. The OPEN
2470
+ * segment keeps the pre-segment behaviour: one `internalTransact` per action, and a refusal
2471
+ * propagates, since it is the live transaction's own (docs/offline-sync.md §Replay with a
2472
+ * per-segment refusal). Any error that is not a refusal propagates from either.
2473
+ *
2474
+ * Each re-staged update pins its base through `Atomic.commit` → `Tracker.absorb`, the path
2475
+ * {@link act} uses, so the pend declares the bases the re-staged operations were computed on. Each
2476
+ * sealed segment that staged records what its actions accepted as already applied
2477
+ * (`SealedSegment.applied`), the tally the head commit reports when the segment is committed.
2478
+ *
2479
+ * @param unreported - a segment whose refusal is recorded but NOT reported through
2480
+ * `onSealedRefused`: the one {@link restoreSealed} is inserting, whose caller reads the recorded
2481
+ * refusal off the segment itself. */
2482
+ async replayActions(unreported) {
2483
+ this.tracker.reset(this.replayBaseline());
2484
+ for (const segment of this.segments.replayable()) {
2485
+ try {
2486
+ segment.applied = await this.internalTransact(...segment.actions);
2487
+ }
2488
+ catch (err) {
2489
+ if (!(err instanceof ActionRefusedError)) {
2490
+ throw err;
2491
+ }
2492
+ this.recordSealedRefusal(segment, err, segment.entryId !== unreported);
2493
+ }
2494
+ }
2495
+ for (const action of this.segments.open) {
1986
2496
  await this.internalTransact(action);
1987
2497
  }
1988
2498
  }
2499
+ /** What a replay resets the tracker to: a copy of {@link inventedBaseline} while this collection
2500
+ * holds no committed revision (those blocks exist nowhere else), and nothing otherwise. */
2501
+ replayBaseline() {
2502
+ return this.source.actionContext === undefined && this.inventedBaseline !== undefined
2503
+ ? copyTransforms(this.inventedBaseline)
2504
+ : emptyTransforms();
2505
+ }
2506
+ /** Record a replay's refusal of a sealed segment and, when `report` says so, report it once,
2507
+ * under the latch. The callback's throw is logged rather than raised: the refusal is already
2508
+ * recorded, and the rest of the replay must still run. */
2509
+ recordSealedRefusal(segment, error, report = true) {
2510
+ this.segments.refuse(segment.entryId, error);
2511
+ log('collection:sealed-segment-refused id=%s tag=%s entry=%s reported=%s error=%s', this.id, this.instanceTag, segment.entryId, report, error.message);
2512
+ if (!report) {
2513
+ return;
2514
+ }
2515
+ try {
2516
+ this.onSealedRefused?.(segment.entryId, error);
2517
+ }
2518
+ catch (err) {
2519
+ log('collection:refusal-callback-threw id=%s tag=%s entry=%s error=%s', this.id, this.instanceTag, segment.entryId, err instanceof Error ? err.message : String(err));
2520
+ }
2521
+ }
1989
2522
  getReadDependencies() {
1990
2523
  return this.source.getReadDependencies();
1991
2524
  }
@@ -2008,13 +2541,9 @@ export class Collection {
2008
2541
  * than kept, because nothing proves it is current at the revision the refresh will pin to.
2009
2542
  *
2010
2543
  * Both answers pass {@link answeredBlock}'s checks as unpinned reads, header first, so a doubted
2011
- * header or tail throws exactly as it would through {@link TransactorSource.tryGet}.
2012
- *
2013
- * NOTE: a batched get fails as a whole when any block in it gets no answer
2014
- * (`NetworkTransactor.get` throws on a missing id), so an unreachable out-of-date tail fails a
2015
- * refresh that would not have needed it. Harmless today: the log has no checkpoints, so a
2016
- * refresh that finds a new tail walks back through the old one anyway. If checkpoints start
2017
- * letting that walk stop short, read the known tail in its own request instead.
2544
+ * header or tail throws exactly as it would through {@link TransactorSource.tryGet}. An
2545
+ * out-of-date tail no coordinator answered comes back flagged (`NetworkTransactor.get` flags that
2546
+ * one block rather than failing the request), and its answer is dropped unjudged.
2018
2547
  *
2019
2548
  * `tailFloor` (see {@link updateInternal}) goes on whichever request reads the tail — never on
2020
2549
  * the header, which is rewritten only when the tail rolls over or the collection changes it
@@ -2035,15 +2564,12 @@ export class Collection {
2035
2564
  blockIds: knownTailId === undefined ? [id] : [id, knownTailId],
2036
2565
  ...Collection.tailFloorField(knownTailId, tailFloor),
2037
2566
  });
2038
- const headerEntry = results?.[id];
2039
- if (headerEntry === undefined) {
2567
+ const answered = Collection.answeredHeader(id, results?.[id]);
2568
+ if (answered === undefined) {
2040
2569
  return undefined;
2041
2570
  }
2042
- const header = answeredBlock(id, headerEntry, undefined);
2043
- if (!header) {
2044
- return undefined;
2045
- }
2046
- const served = [[id, header, servedRevision(headerEntry)]];
2571
+ const { header } = answered;
2572
+ const served = [[id, header, answered.servedRev]];
2047
2573
  const tailId = header.tailId;
2048
2574
  if (tailId === undefined) {
2049
2575
  return { header, served };
@@ -2056,6 +2582,69 @@ export class Collection {
2056
2582
  }
2057
2583
  return { header, tail, served };
2058
2584
  }
2585
+ /** The header a repo answered for collection `id`, judged as an unpinned read, with the
2586
+ * revision it was served at. `undefined` when it is authoritatively absent — no entry, or one
2587
+ * with no block; a throw when the repo could not retrieve it or could not confirm it current
2588
+ * ({@link answeredBlock}). */
2589
+ static answeredHeader(id, entry) {
2590
+ if (entry === undefined) {
2591
+ return undefined;
2592
+ }
2593
+ const header = answeredBlock(id, entry, undefined);
2594
+ return header ? { header, servedRev: servedRevision(entry) } : undefined;
2595
+ }
2596
+ /** The committed tail a header naming `tailId` describes, given the repo's answer for that
2597
+ * block: `undefined` when the block has no committed revision (nothing committed yet). */
2598
+ static committedTailOf(tailId, tail) {
2599
+ const rev = tail?.state.latest?.rev;
2600
+ return rev === undefined ? undefined : { tailId, rev };
2601
+ }
2602
+ /** The committed tail `tailId` names, read out of `reads` and checked as {@link checkedLogTail}
2603
+ * describes; `undefined` for no tail id. Throws the block's failed read, or a doubted answer. */
2604
+ static judgedTail(tailId, reads) {
2605
+ return tailId === undefined
2606
+ ? undefined
2607
+ : Collection.committedTailOf(tailId, Collection.checkedLogTail(tailId, Collection.entryIn(reads, tailId)));
2608
+ }
2609
+ /** The repo's entry for `id` in `reads`, or the error reading it failed with, thrown. */
2610
+ static entryIn(reads, id) {
2611
+ const read = reads.get(id);
2612
+ if (read !== undefined && 'error' in read) {
2613
+ throw read.error;
2614
+ }
2615
+ return read?.entry;
2616
+ }
2617
+ /** Unpinned reads of `blockIds` in ONE request, each block's answer kept apart. When that
2618
+ * request throws, each block is read in a request of its own — concurrently — so the failure
2619
+ * lands on the blocks it belongs to and every other block still answers.
2620
+ *
2621
+ * NOTE: the fallback is unbounded — two gets per collection at once, only after a failed
2622
+ * request. Fine for the tens of tables a host watches; if callers ever name hundreds, read the
2623
+ * fallback in bounded batches. */
2624
+ static async readAttributed(transactor, blockIds) {
2625
+ if (blockIds.length === 0) {
2626
+ return new Map();
2627
+ }
2628
+ try {
2629
+ const results = await transactor.get({ blockIds });
2630
+ return new Map(blockIds.map(id => [id, { entry: results?.[id] }]));
2631
+ }
2632
+ catch (error) {
2633
+ if (blockIds.length === 1) {
2634
+ return new Map([[blockIds[0], { error }]]);
2635
+ }
2636
+ log('collection:tails-read-split blocks=%d error=%o', blockIds.length, error);
2637
+ return new Map(await Promise.all(blockIds.map(async (id) => [id, await Collection.readAlone(transactor, id)])));
2638
+ }
2639
+ }
2640
+ static async readAlone(transactor, id) {
2641
+ try {
2642
+ return { entry: (await transactor.get({ blockIds: [id] }))?.[id] };
2643
+ }
2644
+ catch (error) {
2645
+ return { error };
2646
+ }
2647
+ }
2059
2648
  /** An unpinned read of the log tail block, checked as {@link checkedLogTail} describes, carrying
2060
2649
  * `tailFloor` when the caller has one (see {@link readLogEnds}). */
2061
2650
  static async readLogTail(transactor, tailId, tailFloor) {