@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
@@ -0,0 +1,439 @@
1
+ import { Log } from "../log/log.js";
2
+ import { Tracker } from "../transform/tracker.js";
3
+ import { copyTransforms } from "../transform/helpers.js";
4
+ import { describeTouchedBlocks, baseRevsField } from "../transform/digest.js";
5
+ import { oversizedBlock } from "../network/block-size.js";
6
+ import { mergeDurability } from "../network/durability.js";
7
+ import { highestStaleAt, isExpiryFailure, isRejectedFailure, isShortfallFailure } from "../network/stale-failure.js";
8
+ import { TransactionExpiredError } from "../network/transaction-expired-error.js";
9
+ import { PromiseShortfallError } from "../network/promise-shortfall-error.js";
10
+ import { ValidityRejectedError } from "../network/validity-rejected-error.js";
11
+ import { SyncRetryExhaustedError, SyncRevisionStalledError, TornActionError } from "./struct.js";
12
+ import { clampPriority, SlotHoldAfterLosses } from "../transaction/transaction.js";
13
+ import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
14
+ import { createLogger } from "../logger.js";
15
+ /**
16
+ * The attempt machinery a collection's two write paths share — `Collection.syncAttempts`, which
17
+ * commits the open segment, and `Collection.commitHead`, which commits the head sealed segment
18
+ * (docs/offline-sync.md §One entry, one network transaction). Each path decides WHAT an attempt
19
+ * sends and what to do with a commit; everything about HOW an attempt is built and accounted for
20
+ * is here, so the two cannot drift: the per-attempt tracker and log append
21
+ * ({@link stageAttempt}), the retained attempt a refresh may finish from
22
+ * ({@link retainedAttempt}), and the retry accounting with its stall check and its
23
+ * refresh-until-settled loop ({@link AttemptCycle}). The rules each step enforces are spelled out
24
+ * in docs/internals.md under *Key Invariants* ("The writer's retry finishes its own half-landed
25
+ * action", "A write's log append is a fixed function of the write and the revision it is
26
+ * requesting", "Monotonicity is also what makes a wedged view detectable").
27
+ */
28
+ const log = createLogger('collection');
29
+ /** Default base backoff (and historical fixed delay) between write retries, in ms. */
30
+ const PendingRetryDelayMs = 100;
31
+ /** Default max consecutive no-progress stale-failure retries before a write gives up. */
32
+ const DefaultMaxAttempts = 10;
33
+ /** Default ceiling on a single exponential-backoff sleep, in ms. */
34
+ const DefaultMaxBackoffMs = 5000;
35
+ /** Default consecutive stalled refreshes — ones that moved this collection's revision NOWHERE
36
+ * while a responder CONFIRMED a revision at or above the one being requested — before a write
37
+ * gives up. Two, not one, so a single transiently-lagging read is absorbed.
38
+ *
39
+ * NOTE: two is a judgement call, not a measurement — nothing here counts how often a legitimate
40
+ * loser reads a view that moves nowhere for two consecutive rounds. The check only strikes when the
41
+ * refresh made NO progress at all, so a client merely catching up is already excluded; if a
42
+ * spurious `SyncRevisionStalledError` ever shows up under real contention anyway, raise this. */
43
+ const DefaultMaxStalledAttempts = 2;
44
+ /**
45
+ * The sleep before the refresh that follows a write's `failures`-th consecutive loss.
46
+ *
47
+ * The jittered backoff exists to separate a herd of writers that lost the SAME race, so they do not
48
+ * re-collide on the next tick. A loss to a rival that had already committed (the refusal carried a
49
+ * confirmed `staleAt`) is not a herd, and once this write has taken `SlotHoldAfterLosses` such losses
50
+ * (`confirmedLosses`, counted over the whole write as a member counts its stale refusals of one
51
+ * action) the members that refused it hold the next slot for it — so sleeping only spends that hold.
52
+ * Both sides count the same refusals against the same constant, so the writer stops sleeping on the
53
+ * loss after which a member holds, with nothing said over the wire. A loss the latest refusal did not
54
+ * confirm (`latestConfirmed` false — a race against something still in flight) keeps the jitter.
55
+ *
56
+ * NOTE: against members that do not hold (an earlier release, `slotHoldWindowMs: 0`, or a member the
57
+ * refused pends did not reach) this retries without sleeping and so spends the same attempt budget
58
+ * sooner, at about twice one writer's pend rate (measured in the plan stage of
59
+ * `slot-hold-for-an-aged-writer`). Accepted: the backoff bought that writer nothing either, it only
60
+ * delayed the same give-up.
61
+ */
62
+ function retryBackoffMs(failures, confirmedLosses, latestConfirmed, config, rand) {
63
+ if (latestConfirmed && confirmedLosses >= SlotHoldAfterLosses) {
64
+ return 0;
65
+ }
66
+ return jitteredBackoffMs(failures - 1, config, rand);
67
+ }
68
+ /**
69
+ * Build one attempt: a tracker seeded with a COPY of the target's transforms, so the target is
70
+ * untouched whatever becomes of the attempt, with the log entry for `target.actions` appended at
71
+ * `rev` under `identity`, then the content declarations and the size check.
72
+ *
73
+ * The per-attempt tracker SHARES the target's pin store: it inherits the transforms by copy and
74
+ * never stages the data-block updates itself, so without the shared pins the digest pass could only
75
+ * describe bases still resident in the read cache. NOTE: an attempt that ends in a stale failure is
76
+ * abandoned WITHOUT reset(), so the log tail/header bases its append pinned stay in the shared
77
+ * store until the target tracker's next reset. Bounded and harmless — a few log blocks per
78
+ * attempt, capped by `maxAttempts`, each re-validated against the source generation before any use
79
+ * — but if an attempt ever grows a per-attempt footprint beyond the log blocks, reset the abandoned
80
+ * tracker on the stale-failure branch instead of letting the residue ride to the end of the write.
81
+ *
82
+ * The append is a fixed function of the write and `rev`: the timestamp is the identity's, and any
83
+ * data block the append has to mint takes the id `newDataBlockId` hands out — the caller's
84
+ * `Collection.logAppendBlockIds`, which replays the ids an earlier attempt at this revision minted.
85
+ *
86
+ * The declarations are computed AFTER the append so the log tail and header transforms the attempt
87
+ * just staged are digested too, and purely locally — an id whose base is not cached is omitted and
88
+ * falls back to corroboration on the member side. NOTE: recomputed from scratch on every attempt,
89
+ * so a write that loses N races pays N full hashing passes over its touched blocks. Unmeasured and
90
+ * cheap relative to the round trips it is retrying; if a high-contention write ever shows digest
91
+ * hashing in a profile, memoize per (id, staged ops).
92
+ *
93
+ * @throws BlockTooLargeError when a touched block would be left larger than one message can carry —
94
+ * before anything is sent, judged apart from the declaration (which never throws), and unretried by
95
+ * either write path, since a later attempt would leave the same block. */
96
+ export async function stageAttempt(collectionId, cache, target, identity, rev, newDataBlockId) {
97
+ const tracker = new Tracker(cache, copyTransforms(target.transforms), target.pins);
98
+ const collectionLog = await Log.open(tracker, collectionId, { newDataBlockId: newDataBlockId(tracker) });
99
+ if (!collectionLog) {
100
+ throw new Error(`Log not found for collection ${collectionId}`);
101
+ }
102
+ const added = await collectionLog.addActions([...target.actions], identity.actionId, rev, () => tracker.transformedBlockIds(), { timestamp: identity.timestamp });
103
+ const touched = await describeTouchedBlocks(tracker, tracker.transformedBlockIds());
104
+ const tooLarge = oversizedBlock(touched.bytes);
105
+ if (tooLarge)
106
+ throw tooLarge;
107
+ return {
108
+ tracker,
109
+ rev,
110
+ tailId: added.tailPath.block.header.id,
111
+ blockDigests: touched.digests,
112
+ // The base each update-only block's operations were computed against, for the pend (see
113
+ // `PendRequest.baseRevs`): the pinned revisions, which the caller re-judged before staging.
114
+ baseRevs: tracker.stagedBaseRevs(tracker.transformedBlockIds()),
115
+ };
116
+ }
117
+ /** Exactly what an attempt sends under `actionId`, for `Collection.retainInFlightAttempt` and for
118
+ * the write-ahead hook (`HeadCommitOptions.recordAttempt`): a refused commit is not proof nothing
119
+ * landed, and if the refresh that follows finds the attempt's own log entry these are the
120
+ * transforms that finish the action. The attempt's tracker is abandoned once this is taken, so its
121
+ * transforms are handed over as they are, uncopied.
122
+ * NOTE: the same object reaches the write-ahead hook and is retained for the re-send; nothing in
123
+ * the tree mutates it (a fold clones the inserts and applies the updates to the cache's own blocks),
124
+ * but a hook that mutated its argument would corrupt the re-send. If a hook ever needs to, copy
125
+ * here (`copyTransforms`) rather than at the hook. */
126
+ export function retainedAttempt(staged, actionId) {
127
+ return {
128
+ actionId,
129
+ rev: staged.rev,
130
+ transforms: staged.tracker.transforms,
131
+ tailId: staged.tailId,
132
+ ...(staged.blockDigests === undefined ? {} : { blockDigests: staged.blockDigests }),
133
+ ...baseRevsField(staged.baseRevs),
134
+ };
135
+ }
136
+ /**
137
+ * The inverse of {@link retainedAttempt}, for a head commit opened with `resume`
138
+ * (`HeadCommitOptions.resume`): the attempt an earlier cycle recorded, as a {@link StagedAttempt}
139
+ * that sends exactly what that cycle sent, while `rev` — the revision the next attempt would
140
+ * request — equals the recorded one; `undefined` otherwise, and the attempt is built as usual.
141
+ * The tracker is over the handle's read cache, with a COPY of the recorded transforms (a fold
142
+ * resets it and folds what it holds, and the record stays the caller's) and pins of its own, since
143
+ * it stages nothing.
144
+ *
145
+ * The recorded attempt IS the attempt that may have landed: it can sit on a minority of its cohort,
146
+ * hidden from the refresh by a coordinator lagging that cohort, and storage accepts a retry of one
147
+ * `(action id, revision)` as the same write, so anything but these transforms under that pair forks
148
+ * the block on the machines that hold the first (docs/offline-sync.md §Identity across attempts).
149
+ * Three departures from how an attempt is otherwise built are deliberate:
150
+ * - **Keyed on `resume`, not on the retained attempt.** Within one cycle a retry at an unchanged
151
+ * revision reuses the head tracker and the minted log block ids, so it is byte-identical already,
152
+ * and keeps the re-judging of its base pins before each attempt (`Collection.headTrackerFor`).
153
+ * The recorded attempt is re-sent as it was, unjudged: a base that moved under it is judged by
154
+ * storage's own base guard, which refuses it on every machine whose base moved — the exception
155
+ * `Collection.completeOwnEntry`'s re-send of a retained attempt already takes.
156
+ * - **No invented baseline.** A head tracker over a collection with no committed revision starts
157
+ * from the invented baseline so the header, log block and root ride in the head's commit; the
158
+ * recorded transforms already carry those inserts.
159
+ * - **Only equality switches it on.** A refresh that moves the revision past `attempt.rev` adopted a
160
+ * rival's entry there, which proves the recorded attempt lost at that revision, and the write is
161
+ * rebuilt at the higher one. A revision BELOW it is not reachable inside one process (the held
162
+ * revision never lowers); a new handle after a restart that reaches one has read a view behind the
163
+ * attempt, and the ordinary build handles it as it would without `resume` — the recorded revision
164
+ * is not adopted to get there.
165
+ */
166
+ export function resumedAttempt(cache, attempt, rev) {
167
+ if (attempt === undefined || attempt.rev !== rev) {
168
+ return undefined;
169
+ }
170
+ return {
171
+ tracker: new Tracker(cache, copyTransforms(attempt.transforms)),
172
+ rev: attempt.rev,
173
+ tailId: attempt.tailId,
174
+ blockDigests: attempt.blockDigests,
175
+ baseRevs: attempt.baseRevs ?? {},
176
+ };
177
+ }
178
+ /**
179
+ * The retry accounting of one write's attempt cycle: how many consecutive attempts have been
180
+ * refused, what the responders confirmed, whether the refresh in between moved the collection, and
181
+ * who holds what the write has committed so far. One instance per write; the write path drives it
182
+ * in order — {@link beforeAttempt}, then either {@link recordRefusal} followed by
183
+ * {@link refreshUntilSettled}, or {@link recordCommit}.
184
+ */
185
+ export class AttemptCycle {
186
+ collectionId;
187
+ instanceTag;
188
+ maxAttempts;
189
+ maxStalledAttempts;
190
+ backoff;
191
+ deadlineMs;
192
+ signal;
193
+ rand;
194
+ startedAt = Date.now();
195
+ // Count of consecutive stale failures that made no forward progress. Reset to 0 on every
196
+ // commit, so the cap bounds only a persistently-failing write — a legitimate large multi-batch
197
+ // sync (which iterates many times committing progress) never trips it.
198
+ consecutiveFailures = 0;
199
+ lastReason;
200
+ // Highest confirmed revision any responder has reported holding, accumulated with the
201
+ // codebase's single rule for picking among several candidates. Reported on the error, and
202
+ // the evidence the stall check reasons from.
203
+ lastStaleAt;
204
+ // Whether the failure most recently handled carried its OWN staleAt. A strike needs the
205
+ // responder to have re-confirmed the number this round, not merely an older observation
206
+ // left standing in `lastStaleAt`.
207
+ lastFailureConfirmedStaleAt = false;
208
+ // Refused attempts of this write that carried their own staleAt. Never reset: a member counts
209
+ // its stale refusals per action for the action's whole life, and this is the writer's view of
210
+ // that count (see retryBackoffMs).
211
+ confirmedLosses = 0;
212
+ // Consecutive refreshes that moved the requested revision nowhere at all while a confirmed
213
+ // revision stood at or above it.
214
+ consecutiveStalls = 0;
215
+ // The revision the PREVIOUS attempt would have requested, so the stall check can tell a
216
+ // refresh that moved nowhere from one that is still climbing toward the confirmed number.
217
+ previousRequestedRev;
218
+ /** Who holds what the write has committed so far. Stays `undefined` while nothing has been
219
+ * committed, which is also the answer when no attempt runs at all — a write with nothing staged
220
+ * writes nothing, and there is no durability to fabricate for it. Refused attempts never
221
+ * contribute: a refused attempt left nothing behind, so the answer is the committing one's. A
222
+ * write that commits more than once folds them with `mergeDurability`, whose scalar answer is
223
+ * the WEAKEST: one batch that only reached the writer makes the whole write only-on-the-writer,
224
+ * and reporting the last batch's class instead would show such a write as saved. */
225
+ durability;
226
+ constructor(collectionId, instanceTag, options) {
227
+ this.collectionId = collectionId;
228
+ this.instanceTag = instanceTag;
229
+ this.maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
230
+ this.maxStalledAttempts = options?.maxStalledAttempts ?? DefaultMaxStalledAttempts;
231
+ this.backoff = {
232
+ baseMs: options?.baseBackoffMs ?? PendingRetryDelayMs,
233
+ capMs: options?.maxBackoffMs ?? DefaultMaxBackoffMs,
234
+ };
235
+ this.deadlineMs = options?.deadlineMs;
236
+ this.signal = options?.signal;
237
+ this.rand = options?.rand;
238
+ }
239
+ /** The aged retry priority for the next attempt, from the consecutive-failure count: a write
240
+ * that keeps losing concurrent races out-ranks fresh (priority-0) rivals in the cluster's
241
+ * `resolveRace` (fairness-only, capped at `MaxPriority`). A first attempt is priority 0, so the
242
+ * common pend is unchanged. */
243
+ priority() {
244
+ return clampPriority(this.consecutiveFailures);
245
+ }
246
+ /**
247
+ * The checks that run before an attempt is built: the abort signal, the wall-clock deadline, and
248
+ * the stall check. The deadline comes before the stall check deliberately: it is the documented
249
+ * outer bound, so a write that is both past it and stalled reports the deadline.
250
+ *
251
+ * The stall check asks: can the attempt about to run possibly differ from the one that just
252
+ * failed? Only when BOTH of these hold is the answer provably no:
253
+ *
254
+ * - `requestedRev` is at or below one a responder CONFIRMED is taken. A producer sets `staleAt`
255
+ * only after reading that revision as durably held by someone else out of its own storage,
256
+ * revisions are one per-collection counter that every commit touches, and a confirmed
257
+ * revision never becomes un-taken (invalidation takes a NEW slot). So the request is already
258
+ * lost before it is sent.
259
+ * - The refresh in between moved the collection nowhere. `advanceContext` never lowers the
260
+ * held revision, so "nowhere" is exactly `requestedRev` unchanged since the last attempt. A
261
+ * refresh that moved forward WITHOUT clearing the confirmed number is a collection still
262
+ * climbing (it read a replica that lags the holder — the same partial catch-up
263
+ * `reportShortfall` exists to report), and its next attempt is a genuinely different request
264
+ * that may yet win.
265
+ *
266
+ * This is NOT a second answer to "is this failure retryable?" — `isConflictFailure` remains the
267
+ * sole rule for that, untouched. It only ever stops a loop that rule had already decided to
268
+ * continue.
269
+ *
270
+ * @param requestedRev the revision the attempt would request (`Collection.getNextRev`).
271
+ * @param heldRev the revision the collection holds, for the stall report.
272
+ * @throws AbortError, {@link SyncRetryExhaustedError} (deadline), {@link SyncRevisionStalledError}. */
273
+ beforeAttempt(requestedRev, heldRev) {
274
+ if (this.signal?.aborted) {
275
+ throw makeAbortError(this.signal);
276
+ }
277
+ if (this.pastDeadline()) {
278
+ throw new SyncRetryExhaustedError(this.collectionId, this.consecutiveFailures, this.lastReason ?? 'deadline exceeded', this.lastStaleAt);
279
+ }
280
+ const refreshMoved = this.previousRequestedRev !== undefined && requestedRev > this.previousRequestedRev;
281
+ this.previousRequestedRev = requestedRev;
282
+ if (this.lastStaleAt === undefined) {
283
+ return;
284
+ }
285
+ if (requestedRev > this.lastStaleAt.rev || refreshMoved) {
286
+ // Either the refresh adopted a revision above the confirmed one — ordinary contention,
287
+ // where the rival's commit is exactly what we just read — or it made partial forward
288
+ // progress. Both mean the next attempt differs. Not a stall.
289
+ this.consecutiveStalls = 0;
290
+ }
291
+ else if (this.lastFailureConfirmedStaleAt) {
292
+ this.consecutiveStalls++;
293
+ if (log.enabled) {
294
+ log('collection:sync-stalled id=%s tag=%s heldRev=%s requestedRev=%d staleBlock=%s staleRev=%d strike=%d of=%d', this.collectionId, this.instanceTag, heldRev ?? 'none', requestedRev, this.lastStaleAt.blockId, this.lastStaleAt.rev, this.consecutiveStalls, this.maxStalledAttempts);
295
+ }
296
+ // Two strikes, not one: a legitimate loser can transiently read a view that has not yet
297
+ // caught up with the rival's commit, which looks identical for one round.
298
+ if (this.consecutiveStalls >= this.maxStalledAttempts) {
299
+ throw new SyncRevisionStalledError(this.collectionId, this.consecutiveFailures, this.lastStaleAt, requestedRev, heldRev, this.lastReason);
300
+ }
301
+ }
302
+ // Else: the responder told us nothing new this round. No strike, and no reset either — the
303
+ // budget stays bounded by maxAttempts.
304
+ }
305
+ /**
306
+ * Account for a refused attempt. The three refusals a retry can never get past are thrown by
307
+ * name, with nothing on the collection touched (the attempt ran on its own tracker), so the
308
+ * staged actions are still staged for a later write: an expiry, because the next attempt's
309
+ * expiration comes from the same clock; a promise shortfall, because every coordinator of the
310
+ * cohort meets the same silent members (only a pend answers this way, so nothing of the attempt
311
+ * was stored); a validity rejection, because the next attempt sends the same content to the same
312
+ * checks. Everything else is a stale failure counted against the no-progress budget, so a
313
+ * transactor that persistently rejects can no longer hold the collection latch forever.
314
+ *
315
+ * NOTE: an expiry refusing a commit SWEEP (`NetworkTransactor.commitTailThenSweep`) arrives after
316
+ * the log tail was stored, and no refresh follows this throw, so that attempt's log entry stays
317
+ * behind with none of its data — the state the budget-exhausted exit leaves too. Needs a sweep
318
+ * cohort whose clocks disagree while the tail's agree; tracked with the other leftover-entry
319
+ * exits in tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
320
+ *
321
+ * NOTE: the budget also bounds the legitimate `pending`-wait case (retrying the same action while
322
+ * another commit is in flight), which used to retry indefinitely. Default 10 attempts ≈ 21s of
323
+ * exponential backoff. If a high-contention workload legitimately needs to wait longer for a
324
+ * pending commit to clear, raise maxAttempts for that caller.
325
+ *
326
+ * NOTE: no refresh follows the LAST budgeted attempt, so if that attempt's log tail landed nobody
327
+ * finds out: the caller gets plain exhaustion over a log that holds an entry for this write. The
328
+ * write is still never reported saved, which is the rule; what is lost is the more specific name
329
+ * (TornActionError). The leftover entry itself is tracked in
330
+ * tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
331
+ *
332
+ * @throws TransactionExpiredError, PromiseShortfallError, ValidityRejectedError, SyncRetryExhaustedError */
333
+ recordRefusal(refusal) {
334
+ if (isExpiryFailure(refusal)) {
335
+ throw new TransactionExpiredError(refusal.expired);
336
+ }
337
+ if (isShortfallFailure(refusal)) {
338
+ throw new PromiseShortfallError(refusal.shortfall);
339
+ }
340
+ if (isRejectedFailure(refusal)) {
341
+ throw new ValidityRejectedError(refusal.rejected);
342
+ }
343
+ this.consecutiveFailures++;
344
+ this.lastReason = refusal.reason ?? this.lastReason;
345
+ // Highest-wins, not last-wins: the next request has to clear EVERY holder, so a later
346
+ // responder reporting a LOWER number understates the binding constraint. Same rule the
347
+ // producers and the transactor's aggregation already use.
348
+ this.lastStaleAt = highestStaleAt([this.lastStaleAt, refusal.staleAt]);
349
+ this.lastFailureConfirmedStaleAt = refusal.staleAt !== undefined;
350
+ if (this.lastFailureConfirmedStaleAt)
351
+ this.confirmedLosses++;
352
+ if (this.consecutiveFailures >= this.maxAttempts) {
353
+ throw new SyncRetryExhaustedError(this.collectionId, this.consecutiveFailures, this.lastReason, this.lastStaleAt);
354
+ }
355
+ }
356
+ /** Account for a commit — by an attempt, or by a refresh that finished the write's own entry,
357
+ * which is a commit too and is reported and counted exactly like one (see {@link durability}).
358
+ * Forward progress: the no-progress budget and the stall evidence start over. */
359
+ recordCommit(durability) {
360
+ this.durability = this.durability === undefined ? durability : mergeDurability([this.durability, durability]);
361
+ this.consecutiveFailures = 0;
362
+ this.lastReason = undefined;
363
+ this.lastStaleAt = undefined;
364
+ this.lastFailureConfirmedStaleAt = false;
365
+ this.consecutiveStalls = 0;
366
+ }
367
+ /**
368
+ * Back off, refresh, and keep refreshing while the refresh reports that this write's own
369
+ * half-landed action could not be finished YET. The write path must not fall through to a new
370
+ * attempt in that state: the action's log entry is already durable, and as soon as a refresh
371
+ * adopts a newer revision a new attempt appends a SECOND entry under the same action id — the
372
+ * duplicate `Collection.consumeOwnEntry` exists to prevent. (At an unchanged revision the rebuild
373
+ * is byte-identical — see `Collection.logAppendBlockIds` — so what is at stake is the second
374
+ * entry, not two versions of one tail block.) Each round is a failure against the same
375
+ * no-progress budget as a refused attempt, and the round that would spend the last of it is told
376
+ * so (`lastChance`), so it settles a half-landed write instead of asking for another round and
377
+ * the error that escapes says whether the write can still land. (A deadline cannot be foreseen
378
+ * the same way; a write given up on it escapes unsettled, as `final: false`.)
379
+ *
380
+ * The backoff before each round grows exponentially from the base delay up to the cap, with
381
+ * proportional random jitter so a herd of clients that lost the same race does not re-collide on
382
+ * the next tick (see utility/backoff.ts) — except once this write has lost to committed rivals
383
+ * often enough that a member holds the next slot for it ({@link retryBackoffMs}). The abortable
384
+ * sleep lets an aborted write reject promptly instead of finishing the sleep. A refresh that
385
+ * follows NO refused attempt — the one `Collection.commitHead` opens its cycle with — sleeps not
386
+ * at all: there is no race to space out.
387
+ * NOTE: the `missing`/`reason` conflict paths pay this backoff too (they used to retry with zero
388
+ * delay); that is what stops the persistent-`reason` hot spin. If a high-contention workload ever
389
+ * shows this base delay as recovery latency, lower baseBackoffMs for that caller rather than
390
+ * reintroducing the zero-delay retry.
391
+ *
392
+ * The highest revision a responder confirmed is taken rides out as the floor of the refresh's
393
+ * tail read, so a machine that has not caught up to it is not the last one asked (see
394
+ * `Collection.updateInternal`).
395
+ *
396
+ * @returns whether the refresh FINISHED the write's own log entry (`RefreshReport.ownEntryFinished`)
397
+ * — the write is saved and the entry consumed, whether or not the refresh learned who holds it.
398
+ * @throws TornActionError with any reason but an unsettled `completion-refused`, and that one too
399
+ * once the budget or the deadline is spent; whatever else the refresh throws. */
400
+ async refreshUntilSettled(refresh) {
401
+ // Whether the failure just handled was a loss to a rival already durably committed. Only the
402
+ // attempt's own refusal can say so; a refresh refused for a cause that can clear (below) is a
403
+ // race against something still in flight, and clears it.
404
+ let latestConfirmed = this.lastFailureConfirmedStaleAt;
405
+ for (;;) {
406
+ const delay = this.consecutiveFailures === 0
407
+ ? 0
408
+ : retryBackoffMs(this.consecutiveFailures, this.confirmedLosses, latestConfirmed, this.backoff, this.rand);
409
+ await abortableDelay(delay, this.signal);
410
+ try {
411
+ const report = {};
412
+ await refresh(report, this.consecutiveFailures + 1 >= this.maxAttempts, this.lastStaleAt?.rev);
413
+ const completed = report.ownEntryFinished?.durability;
414
+ if (completed !== undefined) {
415
+ this.recordCommit(completed);
416
+ }
417
+ return report.ownEntryFinished !== undefined;
418
+ }
419
+ catch (err) {
420
+ if (!(err instanceof TornActionError) || err.reason !== 'completion-refused') {
421
+ throw err;
422
+ }
423
+ // Refused for a cause that can clear. The error already names the write as torn, which
424
+ // is the truth if the budget ends here — so it, not a plain exhaustion, is what escapes:
425
+ // the log holds an entry for a write that was not saved.
426
+ this.consecutiveFailures++;
427
+ this.lastReason = err.detail;
428
+ latestConfirmed = false;
429
+ if (this.consecutiveFailures >= this.maxAttempts || this.pastDeadline()) {
430
+ throw err;
431
+ }
432
+ }
433
+ }
434
+ }
435
+ pastDeadline() {
436
+ return this.deadlineMs !== undefined && Date.now() - this.startedAt >= this.deadlineMs;
437
+ }
438
+ }
439
+ //# sourceMappingURL=write-attempts.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"write-attempts.js","sourceRoot":"","sources":["../../../src/collection/write-attempts.ts"],"names":[],"mappings":"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"}
@@ -1,5 +1,6 @@
1
1
  import type { BlockId, CollectionHeaderBlock, CollectionId } from "../../index.js";
2
2
  import type { KeyRange } from "../../btree/index.js";
3
+ import { ActionRefusedError } from "../../collection/struct.js";
3
4
  export declare const TreeHeaderBlockType: string;
4
5
  export type TreeCollectionHeaderBlock = CollectionHeaderBlock & {
5
6
  rootId: BlockId;
@@ -27,6 +28,9 @@ export declare const rootId$: string;
27
28
  * re-stage of a present key (a replay after a clean refresh) would refuse itself.
28
29
  * - `unchanged` — see {@link TreeUnchangedGuard}: the only kind that says something must
29
30
  * still BE here, rather than that nothing may be.
31
+ * - `absentOrEqual`, `unchangedOrEqual`, `unchangedOrAbsent` — the three ALREADY-APPLIED variants
32
+ * (see {@link TreeAlreadyAppliedGuard}): each accepts, and SKIPS the element, where a rival has
33
+ * already made exactly the change this element makes, instead of refusing it.
30
34
  *
31
35
  * MIXED VERSIONS: a peer running a build that predates guards destructures `[key, entry]`
32
36
  * and ignores the third slot — its replays revert to today's silent overwrite. No version
@@ -39,7 +43,57 @@ export type TreeEntryGuard<TKey, TEntry = unknown> = {
39
43
  } | {
40
44
  kind: 'absentRange';
41
45
  range: KeyRange<TKey>;
42
- } | TreeUnchangedGuard<TEntry>;
46
+ } | TreeUnchangedGuard<TEntry> | TreeAlreadyAppliedGuard<TEntry>;
47
+ /**
48
+ * The three guard kinds that accept a row another writer already changed the same way, for the
49
+ * offline-sync queue's rebase of a queued entry (docs/offline-sync.md §Guards that make idempotent
50
+ * writes assured). Every guard above refuses when the row is not as the staged write found it, which
51
+ * includes the rival that made exactly the change this write makes: two machines marking one task
52
+ * done, two machines deleting one row. Each variant below has three outcomes, where its base kind has
53
+ * two — it ACCEPTS AND WRITES as the base kind does, it ACCEPTS AS ALREADY APPLIED and skips the
54
+ * element (the final state is the one the write intended), or it REFUSES with the base kind's error:
55
+ *
56
+ * | Kind | Element | Writes when | Skips as already applied when | Refuses with |
57
+ * |---|---|---|---|---|
58
+ * | `absentOrEqual` | upsert | the key is absent | the present entry equals the element's own `entry` | {@link TreeKeyTakenError}, as `absent` does |
59
+ * | `unchangedOrEqual` | upsert | the present entry equals `expected` | the present entry equals the element's own `entry` (checked second, so a no-op update whose `expected` equals its `entry` writes) | {@link TreeEntryChangedError} on absent or any other entry |
60
+ * | `unchangedOrAbsent` | delete | the present entry equals `expected` | the key is absent | {@link TreeEntryChangedError} on any other entry |
61
+ *
62
+ * "Equals" is `structuralEquals` in `packages/db-core/src/utility/structural-equals.ts`, the
63
+ * comparison `unchanged` uses, with the same JSON caveats {@link TreeUnchangedGuard} states. The
64
+ * post-image an upsert variant compares against is the element's own `entry`, not a second copy on
65
+ * the guard: the element already carries it, so the guard stays the size its base kind is.
66
+ *
67
+ * Kinds and elements: `unchangedOrAbsent` is meaningful only on a delete (on an upsert it would mean
68
+ * "resurrect the row"), and the two `…OrEqual` kinds only on an upsert (a delete has no `entry` to
69
+ * compare, and would be a no-op by construction). The handler narrows both ways at runtime: a delete
70
+ * carrying an upsert-only kind throws {@link TreeDeleteGuardKindError}, an upsert carrying the
71
+ * delete-only kind {@link TreeUpsertGuardKindError} — malformed actions, outside the refusal
72
+ * hierarchy, never ignored.
73
+ *
74
+ * Whether an element accepted as already applied changed anything is reported out of the handler
75
+ * as an `AlreadyAppliedTally` (`packages/db-core/src/collection/action.ts`), which the offline queue
76
+ * folds into the `effect` of its `committed` status.
77
+ */
78
+ export type TreeAlreadyAppliedGuard<TEntry = unknown> = {
79
+ kind: 'absentOrEqual';
80
+ } | {
81
+ kind: 'unchangedOrEqual'; /** The entry image the staged write read, as stored. */
82
+ expected: TEntry;
83
+ } | {
84
+ kind: 'unchangedOrAbsent'; /** The entry image the staged delete read, as stored. */
85
+ expected: TEntry;
86
+ };
87
+ /** The kinds a {@link TreeUpsertElement} may carry: every kind but the delete-only
88
+ * `unchangedOrAbsent`. */
89
+ export type TreeUpsertGuard<TKey, TEntry = unknown> = Exclude<TreeEntryGuard<TKey, TEntry>, {
90
+ kind: 'unchangedOrAbsent';
91
+ }>;
92
+ /** The kinds a {@link TreeDeleteElement} may carry: the two that say something must still BE at the
93
+ * key — `unchanged`, and `unchangedOrAbsent`, which also accepts the key already gone. */
94
+ export type TreeDeleteGuard<TEntry = unknown> = TreeUnchangedGuard<TEntry> | Extract<TreeAlreadyAppliedGuard<TEntry>, {
95
+ kind: 'unchangedOrAbsent';
96
+ }>;
43
97
  /**
44
98
  * "The entry I am replacing must still be exactly the one I read" — the optimistic-concurrency
45
99
  * (lost-update) guard, and the only {@link TreeEntryGuard} kind that also applies to a DELETE.
@@ -51,8 +105,9 @@ export type TreeEntryGuard<TKey, TEntry = unknown> = {
51
105
  * exists, so re-applying it is never right: an upsert would resurrect a row a rival deleted, and
52
106
  * a delete would be the second of two racing deletes. Refusing both is the optimistic answer —
53
107
  * the writer read a row that is now gone, and an application-level retry then affects zero rows
54
- * sequentially. If tolerating absence on deletes is ever genuinely wanted, add a separate
55
- * `unchangedOrAbsent` kind rather than weakening this one's contract.
108
+ * sequentially. A delete that means "gone either way" carries `unchangedOrAbsent` instead, and an
109
+ * upsert that means "equal either way" carries `unchangedOrEqual` ({@link TreeAlreadyAppliedGuard});
110
+ * this kind's contract is not weakened for them.
56
111
  *
57
112
  * `expected` is the entry AS STORED, not a digest: a guard rides in the log beside its action
58
113
  * under the same encoding entries already use, so a full copy round-trips by construction and no
@@ -69,21 +124,22 @@ export type TreeUnchangedGuard<TEntry = unknown> = {
69
124
  /** The entry image the staged write read, as stored. */
70
125
  expected: TEntry;
71
126
  };
72
- /** An element that writes (inserts or replaces) an entry. Any {@link TreeEntryGuard} kind is
73
- * meaningful here. */
127
+ /** An element that writes (inserts or replaces) an entry. Every {@link TreeEntryGuard} kind but the
128
+ * delete-only `unchangedOrAbsent` is meaningful here ({@link TreeUpsertGuard}). */
74
129
  export type TreeUpsertElement<TKey, TEntry> = [
75
130
  key: TKey,
76
131
  entry: TEntry,
77
- guard?: TreeEntryGuard<TKey, TEntry>
132
+ guard?: TreeUpsertGuard<TKey, TEntry>
78
133
  ];
79
- /** An element that deletes the entry at a key. Only {@link TreeUnchangedGuard} says anything a
80
- * delete can act on — the other kinds all assert that nothing is present, which would make the
81
- * delete a no-op by construction. The handler rejects any other kind at runtime too, since a
82
- * replayed log entry is deserialized data that this type never policed. */
134
+ /** An element that deletes the entry at a key. Only the two kinds that say something must still BE
135
+ * at the key say anything a delete can act on ({@link TreeDeleteGuard}) — the other kinds all assert
136
+ * that nothing is present, which would make the delete a no-op by construction. The handler rejects
137
+ * any other kind at runtime too, since a replayed log entry is deserialized data that this type
138
+ * never policed. */
83
139
  export type TreeDeleteElement<TKey, TEntry> = [
84
140
  key: TKey,
85
141
  entry?: undefined,
86
- guard?: TreeUnchangedGuard<TEntry>
142
+ guard?: TreeDeleteGuard<TEntry>
87
143
  ];
88
144
  /** Represents a unit of change to a tree collection. */
89
145
  export type TreeReplaceAction<TKey, TEntry> = (TreeUpsertElement<TKey, TEntry> | TreeDeleteElement<TKey, TEntry>)[];
@@ -104,10 +160,13 @@ export type TreeReplaceAction<TKey, TEntry> = (TreeUpsertElement<TKey, TEntry> |
104
160
  * {@link TreeEntryChangedError} is a lost update (the bridge raises its
105
161
  * `ConcurrentModificationError`, status code BUSY, which is not a constraint error). Catch
106
162
  * this base to treat any guard refusal uniformly; catch a subclass to say which happened.
163
+ *
164
+ * It is the tree's {@link ActionRefusedError}, which is what the collection's segment-aware
165
+ * replay recognises (a refusal from a sealed segment is recorded against that segment rather
166
+ * than thrown — see `Collection.replayActions`); the classifier and the bridge keep matching
167
+ * this class, which the subclass relation leaves unchanged.
107
168
  */
108
- export declare class TreeGuardRefusedError<TKey = unknown> extends Error {
109
- /** The collection whose tree refused the entry. */
110
- readonly collectionId: CollectionId;
169
+ export declare class TreeGuardRefusedError<TKey = unknown> extends ActionRefusedError {
111
170
  /** The key whose staged entry was refused. */
112
171
  readonly key: TKey;
113
172
  constructor(
@@ -184,21 +243,45 @@ export declare class TreeEntryChangedError<TKey = unknown, TEntry = unknown> ext
184
243
  * present, which would make the delete a no-op by construction, so this is a malformed action —
185
244
  * a caller bug, or a log entry written by a build whose element types disagree with this one.
186
245
  * The handler raises it rather than ignoring the guard (the pre-guard behaviour) so a writer
187
- * never believes an unenforceable guard is being enforced.
246
+ * never believes an unenforceable guard is being enforced. {@link TreeUpsertGuardKindError} is the
247
+ * upsert side of the same check.
188
248
  */
189
249
  export declare class TreeDeleteGuardKindError<TKey = unknown> extends Error {
190
250
  /** The collection whose tree rejected the element. */
191
251
  readonly collectionId: CollectionId;
192
252
  /** The key the malformed delete named. */
193
253
  readonly key: TKey;
194
- /** The `kind` that was carried; only `'unchanged'` is meaningful on a delete. */
254
+ /** The `kind` that was carried; only `'unchanged'` and `'unchangedOrAbsent'` are meaningful on
255
+ * a delete. */
195
256
  readonly guardKind: string;
196
257
  constructor(
197
258
  /** The collection whose tree rejected the element. */
198
259
  collectionId: CollectionId,
199
260
  /** The key the malformed delete named. */
200
261
  key: TKey,
201
- /** The `kind` that was carried; only `'unchanged'` is meaningful on a delete. */
262
+ /** The `kind` that was carried; only `'unchanged'` and `'unchangedOrAbsent'` are meaningful on
263
+ * a delete. */
264
+ guardKind: string);
265
+ }
266
+ /**
267
+ * An UPSERT element carries the delete-only guard kind, `unchangedOrAbsent`: on an upsert it would
268
+ * mean "write the row whether or not a rival deleted it", which resurrects a row the staged write
269
+ * never meant to and so is a malformed action, not a concurrency refusal — the mirror of
270
+ * {@link TreeDeleteGuardKindError}, and like it deliberately not a {@link TreeGuardRefusedError}.
271
+ */
272
+ export declare class TreeUpsertGuardKindError<TKey = unknown> extends Error {
273
+ /** The collection whose tree rejected the element. */
274
+ readonly collectionId: CollectionId;
275
+ /** The key the malformed upsert named. */
276
+ readonly key: TKey;
277
+ /** The `kind` that was carried. */
278
+ readonly guardKind: string;
279
+ constructor(
280
+ /** The collection whose tree rejected the element. */
281
+ collectionId: CollectionId,
282
+ /** The key the malformed upsert named. */
283
+ key: TKey,
284
+ /** The `kind` that was carried. */
202
285
  guardKind: string);
203
286
  }
204
287
  //# sourceMappingURL=struct.d.ts.map