@optimystic/db-core 1.19.0 → 1.20.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (171) hide show
  1. package/dist/src/cluster/structs.d.ts +41 -8
  2. package/dist/src/cluster/structs.d.ts.map +1 -1
  3. package/dist/src/cluster/structs.js +18 -7
  4. package/dist/src/cluster/structs.js.map +1 -1
  5. package/dist/src/collection/action.d.ts +29 -0
  6. package/dist/src/collection/action.d.ts.map +1 -1
  7. package/dist/src/collection/action.js +6 -0
  8. package/dist/src/collection/action.js.map +1 -1
  9. package/dist/src/collection/collection.d.ts +533 -120
  10. package/dist/src/collection/collection.d.ts.map +1 -1
  11. package/dist/src/collection/collection.js +974 -500
  12. package/dist/src/collection/collection.js.map +1 -1
  13. package/dist/src/collection/head-commit.d.ts +110 -0
  14. package/dist/src/collection/head-commit.d.ts.map +1 -0
  15. package/dist/src/collection/head-commit.js +65 -0
  16. package/dist/src/collection/head-commit.js.map +1 -0
  17. package/dist/src/collection/index.d.ts +2 -0
  18. package/dist/src/collection/index.d.ts.map +1 -1
  19. package/dist/src/collection/index.js +2 -0
  20. package/dist/src/collection/index.js.map +1 -1
  21. package/dist/src/collection/segments.d.ts +77 -0
  22. package/dist/src/collection/segments.d.ts.map +1 -0
  23. package/dist/src/collection/segments.js +110 -0
  24. package/dist/src/collection/segments.js.map +1 -0
  25. package/dist/src/collection/struct.d.ts +156 -1
  26. package/dist/src/collection/struct.d.ts.map +1 -1
  27. package/dist/src/collection/struct.js +70 -0
  28. package/dist/src/collection/struct.js.map +1 -1
  29. package/dist/src/collection/write-attempts.d.ts +245 -0
  30. package/dist/src/collection/write-attempts.d.ts.map +1 -0
  31. package/dist/src/collection/write-attempts.js +439 -0
  32. package/dist/src/collection/write-attempts.js.map +1 -0
  33. package/dist/src/collections/tree/struct.d.ts +100 -17
  34. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  35. package/dist/src/collections/tree/struct.js +38 -7
  36. package/dist/src/collections/tree/struct.js.map +1 -1
  37. package/dist/src/collections/tree/tree.d.ts +17 -5
  38. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  39. package/dist/src/collections/tree/tree.js +112 -26
  40. package/dist/src/collections/tree/tree.js.map +1 -1
  41. package/dist/src/index.d.ts +2 -0
  42. package/dist/src/index.d.ts.map +1 -1
  43. package/dist/src/index.js +2 -0
  44. package/dist/src/index.js.map +1 -1
  45. package/dist/src/network/i-repo.d.ts +3 -0
  46. package/dist/src/network/i-repo.d.ts.map +1 -1
  47. package/dist/src/network/index.d.ts +3 -0
  48. package/dist/src/network/index.d.ts.map +1 -1
  49. package/dist/src/network/index.js +3 -0
  50. package/dist/src/network/index.js.map +1 -1
  51. package/dist/src/network/promise-shortfall-error.d.ts +40 -0
  52. package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
  53. package/dist/src/network/promise-shortfall-error.js +67 -0
  54. package/dist/src/network/promise-shortfall-error.js.map +1 -0
  55. package/dist/src/network/refuse-solo.d.ts +8 -0
  56. package/dist/src/network/refuse-solo.d.ts.map +1 -0
  57. package/dist/src/network/refuse-solo.js +8 -0
  58. package/dist/src/network/refuse-solo.js.map +1 -0
  59. package/dist/src/network/stale-failure.d.ts +20 -3
  60. package/dist/src/network/stale-failure.d.ts.map +1 -1
  61. package/dist/src/network/stale-failure.js +24 -3
  62. package/dist/src/network/stale-failure.js.map +1 -1
  63. package/dist/src/network/struct.d.ts +148 -2
  64. package/dist/src/network/struct.d.ts.map +1 -1
  65. package/dist/src/network/struct.js.map +1 -1
  66. package/dist/src/network/validity-rejected-error.d.ts +28 -0
  67. package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
  68. package/dist/src/network/validity-rejected-error.js +51 -0
  69. package/dist/src/network/validity-rejected-error.js.map +1 -0
  70. package/dist/src/offline/entry.d.ts +72 -0
  71. package/dist/src/offline/entry.d.ts.map +1 -0
  72. package/dist/src/offline/entry.js +73 -0
  73. package/dist/src/offline/entry.js.map +1 -0
  74. package/dist/src/offline/index.d.ts +5 -0
  75. package/dist/src/offline/index.d.ts.map +1 -0
  76. package/dist/src/offline/index.js +5 -0
  77. package/dist/src/offline/index.js.map +1 -0
  78. package/dist/src/offline/journal.d.ts +61 -0
  79. package/dist/src/offline/journal.d.ts.map +1 -0
  80. package/dist/src/offline/journal.js +2 -0
  81. package/dist/src/offline/journal.js.map +1 -0
  82. package/dist/src/offline/queue.d.ts +484 -0
  83. package/dist/src/offline/queue.d.ts.map +1 -0
  84. package/dist/src/offline/queue.js +1236 -0
  85. package/dist/src/offline/queue.js.map +1 -0
  86. package/dist/src/offline/reachability.d.ts +25 -0
  87. package/dist/src/offline/reachability.d.ts.map +1 -0
  88. package/dist/src/offline/reachability.js +13 -0
  89. package/dist/src/offline/reachability.js.map +1 -0
  90. package/dist/src/offline/status.d.ts +148 -0
  91. package/dist/src/offline/status.d.ts.map +1 -0
  92. package/dist/src/offline/status.js +63 -0
  93. package/dist/src/offline/status.js.map +1 -0
  94. package/dist/src/offline/wake.d.ts +30 -0
  95. package/dist/src/offline/wake.d.ts.map +1 -0
  96. package/dist/src/offline/wake.js +68 -0
  97. package/dist/src/offline/wake.js.map +1 -0
  98. package/dist/src/testing/test-transactor.d.ts +29 -0
  99. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  100. package/dist/src/testing/test-transactor.js +50 -0
  101. package/dist/src/testing/test-transactor.js.map +1 -1
  102. package/dist/src/transaction/commit-failure-class.d.ts +103 -0
  103. package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
  104. package/dist/src/transaction/commit-failure-class.js +96 -0
  105. package/dist/src/transaction/commit-failure-class.js.map +1 -0
  106. package/dist/src/transaction/coordinator.d.ts +165 -41
  107. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  108. package/dist/src/transaction/coordinator.js +605 -300
  109. package/dist/src/transaction/coordinator.js.map +1 -1
  110. package/dist/src/transaction/entry-commit.d.ts +139 -0
  111. package/dist/src/transaction/entry-commit.d.ts.map +1 -0
  112. package/dist/src/transaction/entry-commit.js +199 -0
  113. package/dist/src/transaction/entry-commit.js.map +1 -0
  114. package/dist/src/transaction/index.d.ts +4 -1
  115. package/dist/src/transaction/index.d.ts.map +1 -1
  116. package/dist/src/transaction/index.js +1 -0
  117. package/dist/src/transaction/index.js.map +1 -1
  118. package/dist/src/transaction/transaction.d.ts +20 -0
  119. package/dist/src/transaction/transaction.d.ts.map +1 -1
  120. package/dist/src/transaction/validator.d.ts +7 -0
  121. package/dist/src/transaction/validator.d.ts.map +1 -1
  122. package/dist/src/transaction/validator.js +21 -12
  123. package/dist/src/transaction/validator.js.map +1 -1
  124. package/dist/src/transactor/network-transactor.d.ts +1 -0
  125. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  126. package/dist/src/transactor/network-transactor.js +61 -28
  127. package/dist/src/transactor/network-transactor.js.map +1 -1
  128. package/dist/src/transactor/transactor-source.d.ts +22 -11
  129. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  130. package/dist/src/transactor/transactor-source.js +9 -13
  131. package/dist/src/transactor/transactor-source.js.map +1 -1
  132. package/dist/src/utility/visit-every.d.ts +14 -0
  133. package/dist/src/utility/visit-every.d.ts.map +1 -0
  134. package/dist/src/utility/visit-every.js +27 -0
  135. package/dist/src/utility/visit-every.js.map +1 -0
  136. package/package.json +1 -1
  137. package/src/cluster/structs.ts +42 -7
  138. package/src/collection/action.ts +34 -0
  139. package/src/collection/collection.ts +1048 -543
  140. package/src/collection/head-commit.ts +148 -0
  141. package/src/collection/index.ts +2 -0
  142. package/src/collection/segments.ts +149 -0
  143. package/src/collection/struct.ts +183 -1
  144. package/src/collection/write-attempts.ts +506 -0
  145. package/src/collections/tree/struct.ts +97 -17
  146. package/src/collections/tree/tree.ts +125 -29
  147. package/src/index.ts +2 -0
  148. package/src/network/i-repo.ts +3 -0
  149. package/src/network/index.ts +3 -0
  150. package/src/network/promise-shortfall-error.ts +69 -0
  151. package/src/network/refuse-solo.ts +7 -0
  152. package/src/network/stale-failure.ts +27 -4
  153. package/src/network/struct.ts +154 -2
  154. package/src/network/validity-rejected-error.ts +55 -0
  155. package/src/offline/entry.ts +127 -0
  156. package/src/offline/index.ts +4 -0
  157. package/src/offline/journal.ts +60 -0
  158. package/src/offline/queue.ts +1342 -0
  159. package/src/offline/reachability.ts +32 -0
  160. package/src/offline/status.ts +183 -0
  161. package/src/offline/wake.ts +67 -0
  162. package/src/testing/test-transactor.ts +53 -0
  163. package/src/transaction/commit-failure-class.ts +133 -0
  164. package/src/transaction/coordinator.ts +696 -349
  165. package/src/transaction/entry-commit.ts +285 -0
  166. package/src/transaction/index.ts +4 -0
  167. package/src/transaction/transaction.ts +21 -0
  168. package/src/transaction/validator.ts +22 -12
  169. package/src/transactor/network-transactor.ts +62 -28
  170. package/src/transactor/transactor-source.ts +29 -13
  171. package/src/utility/visit-every.ts +25 -0
@@ -1,33 +1,17 @@
1
- import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms, ActionId, BlockContentDigests } from "../index.js";
1
+ import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms, ActionId } from "../index.js";
2
2
  import { Tracker } from "../transform/tracker.js";
3
3
  import type { BasePins } from "../transform/base-pins.js";
4
4
  import { CacheSource } from "../transform/cache-source.js";
5
- import type { BlockBaseRevs } from "../network/struct.js";
6
5
  import { TransactorSource } from "../transactor/transactor-source.js";
7
6
  import { BlockFloors } from "../transactor/block-floors.js";
8
7
  import type { WriteDurability } from "../network/struct.js";
9
- import type { CollectionId, CommittedTail, CommittedTailAnswer, CommittedTailQuery, ICollection, SyncOptions } from "./index.js";
10
- import type { ActionContext } from "./action.js";
8
+ import type { CollectionId, CommittedTail, CommittedTailAnswer, CommittedTailQuery, HeadCommitOptions, ICollection, InFlightAttempt, InFlightCycle, OpenHeadCommitOptions, SyncOptions } from "./index.js";
9
+ import { ActionRefusedError } from "./struct.js";
10
+ import type { EntryId } from "./segments.js";
11
+ import type { ActionContext, ActionRev, AlreadyAppliedTally } from "./action.js";
12
+ import type { WriteIdentity } from "./write-attempts.js";
13
+ import type { HeadCommitHandle } from "./head-commit.js";
11
14
  import type { ReadDependency } from "../transaction/transaction.js";
12
- /** Exactly what one failed write attempt sent to the transactor — enough to send the same thing
13
- * again. Retained by {@link Collection.retainInFlightAttempt} so that a refresh which then finds
14
- * this attempt's own log entry can land the blocks the attempt left behind, at the same action id
15
- * and revision (see {@link Collection.completeOwnEntry}). */
16
- export type InFlightAttempt = {
17
- /** The revision the attempt's log entry was stamped with, and pended and committed at. */
18
- rev: number;
19
- /** Every transform the attempt pended — the log blocks included. The caller hands over a copy
20
- * it will not mutate; the collection keeps it as given. */
21
- transforms: Transforms;
22
- /** The attempt's log tail block, committed first. */
23
- tailId: BlockId;
24
- /** The per-block content declarations the attempt's commit carried, if any. */
25
- blockDigests?: BlockContentDigests;
26
- /** The per-block bases the attempt's pend carried, if any (see `PendRequest.baseRevs`). Kept
27
- * with the transforms because they describe them: a re-send of these operations must name the
28
- * same bases they were computed against. */
29
- baseRevs?: BlockBaseRevs;
30
- };
31
15
  /** What one refresh ({@link Collection.refreshInFlight}, and the refresh inside a sync) found out
32
16
  * about the write in flight on the instance's behalf. The caller hands in an empty report and the
33
17
  * refresh fills it in AS IT GOES, rather than returning it at the end, so a refresh that throws
@@ -50,7 +34,10 @@ export type RefreshReport = {
50
34
  };
51
35
  };
52
36
  export type CollectionInitOptions<TAction> = {
53
- modules: Record<ActionType, ActionHandler<TAction>>;
37
+ /** One handler per action type. A handler may answer what the action accepted as already applied
38
+ * ({@link AlreadyAppliedTally}); one that answers nothing counts as the zero tally, so a collection
39
+ * type with no such notion returns nothing. */
40
+ modules: Record<ActionType, ActionHandler<TAction, AlreadyAppliedTally | void>>;
54
41
  createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => IBlock;
55
42
  /** Called for each local action that is potentially in conflict with a remote action.
56
43
  * @param action - The local action to check
@@ -60,6 +47,14 @@ export type CollectionInitOptions<TAction> = {
60
47
  * the conflict replay), or undefined to discard this action
61
48
  */
62
49
  filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined;
50
+ /** Called once per refusal of a SEALED segment discovered by a replay (see
51
+ * {@link Collection.replayActions}): the segment's entry id and the handler's refusal. Called
52
+ * synchronously from inside the replay, under the collection latch, so it MUST NOT call a
53
+ * latched method of this collection ({@link Collection.update}, {@link Collection.dropSealed},
54
+ * {@link Collection.sync}, …) synchronously — the latch is non-reentrant and that would
55
+ * deadlock. The queue schedules its reaction instead. A throw out of the callback is caught and
56
+ * logged (`collection:refusal-callback-threw`), never allowed to abort the replay. */
57
+ onSealedRefused?: (entryId: EntryId, error: ActionRefusedError) => void;
63
58
  };
64
59
  /** Options for building a committed read view (see {@link Collection.createReadTracker}
65
60
  * and `Tree.readView`). */
@@ -92,8 +87,17 @@ export interface CollectionSnapshot<TAction> {
92
87
  * were not built on. Absent on a snapshot built by hand; such a restore keeps whatever pins
93
88
  * the tracker holds for the restored ids. */
94
89
  pins?: BasePins;
95
- /** Pending actions queued at snapshot time. */
90
+ /** The OPEN segment's actions at snapshot time (see {@link SegmentList}). Sealed segments are
91
+ * not captured as actions — their effects are in `transforms`, which is what a committed read
92
+ * view built from this snapshot must include — and a restore never puts one back: whether it
93
+ * reinstates `transforms` verbatim or rebuilds the tracker from the sealed segments as they are
94
+ * then is decided by {@link sealedVersion} (see {@link Collection.restorePending}). */
96
95
  pending: Action<TAction>[];
96
+ /** {@link SegmentList.version} at capture: a restore that finds the sealed list changed since —
97
+ * a segment sealed, dropped or refused while the snapshot was outstanding — replays rather than
98
+ * reinstating `transforms`, which would put a dropped segment's effects back. Absent on a
99
+ * snapshot built by hand, which reads as "unchanged". */
100
+ sealedVersion?: number;
97
101
  /** The committed boundary (action context) the staged state sat on when captured.
98
102
  * `undefined` for a collection with no committed revision yet (an invented
99
103
  * collection whose header/root still live in the tracker). A read view built
@@ -116,12 +120,27 @@ export declare class Collection<TAction> implements ICollection<TAction> {
116
120
  * {@link BlockFloors}). */
117
121
  private readonly floors;
118
122
  private readonly filterConflict?;
123
+ /** See {@link CollectionInitOptions.onSealedRefused}. */
124
+ private readonly onSealedRefused?;
119
125
  /** Short random tag naming THIS instance (see {@link newInstanceTag}). Open paths generate
120
126
  * it BEFORE construction (so pre-construction diagnostics such as attachToLog can carry it);
121
127
  * the default covers direct construction in tests. */
122
128
  readonly instanceTag: string;
123
- private pending;
129
+ /** The staged actions: sealed segments, one per queued entry, ahead of the open segment the
130
+ * current transaction stages into (see {@link SegmentList}). While nothing is sealed this is
131
+ * exactly the one pending list it replaced, and every path behaves as it did then. */
132
+ private readonly segments;
124
133
  private readonly latchId;
134
+ /** The transforms an INVENTED collection starts from — its header, its empty log block and (for
135
+ * a tree) its empty root, as {@link createOrOpen}'s create branch staged them. A replay resets
136
+ * the tracker to a copy of this, rather than to empty, for as long as no committed revision has
137
+ * been adopted: those blocks are then nowhere but the tracker, and resetting to empty would drop
138
+ * them and leave the collection unreadable (the hazard {@link mustReplay} and
139
+ * {@link snapshotPending} describe). Never cleared — it is read only while
140
+ * `source.actionContext` is undefined, and once a context is adopted the blocks are in storage
141
+ * and the empty reset is the right one. `undefined` for a collection opened over a committed
142
+ * header, which never replays from a baseline. */
143
+ private inventedBaseline?;
125
144
  /** The action id of a write currently in flight ON THIS INSTANCE'S BEHALF, or `undefined`
126
145
  * outside a write. Read by {@link updateInternal}: if the committed log now carries an entry
127
146
  * under this id, that action's LOG TAIL landed despite the failure answer that sent us back here
@@ -170,19 +189,46 @@ export declare class Collection<TAction> implements ICollection<TAction> {
170
189
  * Only the latest attempt is kept. An own entry can only be visible at the revision of an
171
190
  * attempt whose tail landed, and a later attempt at a DIFFERENT revision is only made after a
172
191
  * refresh adopted somebody else's entry at the earlier one — which is proof the earlier tail did
173
- * not land. {@link completeOwnEntry} still checks the revision and refuses on a mismatch. */
192
+ * not land. {@link completeOwnEntry} still checks the revision and refuses on a mismatch.
193
+ *
194
+ * A head commit may be opened with one already in hand ({@link openHeadCommit}'s `resume`): the
195
+ * attempt an earlier cycle under the same action id recorded through `HeadCommitOptions.recordAttempt`
196
+ * before sending it, which the cycle's opening refresh can then finish from. */
174
197
  private inFlightAttempt?;
175
198
  /** The log data-block ids the append of the action marked in {@link inFlightActionId} has
176
199
  * minted, in the order it minted them, together with the revision they were minted for. Set and
177
200
  * read by {@link logAppendBlockIds}, cleared with the rest of the in-flight state by
178
201
  * {@link beginInFlightAction} and its disposer. */
179
202
  private mintedLogBlockIds?;
203
+ /** What the cycle marked in {@link inFlightActionId} asked of every send it makes
204
+ * ({@link InFlightCycle}) — read by {@link send} and by the re-send {@link completeOwnEntry} makes
205
+ * to finish a torn attempt, so neither needs it threaded through. Set by
206
+ * {@link beginInFlightAction} and cleared by its disposer. */
207
+ private inFlightCycle;
208
+ /** The head commit running on this instance ({@link openHeadCommit}), for the whole cycle — set and
209
+ * cleared beside {@link inFlightActionId}: the sealed segment it is committing, and the hook told
210
+ * what that segment accepted as already applied when it is dropped as committed
211
+ * ({@link HeadCommitOptions.onCommittedHead}). Read by {@link consumeOwnEntry}: the entry a head
212
+ * commit's own refresh finds under the in-flight action id records the HEAD segment's actions, not
213
+ * the open segment's, so consuming it removes that segment — and reports it through the hook, as
214
+ * the handle's `fold` does. */
215
+ private headCommit?;
216
+ /** Set only while a head commit has RELEASED the collection latch for its one network round trip
217
+ * ({@link HeadCommitHandle.release}), and cleared the moment it is retaken, so anything that runs under the
218
+ * latch in that window can tell. Two things must: a refresh ({@link updateInternal}) that walks
219
+ * into the in-flight entry returns without adopting it, since it can neither finish it as the
220
+ * write's own (nothing failed, nothing is retained) nor replay it as a stranger's (that would
221
+ * re-stage the head over state that already contains it); and {@link dropSealed} refuses to drop
222
+ * the segment the commit is carrying. A second {@link commitHead} meets it as its `in-flight`
223
+ * precondition. Gated on THIS field, not on {@link inFlightActionId}: the head commit's own
224
+ * refreshes run with it cleared and must take the own-entry path. */
225
+ private headInFlight?;
180
226
  /** The log tail block id the most recent header read named. A refresh asks for this block in the
181
227
  * same request as the header ({@link readLogEnds}): the tail id only changes when the tail block
182
228
  * fills, so an idle refresh is one request rather than two. A stale value costs one extra request
183
229
  * and nothing else. */
184
230
  private logTailId?;
185
- protected constructor(id: CollectionId, transactor: ITransactor, handlers: Record<ActionType, ActionHandler<TAction>>, source: TransactorSource<IBlock>,
231
+ protected constructor(id: CollectionId, transactor: ITransactor, handlers: Record<ActionType, ActionHandler<TAction, AlreadyAppliedTally | void>>, source: TransactorSource<IBlock>,
186
232
  /** Cache of unmodified blocks from the source */
187
233
  sourceCache: CacheSource<IBlock>,
188
234
  /** Tracked Changes */
@@ -191,6 +237,8 @@ export declare class Collection<TAction> implements ICollection<TAction> {
191
237
  * {@link updateInternal}, and shared with every read source this handle builds (see
192
238
  * {@link BlockFloors}). */
193
239
  floors: BlockFloors, filterConflict?: ((action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined) | undefined,
240
+ /** See {@link CollectionInitOptions.onSealedRefused}. */
241
+ onSealedRefused?: ((entryId: EntryId, error: ActionRefusedError) => void) | undefined,
194
242
  /** Short random tag naming THIS instance (see {@link newInstanceTag}). Open paths generate
195
243
  * it BEFORE construction (so pre-construction diagnostics such as attachToLog can carry it);
196
244
  * the default covers direct construction in tests. */
@@ -243,10 +291,12 @@ export declare class Collection<TAction> implements ICollection<TAction> {
243
291
  * a poll of many collections whose logs stayed on their blocks is one request, however many it
244
292
  * names; the per-block judgement is {@link readLogEnds}'s, through the same helpers.
245
293
  *
246
- * A request that throws is not every collection's failure: `NetworkTransactor.get` fails as a
247
- * whole when any block in it gets no answer, so {@link readAttributed} then reads each block
248
- * alone and only the collections whose blocks failed report an error. That fallback costs what
249
- * reading each collection separately costs, and only when a request fails. */
294
+ * A block no coordinator answered comes back flagged and fails only its own collection, through
295
+ * the per-block judgement. A request that throws as a whole — `NetworkTransactor.get` does when a
296
+ * coordinator's answer leaves a block out — is not every collection's failure either:
297
+ * {@link readAttributed} then reads each block alone and only the collections whose blocks failed
298
+ * report an error. That fallback costs what reading each collection separately costs, and only
299
+ * when a request fails. */
250
300
  static readCommittedTails(transactor: ITransactor, queries: ReadonlyArray<CommittedTailQuery>): Promise<Map<CollectionId, CommittedTailAnswer>>;
251
301
  /** The per-instance read wiring every open path needs, plus the collection's log ends — the
252
302
  * header, then the log tail block it names — read by {@link readLogEnds}, the reader every
@@ -261,7 +311,8 @@ export declare class Collection<TAction> implements ICollection<TAction> {
261
311
  * first read of it through the handle's cache now records, at the revision it was served at
262
312
  * (see {@link attachToLog}). */
263
313
  private static probeHeader;
264
- /** A new handle's floors: none yet (opening walks no entries), wired to report every below-floor
314
+ /** A new handle's floors: none yet (an open raises them from its log tail,
315
+ * {@link floorTailEntries}), wired to report every below-floor
265
316
  * answer any of the handle's read sources receives. The line is the only trace such an answer
266
317
  * leaves — the read itself succeeds (see the accepted-tradeoff NOTE at
267
318
  * `TransactorSource.mayRetain`) — so repeated lines for one block with `servedRev` short of
@@ -274,6 +325,23 @@ export declare class Collection<TAction> implements ICollection<TAction> {
274
325
  * declines to keep is re-read through the tracker/cache, so it can disagree with the probe when
275
326
  * storage is flaky mid-open.) */
276
327
  private static attachToLog;
328
+ /** Floor every block an action entry in the opened log's tail block names, at that entry's
329
+ * revision — what a refresh's walk does for the entries it walks ({@link raiseFloors}), for the
330
+ * entries an open has read but does not walk.
331
+ *
332
+ * An open adopts the revision the tail names, then reads each block it needs for the first time.
333
+ * When the answering repo's copy of such a block is older than an entry the tail holds — a node
334
+ * whose crash kept a commit's log tail but lost its other blocks within the store's durability
335
+ * window, or a coordinator that missed the commit — nothing else tells the read so, and the
336
+ * repo serves its held copy (a held block's first read after a restart is answered locally while
337
+ * the consult runs behind it). The handle then shows, say, a table row whose index entry is
338
+ * missing. With the floor, the read carries the revision the tail proves, so the repo consults
339
+ * its cohort before answering and the transactor re-asks another machine for an answer still
340
+ * below it (see {@link BlockFloors}).
341
+ *
342
+ * Only the tail block's entries: they are what the open read, and they hold the newest commits —
343
+ * the ones a durability window can tear. Invalidation entries set no floor, as on a refresh. */
344
+ private static floorTailEntries;
277
345
  /** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
278
346
  *
279
347
  * The revision a collection last committed at is knowledge it earned; a read that found
@@ -388,6 +456,13 @@ export declare class Collection<TAction> implements ICollection<TAction> {
388
456
  act(...actions: Action<TAction>[]): Promise<void>;
389
457
  private actInternal;
390
458
  private internalTransact;
459
+ /** Run `actions` through their handlers over `tracker` as ONE atomic unit: a throw from any
460
+ * handler leaves none of their writes staged. The live tracker's path ({@link internalTransact})
461
+ * and a head commit's tracker ({@link buildHeadTracker}) share it.
462
+ *
463
+ * @returns the sum of what the handlers accepted as already applied ({@link AlreadyAppliedTally});
464
+ * a handler that answers nothing adds the zero tally. */
465
+ private stageInto;
391
466
  /** Load external changes and update our context to the latest log revision - resolve any conflicts with our pending actions. */
392
467
  update(): Promise<void>;
393
468
  /** The refresh `TransactionCoordinator.commit` runs between attempts: exactly {@link update},
@@ -493,27 +568,64 @@ export declare class Collection<TAction> implements ICollection<TAction> {
493
568
  * {@link completeOwnEntry} has returned for this entry — the entry alone is not proof the write
494
569
  * is saved.
495
570
  *
496
- * `addActions` wrote exactly the snapshot pending list under this action id, and the entry's
497
- * actions are therefore the LEADING `entry.actions.length` items of `this.pending` — anything
498
- * staged since is behind them, because {@link actInternal} appends. Under
499
- * {@link syncInternal} nothing can even be staged mid-cycle (`act()` shares the collection
500
- * latch); under `TransactionCoordinator.commit` the mark spans a latch-free inter-attempt
501
- * window, so an `act()` there CAN grow `pending` — still only at the tail, so the slice stays
502
- * right.
503
- *
504
- * The guard below is the load-bearing part: `slice` fails SILENTLY if that correspondence ever
505
- * breaks, dropping actions that were never committed, so an entry longer than `pending` throws
506
- * instead of losing work. (See the sibling note on `syncInternal`'s post-commit replay, which
507
- * rests on the same invariant.) */
571
+ * A whole-collection write (`sync`) wrote exactly the snapshot of the OPEN segment under this
572
+ * action id, and the entry's actions are therefore the LEADING `entry.actions.length` items of
573
+ * the open segment — anything staged since is behind them, because {@link actInternal}
574
+ * appends. Under {@link syncInternal} nothing can even be staged mid-cycle (`act()` shares the
575
+ * collection latch); under `TransactionCoordinator.commit` the mark spans a latch-free
576
+ * inter-attempt window, so an `act()` there CAN grow the open segment — still only at the
577
+ * tail, so the slice stays right. No sealed segment can exist for such a write: every
578
+ * whole-collection path refuses while one does ({@link SealedSegmentsError}).
579
+ *
580
+ * A head commit ({@link commitHead}, which marks {@link headCommit} for its cycle) wrote the
581
+ * HEAD sealed segment's actions, so its entry is consumed by removing that segment — the open
582
+ * segment, which may have grown while the commit was on the network, is untouched. The sealed
583
+ * segments behind the head are never touched by either arm.
584
+ *
585
+ * The guards are the load-bearing part: `slice` fails SILENTLY if the open correspondence ever
586
+ * breaks, dropping actions that were never committed, so an entry longer than the open segment
587
+ * throws instead of losing work, and an entry whose action count is not the head's throws rather
588
+ * than removing a segment the entry does not record. (See the sibling note on `syncInternal`'s
589
+ * post-commit replay, which rests on the same invariant.)
590
+ *
591
+ * @returns whether the staged set changed — always true here: even for a zero-action entry the
592
+ * tracker still holds this action's staged transforms, and only the replay at the end of
593
+ * `updateInternal` — which resets the tracker and re-stages just what remains — drops them.
594
+ * That reset is what turns `hasUnsyncedChanges()` false so the sync loop exits reporting the
595
+ * success the writer is owed (the action IS durable). */
508
596
  private consumeOwnEntry;
509
- /** Maps each pending action to its effective form against a remote entry: the original, a
510
- * replacement, or dropped. A replacement or a discard changes the pending set; the tracker still
597
+ /** Remove the head segment `entryId` because `entry`, its own committed log entry, made it
598
+ * durable — the head arm of {@link consumeOwnEntry}. Bumps the segment version, so an outstanding
599
+ * snapshot restores by replay rather than putting the committed segment back, and reports the
600
+ * dropped segment's tally through the cycle's hook ({@link reportCommittedHead}), as the handle's
601
+ * `fold` does for an attempt that committed. */
602
+ private consumeHead;
603
+ /** Hand the tally recorded on `segment` — the head segment just made durable and dropped — to the
604
+ * cycle's `onCommittedHead` hook ({@link HeadCommitOptions.onCommittedHead}), under the latch, from
605
+ * the two places that drop a head segment as committed: the handle's `fold`, and
606
+ * {@link consumeHead}. A segment with no recorded tally is a defect, answered with the zero tally
607
+ * and logged rather than thrown: every sealed segment is staged by {@link buildHeadTracker} before
608
+ * its first send and by a replay when put back ({@link restoreSealed}), and the resume path that
609
+ * re-sends a recorded attempt verbatim runs after one of those. A throw out of the hook is logged,
610
+ * never raised — the commit is already durable. */
611
+ private reportCommittedHead;
612
+ /** The open segment with the leading actions `entry` made durable dropped off it. */
613
+ private consumedFromOpen;
614
+ /** Maps each OPEN-segment action to its effective form against a remote entry: the original, a
615
+ * replacement, or dropped. A replacement or a discard changes the staged set; the tracker still
511
616
  * holds the pre-filter transforms, so report it as mutated to force a replay that re-stages
512
617
  * against the effective actions. Identity comparison per the contract: keep => same instance,
513
618
  * replace => new instance.
619
+ *
620
+ * A SEALED segment's action list is the queue entry's own and is never rewritten (invariant 3
621
+ * of docs/offline-sync.md §The segment model), so the hook is not offered them. `Tree` and
622
+ * `Diary` install no hook, so nothing observable changes for them either way.
623
+ *
514
624
  * NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead of
515
625
  * returning the same one forces a replay on every update — if that ever shows up as a hot path,
516
- * compare by value/id here instead of by reference. */
626
+ * compare by value/id here instead of by reference.
627
+ *
628
+ * @returns whether the open segment changed. */
517
629
  private filterAgainstEntry;
518
630
  /** Refresh this instance against the stored log: adopt the latest committed revision, resolve
519
631
  * pending actions against everything that landed since, and replay them if anything conflicts.
@@ -678,8 +790,8 @@ export declare class Collection<TAction> implements ICollection<TAction> {
678
790
  * revision. A revision only one side names is missing evidence, not disagreement — the rule
679
791
  * {@link earliestFork} applies too. */
680
792
  private static disagreesWithHeld;
681
- /** Whether {@link updateInternal} must re-stage `pending` after adopting `latest`, given the
682
- * context it held BEFORE the refresh.
793
+ /** Whether {@link updateInternal} must re-stage the staged actions after adopting `latest`,
794
+ * given the context it held BEFORE the refresh.
683
795
  *
684
796
  * The answer is deliberately NOT just "a conflict was found". A conflict is detected by an
685
797
  * incoming log entry naming a block this tracker already holds a transform for — so an action
@@ -694,16 +806,17 @@ export declare class Collection<TAction> implements ICollection<TAction> {
694
806
  * The advance test rests on {@link advanceContext} being monotonic (it refuses to lower), which
695
807
  * is what makes "the adopted rev differs from the held one" mean "it went up".
696
808
  *
697
- * The second conjunct is `pending.length` and deliberately NOT {@link hasUnsyncedChanges},
698
- * which also counts tracker transforms. A collection {@link createOrOpen} just INVENTED holds
699
- * its staged header/root in the tracker with NO pending action naming them, and
700
- * {@link replayActions} resets the tracker before re-staging — so counting transforms here
701
- * would drop those blocks and leave a brand-new collection unreadable (the same hazard
702
- * {@link snapshotPending} documents). Nothing to re-stage means nothing to replay.
703
- *
704
- * NOTE: this makes a refresh that adopts a newer revision O(pending) rather than free, so a
705
- * read taken mid-transaction while a rival keeps committing re-stages every action staged so
706
- * far, on each such read. Measured as no change to the storage-op budgets
809
+ * The second conjunct counts the REPLAYABLE actions — every non-refused sealed segment's plus
810
+ * the open segment's, since a refresh that adopts a newer revision must re-stage the sealed
811
+ * segments too — and deliberately NOT {@link hasUnsyncedChanges}, which also counts tracker
812
+ * transforms. A collection {@link createOrOpen} just INVENTED holds its staged header/root in
813
+ * the tracker with NO staged action naming them; {@link replayActions} now restores them from
814
+ * {@link inventedBaseline}, but nothing to re-stage still means nothing to replay, and a replay
815
+ * over no actions would be a wasted tracker rebuild.
816
+ *
817
+ * NOTE: this makes a refresh that adopts a newer revision O(staged actions) rather than free,
818
+ * so a read taken mid-transaction while a rival keeps committing re-stages every action staged
819
+ * so far, on each such read. Measured as no change to the storage-op budgets
707
820
  * (`index-backfill-cost.spec.ts`, `cold-apply-cost.spec.ts`), because the replay's reads are
708
821
  * served from `sourceCache`. If a long transaction's reads ever show up as slow, narrow the
709
822
  * replay to the actions whose reads the adopted entries actually invalidated — NOT back to
@@ -711,17 +824,14 @@ export declare class Collection<TAction> implements ICollection<TAction> {
711
824
  private mustReplay;
712
825
  /** Re-judge every staged update's pinned base against the read cache and re-stage the pending
713
826
  * queue if any has moved. Runs immediately before each pend attempt — {@link syncAttempts} and
714
- * the coordinator's commit span both call it — because that is the last moment before the
715
- * base the pend declares is put on the wire, and nothing between a refused attempt and the
716
- * re-pend reads the block again (the refresh may have moved nothing and so replayed nothing).
827
+ * the coordinator's commit span both call it, and {@link headTrackerFor} re-judges a head
828
+ * commit's tracker the same way — because that is the last moment before the base the pend
829
+ * declares is put on the wire, and nothing between a refused attempt and the re-pend reads the
830
+ * block again (the refresh may have moved nothing and so replayed nothing).
717
831
  *
718
- * Two steps. First, one read for each pinned block the cache does NOT retain — content handed
719
- * through unkept (a below-floor answer, which the cache re-asks for on every read anyway): the
720
- * pin names the revision last served, storage may have caught up since without the log moving,
721
- * and only a read can tell. An evicted-but-kept base needs no read: its content met every floor
722
- * the handle knows, so storage cannot have moved it without a log entry the next refresh will
723
- * walk (and the pend would be refused as stale on revision alone). Then, one cache probe per
724
- * pinned block ({@link Tracker.movedBases}) and a replay if any moved.
832
+ * Two steps. First, one read for each pinned block the cache does NOT retain
833
+ * ({@link rereadUnretainedBases}). Then, one cache probe per pinned block
834
+ * ({@link Tracker.movedBases}) and a replay if any moved.
725
835
  *
726
836
  * Latch-free by contract, like {@link snapshotPending}: the caller holds this instance's latch
727
837
  * ({@link replayActions} is always run under it).
@@ -733,6 +843,13 @@ export declare class Collection<TAction> implements ICollection<TAction> {
733
843
  *
734
844
  * @returns whether the pending queue was re-staged. */
735
845
  restageIfBasesMoved(): Promise<boolean>;
846
+ /** One read for each of `tracker`'s pinned blocks the cache does NOT retain — content handed
847
+ * through unkept (a below-floor answer, which the cache re-asks for on every read anyway): the
848
+ * pin names the revision last served, storage may have caught up since without the log moving,
849
+ * and only a read can tell. An evicted-but-kept base needs no read: its content met every floor
850
+ * the handle knows, so storage cannot have moved it without a log entry the next refresh will
851
+ * walk (and the pend would be refused as stale on revision alone). */
852
+ private rereadUnretainedBases;
736
853
  /** Report each moved base, naming the revision the operations were computed against and the
737
854
  * one the cache describes now, and return how many there were. */
738
855
  private logMovedBases;
@@ -754,29 +871,63 @@ export declare class Collection<TAction> implements ICollection<TAction> {
754
871
  * mutations staged since. Reads through the collection then observe exactly the
755
872
  * snapshot state again; storage is untouched because nothing was ever synced.
756
873
  *
757
- * A snapshot is only restorable VERBATIM onto the committed boundary it was captured
758
- * on. If this collection has since ADOPTED a newer committed revision — a rival's
759
- * commit folded in by a refresh while the snapshot's transaction was in flight, e.g.
760
- * the conflict replay that refused a guarded insert (TreeKeyTakenError) — the
761
- * snapshot's transforms describe block state at the OLD boundary, and reinstalling
762
- * them would shadow committed blocks with stale structure. The observed case: an
763
- * INVENTED collection's pre-commit header/root transforms restored over the rival's
764
- * now-committed collection make every later read descend an empty tree, silently
765
- * hiding the committed rows. When the snapshot's pending queue is empty (the
766
- * transaction-rollback shape: the capture predates the transaction's first stage),
767
- * the correct restore target IS the committed state — reset the tracker empty and
768
- * let reads flow through to the adopted revision.
769
- *
770
- * NOTE: a snapshot that carries PENDING actions across a moved boundary (a
771
- * mid-transaction savepoint captured before a mid-transaction refresh adopted a
772
- * rival's commit) still restores verbatim below — rebasing it would require an async
773
- * replay this synchronous method cannot run. That shape predates this guard and
774
- * keeps its old behaviour; if it is ever observed producing stale reads, the rebase
775
- * belongs in an async caller that can replay the pending queue (see replayActions).
874
+ * The snapshot describes the OPEN segment only (docs/offline-sync.md §Rollback and savepoints
875
+ * only touch the open segment): its `pending` is the open segment's actions, while its
876
+ * `transforms` are the whole tracker at capture, the sealed segments' effects included. Which
877
+ * arm a restore takes is decided from three facts — whether the sealed list has changed since
878
+ * the capture ({@link CollectionSnapshot.sealedVersion} against {@link SegmentList.version}),
879
+ * whether the committed boundary has moved (this collection has since ADOPTED a newer
880
+ * revision), and whether any segment is sealed now:
881
+ *
882
+ * - **Verbatim**, when the sealed list is unchanged and the boundary has not moved: the tracker
883
+ * is reset to a copy of the captured transforms, the captured pins are restored, and the open
884
+ * segment is set to the captured actions. This keeps an INVENTED collection's header, log
885
+ * block and root, which live in the tracker until the first sync and would be lost by a
886
+ * reset. It is the arm every restore took before segments existed, so while nothing is ever
887
+ * sealed nothing behaves differently.
888
+ * - **Replay**, when the sealed list has changed — a segment sealed, dropped or refused while
889
+ * the snapshot was outstanding — or when the boundary has moved while a segment is sealed:
890
+ * the open segment is set to the captured actions and the tracker is rebuilt by
891
+ * {@link replayActions}, the sealed segments as they are NOW (refused ones skipped, a newly
892
+ * refused one recorded and reported) and then the restored open actions. Reinstating the
893
+ * captured transforms would put a dropped segment's effects back — the drain removes the
894
+ * head segment after committing it, and the next head commit would commit it a second time
895
+ * — and a reset would drop the sealed segments' effects.
896
+ * - A moved boundary with NOTHING sealed keeps the two arms it had before segments. An empty
897
+ * captured open segment (the transaction-rollback shape: the capture predates the
898
+ * transaction's first stage) resets the tracker empty, because the captured transforms
899
+ * describe block state at the OLD boundary and reinstalling them would shadow committed
900
+ * blocks with stale structure — the observed case being an INVENTED collection's pre-commit
901
+ * header/root restored over a rival's now-committed collection, after the conflict replay
902
+ * that refused a guarded insert (TreeKeyTakenError), making every later read descend an
903
+ * empty tree. A non-empty one restores verbatim (the NOTE below).
904
+ *
905
+ * The staged-base rule (docs/internals.md §Staged Edits Keep Their Base: an update names the
906
+ * base it was computed against, and a rollback never pairs operations with the bases of some
907
+ * later re-stage) is met differently by the two arms. The verbatim arm restores the captured
908
+ * pins beside the captured operations. The replay arm restores none: its reset clears the pin
909
+ * store, and every re-staged update pins its base from the read cache as it is now, which IS
910
+ * the base the re-staged operations were computed against.
911
+ *
912
+ * A refusal of the OPEN segment inside the replay arm propagates, as it would out of a
913
+ * refresh's replay: the caller rolling back is told that its transaction's own actions no
914
+ * longer apply at the boundary the collection is now at. Rare — it needs a sealed change, or a
915
+ * sealed segment across a moved boundary, AND a rival between capture and restore — and the
916
+ * honest answer; the tracker is then as {@link updateInternal}'s note on a throw out of
917
+ * `replayActions` describes.
918
+ *
919
+ * Latch-free by contract, like {@link snapshotPending}: every caller holds this instance's
920
+ * latch or runs on the single call path that excludes a concurrent stage (the coordinator's
921
+ * `rollback` and the bridge's savepoint rollback document that assumption).
922
+ *
923
+ * NOTE: a snapshot that carries PENDING actions across a moved boundary with nothing sealed (a
924
+ * mid-transaction savepoint captured before a mid-transaction refresh adopted a rival's commit)
925
+ * still restores verbatim. That shape predates the moved-boundary guard and keeps its old
926
+ * behaviour; if it is ever observed producing stale reads, route it through the replay arm too.
776
927
  * The WRITE side of that shape is closed here: the snapshot's base pins are restored with
777
928
  * its transforms, so the restored operations name the bases they were computed on, and the
778
929
  * pre-pend re-validation (restageIfBasesMoved) finds those bases moved and re-stages. */
779
- restorePending(snapshot: CollectionSnapshot<TAction>): void;
930
+ restorePending(snapshot: CollectionSnapshot<TAction>): Promise<void>;
780
931
  /** A read-only {@link Tracker} pinned to this collection's committed state AS OF the
781
932
  * moment of this call, seeded with a (deep-copied) set of pre-transaction transforms.
782
933
  * Reads through it observe exactly that revision plus exactly those transforms — NOT
@@ -819,28 +970,143 @@ export declare class Collection<TAction> implements ICollection<TAction> {
819
970
  * yield a coherent pre-commit view AFTER that commit folded into the shared cache
820
971
  * (a mid-sweep multi-tree commit being the motivating case). */
821
972
  createReadTracker(transforms: Transforms, options?: ReadViewOptions): Tracker<IBlock>;
822
- /** The staged (not-yet-synced) actions queued by {@link act}.
973
+ /** The OPEN segment: the staged (not-yet-synced) actions queued by {@link act} that no
974
+ * {@link sealPending} has closed off.
823
975
  *
824
976
  * Exposed so a {@link TransactionCoordinator} can append them to the log at
825
977
  * commit time — mirroring what {@link sync} does internally — when the actions
826
978
  * were staged directly into this collection (e.g. through a Tree's stage())
827
- * rather than applied via the coordinator's own action path. */
979
+ * rather than applied via the coordinator's own action path.
980
+ *
981
+ * @throws SealedSegmentsError while any segment is sealed: the coordinator's only use is a
982
+ * whole-collection append, which would merge the sealed segments' effects (they are in the
983
+ * tracker) into one entry under one action id. The throw lands in `commitOnceLatched`'s
984
+ * existing catch, which restores every participant. */
828
985
  getPendingActions(): Action<TAction>[];
829
- /** Drop the staged actions after they have been committed through a
830
- * coordinator. Counterpart to {@link getPendingActions}; {@link sync} clears
831
- * its own pending inline, so this is only needed when commit was orchestrated
832
- * externally. */
986
+ /** Drop the OPEN segment after it has been committed through a coordinator. Counterpart to
987
+ * {@link getPendingActions}, which cannot have returned anything while a segment was sealed,
988
+ * so only the open segment is ever cleared here; {@link sync} clears its own inline, so this
989
+ * is only needed when commit was orchestrated externally. */
833
990
  clearPendingActions(): void;
834
- /** Whether {@link sync} has anything to push: staged actions, or tracker transforms
835
- * that were never committed (an INVENTED collection's header/root blocks live there
836
- * until its first sync, with no pending action to name them).
991
+ /** Whether {@link sync} has anything to push: staged actions in the open segment, or tracker
992
+ * transforms that were never committed — an INVENTED collection's header/root blocks, which
993
+ * live there until its first sync with no staged action to name them, and the effects of
994
+ * every sealed segment.
837
995
  *
838
996
  * This is the exact predicate {@link syncInternal} loops on, so `false` means a sync
839
997
  * would commit nothing. Exposed so a caller that would otherwise flush
840
998
  * unconditionally can skip the round trip — note that {@link Tree.sync} routes
841
999
  * through {@link updateAndSync}, so an unnecessary flush still pays a full,
842
- * cache-bypassing {@link update} before discovering it has nothing to do. */
1000
+ * cache-bypassing {@link update} before discovering it has nothing to do.
1001
+ *
1002
+ * `true` does not promise that {@link sync} can push it: while any segment is sealed, `sync`
1003
+ * refuses with {@link SealedSegmentsError} rather than committing the sealed effects as one
1004
+ * entry, so a caller that loops on this over a sealed collection gets that typed error, never
1005
+ * a silent no-op. Check {@link sealedEntries} first, or commit the head segment.
1006
+ *
1007
+ * Nor does `false` promise that nothing is sealed. A sealed segment leaves no tracker transform
1008
+ * when every one of its actions is refused, or wrote nothing (a blind delete of a key nobody
1009
+ * holds), so over an otherwise empty tracker this reads `false` while {@link sealedEntries} is
1010
+ * non-empty. The queue drives off {@link sealedEntries}, never off this predicate. */
843
1011
  hasUnsyncedChanges(): boolean;
1012
+ /** Close the open segment into a sealed segment owned by `entryId` (see {@link SegmentList}).
1013
+ * Returns `false` and changes nothing when the open segment is empty: an invented collection's
1014
+ * header transforms are not an action and are not sealed, so an entry that staged nothing here
1015
+ * owns no segment here. Throws when `entryId` is already sealed in this collection.
1016
+ *
1017
+ * Synchronous and latch-free by contract, like {@link snapshotPending}: the caller brackets it
1018
+ * (no concurrent act or sync is in flight). */
1019
+ sealPending(entryId: EntryId): boolean;
1020
+ /** The entry ids of the sealed segments, oldest first — refused ones included, until dropped. */
1021
+ sealedEntries(): EntryId[];
1022
+ /** The log tail block id the most recent header read named ({@link logTailId}), for a caller that
1023
+ * resolves this collection's cohorts from routing keys without a read — the offline queue's
1024
+ * reachability gate (docs/offline-sync.md §When to submit). `undefined` before the first header
1025
+ * read of an invented collection; possibly stale by one roll-over, which costs that caller nothing
1026
+ * worse than asking about a block the collection has moved on from. */
1027
+ knownLogTailId(): BlockId | undefined;
1028
+ /** The refusal recorded for `entryId`'s segment by a replay that excluded it (see
1029
+ * {@link replayActions}), or `undefined` when the segment is not refused — or not sealed here. */
1030
+ sealedRefusal(entryId: EntryId): ActionRefusedError | undefined;
1031
+ /** The sealed segment `entryId` owns here: its actions, the array the segment holds (never
1032
+ * mutated by a caller; the offline journal serialises it), or `undefined` when the entry is not
1033
+ * sealed here. Synchronous and latch-free, like {@link sealedEntries}. */
1034
+ sealedActions(entryId: EntryId): readonly Action<TAction>[] | undefined;
1035
+ /** The OPEN segment's actions — what the current transaction has staged since the last seal — as
1036
+ * the array the segment holds (never mutated by a caller). Unlike {@link getPendingActions} it
1037
+ * answers while segments are sealed, for a reader that judges the open transaction beside the
1038
+ * queued ones (the Quereus plugin's `CommitOutlook()`). Synchronous and latch-free, like
1039
+ * {@link sealedActions}. */
1040
+ openActions(): readonly Action<TAction>[];
1041
+ /** The exact inverse of {@link sealPending}, list-only and latch-free by the same contract: move
1042
+ * the segment's actions back into the open segment, for an enqueue whose journal write failed
1043
+ * after sealing (`OfflineQueue.enqueue`, which unseals every collection it sealed, in reverse
1044
+ * order, and rethrows). Requires the segment to be the NEWEST sealed one and the open segment to
1045
+ * be empty — both true at that one call site, which has just sealed and staged nothing since —
1046
+ * and throws otherwise (`SegmentList.unseal`). The tracker is untouched: its transforms are
1047
+ * already what they were before the seal. The segment version moves, so a snapshot taken before
1048
+ * the transaction restores by replay ({@link restorePending}), which ends with the transaction's
1049
+ * actions gone once the caller rolls it back. */
1050
+ unseal(entryId: EntryId): void;
1051
+ /** Whether this collection's committed context names `attempt.actionId` at `attempt.rev`: the
1052
+ * write that attempt sent is committed here, and this handle has adopted it. This is how a restore
1053
+ * after a restart recognises, before re-staging a journaled segment, that the segment's network
1054
+ * commit landed and the crash came after it (docs/offline-sync.md §Restore after a restart):
1055
+ * re-staging such a segment would run its own guards against its own committed rows (`absent`
1056
+ * refuses on a present key) and fail the entry with `constraint`, the opposite of the truth.
1057
+ * `false` for an invented collection, which has no context. Synchronous and latch-free.
1058
+ *
1059
+ * NOTE: `actionIdAt` reaches back only to the most recent checkpoint, and no checkpoint is written
1060
+ * today (backlog `debt-the-collection-log-never-writes-a-checkpoint`); if that changes, read the
1061
+ * log's entry at `attempt.rev` instead, since a committed attempt behind a checkpoint would
1062
+ * otherwise answer `false` and be re-staged against itself. */
1063
+ holdsCommitted(attempt: ActionRev): boolean;
1064
+ /**
1065
+ * Put a sealed segment back, holding `actions` under `entryId`, at `position` in the sealed list —
1066
+ * ahead of the segment `before` names, or last — and rebuild the tracker by replaying every
1067
+ * replayable segment in order ({@link replayActions}), for the offline queue's restore after a
1068
+ * restart (`OfflineQueue.restore`; docs/offline-sync.md §Restore after a restart). A record
1069
+ * restored late belongs ahead of entries queued since, in the queue and in each collection's
1070
+ * sealed list alike, or the head commit's "head is first" rule and the queue's order disagree;
1071
+ * hence insertion rather than appending, at the cost of the one replay every insertion costs.
1072
+ *
1073
+ * The replay records and reports each refusal it meets as a refresh's would — EXCEPT this
1074
+ * segment's own, which is recorded on the segment and RETURNED rather than reported through
1075
+ * `onSealedRefused`: the queue registers the entry and hears the result from its own `stage`
1076
+ * callback, since the collection cannot report it to a queue that does not yet list the entry. A
1077
+ * later segment the replay newly refuses (this segment inserts the key it also inserts, say) is
1078
+ * reported through `onSealedRefused` as any replay's would be.
1079
+ *
1080
+ * Takes the collection latch, like {@link dropSealed}. Throws before anything changes when the
1081
+ * open segment is non-empty (a transaction is open, and its actions were staged over state without
1082
+ * this segment; the only caller refuses to restore mid-transaction), when a head commit is in
1083
+ * flight ({@link SealedSegmentsError}, `in-flight`), when `entryId` is already sealed here, or when
1084
+ * `before` names no segment here. A replay error that is not a refusal (a block the replay could
1085
+ * not read, say) propagates with the segment REMOVED again: the caller's restore rolls back and
1086
+ * may try this entry again later, which would otherwise meet its own segment as "already sealed".
1087
+ * The tracker is then half re-staged, the state a refresh's replay that throws leaves too (backlog
1088
+ * `debt-a-failed-refresh-can-leave-a-collection-half-restaged`); the next replay rebuilds it.
1089
+ *
1090
+ * @returns this segment's own refusal, when the replay refused it; `undefined` when it staged. */
1091
+ restoreSealed(entryId: EntryId, actions: readonly Action<TAction>[], position: {
1092
+ before: EntryId;
1093
+ } | 'last'): Promise<ActionRefusedError | undefined>;
1094
+ /** Remove the sealed segment owned by `entryId`, wherever it sits, and rebuild the tracker by
1095
+ * replaying what remains ({@link replayActions}). A later segment whose guard now refuses — one
1096
+ * that updated a row the dropped segment inserted, say — is recorded and reported through
1097
+ * `onSealedRefused` during that replay; cascading the removal through the queue's other
1098
+ * collections is the queue's job (docs/offline-sync.md §Removing an entry). Throws for an id
1099
+ * that is not sealed here, before anything changes, and {@link SealedSegmentsError} (`in-flight`)
1100
+ * for the segment a {@link commitHead} on this instance is carrying to the network — the only
1101
+ * segment that cannot be dropped while it waits, since the outcome being applied names it.
1102
+ * Another segment can be: the replay here rebuilds the live tracker, which the head commit's own
1103
+ * tracker does not depend on.
1104
+ *
1105
+ * Takes the collection latch, like {@link update}. */
1106
+ dropSealed(entryId: EntryId): Promise<void>;
1107
+ /** The refusal every whole-collection commit path makes while a segment is sealed (see
1108
+ * {@link SealedSegmentsError}). */
1109
+ private assertNoSealedSegments;
844
1110
  /** The committed revision this collection currently READS at, or `undefined` for an
845
1111
  * INVENTED collection that has never adopted a committed revision
846
1112
  * ({@link createOrOpen} found no header and staged a fresh empty one).
@@ -963,8 +1229,11 @@ export declare class Collection<TAction> implements ICollection<TAction> {
963
1229
  * path, which is the same assumption the participant selection in
964
1230
  * `TransactionCoordinator.commitOnce` and its `rollback` already rest on. If a second writer is
965
1231
  * ever allowed to drive the SAME instance concurrently, this must become a per-attempt token (a
966
- * mark object compared by identity, refusing to replace a live one) rather than a bare id. */
967
- beginInFlightAction(actionId: ActionId): () => void;
1232
+ * mark object compared by identity, refusing to replace a live one) rather than a bare id.
1233
+ *
1234
+ * `cycle` is what every send of the cycle carries ({@link InFlightCycle}); a re-mark replaces it,
1235
+ * which is harmless because every caller re-marks with what it marked. */
1236
+ beginInFlightAction(actionId: ActionId, cycle?: InFlightCycle): () => void;
968
1237
  /** Keep what a FAILED attempt under `actionId` sent, so that if the refresh before its retry
969
1238
  * finds that attempt's own log entry it can finish the action rather than assume it finished
970
1239
  * (see {@link inFlightAttempt} and {@link completeOwnEntry}). Every write path that marks an
@@ -972,11 +1241,11 @@ export declare class Collection<TAction> implements ICollection<TAction> {
972
1241
  * a path that does not still never reports a half-landed write as saved (the refresh then
973
1242
  * refuses with a `transforms-not-held` {@link TornActionError}), but it cannot recover from one.
974
1243
  *
975
- * A no-op unless `actionId` is the action currently marked, so a late call from an attempt whose
976
- * cycle has already ended cannot plant transforms under somebody else's mark. Latch-free and
1244
+ * A no-op unless the attempt's action is the one currently marked, so a late call from an attempt
1245
+ * whose cycle has already ended cannot plant transforms under somebody else's mark. Latch-free and
977
1246
  * synchronous, like the mark itself: `TransactionCoordinator` calls it from inside its commit
978
1247
  * span, where it already holds this instance's latch. */
979
- retainInFlightAttempt(actionId: ActionId, attempt: InFlightAttempt): void;
1248
+ retainInFlightAttempt(attempt: InFlightAttempt): void;
980
1249
  /** Ids for the log data blocks a write's log append may have to mint, so a RETRY of that write
981
1250
  * at the same revision sends the same ids the attempt it is repeating sent. Hand the result to
982
1251
  * {@link Log.open} as `newDataBlockId`; it yields remembered ids in order and mints (and
@@ -1017,22 +1286,142 @@ export declare class Collection<TAction> implements ICollection<TAction> {
1017
1286
  * class or throws ({@link SyncRetryExhaustedError} for a write that never landed). Present a change
1018
1287
  * as saved only via `isFullyDurable`, never by comparing `quorum`. */
1019
1288
  sync(options?: SyncOptions): Promise<WriteDurability | undefined>;
1289
+ /** The refresh a write's attempt cycle runs between attempts ({@link AttemptCycle.refreshUntilSettled}):
1290
+ * {@link updateInternal}, under the latch the write already holds and with its action marked in
1291
+ * flight, so the refresh recognises the write's own log entry. */
1292
+ private readonly refreshBetweenAttempts;
1020
1293
  /** Mints the one action id this sync reuses across all of its retry attempts, and owns it for
1021
1294
  * the WHOLE cycle — including the inter-attempt refresh, which is the only thing that reads it
1022
1295
  * (see {@link inFlightActionId}). `sync()`/`updateAndSync()` hold the collection latch across
1023
1296
  * all of this, so the mark's lifetime is contained inside the latched span here; the disposer
1024
1297
  * runs on every exit, including a throw out of retry exhaustion or an abort. */
1025
1298
  private syncInternal;
1026
- /** The retry loop behind {@link syncInternal}, run with `actionId` already marked in flight.
1299
+ /** The retry loop behind {@link syncInternal}, run with the action already marked in flight: the
1300
+ * attempt machinery of {@link AttemptCycle} and {@link stageAttempt}, aimed at the open segment
1301
+ * over the live tracker. {@link commitHead} drives the same machinery at the head segment.
1027
1302
  *
1028
- * @param timestamp the WRITE's time, stamped on the log entry every attempt appends — see
1029
- * {@link syncInternal}, which mints it.
1030
1303
  * @returns the durability of what this sync committed, or `undefined` when the loop never ran a
1031
1304
  * commit (nothing staged). See {@link sync}. */
1032
1305
  private syncAttempts;
1306
+ /** Build one attempt at the revision this collection would commit at next ({@link stageAttempt});
1307
+ * the ids its log append may have to mint come from {@link logAppendBlockIds}, so a retry at the
1308
+ * same revision appends the same entry. */
1309
+ private buildAttempt;
1310
+ /** Send one attempt — pend, then commit — under the cycle's aged retry `priority`, carrying what
1311
+ * the cycle asked of every send ({@link inFlightCycle}). */
1312
+ private send;
1313
+ /** Fold a committed attempt's transforms — the log append included — into this instance's read
1314
+ * cache and adopt the revision it committed at. Every caller does this BEFORE replaying what is
1315
+ * still staged (see the note in {@link syncAttempts}). Takes the transforms out of the attempt's
1316
+ * tracker, which is finished with. */
1317
+ private foldOwnCommit;
1033
1318
  /** Refresh from the transactor, then push. Same return contract as {@link sync}: the durability of
1034
1319
  * what was committed, or `undefined` when nothing was staged and so nothing was written. */
1035
1320
  updateAndSync(options?: SyncOptions): Promise<WriteDurability | undefined>;
1321
+ /** Commit exactly the head sealed segment — the oldest, `entryId` — as one log entry under the
1322
+ * action id and timestamp `options` supplies, for the offline-sync queue's drain
1323
+ * (docs/offline-sync.md §One entry, one network transaction): {@link openHeadCommit} followed by
1324
+ * the one-collection driver, `driveHeadCommit` in head-commit.ts, with the handle closed on every
1325
+ * exit. The attempt machinery is {@link syncAttempts}' ({@link AttemptCycle}, {@link stageAttempt});
1326
+ * what differs is the target — a head tracker ({@link headTrackerFor}) — and the latch, released
1327
+ * around the one network `await` ({@link HeadCommitHandle.release}). `options.recordAttempt` is
1328
+ * called with each attempt before it is sent, and `options.resume` hands back an attempt an
1329
+ * earlier cycle under the same action id recorded (see {@link HeadCommitOptions}).
1330
+ *
1331
+ * @returns what {@link sync} returns: who holds the commit, or `undefined` when the refresh
1332
+ * established that the write was already saved under `options.actionId` without re-sending.
1333
+ * @throws SealedSegmentsError before anything is done, when `entryId` is not the head segment
1334
+ * (`not-head`), carries a recorded refusal (`refused`), or a head commit is already in flight on
1335
+ * this instance (`in-flight`); the head segment's recorded refusal, an {@link ActionRefusedError},
1336
+ * when a refresh or the head tracker's staging refused it during the cycle; whatever
1337
+ * `options.recordAttempt` throws, before anything is sent; otherwise what {@link sync} throws. */
1338
+ commitHead(entryId: EntryId, options: HeadCommitOptions): Promise<WriteDurability | undefined>;
1339
+ /** Open a head commit of `entryId` under `identity` and hand back the handle a driver runs it
1340
+ * through, step by step ({@link HeadCommitHandle}): this is {@link commitHead} with the loop left
1341
+ * to the caller, for the coordinator's per-entry commit over several collections, which runs each
1342
+ * step on every collection it wrote in lock-step. Takes the collection latch, which the handle
1343
+ * holds until its `close()` except around the network round trip; checks the three
1344
+ * preconditions; marks the action in flight for the whole cycle ({@link beginInFlightAction}), as
1345
+ * a sync's is, so the refresh between attempts recognises the write's own entry; sets
1346
+ * {@link headCommit}, which tells {@link consumeOwnEntry} that such an entry records the head
1347
+ * segment; and seeds the retained attempt with `options.resume` when one is given, so that the
1348
+ * opening refresh can finish an earlier cycle's torn attempt from it ({@link completeOwnEntry}) —
1349
+ * and `stage()` re-sends it verbatim while the next attempt would request its revision
1350
+ * ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}), recorded
1351
+ * with the in-flight mark, so the handle's `send()` and a refresh's re-send of a torn attempt both
1352
+ * carry it.
1353
+ *
1354
+ * **The target.** The live tracker holds every sealed segment and the open one, cumulatively, so
1355
+ * an attempt cannot run on a copy of it the way a sync's does. It runs on a HEAD TRACKER instead
1356
+ * ({@link headTrackerFor}): the head segment's actions alone, staged atomically over the
1357
+ * committed state, with pins of their own — built once per requested revision and reused across
1358
+ * attempts, since a rebuild mints fresh ids for the blocks the actions insert and would send
1359
+ * different content under one `(action id, revision)` (the rule {@link logAppendBlockIds}
1360
+ * closes). Staging runs the actions' guards against the committed state; a refusal there is the
1361
+ * segment's refusal, recorded and reported exactly as a replay's would be, and thrown out of
1362
+ * `stage()`.
1363
+ *
1364
+ * **The latch.** Held for every step EXCEPT the one `await` on the network, so `act`,
1365
+ * `sealPending`, `update` and the rest are not blocked behind a commit that can take seconds
1366
+ * (docs/offline-sync.md §The drain does not hold the collection latch across the network). While
1367
+ * it is released {@link headInFlight} is set: a refresh that walks into this commit's entry defers
1368
+ * to it, and `dropSealed` of the head refuses. A second head commit on this instance waits on the
1369
+ * latch and then meets the `in-flight` precondition.
1370
+ *
1371
+ * **The head's recorded refusal** is re-checked by `stage()` before every attempt and by
1372
+ * `refused()` after every refused send, because a refresh that adopted a rival — a reader's,
1373
+ * while the latch was released, or this cycle's own — may have replayed and refused it; each
1374
+ * throws the recorded refusal in place of another attempt. On success the driver calls `fold()`
1375
+ * (remove the head segment, bump the segment version, fold the attempt's transforms into the
1376
+ * cache and adopt its revision) and only THEN `replay()` (the remaining segments and the open
1377
+ * segment over the committed state that now holds the head) — the fold-before-replay order
1378
+ * {@link syncAttempts} takes, which anything staged while the commit was on the network relies on.
1379
+ *
1380
+ * A driver that opens handles on more than one collection opens them in sorted collection-id
1381
+ * order, the order `TransactionCoordinator.commitOnce` takes the same latches in; see the
1382
+ * interface.
1383
+ *
1384
+ * @throws Error before the latch is taken when `options.resume` was recorded under an action other than
1385
+ * `identity.actionId` — a caller defect, since the attempt would be re-sent under the wrong id;
1386
+ * SealedSegmentsError, with the latch released again, when `entryId` is not the head segment
1387
+ * (`not-head`), carries a recorded refusal (`refused`), or a head commit is already in flight on
1388
+ * this instance (`in-flight`). */
1389
+ openHeadCommit(entryId: EntryId, identity: WriteIdentity, options?: OpenHeadCommitOptions): Promise<HeadCommitHandle>;
1390
+ /** The handle {@link openHeadCommit} returns: closures over this instance's private state, so
1391
+ * nothing private becomes public. `release` is the latch release of the latch the caller took;
1392
+ * `endInFlight` the disposer of the in-flight mark. The head tracker lives here, per handle, so it
1393
+ * is reused across the attempts of one cycle exactly as the in-line loop reused it. `resume` is
1394
+ * the attempt the cycle was opened with, which `stage()` re-sends verbatim while the next attempt
1395
+ * would request its revision ({@link resumedAttempt}). */
1396
+ private headCommitHandle;
1397
+ /** {@link commitHead}'s preconditions, each a {@link SealedSegmentsError} naming its reason. */
1398
+ private assertHeadCommittable;
1399
+ /** The head segment, which a running head commit may still commit: it is `entryId` — anything
1400
+ * else is a defect ({@link headSegment}) — and it has not been refused meanwhile. A refresh that
1401
+ * adopted a rival may have replayed and refused it, and that refusal, not another attempt, is
1402
+ * then the cycle's answer. */
1403
+ private committableHead;
1404
+ /** The head segment, asserted to be `entryId`. Nothing may remove the head while a head commit
1405
+ * of it runs — a refresh that meets it defers, `dropSealed` of it refuses — so anything else here
1406
+ * is a defect, thrown as one. */
1407
+ private headSegment;
1408
+ /** The tracker a head attempt is built from (see {@link commitHead}): `current`, while it was
1409
+ * built for the revision the next attempt requests and no base under it has moved; otherwise a
1410
+ * fresh one ({@link buildHeadTracker}). A revision that moved is a write that is genuinely
1411
+ * different. A base that moved at the same revision is re-judged exactly as
1412
+ * {@link restageIfBasesMoved} re-judges the live queue before an attempt, and rebuilds.
1413
+ * NOTE: that rebuild is the same exception to the byte-identical retry that {@link syncAttempts}
1414
+ * records at its `restageIfBasesMoved` call — fresh ids for the blocks the actions insert under
1415
+ * an unchanged `(action id, revision)` — reached the same narrow way and refused by storage's
1416
+ * base guard on the same machines; the same answer applies if it is ever seen. */
1417
+ private headTrackerFor;
1418
+ /** A tracker over this instance's read cache, with pins of its own, holding `segment`'s actions
1419
+ * staged atomically over the committed state — from the invented baseline while this collection
1420
+ * has no committed revision ({@link replayBaseline}): its header, log block and root then exist
1421
+ * nowhere else, and the head's commit has to carry them. A refusal is the segment's own,
1422
+ * recorded and reported ({@link recordSealedRefusal}) and thrown; a live replay that found it
1423
+ * first has already done the recording, and the caller never gets here. */
1424
+ private buildHeadTracker;
1036
1425
  /** Stage `actions` and flush them as one call that either takes effect or leaves NOTHING behind:
1037
1426
  * when the flush throws, the actions this call staged are unstaged again before the error escapes.
1038
1427
  *
@@ -1057,14 +1446,42 @@ export declare class Collection<TAction> implements ICollection<TAction> {
1057
1446
  * revision from before the actions were staged.
1058
1447
  *
1059
1448
  * While the held revision has not moved, the earlier transforms are reinstated verbatim rather
1060
- * than rebuilt by replay: an INVENTED collection keeps its header and root in the tracker with
1061
- * no staged action naming them, and a replay (which resets the tracker first) would drop them —
1062
- * the hazard {@link mustReplay} and {@link snapshotPending} document. Once the revision has
1063
- * moved those transforms describe blocks at a revision this handle has left, so what remains is
1064
- * re-staged against the adopted one, exactly as a refresh would have done. */
1449
+ * than rebuilt by replay: they are exactly the state before the call, and reinstating them costs
1450
+ * no handler run (a replay would rebuild the same state from {@link inventedBaseline} and the
1451
+ * staged actions). Once the revision has moved those transforms describe blocks at a revision
1452
+ * this handle has left, so what remains is re-staged against the adopted one, exactly as a
1453
+ * refresh would have done. */
1065
1454
  private unstage;
1066
1455
  selectLog(forward?: boolean): AsyncIterableIterator<Action<TAction>>;
1456
+ /** Rebuild the tracker from the staged actions over the committed state this collection now
1457
+ * reads at (always called under latch): reset to {@link replayBaseline}, then every sealed
1458
+ * segment in order, then the open segment.
1459
+ *
1460
+ * A SEALED segment is staged as ONE atomic unit — one `internalTransact` call over all of its
1461
+ * actions — so a refusal of any action in it leaves none of its writes staged, and a refusal
1462
+ * ({@link ActionRefusedError}, the only class caught) is that segment's own: recorded on it,
1463
+ * reported through `onSealedRefused`, and the replay goes on to the next segment. A segment
1464
+ * already refused is skipped and not reported again; it stays listed until dropped. The OPEN
1465
+ * segment keeps the pre-segment behaviour: one `internalTransact` per action, and a refusal
1466
+ * propagates, since it is the live transaction's own (docs/offline-sync.md §Replay with a
1467
+ * per-segment refusal). Any error that is not a refusal propagates from either.
1468
+ *
1469
+ * Each re-staged update pins its base through `Atomic.commit` → `Tracker.absorb`, the path
1470
+ * {@link act} uses, so the pend declares the bases the re-staged operations were computed on. Each
1471
+ * sealed segment that staged records what its actions accepted as already applied
1472
+ * (`SealedSegment.applied`), the tally the head commit reports when the segment is committed.
1473
+ *
1474
+ * @param unreported - a segment whose refusal is recorded but NOT reported through
1475
+ * `onSealedRefused`: the one {@link restoreSealed} is inserting, whose caller reads the recorded
1476
+ * refusal off the segment itself. */
1067
1477
  private replayActions;
1478
+ /** What a replay resets the tracker to: a copy of {@link inventedBaseline} while this collection
1479
+ * holds no committed revision (those blocks exist nowhere else), and nothing otherwise. */
1480
+ private replayBaseline;
1481
+ /** Record a replay's refusal of a sealed segment and, when `report` says so, report it once,
1482
+ * under the latch. The callback's throw is logged rather than raised: the refusal is already
1483
+ * recorded, and the rest of the replay must still run. */
1484
+ private recordSealedRefusal;
1068
1485
  getReadDependencies(): ReadDependency[];
1069
1486
  clearReadDependencies(): void;
1070
1487
  /** Called for each local action that may be in conflict with a remote action (always called under latch).
@@ -1081,13 +1498,9 @@ export declare class Collection<TAction> implements ICollection<TAction> {
1081
1498
  * than kept, because nothing proves it is current at the revision the refresh will pin to.
1082
1499
  *
1083
1500
  * Both answers pass {@link answeredBlock}'s checks as unpinned reads, header first, so a doubted
1084
- * header or tail throws exactly as it would through {@link TransactorSource.tryGet}.
1085
- *
1086
- * NOTE: a batched get fails as a whole when any block in it gets no answer
1087
- * (`NetworkTransactor.get` throws on a missing id), so an unreachable out-of-date tail fails a
1088
- * refresh that would not have needed it. Harmless today: the log has no checkpoints, so a
1089
- * refresh that finds a new tail walks back through the old one anyway. If checkpoints start
1090
- * letting that walk stop short, read the known tail in its own request instead.
1501
+ * header or tail throws exactly as it would through {@link TransactorSource.tryGet}. An
1502
+ * out-of-date tail no coordinator answered comes back flagged (`NetworkTransactor.get` flags that
1503
+ * one block rather than failing the request), and its answer is dropped unjudged.
1091
1504
  *
1092
1505
  * `tailFloor` (see {@link updateInternal}) goes on whichever request reads the tail — never on
1093
1506
  * the header, which is rewritten only when the tail rolls over or the collection changes it