@optimystic/db-core 1.22.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.
- package/README.md +8 -4
- package/dist/src/collection/action.d.ts +7 -4
- package/dist/src/collection/action.d.ts.map +1 -1
- package/dist/src/collection/action.js +13 -5
- package/dist/src/collection/action.js.map +1 -1
- package/dist/src/collection/collection.d.ts +134 -46
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +207 -70
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/collection/struct.d.ts +38 -8
- package/dist/src/collection/struct.d.ts.map +1 -1
- package/dist/src/collection/struct.js.map +1 -1
- package/dist/src/collection/write-attempts.d.ts +138 -34
- package/dist/src/collection/write-attempts.d.ts.map +1 -1
- package/dist/src/collection/write-attempts.js +168 -101
- package/dist/src/collection/write-attempts.js.map +1 -1
- package/dist/src/collections/diary/diary.d.ts.map +1 -1
- package/dist/src/collections/diary/diary.js +5 -1
- package/dist/src/collections/diary/diary.js.map +1 -1
- package/dist/src/collections/tree/tree.d.ts +15 -9
- package/dist/src/collections/tree/tree.d.ts.map +1 -1
- package/dist/src/collections/tree/tree.js +6 -4
- package/dist/src/collections/tree/tree.js.map +1 -1
- package/dist/src/hlc/clock-store.d.ts +63 -0
- package/dist/src/hlc/clock-store.d.ts.map +1 -0
- package/dist/src/hlc/clock-store.js +49 -0
- package/dist/src/hlc/clock-store.js.map +1 -0
- package/dist/src/hlc/clock.d.ts +64 -0
- package/dist/src/hlc/clock.d.ts.map +1 -0
- package/dist/src/hlc/clock.js +171 -0
- package/dist/src/hlc/clock.js.map +1 -0
- package/dist/src/hlc/hlc.d.ts +38 -0
- package/dist/src/hlc/hlc.d.ts.map +1 -0
- package/dist/src/hlc/hlc.js +41 -0
- package/dist/src/hlc/hlc.js.map +1 -0
- package/dist/src/hlc/index.d.ts +5 -0
- package/dist/src/hlc/index.d.ts.map +1 -0
- package/dist/src/hlc/index.js +5 -0
- package/dist/src/hlc/index.js.map +1 -0
- package/dist/src/hlc/skew.d.ts +35 -0
- package/dist/src/hlc/skew.d.ts.map +1 -0
- package/dist/src/hlc/skew.js +35 -0
- package/dist/src/hlc/skew.js.map +1 -0
- package/dist/src/index.d.ts +2 -0
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +2 -0
- package/dist/src/index.js.map +1 -1
- package/dist/src/lane/index.d.ts +2 -0
- package/dist/src/lane/index.d.ts.map +1 -0
- package/dist/src/lane/index.js +2 -0
- package/dist/src/lane/index.js.map +1 -0
- package/dist/src/lane/lane.d.ts +46 -0
- package/dist/src/lane/lane.d.ts.map +1 -0
- package/dist/src/lane/lane.js +26 -0
- package/dist/src/lane/lane.js.map +1 -0
- package/dist/src/log/log.d.ts +50 -22
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +21 -13
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/log/struct.d.ts +61 -1
- package/dist/src/log/struct.d.ts.map +1 -1
- package/dist/src/log/struct.js +24 -0
- package/dist/src/log/struct.js.map +1 -1
- package/dist/src/network/i-repo.d.ts +10 -0
- package/dist/src/network/i-repo.d.ts.map +1 -1
- package/dist/src/network/stale-failure.d.ts +20 -7
- package/dist/src/network/stale-failure.d.ts.map +1 -1
- package/dist/src/network/stale-failure.js +29 -7
- package/dist/src/network/stale-failure.js.map +1 -1
- package/dist/src/network/struct.d.ts +35 -0
- package/dist/src/network/struct.d.ts.map +1 -1
- package/dist/src/network/struct.js.map +1 -1
- package/dist/src/offline/entry.d.ts +14 -0
- package/dist/src/offline/entry.d.ts.map +1 -1
- package/dist/src/offline/entry.js +2 -0
- package/dist/src/offline/entry.js.map +1 -1
- package/dist/src/offline/journal.d.ts +10 -0
- package/dist/src/offline/journal.d.ts.map +1 -1
- package/dist/src/offline/queue.d.ts +10 -0
- package/dist/src/offline/queue.d.ts.map +1 -1
- package/dist/src/offline/queue.js +29 -3
- package/dist/src/offline/queue.js.map +1 -1
- package/dist/src/offline/status.d.ts +7 -0
- package/dist/src/offline/status.d.ts.map +1 -1
- package/dist/src/offline/status.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +9 -1
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +6 -1
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/actions-engine.d.ts +3 -0
- package/dist/src/transaction/actions-engine.d.ts.map +1 -1
- package/dist/src/transaction/actions-engine.js +3 -0
- package/dist/src/transaction/actions-engine.js.map +1 -1
- package/dist/src/transaction/coordinator.d.ts +10 -5
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +197 -48
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/dist/src/transaction/entry-commit.d.ts +45 -10
- package/dist/src/transaction/entry-commit.d.ts.map +1 -1
- package/dist/src/transaction/entry-commit.js +20 -7
- package/dist/src/transaction/entry-commit.js.map +1 -1
- package/dist/src/transaction/errors.d.ts +69 -1
- package/dist/src/transaction/errors.d.ts.map +1 -1
- package/dist/src/transaction/errors.js +70 -1
- package/dist/src/transaction/errors.js.map +1 -1
- package/dist/src/transaction/index.d.ts +1 -1
- package/dist/src/transaction/index.d.ts.map +1 -1
- package/dist/src/transaction/index.js +1 -1
- package/dist/src/transaction/index.js.map +1 -1
- package/dist/src/transaction/session.d.ts.map +1 -1
- package/dist/src/transaction/session.js +18 -5
- package/dist/src/transaction/session.js.map +1 -1
- package/dist/src/transaction/transaction.d.ts +74 -15
- package/dist/src/transaction/transaction.d.ts.map +1 -1
- package/dist/src/transaction/transaction.js +35 -15
- package/dist/src/transaction/transaction.js.map +1 -1
- package/dist/src/transaction/validator.d.ts +25 -4
- package/dist/src/transaction/validator.d.ts.map +1 -1
- package/dist/src/transaction/validator.js +45 -5
- package/dist/src/transaction/validator.js.map +1 -1
- package/dist/src/transactor/block-floors.d.ts +12 -1
- package/dist/src/transactor/block-floors.d.ts.map +1 -1
- package/dist/src/transactor/block-floors.js +14 -1
- package/dist/src/transactor/block-floors.js.map +1 -1
- package/dist/src/transactor/network-transactor.d.ts +8 -0
- package/dist/src/transactor/network-transactor.d.ts.map +1 -1
- package/dist/src/transactor/network-transactor.js +8 -4
- package/dist/src/transactor/network-transactor.js.map +1 -1
- package/dist/src/transactor/transactor-source.d.ts +11 -0
- package/dist/src/transactor/transactor-source.d.ts.map +1 -1
- package/dist/src/transactor/transactor-source.js +5 -1
- package/dist/src/transactor/transactor-source.js.map +1 -1
- package/dist/src/transactor/transactor.d.ts +8 -0
- package/dist/src/transactor/transactor.d.ts.map +1 -1
- package/dist/src/transform/cache-source.d.ts +7 -0
- package/dist/src/transform/cache-source.d.ts.map +1 -1
- package/dist/src/transform/cache-source.js +14 -18
- package/dist/src/transform/cache-source.js.map +1 -1
- package/package.json +1 -1
- package/src/collection/action.ts +13 -5
- package/src/collection/collection.ts +250 -76
- package/src/collection/struct.ts +38 -8
- package/src/collection/write-attempts.ts +213 -109
- package/src/collections/diary/diary.ts +5 -1
- package/src/collections/tree/tree.ts +18 -11
- package/src/hlc/clock-store.ts +68 -0
- package/src/hlc/clock.ts +196 -0
- package/src/hlc/hlc.ts +56 -0
- package/src/hlc/index.ts +4 -0
- package/src/hlc/skew.ts +55 -0
- package/src/index.ts +2 -0
- package/src/lane/index.ts +1 -0
- package/src/lane/lane.ts +54 -0
- package/src/log/log.ts +341 -310
- package/src/log/struct.ts +62 -1
- package/src/network/i-repo.ts +11 -1
- package/src/network/stale-failure.ts +31 -7
- package/src/network/struct.ts +805 -770
- package/src/offline/entry.ts +16 -0
- package/src/offline/journal.ts +10 -0
- package/src/offline/queue.ts +38 -4
- package/src/offline/status.ts +7 -0
- package/src/testing/test-transactor.ts +1065 -1053
- package/src/transaction/actions-engine.ts +3 -0
- package/src/transaction/coordinator.ts +229 -54
- package/src/transaction/entry-commit.ts +56 -14
- package/src/transaction/errors.ts +60 -0
- package/src/transaction/index.ts +1 -1
- package/src/transaction/session.ts +18 -5
- package/src/transaction/transaction.ts +90 -17
- package/src/transaction/validator.ts +46 -5
- package/src/transactor/block-floors.ts +15 -1
- package/src/transactor/network-transactor.ts +15 -4
- package/src/transactor/transactor-source.ts +15 -1
- package/src/transactor/transactor.ts +9 -0
- package/src/transform/cache-source.ts +15 -17
package/src/network/struct.ts
CHANGED
|
@@ -1,770 +1,805 @@
|
|
|
1
|
-
import type { CollectionId, BlockId, IBlock, ActionId, Transform, Transforms } from "../index.js";
|
|
2
|
-
import type { ActionContext, ActionRev } from "../collection/action.js";
|
|
3
|
-
import type { Transaction, ValidityRejection } from "../transaction/transaction.js";
|
|
4
|
-
import type { DisputeResolutionProof } from "../log/struct.js";
|
|
5
|
-
import type {
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
* '
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
/**
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
/**
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
*
|
|
87
|
-
* (
|
|
88
|
-
*
|
|
89
|
-
*
|
|
90
|
-
*
|
|
91
|
-
* in
|
|
92
|
-
*
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
* `
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
* The
|
|
109
|
-
*
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
121
|
-
*
|
|
122
|
-
*
|
|
123
|
-
*
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
};
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
/**
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
*
|
|
143
|
-
*
|
|
144
|
-
*
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
*
|
|
148
|
-
*
|
|
149
|
-
*
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
export type
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
*
|
|
165
|
-
*
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
*
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
*
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
* (`
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
*
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
/**
|
|
213
|
-
*
|
|
214
|
-
*
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
*
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
*
|
|
241
|
-
*
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
/**
|
|
254
|
-
*
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
*
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
*/
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
/**
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
};
|
|
322
|
-
|
|
323
|
-
/**
|
|
324
|
-
* Why a
|
|
325
|
-
*
|
|
326
|
-
*
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
*/
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
*/
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
*
|
|
387
|
-
*
|
|
388
|
-
*
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
*/
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
};
|
|
407
|
-
|
|
408
|
-
/**
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
*
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
*
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
*
|
|
469
|
-
*
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
*
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
/**
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
*
|
|
509
|
-
*
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
};
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
/**
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
*
|
|
544
|
-
*
|
|
545
|
-
*
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
*
|
|
561
|
-
*
|
|
562
|
-
*
|
|
563
|
-
*
|
|
564
|
-
*
|
|
565
|
-
*
|
|
566
|
-
*
|
|
567
|
-
*
|
|
568
|
-
*
|
|
569
|
-
*
|
|
570
|
-
*
|
|
571
|
-
*
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
*
|
|
575
|
-
*
|
|
576
|
-
*
|
|
577
|
-
* (`
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
*
|
|
581
|
-
*
|
|
582
|
-
*
|
|
583
|
-
*
|
|
584
|
-
*
|
|
585
|
-
*
|
|
586
|
-
*
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
*
|
|
590
|
-
*
|
|
591
|
-
*
|
|
592
|
-
*
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
*
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
*
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
*
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
/**
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
*
|
|
666
|
-
*
|
|
667
|
-
*
|
|
668
|
-
*
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
*
|
|
672
|
-
*
|
|
673
|
-
*
|
|
674
|
-
*
|
|
675
|
-
*
|
|
676
|
-
*
|
|
677
|
-
*
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
*
|
|
681
|
-
*
|
|
682
|
-
*
|
|
683
|
-
|
|
684
|
-
/**
|
|
685
|
-
*
|
|
686
|
-
*
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
*
|
|
690
|
-
*
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
/**
|
|
699
|
-
*
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
/**
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
*
|
|
753
|
-
*
|
|
754
|
-
*
|
|
755
|
-
*
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
)
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
export type
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
1
|
+
import type { CollectionId, BlockId, IBlock, ActionId, Transform, Transforms } from "../index.js";
|
|
2
|
+
import type { ActionContext, ActionRev } from "../collection/action.js";
|
|
3
|
+
import type { Transaction, ValidityRejection } from "../transaction/transaction.js";
|
|
4
|
+
import type { DisputeResolutionProof } from "../log/struct.js";
|
|
5
|
+
import type { Hlc } from "../hlc/hlc.js";
|
|
6
|
+
import type { Lane } from "../lane/lane.js";
|
|
7
|
+
import type { PeerId } from "./types.js";
|
|
8
|
+
|
|
9
|
+
export type ActionBlocks = {
|
|
10
|
+
blockIds: BlockId[];
|
|
11
|
+
actionId: ActionId;
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
export type ActionTransforms = {
|
|
15
|
+
actionId: ActionId;
|
|
16
|
+
rev?: number;
|
|
17
|
+
transforms: Transforms;
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
export type ActionTransform = {
|
|
21
|
+
actionId: ActionId;
|
|
22
|
+
rev?: number;
|
|
23
|
+
transform: Transform;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
export type ActionPending = {
|
|
27
|
+
blockId: BlockId;
|
|
28
|
+
actionId: ActionId;
|
|
29
|
+
transform?: Transform;
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
export type PendRequest = ActionTransforms & {
|
|
33
|
+
/** What to do if there are any pending actions.
|
|
34
|
+
* 'c' is continue normally,
|
|
35
|
+
* 'f' is fail, returning the pending ActionIds,
|
|
36
|
+
* 'r' is return, which fails but returns the pending ActionIds and their transforms */
|
|
37
|
+
policy: 'c' | 'f' | 'r';
|
|
38
|
+
/**
|
|
39
|
+
* Present only on a validated multi-collection pend (`TransactionCoordinator.pendCollection`
|
|
40
|
+
* under its default `pendValidation: 'transaction'`): the transaction to re-execute plus the
|
|
41
|
+
* hash of ALL operations across all blocks it must produce. Absent on every pend that carries
|
|
42
|
+
* bare transforms and is therefore not re-checkable — the single-collection `Collection.sync`
|
|
43
|
+
* path, and a coordinator built with `pendValidation: 'none'` (the Quereus adapter's legacy
|
|
44
|
+
* multi-tree commit, which has no statements to re-execute) — see
|
|
45
|
+
* `ClusterConsensusConfig.unvalidatablePendPolicy` for what a validating receiver does with
|
|
46
|
+
* that shape. ONE optional pair, deliberately: "transaction
|
|
47
|
+
* without its hash" (or the reverse) was a state the old two independent optional fields
|
|
48
|
+
* permitted and no producer ever created — and a receiver whose guard required both could be
|
|
49
|
+
* talked out of validating by a sender that omitted one.
|
|
50
|
+
*/
|
|
51
|
+
validation?: {
|
|
52
|
+
/** The full transaction for replay/validation. */
|
|
53
|
+
transaction: Transaction;
|
|
54
|
+
/** Hash of ALL operations across all blocks the re-executed transaction must produce. */
|
|
55
|
+
operationsHash: string;
|
|
56
|
+
};
|
|
57
|
+
/** For multi-collection transactions: supercluster nominees for consensus */
|
|
58
|
+
superclusterNominees?: PeerId[];
|
|
59
|
+
/**
|
|
60
|
+
* The HLC of the write this pend carries (`LogEntry.hlc`, `Transaction.hlc`): the same value the
|
|
61
|
+
* log entry inside `transforms` carries, put here so a storage node observes the HLC of every
|
|
62
|
+
* write it stores without parsing log blocks out of transforms (docs/crdt-sync.md §Migration
|
|
63
|
+
* Path, Stage 1). The writer always sets it (`TransactorSource.transact`,
|
|
64
|
+
* `TransactionCoordinator.pendRequestFor`); optional on the wire because an older writer sends
|
|
65
|
+
* none, and because the re-send of a retained attempt has none at hand. Observational: a member
|
|
66
|
+
* reads it into its clock and never judges the pend by it. Omitted rather than `undefined`, for
|
|
67
|
+
* the same preimage reason as {@link baseRevs}.
|
|
68
|
+
*/
|
|
69
|
+
hlc?: Hlc;
|
|
70
|
+
/**
|
|
71
|
+
* The lane of the write this pend carries (`ActionEntry.lane`, `Transaction.lane`): whether its
|
|
72
|
+
* conflicts with concurrent writes are the quorum's to decide (`serializable`) or may be merged
|
|
73
|
+
* later under the collection's declaration (`convergent`) — see `Lane` in
|
|
74
|
+
* `packages/db-core/src/lane/lane.ts`. The same value the log entry inside `transforms` carries,
|
|
75
|
+
* put here so a storage node reads it without parsing log blocks. Every writer of this build sets
|
|
76
|
+
* it (`TransactorSource.transact`, `TransactionCoordinator.pendRequestFor`); optional on the wire
|
|
77
|
+
* because an older writer sends none. A reader treats absence as "not stated", never as a lane.
|
|
78
|
+
* Observational: nothing judges the pend by it — a validating member checks the lane the
|
|
79
|
+
* transaction inside {@link validation} claims (`TransactionValidator.validate`) — and the
|
|
80
|
+
* coordinator's solo log lines report it. Omitted rather than `undefined`, for the same preimage
|
|
81
|
+
* reason as {@link baseRevs}.
|
|
82
|
+
*/
|
|
83
|
+
lane?: Lane;
|
|
84
|
+
/**
|
|
85
|
+
* Aged, advisory retry priority for a pend that carries no transaction (default 0 when absent).
|
|
86
|
+
* A validated multi-collection pend instead carries priority on the transaction inside
|
|
87
|
+
* {@link PendRequest.validation} ({@link Transaction.priority}); this top-level field is the
|
|
88
|
+
* carrier for every pend without one — a `Collection.sync` pend, and an unvalidated
|
|
89
|
+
* coordinator pend (`pendValidation: 'none'`). A cluster member reads whichever is present as the first
|
|
90
|
+
* `resolveRace` tiebreak. FAIRNESS-ONLY: it rides inside the signed cluster `message` (so it is
|
|
91
|
+
* integrity-protected in transit) but MUST NOT affect the operations hash, stale-read checks, or
|
|
92
|
+
* validity — a stale pend is still rejected regardless of priority.
|
|
93
|
+
*/
|
|
94
|
+
priority?: number;
|
|
95
|
+
/**
|
|
96
|
+
* Per block, the committed revision of the base the author's update operations were computed
|
|
97
|
+
* against (`Tracker.stagedBaseRevs`). Present for a block whose transform is update-only and
|
|
98
|
+
* whose base the author knows; never for an inserted or deleted block (base-independent), and
|
|
99
|
+
* absent for a block the author did not read through a source that reports revisions. Omitted
|
|
100
|
+
* entirely when empty (`baseRevsField`): the request is hashed verbatim into every cohort
|
|
101
|
+
* signature preimage, so a pend that declares nothing must serialize exactly as it did before
|
|
102
|
+
* the field existed. Action-wide here; the transactor narrows it to each per-coordinator batch's
|
|
103
|
+
* own block ids at send time, exactly as it narrows {@link CommitRequest.blockDigests}.
|
|
104
|
+
*
|
|
105
|
+
* Storage keeps it beside the pending record (`BlockMetadata.pendingBases` in db-p2p), so every
|
|
106
|
+
* later step that applies the record can refuse to apply it to a different version of the block
|
|
107
|
+
* — including the read-driven promotion in `StorageRepo.get`, which has no commit message to
|
|
108
|
+
* consult. The commit's own `blockDigests[id].baseRev` is now the fallback for a record whose
|
|
109
|
+
* pend named no base, not the primary check.
|
|
110
|
+
*/
|
|
111
|
+
baseRevs?: BlockBaseRevs;
|
|
112
|
+
/**
|
|
113
|
+
* The writer's word that this pend, together with the other pends sent with it in one request
|
|
114
|
+
* (`IRepo.pendMany`), is the action's whole reservation — every block the action will commit is in
|
|
115
|
+
* that one request — and that the action's commit goes as one request to the coordinator this pend
|
|
116
|
+
* goes to. Only then may a coordinator hold back the pend record's final delivery to the other
|
|
117
|
+
* members and send it inside the commit's first request (`ClusterCoordinator.mayDeferPendDelivery`
|
|
118
|
+
* in db-p2p): a member that refuses any of the record's pends late refuses that one commit record,
|
|
119
|
+
* before anything of the action is durable. A send that pends in several requests before committing
|
|
120
|
+
* any — several collections one request each under one action id, or one collection split across
|
|
121
|
+
* coordinators — must never carry it: one request's late refusal would surface while another
|
|
122
|
+
* request's commit may already have landed, tearing the action.
|
|
123
|
+
*
|
|
124
|
+
* Set by `TransactorSource.transact`, and by `TransactionCoordinator` for a transaction of exactly
|
|
125
|
+
* one collection or for every request of a `pendMany` (whose commit goes through `commitMany`);
|
|
126
|
+
* `NetworkTransactor.pend` keeps it only on a request carrying the whole pend.
|
|
127
|
+
* `Collection.completeOwnEntry` re-sends one participant of a half-landed multi-collection action
|
|
128
|
+
* through `transact`, and carries it too: that re-send pends and commits its one collection on its
|
|
129
|
+
* own, so its late refusal stops only its own commit, as an on-time refusal would.
|
|
130
|
+
* Omitted rather than `false`, for the same preimage reason as {@link baseRevs}; a coordinator on
|
|
131
|
+
* an older build ignores it, and then delivers at once as it always did.
|
|
132
|
+
*/
|
|
133
|
+
soleReservation?: true;
|
|
134
|
+
/**
|
|
135
|
+
* The writer's word that this write must not be committed by a lone node that knows it is not
|
|
136
|
+
* alone (`SyncOptions.refuseSoloCommit`). A coordinator whose cohort for the write is only itself
|
|
137
|
+
* refuses the pend — before reserving anything — when it knows of cohort members it could not
|
|
138
|
+
* place in the cohort, is still waiting to hear from a configured bootstrap peer, or could not
|
|
139
|
+
* route the write to itself, answering with a {@link ShortfallFailure} whose
|
|
140
|
+
* {@link PromiseShortfall.soloRefused} names which (`CoordinatorRepo.pendSolo` in db-p2p). A
|
|
141
|
+
* coordinator that is genuinely alone ignores it and pends as it always did, and so does every
|
|
142
|
+
* coordinator whose cohort has more than one member.
|
|
143
|
+
*
|
|
144
|
+
* Carried by every send of the write's attempt cycle, the re-send a refresh makes to finish a torn
|
|
145
|
+
* attempt included (`Collection.completeOwnEntry`). Every per-coordinator rebuild of the request
|
|
146
|
+
* keeps it (`pendRequestForBatch` in `NetworkTransactor`), since a batch that dropped it would
|
|
147
|
+
* lose the protection for that coordinator's share. Omitted rather than `false`, for the same
|
|
148
|
+
* preimage reason as {@link baseRevs}: a write that does not set it serializes exactly as before.
|
|
149
|
+
* A coordinator on an older build ignores it and commits alone at `local`; in a group of mixed
|
|
150
|
+
* versions the offline queue's reachability gate is then the only protection.
|
|
151
|
+
*/
|
|
152
|
+
refuseSolo?: true;
|
|
153
|
+
};
|
|
154
|
+
|
|
155
|
+
export type BlockActionStatus = ActionBlocks & {
|
|
156
|
+
statuses: ('pending' | 'committed' | 'checkpointed' | 'aborted' | 'committed-invalidated')[];
|
|
157
|
+
};
|
|
158
|
+
|
|
159
|
+
/** How widely a successful write is known to be held at the moment it was acknowledged. */
|
|
160
|
+
export type DurabilityQuorum =
|
|
161
|
+
/** Every member of the resolved cohort confirmed it holds the revision. */
|
|
162
|
+
| 'full'
|
|
163
|
+
/** A strict majority confirmed — the acknowledgement bar — but at least one member did not.
|
|
164
|
+
* Also the class of a torn action whose cohort confirmed everything it was asked for
|
|
165
|
+
* (`withTornBlocks` clamps `full` down to this; `torn` then names the blocks, and `unconfirmed`
|
|
166
|
+
* may be empty). */
|
|
167
|
+
| 'majority'
|
|
168
|
+
/** The cohort resolved, and it is this node alone. Nobody else holds the revision yet. When this
|
|
169
|
+
* node knows of other members of the cohort that it could not reach (`IKeyNetwork.absentCohortMembers`),
|
|
170
|
+
* they are named in `unconfirmed` and counted in `cohort`: the write is owed to them. With none
|
|
171
|
+
* named, it is a correct, complete one-machine write. */
|
|
172
|
+
| 'local'
|
|
173
|
+
/** The cohort did NOT resolve: the lookup threw, or named nobody, or named a single peer that
|
|
174
|
+
* is not this node. The write is on this node's storage and the network was never consulted.
|
|
175
|
+
* Deliberately NOT `local`: a write that lands where its cohort resolved to is in the right
|
|
176
|
+
* place, whereas this is a write whose correct destination is unknown. */
|
|
177
|
+
| 'unrouted';
|
|
178
|
+
|
|
179
|
+
/** What the answering layer knows about who holds a successful write. Each layer refines it:
|
|
180
|
+
* `StorageRepo` answers for itself alone, `CoordinatorRepo` answers for the cohort the write ran
|
|
181
|
+
* on, and `NetworkTransactor` merges the per-coordinator answers into one action-level answer.
|
|
182
|
+
* Never a policy input — read it to DISPLAY or to REPAIR, never to decide acceptance.
|
|
183
|
+
*
|
|
184
|
+
* The only "this write is completely saved" test is `isFullyDurable` (`network/durability.ts`);
|
|
185
|
+
* do not compare `quorum` by hand, because a `full` cohort report can still sit on an action that
|
|
186
|
+
* abandoned blocks (`torn`). */
|
|
187
|
+
export type WriteDurability = {
|
|
188
|
+
readonly quorum: DurabilityQuorum;
|
|
189
|
+
/** Cohort members confirmed to hold the write, including this node when it holds it.
|
|
190
|
+
* For a commit this means "reported that its storage durably holds the revision"; for a pend
|
|
191
|
+
* it means "accepted the pending record". The two are NOT comparable — a pend confers no
|
|
192
|
+
* storage durability (see the note in `CoordinatorRepo.pendThroughCluster`). */
|
|
193
|
+
readonly confirmed: number;
|
|
194
|
+
/** Size of the cohort the write ran on. Zero exactly when `quorum` is 'unrouted'. For `local`
|
|
195
|
+
* it is one plus the known members the write ran without, so `local` does not imply 1. */
|
|
196
|
+
readonly cohort: number;
|
|
197
|
+
/** Cohort members that did not confirm, by peer-id string. Empty when `quorum` is 'full'.
|
|
198
|
+
* ABSENT (not empty) when the answering layer could not name the cohort — an empty array
|
|
199
|
+
* here means "named the cohort, nobody is missing". On a `local` write these are the members
|
|
200
|
+
* this node knows of but could not reach when it wrote alone. */
|
|
201
|
+
readonly unconfirmed?: readonly string[];
|
|
202
|
+
/** The cohort the write ran on, by peer-id string. Absent where the answering layer has no
|
|
203
|
+
* cohort view at all (a bare `StorageRepo` verdict). */
|
|
204
|
+
readonly cohortPeerIds?: readonly string[];
|
|
205
|
+
/** Peer-id string of the node whose under-replication ledger recorded this write's missing
|
|
206
|
+
* copies — the one node that will fire `BlockDurabilityReachedEvent` for these blocks when they
|
|
207
|
+
* reach full replication. Set only below `full`, and only when every non-torn block's shortfall
|
|
208
|
+
* was recorded. Absent: no node is tracking the shortfall (nothing to push from the coordinator,
|
|
209
|
+
* a ledger fault, no ledger, a producer that predates the field), so no full-replication event
|
|
210
|
+
* should be expected. Per cohort answer: each `otherCohorts` entry carries its own. */
|
|
211
|
+
readonly recordedBy?: string;
|
|
212
|
+
/** Present only on an action-level result assembled from MORE THAN ONE distinct coordinator
|
|
213
|
+
* answer: the other answers. Identical answers are collapsed (`mergeDurability`), so a healthy
|
|
214
|
+
* single-cohort commit has none; one cohort answering differently for two batches appears
|
|
215
|
+
* twice. The scalar fields above always describe the WEAKEST answer, so a consumer that reads
|
|
216
|
+
* only them is reading the binding constraint and is never over-optimistic. */
|
|
217
|
+
readonly otherCohorts?: readonly WriteDurability[];
|
|
218
|
+
/** Blocks this action wrote that are NOT committed — a torn sweep abandoned and cancelled them
|
|
219
|
+
* (`NetworkTransactor.cancelAbandonedSweepBlocks`). Action-level commit results only.
|
|
220
|
+
* These blocks NEVER heal by replication: their transform is gone, and only the writer
|
|
221
|
+
* re-driving the action puts them back. */
|
|
222
|
+
readonly torn?: readonly BlockId[];
|
|
223
|
+
/** Action-level: every block this write committed, with the revision it committed at — what a
|
|
224
|
+
* host holds to match full-replication events (`BlockDurabilityReachedEvent`, keyed by block and
|
|
225
|
+
* revision) back to this write. Set by the db-core layer that issued the commit
|
|
226
|
+
* (`withBlockRevs`), never by a coordinator and never on the wire. Excludes `torn` blocks: they
|
|
227
|
+
* hold nothing. Merging two reports keeps, per block, the HIGHER revision — a block written at r
|
|
228
|
+
* and again at r+1 by one write is covered by an event at r+1 or later. A `Record` rather than a
|
|
229
|
+
* `Map` so the type stays plain JSON. */
|
|
230
|
+
readonly blockRevs?: Readonly<Record<BlockId, number>>;
|
|
231
|
+
};
|
|
232
|
+
|
|
233
|
+
export type PendSuccess = {
|
|
234
|
+
success: true;
|
|
235
|
+
/** List of already pending actions that were found on blocks touched by this pend */
|
|
236
|
+
pending: ActionPending[];
|
|
237
|
+
/** The affected blocks */
|
|
238
|
+
blockIds: BlockId[];
|
|
239
|
+
/** Who accepted the pending record. REQUIRED, not optional: an absent field would read as plain
|
|
240
|
+
* success, which is exactly the ambiguity this field exists to remove (a solo write, a write
|
|
241
|
+
* whose cohort never resolved, and a quorum write all used to answer `{ success: true }`). */
|
|
242
|
+
durability: WriteDurability;
|
|
243
|
+
};
|
|
244
|
+
|
|
245
|
+
export type StaleFailure = {
|
|
246
|
+
success: false;
|
|
247
|
+
/** The reason for the failure */
|
|
248
|
+
reason?: string;
|
|
249
|
+
/** List of actions that have already been committed and are newer than our known revision */
|
|
250
|
+
missing?: ActionTransforms[];
|
|
251
|
+
/** List of actions that are pending on the blocks touched by this pend */
|
|
252
|
+
pending?: ActionPending[];
|
|
253
|
+
/**
|
|
254
|
+
* Explicit retryability. True when this failure is an optimistic-concurrency loss — the
|
|
255
|
+
* requested revision was taken, or a rival pend holds the blocks — so a re-read, rebase and
|
|
256
|
+
* re-pend can win. Set it only when the producer genuinely classified the failure; leave it
|
|
257
|
+
* absent otherwise, and consumers fall back to inferring from `missing`/`pending`.
|
|
258
|
+
* Read it through `isConflictFailure` rather than testing it directly.
|
|
259
|
+
*/
|
|
260
|
+
conflict?: boolean;
|
|
261
|
+
/**
|
|
262
|
+
* The block that already occupies (or is past) the requested revision, and the revision the
|
|
263
|
+
* responder holds for it.
|
|
264
|
+
*
|
|
265
|
+
* CONFIRMED-ONLY: set this only when the producer read the revision out of its own storage.
|
|
266
|
+
* A producer that merely suspects staleness — or that learned of it from another peer's
|
|
267
|
+
* free-form reject text — must leave it absent. Absent means "no confirmed number", never
|
|
268
|
+
* "not stale".
|
|
269
|
+
*
|
|
270
|
+
* DIAGNOSTIC, NOT A RETRYABILITY SIGNAL: `conflict` (read via `isConflictFailure`) remains the
|
|
271
|
+
* single source of truth for "can a re-read and re-pend win?". Never branch retry decisions on
|
|
272
|
+
* the presence of this field.
|
|
273
|
+
*/
|
|
274
|
+
staleAt?: { blockId: BlockId; rev: number };
|
|
275
|
+
/** Never set on a lost race — an expiry is its own failure shape, {@link ExpiredFailure}. */
|
|
276
|
+
expired?: never;
|
|
277
|
+
/** Never set on a lost race — a cohort too few of whose members answered is its own failure
|
|
278
|
+
* shape, {@link ShortfallFailure}. */
|
|
279
|
+
shortfall?: never;
|
|
280
|
+
/** Never set on a lost race — a write judged invalid is its own failure shape,
|
|
281
|
+
* {@link RejectedFailure}. */
|
|
282
|
+
rejected?: never;
|
|
283
|
+
};
|
|
284
|
+
|
|
285
|
+
/**
|
|
286
|
+
* Why a cohort refused a write as expired: by each refusing member's own clock, the transaction's
|
|
287
|
+
* `expiration` had already passed when the record reached it. Plain data, so it crosses the JSON repo
|
|
288
|
+
* protocol intact. `TransactionExpiredError` is built from it, wherever it is raised.
|
|
289
|
+
*/
|
|
290
|
+
export type TransactionExpiry = {
|
|
291
|
+
/** The transaction's expiration (unix ms), as the writer's transactor set it from its own clock. */
|
|
292
|
+
expiration: number;
|
|
293
|
+
/** Per refusing cohort member (peer-id string), the clock reading (unix ms) it signed when it
|
|
294
|
+
* judged the record expired (`Signature.expiredAt`). Never empty. */
|
|
295
|
+
memberClocks: Record<string, number>;
|
|
296
|
+
/** The coordinating node's clock (unix ms) when it concluded the refusal. */
|
|
297
|
+
coordinatorClock: number;
|
|
298
|
+
};
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* The cohort refused the write because the transaction had already EXPIRED by the members' clocks —
|
|
302
|
+
* a clock disagreement between the writer and the cohort, not a lost race and not a judgement of the
|
|
303
|
+
* write. Never retryable: every retry carries an expiration set by the same clock, and is refused the
|
|
304
|
+
* same way until a clock is corrected. A sibling of {@link StaleFailure} rather than a field on it,
|
|
305
|
+
* because "lost to a newer revision" is exactly what this is not; the fields it can never carry are
|
|
306
|
+
* typed `never`, so a consumer reads `reason`, `missing` or `staleAt` off either shape unnarrowed.
|
|
307
|
+
* Tell the two apart with `isExpiryFailure`, never by reading `reason`.
|
|
308
|
+
*/
|
|
309
|
+
export type ExpiredFailure = {
|
|
310
|
+
success: false;
|
|
311
|
+
/** The coordinator's description of the refusal, for a log line. Never branch on it. */
|
|
312
|
+
reason?: string;
|
|
313
|
+
/** Always false: an expiry is never a conflict a re-read can win. */
|
|
314
|
+
conflict: false;
|
|
315
|
+
expired: TransactionExpiry;
|
|
316
|
+
missing?: never;
|
|
317
|
+
pending?: never;
|
|
318
|
+
staleAt?: never;
|
|
319
|
+
shortfall?: never;
|
|
320
|
+
rejected?: never;
|
|
321
|
+
};
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* Why a cohort's promise round fell short with no member refusing it as a lost race or a held block,
|
|
325
|
+
* and too few rejecting it for a rejection: too few members answered. Plain data, so it crosses the
|
|
326
|
+
* JSON repo protocol intact. `PromiseShortfallError` is built from it, wherever it is raised.
|
|
327
|
+
*/
|
|
328
|
+
export type PromiseShortfall = {
|
|
329
|
+
/** Approve votes the round received. */
|
|
330
|
+
approvals: number;
|
|
331
|
+
/** Reject votes the round received — fewer than would make the round a rejection. */
|
|
332
|
+
rejections: number;
|
|
333
|
+
/** How many members the cohort the round ran on has. */
|
|
334
|
+
peerCount: number;
|
|
335
|
+
/** The approvals the round needed: `ceil(peerCount × superMajorityThreshold)`. */
|
|
336
|
+
needed: number;
|
|
337
|
+
/** Peer-id strings of the cohort members that cast no promise vote at all. */
|
|
338
|
+
silentPeers: string[];
|
|
339
|
+
/**
|
|
340
|
+
* Set only when no consensus round ran: a coordinator whose cohort for the write was only itself
|
|
341
|
+
* refused to write alone, because the write asked it to (`PendRequest.refuseSolo`). The other
|
|
342
|
+
* fields then describe the cohort the coordinator expected rather than one it asked: one approval
|
|
343
|
+
* (its own), no rejections, the members it knows of and could not reach as `silentPeers`, and the
|
|
344
|
+
* bar a cohort of that size would set. Absent on a shortfall a consensus round produced, so a log
|
|
345
|
+
* or an application can tell "refused to write alone" from "a round heard too few".
|
|
346
|
+
*/
|
|
347
|
+
soloRefused?: SoloRefusalReason;
|
|
348
|
+
};
|
|
349
|
+
|
|
350
|
+
/**
|
|
351
|
+
* Why a lone coordinator refused a write that asked not to be committed alone
|
|
352
|
+
* (`PendRequest.refuseSolo`, `CommitRequest.refuseSolo`):
|
|
353
|
+
* - `absent-members`: its cohort for the write was only itself, and it knows of cohort members it
|
|
354
|
+
* could not place in that cohort (`IKeyNetwork.absentCohortMembers`);
|
|
355
|
+
* - `awaiting-bootstrap`: its cohort was only itself and it is still waiting to hear from a peer it
|
|
356
|
+
* was configured to join through (`IKeyNetwork.awaitingBootstrapContact`);
|
|
357
|
+
* - `unrouted`: the cohort lookup failed, named nobody, or named one peer that is not this node.
|
|
358
|
+
*/
|
|
359
|
+
export type SoloRefusalReason = 'absent-members' | 'awaiting-bootstrap' | 'unrouted';
|
|
360
|
+
|
|
361
|
+
/**
|
|
362
|
+
* The cohort refused the pend because too few of its members ANSWERED the promise round for it to
|
|
363
|
+
* reach its bar — silence, not a judgement of the write and not a lost race. Not retryable by a write
|
|
364
|
+
* path: every coordinator of that cohort meets the same silent members, so a re-read and re-pend fails
|
|
365
|
+
* the same way until they come back. A sibling of {@link StaleFailure} and {@link ExpiredFailure},
|
|
366
|
+
* with the fields it can never carry typed `never`, so a consumer reads `reason`, `missing` or
|
|
367
|
+
* `staleAt` off any of them unnarrowed. Tell it apart with `isShortfallFailure`, never by reading
|
|
368
|
+
* `reason`. A pend answer only: a commit that falls short is still thrown (see
|
|
369
|
+
* `CoordinatorRepo.commit`).
|
|
370
|
+
*/
|
|
371
|
+
export type ShortfallFailure = {
|
|
372
|
+
success: false;
|
|
373
|
+
/** The coordinator's description of the refusal, for a log line. Never branch on it. */
|
|
374
|
+
reason?: string;
|
|
375
|
+
/** Always false: silence is not a conflict a re-read can win. */
|
|
376
|
+
conflict: false;
|
|
377
|
+
shortfall: PromiseShortfall;
|
|
378
|
+
missing?: never;
|
|
379
|
+
pending?: never;
|
|
380
|
+
staleAt?: never;
|
|
381
|
+
expired?: never;
|
|
382
|
+
rejected?: never;
|
|
383
|
+
};
|
|
384
|
+
|
|
385
|
+
/**
|
|
386
|
+
* One refusal behind a {@link TransactionInvalidity}: a cohort member's validity-marked reject vote
|
|
387
|
+
* (`Signature`'s `validity`), or the validity verdict of the coordinating node's own storage-tier check
|
|
388
|
+
* (`StorageRepo.pend`, for a cohort of one, where no vote is cast).
|
|
389
|
+
*/
|
|
390
|
+
export type ValidityRefusal = ValidityRejection & {
|
|
391
|
+
/** The refusing member's peer-id string. Absent for a refusal a node's storage made without a vote. */
|
|
392
|
+
peerId?: string;
|
|
393
|
+
/** The refuser's description, free-form, for a log line. Never branch on it. */
|
|
394
|
+
reason?: string;
|
|
395
|
+
};
|
|
396
|
+
|
|
397
|
+
/**
|
|
398
|
+
* Why a write was refused as INVALID: the members that sank it judged the transaction itself wrong
|
|
399
|
+
* (see {@link ValidityRejection} for which refusals qualify), and no refusal of any other kind sank it
|
|
400
|
+
* beside them, bar expiry votes. Plain data, so it crosses the JSON repo protocol intact.
|
|
401
|
+
* `ValidityRejectedError` is built from it, wherever it is raised.
|
|
402
|
+
*/
|
|
403
|
+
export type TransactionInvalidity = {
|
|
404
|
+
/** Every validity refusal that sank the write. Never empty. */
|
|
405
|
+
refusals: ValidityRefusal[];
|
|
406
|
+
};
|
|
407
|
+
|
|
408
|
+
/**
|
|
409
|
+
* The cohort refused the write because the members that sank it judged it INVALID — the transaction
|
|
410
|
+
* failed its re-execution, its operations hash, its stamp or its client signature. Never retryable:
|
|
411
|
+
* re-sending the same content to the same checks is refused the same way. A sibling of
|
|
412
|
+
* {@link StaleFailure}, {@link ExpiredFailure} and {@link ShortfallFailure}, with the fields it can
|
|
413
|
+
* never carry typed `never`, so a consumer reads `reason`, `missing` or `staleAt` off any of them
|
|
414
|
+
* unnarrowed. Tell it apart with `isRejectedFailure`, never by reading `reason`.
|
|
415
|
+
*
|
|
416
|
+
* A pend answer only, and only when nothing else could explain the rejection: a reject vote with no
|
|
417
|
+
* validity marker beside the marked ones (a stale revision, a member on an older build) leaves the
|
|
418
|
+
* rejection unclassified, and a revision loss the coordinator's own storage confirms is returned as
|
|
419
|
+
* the {@link StaleFailure} it is, since the writer's rebase sends different content.
|
|
420
|
+
*/
|
|
421
|
+
export type RejectedFailure = {
|
|
422
|
+
success: false;
|
|
423
|
+
/** The coordinator's description of the refusal, for a log line. Never branch on it. */
|
|
424
|
+
reason?: string;
|
|
425
|
+
/** Always false: a verdict on the content is not a conflict a re-read can win. */
|
|
426
|
+
conflict: false;
|
|
427
|
+
rejected: TransactionInvalidity;
|
|
428
|
+
missing?: never;
|
|
429
|
+
pending?: never;
|
|
430
|
+
staleAt?: never;
|
|
431
|
+
expired?: never;
|
|
432
|
+
shortfall?: never;
|
|
433
|
+
};
|
|
434
|
+
|
|
435
|
+
/** Every way a pend or a commit can be refused with an answer rather than a throw. */
|
|
436
|
+
export type WriteFailure = StaleFailure | ExpiredFailure | ShortfallFailure | RejectedFailure;
|
|
437
|
+
|
|
438
|
+
export type PendResult = PendSuccess | WriteFailure;
|
|
439
|
+
|
|
440
|
+
/** What one block will materialize to at the committing revision, declared by the client that
|
|
441
|
+
* authored the transforms. */
|
|
442
|
+
export type BlockContentDigest = {
|
|
443
|
+
/** base64url SHA-256 of canonicalJson(block) - see canonicalBlockHash. */
|
|
444
|
+
digest: string;
|
|
445
|
+
/** Committed revision of the base the digest was computed from. ABSENT when the block's
|
|
446
|
+
* transform carries an insert, which makes the result base-independent and therefore
|
|
447
|
+
* checkable by every member regardless of how far behind it is. */
|
|
448
|
+
baseRev?: number;
|
|
449
|
+
};
|
|
450
|
+
|
|
451
|
+
/** Per-block content declarations riding on a commit. Optional per id: a block the client cannot
|
|
452
|
+
* digest without a network read is simply omitted, and falls back to corroboration downstream. */
|
|
453
|
+
export type BlockContentDigests = Record<BlockId, BlockContentDigest>;
|
|
454
|
+
|
|
455
|
+
/** Per block, the committed revision its update operations were computed against — the shape
|
|
456
|
+
* `Tracker.stagedBaseRevs` produces and {@link PendRequest.baseRevs} carries. Optional per id: an
|
|
457
|
+
* inserted or deleted block is base-independent and never named; a block updated without a known
|
|
458
|
+
* base is simply omitted. */
|
|
459
|
+
export type BlockBaseRevs = Record<BlockId, number>;
|
|
460
|
+
|
|
461
|
+
export type CommitRequest = ActionBlocks & {
|
|
462
|
+
/** The header block of the collection, present only when this commit creates the collection
|
|
463
|
+
* (the header is a fresh insert). Collection-identifying metadata, not an ordering signal —
|
|
464
|
+
* the header commits after the tail, like any other touched block.
|
|
465
|
+
* Consumed by dispute reporting (`dispute-service.ts`) as a fallback to name the collection. */
|
|
466
|
+
headerId?: BlockId;
|
|
467
|
+
/** The tail block of the log. Unconditionally the first block committed on every member, whether
|
|
468
|
+
* it travels alone or with the action's other blocks — the ordering `Collection.bootstrapContext`
|
|
469
|
+
* relies on. */
|
|
470
|
+
tailId: BlockId;
|
|
471
|
+
/** The new revision for the committed action */
|
|
472
|
+
rev: number;
|
|
473
|
+
/** Per-block content declarations for the committing action — see {@link BlockContentDigests}.
|
|
474
|
+
* Rides inside the consensus message, so the generic cluster message hash folds it into every
|
|
475
|
+
* cohort signature with no change to the hash helpers. Action-wide here; the transactor narrows
|
|
476
|
+
* it to each per-coordinator batch's own block ids before sending (`RepoCommitRequest`). */
|
|
477
|
+
// NOTE: accepted tradeoff — this field stays OPTIONAL even though an omitted declaration has a real
|
|
478
|
+
// cost: `StorageRepo.persistProofIfContentMatches` retains no `BlockCommitProof` for a block that
|
|
479
|
+
// declared no digest (`commit:proof-undeclared`), and a block with no proof is refused by any
|
|
480
|
+
// receiver running the default `requirePushCertificate: true` (`push:reject-uncertified
|
|
481
|
+
// reason=no-proof`). Such a block stays readable and still repairs by corroboration while two or
|
|
482
|
+
// more holders remain, but it can never GAIN a
|
|
483
|
+
// holder by push — so spread-on-churn and cohort-growth healing silently stop maintaining its
|
|
484
|
+
// replication factor. Kept optional anyway because: (a) required-but-nullable is the strongest form
|
|
485
|
+
// available and still permits `undefined`, so it does not make the bad state unrepresentable, only
|
|
486
|
+
// typed out loud; (b) some commits legitimately declare nothing — delete-only/tombstone commits
|
|
487
|
+
// materialize no content, and a member on a lagging base abstains; (c) measured migration cost of
|
|
488
|
+
// required-but-nullable here and on `RepoCommitRequest` is >=194 `tsc --noEmit` errors across >=39
|
|
489
|
+
// files (39/9 in db-core, 155/30 in db-p2p, quereus-plugin-optimystic unmeasured), nearly all fixed
|
|
490
|
+
// by literally writing `undefined`. Revisit if undeclared commits ever become common enough to show
|
|
491
|
+
// up as replication-factor decay.
|
|
492
|
+
blockDigests?: BlockContentDigests;
|
|
493
|
+
/**
|
|
494
|
+
* {@link PendRequest.refuseSolo}, on the commit. A coordinator whose cohort for the commit is only
|
|
495
|
+
* itself refuses it on the same rule, before minting a proof or applying anything, with a
|
|
496
|
+
* conflict-shaped refusal (`SOLO_COMMIT_REFUSED_REASON` in db-p2p), since a commit cannot answer
|
|
497
|
+
* with a shortfall. That is reached when the pend ran on a real cohort and the partner dropped
|
|
498
|
+
* before the commit: the writer cancels and retries, and the retry's pend meets the pend-side
|
|
499
|
+
* refusal. Carried through every per-coordinator rebuild of the commit (`repoCommitRequest` in
|
|
500
|
+
* `NetworkTransactor`); omitted rather than `false` for the preimage reason
|
|
501
|
+
* {@link blockDigests} is.
|
|
502
|
+
*/
|
|
503
|
+
refuseSolo?: true;
|
|
504
|
+
/**
|
|
505
|
+
* {@link PendRequest.lane}, on the commit, so a coordinator handling the commit reads the write's
|
|
506
|
+
* lane with no memory of the pend. Carried through every per-coordinator rebuild of the commit
|
|
507
|
+
* (`repoCommitRequest` in `NetworkTransactor`); optional on the wire for an older writer, and
|
|
508
|
+
* absence is "not stated". Omitted rather than `undefined`, for the preimage reason
|
|
509
|
+
* {@link blockDigests} is.
|
|
510
|
+
*/
|
|
511
|
+
lane?: Lane;
|
|
512
|
+
};
|
|
513
|
+
|
|
514
|
+
/**
|
|
515
|
+
* Originates a compensating invalidation through the same critical-cluster consensus as any
|
|
516
|
+
* transaction: it takes a revision slot and serializes against concurrent commits. Each member
|
|
517
|
+
* applies it deterministically — verifying {@link resolution} as an invalidation certificate, then
|
|
518
|
+
* writing the per-block compensating revisions and appending the durable invalidation log entry.
|
|
519
|
+
*
|
|
520
|
+
* Carries everything a member needs to apply the reversal without trusting the originator: the
|
|
521
|
+
* target action, the blocks it wrote, the owning collection's log, and the signed proof.
|
|
522
|
+
*/
|
|
523
|
+
export type InvalidateRequest = {
|
|
524
|
+
/** actionId of the committed action being reversed. */
|
|
525
|
+
invalidatedActionId: ActionId;
|
|
526
|
+
/** rev of the invalidated entry — pins which block revisions to roll back. */
|
|
527
|
+
invalidatedRev: number;
|
|
528
|
+
/** Blocks the invalidated action wrote (its commit's blockIds). */
|
|
529
|
+
blockIds: BlockId[];
|
|
530
|
+
/** The collection (log) the invalidated action belongs to — where the compensating entry lands. */
|
|
531
|
+
collectionId: CollectionId;
|
|
532
|
+
/** The invalidation certificate (challenger-wins + signed 2/3 decisive arbitrator votes). */
|
|
533
|
+
resolution: DisputeResolutionProof;
|
|
534
|
+
};
|
|
535
|
+
|
|
536
|
+
export type CommitResult = CommitSuccess | WriteFailure;
|
|
537
|
+
|
|
538
|
+
export type CommitSuccess = {
|
|
539
|
+
success: true;
|
|
540
|
+
/** If present, the identified collection acts as the coordinator for the multi-collection transaction */
|
|
541
|
+
coordinatorId?: CollectionId;
|
|
542
|
+
/** Who holds the committed revision. REQUIRED for the same reason as {@link PendSuccess.durability}:
|
|
543
|
+
* a quorum commit, a solo commit, a commit whose cohort lookup failed, and a torn multi-block
|
|
544
|
+
* commit all answered `{ success: true }` before this field existed, and a writer could not tell
|
|
545
|
+
* them apart (GitHub #19). Test it through `isFullyDurable`, never by comparing `quorum`. */
|
|
546
|
+
durability: WriteDurability;
|
|
547
|
+
};
|
|
548
|
+
|
|
549
|
+
export type BlockActionState = {
|
|
550
|
+
/** The latest action that has been committed */
|
|
551
|
+
latest?: ActionRev;
|
|
552
|
+
/** If present, the specified actions are pending */
|
|
553
|
+
pendings?: ActionId[];
|
|
554
|
+
};
|
|
555
|
+
|
|
556
|
+
export type BlockGets = {
|
|
557
|
+
blockIds: BlockId[];
|
|
558
|
+
context?: ActionContext; // Latest if this is omitted
|
|
559
|
+
/** Per block, the lowest revision the ASKER can accept for it — its floor. Omit a block that
|
|
560
|
+
* has none; omit the field entirely when no block does.
|
|
561
|
+
*
|
|
562
|
+
* A floor is knowledge only the asker holds: a collection that walked the log entry
|
|
563
|
+
* "action A, committed at revision r, changed block X" knows a read of X at a context at or
|
|
564
|
+
* above `r` must come back materialized at `r` or later, while the repo answering may honestly
|
|
565
|
+
* believe its older copy is current. `TransactorSource.tryGet` fills this from the collection's
|
|
566
|
+
* `BlockFloors`, and a refresh that follows a refused write puts the revision the refusal
|
|
567
|
+
* confirmed on its read of the log tail (`Collection.readLogEnds`). `NetworkTransactor.get`
|
|
568
|
+
* treats an answer under a block's floor as NOT answered, so it earns the same second-chance
|
|
569
|
+
* round against a different coordinator that `unavailable` and `unconfirmedAheadRev` earn.
|
|
570
|
+
*
|
|
571
|
+
* On the wire, per batch: `NetworkTransactor.get` forwards to each downstream `IRepo.get` the
|
|
572
|
+
* floors of that batch's blocks alone, and leaves the field off a batch none of whose blocks has
|
|
573
|
+
* one. A peer that predates the field ignores it and answers as it always did, which is safe
|
|
574
|
+
* because the reader-side check is what enforces the floor, on the merged answer, either way
|
|
575
|
+
* (`TransactorSource` / `BlockFloorCheck`) — so an `ITransactor` that ignores the field
|
|
576
|
+
* (`TestTransactor`, the reference peer's) stays correct too. A coordinator that does read it
|
|
577
|
+
* (`CoordinatorRepo.get`) consults its cohort at once for a present block whose local revision
|
|
578
|
+
* is below the floor, whatever its read-repair window says, and remembers the floor it consulted
|
|
579
|
+
* under so a floor no machine can meet costs one consult per window; it never refuses on a floor.
|
|
580
|
+
*
|
|
581
|
+
* NOTE: the retry `NetworkTransactor.get` runs is per BATCH, not per block, so one below-floor
|
|
582
|
+
* block re-asks every block that shared its coordinator. Costs nothing today — `tryGet` asks
|
|
583
|
+
* for one block per request, and the one batched floored read is a refresh's header-and-tail
|
|
584
|
+
* read, whose other block is the header the refresh needed from the second machine anyway —
|
|
585
|
+
* but a read source that batches unrelated blocks would pay it. Split the retry payload down to
|
|
586
|
+
* the failing block ids then. */
|
|
587
|
+
floors?: Record<BlockId, number>;
|
|
588
|
+
/** Per block, what the ASKER itself holds of it: its committed latest `(rev, actionId)`, or `null`
|
|
589
|
+
* when it holds no committed revision. A block the asker could not read locally is left out, and
|
|
590
|
+
* the field is left off when none could be read.
|
|
591
|
+
*
|
|
592
|
+
* It exists because a coordinator's cohort consult asks every other cohort member "what do you hold
|
|
593
|
+
* for this block?", and when the asker is itself a member that question has just been answered in
|
|
594
|
+
* its own request. A coordinator that reads the field uses the statement as that member's answer
|
|
595
|
+
* instead of asking it over the network (`CoordinatorRepo.get`), but only where doing so loses
|
|
596
|
+
* nothing: the statement is "nothing", or a revision at or below the coordinator's own (at an equal
|
|
597
|
+
* revision, only under the same action). A statement ahead of the coordinator is consulted as
|
|
598
|
+
* before, because acquiring or judging that revision needs the member's archive and commit proof,
|
|
599
|
+
* which a stated revision carries neither of. A statement can only lower what the coordinator
|
|
600
|
+
* concludes about being behind; it never makes it adopt anything.
|
|
601
|
+
*
|
|
602
|
+
* The statement names no peer. WHO is stating is the identity of the connection the request
|
|
603
|
+
* arrived on (`MessageOptions.asker`), so a request cannot speak for another member. Filled below
|
|
604
|
+
* the transactor, by the reader's remote-repo decorator (`stateHoldingsOnReads` in
|
|
605
|
+
* `packages/db-p2p/src/repo/stated-holdings.ts`), and only on a read sent to another machine. A
|
|
606
|
+
* peer that predates the field ignores it and consults as before. */
|
|
607
|
+
askerHolds?: Record<BlockId, ActionRev | null>;
|
|
608
|
+
/** Ask the answering repo whether each block's CURRENT content was built from this committed
|
|
609
|
+
* action at this revision; it answers per block in {@link GetBlockResult.lineage}. On the wire,
|
|
610
|
+
* unlike `floors`. A repo that predates the field leaves `lineage` absent, which every consumer
|
|
611
|
+
* reads as `unknown`. Asked only by a writer deciding whether its own superseded write is saved
|
|
612
|
+
* (`ITransactor.getLineage`); an ordinary read never sets it. */
|
|
613
|
+
lineageOf?: ActionRev;
|
|
614
|
+
/** The asker does not want this read to start the read-repair consult that the lazy window alone
|
|
615
|
+
* would run BEHIND the read: a held block whose window has expired (or that the lazy mode's
|
|
616
|
+
* `readRepairSampleRate` picked for a re-check) is answered from the answering repo's own copy and
|
|
617
|
+
* no cohort consult is started for it. An effort hint, never a correctness one —
|
|
618
|
+
* the doubt an earlier consult recorded still stamps `unconfirmedAheadRev`, and the window's
|
|
619
|
+
* freshness stamp is untouched, so the next read without the flag consults as before.
|
|
620
|
+
*
|
|
621
|
+
* It never skips a consult whose answer the read depends on: a block missing locally (the absence
|
|
622
|
+
* verdict), a held block whose read carries a floor above it ({@link floors}), and every consult
|
|
623
|
+
* under `'paranoid'` read-repair still run and still block. Whole-read, so `NetworkTransactor.get`
|
|
624
|
+
* forwards it on every batch: a remote coordinator also skips its own background consult. A peer
|
|
625
|
+
* that predates the field ignores it and consults as before. Meant for the node's watch tick,
|
|
626
|
+
* through `Collection.readCommittedTails`, which reads every watched tail on a timer. Distinct from
|
|
627
|
+
* `skipClusterFetch`, the sync protocol's guard, which skips every consult and never flags. */
|
|
628
|
+
skipWindowConsult?: true;
|
|
629
|
+
};
|
|
630
|
+
|
|
631
|
+
/**
|
|
632
|
+
* Whether a block's current content was BUILT FROM a given committed `(actionId, rev)` — the
|
|
633
|
+
* write's transform is part of what the block holds now, even though later actions have since
|
|
634
|
+
* taken later revisions.
|
|
635
|
+
*
|
|
636
|
+
* - `contains` — it was. Holding that exact revision as the latest counts.
|
|
637
|
+
* - `excludes` — it provably was not: another action holds that revision of the block, or the
|
|
638
|
+
* block's history spans that revision without it. Nothing can land the write there any more.
|
|
639
|
+
* - `behind` — the block has not reached that revision (or does not exist). The write is not
|
|
640
|
+
* there, and could only get there through one of its own pending records.
|
|
641
|
+
* - `unknown` — not established either way.
|
|
642
|
+
*
|
|
643
|
+
* One repo answers from its own records only ({@link GetBlockResult.lineage}); a transactor
|
|
644
|
+
* answers for the block's cohort ({@link ActionLineage}).
|
|
645
|
+
*/
|
|
646
|
+
export type BlockLineage = 'contains' | 'excludes' | 'behind' | 'unknown';
|
|
647
|
+
|
|
648
|
+
/** A cohort-level answer to "is this committed write part of what these blocks hold now?" — see
|
|
649
|
+
* `ITransactor.getLineage`. */
|
|
650
|
+
export type ActionLineage = {
|
|
651
|
+
/** One answer per requested block id, in request order. */
|
|
652
|
+
blocks: BlockLineage[];
|
|
653
|
+
/** Who holds the write, present exactly when EVERY block answered `contains`: the weakest
|
|
654
|
+
* block's cohort report, by the same rule a commit's durability is merged. */
|
|
655
|
+
durability?: WriteDurability;
|
|
656
|
+
};
|
|
657
|
+
|
|
658
|
+
/** Why a repo could not establish whether a block exists. Present ONLY when the repo
|
|
659
|
+
* knows its own answer is a guess; an absent field is an authoritative answer. */
|
|
660
|
+
export type BlockUnavailableReason =
|
|
661
|
+
/** Records for this block exist here but it cannot be reconstructed locally — a
|
|
662
|
+
* revision was received with no base to apply it to, or its history is truncated. */
|
|
663
|
+
| 'unmaterializable'
|
|
664
|
+
/** Nothing is held locally; PART of the cohort answered and part could not be asked.
|
|
665
|
+
* A silent peer could be the sole holder, so the absence is a guess — but other
|
|
666
|
+
* coordinators are reachable, so asking one of them can still settle it. Also the
|
|
667
|
+
* fallback when the consult could not run at all (the cohort lookup itself failed):
|
|
668
|
+
* a routing failure says nothing about how many cohort members were reachable. */
|
|
669
|
+
| 'peers-unreachable'
|
|
670
|
+
/** Nothing is held locally and NO cohort member outside the answering node could be
|
|
671
|
+
* asked at all. Distinct from `peers-unreachable` in exactly the way that matters to
|
|
672
|
+
* a caller: there is no better-connected coordinator to re-ask, so the answer will
|
|
673
|
+
* not improve until that node's connectivity does. Its local view is all there is.
|
|
674
|
+
* Also the answer of a node whose cohort view holds only itself while a peer it was
|
|
675
|
+
* configured to join through has never been heard from
|
|
676
|
+
* (`IKeyNetwork.awaitingBootstrapContact`): it knows of a machine outside itself and
|
|
677
|
+
* has not reached it. */
|
|
678
|
+
| 'cohort-unreachable'
|
|
679
|
+
/** Nothing is held locally, but a cohort peer positively CLAIMED a revision of this
|
|
680
|
+
* block, and the answering node could neither corroborate that claim to a quorum nor
|
|
681
|
+
* acquire the content. The block is known to exist somewhere; reporting it absent
|
|
682
|
+
* would be a lie regardless of whether anyone was silent. */
|
|
683
|
+
| 'claimed-elsewhere'
|
|
684
|
+
/** Nothing is held locally and the answering node had nobody to ask (its cohort view
|
|
685
|
+
* was empty, or only itself), but the read carried a floor for the block
|
|
686
|
+
* ({@link BlockGets.floors}): the asker walked a log entry committing a revision of it.
|
|
687
|
+
* The block is known to exist, from the asker's own evidence, so "never created" would
|
|
688
|
+
* contradict what the asker already knows. Unlike `cohort-unreachable` this is never
|
|
689
|
+
* "the local view is all there is": another machine may hold the block, and asking one
|
|
690
|
+
* is the remedy. */
|
|
691
|
+
| 'named-by-log';
|
|
692
|
+
|
|
693
|
+
export type GetBlockResult = {
|
|
694
|
+
/** The retrieved block - undefined if the block was deleted */
|
|
695
|
+
block?: IBlock;
|
|
696
|
+
/** The latest and pending states of the repo that retrieved the block */
|
|
697
|
+
state: BlockActionState;
|
|
698
|
+
/** The revision the returned `block` actually IS — the `(rev, actionId)` of the highest
|
|
699
|
+
* committed revision of THIS block at or below the caller's {@link BlockGets.context}`.rev`.
|
|
700
|
+
* Differs from `state.latest` only for a revision-pinned read of a block that has committed
|
|
701
|
+
* further since the pin; for an unpinned read the two agree.
|
|
702
|
+
*
|
|
703
|
+
* This — not `state.latest` — is what a read observed, so it is what a read dependency must
|
|
704
|
+
* record (recording `latest` would claim the reader saw content it never read, and the
|
|
705
|
+
* validator's stale-read check would wrongly pass), and it is the only correct label for the
|
|
706
|
+
* content when it is passed on (a block-repair archive, a replica push). `state.latest` keeps
|
|
707
|
+
* its own meaning: the newest revision the answering repo holds for the block.
|
|
708
|
+
*
|
|
709
|
+
* The revision and its action id are ONE field, deliberately: a site that must label content
|
|
710
|
+
* it is holding needs both, and two independently-optional fields could disagree — which is
|
|
711
|
+
* exactly the mislabel this exists to make unrepresentable (old bytes served under a newer
|
|
712
|
+
* revision's number and action id, which a receiver keyed by action id then writes over its
|
|
713
|
+
* own good copy; see `serveBlockArchive`).
|
|
714
|
+
*
|
|
715
|
+
* Optional: a producer that does not know what it materialized leaves it absent rather than
|
|
716
|
+
* guessing, and consumers fall back to `state.latest` (read dependencies record
|
|
717
|
+
* `state.latest?.rev ?? 0`; a labelling site refuses to label a pinned read). */
|
|
718
|
+
materialized?: ActionRev;
|
|
719
|
+
/** Set when this repo could not determine whether the block exists — its answer is a
|
|
720
|
+
* guess, not an authoritative absent. Every producer that omits it (including
|
|
721
|
+
* TestTransactor) keeps meaning "authoritative". */
|
|
722
|
+
unavailable?: BlockUnavailableReason;
|
|
723
|
+
/** Set when this repo served committed content it could NOT confirm is current: its
|
|
724
|
+
* freshness consult did not converge AND a cohort peer claimed a strictly higher
|
|
725
|
+
* revision than the one served, within the view the caller asked for (unpinned, or
|
|
726
|
+
* pinned at or above the claim). Carries that claimed revision. The claim did not
|
|
727
|
+
* drive a successful repair — it failed the read-repair corroboration quorum, or was
|
|
728
|
+
* corroborated but the content could not be acquired — so it is evidence of DOUBT,
|
|
729
|
+
* never a revision to adopt. Distinct from `unavailable`, which is about EXISTENCE:
|
|
730
|
+
* the content here is real, it may just be behind. Absent = confirmed, so every
|
|
731
|
+
* producer that omits it keeps its meaning. */
|
|
732
|
+
unconfirmedAheadRev?: number;
|
|
733
|
+
/** This repo's answer to {@link BlockGets.lineageOf}, from its OWN records only — no cohort
|
|
734
|
+
* view. Absent when the question was not asked, or the repo predates it. */
|
|
735
|
+
lineage?: BlockLineage;
|
|
736
|
+
};
|
|
737
|
+
|
|
738
|
+
/**
|
|
739
|
+
* Thrown by a block read when the responsible repo could not determine whether the
|
|
740
|
+
* block exists. Distinct from "the block is absent" (undefined) and from a transport
|
|
741
|
+
* failure — this node's data is genuinely indeterminate and the caller must not treat
|
|
742
|
+
* it as empty. Not a StaleFailure: `Collection.sync` does not retry it.
|
|
743
|
+
*/
|
|
744
|
+
export class BlockUnavailableError extends Error {
|
|
745
|
+
constructor(readonly blockId: BlockId, readonly reason: BlockUnavailableReason) {
|
|
746
|
+
super(`Block ${blockId} is unavailable (${reason}): the repo could not determine whether it exists`);
|
|
747
|
+
this.name = 'BlockUnavailableError';
|
|
748
|
+
}
|
|
749
|
+
}
|
|
750
|
+
|
|
751
|
+
/**
|
|
752
|
+
* Thrown by an unpinned ("give me latest") block read whose surviving answer carries
|
|
753
|
+
* {@link GetBlockResult.unconfirmedAheadRev}: every reachable coordinator served content
|
|
754
|
+
* it could not confirm is current, while a cohort peer claimed a strictly higher revision
|
|
755
|
+
* nothing could corroborate or refute. Sibling of {@link BlockUnavailableError} — that one
|
|
756
|
+
* is about EXISTENCE (blockless answer, could not find out), this one about CURRENCY (real
|
|
757
|
+
* content, possibly behind). Not a StaleFailure: `Collection.sync` does not retry it.
|
|
758
|
+
*/
|
|
759
|
+
export class BlockPossiblyStaleError extends Error {
|
|
760
|
+
constructor(readonly blockId: BlockId, readonly claimedRev: number) {
|
|
761
|
+
super(`Block ${blockId} may be stale: a cohort peer claimed rev ${claimedRev} that no reachable coordinator could confirm or refute`);
|
|
762
|
+
this.name = 'BlockPossiblyStaleError';
|
|
763
|
+
}
|
|
764
|
+
}
|
|
765
|
+
|
|
766
|
+
export type GetBlockResults = Record<BlockId, GetBlockResult>;
|
|
767
|
+
|
|
768
|
+
/**
|
|
769
|
+
* Result of validating a transaction in a PendRequest.
|
|
770
|
+
*/
|
|
771
|
+
export type PendValidationResult = {
|
|
772
|
+
/** Whether validation passed */
|
|
773
|
+
valid: boolean;
|
|
774
|
+
/** Reason for validation failure (if valid=false) */
|
|
775
|
+
reason?: string;
|
|
776
|
+
/** Set only on a failure that judges the transaction itself wrong; see {@link ValidityRejection}. */
|
|
777
|
+
validity?: ValidityRejection;
|
|
778
|
+
};
|
|
779
|
+
|
|
780
|
+
/**
|
|
781
|
+
* Hook for validating transactions in PendRequests.
|
|
782
|
+
*
|
|
783
|
+
* This hook is called by the storage layer when receiving a PendRequest
|
|
784
|
+
* that carries a `validation` payload (the transaction plus its operations
|
|
785
|
+
* hash). If validation fails — or the hook throws — the pend operation is
|
|
786
|
+
* rejected. What a hook-configured node does with a pend carrying NO
|
|
787
|
+
* `validation` payload is a policy decision
|
|
788
|
+
* (`StorageRepoOptions.unvalidatablePendPolicy` in db-p2p).
|
|
789
|
+
*
|
|
790
|
+
* If the hook is not provided, validation is skipped (storage-only nodes).
|
|
791
|
+
*/
|
|
792
|
+
export type PendValidationHook = (
|
|
793
|
+
transaction: Transaction,
|
|
794
|
+
operationsHash: string
|
|
795
|
+
) => Promise<PendValidationResult>;
|
|
796
|
+
|
|
797
|
+
// Backward compatibility aliases (deprecated - use Action* names)
|
|
798
|
+
/** @deprecated Use ActionBlocks instead */
|
|
799
|
+
export type TrxBlocks = ActionBlocks;
|
|
800
|
+
/** @deprecated Use ActionTransforms instead */
|
|
801
|
+
export type TrxTransforms = ActionTransforms;
|
|
802
|
+
/** @deprecated Use ActionTransform instead */
|
|
803
|
+
export type TrxTransform = ActionTransform;
|
|
804
|
+
/** @deprecated Use ActionPending instead */
|
|
805
|
+
export type TrxPending = ActionPending;
|