@optimystic/db-core 1.19.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 (171) hide show
  1. package/dist/src/cluster/structs.d.ts +41 -8
  2. package/dist/src/cluster/structs.d.ts.map +1 -1
  3. package/dist/src/cluster/structs.js +18 -7
  4. package/dist/src/cluster/structs.js.map +1 -1
  5. package/dist/src/collection/action.d.ts +29 -0
  6. package/dist/src/collection/action.d.ts.map +1 -1
  7. package/dist/src/collection/action.js +6 -0
  8. package/dist/src/collection/action.js.map +1 -1
  9. package/dist/src/collection/collection.d.ts +533 -120
  10. package/dist/src/collection/collection.d.ts.map +1 -1
  11. package/dist/src/collection/collection.js +974 -500
  12. package/dist/src/collection/collection.js.map +1 -1
  13. package/dist/src/collection/head-commit.d.ts +110 -0
  14. package/dist/src/collection/head-commit.d.ts.map +1 -0
  15. package/dist/src/collection/head-commit.js +65 -0
  16. package/dist/src/collection/head-commit.js.map +1 -0
  17. package/dist/src/collection/index.d.ts +2 -0
  18. package/dist/src/collection/index.d.ts.map +1 -1
  19. package/dist/src/collection/index.js +2 -0
  20. package/dist/src/collection/index.js.map +1 -1
  21. package/dist/src/collection/segments.d.ts +77 -0
  22. package/dist/src/collection/segments.d.ts.map +1 -0
  23. package/dist/src/collection/segments.js +110 -0
  24. package/dist/src/collection/segments.js.map +1 -0
  25. package/dist/src/collection/struct.d.ts +156 -1
  26. package/dist/src/collection/struct.d.ts.map +1 -1
  27. package/dist/src/collection/struct.js +70 -0
  28. package/dist/src/collection/struct.js.map +1 -1
  29. package/dist/src/collection/write-attempts.d.ts +245 -0
  30. package/dist/src/collection/write-attempts.d.ts.map +1 -0
  31. package/dist/src/collection/write-attempts.js +439 -0
  32. package/dist/src/collection/write-attempts.js.map +1 -0
  33. package/dist/src/collections/tree/struct.d.ts +100 -17
  34. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  35. package/dist/src/collections/tree/struct.js +38 -7
  36. package/dist/src/collections/tree/struct.js.map +1 -1
  37. package/dist/src/collections/tree/tree.d.ts +17 -5
  38. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  39. package/dist/src/collections/tree/tree.js +112 -26
  40. package/dist/src/collections/tree/tree.js.map +1 -1
  41. package/dist/src/index.d.ts +2 -0
  42. package/dist/src/index.d.ts.map +1 -1
  43. package/dist/src/index.js +2 -0
  44. package/dist/src/index.js.map +1 -1
  45. package/dist/src/network/i-repo.d.ts +3 -0
  46. package/dist/src/network/i-repo.d.ts.map +1 -1
  47. package/dist/src/network/index.d.ts +3 -0
  48. package/dist/src/network/index.d.ts.map +1 -1
  49. package/dist/src/network/index.js +3 -0
  50. package/dist/src/network/index.js.map +1 -1
  51. package/dist/src/network/promise-shortfall-error.d.ts +40 -0
  52. package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
  53. package/dist/src/network/promise-shortfall-error.js +67 -0
  54. package/dist/src/network/promise-shortfall-error.js.map +1 -0
  55. package/dist/src/network/refuse-solo.d.ts +8 -0
  56. package/dist/src/network/refuse-solo.d.ts.map +1 -0
  57. package/dist/src/network/refuse-solo.js +8 -0
  58. package/dist/src/network/refuse-solo.js.map +1 -0
  59. package/dist/src/network/stale-failure.d.ts +20 -3
  60. package/dist/src/network/stale-failure.d.ts.map +1 -1
  61. package/dist/src/network/stale-failure.js +24 -3
  62. package/dist/src/network/stale-failure.js.map +1 -1
  63. package/dist/src/network/struct.d.ts +148 -2
  64. package/dist/src/network/struct.d.ts.map +1 -1
  65. package/dist/src/network/struct.js.map +1 -1
  66. package/dist/src/network/validity-rejected-error.d.ts +28 -0
  67. package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
  68. package/dist/src/network/validity-rejected-error.js +51 -0
  69. package/dist/src/network/validity-rejected-error.js.map +1 -0
  70. package/dist/src/offline/entry.d.ts +72 -0
  71. package/dist/src/offline/entry.d.ts.map +1 -0
  72. package/dist/src/offline/entry.js +73 -0
  73. package/dist/src/offline/entry.js.map +1 -0
  74. package/dist/src/offline/index.d.ts +5 -0
  75. package/dist/src/offline/index.d.ts.map +1 -0
  76. package/dist/src/offline/index.js +5 -0
  77. package/dist/src/offline/index.js.map +1 -0
  78. package/dist/src/offline/journal.d.ts +61 -0
  79. package/dist/src/offline/journal.d.ts.map +1 -0
  80. package/dist/src/offline/journal.js +2 -0
  81. package/dist/src/offline/journal.js.map +1 -0
  82. package/dist/src/offline/queue.d.ts +484 -0
  83. package/dist/src/offline/queue.d.ts.map +1 -0
  84. package/dist/src/offline/queue.js +1236 -0
  85. package/dist/src/offline/queue.js.map +1 -0
  86. package/dist/src/offline/reachability.d.ts +25 -0
  87. package/dist/src/offline/reachability.d.ts.map +1 -0
  88. package/dist/src/offline/reachability.js +13 -0
  89. package/dist/src/offline/reachability.js.map +1 -0
  90. package/dist/src/offline/status.d.ts +148 -0
  91. package/dist/src/offline/status.d.ts.map +1 -0
  92. package/dist/src/offline/status.js +63 -0
  93. package/dist/src/offline/status.js.map +1 -0
  94. package/dist/src/offline/wake.d.ts +30 -0
  95. package/dist/src/offline/wake.d.ts.map +1 -0
  96. package/dist/src/offline/wake.js +68 -0
  97. package/dist/src/offline/wake.js.map +1 -0
  98. package/dist/src/testing/test-transactor.d.ts +29 -0
  99. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  100. package/dist/src/testing/test-transactor.js +50 -0
  101. package/dist/src/testing/test-transactor.js.map +1 -1
  102. package/dist/src/transaction/commit-failure-class.d.ts +103 -0
  103. package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
  104. package/dist/src/transaction/commit-failure-class.js +96 -0
  105. package/dist/src/transaction/commit-failure-class.js.map +1 -0
  106. package/dist/src/transaction/coordinator.d.ts +165 -41
  107. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  108. package/dist/src/transaction/coordinator.js +605 -300
  109. package/dist/src/transaction/coordinator.js.map +1 -1
  110. package/dist/src/transaction/entry-commit.d.ts +139 -0
  111. package/dist/src/transaction/entry-commit.d.ts.map +1 -0
  112. package/dist/src/transaction/entry-commit.js +199 -0
  113. package/dist/src/transaction/entry-commit.js.map +1 -0
  114. package/dist/src/transaction/index.d.ts +4 -1
  115. package/dist/src/transaction/index.d.ts.map +1 -1
  116. package/dist/src/transaction/index.js +1 -0
  117. package/dist/src/transaction/index.js.map +1 -1
  118. package/dist/src/transaction/transaction.d.ts +20 -0
  119. package/dist/src/transaction/transaction.d.ts.map +1 -1
  120. package/dist/src/transaction/validator.d.ts +7 -0
  121. package/dist/src/transaction/validator.d.ts.map +1 -1
  122. package/dist/src/transaction/validator.js +21 -12
  123. package/dist/src/transaction/validator.js.map +1 -1
  124. package/dist/src/transactor/network-transactor.d.ts +1 -0
  125. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  126. package/dist/src/transactor/network-transactor.js +61 -28
  127. package/dist/src/transactor/network-transactor.js.map +1 -1
  128. package/dist/src/transactor/transactor-source.d.ts +22 -11
  129. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  130. package/dist/src/transactor/transactor-source.js +9 -13
  131. package/dist/src/transactor/transactor-source.js.map +1 -1
  132. package/dist/src/utility/visit-every.d.ts +14 -0
  133. package/dist/src/utility/visit-every.d.ts.map +1 -0
  134. package/dist/src/utility/visit-every.js +27 -0
  135. package/dist/src/utility/visit-every.js.map +1 -0
  136. package/package.json +1 -1
  137. package/src/cluster/structs.ts +42 -7
  138. package/src/collection/action.ts +34 -0
  139. package/src/collection/collection.ts +1048 -543
  140. package/src/collection/head-commit.ts +148 -0
  141. package/src/collection/index.ts +2 -0
  142. package/src/collection/segments.ts +149 -0
  143. package/src/collection/struct.ts +183 -1
  144. package/src/collection/write-attempts.ts +506 -0
  145. package/src/collections/tree/struct.ts +97 -17
  146. package/src/collections/tree/tree.ts +125 -29
  147. package/src/index.ts +2 -0
  148. package/src/network/i-repo.ts +3 -0
  149. package/src/network/index.ts +3 -0
  150. package/src/network/promise-shortfall-error.ts +69 -0
  151. package/src/network/refuse-solo.ts +7 -0
  152. package/src/network/stale-failure.ts +27 -4
  153. package/src/network/struct.ts +154 -2
  154. package/src/network/validity-rejected-error.ts +55 -0
  155. package/src/offline/entry.ts +127 -0
  156. package/src/offline/index.ts +4 -0
  157. package/src/offline/journal.ts +60 -0
  158. package/src/offline/queue.ts +1342 -0
  159. package/src/offline/reachability.ts +32 -0
  160. package/src/offline/status.ts +183 -0
  161. package/src/offline/wake.ts +67 -0
  162. package/src/testing/test-transactor.ts +53 -0
  163. package/src/transaction/commit-failure-class.ts +133 -0
  164. package/src/transaction/coordinator.ts +696 -349
  165. package/src/transaction/entry-commit.ts +285 -0
  166. package/src/transaction/index.ts +4 -0
  167. package/src/transaction/transaction.ts +21 -0
  168. package/src/transaction/validator.ts +22 -12
  169. package/src/transactor/network-transactor.ts +62 -28
  170. package/src/transactor/transactor-source.ts +29 -13
  171. package/src/utility/visit-every.ts +25 -0
@@ -2,6 +2,7 @@ import type { BlockId, CollectionHeaderBlock, CollectionId } from "../../index.j
2
2
  import type { KeyRange } from "../../btree/index.js";
3
3
  import { registerBlockType } from "../../blocks/block-types.js";
4
4
  import { registerCollectionType } from "../../collection/collection-type-registry.js";
5
+ import { ActionRefusedError } from "../../collection/struct.js";
5
6
  import { nameof } from "../../utility/nameof.js";
6
7
 
7
8
  export const TreeHeaderBlockType = registerBlockType("TRE", "TreeHeaderBlock");
@@ -39,6 +40,9 @@ export const rootId$ = nameof<TreeCollectionHeaderBlock>("rootId");
39
40
  * re-stage of a present key (a replay after a clean refresh) would refuse itself.
40
41
  * - `unchanged` — see {@link TreeUnchangedGuard}: the only kind that says something must
41
42
  * still BE here, rather than that nothing may be.
43
+ * - `absentOrEqual`, `unchangedOrEqual`, `unchangedOrAbsent` — the three ALREADY-APPLIED variants
44
+ * (see {@link TreeAlreadyAppliedGuard}): each accepts, and SKIPS the element, where a rival has
45
+ * already made exactly the change this element makes, instead of refusing it.
42
46
  *
43
47
  * MIXED VERSIONS: a peer running a build that predates guards destructures `[key, entry]`
44
48
  * and ignores the third slot — its replays revert to today's silent overwrite. No version
@@ -48,7 +52,52 @@ export type TreeEntryGuard<TKey, TEntry = unknown> =
48
52
  | { kind: 'absent' }
49
53
  | { kind: 'keepExisting' }
50
54
  | { kind: 'absentRange', range: KeyRange<TKey> }
51
- | TreeUnchangedGuard<TEntry>;
55
+ | TreeUnchangedGuard<TEntry>
56
+ | TreeAlreadyAppliedGuard<TEntry>;
57
+
58
+ /**
59
+ * The three guard kinds that accept a row another writer already changed the same way, for the
60
+ * offline-sync queue's rebase of a queued entry (docs/offline-sync.md §Guards that make idempotent
61
+ * writes assured). Every guard above refuses when the row is not as the staged write found it, which
62
+ * includes the rival that made exactly the change this write makes: two machines marking one task
63
+ * done, two machines deleting one row. Each variant below has three outcomes, where its base kind has
64
+ * two — it ACCEPTS AND WRITES as the base kind does, it ACCEPTS AS ALREADY APPLIED and skips the
65
+ * element (the final state is the one the write intended), or it REFUSES with the base kind's error:
66
+ *
67
+ * | Kind | Element | Writes when | Skips as already applied when | Refuses with |
68
+ * |---|---|---|---|---|
69
+ * | `absentOrEqual` | upsert | the key is absent | the present entry equals the element's own `entry` | {@link TreeKeyTakenError}, as `absent` does |
70
+ * | `unchangedOrEqual` | upsert | the present entry equals `expected` | the present entry equals the element's own `entry` (checked second, so a no-op update whose `expected` equals its `entry` writes) | {@link TreeEntryChangedError} on absent or any other entry |
71
+ * | `unchangedOrAbsent` | delete | the present entry equals `expected` | the key is absent | {@link TreeEntryChangedError} on any other entry |
72
+ *
73
+ * "Equals" is `structuralEquals` in `packages/db-core/src/utility/structural-equals.ts`, the
74
+ * comparison `unchanged` uses, with the same JSON caveats {@link TreeUnchangedGuard} states. The
75
+ * post-image an upsert variant compares against is the element's own `entry`, not a second copy on
76
+ * the guard: the element already carries it, so the guard stays the size its base kind is.
77
+ *
78
+ * Kinds and elements: `unchangedOrAbsent` is meaningful only on a delete (on an upsert it would mean
79
+ * "resurrect the row"), and the two `…OrEqual` kinds only on an upsert (a delete has no `entry` to
80
+ * compare, and would be a no-op by construction). The handler narrows both ways at runtime: a delete
81
+ * carrying an upsert-only kind throws {@link TreeDeleteGuardKindError}, an upsert carrying the
82
+ * delete-only kind {@link TreeUpsertGuardKindError} — malformed actions, outside the refusal
83
+ * hierarchy, never ignored.
84
+ *
85
+ * Whether an element accepted as already applied changed anything is reported out of the handler
86
+ * as an `AlreadyAppliedTally` (`packages/db-core/src/collection/action.ts`), which the offline queue
87
+ * folds into the `effect` of its `committed` status.
88
+ */
89
+ export type TreeAlreadyAppliedGuard<TEntry = unknown> =
90
+ | { kind: 'absentOrEqual' }
91
+ | { kind: 'unchangedOrEqual', /** The entry image the staged write read, as stored. */ expected: TEntry }
92
+ | { kind: 'unchangedOrAbsent', /** The entry image the staged delete read, as stored. */ expected: TEntry };
93
+
94
+ /** The kinds a {@link TreeUpsertElement} may carry: every kind but the delete-only
95
+ * `unchangedOrAbsent`. */
96
+ export type TreeUpsertGuard<TKey, TEntry = unknown> = Exclude<TreeEntryGuard<TKey, TEntry>, { kind: 'unchangedOrAbsent' }>;
97
+
98
+ /** The kinds a {@link TreeDeleteElement} may carry: the two that say something must still BE at the
99
+ * key — `unchanged`, and `unchangedOrAbsent`, which also accepts the key already gone. */
100
+ export type TreeDeleteGuard<TEntry = unknown> = TreeUnchangedGuard<TEntry> | Extract<TreeAlreadyAppliedGuard<TEntry>, { kind: 'unchangedOrAbsent' }>;
52
101
 
53
102
  /**
54
103
  * "The entry I am replacing must still be exactly the one I read" — the optimistic-concurrency
@@ -61,8 +110,9 @@ export type TreeEntryGuard<TKey, TEntry = unknown> =
61
110
  * exists, so re-applying it is never right: an upsert would resurrect a row a rival deleted, and
62
111
  * a delete would be the second of two racing deletes. Refusing both is the optimistic answer —
63
112
  * the writer read a row that is now gone, and an application-level retry then affects zero rows
64
- * sequentially. If tolerating absence on deletes is ever genuinely wanted, add a separate
65
- * `unchangedOrAbsent` kind rather than weakening this one's contract.
113
+ * sequentially. A delete that means "gone either way" carries `unchangedOrAbsent` instead, and an
114
+ * upsert that means "equal either way" carries `unchangedOrEqual` ({@link TreeAlreadyAppliedGuard});
115
+ * this kind's contract is not weakened for them.
66
116
  *
67
117
  * `expected` is the entry AS STORED, not a digest: a guard rides in the log beside its action
68
118
  * under the same encoding entries already use, so a full copy round-trips by construction and no
@@ -80,8 +130,8 @@ export type TreeUnchangedGuard<TEntry = unknown> = {
80
130
  expected: TEntry,
81
131
  };
82
132
 
83
- /** An element that writes (inserts or replaces) an entry. Any {@link TreeEntryGuard} kind is
84
- * meaningful here. */
133
+ /** An element that writes (inserts or replaces) an entry. Every {@link TreeEntryGuard} kind but the
134
+ * delete-only `unchangedOrAbsent` is meaningful here ({@link TreeUpsertGuard}). */
85
135
  export type TreeUpsertElement<TKey, TEntry> = [
86
136
  // The key to write at
87
137
  key: TKey,
@@ -90,20 +140,22 @@ export type TreeUpsertElement<TKey, TEntry> = [
90
140
  // Optional intent, re-checked on every handler run (see TreeEntryGuard). Absent = plain
91
141
  // upsert, so existing callers and previously committed log entries deserialize and replay
92
142
  // unchanged.
93
- guard?: TreeEntryGuard<TKey, TEntry>,
143
+ guard?: TreeUpsertGuard<TKey, TEntry>,
94
144
  ];
95
145
 
96
- /** An element that deletes the entry at a key. Only {@link TreeUnchangedGuard} says anything a
97
- * delete can act on — the other kinds all assert that nothing is present, which would make the
98
- * delete a no-op by construction. The handler rejects any other kind at runtime too, since a
99
- * replayed log entry is deserialized data that this type never policed. */
146
+ /** An element that deletes the entry at a key. Only the two kinds that say something must still BE
147
+ * at the key say anything a delete can act on ({@link TreeDeleteGuard}) — the other kinds all assert
148
+ * that nothing is present, which would make the delete a no-op by construction. The handler rejects
149
+ * any other kind at runtime too, since a replayed log entry is deserialized data that this type
150
+ * never policed. */
100
151
  export type TreeDeleteElement<TKey, TEntry> = [
101
152
  // The key to delete
102
153
  key: TKey,
103
154
  // Always empty: the absent entry is what marks this element a delete
104
155
  entry?: undefined,
105
156
  // Optional lost-update guard: refuse the delete unless the entry is still the one that was read
106
- guard?: TreeUnchangedGuard<TEntry>,
157
+ // (`unchanged`), or unless it is either that or already gone (`unchangedOrAbsent`)
158
+ guard?: TreeDeleteGuard<TEntry>,
107
159
  ];
108
160
 
109
161
  /** Represents a unit of change to a tree collection. */
@@ -129,16 +181,21 @@ export type TreeReplaceAction<TKey, TEntry> = (
129
181
  * {@link TreeEntryChangedError} is a lost update (the bridge raises its
130
182
  * `ConcurrentModificationError`, status code BUSY, which is not a constraint error). Catch
131
183
  * this base to treat any guard refusal uniformly; catch a subclass to say which happened.
184
+ *
185
+ * It is the tree's {@link ActionRefusedError}, which is what the collection's segment-aware
186
+ * replay recognises (a refusal from a sealed segment is recorded against that segment rather
187
+ * than thrown — see `Collection.replayActions`); the classifier and the bridge keep matching
188
+ * this class, which the subclass relation leaves unchanged.
132
189
  */
133
- export class TreeGuardRefusedError<TKey = unknown> extends Error {
190
+ export class TreeGuardRefusedError<TKey = unknown> extends ActionRefusedError {
134
191
  constructor(
135
192
  /** The collection whose tree refused the entry. */
136
- public readonly collectionId: CollectionId,
193
+ collectionId: CollectionId,
137
194
  /** The key whose staged entry was refused. */
138
195
  public readonly key: TKey,
139
196
  message: string,
140
197
  ) {
141
- super(message);
198
+ super(collectionId, message);
142
199
  this.name = 'TreeGuardRefusedError';
143
200
  }
144
201
  }
@@ -226,7 +283,8 @@ export class TreeEntryChangedError<TKey = unknown, TEntry = unknown> extends Tre
226
283
  * present, which would make the delete a no-op by construction, so this is a malformed action —
227
284
  * a caller bug, or a log entry written by a build whose element types disagree with this one.
228
285
  * The handler raises it rather than ignoring the guard (the pre-guard behaviour) so a writer
229
- * never believes an unenforceable guard is being enforced.
286
+ * never believes an unenforceable guard is being enforced. {@link TreeUpsertGuardKindError} is the
287
+ * upsert side of the same check.
230
288
  */
231
289
  export class TreeDeleteGuardKindError<TKey = unknown> extends Error {
232
290
  constructor(
@@ -234,15 +292,37 @@ export class TreeDeleteGuardKindError<TKey = unknown> extends Error {
234
292
  public readonly collectionId: CollectionId,
235
293
  /** The key the malformed delete named. */
236
294
  public readonly key: TKey,
237
- /** The `kind` that was carried; only `'unchanged'` is meaningful on a delete. */
295
+ /** The `kind` that was carried; only `'unchanged'` and `'unchangedOrAbsent'` are meaningful on
296
+ * a delete. */
238
297
  public readonly guardKind: string,
239
298
  ) {
240
299
  super(`Tree collection ${collectionId}: the delete of key ${renderKey(key)} carries a `
241
- + `'${guardKind}' guard; only 'unchanged' is meaningful on a delete`);
300
+ + `'${guardKind}' guard; only 'unchanged' and 'unchangedOrAbsent' are meaningful on a delete`);
242
301
  this.name = 'TreeDeleteGuardKindError';
243
302
  }
244
303
  }
245
304
 
305
+ /**
306
+ * An UPSERT element carries the delete-only guard kind, `unchangedOrAbsent`: on an upsert it would
307
+ * mean "write the row whether or not a rival deleted it", which resurrects a row the staged write
308
+ * never meant to and so is a malformed action, not a concurrency refusal — the mirror of
309
+ * {@link TreeDeleteGuardKindError}, and like it deliberately not a {@link TreeGuardRefusedError}.
310
+ */
311
+ export class TreeUpsertGuardKindError<TKey = unknown> extends Error {
312
+ constructor(
313
+ /** The collection whose tree rejected the element. */
314
+ public readonly collectionId: CollectionId,
315
+ /** The key the malformed upsert named. */
316
+ public readonly key: TKey,
317
+ /** The `kind` that was carried. */
318
+ public readonly guardKind: string,
319
+ ) {
320
+ super(`Tree collection ${collectionId}: the upsert of key ${renderKey(key)} carries a `
321
+ + `'${guardKind}' guard, which is meaningful only on a delete`);
322
+ this.name = 'TreeUpsertGuardKindError';
323
+ }
324
+ }
325
+
246
326
  /** String keys render JSON-quoted so framing control bytes stay visible/escaped in logs;
247
327
  * everything else via String() — JSON.stringify would throw on a bigint key, and an error
248
328
  * constructor must never be the second failure. Module-private on purpose: every tree message
@@ -4,28 +4,39 @@ import { BTree, type Path, type KeyRange } from "../../btree/index.js";
4
4
  import { CollectionTrunk } from "./collection-trunk.js";
5
5
  import { structuralEquals } from "../../utility/structural-equals.js";
6
6
  import { BLOCK_TARGET_BYTES } from "../../network/block-size.js";
7
+ import { ZeroTally } from "../../collection/action.js";
8
+ import type { AlreadyAppliedTally } from "../../collection/action.js";
7
9
  import {
8
10
  TreeHeaderBlockType, TreeDeleteGuardKindError, TreeEntryChangedError, TreeKeyTakenError,
9
- TreeRangeTakenError, type TreeEntryGuard, type TreeReplaceAction,
11
+ TreeRangeTakenError, TreeUpsertGuardKindError, type TreeEntryGuard, type TreeReplaceAction,
10
12
  } from "./struct.js";
11
13
 
14
+ /** What a guard decided for its element: write it, skip it with no claim about equality
15
+ * (`keepExisting` found the key occupied), or skip it because a rival already made exactly this
16
+ * change — the already-applied acceptance a `TreeAlreadyAppliedGuard` kind makes, which is the one
17
+ * skip the handler counts (`alreadyApplied` on the {@link AlreadyAppliedTally}). */
18
+ type GuardVerdict = 'proceed' | 'skip' | 'already-applied';
19
+
12
20
  /**
13
21
  * Enforce a guard carried by an UPSERT element against the CURRENT content of `actionTree` —
14
22
  * the same Atomic store the upsert writes to, so it sees what earlier elements of this same
15
23
  * replay already staged or deleted (an UPDATE's delete-old half runs before its guarded insert
16
- * half). Throws the guard's refusal, which discards the whole action's staged writes.
24
+ * half). Throws the guard's refusal, which discards the whole action's staged writes. `entry` is the
25
+ * element's own entry, the post-image the `…OrEqual` kinds compare against.
17
26
  *
18
27
  * @returns `'skip'` when the element must be left unwritten (`keepExisting` found the key
19
- * occupied — the INSERT OR IGNORE disposition), `'proceed'` otherwise.
28
+ * occupied — the INSERT OR IGNORE disposition), `'already-applied'` when an already-applied kind
29
+ * found the rival had made this change, `'proceed'` otherwise.
20
30
  */
21
31
  async function enforceUpsertGuard<TKey, TEntry>(
22
32
  actionTree: BTree<TKey, TEntry>,
23
33
  id: CollectionId,
24
34
  key: TKey,
35
+ entry: TEntry,
25
36
  guard: TreeEntryGuard<TKey, TEntry>,
26
37
  keyFromEntry: (entry: TEntry) => TKey,
27
38
  compare: (a: TKey, b: TKey) => number,
28
- ): Promise<'proceed' | 'skip'> {
39
+ ): Promise<GuardVerdict> {
29
40
  switch (guard.kind) {
30
41
  case 'absentRange': {
31
42
  // Secondary-UNIQUE: the claimed range (a unique index's framed value prefix) must hold
@@ -53,6 +64,86 @@ async function enforceUpsertGuard<TKey, TEntry>(
53
64
  // keepExisting: leave the present (rival's) entry in place and skip this element.
54
65
  return 'skip';
55
66
  }
67
+ case 'absentOrEqual': {
68
+ const actual = actionTree.at(await actionTree.find(key));
69
+ if (actual === undefined) return 'proceed';
70
+ if (structuralEquals(actual, entry)) return 'already-applied';
71
+ throw new TreeKeyTakenError(id, key);
72
+ }
73
+ case 'unchangedOrEqual': {
74
+ const actual = actionTree.at(await actionTree.find(key));
75
+ // `expected` first: a no-op update (expected equals entry) writes and counts as applied.
76
+ if (actual !== undefined && structuralEquals(actual, guard.expected)) return 'proceed';
77
+ if (actual !== undefined && structuralEquals(actual, entry)) return 'already-applied';
78
+ throw new TreeEntryChangedError(id, key, guard.expected, actual);
79
+ }
80
+ case 'unchangedOrAbsent': {
81
+ throw new TreeUpsertGuardKindError(id, key, guard.kind);
82
+ }
83
+ }
84
+ }
85
+
86
+ /**
87
+ * Enforce a guard carried by a DELETE element against the entry found at its path. Throws the
88
+ * guard's refusal, or {@link TreeDeleteGuardKindError} for a kind no delete can act on — the element
89
+ * type already says so ({@link TreeDeleteElement}), but a replayed log entry is deserialized data
90
+ * that no type policed, so the handler re-checks rather than silently ignoring a guard the writer
91
+ * believed was being enforced.
92
+ *
93
+ * @returns `'already-applied'` when `unchangedOrAbsent` found the key already gone (nothing to
94
+ * delete), `'proceed'` otherwise.
95
+ */
96
+ function enforceDeleteGuard<TKey, TEntry>(
97
+ id: CollectionId,
98
+ key: TKey,
99
+ guard: TreeEntryGuard<TKey, TEntry>,
100
+ actual: TEntry | undefined,
101
+ ): Exclude<GuardVerdict, 'skip'> {
102
+ switch (guard.kind) {
103
+ case 'unchanged': {
104
+ assertEntryUnchanged(id, key, guard.expected, actual);
105
+ return 'proceed';
106
+ }
107
+ case 'unchangedOrAbsent': {
108
+ if (actual === undefined) return 'already-applied';
109
+ assertEntryUnchanged(id, key, guard.expected, actual);
110
+ return 'proceed';
111
+ }
112
+ default: {
113
+ throw new TreeDeleteGuardKindError(id, key, guard.kind);
114
+ }
115
+ }
116
+ }
117
+
118
+ /** Whether a write under `guard` counts as `applied` on the tally (see {@link AlreadyAppliedTally}):
119
+ * the three already-applied kinds, whose skips are the `alreadyApplied` side, and the two exact-key
120
+ * base kinds that write whenever they do not refuse — `absent` and `unchanged`, which the SQL layer
121
+ * stages on every main-table element and never on an index tree — so an entry with a plain insert
122
+ * beside an already-applied update reads `applied`, as a host taking `already-applied` for "none of
123
+ * my changes landed" needs. Not counted: `keepExisting` (its skip says nothing about equality),
124
+ * `absentRange` and an unguarded element, the shapes an index tree's entries take, whose writes
125
+ * under an already-applied entry are rewrites of what the rival's row already implies. */
126
+ function countsWrite<TKey, TEntry>(guard: TreeEntryGuard<TKey, TEntry>): boolean {
127
+ return guard.kind === 'absent' || guard.kind === 'unchanged'
128
+ || guard.kind === 'absentOrEqual' || guard.kind === 'unchangedOrEqual' || guard.kind === 'unchangedOrAbsent';
129
+ }
130
+
131
+ /** A tally over one handler run, mutable while the run counts. */
132
+ class TallyBuilder {
133
+ private alreadyApplied = 0;
134
+ private applied = 0;
135
+
136
+ /** Count `verdict` for an element carrying `guard`. Only an already-applied kind answers
137
+ * `'already-applied'`; a write counts when {@link countsWrite} says so. */
138
+ count<TKey, TEntry>(guard: TreeEntryGuard<TKey, TEntry>, verdict: GuardVerdict): void {
139
+ if (verdict === 'already-applied') this.alreadyApplied++;
140
+ else if (verdict === 'proceed' && countsWrite(guard)) this.applied++;
141
+ }
142
+
143
+ result(): AlreadyAppliedTally {
144
+ return this.alreadyApplied === 0 && this.applied === 0
145
+ ? ZeroTally
146
+ : { alreadyApplied: this.alreadyApplied, applied: this.applied };
56
147
  }
57
148
  }
58
149
 
@@ -70,21 +161,6 @@ function assertEntryUnchanged<TKey, TEntry>(
70
161
  }
71
162
  }
72
163
 
73
- /** Narrow a DELETE element's guard to the only kind a delete can act on. The element type already
74
- * says this ({@link TreeDeleteElement}), but a replayed log entry is deserialized data that no
75
- * type policed, so the handler re-checks it and throws {@link TreeDeleteGuardKindError} rather
76
- * than silently ignoring a guard the writer believed was being enforced. */
77
- function deleteGuardExpected<TKey, TEntry>(
78
- id: CollectionId,
79
- key: TKey,
80
- guard: TreeEntryGuard<TKey, TEntry>,
81
- ): TEntry {
82
- if (guard.kind !== 'unchanged') {
83
- throw new TreeDeleteGuardKindError(id, key, guard.kind);
84
- }
85
- return guard.expected;
86
- }
87
-
88
164
  /**
89
165
  * Read-only surface of a tree: every navigation/lookup method a reader needs, with
90
166
  * none of the mutation (stage/sync) or network-refresh (update) entry points. Both
@@ -108,6 +184,11 @@ interface BTreeHolder<TKey, TEntry> {
108
184
  btree?: BTree<TKey, TEntry>;
109
185
  }
110
186
 
187
+ /** The collection options a tree's opener may set — the ones that are not the tree's own to
188
+ * decide. Today that is the sealed-segment refusal callback the offline-sync queue installs
189
+ * (see {@link CollectionInitOptions.onSealedRefused}). */
190
+ export type TreeCollectionOptions = Pick<CollectionInitOptions<unknown>, 'onSealedRefused'>;
191
+
111
192
  export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
112
193
 
113
194
  private constructor(
@@ -130,9 +211,11 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
130
211
  compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0,
131
212
  /** See {@link Tree.createOrOpen}'s `nodeCapacity`. */
132
213
  nodeCapacity?: number,
214
+ /** See {@link Tree.createOrOpen}'s `options`. */
215
+ options?: TreeCollectionOptions,
133
216
  ): Promise<Tree<TKey, TEntry> | undefined> {
134
217
  const held: BTreeHolder<TKey, TEntry> = {};
135
- const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held);
218
+ const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held, options);
136
219
  const collection = await Collection.open<TreeReplaceAction<TKey, TEntry>>(network, id, init);
137
220
  return collection ? Tree.attach(collection, held, keyFromEntry, compare, nodeCapacity) : undefined;
138
221
  }
@@ -154,9 +237,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
154
237
  * they pass it consistently); if a persisted tree ever needs a custom fan-out, persist it in
155
238
  * the header and read it back on reopen rather than trusting the caller to re-supply it. */
156
239
  nodeCapacity?: number,
240
+ /** Collection options the opener sets rather than the tree: the sealed-segment refusal
241
+ * callback (see {@link TreeCollectionOptions}). Omit for a tree nothing seals. */
242
+ options?: TreeCollectionOptions,
157
243
  ): Promise<Tree<TKey, TEntry>> {
158
244
  const held: BTreeHolder<TKey, TEntry> = {};
159
- const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held);
245
+ const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held, options);
160
246
  const collection = await Collection.createOrOpen<TreeReplaceAction<TKey, TEntry>>(network, id, init);
161
247
  return Tree.attach(collection, held, keyFromEntry, compare, nodeCapacity);
162
248
  }
@@ -169,10 +255,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
169
255
  compare: (a: TKey, b: TKey) => number,
170
256
  nodeCapacity: number | undefined,
171
257
  held: BTreeHolder<TKey, TEntry>,
258
+ options: TreeCollectionOptions | undefined,
172
259
  ): CollectionInitOptions<TreeReplaceAction<TKey, TEntry>> {
173
260
  return {
261
+ ...options,
174
262
  modules: {
175
- "replace": async ({ data: actions }, trx) => {
263
+ "replace": async ({ data: actions }, trx): Promise<AlreadyAppliedTally> => {
176
264
  // Write through the Atomic store the handler is handed (`trx`), NOT the captured
177
265
  // read btree, so `internalTransact`'s all-or-nothing wrapper actually governs this
178
266
  // action: if any entry throws, `atomic.commit()` is skipped and every staged node
@@ -187,6 +275,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
187
275
  nodeCapacity, // keep the write btree's fan-out in lock-step with the read btree
188
276
  BLOCK_TARGET_BYTES, // and its node size rule: every node is a block that must stay copyable
189
277
  );
278
+ const tally = new TallyBuilder();
190
279
  for (const [key, entry, guard] of actions) {
191
280
  // NOTE: an element is a DELETE when its entry slot is falsy, not when it is
192
281
  // strictly `undefined`. That is deliberate and load-bearing: JSON encodes the
@@ -211,9 +300,10 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
211
300
  // slot above: an explicitly-passed `undefined` guard (the shape every unguarded
212
301
  // index write stages) comes back from JSON as `null`, and reading `.kind` off it
213
302
  // would throw a TypeError mid-replay instead of meaning "no guard".
214
- if (guard
215
- && await enforceUpsertGuard(actionTree, id, key, guard, keyFromEntry, compare) === 'skip') {
216
- continue;
303
+ if (guard) {
304
+ const verdict = await enforceUpsertGuard(actionTree, id, key, entry, guard, keyFromEntry, compare);
305
+ tally.count(guard, verdict);
306
+ if (verdict !== 'proceed') continue;
217
307
  }
218
308
  await actionTree.upsert(entry);
219
309
  } else {
@@ -221,7 +311,9 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
221
311
  // consumes it, with no mutation in between to invalidate it.
222
312
  const path = await actionTree.find(key);
223
313
  if (guard) {
224
- assertEntryUnchanged(id, key, deleteGuardExpected(id, key, guard), actionTree.at(path));
314
+ const verdict = enforceDeleteGuard(id, key, guard, actionTree.at(path));
315
+ tally.count(guard, verdict);
316
+ if (verdict === 'already-applied') continue;
225
317
  }
226
318
  await actionTree.deleteAt(path);
227
319
  }
@@ -230,6 +322,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
230
322
  // Bump it to invalidate any Path a caller still holds — preserving the path-invalidation
231
323
  // the previous in-place handler gave for free.
232
324
  held.btree?.invalidatePaths();
325
+ return tally.result();
233
326
  }
234
327
  },
235
328
  createHeaderBlock: (hid: BlockId, store: BlockStore<IBlock>) => { // Only called if the collection does not exist
@@ -311,9 +404,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
311
404
 
312
405
  /** Restore the staged state captured by {@link snapshot}, discarding mutations
313
406
  * staged since. Counterpart to {@link stage} for transaction rollback —
314
- * preserves a never-synced collection's header/root rather than wiping it. */
315
- restore(snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>): void {
316
- this.collection.restorePending(snapshot);
407
+ * preserves a never-synced collection's header/root rather than wiping it.
408
+ * Resolves once the restore is complete: a restore across a change to the
409
+ * collection's sealed segments replays them, which runs the action handlers
410
+ * (see {@link Collection.restorePending}). */
411
+ async restore(snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>): Promise<void> {
412
+ await this.collection.restorePending(snapshot);
317
413
  }
318
414
 
319
415
  /** Build a read-only view of this tree as captured by an earlier {@link snapshot}
package/src/index.ts CHANGED
@@ -9,6 +9,7 @@ export * from "./log/index.js";
9
9
  export * from "./logger-registry.js";
10
10
  export * from "./matchmaking/index.js";
11
11
  export * from "./network/index.js";
12
+ export * from "./offline/index.js";
12
13
  export * from "./reactivity/index.js";
13
14
  export * from "./transaction/index.js";
14
15
  export * from "./transactor/index.js";
@@ -25,3 +26,4 @@ export * from "./utility/pending.js";
25
26
  export * from "./utility/lru-map.js";
26
27
  export * from "./utility/backoff.js";
27
28
  export * from "./utility/unref-timer.js";
29
+ export * from "./utility/visit-every.js";
@@ -57,6 +57,9 @@ export type RepoCommitRequest = {
57
57
  // durable commit proof and so cannot gain holders by push. Full rationale and the measured cost of
58
58
  // making it required live at {@link CommitRequest.blockDigests} in `struct.ts`; keep the two in sync.
59
59
  blockDigests?: BlockContentDigests;
60
+ /** {@link CommitRequest.refuseSolo}: present on every per-coordinator commit of a write that asked
61
+ * not to be committed alone, and omitted otherwise. */
62
+ refuseSolo?: true;
60
63
  };
61
64
 
62
65
  export type IRepo = {
@@ -4,6 +4,8 @@ export * from "./block-size.js";
4
4
  export * from "./durability.js";
5
5
  export * from "./i-repo.js";
6
6
  export * from "./lineage.js";
7
+ export * from "./promise-shortfall-error.js";
8
+ export * from "./refuse-solo.js";
7
9
  export * from "./repo-protocol.js";
8
10
  export * from "./routing-key.js";
9
11
  export * from "./stale-failure.js";
@@ -11,3 +13,4 @@ export * from "./struct.js";
11
13
  export * from "./transaction-expired-error.js";
12
14
  export * from "./transaction-size.js";
13
15
  export * from "./types.js";
16
+ export * from "./validity-rejected-error.js";
@@ -0,0 +1,69 @@
1
+ import type { PromiseShortfall, ShortfallFailure, SoloRefusalReason } from "./struct.js";
2
+
3
+ /**
4
+ * A pend the cohort could not accept because too few of its members answered the promise round: the
5
+ * approvals fell short of the bar with no member refusing the write as a lost race or a held block,
6
+ * and too few rejecting it for a rejection. Nobody judged the write; the cohort was not all there.
7
+ * Not retryable by a write path — every coordinator of the cohort meets the same silent members, so a
8
+ * re-read and re-pend fails the same way until they answer again. Nothing was saved: the members that
9
+ * approved release their reservation when the writer cancels.
10
+ *
11
+ * ONE class for every place it is raised, as `TransactionExpiredError` is. The cluster coordinator
12
+ * (db-p2p `ClusterCoordinator`) raises it; the coordinating repo returns its facts as a
13
+ * {@link ShortfallFailure} ({@link toFailure}), which is what lets a remote writer receive them at
14
+ * all; and each write path (`Collection.sync`, `TransactionCoordinator.commit`) raises it again from
15
+ * that refusal.
16
+ *
17
+ * The message is the sentence the coordinator has always thrown, byte for byte: a downstream
18
+ * repository matches it to retry a silent cohort (backlog
19
+ * `debt-a-downstream-repo-classifies-retries-by-parsing-our-error-text`). Test for this class, or for
20
+ * the refusal with `isShortfallFailure`, rather than for the text.
21
+ */
22
+ export class PromiseShortfallError extends Error {
23
+ /** Approve votes the round received. */
24
+ readonly approvals: number;
25
+ /** Reject votes the round received — fewer than would make the round a rejection. */
26
+ readonly rejections: number;
27
+ /** How many members the cohort the round ran on has. */
28
+ readonly peerCount: number;
29
+ /** The approvals the round needed. */
30
+ readonly needed: number;
31
+ /** Peer-id strings of the cohort members that cast no promise vote at all. */
32
+ readonly silentPeers: readonly string[];
33
+ /** Why a lone coordinator refused to write alone, when that is what this shortfall is
34
+ * ({@link PromiseShortfall.soloRefused}); absent when a consensus round fell short. */
35
+ readonly soloRefused?: SoloRefusalReason;
36
+
37
+ constructor(shortfall: PromiseShortfall) {
38
+ // NOTE: `shortfall` off the wire is trusted as shaped (`isShortfallFailure` checks only presence),
39
+ // so a malformed coordinator answer throws a TypeError here (no `silentPeers` array) instead of
40
+ // this error. Either still ends the write; if hostile coordinators become a concern, validate the
41
+ // shape where the refusal is received, as for `TransactionExpiredError`.
42
+ super(`Failed to get super-majority: ${shortfall.approvals}/${shortfall.peerCount} approvals (needed ${shortfall.needed}, ${shortfall.rejections} rejections)`);
43
+ this.name = 'PromiseShortfallError';
44
+ this.approvals = shortfall.approvals;
45
+ this.rejections = shortfall.rejections;
46
+ this.peerCount = shortfall.peerCount;
47
+ this.needed = shortfall.needed;
48
+ this.silentPeers = [...shortfall.silentPeers];
49
+ if (shortfall.soloRefused !== undefined) this.soloRefused = shortfall.soloRefused;
50
+ }
51
+
52
+ /** The refusal a coordinating repo returns for this error, so it crosses the repo protocol as an
53
+ * answer rather than as a reset stream. */
54
+ toFailure(): ShortfallFailure {
55
+ return {
56
+ success: false,
57
+ conflict: false,
58
+ reason: this.message,
59
+ shortfall: {
60
+ approvals: this.approvals,
61
+ rejections: this.rejections,
62
+ peerCount: this.peerCount,
63
+ needed: this.needed,
64
+ silentPeers: [...this.silentPeers],
65
+ ...(this.soloRefused === undefined ? {} : { soloRefused: this.soloRefused }),
66
+ },
67
+ };
68
+ }
69
+ }
@@ -0,0 +1,7 @@
1
+ /** Wraps `PendRequest.refuseSolo` and `CommitRequest.refuseSolo` so the field spreads onto a request
2
+ * only when the write refuses to be committed alone. A write that does not is omitted rather than
3
+ * sent as `false`: the request is hashed verbatim into every cohort signature preimage, so it must
4
+ * serialize exactly as it did before the field existed. Every producer of the field goes through here. */
5
+ export function refuseSoloField(refuse: boolean | undefined): { refuseSolo?: true } {
6
+ return refuse === true ? { refuseSolo: true } : {};
7
+ }
@@ -1,5 +1,5 @@
1
1
  import type { ActionId, ActionRev } from "../collection/action.js";
2
- import type { ExpiredFailure, StaleFailure, WriteFailure } from "./struct.js";
2
+ import type { ExpiredFailure, RejectedFailure, ShortfallFailure, StaleFailure, WriteFailure } from "./struct.js";
3
3
 
4
4
  /**
5
5
  * The single rule for "is this non-success retryable after a re-read?" Both write paths and the
@@ -7,11 +7,12 @@ import type { ExpiredFailure, StaleFailure, WriteFailure } from "./struct.js";
7
7
  *
8
8
  * {@link StaleFailure.conflict} is authoritative when present. The `missing`/`pending` fallback
9
9
  * covers producers that have not been taught the field, including a remote peer on an older build
10
- * (the repo protocol is plain JSON, so an unset field simply arrives absent). An expiry is never a
11
- * conflict ({@link isExpiryFailure}), whatever else arrived beside it.
10
+ * (the repo protocol is plain JSON, so an unset field simply arrives absent). An expiry
11
+ * ({@link isExpiryFailure}), a promise shortfall ({@link isShortfallFailure}) and a validity
12
+ * rejection ({@link isRejectedFailure}) are never a conflict, whatever else arrived beside them.
12
13
  */
13
14
  export function isConflictFailure(failure: WriteFailure): boolean {
14
- if (isExpiryFailure(failure)) return false;
15
+ if (isExpiryFailure(failure) || isShortfallFailure(failure) || isRejectedFailure(failure)) return false;
15
16
  return failure.conflict ?? Boolean(failure.missing?.length || failure.pending?.length);
16
17
  }
17
18
 
@@ -26,6 +27,28 @@ export function isExpiryFailure(failure: WriteFailure): failure is ExpiredFailur
26
27
  return failure.expired !== undefined;
27
28
  }
28
29
 
30
+ /**
31
+ * The single rule for "did the cohort refuse this pend because too few of its members answered the
32
+ * promise round?" ({@link ShortfallFailure}). Every write path stops on it rather than retrying, since
33
+ * every coordinator of the cohort meets the same silent members. Decided by the structured field,
34
+ * never the reason text; a coordinator on a build that predates the field throws the shortfall
35
+ * instead of returning it, which a writer sees as it always did.
36
+ */
37
+ export function isShortfallFailure(failure: WriteFailure): failure is ShortfallFailure {
38
+ return failure.shortfall !== undefined;
39
+ }
40
+
41
+ /**
42
+ * The single rule for "did the cohort refuse this pend because the members that sank it judged the
43
+ * transaction invalid?" ({@link RejectedFailure}). Every write path stops on it rather than retrying,
44
+ * since re-sending the same content to the same checks is refused the same way. Decided by the
45
+ * structured field, never the reason text; a coordinator on a build that predates the field throws the
46
+ * rejection instead of returning it, which a writer sees as it always did.
47
+ */
48
+ export function isRejectedFailure(failure: WriteFailure): failure is RejectedFailure {
49
+ return failure.rejected !== undefined;
50
+ }
51
+
29
52
  /**
30
53
  * The single rule for picking one {@link StaleFailure.staleAt} out of several candidates.
31
54
  *