@optimystic/db-core 1.21.0 → 1.23.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 (181) hide show
  1. package/README.md +8 -4
  2. package/dist/src/btree/btree.d.ts +36 -4
  3. package/dist/src/btree/btree.d.ts.map +1 -1
  4. package/dist/src/btree/btree.js +86 -18
  5. package/dist/src/btree/btree.js.map +1 -1
  6. package/dist/src/collection/action.d.ts +7 -4
  7. package/dist/src/collection/action.d.ts.map +1 -1
  8. package/dist/src/collection/action.js +13 -5
  9. package/dist/src/collection/action.js.map +1 -1
  10. package/dist/src/collection/collection.d.ts +177 -51
  11. package/dist/src/collection/collection.d.ts.map +1 -1
  12. package/dist/src/collection/collection.js +265 -81
  13. package/dist/src/collection/collection.js.map +1 -1
  14. package/dist/src/collection/struct.d.ts +44 -8
  15. package/dist/src/collection/struct.d.ts.map +1 -1
  16. package/dist/src/collection/struct.js.map +1 -1
  17. package/dist/src/collection/write-attempts.d.ts +138 -34
  18. package/dist/src/collection/write-attempts.d.ts.map +1 -1
  19. package/dist/src/collection/write-attempts.js +168 -101
  20. package/dist/src/collection/write-attempts.js.map +1 -1
  21. package/dist/src/collections/diary/diary.d.ts.map +1 -1
  22. package/dist/src/collections/diary/diary.js +5 -1
  23. package/dist/src/collections/diary/diary.js.map +1 -1
  24. package/dist/src/collections/tree/tree.d.ts +18 -10
  25. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  26. package/dist/src/collections/tree/tree.js +17 -9
  27. package/dist/src/collections/tree/tree.js.map +1 -1
  28. package/dist/src/hlc/clock-store.d.ts +63 -0
  29. package/dist/src/hlc/clock-store.d.ts.map +1 -0
  30. package/dist/src/hlc/clock-store.js +49 -0
  31. package/dist/src/hlc/clock-store.js.map +1 -0
  32. package/dist/src/hlc/clock.d.ts +64 -0
  33. package/dist/src/hlc/clock.d.ts.map +1 -0
  34. package/dist/src/hlc/clock.js +171 -0
  35. package/dist/src/hlc/clock.js.map +1 -0
  36. package/dist/src/hlc/hlc.d.ts +38 -0
  37. package/dist/src/hlc/hlc.d.ts.map +1 -0
  38. package/dist/src/hlc/hlc.js +41 -0
  39. package/dist/src/hlc/hlc.js.map +1 -0
  40. package/dist/src/hlc/index.d.ts +5 -0
  41. package/dist/src/hlc/index.d.ts.map +1 -0
  42. package/dist/src/hlc/index.js +5 -0
  43. package/dist/src/hlc/index.js.map +1 -0
  44. package/dist/src/hlc/skew.d.ts +35 -0
  45. package/dist/src/hlc/skew.d.ts.map +1 -0
  46. package/dist/src/hlc/skew.js +35 -0
  47. package/dist/src/hlc/skew.js.map +1 -0
  48. package/dist/src/index.d.ts +2 -0
  49. package/dist/src/index.d.ts.map +1 -1
  50. package/dist/src/index.js +2 -0
  51. package/dist/src/index.js.map +1 -1
  52. package/dist/src/lane/index.d.ts +2 -0
  53. package/dist/src/lane/index.d.ts.map +1 -0
  54. package/dist/src/lane/index.js +2 -0
  55. package/dist/src/lane/index.js.map +1 -0
  56. package/dist/src/lane/lane.d.ts +46 -0
  57. package/dist/src/lane/lane.d.ts.map +1 -0
  58. package/dist/src/lane/lane.js +26 -0
  59. package/dist/src/lane/lane.js.map +1 -0
  60. package/dist/src/log/log.d.ts +50 -22
  61. package/dist/src/log/log.d.ts.map +1 -1
  62. package/dist/src/log/log.js +21 -13
  63. package/dist/src/log/log.js.map +1 -1
  64. package/dist/src/log/struct.d.ts +61 -1
  65. package/dist/src/log/struct.d.ts.map +1 -1
  66. package/dist/src/log/struct.js +24 -0
  67. package/dist/src/log/struct.js.map +1 -1
  68. package/dist/src/network/i-repo.d.ts +10 -0
  69. package/dist/src/network/i-repo.d.ts.map +1 -1
  70. package/dist/src/network/stale-failure.d.ts +20 -7
  71. package/dist/src/network/stale-failure.d.ts.map +1 -1
  72. package/dist/src/network/stale-failure.js +29 -7
  73. package/dist/src/network/stale-failure.js.map +1 -1
  74. package/dist/src/network/struct.d.ts +50 -0
  75. package/dist/src/network/struct.d.ts.map +1 -1
  76. package/dist/src/network/struct.js.map +1 -1
  77. package/dist/src/offline/entry.d.ts +14 -0
  78. package/dist/src/offline/entry.d.ts.map +1 -1
  79. package/dist/src/offline/entry.js +2 -0
  80. package/dist/src/offline/entry.js.map +1 -1
  81. package/dist/src/offline/journal.d.ts +10 -0
  82. package/dist/src/offline/journal.d.ts.map +1 -1
  83. package/dist/src/offline/queue.d.ts +10 -0
  84. package/dist/src/offline/queue.d.ts.map +1 -1
  85. package/dist/src/offline/queue.js +29 -3
  86. package/dist/src/offline/queue.js.map +1 -1
  87. package/dist/src/offline/status.d.ts +7 -0
  88. package/dist/src/offline/status.d.ts.map +1 -1
  89. package/dist/src/offline/status.js.map +1 -1
  90. package/dist/src/testing/test-transactor.d.ts +9 -1
  91. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  92. package/dist/src/testing/test-transactor.js +12 -3
  93. package/dist/src/testing/test-transactor.js.map +1 -1
  94. package/dist/src/transaction/actions-engine.d.ts +3 -0
  95. package/dist/src/transaction/actions-engine.d.ts.map +1 -1
  96. package/dist/src/transaction/actions-engine.js +3 -0
  97. package/dist/src/transaction/actions-engine.js.map +1 -1
  98. package/dist/src/transaction/coordinator.d.ts +16 -5
  99. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  100. package/dist/src/transaction/coordinator.js +203 -48
  101. package/dist/src/transaction/coordinator.js.map +1 -1
  102. package/dist/src/transaction/entry-commit.d.ts +45 -10
  103. package/dist/src/transaction/entry-commit.d.ts.map +1 -1
  104. package/dist/src/transaction/entry-commit.js +20 -7
  105. package/dist/src/transaction/entry-commit.js.map +1 -1
  106. package/dist/src/transaction/errors.d.ts +69 -1
  107. package/dist/src/transaction/errors.d.ts.map +1 -1
  108. package/dist/src/transaction/errors.js +70 -1
  109. package/dist/src/transaction/errors.js.map +1 -1
  110. package/dist/src/transaction/index.d.ts +1 -1
  111. package/dist/src/transaction/index.d.ts.map +1 -1
  112. package/dist/src/transaction/index.js +1 -1
  113. package/dist/src/transaction/index.js.map +1 -1
  114. package/dist/src/transaction/session.d.ts.map +1 -1
  115. package/dist/src/transaction/session.js +18 -5
  116. package/dist/src/transaction/session.js.map +1 -1
  117. package/dist/src/transaction/transaction.d.ts +74 -15
  118. package/dist/src/transaction/transaction.d.ts.map +1 -1
  119. package/dist/src/transaction/transaction.js +35 -15
  120. package/dist/src/transaction/transaction.js.map +1 -1
  121. package/dist/src/transaction/validator.d.ts +25 -4
  122. package/dist/src/transaction/validator.d.ts.map +1 -1
  123. package/dist/src/transaction/validator.js +45 -5
  124. package/dist/src/transaction/validator.js.map +1 -1
  125. package/dist/src/transactor/block-floors.d.ts +12 -1
  126. package/dist/src/transactor/block-floors.d.ts.map +1 -1
  127. package/dist/src/transactor/block-floors.js +14 -1
  128. package/dist/src/transactor/block-floors.js.map +1 -1
  129. package/dist/src/transactor/network-transactor.d.ts +8 -0
  130. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  131. package/dist/src/transactor/network-transactor.js +9 -4
  132. package/dist/src/transactor/network-transactor.js.map +1 -1
  133. package/dist/src/transactor/transactor-source.d.ts +11 -0
  134. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  135. package/dist/src/transactor/transactor-source.js +5 -1
  136. package/dist/src/transactor/transactor-source.js.map +1 -1
  137. package/dist/src/transactor/transactor.d.ts +8 -0
  138. package/dist/src/transactor/transactor.d.ts.map +1 -1
  139. package/dist/src/transform/cache-source.d.ts +7 -0
  140. package/dist/src/transform/cache-source.d.ts.map +1 -1
  141. package/dist/src/transform/cache-source.js +14 -18
  142. package/dist/src/transform/cache-source.js.map +1 -1
  143. package/package.json +1 -1
  144. package/src/btree/btree.ts +92 -18
  145. package/src/collection/action.ts +13 -5
  146. package/src/collection/collection.ts +3272 -3039
  147. package/src/collection/struct.ts +493 -456
  148. package/src/collection/write-attempts.ts +213 -109
  149. package/src/collections/diary/diary.ts +5 -1
  150. package/src/collections/tree/tree.ts +33 -18
  151. package/src/hlc/clock-store.ts +68 -0
  152. package/src/hlc/clock.ts +196 -0
  153. package/src/hlc/hlc.ts +56 -0
  154. package/src/hlc/index.ts +4 -0
  155. package/src/hlc/skew.ts +55 -0
  156. package/src/index.ts +2 -0
  157. package/src/lane/index.ts +1 -0
  158. package/src/lane/lane.ts +54 -0
  159. package/src/log/log.ts +341 -310
  160. package/src/log/struct.ts +62 -1
  161. package/src/network/i-repo.ts +11 -1
  162. package/src/network/stale-failure.ts +31 -7
  163. package/src/network/struct.ts +50 -0
  164. package/src/offline/entry.ts +16 -0
  165. package/src/offline/journal.ts +10 -0
  166. package/src/offline/queue.ts +38 -4
  167. package/src/offline/status.ts +7 -0
  168. package/src/testing/test-transactor.ts +1065 -1050
  169. package/src/transaction/actions-engine.ts +3 -0
  170. package/src/transaction/coordinator.ts +235 -54
  171. package/src/transaction/entry-commit.ts +56 -14
  172. package/src/transaction/errors.ts +60 -0
  173. package/src/transaction/index.ts +1 -1
  174. package/src/transaction/session.ts +18 -5
  175. package/src/transaction/transaction.ts +90 -17
  176. package/src/transaction/validator.ts +46 -5
  177. package/src/transactor/block-floors.ts +15 -1
  178. package/src/transactor/network-transactor.ts +1908 -1896
  179. package/src/transactor/transactor-source.ts +15 -1
  180. package/src/transactor/transactor.ts +9 -0
  181. package/src/transform/cache-source.ts +15 -17
@@ -1,456 +1,493 @@
1
- import type { IBlock, BlockId, Action, ActionId, Transforms, WriteDurability } from "../index.js";
2
- import type { IChainHeader } from "../chain/chain-nodes.js";
3
- import type { RandFn } from "../utility/backoff.js";
4
- import type { EntryId } from "./segments.js";
5
- import type { AlreadyAppliedTally } from "./action.js";
6
- import type { BlockBaseRevs, BlockContentDigests } from "../network/struct.js";
7
-
8
- export type CollectionId = BlockId;
9
-
10
- /**
11
- * A handler's statement that an action cannot be applied over the committed state it is being
12
- * replayed against — a uniqueness or lost-update check failed. Not a transport failure and never
13
- * retryable: the action's staged writes are discarded (the handler runs inside an Atomic), and
14
- * nothing downgrades it to a stale failure. `TreeGuardRefusedError` in
15
- * `packages/db-core/src/collections/tree/struct.ts` is the tree's subclass, and carries the
16
- * contract every refusal obeys.
17
- *
18
- * Lives here rather than beside the tree so the collection can recognise a refusal without
19
- * importing the tree module (which imports the collection). Segment-aware replay
20
- * (`Collection.replayActions`) treats a throw of this class from a SEALED segment as that
21
- * segment's refusal and keeps going; from the open segment it propagates as it always has.
22
- */
23
- export class ActionRefusedError extends Error {
24
- constructor(
25
- /** The collection whose handler refused the action. */
26
- readonly collectionId: CollectionId,
27
- message: string,
28
- ) {
29
- super(message);
30
- this.name = 'ActionRefusedError';
31
- }
32
- }
33
-
34
- /** Why a sealed segment stood in the way of a commit (see {@link SealedSegmentsError}):
35
- * - `whole-collection` — a whole-collection commit was asked for while a segment is sealed.
36
- * - `not-head` — `commitHead` named a segment that is not the oldest sealed one.
37
- * - `refused` — `commitHead` named a segment a replay has refused; the queue drops it instead.
38
- * - `in-flight` — a head commit is on the network for the named segment, so neither a second
39
- * `commitHead` nor a `dropSealed` of it can proceed. */
40
- export type SealedSegmentsReason = 'whole-collection' | 'not-head' | 'refused' | 'in-flight';
41
-
42
- /**
43
- * Thrown by the whole-collection commit paths — {@link ICollection.sync},
44
- * {@link ICollection.updateAndSync}, `Collection.actAndSync` and `Collection.getPendingActions`
45
- * (the coordinator's append) — while the collection holds sealed segments. Those paths commit
46
- * everything staged as ONE log entry under one action id; over sealed segments that would merge
47
- * several queue entries into one, which the queue's identity rules forbid
48
- * (docs/offline-sync.md §Identity across attempts). A sealed segment is committed on its own,
49
- * through `Collection.commitHead`, whose own preconditions throw this class too, with a
50
- * {@link reason} other than `whole-collection` (see {@link SealedSegmentsReason}).
51
- *
52
- * Nothing is unstaged or changed when this is thrown: every segment, sealed and open, is exactly
53
- * as it was.
54
- */
55
- export class SealedSegmentsError extends Error {
56
- constructor(
57
- readonly collectionId: CollectionId,
58
- /** The sealed segments' entry ids, in order. */
59
- readonly sealedEntries: EntryId[],
60
- readonly reason: SealedSegmentsReason = 'whole-collection',
61
- /** The entry a `commitHead` or `dropSealed` named, for every reason but `whole-collection`. */
62
- readonly entryId?: EntryId,
63
- ) {
64
- super(sealedSegmentsMessage(collectionId, sealedEntries, reason, entryId));
65
- this.name = 'SealedSegmentsError';
66
- }
67
- }
68
-
69
- function sealedSegmentsMessage(collectionId: CollectionId, sealedEntries: EntryId[], reason: SealedSegmentsReason, entryId: EntryId | undefined): string {
70
- const listed = sealedEntries.length === 0 ? 'nothing' : sealedEntries.join(', ');
71
- switch (reason) {
72
- case 'whole-collection':
73
- return `collection ${collectionId} holds sealed segment(s) ${listed}; `
74
- + `a whole-collection commit would merge them into one log entry — commit the head segment instead`;
75
- case 'not-head':
76
- return `collection ${collectionId}: entry ${entryId} is not the head sealed segment (sealed: ${listed}); `
77
- + `only the oldest sealed segment can be committed`;
78
- case 'refused':
79
- return `collection ${collectionId}: entry ${entryId} carries a recorded refusal; `
80
- + `a refused segment is dropped, never committed`;
81
- case 'in-flight':
82
- return `collection ${collectionId}: a head commit of entry ${entryId} is in flight on this instance`;
83
- }
84
- }
85
-
86
- /** Exactly what one write attempt sent to the transactor — enough to send the same thing again.
87
- * Retained by `Collection.retainInFlightAttempt` so that a refresh which then finds this attempt's
88
- * own log entry can land the blocks the attempt left behind, at the same action id and revision
89
- * (see `Collection.completeOwnEntry`).
90
- *
91
- * Also the shape a caller RECORDS before an attempt is sent and hands back on a later cycle
92
- * ({@link HeadCommitOptions.recordAttempt} and {@link HeadCommitOptions.resume};
93
- * docs/offline-sync.md §Identity across attempts), so it must stay plain data — ids, numbers and the
94
- * transforms as the wire carries them, nothing with object identity and no functions: the
95
- * offline-sync journal serialises it as JSON. */
96
- export type InFlightAttempt = {
97
- /** The action id the attempt was sent under — the one every attempt of the write reuses, and
98
- * the one a cycle that resumes from this record must run under. */
99
- actionId: ActionId;
100
- /** The revision the attempt's log entry was stamped with, and pended and committed at. */
101
- rev: number;
102
- /** Every transform the attempt pended — the log blocks included. The caller hands over a copy
103
- * it will not mutate; the collection keeps it as given. */
104
- transforms: Transforms;
105
- /** The attempt's log tail block, committed first. */
106
- tailId: BlockId;
107
- /** The per-block content declarations the attempt's commit carried, if any. */
108
- blockDigests?: BlockContentDigests;
109
- /** The per-block bases the attempt's pend carried, if any (see `PendRequest.baseRevs`). Kept
110
- * with the transforms because they describe them: a re-send of these operations must name the
111
- * same bases they were computed against. */
112
- baseRevs?: BlockBaseRevs;
113
- };
114
-
115
- /** What `Collection.commitHead` commits the head segment under, beside the retry bounds of
116
- * {@link SyncOptions}. Both fields are the queue's (docs/offline-sync.md §Identity across
117
- * attempts): the collection mints neither. */
118
- export type HeadCommitOptions = SyncOptions & {
119
- /** The action id the attempt cycle runs under. The queue mints it, and re-supplies the SAME id
120
- * when it re-drives an entry whose earlier attempt may have landed, so the refresh that opens the
121
- * cycle recognises that attempt's log entry as the write's own and finishes or consumes it
122
- * instead of committing a second copy. */
123
- actionId: ActionId;
124
- /** The entry's local commit time, stamped on the log entry in place of the time
125
- * `Collection.syncInternal` mints for a sync. Fixed per write, so every attempt appends the same
126
- * entry (see "A write's log append is a fixed function of the write and the revision it is
127
- * requesting" in docs/internals.md). */
128
- timestamp: number;
129
- /** The write-ahead hook: called with each attempt exactly as it is about to be sent — after it is
130
- * built and BEFORE the collection latch is released for the network — and awaited under that
131
- * latch. It is where the queue records the attempt's identity before sending it
132
- * (docs/offline-sync.md §Identity across attempts) and, later, where the journal writes it. A
133
- * throw aborts the cycle before anything is sent: it escapes `commitHead` unchanged, the handle
134
- * closes, and every segment is exactly as it was. */
135
- recordAttempt?: (attempt: InFlightAttempt) => Promise<void>;
136
- /** The attempt an earlier cycle under the SAME `actionId` handed to `recordAttempt` and did not
137
- * resolve — it must carry this `actionId`, and `openHeadCommit` throws before touching anything
138
- * when it does not. Seeded as the retained attempt right after the action is marked in flight,
139
- * so the cycle's opening refresh, finding that attempt's log entry with blocks missing, finishes
140
- * it from these transforms (`Collection.completeOwnEntry`) instead of refusing it as torn with
141
- * `transforms-not-held`. Without it a re-drive can recognise only an attempt that landed whole.
142
- * The revision check still applies: an attempt recorded at a revision other than the entry's is
143
- * refused as before. And when that refresh finds nothing new, this attempt is what the cycle
144
- * re-sends, verbatim, while the next attempt would request its revision (`resumedAttempt`), since
145
- * it may have landed on machines the refresh did not hear from. */
146
- resume?: InFlightAttempt;
147
- /** Called once, with what the head segment's actions accepted as already applied
148
- * ({@link AlreadyAppliedTally}, as recorded on the segment by its last staging over the committed
149
- * state), at the moment the segment is made durable and dropped: when the committed attempt is
150
- * folded (`HeadCommitHandle.fold`), or when the cycle's refresh finds the entry's own log entry and
151
- * consumes the head (`Collection.consumeHead`) — so a re-drive that finds its earlier attempt landed
152
- * reports it too. Runs synchronously under the collection latch, like `onSealedRefused`, so it must
153
- * not call a latched method of the collection; the queue's closure only records into a map. A throw
154
- * out of it is logged, never raised: the commit is already durable. A hook rather than a widened
155
- * return type because the partial-commit path reports the committed half through
156
- * `CoordinatorPartialCommitError` and the refresh-consumed path through `RefreshReport`; one hook
157
- * reaches all three. */
158
- onCommittedHead?: (applied: AlreadyAppliedTally) => void;
159
- };
160
-
161
- export type CollectionHeaderBlock = IBlock & Partial<IChainHeader>;
162
-
163
- /** A collection's committed tail: the log tail block its header names, and that block's latest
164
- * committed revision, which is the collection's (every commit touches the log tail). */
165
- export type CommittedTail = { tailId: BlockId; rev: number };
166
-
167
- /** One collection a batched committed-tail read names (`Collection.readCommittedTails`). */
168
- export type CommittedTailQuery = {
169
- readonly id: CollectionId;
170
- /** The tail block the caller's previous read found. While the header still names it, the read
171
- * needs no second request for this collection. */
172
- readonly knownTailId?: BlockId;
173
- };
174
-
175
- /** One collection's answer to a batched committed-tail read: its tail (`undefined` when it has
176
- * never committed), or why reading it failed — what the single-collection read would have thrown. */
177
- export type CommittedTailAnswer =
178
- | { readonly tail: CommittedTail | undefined }
179
- | { readonly error: unknown };
180
-
181
- /** Bounds the retry loop inside {@link ICollection.sync} / {@link ICollection.updateAndSync}
182
- * so a transactor that keeps rejecting the sync can no longer spin the collection latch forever.
183
- * All fields are optional; unset fields fall back to conservative defaults. */
184
- export interface SyncOptions {
185
- /** Max consecutive stale-failure retries that make no progress before giving up.
186
- * The counter resets to 0 on every successful commit, so a legitimate large multi-batch
187
- * sync (which iterates many times making forward progress) is never falsely tripped.
188
- * Default 10. */
189
- maxAttempts?: number;
190
- /** Optional wall-clock deadline in ms measured from the start of the sync call. Independent
191
- * of the attempt count — a progress-agnostic ceiling. Unset means no deadline. */
192
- deadlineMs?: number;
193
- /** Base backoff delay in ms applied before the first retry; subsequent retries grow the delay
194
- * exponentially up to {@link maxBackoffMs}. Default 100. Not applied once `SlotHoldAfterLosses` of the
195
- * write's refused attempts carried a confirmed committed revision (`StaleFailure.staleAt`) and the
196
- * latest refusal is one of them: a member then holds the next slot for this write,
197
- * and the retry follows at once rather than spending the hold asleep. */
198
- baseBackoffMs?: number;
199
- /** Upper bound on any single backoff sleep, in ms. Default 5000. Like {@link baseBackoffMs}, not
200
- * applied to a retry that follows at once because a member holds the slot for this write. */
201
- maxBackoffMs?: number;
202
- /** Optional abort signal. Checked at the top of each loop iteration and raced against the
203
- * backoff sleep, so an aborted sync rejects promptly (with an AbortError) rather than finishing
204
- * the current sleep. */
205
- signal?: AbortSignal;
206
- /** Advanced/testing hook: source of uniform [0,1) randomness for the backoff jitter. Defaults to
207
- * the package CSPRNG; inject a deterministic sequence to assert exact retry delays. */
208
- rand?: RandFn;
209
- /** Consecutive refreshes that move this collection's revision NOWHERE while a responder has
210
- * CONFIRMED a revision at or above the one the next attempt would request, before sync gives up
211
- * with {@link SyncRevisionStalledError}. Such a retry provably re-sends the identical, already
212
- * lost request, so the wait buys nothing. Two absorbs one transiently-lagging read; set it to
213
- * {@link maxAttempts} or higher to restore the pre-existing behaviour of burning the whole
214
- * budget. Default 2.
215
- *
216
- * Neither shape of progress trips this. Ordinary contention: the rival's commit is what the
217
- * refresh adopts, so the next request lands above the confirmed revision. A collection still
218
- * catching up: the refresh moves the revision forward without yet clearing the confirmed
219
- * number, so the next request differs from the one that just failed. Either resets the counter.
220
- * {@link deadlineMs} is still checked first, so a sync that is both past its deadline and
221
- * stalled reports the deadline (as {@link SyncRetryExhaustedError}), not the stall. */
222
- maxStalledAttempts?: number;
223
- /** Refuse to let this write be committed by a lone node — a coordinator whose cohort for the
224
- * write is only itself — while that node knows of members of the cohort it could not reach, is
225
- * still waiting to hear from a peer it was configured to join through, or could not route the
226
- * write at all. A node that is genuinely alone (no absent member known, nothing awaited, routed to
227
- * itself) still commits. The refusal is a promise shortfall (`PromiseShortfallError`, with
228
- * `soloRefused` naming the reason), so the write stops and is classified `cohort-unreachable`.
229
- * Rides on every send of the write's attempt cycle as `PendRequest.refuseSolo` and
230
- * `CommitRequest.refuseSolo`. Default off: only the offline queue sets it (docs/offline-sync.md
231
- * §When to submit: the reachability gate). A coordinator on a build that predates the field
232
- * ignores it and commits alone as before. */
233
- refuseSoloCommit?: boolean;
234
- }
235
-
236
- /** What a write's attempt cycle carries besides its identity, recorded beside the in-flight mark
237
- * (`Collection.beginInFlightAction`) so that every send of the cycle carries it: each attempt, and
238
- * the re-send a refresh makes to finish a torn one (`Collection.completeOwnEntry`). */
239
- export type InFlightCycle = {
240
- /** {@link SyncOptions.refuseSoloCommit}, for this cycle. */
241
- readonly refuseSolo?: boolean;
242
- };
243
-
244
- /** What `Collection.openHeadCommit` opens a head commit with besides its identity: the cycle's
245
- * {@link InFlightCycle}, the attempt an earlier cycle under the same action id recorded and did not
246
- * resolve ({@link HeadCommitOptions.resume}), and the committed-head hook
247
- * ({@link HeadCommitOptions.onCommittedHead}). */
248
- export type OpenHeadCommitOptions = InFlightCycle & {
249
- readonly resume?: InFlightAttempt;
250
- readonly onCommittedHead?: (applied: AlreadyAppliedTally) => void;
251
- };
252
-
253
- /** Thrown by {@link ICollection.sync} / {@link ICollection.updateAndSync} when the retry budget
254
- * (attempt count or deadline) is exhausted while the transactor keeps returning stale failures.
255
- * Catchable so callers can surface a clear "gave up syncing" condition instead of hanging.
256
- *
257
- * It says the write was NOT SAVED; it does not prove nothing was stored. A write's log tail is
258
- * committed before its other blocks, and the attempt that spent the budget is not followed by a
259
- * refresh, so that attempt's log entry may be standing in the log with none of its data — the state
260
- * {@link TornActionError} names when a refresh does get to see it. */
261
- export class SyncRetryExhaustedError extends Error {
262
- constructor(
263
- readonly collectionId: CollectionId,
264
- readonly attempts: number,
265
- readonly lastReason?: string,
266
- /** The last confirmed revision a responder reported holding, if any responder reported one
267
- * (see `StaleFailure.staleAt`). Absent whenever no rejection carried a confirmed number —
268
- * which is normal, not a signal that the failure was something other than a lost race. */
269
- readonly staleAt?: { blockId: BlockId; rev: number },
270
- ) {
271
- super(`sync for collection ${collectionId} exhausted ${attempts} retries` +
272
- (lastReason ? `: ${lastReason}` : '') +
273
- (staleAt ? `, last seen block ${staleAt.blockId} at rev ${staleAt.rev}` : ''));
274
- this.name = 'SyncRetryExhaustedError';
275
- }
276
- }
277
-
278
- /** Thrown by {@link ICollection.sync} / {@link ICollection.updateAndSync} when refreshing
279
- * repeatedly moved this collection nowhere at all while a responder confirmed a revision at or
280
- * above the one being requested — the client's view of the current revision disagrees with the
281
- * cluster's, and retrying would re-send the identical taken number.
282
- *
283
- * The distinction matters because the two failures need different responses. Plain exhaustion
284
- * means "I lost a race too many times", and waiting longer or retrying later can succeed. This
285
- * one means the next attempt is provably identical to the one that just failed, so the remaining
286
- * budget buys nothing — the caller's view of the collection has to be repaired first.
287
- *
288
- * Sync deliberately does NOT adopt the responder's revision to get past this. `staleAt` is a bare
289
- * number, not content: submitting this client's staged transforms at a revision built on a
290
- * history it never read would overwrite that history silently. Reconciling a genuine fork is
291
- * partition healing's job (docs/transactions.md), not the retry loop's.
292
- *
293
- * Extends {@link SyncRetryExhaustedError} so existing callers that catch the base class keep
294
- * working; catch this subclass to distinguish "my revision view is wrong" from "I lost a race
295
- * too many times". */
296
- export class SyncRevisionStalledError extends SyncRetryExhaustedError {
297
- /** Required here, unlike on the base class — it is the evidence the stall is based on. */
298
- declare readonly staleAt: { blockId: BlockId; rev: number };
299
-
300
- constructor(
301
- collectionId: CollectionId,
302
- attempts: number,
303
- staleAt: { blockId: BlockId; rev: number },
304
- /** The revision the next attempt would have requested. */
305
- readonly requestedRev: number,
306
- /** The revision this client believes is current. `undefined` for a collection that has
307
- * committed nothing. */
308
- readonly heldRev: number | undefined,
309
- lastReason?: string,
310
- ) {
311
- super(collectionId, attempts, lastReason, staleAt);
312
- // The base class's "exhausted N retries" wording is deliberately NOT reused: it reads as
313
- // ordinary contention, which is exactly the misdiagnosis this class exists to prevent.
314
- this.message = `sync for collection ${collectionId} stopped after ${attempts} attempts: `
315
- + `this client holds rev ${heldRev ?? 'none'} and would request rev ${requestedRev}, `
316
- + `but block ${staleAt.blockId} is confirmed committed at rev ${staleAt.rev} and `
317
- + `refreshing did not close the gap`
318
- + (lastReason ? `: ${lastReason}` : '');
319
- this.name = 'SyncRevisionStalledError';
320
- }
321
- }
322
-
323
- /** Why a half-landed write could not be finished (see {@link TornActionError}). This is the CAUSE
324
- * of giving up; whether the write is then definitely not saved is a separate fact, carried by
325
- * {@link TornActionError.final} — every reason can arrive with either value.
326
- *
327
- * - `rival-holds-revision` — finishing was refused because a DIFFERENT action holds a revision past
328
- * the one the write needed on some block. That alone does NOT mean the write is lost: a later
329
- * revision is often built ON the write (a rival that read it and added to it), and a write every
330
- * block of which was built upon is reported SAVED, never by this error. It is raised only once
331
- * the blocks' own history was asked (`ITransactor.getLineage`) and did not vouch for every block.
332
- * - `completion-refused` — finishing was attempted and refused for a cause that can clear on its
333
- * own (another write in flight on the block, the revision not yet held by a majority). The write
334
- * paths retry this inside their own budget, so seeing it means that budget ran out.
335
- * - `transforms-not-held` — the write's own log entry was found with blocks still missing, but this
336
- * collection no longer holds the transforms that would finish them. */
337
- export type TornActionReason = 'rival-holds-revision' | 'completion-refused' | 'transforms-not-held';
338
-
339
- /** Thrown when a write HALF-LANDED and was not finished: its log entry is stored, but at least one
340
- * of the other blocks that entry names is not known to hold the write.
341
- *
342
- * A write's log tail is committed before the rest of its blocks, so a write can be refused AFTER the
343
- * tail was stored (see `NetworkTransactor.commit`). The writer's retry then finds its own log entry.
344
- * That entry proves only that the tail landed; the write is saved only once EVERY block the entry
345
- * names holds the write — at the write's own revision, or at a later revision that was built from
346
- * it — so the retry finishes the remaining blocks at the same action id and revision (see
347
- * `Collection.completeOwnEntry`). This error is what it raises when it could not — {@link reason}
348
- * says why, and {@link final} says what that leaves the caller able to do.
349
- *
350
- * **{@link final} is the field to act on.** An application's only safe reaction to a failed write
351
- * is to submit it again, and that is only safe when the first one can never show up:
352
- *
353
- * - `final: true` — the write is NOT saved and never will be. Every block it still needed answered
354
- * for its whole cohort that it does not hold the write (its history passed the write's revision
355
- * without it, or it never reached that revision), and the write's pending records were confirmed
356
- * cancelled first, so nothing is left that could land it. Submitting the same change again stores
357
- * it once.
358
- * - `final: false` — that could NOT be established. The write may already be saved, or may still
359
- * land (a block's cohort did not all answer, members contradicted each other, fewer than a
360
- * majority hold it, or the cancel could not be confirmed). Submitting again can store the change
361
- * twice; read the data back first.
362
- *
363
- * It is deliberately not a {@link SyncRetryExhaustedError}: that error says the write never landed,
364
- * whereas here the log already holds an entry for it. Finishing needs the original action id and
365
- * the transforms it sent, and both are gone once this escapes. Re-driving under a NEW revision
366
- * records the same actions in the log twice, so nothing here does that on the caller's behalf. The
367
- * staged actions are left in place on the collection, so at this level "submit again" is calling
368
- * `sync()` again, and abandoning the write is the caller's to do (`Collection.restorePending`).
369
- * `Tree.replace` and `Diary.append` do abandon it — they own both the staging and the flush, and a
370
- * failed call that left its action staged would ride along, unasked, with the caller's next write.
371
- *
372
- * Raised out of {@link ICollection.sync} / {@link ICollection.updateAndSync}, and out of the
373
- * refresh `TransactionCoordinator.commit` runs between attempts (`Collection.refreshInFlight`).
374
- * The coordinator passes it on bare only when no other participant of the commit is saved; when
375
- * one is, it arrives as the `reason` of a `CoordinatorPartialCommitError` that names the saved
376
- * participants. */
377
- export class TornActionError extends Error {
378
- constructor(
379
- readonly collectionId: CollectionId,
380
- /** The half-landed write's action id. */
381
- readonly actionId: string,
382
- /** The revision its log entry landed at — the revision every block it names had to take. */
383
- readonly rev: number,
384
- /** The blocks the entry names that are not known to hold the write. */
385
- readonly blockIds: BlockId[],
386
- /** Why finishing failed — see {@link TornActionReason}. Says nothing about {@link final}. */
387
- readonly reason: TornActionReason,
388
- /** Whether the write is definitely not saved and can never land — see the class comment.
389
- * `false` means "not established", never "it landed". */
390
- readonly final: boolean,
391
- /** The refusal in the responder's own words, for a log line. Never branch on it. */
392
- readonly detail: string,
393
- /** The confirmed revision a responder reported holding under ANOTHER action, when the refusal
394
- * carried one (see `StaleFailure.staleAt`). */
395
- readonly staleAt?: { blockId: BlockId; rev: number },
396
- ) {
397
- super(`collection ${collectionId}: action ${actionId} is torn at rev ${rev} — its log entry is stored `
398
- + `but block(s) ${blockIds.join(', ') || '(unknown)'} are not known to hold it, and the write cannot be `
399
- + `finished: ${detail}`
400
- + (staleAt ? ` (block ${staleAt.blockId} is at rev ${staleAt.rev})` : '')
401
- + (final
402
- ? ' — the write is not saved and cannot land; it is safe to submit again'
403
- : ' — whether the write is saved could not be established; it may be saved already or land later'));
404
- this.name = 'TornActionError';
405
- }
406
- }
407
-
408
- /** Thrown when a collection that already holds a committed revision reads its own header
409
- * block as authoritatively absent.
410
- *
411
- * The two facts contradict each other: this client has proof that something was committed
412
- * under this id (it holds the revision it committed at, or the one it read off the log tail),
413
- * and storage has just answered that nothing ever was. Exactly one of them is wrong, so this
414
- * is a fault rather than an absence — the same reasoning `Collection.attachToLog` applies to a
415
- * header that probes fine but whose log will not open.
416
- *
417
- * Deliberately NOT a `StaleFailure`: {@link ICollection.sync}'s retry loop only absorbs
418
- * returned stale failures, so throwing this aborts the sync immediately with a named
419
- * diagnosis instead of letting it spin the full retry budget re-requesting a revision it
420
- * has silently forgotten.
421
- *
422
- * NOTE: durable invalidation restores reverted content to its as-if-absent state, so once the
423
- * cascade runs end-to-end (docs/right-is-right.md § Durable Invalidation), reverting the commit
424
- * that CREATED a collection would make its header legitimately absent for a client still holding
425
- * that revision — a reversal, not a contradiction, which this message would misdiagnose.
426
- * Aborting is still the right action there; if it ever fires for that reason, distinguish the
427
- * two by checking the log for an invalidation of the held revision before wording the error. */
428
- export class CollectionHeaderVanishedError extends Error {
429
- constructor(
430
- readonly collectionId: CollectionId,
431
- /** The committed revision this collection held when the header read came back absent. */
432
- readonly heldRev: number,
433
- ) {
434
- super(`collection ${collectionId} holds committed revision ${heldRev}, but its header block `
435
- + `read as absent — storage reported that nothing was ever committed under this id`);
436
- this.name = 'CollectionHeaderVanishedError';
437
- }
438
- }
439
-
440
- export interface ICollection<TAction> {
441
- readonly id: CollectionId;
442
- act(...actions: Action<TAction>[]): Promise<void>;
443
- update(): Promise<void>;
444
- /** Push staged changes. Resolves to who holds what was committed, or `undefined` when NOTHING WAS
445
- * WRITTEN — nothing was staged, so there was no pend and no commit and there is no durability to
446
- * report. A write that never landed throws ({@link SyncRetryExhaustedError}) rather than returning
447
- * a class. Decide "is this saved" with `isFullyDurable`, never by comparing `quorum`. */
448
- sync(options?: SyncOptions): Promise<WriteDurability | undefined>;
449
- /** Refresh, then {@link sync}. Same return contract. */
450
- updateAndSync(options?: SyncOptions): Promise<WriteDurability | undefined>;
451
- selectLog(forward?: boolean): AsyncIterableIterator<Action<TAction>>;
452
- }
453
-
454
- export type CreateCollectionAction = Action<void> & {
455
- type: "create";
456
- };
1
+ import type { IBlock, BlockId, Action, ActionId, Transforms, WriteDurability } from "../index.js";
2
+ import type { IChainHeader } from "../chain/chain-nodes.js";
3
+ import type { RandFn } from "../utility/backoff.js";
4
+ import type { EntryId } from "./segments.js";
5
+ import type { AlreadyAppliedTally } from "./action.js";
6
+ import type { BlockBaseRevs, BlockContentDigests } from "../network/struct.js";
7
+ import type { Hlc } from "../hlc/hlc.js";
8
+ import type { Lane } from "../lane/lane.js";
9
+
10
+ export type CollectionId = BlockId;
11
+
12
+ /**
13
+ * A handler's statement that an action cannot be applied over the committed state it is being
14
+ * replayed against — a uniqueness or lost-update check failed. Not a transport failure and never
15
+ * retryable: the action's staged writes are discarded (the handler runs inside an Atomic), and
16
+ * nothing downgrades it to a stale failure. `TreeGuardRefusedError` in
17
+ * `packages/db-core/src/collections/tree/struct.ts` is the tree's subclass, and carries the
18
+ * contract every refusal obeys.
19
+ *
20
+ * Lives here rather than beside the tree so the collection can recognise a refusal without
21
+ * importing the tree module (which imports the collection). Segment-aware replay
22
+ * (`Collection.replayActions`) treats a throw of this class from a SEALED segment as that
23
+ * segment's refusal and keeps going; from the open segment it propagates as it always has.
24
+ */
25
+ export class ActionRefusedError extends Error {
26
+ constructor(
27
+ /** The collection whose handler refused the action. */
28
+ readonly collectionId: CollectionId,
29
+ message: string,
30
+ ) {
31
+ super(message);
32
+ this.name = 'ActionRefusedError';
33
+ }
34
+ }
35
+
36
+ /** Why a sealed segment stood in the way of a commit (see {@link SealedSegmentsError}):
37
+ * - `whole-collection` — a whole-collection commit was asked for while a segment is sealed.
38
+ * - `not-head` — `commitHead` named a segment that is not the oldest sealed one.
39
+ * - `refused` — `commitHead` named a segment a replay has refused; the queue drops it instead.
40
+ * - `in-flight` — a head commit is on the network for the named segment, so neither a second
41
+ * `commitHead` nor a `dropSealed` of it can proceed. */
42
+ export type SealedSegmentsReason = 'whole-collection' | 'not-head' | 'refused' | 'in-flight';
43
+
44
+ /**
45
+ * Thrown by the whole-collection commit paths — {@link ICollection.sync},
46
+ * {@link ICollection.updateAndSync}, `Collection.actAndSync` and `Collection.getPendingActions`
47
+ * (the coordinator's append) — while the collection holds sealed segments. Those paths commit
48
+ * everything staged as ONE log entry under one action id; over sealed segments that would merge
49
+ * several queue entries into one, which the queue's identity rules forbid
50
+ * (docs/offline-sync.md §Identity across attempts). A sealed segment is committed on its own,
51
+ * through `Collection.commitHead`, whose own preconditions throw this class too, with a
52
+ * {@link reason} other than `whole-collection` (see {@link SealedSegmentsReason}).
53
+ *
54
+ * Nothing is unstaged or changed when this is thrown: every segment, sealed and open, is exactly
55
+ * as it was.
56
+ */
57
+ export class SealedSegmentsError extends Error {
58
+ constructor(
59
+ readonly collectionId: CollectionId,
60
+ /** The sealed segments' entry ids, in order. */
61
+ readonly sealedEntries: EntryId[],
62
+ readonly reason: SealedSegmentsReason = 'whole-collection',
63
+ /** The entry a `commitHead` or `dropSealed` named, for every reason but `whole-collection`. */
64
+ readonly entryId?: EntryId,
65
+ ) {
66
+ super(sealedSegmentsMessage(collectionId, sealedEntries, reason, entryId));
67
+ this.name = 'SealedSegmentsError';
68
+ }
69
+ }
70
+
71
+ function sealedSegmentsMessage(collectionId: CollectionId, sealedEntries: EntryId[], reason: SealedSegmentsReason, entryId: EntryId | undefined): string {
72
+ const listed = sealedEntries.length === 0 ? 'nothing' : sealedEntries.join(', ');
73
+ switch (reason) {
74
+ case 'whole-collection':
75
+ return `collection ${collectionId} holds sealed segment(s) ${listed}; `
76
+ + `a whole-collection commit would merge them into one log entry — commit the head segment instead`;
77
+ case 'not-head':
78
+ return `collection ${collectionId}: entry ${entryId} is not the head sealed segment (sealed: ${listed}); `
79
+ + `only the oldest sealed segment can be committed`;
80
+ case 'refused':
81
+ return `collection ${collectionId}: entry ${entryId} carries a recorded refusal; `
82
+ + `a refused segment is dropped, never committed`;
83
+ case 'in-flight':
84
+ return `collection ${collectionId}: a head commit of entry ${entryId} is in flight on this instance`;
85
+ }
86
+ }
87
+
88
+ /** Exactly what one write attempt sent to the transactor — enough to send the same thing again.
89
+ * Retained by `Collection.retainInFlightAttempt` so that a refresh which then finds this attempt's
90
+ * own log entry can land the blocks the attempt left behind, at the same action id and revision
91
+ * (see `Collection.completeOwnEntry`).
92
+ *
93
+ * Also the shape a caller RECORDS before an attempt is sent and hands back on a later cycle
94
+ * ({@link HeadCommitOptions.recordAttempt} and {@link HeadCommitOptions.resume};
95
+ * docs/offline-sync.md §Identity across attempts), so it must stay plain data — ids, numbers and the
96
+ * transforms as the wire carries them, nothing with object identity and no functions: the
97
+ * offline-sync journal serialises it as JSON. */
98
+ export type InFlightAttempt = {
99
+ /** The action id the attempt was sent under — the one every attempt of the write reuses, and
100
+ * the one a cycle that resumes from this record must run under. */
101
+ actionId: ActionId;
102
+ /** The revision the attempt's log entry was stamped with, and pended and committed at. */
103
+ rev: number;
104
+ /** Every transform the attempt pended — the log blocks included. The caller hands over a copy
105
+ * it will not mutate; the collection keeps it as given. */
106
+ transforms: Transforms;
107
+ /** The attempt's log tail block, committed first. */
108
+ tailId: BlockId;
109
+ /** The per-block content declarations the attempt's commit carried, if any. */
110
+ blockDigests?: BlockContentDigests;
111
+ /** The per-block bases the attempt's pend carried, if any (see `PendRequest.baseRevs`). Kept
112
+ * with the transforms because they describe them: a re-send of these operations must name the
113
+ * same bases they were computed against. */
114
+ baseRevs?: BlockBaseRevs;
115
+ };
116
+
117
+ /** What `Collection.commitHead` commits the head segment under, beside the retry bounds of
118
+ * {@link SyncOptions}. The three identity fields are the queue's (docs/offline-sync.md §Identity
119
+ * across attempts): the collection mints none of them. */
120
+ export type HeadCommitOptions = SyncOptions & {
121
+ /** The action id the attempt cycle runs under. The queue mints it, and re-supplies the SAME id
122
+ * when it re-drives an entry whose earlier attempt may have landed, so the refresh that opens the
123
+ * cycle recognises that attempt's log entry as the write's own and finishes or consumes it
124
+ * instead of committing a second copy. */
125
+ actionId: ActionId;
126
+ /** The entry's local commit time, stamped on the log entry in place of the time
127
+ * `Collection.syncInternal` mints for a sync. Fixed per write, so every attempt appends the same
128
+ * entry (see "A write's log append is a fixed function of the write and the revision it is
129
+ * requesting" in docs/internals.md). The second per-write value, {@link hlc}, follows the same
130
+ * rule. */
131
+ timestamp: number;
132
+ /** The entry's local commit time as an HLC (`LogEntry.hlc`): minted by the queue at enqueue from
133
+ * the collections' transactor clock, journaled with the entry, and re-supplied on every drive of
134
+ * it, first or re-drive, so every attempt appends the same entry. */
135
+ hlc: Hlc;
136
+ /** The entry's lane (`ActionEntry.lane`): fixed at enqueue — the caller's classification, or the
137
+ * stricter of the sealed collections' own declarations — journaled with the entry and re-supplied
138
+ * on every drive, so every attempt appends the same entry. Required here, unlike the
139
+ * {@link SyncOptions.lane} it narrows: a head commit never classifies for itself. */
140
+ lane: Lane;
141
+ /** The write-ahead hook: called with each attempt exactly as it is about to be sent — after it is
142
+ * built and BEFORE the collection latch is released for the network — and awaited under that
143
+ * latch. It is where the queue records the attempt's identity before sending it
144
+ * (docs/offline-sync.md §Identity across attempts) and, later, where the journal writes it. A
145
+ * throw aborts the cycle before anything is sent: it escapes `commitHead` unchanged, the handle
146
+ * closes, and every segment is exactly as it was. */
147
+ recordAttempt?: (attempt: InFlightAttempt) => Promise<void>;
148
+ /** The attempt an earlier cycle under the SAME `actionId` handed to `recordAttempt` and did not
149
+ * resolve — it must carry this `actionId`, and `openHeadCommit` throws before touching anything
150
+ * when it does not. Seeded as the retained attempt right after the action is marked in flight,
151
+ * so the cycle's opening refresh, finding that attempt's log entry with blocks missing, finishes
152
+ * it from these transforms (`Collection.completeOwnEntry`) instead of refusing it as torn with
153
+ * `transforms-not-held`. Without it a re-drive can recognise only an attempt that landed whole.
154
+ * The revision check still applies: an attempt recorded at a revision other than the entry's is
155
+ * refused as before. And when that refresh finds nothing new, this attempt is what the cycle
156
+ * re-sends, verbatim, while the next attempt would request its revision (`resumedAttempt`), since
157
+ * it may have landed on machines the refresh did not hear from. */
158
+ resume?: InFlightAttempt;
159
+ /** Called once, with what the head segment's actions accepted as already applied
160
+ * ({@link AlreadyAppliedTally}, as recorded on the segment by its last staging over the committed
161
+ * state), at the moment the segment is made durable and dropped: when the committed attempt is
162
+ * folded (`HeadCommitHandle.fold`), or when the cycle's refresh finds the entry's own log entry and
163
+ * consumes the head (`Collection.consumeHead`) — so a re-drive that finds its earlier attempt landed
164
+ * reports it too. Runs synchronously under the collection latch, like `onSealedRefused`, so it must
165
+ * not call a latched method of the collection; the queue's closure only records into a map. A throw
166
+ * out of it is logged, never raised: the commit is already durable. A hook rather than a widened
167
+ * return type because the partial-commit path reports the committed half through
168
+ * `CoordinatorPartialCommitError` and the refresh-consumed path through `RefreshReport`; one hook
169
+ * reaches all three. */
170
+ onCommittedHead?: (applied: AlreadyAppliedTally) => void;
171
+ };
172
+
173
+ export type CollectionHeaderBlock = IBlock & Partial<IChainHeader>;
174
+
175
+ /** A collection's committed tail: the log tail block its header names, and that block's latest
176
+ * committed revision, which is the collection's (every commit touches the log tail). */
177
+ export type CommittedTail = { tailId: BlockId; rev: number };
178
+
179
+ /** One collection a batched committed-tail read names (`Collection.readCommittedTails`). */
180
+ export type CommittedTailQuery = {
181
+ readonly id: CollectionId;
182
+ /** The tail block the caller's previous read found. While the header still names it, the read
183
+ * needs no second request for this collection. */
184
+ readonly knownTailId?: BlockId;
185
+ };
186
+
187
+ /** How a batched committed-tail read (`Collection.readCommittedTails`) asks. */
188
+ export type CommittedTailReadOptions = {
189
+ /** Ask every answering repo not to start the background read-repair consult its lazy window would
190
+ * run behind the read (`BlockGets.skipWindowConsult`) — for a poll that only wants what is held. */
191
+ readonly skipWindowConsult?: boolean;
192
+ };
193
+
194
+ /** One collection's answer to a batched committed-tail read: its tail (`undefined` when it has
195
+ * never committed), or why reading it failed — what the single-collection read would have thrown. */
196
+ export type CommittedTailAnswer =
197
+ | { readonly tail: CommittedTail | undefined }
198
+ | { readonly error: unknown };
199
+
200
+ /** Bounds the retry loop inside {@link ICollection.sync} / {@link ICollection.updateAndSync}
201
+ * so a transactor that keeps rejecting the sync can no longer spin the collection latch forever.
202
+ * All fields are optional; unset fields fall back to conservative defaults. */
203
+ export interface SyncOptions {
204
+ /** Max consecutive stale-failure retries that make no progress before giving up.
205
+ * The counter resets to 0 on every successful commit, so a legitimate large multi-batch
206
+ * sync (which iterates many times making forward progress) is never falsely tripped.
207
+ * Default 10. */
208
+ maxAttempts?: number;
209
+ /** Optional wall-clock deadline in ms measured from the start of the sync call. Independent
210
+ * of the attempt count — a progress-agnostic ceiling. Unset means no deadline. */
211
+ deadlineMs?: number;
212
+ /** Base backoff delay in ms applied before the first retry; subsequent retries grow the delay
213
+ * exponentially up to {@link maxBackoffMs}. Default 100. Not applied once `SlotHoldAfterLosses` of the
214
+ * write's refused attempts carried a confirmed committed revision (`StaleFailure.staleAt`) and the
215
+ * latest refusal is one of them: a member then holds the next slot for this write,
216
+ * and the retry follows at once rather than spending the hold asleep. */
217
+ baseBackoffMs?: number;
218
+ /** Upper bound on any single backoff sleep, in ms. Default 5000. Like {@link baseBackoffMs}, not
219
+ * applied to a retry that follows at once because a member holds the slot for this write. */
220
+ maxBackoffMs?: number;
221
+ /** Optional abort signal. Checked at the top of each loop iteration and raced against the
222
+ * backoff sleep, so an aborted sync rejects promptly (with an AbortError) rather than finishing
223
+ * the current sleep. */
224
+ signal?: AbortSignal;
225
+ /** Advanced/testing hook: source of uniform [0,1) randomness for the backoff jitter. Defaults to
226
+ * the package CSPRNG; inject a deterministic sequence to assert exact retry delays. */
227
+ rand?: RandFn;
228
+ /** Consecutive refreshes that move this collection's revision NOWHERE while a responder has
229
+ * CONFIRMED a revision at or above the one the next attempt would request, before sync gives up
230
+ * with {@link SyncRevisionStalledError}. Such a retry provably re-sends the identical, already
231
+ * lost request, so the wait buys nothing. Two absorbs one transiently-lagging read; set it to
232
+ * {@link maxAttempts} or higher to restore the pre-existing behaviour of burning the whole
233
+ * budget. Default 2.
234
+ *
235
+ * Neither shape of progress trips this. Ordinary contention: the rival's commit is what the
236
+ * refresh adopts, so the next request lands above the confirmed revision. A collection still
237
+ * catching up: the refresh moves the revision forward without yet clearing the confirmed
238
+ * number, so the next request differs from the one that just failed. Either resets the counter.
239
+ * {@link deadlineMs} is still checked first, so a sync that is both past its deadline and
240
+ * stalled reports the deadline (as {@link SyncRetryExhaustedError}), not the stall.
241
+ *
242
+ * `TransactionCoordinator.commit` and `commitEntry` read it too, applying the same rule to each
243
+ * participant on its own counter (`RevisionStallWatch`) and stopping with
244
+ * `CoordinatorRevisionStalledError` on the first participant to reach it; the offline queue
245
+ * forwards it to `commitEntry` (`OfflineQueueOptions.submit`). */
246
+ maxStalledAttempts?: number;
247
+ /** Refuse to let this write be committed by a lone node — a coordinator whose cohort for the
248
+ * write is only itself — while that node knows of members of the cohort it could not reach, is
249
+ * still waiting to hear from a peer it was configured to join through, or could not route the
250
+ * write at all. A node that is genuinely alone (no absent member known, nothing awaited, routed to
251
+ * itself) still commits. The refusal is a promise shortfall (`PromiseShortfallError`, with
252
+ * `soloRefused` naming the reason), so the write stops and is classified `cohort-unreachable`.
253
+ * Rides on every send of the write's attempt cycle as `PendRequest.refuseSolo` and
254
+ * `CommitRequest.refuseSolo`. Default off: only the offline queue sets it (docs/offline-sync.md
255
+ * §When to submit: the reachability gate). A coordinator on a build that predates the field
256
+ * ignores it and commits alone as before. */
257
+ refuseSoloCommit?: boolean;
258
+ /** The caller's classification of the write: the lane (`Lane` in `packages/db-core/src/lane/lane.ts`)
259
+ * its log entry, its pend and its commit carry. Taken at face value — the caller knows more than
260
+ * the collection does (the SQL bridge computes it from the statements), and the member-side check
261
+ * is a later ticket. Absent, the collection's own merge declaration decides
262
+ * (`Collection.laneOf`), which is `serializable` for a collection that declares nothing. Read by
263
+ * `Collection.sync`, `updateAndSync` and `actAndSync`, and by `TransactionSession.commit`, which
264
+ * folds it into the transaction it builds; `TransactionCoordinator.commit` and `commitEntry` take
265
+ * the lane off the transaction and the entry, which carry it already, and do not read this. */
266
+ lane?: Lane;
267
+ }
268
+
269
+ /** What a write's attempt cycle carries besides its identity, recorded beside the in-flight mark
270
+ * (`Collection.beginInFlightAction`) so that every send of the cycle carries it: each attempt, and
271
+ * the re-send a refresh makes to finish a torn one (`Collection.completeOwnEntry`). */
272
+ export type InFlightCycle = {
273
+ /** The write's lane (`WriteIdentity.lane`), on every pend and commit of the cycle — the re-send
274
+ * of a torn attempt included, which is why it rides here and not only on the identity the
275
+ * attempts are built from. */
276
+ readonly lane: Lane;
277
+ /** {@link SyncOptions.refuseSoloCommit}, for this cycle. */
278
+ readonly refuseSolo?: boolean;
279
+ };
280
+
281
+ /** What `Collection.openHeadCommit` opens a head commit with besides its identity: the cycle's
282
+ * {@link InFlightCycle} less its lane, which is the identity's; the attempt an earlier cycle under
283
+ * the same action id recorded and did not resolve ({@link HeadCommitOptions.resume}); and the
284
+ * committed-head hook ({@link HeadCommitOptions.onCommittedHead}). */
285
+ export type OpenHeadCommitOptions = Omit<InFlightCycle, 'lane'> & {
286
+ readonly resume?: InFlightAttempt;
287
+ readonly onCommittedHead?: (applied: AlreadyAppliedTally) => void;
288
+ };
289
+
290
+ /** Thrown by {@link ICollection.sync} / {@link ICollection.updateAndSync} when the retry budget
291
+ * (attempt count or deadline) is exhausted while the transactor keeps returning stale failures.
292
+ * Catchable so callers can surface a clear "gave up syncing" condition instead of hanging.
293
+ *
294
+ * It says the write was NOT SAVED; it does not prove nothing was stored. A write's log tail is
295
+ * committed before its other blocks, and the attempt that spent the budget is not followed by a
296
+ * refresh, so that attempt's log entry may be standing in the log with none of its data — the state
297
+ * {@link TornActionError} names when a refresh does get to see it. */
298
+ export class SyncRetryExhaustedError extends Error {
299
+ constructor(
300
+ readonly collectionId: CollectionId,
301
+ readonly attempts: number,
302
+ readonly lastReason?: string,
303
+ /** The last confirmed revision a responder reported holding, if any responder reported one
304
+ * (see `StaleFailure.staleAt`). Absent whenever no rejection carried a confirmed number —
305
+ * which is normal, not a signal that the failure was something other than a lost race. */
306
+ readonly staleAt?: { blockId: BlockId; rev: number },
307
+ ) {
308
+ super(`sync for collection ${collectionId} exhausted ${attempts} retries` +
309
+ (lastReason ? `: ${lastReason}` : '') +
310
+ (staleAt ? `, last seen block ${staleAt.blockId} at rev ${staleAt.rev}` : ''));
311
+ this.name = 'SyncRetryExhaustedError';
312
+ }
313
+ }
314
+
315
+ /** Thrown by {@link ICollection.sync} / {@link ICollection.updateAndSync} when refreshing
316
+ * repeatedly moved this collection nowhere at all while a responder confirmed a revision at or
317
+ * above the one being requested — the client's view of the current revision disagrees with the
318
+ * cluster's, and retrying would re-send the identical taken number.
319
+ *
320
+ * The distinction matters because the two failures need different responses. Plain exhaustion
321
+ * means "I lost a race too many times", and waiting longer or retrying later can succeed. This
322
+ * one means the next attempt is provably identical to the one that just failed, so the remaining
323
+ * budget buys nothing — the caller's view of the collection has to be repaired first.
324
+ *
325
+ * Sync deliberately does NOT adopt the responder's revision to get past this. `staleAt` is a bare
326
+ * number, not content: submitting this client's staged transforms at a revision built on a
327
+ * history it never read would overwrite that history silently. Reconciling a genuine fork is
328
+ * partition healing's job (docs/transactions.md), not the retry loop's.
329
+ *
330
+ * Extends {@link SyncRetryExhaustedError} so existing callers that catch the base class keep
331
+ * working; catch this subclass to distinguish "my revision view is wrong" from "I lost a race
332
+ * too many times". */
333
+ export class SyncRevisionStalledError extends SyncRetryExhaustedError {
334
+ /** Required here, unlike on the base class — it is the evidence the stall is based on. */
335
+ declare readonly staleAt: { blockId: BlockId; rev: number };
336
+
337
+ constructor(
338
+ collectionId: CollectionId,
339
+ attempts: number,
340
+ staleAt: { blockId: BlockId; rev: number },
341
+ /** The revision the next attempt would have requested. */
342
+ readonly requestedRev: number,
343
+ /** The revision this client believes is current. `undefined` for a collection that has
344
+ * committed nothing. */
345
+ readonly heldRev: number | undefined,
346
+ lastReason?: string,
347
+ ) {
348
+ super(collectionId, attempts, lastReason, staleAt);
349
+ // The base class's "exhausted N retries" wording is deliberately NOT reused: it reads as
350
+ // ordinary contention, which is exactly the misdiagnosis this class exists to prevent.
351
+ this.message = `sync for collection ${collectionId} stopped after ${attempts} attempts: `
352
+ + `this client holds rev ${heldRev ?? 'none'} and would request rev ${requestedRev}, `
353
+ + `but block ${staleAt.blockId} is confirmed committed at rev ${staleAt.rev} and `
354
+ + `refreshing did not close the gap`
355
+ + (lastReason ? `: ${lastReason}` : '');
356
+ this.name = 'SyncRevisionStalledError';
357
+ }
358
+ }
359
+
360
+ /** Why a half-landed write could not be finished (see {@link TornActionError}). This is the CAUSE
361
+ * of giving up; whether the write is then definitely not saved is a separate fact, carried by
362
+ * {@link TornActionError.final} — every reason can arrive with either value.
363
+ *
364
+ * - `rival-holds-revision` — finishing was refused because a DIFFERENT action holds a revision past
365
+ * the one the write needed on some block. That alone does NOT mean the write is lost: a later
366
+ * revision is often built ON the write (a rival that read it and added to it), and a write every
367
+ * block of which was built upon is reported SAVED, never by this error. It is raised only once
368
+ * the blocks' own history was asked (`ITransactor.getLineage`) and did not vouch for every block.
369
+ * - `completion-refused` — finishing was attempted and refused for a cause that can clear on its
370
+ * own (another write in flight on the block, the revision not yet held by a majority). The write
371
+ * paths retry this inside their own budget, so seeing it means that budget ran out.
372
+ * - `transforms-not-held` — the write's own log entry was found with blocks still missing, but this
373
+ * collection no longer holds the transforms that would finish them. */
374
+ export type TornActionReason = 'rival-holds-revision' | 'completion-refused' | 'transforms-not-held';
375
+
376
+ /** Thrown when a write HALF-LANDED and was not finished: its log entry is stored, but at least one
377
+ * of the other blocks that entry names is not known to hold the write.
378
+ *
379
+ * A write's log tail is committed before the rest of its blocks, so a write can be refused AFTER the
380
+ * tail was stored (see `NetworkTransactor.commit`). The writer's retry then finds its own log entry.
381
+ * That entry proves only that the tail landed; the write is saved only once EVERY block the entry
382
+ * names holds the write — at the write's own revision, or at a later revision that was built from
383
+ * it — so the retry finishes the remaining blocks at the same action id and revision (see
384
+ * `Collection.completeOwnEntry`). This error is what it raises when it could not — {@link reason}
385
+ * says why, and {@link final} says what that leaves the caller able to do.
386
+ *
387
+ * **{@link final} is the field to act on.** An application's only safe reaction to a failed write
388
+ * is to submit it again, and that is only safe when the first one can never show up:
389
+ *
390
+ * - `final: true` — the write is NOT saved and never will be. Every block it still needed answered
391
+ * for its whole cohort that it does not hold the write (its history passed the write's revision
392
+ * without it, or it never reached that revision), and the write's pending records were confirmed
393
+ * cancelled first, so nothing is left that could land it. Submitting the same change again stores
394
+ * it once.
395
+ * - `final: false` — that could NOT be established. The write may already be saved, or may still
396
+ * land (a block's cohort did not all answer, members contradicted each other, fewer than a
397
+ * majority hold it, or the cancel could not be confirmed). Submitting again can store the change
398
+ * twice; read the data back first.
399
+ *
400
+ * It is deliberately not a {@link SyncRetryExhaustedError}: that error says the write never landed,
401
+ * whereas here the log already holds an entry for it. Finishing needs the original action id and
402
+ * the transforms it sent, and both are gone once this escapes. Re-driving under a NEW revision
403
+ * records the same actions in the log twice, so nothing here does that on the caller's behalf. The
404
+ * staged actions are left in place on the collection, so at this level "submit again" is calling
405
+ * `sync()` again, and abandoning the write is the caller's to do (`Collection.restorePending`).
406
+ * `Tree.replace` and `Diary.append` do abandon it — they own both the staging and the flush, and a
407
+ * failed call that left its action staged would ride along, unasked, with the caller's next write.
408
+ *
409
+ * Raised out of {@link ICollection.sync} / {@link ICollection.updateAndSync}, and out of the
410
+ * refresh `TransactionCoordinator.commit` runs between attempts (`Collection.refreshInFlight`).
411
+ * The coordinator passes it on bare only when no other participant of the commit is saved; when
412
+ * one is, it arrives as the `reason` of a `CoordinatorPartialCommitError` that names the saved
413
+ * participants. */
414
+ export class TornActionError extends Error {
415
+ constructor(
416
+ readonly collectionId: CollectionId,
417
+ /** The half-landed write's action id. */
418
+ readonly actionId: string,
419
+ /** The revision its log entry landed at — the revision every block it names had to take. */
420
+ readonly rev: number,
421
+ /** The blocks the entry names that are not known to hold the write. */
422
+ readonly blockIds: BlockId[],
423
+ /** Why finishing failed — see {@link TornActionReason}. Says nothing about {@link final}. */
424
+ readonly reason: TornActionReason,
425
+ /** Whether the write is definitely not saved and can never land — see the class comment.
426
+ * `false` means "not established", never "it landed". */
427
+ readonly final: boolean,
428
+ /** The refusal in the responder's own words, for a log line. Never branch on it. */
429
+ readonly detail: string,
430
+ /** The confirmed revision a responder reported holding under ANOTHER action, when the refusal
431
+ * carried one (see `StaleFailure.staleAt`). */
432
+ readonly staleAt?: { blockId: BlockId; rev: number },
433
+ ) {
434
+ super(`collection ${collectionId}: action ${actionId} is torn at rev ${rev} — its log entry is stored `
435
+ + `but block(s) ${blockIds.join(', ') || '(unknown)'} are not known to hold it, and the write cannot be `
436
+ + `finished: ${detail}`
437
+ + (staleAt ? ` (block ${staleAt.blockId} is at rev ${staleAt.rev})` : '')
438
+ + (final
439
+ ? ' — the write is not saved and cannot land; it is safe to submit again'
440
+ : ' — whether the write is saved could not be established; it may be saved already or land later'));
441
+ this.name = 'TornActionError';
442
+ }
443
+ }
444
+
445
+ /** Thrown when a collection that already holds a committed revision reads its own header
446
+ * block as authoritatively absent.
447
+ *
448
+ * The two facts contradict each other: this client has proof that something was committed
449
+ * under this id (it holds the revision it committed at, or the one it read off the log tail),
450
+ * and storage has just answered that nothing ever was. Exactly one of them is wrong, so this
451
+ * is a fault rather than an absence — the same reasoning `Collection.attachToLog` applies to a
452
+ * header that probes fine but whose log will not open.
453
+ *
454
+ * Deliberately NOT a `StaleFailure`: {@link ICollection.sync}'s retry loop only absorbs
455
+ * returned stale failures, so throwing this aborts the sync immediately with a named
456
+ * diagnosis instead of letting it spin the full retry budget re-requesting a revision it
457
+ * has silently forgotten.
458
+ *
459
+ * NOTE: durable invalidation restores reverted content to its as-if-absent state, so once the
460
+ * cascade runs end-to-end (docs/right-is-right.md § Durable Invalidation), reverting the commit
461
+ * that CREATED a collection would make its header legitimately absent for a client still holding
462
+ * that revision — a reversal, not a contradiction, which this message would misdiagnose.
463
+ * Aborting is still the right action there; if it ever fires for that reason, distinguish the
464
+ * two by checking the log for an invalidation of the held revision before wording the error. */
465
+ export class CollectionHeaderVanishedError extends Error {
466
+ constructor(
467
+ readonly collectionId: CollectionId,
468
+ /** The committed revision this collection held when the header read came back absent. */
469
+ readonly heldRev: number,
470
+ ) {
471
+ super(`collection ${collectionId} holds committed revision ${heldRev}, but its header block `
472
+ + `read as absent — storage reported that nothing was ever committed under this id`);
473
+ this.name = 'CollectionHeaderVanishedError';
474
+ }
475
+ }
476
+
477
+ export interface ICollection<TAction> {
478
+ readonly id: CollectionId;
479
+ act(...actions: Action<TAction>[]): Promise<void>;
480
+ update(): Promise<void>;
481
+ /** Push staged changes. Resolves to who holds what was committed, or `undefined` when NOTHING WAS
482
+ * WRITTEN — nothing was staged, so there was no pend and no commit and there is no durability to
483
+ * report. A write that never landed throws ({@link SyncRetryExhaustedError}) rather than returning
484
+ * a class. Decide "is this saved" with `isFullyDurable`, never by comparing `quorum`. */
485
+ sync(options?: SyncOptions): Promise<WriteDurability | undefined>;
486
+ /** Refresh, then {@link sync}. Same return contract. */
487
+ updateAndSync(options?: SyncOptions): Promise<WriteDurability | undefined>;
488
+ selectLog(forward?: boolean): AsyncIterableIterator<Action<TAction>>;
489
+ }
490
+
491
+ export type CreateCollectionAction = Action<void> & {
492
+ type: "create";
493
+ };