@optimystic/db-core 1.18.0 → 1.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/README.md +2 -1
  2. package/dist/src/blocks/helpers.d.ts +7 -0
  3. package/dist/src/blocks/helpers.d.ts.map +1 -1
  4. package/dist/src/blocks/helpers.js +7 -1
  5. package/dist/src/blocks/helpers.js.map +1 -1
  6. package/dist/src/btree/btree.d.ts +100 -4
  7. package/dist/src/btree/btree.d.ts.map +1 -1
  8. package/dist/src/btree/btree.js +252 -90
  9. package/dist/src/btree/btree.js.map +1 -1
  10. package/dist/src/btree/node-division.d.ts +37 -0
  11. package/dist/src/btree/node-division.d.ts.map +1 -0
  12. package/dist/src/btree/node-division.js +133 -0
  13. package/dist/src/btree/node-division.js.map +1 -0
  14. package/dist/src/chain/chain.d.ts +23 -0
  15. package/dist/src/chain/chain.d.ts.map +1 -1
  16. package/dist/src/chain/chain.js +43 -6
  17. package/dist/src/chain/chain.js.map +1 -1
  18. package/dist/src/cluster/structs.d.ts +41 -8
  19. package/dist/src/cluster/structs.d.ts.map +1 -1
  20. package/dist/src/cluster/structs.js +18 -7
  21. package/dist/src/cluster/structs.js.map +1 -1
  22. package/dist/src/collection/action.d.ts +29 -0
  23. package/dist/src/collection/action.d.ts.map +1 -1
  24. package/dist/src/collection/action.js +6 -0
  25. package/dist/src/collection/action.js.map +1 -1
  26. package/dist/src/collection/collection.d.ts +566 -120
  27. package/dist/src/collection/collection.d.ts.map +1 -1
  28. package/dist/src/collection/collection.js +1084 -495
  29. package/dist/src/collection/collection.js.map +1 -1
  30. package/dist/src/collection/head-commit.d.ts +110 -0
  31. package/dist/src/collection/head-commit.d.ts.map +1 -0
  32. package/dist/src/collection/head-commit.js +65 -0
  33. package/dist/src/collection/head-commit.js.map +1 -0
  34. package/dist/src/collection/index.d.ts +2 -0
  35. package/dist/src/collection/index.d.ts.map +1 -1
  36. package/dist/src/collection/index.js +2 -0
  37. package/dist/src/collection/index.js.map +1 -1
  38. package/dist/src/collection/segments.d.ts +77 -0
  39. package/dist/src/collection/segments.d.ts.map +1 -0
  40. package/dist/src/collection/segments.js +110 -0
  41. package/dist/src/collection/segments.js.map +1 -0
  42. package/dist/src/collection/struct.d.ts +176 -1
  43. package/dist/src/collection/struct.d.ts.map +1 -1
  44. package/dist/src/collection/struct.js +70 -0
  45. package/dist/src/collection/struct.js.map +1 -1
  46. package/dist/src/collection/write-attempts.d.ts +245 -0
  47. package/dist/src/collection/write-attempts.d.ts.map +1 -0
  48. package/dist/src/collection/write-attempts.js +439 -0
  49. package/dist/src/collection/write-attempts.js.map +1 -0
  50. package/dist/src/collections/tree/struct.d.ts +100 -17
  51. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  52. package/dist/src/collections/tree/struct.js +38 -7
  53. package/dist/src/collections/tree/struct.js.map +1 -1
  54. package/dist/src/collections/tree/tree.d.ts +17 -5
  55. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  56. package/dist/src/collections/tree/tree.js +117 -29
  57. package/dist/src/collections/tree/tree.js.map +1 -1
  58. package/dist/src/index.d.ts +2 -0
  59. package/dist/src/index.d.ts.map +1 -1
  60. package/dist/src/index.js +2 -0
  61. package/dist/src/index.js.map +1 -1
  62. package/dist/src/log/log.d.ts +5 -1
  63. package/dist/src/log/log.d.ts.map +1 -1
  64. package/dist/src/log/log.js +7 -1
  65. package/dist/src/log/log.js.map +1 -1
  66. package/dist/src/network/block-size.d.ts +67 -0
  67. package/dist/src/network/block-size.d.ts.map +1 -0
  68. package/dist/src/network/block-size.js +82 -0
  69. package/dist/src/network/block-size.js.map +1 -0
  70. package/dist/src/network/i-repo.d.ts +3 -0
  71. package/dist/src/network/i-repo.d.ts.map +1 -1
  72. package/dist/src/network/index.d.ts +5 -0
  73. package/dist/src/network/index.d.ts.map +1 -1
  74. package/dist/src/network/index.js +5 -0
  75. package/dist/src/network/index.js.map +1 -1
  76. package/dist/src/network/promise-shortfall-error.d.ts +40 -0
  77. package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
  78. package/dist/src/network/promise-shortfall-error.js +67 -0
  79. package/dist/src/network/promise-shortfall-error.js.map +1 -0
  80. package/dist/src/network/refuse-solo.d.ts +8 -0
  81. package/dist/src/network/refuse-solo.d.ts.map +1 -0
  82. package/dist/src/network/refuse-solo.js +8 -0
  83. package/dist/src/network/refuse-solo.js.map +1 -0
  84. package/dist/src/network/stale-failure.d.ts +20 -3
  85. package/dist/src/network/stale-failure.d.ts.map +1 -1
  86. package/dist/src/network/stale-failure.js +24 -3
  87. package/dist/src/network/stale-failure.js.map +1 -1
  88. package/dist/src/network/struct.d.ts +161 -13
  89. package/dist/src/network/struct.d.ts.map +1 -1
  90. package/dist/src/network/struct.js.map +1 -1
  91. package/dist/src/network/transaction-size.d.ts +59 -0
  92. package/dist/src/network/transaction-size.d.ts.map +1 -0
  93. package/dist/src/network/transaction-size.js +74 -0
  94. package/dist/src/network/transaction-size.js.map +1 -0
  95. package/dist/src/network/validity-rejected-error.d.ts +28 -0
  96. package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
  97. package/dist/src/network/validity-rejected-error.js +51 -0
  98. package/dist/src/network/validity-rejected-error.js.map +1 -0
  99. package/dist/src/offline/entry.d.ts +72 -0
  100. package/dist/src/offline/entry.d.ts.map +1 -0
  101. package/dist/src/offline/entry.js +73 -0
  102. package/dist/src/offline/entry.js.map +1 -0
  103. package/dist/src/offline/index.d.ts +5 -0
  104. package/dist/src/offline/index.d.ts.map +1 -0
  105. package/dist/src/offline/index.js +5 -0
  106. package/dist/src/offline/index.js.map +1 -0
  107. package/dist/src/offline/journal.d.ts +61 -0
  108. package/dist/src/offline/journal.d.ts.map +1 -0
  109. package/dist/src/offline/journal.js +2 -0
  110. package/dist/src/offline/journal.js.map +1 -0
  111. package/dist/src/offline/queue.d.ts +484 -0
  112. package/dist/src/offline/queue.d.ts.map +1 -0
  113. package/dist/src/offline/queue.js +1236 -0
  114. package/dist/src/offline/queue.js.map +1 -0
  115. package/dist/src/offline/reachability.d.ts +25 -0
  116. package/dist/src/offline/reachability.d.ts.map +1 -0
  117. package/dist/src/offline/reachability.js +13 -0
  118. package/dist/src/offline/reachability.js.map +1 -0
  119. package/dist/src/offline/status.d.ts +148 -0
  120. package/dist/src/offline/status.d.ts.map +1 -0
  121. package/dist/src/offline/status.js +63 -0
  122. package/dist/src/offline/status.js.map +1 -0
  123. package/dist/src/offline/wake.d.ts +30 -0
  124. package/dist/src/offline/wake.d.ts.map +1 -0
  125. package/dist/src/offline/wake.js +68 -0
  126. package/dist/src/offline/wake.js.map +1 -0
  127. package/dist/src/reactivity/config.d.ts +8 -4
  128. package/dist/src/reactivity/config.d.ts.map +1 -1
  129. package/dist/src/reactivity/config.js +7 -3
  130. package/dist/src/reactivity/config.js.map +1 -1
  131. package/dist/src/reactivity/rotation.d.ts +9 -3
  132. package/dist/src/reactivity/rotation.d.ts.map +1 -1
  133. package/dist/src/reactivity/rotation.js +8 -2
  134. package/dist/src/reactivity/rotation.js.map +1 -1
  135. package/dist/src/testing/test-transactor.d.ts +31 -0
  136. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  137. package/dist/src/testing/test-transactor.js +60 -0
  138. package/dist/src/testing/test-transactor.js.map +1 -1
  139. package/dist/src/transaction/commit-failure-class.d.ts +103 -0
  140. package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
  141. package/dist/src/transaction/commit-failure-class.js +96 -0
  142. package/dist/src/transaction/commit-failure-class.js.map +1 -0
  143. package/dist/src/transaction/coordinator.d.ts +224 -31
  144. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  145. package/dist/src/transaction/coordinator.js +841 -362
  146. package/dist/src/transaction/coordinator.js.map +1 -1
  147. package/dist/src/transaction/entry-commit.d.ts +139 -0
  148. package/dist/src/transaction/entry-commit.d.ts.map +1 -0
  149. package/dist/src/transaction/entry-commit.js +199 -0
  150. package/dist/src/transaction/entry-commit.js.map +1 -0
  151. package/dist/src/transaction/index.d.ts +4 -1
  152. package/dist/src/transaction/index.d.ts.map +1 -1
  153. package/dist/src/transaction/index.js +1 -0
  154. package/dist/src/transaction/index.js.map +1 -1
  155. package/dist/src/transaction/transaction.d.ts +20 -0
  156. package/dist/src/transaction/transaction.d.ts.map +1 -1
  157. package/dist/src/transaction/validator.d.ts +7 -0
  158. package/dist/src/transaction/validator.d.ts.map +1 -1
  159. package/dist/src/transaction/validator.js +21 -12
  160. package/dist/src/transaction/validator.js.map +1 -1
  161. package/dist/src/transactor/change-notifier.d.ts +13 -4
  162. package/dist/src/transactor/change-notifier.d.ts.map +1 -1
  163. package/dist/src/transactor/change-notifier.js.map +1 -1
  164. package/dist/src/transactor/network-transactor.d.ts +58 -8
  165. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  166. package/dist/src/transactor/network-transactor.js +244 -50
  167. package/dist/src/transactor/network-transactor.js.map +1 -1
  168. package/dist/src/transactor/transactor-source.d.ts +22 -11
  169. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  170. package/dist/src/transactor/transactor-source.js +9 -13
  171. package/dist/src/transactor/transactor-source.js.map +1 -1
  172. package/dist/src/transactor/transactor.d.ts +14 -0
  173. package/dist/src/transactor/transactor.d.ts.map +1 -1
  174. package/dist/src/transform/digest.d.ts +20 -0
  175. package/dist/src/transform/digest.d.ts.map +1 -1
  176. package/dist/src/transform/digest.js +23 -3
  177. package/dist/src/transform/digest.js.map +1 -1
  178. package/dist/src/utility/visit-every.d.ts +14 -0
  179. package/dist/src/utility/visit-every.d.ts.map +1 -0
  180. package/dist/src/utility/visit-every.js +27 -0
  181. package/dist/src/utility/visit-every.js.map +1 -0
  182. package/package.json +1 -1
  183. package/src/blocks/helpers.ts +8 -1
  184. package/src/btree/btree.ts +266 -88
  185. package/src/btree/node-division.ts +155 -0
  186. package/src/chain/chain.ts +55 -6
  187. package/src/cluster/structs.ts +42 -7
  188. package/src/collection/action.ts +34 -0
  189. package/src/collection/collection.ts +1167 -540
  190. package/src/collection/head-commit.ts +148 -0
  191. package/src/collection/index.ts +2 -0
  192. package/src/collection/segments.ts +149 -0
  193. package/src/collection/struct.ts +201 -1
  194. package/src/collection/write-attempts.ts +506 -0
  195. package/src/collections/tree/struct.ts +97 -17
  196. package/src/collections/tree/tree.ts +129 -31
  197. package/src/index.ts +2 -0
  198. package/src/log/log.ts +7 -1
  199. package/src/network/block-size.ts +81 -0
  200. package/src/network/i-repo.ts +3 -0
  201. package/src/network/index.ts +5 -0
  202. package/src/network/promise-shortfall-error.ts +69 -0
  203. package/src/network/refuse-solo.ts +7 -0
  204. package/src/network/stale-failure.ts +27 -4
  205. package/src/network/struct.ts +169 -15
  206. package/src/network/transaction-size.ts +73 -0
  207. package/src/network/validity-rejected-error.ts +55 -0
  208. package/src/offline/entry.ts +127 -0
  209. package/src/offline/index.ts +4 -0
  210. package/src/offline/journal.ts +60 -0
  211. package/src/offline/queue.ts +1342 -0
  212. package/src/offline/reachability.ts +32 -0
  213. package/src/offline/status.ts +183 -0
  214. package/src/offline/wake.ts +67 -0
  215. package/src/reactivity/config.ts +8 -4
  216. package/src/reactivity/rotation.ts +9 -3
  217. package/src/testing/test-transactor.ts +65 -0
  218. package/src/transaction/commit-failure-class.ts +133 -0
  219. package/src/transaction/coordinator.ts +969 -393
  220. package/src/transaction/entry-commit.ts +285 -0
  221. package/src/transaction/index.ts +4 -0
  222. package/src/transaction/transaction.ts +21 -0
  223. package/src/transaction/validator.ts +22 -12
  224. package/src/transactor/change-notifier.ts +13 -4
  225. package/src/transactor/network-transactor.ts +252 -55
  226. package/src/transactor/transactor-source.ts +29 -13
  227. package/src/transactor/transactor.ts +16 -0
  228. package/src/transform/digest.ts +36 -3
  229. package/src/utility/visit-every.ts +25 -0
@@ -0,0 +1,245 @@
1
+ import type { IBlock, BlockId, Action, ActionId, BlockContentDigests, BlockStore, Transforms, WriteDurability, WriteFailure } from "../index.js";
2
+ import type { BlockBaseRevs } from "../network/struct.js";
3
+ import { Tracker } from "../transform/tracker.js";
4
+ import type { BasePins } from "../transform/base-pins.js";
5
+ import type { CacheSource } from "../transform/cache-source.js";
6
+ import type { CollectionId, InFlightAttempt, SyncOptions } from "./struct.js";
7
+ import type { RefreshReport } from "./collection.js";
8
+ /** What a write is identified as on the wire: the action id every attempt of it reuses, and the
9
+ * log entry's timestamp. Both are minted once per WRITE, never per attempt, so a retry at the same
10
+ * revision appends the same entry (docs/internals.md, "A write's log append is a fixed function of
11
+ * the write and the revision it is requesting"). */
12
+ export type WriteIdentity = {
13
+ readonly actionId: ActionId;
14
+ readonly timestamp: number;
15
+ };
16
+ /** What one attempt is built from: the actions its log entry records, the transforms they produced
17
+ * over the committed state, and the bases those transforms were computed against. For a sync these
18
+ * are the open segment and the live tracker's; for a head commit the head segment and the head
19
+ * tracker's (see `Collection.commitHead`). */
20
+ export type AttemptTarget<TAction> = {
21
+ readonly actions: readonly Action<TAction>[];
22
+ readonly transforms: Transforms;
23
+ readonly pins: BasePins;
24
+ };
25
+ /** One attempt as it goes on the wire: a per-attempt tracker holding the target's transforms plus
26
+ * the log append, the revision it requests, and the declarations the pend and commit carry. */
27
+ export type StagedAttempt = {
28
+ readonly tracker: Tracker<IBlock>;
29
+ readonly rev: number;
30
+ /** The log tail block the entry was appended to, committed first. */
31
+ readonly tailId: BlockId;
32
+ readonly blockDigests: BlockContentDigests | undefined;
33
+ readonly baseRevs: BlockBaseRevs;
34
+ };
35
+ /**
36
+ * Build one attempt: a tracker seeded with a COPY of the target's transforms, so the target is
37
+ * untouched whatever becomes of the attempt, with the log entry for `target.actions` appended at
38
+ * `rev` under `identity`, then the content declarations and the size check.
39
+ *
40
+ * The per-attempt tracker SHARES the target's pin store: it inherits the transforms by copy and
41
+ * never stages the data-block updates itself, so without the shared pins the digest pass could only
42
+ * describe bases still resident in the read cache. NOTE: an attempt that ends in a stale failure is
43
+ * abandoned WITHOUT reset(), so the log tail/header bases its append pinned stay in the shared
44
+ * store until the target tracker's next reset. Bounded and harmless — a few log blocks per
45
+ * attempt, capped by `maxAttempts`, each re-validated against the source generation before any use
46
+ * — but if an attempt ever grows a per-attempt footprint beyond the log blocks, reset the abandoned
47
+ * tracker on the stale-failure branch instead of letting the residue ride to the end of the write.
48
+ *
49
+ * The append is a fixed function of the write and `rev`: the timestamp is the identity's, and any
50
+ * data block the append has to mint takes the id `newDataBlockId` hands out — the caller's
51
+ * `Collection.logAppendBlockIds`, which replays the ids an earlier attempt at this revision minted.
52
+ *
53
+ * The declarations are computed AFTER the append so the log tail and header transforms the attempt
54
+ * just staged are digested too, and purely locally — an id whose base is not cached is omitted and
55
+ * falls back to corroboration on the member side. NOTE: recomputed from scratch on every attempt,
56
+ * so a write that loses N races pays N full hashing passes over its touched blocks. Unmeasured and
57
+ * cheap relative to the round trips it is retrying; if a high-contention write ever shows digest
58
+ * hashing in a profile, memoize per (id, staged ops).
59
+ *
60
+ * @throws BlockTooLargeError when a touched block would be left larger than one message can carry —
61
+ * before anything is sent, judged apart from the declaration (which never throws), and unretried by
62
+ * either write path, since a later attempt would leave the same block. */
63
+ export declare function stageAttempt<TAction>(collectionId: CollectionId, cache: CacheSource<IBlock>, target: AttemptTarget<TAction>, identity: WriteIdentity, rev: number, newDataBlockId: (store: BlockStore<IBlock>) => () => BlockId): Promise<StagedAttempt>;
64
+ /** Exactly what an attempt sends under `actionId`, for `Collection.retainInFlightAttempt` and for
65
+ * the write-ahead hook (`HeadCommitOptions.recordAttempt`): a refused commit is not proof nothing
66
+ * landed, and if the refresh that follows finds the attempt's own log entry these are the
67
+ * transforms that finish the action. The attempt's tracker is abandoned once this is taken, so its
68
+ * transforms are handed over as they are, uncopied.
69
+ * NOTE: the same object reaches the write-ahead hook and is retained for the re-send; nothing in
70
+ * the tree mutates it (a fold clones the inserts and applies the updates to the cache's own blocks),
71
+ * but a hook that mutated its argument would corrupt the re-send. If a hook ever needs to, copy
72
+ * here (`copyTransforms`) rather than at the hook. */
73
+ export declare function retainedAttempt(staged: StagedAttempt, actionId: ActionId): InFlightAttempt;
74
+ /**
75
+ * The inverse of {@link retainedAttempt}, for a head commit opened with `resume`
76
+ * (`HeadCommitOptions.resume`): the attempt an earlier cycle recorded, as a {@link StagedAttempt}
77
+ * that sends exactly what that cycle sent, while `rev` — the revision the next attempt would
78
+ * request — equals the recorded one; `undefined` otherwise, and the attempt is built as usual.
79
+ * The tracker is over the handle's read cache, with a COPY of the recorded transforms (a fold
80
+ * resets it and folds what it holds, and the record stays the caller's) and pins of its own, since
81
+ * it stages nothing.
82
+ *
83
+ * The recorded attempt IS the attempt that may have landed: it can sit on a minority of its cohort,
84
+ * hidden from the refresh by a coordinator lagging that cohort, and storage accepts a retry of one
85
+ * `(action id, revision)` as the same write, so anything but these transforms under that pair forks
86
+ * the block on the machines that hold the first (docs/offline-sync.md §Identity across attempts).
87
+ * Three departures from how an attempt is otherwise built are deliberate:
88
+ * - **Keyed on `resume`, not on the retained attempt.** Within one cycle a retry at an unchanged
89
+ * revision reuses the head tracker and the minted log block ids, so it is byte-identical already,
90
+ * and keeps the re-judging of its base pins before each attempt (`Collection.headTrackerFor`).
91
+ * The recorded attempt is re-sent as it was, unjudged: a base that moved under it is judged by
92
+ * storage's own base guard, which refuses it on every machine whose base moved — the exception
93
+ * `Collection.completeOwnEntry`'s re-send of a retained attempt already takes.
94
+ * - **No invented baseline.** A head tracker over a collection with no committed revision starts
95
+ * from the invented baseline so the header, log block and root ride in the head's commit; the
96
+ * recorded transforms already carry those inserts.
97
+ * - **Only equality switches it on.** A refresh that moves the revision past `attempt.rev` adopted a
98
+ * rival's entry there, which proves the recorded attempt lost at that revision, and the write is
99
+ * rebuilt at the higher one. A revision BELOW it is not reachable inside one process (the held
100
+ * revision never lowers); a new handle after a restart that reaches one has read a view behind the
101
+ * attempt, and the ordinary build handles it as it would without `resume` — the recorded revision
102
+ * is not adopted to get there.
103
+ */
104
+ export declare function resumedAttempt(cache: CacheSource<IBlock>, attempt: InFlightAttempt | undefined, rev: number): StagedAttempt | undefined;
105
+ /** The refresh a write path runs between attempts — `Collection.updateInternal`, under the
106
+ * collection latch, with the write's action marked in flight so the refresh recognises the write's
107
+ * own log entry. `lastChance` says the budget ends with this round; `tailFloor` is the highest
108
+ * revision a responder confirmed is taken, for the tail read. */
109
+ export type Refresh = (report: RefreshReport, lastChance: boolean, tailFloor: number | undefined) => Promise<void>;
110
+ /**
111
+ * The retry accounting of one write's attempt cycle: how many consecutive attempts have been
112
+ * refused, what the responders confirmed, whether the refresh in between moved the collection, and
113
+ * who holds what the write has committed so far. One instance per write; the write path drives it
114
+ * in order — {@link beforeAttempt}, then either {@link recordRefusal} followed by
115
+ * {@link refreshUntilSettled}, or {@link recordCommit}.
116
+ */
117
+ export declare class AttemptCycle {
118
+ private readonly collectionId;
119
+ private readonly instanceTag;
120
+ private readonly maxAttempts;
121
+ private readonly maxStalledAttempts;
122
+ private readonly backoff;
123
+ private readonly deadlineMs;
124
+ private readonly signal;
125
+ private readonly rand;
126
+ private readonly startedAt;
127
+ private consecutiveFailures;
128
+ private lastReason;
129
+ private lastStaleAt;
130
+ private lastFailureConfirmedStaleAt;
131
+ private confirmedLosses;
132
+ private consecutiveStalls;
133
+ private previousRequestedRev;
134
+ /** Who holds what the write has committed so far. Stays `undefined` while nothing has been
135
+ * committed, which is also the answer when no attempt runs at all — a write with nothing staged
136
+ * writes nothing, and there is no durability to fabricate for it. Refused attempts never
137
+ * contribute: a refused attempt left nothing behind, so the answer is the committing one's. A
138
+ * write that commits more than once folds them with `mergeDurability`, whose scalar answer is
139
+ * the WEAKEST: one batch that only reached the writer makes the whole write only-on-the-writer,
140
+ * and reporting the last batch's class instead would show such a write as saved. */
141
+ durability: WriteDurability | undefined;
142
+ constructor(collectionId: CollectionId, instanceTag: string, options?: SyncOptions);
143
+ /** The aged retry priority for the next attempt, from the consecutive-failure count: a write
144
+ * that keeps losing concurrent races out-ranks fresh (priority-0) rivals in the cluster's
145
+ * `resolveRace` (fairness-only, capped at `MaxPriority`). A first attempt is priority 0, so the
146
+ * common pend is unchanged. */
147
+ priority(): number;
148
+ /**
149
+ * The checks that run before an attempt is built: the abort signal, the wall-clock deadline, and
150
+ * the stall check. The deadline comes before the stall check deliberately: it is the documented
151
+ * outer bound, so a write that is both past it and stalled reports the deadline.
152
+ *
153
+ * The stall check asks: can the attempt about to run possibly differ from the one that just
154
+ * failed? Only when BOTH of these hold is the answer provably no:
155
+ *
156
+ * - `requestedRev` is at or below one a responder CONFIRMED is taken. A producer sets `staleAt`
157
+ * only after reading that revision as durably held by someone else out of its own storage,
158
+ * revisions are one per-collection counter that every commit touches, and a confirmed
159
+ * revision never becomes un-taken (invalidation takes a NEW slot). So the request is already
160
+ * lost before it is sent.
161
+ * - The refresh in between moved the collection nowhere. `advanceContext` never lowers the
162
+ * held revision, so "nowhere" is exactly `requestedRev` unchanged since the last attempt. A
163
+ * refresh that moved forward WITHOUT clearing the confirmed number is a collection still
164
+ * climbing (it read a replica that lags the holder — the same partial catch-up
165
+ * `reportShortfall` exists to report), and its next attempt is a genuinely different request
166
+ * that may yet win.
167
+ *
168
+ * This is NOT a second answer to "is this failure retryable?" — `isConflictFailure` remains the
169
+ * sole rule for that, untouched. It only ever stops a loop that rule had already decided to
170
+ * continue.
171
+ *
172
+ * @param requestedRev the revision the attempt would request (`Collection.getNextRev`).
173
+ * @param heldRev the revision the collection holds, for the stall report.
174
+ * @throws AbortError, {@link SyncRetryExhaustedError} (deadline), {@link SyncRevisionStalledError}. */
175
+ beforeAttempt(requestedRev: number, heldRev: number | undefined): void;
176
+ /**
177
+ * Account for a refused attempt. The three refusals a retry can never get past are thrown by
178
+ * name, with nothing on the collection touched (the attempt ran on its own tracker), so the
179
+ * staged actions are still staged for a later write: an expiry, because the next attempt's
180
+ * expiration comes from the same clock; a promise shortfall, because every coordinator of the
181
+ * cohort meets the same silent members (only a pend answers this way, so nothing of the attempt
182
+ * was stored); a validity rejection, because the next attempt sends the same content to the same
183
+ * checks. Everything else is a stale failure counted against the no-progress budget, so a
184
+ * transactor that persistently rejects can no longer hold the collection latch forever.
185
+ *
186
+ * NOTE: an expiry refusing a commit SWEEP (`NetworkTransactor.commitTailThenSweep`) arrives after
187
+ * the log tail was stored, and no refresh follows this throw, so that attempt's log entry stays
188
+ * behind with none of its data — the state the budget-exhausted exit leaves too. Needs a sweep
189
+ * cohort whose clocks disagree while the tail's agree; tracked with the other leftover-entry
190
+ * exits in tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
191
+ *
192
+ * NOTE: the budget also bounds the legitimate `pending`-wait case (retrying the same action while
193
+ * another commit is in flight), which used to retry indefinitely. Default 10 attempts ≈ 21s of
194
+ * exponential backoff. If a high-contention workload legitimately needs to wait longer for a
195
+ * pending commit to clear, raise maxAttempts for that caller.
196
+ *
197
+ * NOTE: no refresh follows the LAST budgeted attempt, so if that attempt's log tail landed nobody
198
+ * finds out: the caller gets plain exhaustion over a log that holds an entry for this write. The
199
+ * write is still never reported saved, which is the rule; what is lost is the more specific name
200
+ * (TornActionError). The leftover entry itself is tracked in
201
+ * tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
202
+ *
203
+ * @throws TransactionExpiredError, PromiseShortfallError, ValidityRejectedError, SyncRetryExhaustedError */
204
+ recordRefusal(refusal: WriteFailure): void;
205
+ /** Account for a commit — by an attempt, or by a refresh that finished the write's own entry,
206
+ * which is a commit too and is reported and counted exactly like one (see {@link durability}).
207
+ * Forward progress: the no-progress budget and the stall evidence start over. */
208
+ recordCommit(durability: WriteDurability): void;
209
+ /**
210
+ * Back off, refresh, and keep refreshing while the refresh reports that this write's own
211
+ * half-landed action could not be finished YET. The write path must not fall through to a new
212
+ * attempt in that state: the action's log entry is already durable, and as soon as a refresh
213
+ * adopts a newer revision a new attempt appends a SECOND entry under the same action id — the
214
+ * duplicate `Collection.consumeOwnEntry` exists to prevent. (At an unchanged revision the rebuild
215
+ * is byte-identical — see `Collection.logAppendBlockIds` — so what is at stake is the second
216
+ * entry, not two versions of one tail block.) Each round is a failure against the same
217
+ * no-progress budget as a refused attempt, and the round that would spend the last of it is told
218
+ * so (`lastChance`), so it settles a half-landed write instead of asking for another round and
219
+ * the error that escapes says whether the write can still land. (A deadline cannot be foreseen
220
+ * the same way; a write given up on it escapes unsettled, as `final: false`.)
221
+ *
222
+ * The backoff before each round grows exponentially from the base delay up to the cap, with
223
+ * proportional random jitter so a herd of clients that lost the same race does not re-collide on
224
+ * the next tick (see utility/backoff.ts) — except once this write has lost to committed rivals
225
+ * often enough that a member holds the next slot for it ({@link retryBackoffMs}). The abortable
226
+ * sleep lets an aborted write reject promptly instead of finishing the sleep. A refresh that
227
+ * follows NO refused attempt — the one `Collection.commitHead` opens its cycle with — sleeps not
228
+ * at all: there is no race to space out.
229
+ * NOTE: the `missing`/`reason` conflict paths pay this backoff too (they used to retry with zero
230
+ * delay); that is what stops the persistent-`reason` hot spin. If a high-contention workload ever
231
+ * shows this base delay as recovery latency, lower baseBackoffMs for that caller rather than
232
+ * reintroducing the zero-delay retry.
233
+ *
234
+ * The highest revision a responder confirmed is taken rides out as the floor of the refresh's
235
+ * tail read, so a machine that has not caught up to it is not the last one asked (see
236
+ * `Collection.updateInternal`).
237
+ *
238
+ * @returns whether the refresh FINISHED the write's own log entry (`RefreshReport.ownEntryFinished`)
239
+ * — the write is saved and the entry consumed, whether or not the refresh learned who holds it.
240
+ * @throws TornActionError with any reason but an unsettled `completion-refused`, and that one too
241
+ * once the budget or the deadline is spent; whatever else the refresh throws. */
242
+ refreshUntilSettled(refresh: Refresh): Promise<boolean>;
243
+ private pastDeadline;
244
+ }
245
+ //# sourceMappingURL=write-attempts.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"write-attempts.d.ts","sourceRoot":"","sources":["../../../src/collection/write-attempts.ts"],"names":[],"mappings":"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"}