@optimystic/db-core 1.18.0 → 1.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/README.md +2 -1
  2. package/dist/src/blocks/helpers.d.ts +7 -0
  3. package/dist/src/blocks/helpers.d.ts.map +1 -1
  4. package/dist/src/blocks/helpers.js +7 -1
  5. package/dist/src/blocks/helpers.js.map +1 -1
  6. package/dist/src/btree/btree.d.ts +100 -4
  7. package/dist/src/btree/btree.d.ts.map +1 -1
  8. package/dist/src/btree/btree.js +252 -90
  9. package/dist/src/btree/btree.js.map +1 -1
  10. package/dist/src/btree/node-division.d.ts +37 -0
  11. package/dist/src/btree/node-division.d.ts.map +1 -0
  12. package/dist/src/btree/node-division.js +133 -0
  13. package/dist/src/btree/node-division.js.map +1 -0
  14. package/dist/src/chain/chain.d.ts +23 -0
  15. package/dist/src/chain/chain.d.ts.map +1 -1
  16. package/dist/src/chain/chain.js +43 -6
  17. package/dist/src/chain/chain.js.map +1 -1
  18. package/dist/src/cluster/structs.d.ts +41 -8
  19. package/dist/src/cluster/structs.d.ts.map +1 -1
  20. package/dist/src/cluster/structs.js +18 -7
  21. package/dist/src/cluster/structs.js.map +1 -1
  22. package/dist/src/collection/action.d.ts +29 -0
  23. package/dist/src/collection/action.d.ts.map +1 -1
  24. package/dist/src/collection/action.js +6 -0
  25. package/dist/src/collection/action.js.map +1 -1
  26. package/dist/src/collection/collection.d.ts +566 -120
  27. package/dist/src/collection/collection.d.ts.map +1 -1
  28. package/dist/src/collection/collection.js +1084 -495
  29. package/dist/src/collection/collection.js.map +1 -1
  30. package/dist/src/collection/head-commit.d.ts +110 -0
  31. package/dist/src/collection/head-commit.d.ts.map +1 -0
  32. package/dist/src/collection/head-commit.js +65 -0
  33. package/dist/src/collection/head-commit.js.map +1 -0
  34. package/dist/src/collection/index.d.ts +2 -0
  35. package/dist/src/collection/index.d.ts.map +1 -1
  36. package/dist/src/collection/index.js +2 -0
  37. package/dist/src/collection/index.js.map +1 -1
  38. package/dist/src/collection/segments.d.ts +77 -0
  39. package/dist/src/collection/segments.d.ts.map +1 -0
  40. package/dist/src/collection/segments.js +110 -0
  41. package/dist/src/collection/segments.js.map +1 -0
  42. package/dist/src/collection/struct.d.ts +176 -1
  43. package/dist/src/collection/struct.d.ts.map +1 -1
  44. package/dist/src/collection/struct.js +70 -0
  45. package/dist/src/collection/struct.js.map +1 -1
  46. package/dist/src/collection/write-attempts.d.ts +245 -0
  47. package/dist/src/collection/write-attempts.d.ts.map +1 -0
  48. package/dist/src/collection/write-attempts.js +439 -0
  49. package/dist/src/collection/write-attempts.js.map +1 -0
  50. package/dist/src/collections/tree/struct.d.ts +100 -17
  51. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  52. package/dist/src/collections/tree/struct.js +38 -7
  53. package/dist/src/collections/tree/struct.js.map +1 -1
  54. package/dist/src/collections/tree/tree.d.ts +17 -5
  55. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  56. package/dist/src/collections/tree/tree.js +117 -29
  57. package/dist/src/collections/tree/tree.js.map +1 -1
  58. package/dist/src/index.d.ts +2 -0
  59. package/dist/src/index.d.ts.map +1 -1
  60. package/dist/src/index.js +2 -0
  61. package/dist/src/index.js.map +1 -1
  62. package/dist/src/log/log.d.ts +5 -1
  63. package/dist/src/log/log.d.ts.map +1 -1
  64. package/dist/src/log/log.js +7 -1
  65. package/dist/src/log/log.js.map +1 -1
  66. package/dist/src/network/block-size.d.ts +67 -0
  67. package/dist/src/network/block-size.d.ts.map +1 -0
  68. package/dist/src/network/block-size.js +82 -0
  69. package/dist/src/network/block-size.js.map +1 -0
  70. package/dist/src/network/i-repo.d.ts +3 -0
  71. package/dist/src/network/i-repo.d.ts.map +1 -1
  72. package/dist/src/network/index.d.ts +5 -0
  73. package/dist/src/network/index.d.ts.map +1 -1
  74. package/dist/src/network/index.js +5 -0
  75. package/dist/src/network/index.js.map +1 -1
  76. package/dist/src/network/promise-shortfall-error.d.ts +40 -0
  77. package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
  78. package/dist/src/network/promise-shortfall-error.js +67 -0
  79. package/dist/src/network/promise-shortfall-error.js.map +1 -0
  80. package/dist/src/network/refuse-solo.d.ts +8 -0
  81. package/dist/src/network/refuse-solo.d.ts.map +1 -0
  82. package/dist/src/network/refuse-solo.js +8 -0
  83. package/dist/src/network/refuse-solo.js.map +1 -0
  84. package/dist/src/network/stale-failure.d.ts +20 -3
  85. package/dist/src/network/stale-failure.d.ts.map +1 -1
  86. package/dist/src/network/stale-failure.js +24 -3
  87. package/dist/src/network/stale-failure.js.map +1 -1
  88. package/dist/src/network/struct.d.ts +161 -13
  89. package/dist/src/network/struct.d.ts.map +1 -1
  90. package/dist/src/network/struct.js.map +1 -1
  91. package/dist/src/network/transaction-size.d.ts +59 -0
  92. package/dist/src/network/transaction-size.d.ts.map +1 -0
  93. package/dist/src/network/transaction-size.js +74 -0
  94. package/dist/src/network/transaction-size.js.map +1 -0
  95. package/dist/src/network/validity-rejected-error.d.ts +28 -0
  96. package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
  97. package/dist/src/network/validity-rejected-error.js +51 -0
  98. package/dist/src/network/validity-rejected-error.js.map +1 -0
  99. package/dist/src/offline/entry.d.ts +72 -0
  100. package/dist/src/offline/entry.d.ts.map +1 -0
  101. package/dist/src/offline/entry.js +73 -0
  102. package/dist/src/offline/entry.js.map +1 -0
  103. package/dist/src/offline/index.d.ts +5 -0
  104. package/dist/src/offline/index.d.ts.map +1 -0
  105. package/dist/src/offline/index.js +5 -0
  106. package/dist/src/offline/index.js.map +1 -0
  107. package/dist/src/offline/journal.d.ts +61 -0
  108. package/dist/src/offline/journal.d.ts.map +1 -0
  109. package/dist/src/offline/journal.js +2 -0
  110. package/dist/src/offline/journal.js.map +1 -0
  111. package/dist/src/offline/queue.d.ts +484 -0
  112. package/dist/src/offline/queue.d.ts.map +1 -0
  113. package/dist/src/offline/queue.js +1236 -0
  114. package/dist/src/offline/queue.js.map +1 -0
  115. package/dist/src/offline/reachability.d.ts +25 -0
  116. package/dist/src/offline/reachability.d.ts.map +1 -0
  117. package/dist/src/offline/reachability.js +13 -0
  118. package/dist/src/offline/reachability.js.map +1 -0
  119. package/dist/src/offline/status.d.ts +148 -0
  120. package/dist/src/offline/status.d.ts.map +1 -0
  121. package/dist/src/offline/status.js +63 -0
  122. package/dist/src/offline/status.js.map +1 -0
  123. package/dist/src/offline/wake.d.ts +30 -0
  124. package/dist/src/offline/wake.d.ts.map +1 -0
  125. package/dist/src/offline/wake.js +68 -0
  126. package/dist/src/offline/wake.js.map +1 -0
  127. package/dist/src/reactivity/config.d.ts +8 -4
  128. package/dist/src/reactivity/config.d.ts.map +1 -1
  129. package/dist/src/reactivity/config.js +7 -3
  130. package/dist/src/reactivity/config.js.map +1 -1
  131. package/dist/src/reactivity/rotation.d.ts +9 -3
  132. package/dist/src/reactivity/rotation.d.ts.map +1 -1
  133. package/dist/src/reactivity/rotation.js +8 -2
  134. package/dist/src/reactivity/rotation.js.map +1 -1
  135. package/dist/src/testing/test-transactor.d.ts +31 -0
  136. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  137. package/dist/src/testing/test-transactor.js +60 -0
  138. package/dist/src/testing/test-transactor.js.map +1 -1
  139. package/dist/src/transaction/commit-failure-class.d.ts +103 -0
  140. package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
  141. package/dist/src/transaction/commit-failure-class.js +96 -0
  142. package/dist/src/transaction/commit-failure-class.js.map +1 -0
  143. package/dist/src/transaction/coordinator.d.ts +224 -31
  144. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  145. package/dist/src/transaction/coordinator.js +841 -362
  146. package/dist/src/transaction/coordinator.js.map +1 -1
  147. package/dist/src/transaction/entry-commit.d.ts +139 -0
  148. package/dist/src/transaction/entry-commit.d.ts.map +1 -0
  149. package/dist/src/transaction/entry-commit.js +199 -0
  150. package/dist/src/transaction/entry-commit.js.map +1 -0
  151. package/dist/src/transaction/index.d.ts +4 -1
  152. package/dist/src/transaction/index.d.ts.map +1 -1
  153. package/dist/src/transaction/index.js +1 -0
  154. package/dist/src/transaction/index.js.map +1 -1
  155. package/dist/src/transaction/transaction.d.ts +20 -0
  156. package/dist/src/transaction/transaction.d.ts.map +1 -1
  157. package/dist/src/transaction/validator.d.ts +7 -0
  158. package/dist/src/transaction/validator.d.ts.map +1 -1
  159. package/dist/src/transaction/validator.js +21 -12
  160. package/dist/src/transaction/validator.js.map +1 -1
  161. package/dist/src/transactor/change-notifier.d.ts +13 -4
  162. package/dist/src/transactor/change-notifier.d.ts.map +1 -1
  163. package/dist/src/transactor/change-notifier.js.map +1 -1
  164. package/dist/src/transactor/network-transactor.d.ts +58 -8
  165. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  166. package/dist/src/transactor/network-transactor.js +244 -50
  167. package/dist/src/transactor/network-transactor.js.map +1 -1
  168. package/dist/src/transactor/transactor-source.d.ts +22 -11
  169. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  170. package/dist/src/transactor/transactor-source.js +9 -13
  171. package/dist/src/transactor/transactor-source.js.map +1 -1
  172. package/dist/src/transactor/transactor.d.ts +14 -0
  173. package/dist/src/transactor/transactor.d.ts.map +1 -1
  174. package/dist/src/transform/digest.d.ts +20 -0
  175. package/dist/src/transform/digest.d.ts.map +1 -1
  176. package/dist/src/transform/digest.js +23 -3
  177. package/dist/src/transform/digest.js.map +1 -1
  178. package/dist/src/utility/visit-every.d.ts +14 -0
  179. package/dist/src/utility/visit-every.d.ts.map +1 -0
  180. package/dist/src/utility/visit-every.js +27 -0
  181. package/dist/src/utility/visit-every.js.map +1 -0
  182. package/package.json +1 -1
  183. package/src/blocks/helpers.ts +8 -1
  184. package/src/btree/btree.ts +266 -88
  185. package/src/btree/node-division.ts +155 -0
  186. package/src/chain/chain.ts +55 -6
  187. package/src/cluster/structs.ts +42 -7
  188. package/src/collection/action.ts +34 -0
  189. package/src/collection/collection.ts +1167 -540
  190. package/src/collection/head-commit.ts +148 -0
  191. package/src/collection/index.ts +2 -0
  192. package/src/collection/segments.ts +149 -0
  193. package/src/collection/struct.ts +201 -1
  194. package/src/collection/write-attempts.ts +506 -0
  195. package/src/collections/tree/struct.ts +97 -17
  196. package/src/collections/tree/tree.ts +129 -31
  197. package/src/index.ts +2 -0
  198. package/src/log/log.ts +7 -1
  199. package/src/network/block-size.ts +81 -0
  200. package/src/network/i-repo.ts +3 -0
  201. package/src/network/index.ts +5 -0
  202. package/src/network/promise-shortfall-error.ts +69 -0
  203. package/src/network/refuse-solo.ts +7 -0
  204. package/src/network/stale-failure.ts +27 -4
  205. package/src/network/struct.ts +169 -15
  206. package/src/network/transaction-size.ts +73 -0
  207. package/src/network/validity-rejected-error.ts +55 -0
  208. package/src/offline/entry.ts +127 -0
  209. package/src/offline/index.ts +4 -0
  210. package/src/offline/journal.ts +60 -0
  211. package/src/offline/queue.ts +1342 -0
  212. package/src/offline/reachability.ts +32 -0
  213. package/src/offline/status.ts +183 -0
  214. package/src/offline/wake.ts +67 -0
  215. package/src/reactivity/config.ts +8 -4
  216. package/src/reactivity/rotation.ts +9 -3
  217. package/src/testing/test-transactor.ts +65 -0
  218. package/src/transaction/commit-failure-class.ts +133 -0
  219. package/src/transaction/coordinator.ts +969 -393
  220. package/src/transaction/entry-commit.ts +285 -0
  221. package/src/transaction/index.ts +4 -0
  222. package/src/transaction/transaction.ts +21 -0
  223. package/src/transaction/validator.ts +22 -12
  224. package/src/transactor/change-notifier.ts +13 -4
  225. package/src/transactor/network-transactor.ts +252 -55
  226. package/src/transactor/transactor-source.ts +29 -13
  227. package/src/transactor/transactor.ts +16 -0
  228. package/src/transform/digest.ts +36 -3
  229. package/src/utility/visit-every.ts +25 -0
@@ -0,0 +1,32 @@
1
+ import type { BlockId } from '../blocks/structs.js';
2
+ import type { Collection } from '../collection/collection.js';
3
+
4
+ /**
5
+ * Whether the cohorts responsible for these blocks can be reached now — the gate of
6
+ * docs/offline-sync.md §When to submit. db-p2p implements it over the key network (stage 6);
7
+ * absent, the queue treats the cohort as always reachable ({@link alwaysReachable}), which is right
8
+ * for `TestTransactor`, the local transactor and the in-process mesh. Asked with each collection's
9
+ * header id and its last known log tail id, so an implementation resolves cohorts from routing keys
10
+ * alone and never needs the network to answer whether the network can be reached.
11
+ */
12
+ export interface ICohortReachability {
13
+ reachable(blockIds: readonly BlockId[]): Promise<boolean>;
14
+ /** Optionally call `listener` when reachability may have improved — a machine connected or was
15
+ * identified. A hint, not an answer: the listener asks `reachable` again. Returns an idempotent
16
+ * unsubscribe. Absent → nothing wakes the asker but its own timer. */
17
+ onChange?(listener: () => void): () => void;
18
+ }
19
+
20
+ /** The gate that is always open: what a queue over a transactor with no cohort to lose uses. */
21
+ export const alwaysReachable: ICohortReachability = {
22
+ reachable: () => Promise.resolve(true),
23
+ };
24
+
25
+ /** What a gate is asked with for one collection: its header id and its last known log tail id
26
+ * (`Collection.knownLogTailId`), when it knows one. The offline queue asks with these for every
27
+ * collection the head entry still has to commit, and the Quereus plugin's live-read degrade for the
28
+ * tree it is about to refresh, so the two ask one gate the same question. */
29
+ export function gateBlockIds(collection: Collection<any>): BlockId[] {
30
+ const tailId = collection.knownLogTailId();
31
+ return tailId === undefined ? [collection.id] : [collection.id, tailId];
32
+ }
@@ -0,0 +1,183 @@
1
+ import type { CollectionId } from '../collection/struct.js';
2
+ import type { EntryId } from '../collection/segments.js';
3
+ import type { TransactionDurability } from '../transaction/durability.js';
4
+
5
+ /**
6
+ * The status an offline-sync queue reports for each entry (docs/offline-sync.md §Following
7
+ * transactions), in its db-core form: collections stand in for tables. The plugin's `followed`,
8
+ * `persisted` and `outlook` are its own and never appear here — the outlook needs the catalog's tags
9
+ * and key decoding, which only the plugin has.
10
+ */
11
+
12
+ /** Why an entry failed. `constraint` and `concurrent-modification` are the two guard refusals
13
+ * (`refusalReason` in `packages/db-core/src/transaction/commit-failure-class.ts`); the other four
14
+ * are the queue's own: a validator judged the write invalid, it can never fit a message, it outlived
15
+ * `OfflineQueueOptions.expireAfterMs`, or the application withdrew it with `OfflineQueue.discard`. */
16
+ export type QueuedFailureReason = 'constraint' | 'concurrent-modification' | 'rejected' | 'too-large' | 'expired' | 'discarded';
17
+
18
+ /** What an entry still queued is waiting on: an earlier entry (the drain is strictly first in,
19
+ * first out), the cohort (the reachability gate said no, or the last attempt could not reach it),
20
+ * or the backoff timer after a transient failure. `undefined` for a head about to be submitted. */
21
+ export type EntryWaitingFor = 'earlier-entry' | 'cohort' | 'backoff';
22
+
23
+ /** What a committed entry did to the rows it wrote (docs/offline-sync.md §Guards that make idempotent
24
+ * writes assured): `already-applied` when every element that carried one of the already-applied guard
25
+ * kinds (`TreeAlreadyAppliedGuard` in `packages/db-core/src/collections/tree/struct.ts`) was skipped
26
+ * because a rival had already made exactly its change, and at least one did — summed over every
27
+ * collection the entry wrote (`AlreadyAppliedTally`); `applied` otherwise, including for an entry with
28
+ * no such element and for one of which any collection's tally was never heard — one a restore found
29
+ * already committed, or one committed before a restart lost the tally. "All, not any": an entry of two
30
+ * guarded updates of which one was already done did change a row, and a host reading
31
+ * `already-applied` as "none of my guarded changes landed" must be right — and a write under `absent`
32
+ * or `unchanged`, the main-table base kinds, counts as applied for the same reason. Says nothing about
33
+ * elements carrying no guard, `keepExisting` or `absentRange`, which are never counted. */
34
+ export type CommittedEffect = 'applied' | 'already-applied';
35
+
36
+ export type EntryStatus =
37
+ | {
38
+ kind: 'queued';
39
+ entryId: EntryId;
40
+ /** Per queue, monotonic: the order entries were queued in, which is the order they drain in. */
41
+ seq: number;
42
+ /** The collections the entry sealed a segment in — every collection it changed. */
43
+ collections: readonly CollectionId[];
44
+ queuedAt: number;
45
+ /** Submissions made so far. */
46
+ attempts: number;
47
+ /** Whether an attempt may have landed (see `OfflineQueue`'s in-doubt rule): such an entry can
48
+ * neither be discarded nor expired, and is re-sent only under its own action id. */
49
+ inDoubt: boolean;
50
+ waitingFor: EntryWaitingFor | undefined;
51
+ /** What the last attempt failed with, when one has. */
52
+ lastError?: unknown;
53
+ /** The collections of the entry already durably committed, once a submission has committed
54
+ * part of it (docs/offline-sync.md §Partial commits); absent while none is. */
55
+ committedCollections?: readonly CollectionId[];
56
+ }
57
+ | { kind: 'submitting'; entryId: EntryId; attempt: number }
58
+ | {
59
+ kind: 'committed';
60
+ entryId: EntryId;
61
+ /** Every collection the entry wrote, each with its class — across submissions, so a partly
62
+ * committed entry's earlier half is listed beside the remainder's. */
63
+ durability: TransactionDurability;
64
+ /** Whether the entry's guarded changes were already in place when it committed
65
+ * ({@link CommittedEffect}). */
66
+ effect: CommittedEffect;
67
+ }
68
+ | {
69
+ /** A submission committed part of the entry and not the rest (`CoordinatorPartialCommitError`).
70
+ * Emitted in place of the `queued` status that transition would otherwise report: the entry
71
+ * stays at the head, in doubt, and the drain drives the pending collections on the next
72
+ * submission. Between submissions `status` and `entries` report it `queued`, with
73
+ * `committedCollections` set. */
74
+ kind: 'partially-committed';
75
+ entryId: EntryId;
76
+ /** Every collection of the entry durably committed so far, across submissions. */
77
+ committedCollections: readonly CollectionId[];
78
+ /** The collections in which the entry is still a sealed segment: what the next submission drives. */
79
+ pendingCollections: readonly CollectionId[];
80
+ /** Why the rest did not commit: the partial commit's `reason` when that is an `Error`, otherwise
81
+ * the partial commit error itself (whose message names the reason). */
82
+ cause: Error;
83
+ }
84
+ | {
85
+ kind: 'failed';
86
+ entryId: EntryId;
87
+ reason: QueuedFailureReason;
88
+ error: Error;
89
+ /** The earlier entry whose removal made this one fail (docs/offline-sync.md §Removing an entry). */
90
+ causedBy?: EntryId;
91
+ /** The collections whose visible content this removal changed — the ones the entry still had a
92
+ * segment in when it was removed. */
93
+ changedCollections: readonly CollectionId[];
94
+ /** Set only when part of the entry had committed before the rest failed: the network now holds
95
+ * half of the transaction, which the application has to reconcile (docs/offline-sync.md
96
+ * §Partial commits). */
97
+ committedCollections?: readonly CollectionId[];
98
+ };
99
+
100
+ /** Queue-wide state, for a status bar. */
101
+ export type OfflineQueueState = {
102
+ depth: number;
103
+ oldestQueuedAt: number | undefined;
104
+ /** A submission is on the network. */
105
+ draining: boolean;
106
+ /** What the head is waiting on, when it is not an earlier entry. */
107
+ waitingFor: 'cohort' | 'backoff' | undefined;
108
+ /** Attempts whose failure the drain could not classify (`offline:unclassified-failure`); such an
109
+ * entry is retried rather than dropped, so a rising count with a stuck depth is the signal. */
110
+ unclassifiedFailures: number;
111
+ };
112
+
113
+ /** One entry as `OfflineQueue.entries` lists it: its identity and its current status. */
114
+ export type QueuedEntry = {
115
+ readonly id: EntryId;
116
+ readonly seq: number;
117
+ readonly queuedAt: number;
118
+ readonly collections: readonly CollectionId[];
119
+ /** As on the `queued` status: the collections already committed, once part of the entry is. */
120
+ readonly committedCollections?: readonly CollectionId[];
121
+ readonly status: EntryStatus;
122
+ };
123
+
124
+ /** Thrown by `OfflineQueue.discard` for an entry that cannot be withdrawn: it has been sent at least
125
+ * once and so may already be saved (`inDoubt`), or it is being submitted right now — and by the
126
+ * plugin's restore after a restart for a journaled entry a pass is putting back right now
127
+ * (`restoring`): withdrawn then, its outcome would be written while the queue goes on to admit and
128
+ * drive it. */
129
+ export class EntryNotDiscardableError extends Error {
130
+ constructor(
131
+ readonly entryId: EntryId,
132
+ readonly because: 'in-doubt' | 'submitting' | 'restoring',
133
+ ) {
134
+ super(notDiscardableMessage(entryId, because));
135
+ this.name = 'EntryNotDiscardableError';
136
+ }
137
+ }
138
+
139
+ function notDiscardableMessage(entryId: EntryId, because: EntryNotDiscardableError['because']): string {
140
+ switch (because) {
141
+ case 'in-doubt': return `entry ${entryId} has been sent at least once and may already be saved; it cannot be discarded`;
142
+ case 'submitting': return `entry ${entryId} is being submitted; it cannot be discarded`;
143
+ case 'restoring': return `entry ${entryId} is being put back from its journal record; it cannot be discarded until the pass has put it back`;
144
+ }
145
+ }
146
+
147
+ /** Thrown by `OfflineQueue.discard` for an id the queue does not hold — never queued, or already
148
+ * committed or failed. */
149
+ export class UnknownEntryError extends Error {
150
+ constructor(readonly entryId: EntryId) {
151
+ super(`entry ${entryId} is not queued`);
152
+ this.name = 'UnknownEntryError';
153
+ }
154
+ }
155
+
156
+ /** Thrown by `OfflineQueue.enqueue` after `dispose`, and the rejection of every `whenDrained` the
157
+ * disposal cut short. */
158
+ export class QueueDisposedError extends Error {
159
+ constructor() {
160
+ super('the offline queue has been disposed');
161
+ this.name = 'QueueDisposedError';
162
+ }
163
+ }
164
+
165
+ /** The error a discarded entry fails with (`reason: 'discarded'`): the application withdrew it. */
166
+ export class EntryDiscardedError extends Error {
167
+ constructor(readonly entryId: EntryId) {
168
+ super(`entry ${entryId} was discarded before it was sent`);
169
+ this.name = 'EntryDiscardedError';
170
+ }
171
+ }
172
+
173
+ /** The error an expired entry fails with (`reason: 'expired'`). */
174
+ export class EntryExpiredError extends Error {
175
+ constructor(
176
+ readonly entryId: EntryId,
177
+ readonly queuedAt: number,
178
+ readonly expiresAt: number,
179
+ ) {
180
+ super(`entry ${entryId} queued at ${queuedAt} was not settled by ${expiresAt}`);
181
+ this.name = 'EntryExpiredError';
182
+ }
183
+ }
@@ -0,0 +1,67 @@
1
+ import { jitteredBackoffMs } from '../utility/backoff.js';
2
+ import type { JitteredBackoffConfig, RandFn } from '../utility/backoff.js';
3
+ import { armUnrefTimer } from '../utility/unref-timer.js';
4
+
5
+ /**
6
+ * Where the drain loop parks, and what wakes it: a wake signal — a new local commit, a connection
7
+ * event, a disposal — and ONE re-check timer, shared by the reachability gate and the transient
8
+ * failures, whose delay climbs a jittered exponential step (`jitteredBackoffMs`) that a wake or a
9
+ * committed entry resets. A wake that finds nothing parked is kept and consumed by the next park, so
10
+ * a connection event that arrives during a submission is not lost (the cost: a transient failure
11
+ * right after such a wake is re-driven at once rather than after the backoff). The timer is unref'd,
12
+ * so an idle queue holds no process open, and the wake that pre-empts it cancels it.
13
+ */
14
+ export class DrainWaker {
15
+ private step = 0;
16
+ private waiter: (() => void) | undefined;
17
+ private pending = false;
18
+
19
+ constructor(private readonly config: JitteredBackoffConfig, private readonly rand: RandFn | undefined) {}
20
+
21
+ /** Wake whatever is parked, or keep the wake for the next park; either way the re-check step
22
+ * starts over. */
23
+ wake(): void {
24
+ this.step = 0;
25
+ const waiter = this.waiter;
26
+ if (waiter === undefined) {
27
+ this.pending = true;
28
+ return;
29
+ }
30
+ this.waiter = undefined;
31
+ waiter();
32
+ }
33
+
34
+ /** A committed entry: the cohort answered, so the next wait starts the climb over. */
35
+ resetBackoff(): void {
36
+ this.step = 0;
37
+ }
38
+
39
+ /** Park until {@link wake}; a wake that arrived meanwhile returns at once. */
40
+ untilWoken(): Promise<void> {
41
+ if (this.takePending()) return Promise.resolve();
42
+ return new Promise<void>(resolve => { this.waiter = resolve; });
43
+ }
44
+
45
+ /** Park until the re-check timer at the current step fires or {@link wake} is called, whichever
46
+ * is first. */
47
+ untilWokenOrTimer(): Promise<void> {
48
+ if (this.takePending()) return Promise.resolve();
49
+ const delayMs = jitteredBackoffMs(this.step++, this.config, this.rand);
50
+ return new Promise<void>(resolve => {
51
+ const cancelTimer = armUnrefTimer(() => {
52
+ this.waiter = undefined;
53
+ resolve();
54
+ }, delayMs);
55
+ this.waiter = () => {
56
+ cancelTimer();
57
+ resolve();
58
+ };
59
+ });
60
+ }
61
+
62
+ private takePending(): boolean {
63
+ if (!this.pending) return false;
64
+ this.pending = false;
65
+ return true;
66
+ }
67
+ }
@@ -43,9 +43,13 @@ export const SUBSCRIBER_TTL_CORE_MS = 90_000;
43
43
  /** Subscriber registration TTL on an Edge node (ms), inherited from cohort-topic. */
44
44
  export const SUBSCRIBER_TTL_EDGE_MS = 60_000;
45
45
  /**
46
- * Entries per log block — drives tail rotation. The collection log starts a new tail block every
47
- * `EntriesPerBlock` entries (`chain/chain.ts`), so this is that number, not a tunable of its own: the fill
48
- * tracker's warm-up and filling signals fire at the commit counts the log actually rotates at.
46
+ * Entries per log block — the most commits a tail block takes before the log rotates. The collection log
47
+ * starts a new tail block after `EntriesPerBlock` entries (`chain/chain.ts`), or sooner once the block
48
+ * reaches `BLOCK_TARGET_BYTES` (`network/block-size.ts`), so this is an upper bound, not a tunable of its
49
+ * own: a log of small entries rotates exactly here, while a log of large entries rotates earlier and its
50
+ * fill tracker's warm-up fires late or not at all. Nothing depends on the count being exact — the warm-up
51
+ * and filling signals are logged only, and live rotation is detected from observed tail changes
52
+ * (`ReactivityOriginationManager.observeTailCommit` in db-p2p).
49
53
  */
50
54
  export const BLOCK_FILL_SIZE_DEFAULT = EntriesPerBlock;
51
55
  /** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
@@ -73,7 +77,7 @@ export interface ReactivityConfig {
73
77
  readonly subscriberTtlCoreMs: number;
74
78
  /** Subscriber TTL on an Edge node (ms). */
75
79
  readonly subscriberTtlEdgeMs: number;
76
- /** Entries per log block — drives tail rotation; the log's `EntriesPerBlock`. */
80
+ /** Most entries per log block before the tail rotates — the log's `EntriesPerBlock`, an upper bound (see {@link BLOCK_FILL_SIZE_DEFAULT}). */
77
81
  readonly blockFillSize: number;
78
82
  /** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
79
83
  readonly tDrainMs: number;
@@ -2,7 +2,8 @@
2
2
  * Reactivity — tail rotation lifecycle (`docs/reactivity.md` §Anchor, §Tail rotation).
3
3
  *
4
4
  * A collection's topic is stable (`reactivityCollectionTopicId`, `topic-anchor.ts`); what rotates is its
5
- * **root**. When the tail block fills (`block_fill_size` entries, the log's `EntriesPerBlock`) a new tail
5
+ * **root**. When the tail block fills (at most `block_fill_size` entries, the log's `EntriesPerBlock`, or
6
+ * sooner by size — `BLOCK_TARGET_BYTES`) a new tail
6
7
  * block is born and the root — the tail's storage group at `H(tailId)` — moves to the new tail's group. The
7
8
  * tiers below the root sit at `coord_d(P, topicId)` and never move, so a rotation is "same topic, the root
8
9
  * moved": a registration at the root re-registers under the new root key; one below the root keeps its place
@@ -13,7 +14,8 @@
13
14
  * by {@link buildRotationHint} and detected subscriber-side by {@link detectRotation}.
14
15
  * - **Block-fill tracking** — {@link BlockFillTracker} counts transactions in the current tail block and
15
16
  * fires anticipatory **warm-up** at `block_fill_size − warm_threshold` and the **filling** signal at
16
- * `block_fill_size` (the commit that carries the hint).
17
+ * `block_fill_size` (the commit that carries the hint). The count is an upper bound: a log of large
18
+ * entries rolls over by size first, so for it the signals come late or not at all.
17
19
  * - **Drain** — {@link TailDrainGate} keeps the outgoing root serving renewals/replays for `T_drain` while
18
20
  * bouncing *new* subscriptions with a `Promoted`-shaped {@link RotationRedirectV1} naming the new tail.
19
21
  * - **Jittered re-registration** — {@link planReRegistration} / {@link planReRegistrationWave} schedule a
@@ -131,7 +133,7 @@ export type BlockFillSignal =
131
133
 
132
134
  /** Construction inputs for a {@link BlockFillTracker}. */
133
135
  export interface BlockFillTrackerInit {
134
- /** Entries per log block before the tail rotates (default {@link BLOCK_FILL_SIZE_DEFAULT}, the log's `EntriesPerBlock`). */
136
+ /** Most entries per log block before the tail rotates (default {@link BLOCK_FILL_SIZE_DEFAULT}, the log's `EntriesPerBlock`; a log of large entries rotates sooner, by size). */
135
137
  readonly blockFillSize?: number;
136
138
  /** Transactions remaining in the tail when anticipatory warm-up fires (default {@link WARM_THRESHOLD_DEFAULT}). */
137
139
  readonly warmThreshold?: number;
@@ -141,6 +143,10 @@ export interface BlockFillTrackerInit {
141
143
  * Counts transactions committed into the current tail block and emits the {@link BlockFillSignal} that
142
144
  * drives anticipatory warm-up and the block-filling rotation trigger (`docs/reactivity.md` §Tail rotation,
143
145
  * §Anticipatory warm-up). One tracker per collection on the tail-cohort primary.
146
+ *
147
+ * It counts commits only, so it assumes the block rotates at `blockFillSize`; a log that rolls over earlier
148
+ * by size leaves it out of step. That is harmless because nothing acts on its signals for correctness: a
149
+ * live node only logs them, and detects the rotation itself from the commit that names a new tail.
144
150
  */
145
151
  export class BlockFillTracker {
146
152
  readonly blockFillSize: number;
@@ -508,6 +508,18 @@ export abstract class DelegatingTransactor implements ITransactor {
508
508
  get queryClusterNominees(): ((blockId: BlockId) => Promise<ClusterNomineesResult>) | undefined {
509
509
  return this.inner.queryClusterNominees?.bind(this.inner);
510
510
  }
511
+
512
+ // Getters for the same reason: the coordinator treats their absence as "pend and commit each
513
+ // collection on its own". `TestTransactor` offers neither, so a wrapped one keeps that path.
514
+ get pendMany(): ITransactor['pendMany'] {
515
+ const inner: ITransactor = this.inner;
516
+ return inner.pendMany?.bind(inner);
517
+ }
518
+
519
+ get commitMany(): ITransactor['commitMany'] {
520
+ const inner: ITransactor = this.inner;
521
+ return inner.commitMany?.bind(inner);
522
+ }
511
523
  }
512
524
 
513
525
  /**
@@ -656,6 +668,36 @@ export class TailLandsButReportsStale extends DelegatingTransactor {
656
668
  }
657
669
  }
658
670
 
671
+ /**
672
+ * Answers every pend with a promise shortfall — the cohort's silence, in the shape
673
+ * `CoordinatorRepo.pend` returns it — and delegates nothing, so nothing is reserved and nothing
674
+ * lands. For the write paths' "stopped by name" cases: a shortfall is not a conflict a retry can
675
+ * win, so one attempt is made and `PromiseShortfallError` escapes with every staged action still
676
+ * staged.
677
+ */
678
+ export class RefusesPendsAsShortfall extends DelegatingTransactor {
679
+ /** Pends refused so far. */
680
+ pends = 0;
681
+ /** While `true` every pend is refused; set `false` to let pends through again — the cohort back
682
+ * in reach, for a test of what waits on it. */
683
+ refusing = true;
684
+
685
+ constructor(inner: TestTransactor) {
686
+ super(inner);
687
+ }
688
+
689
+ override async pend(request: PendRequest): Promise<PendResult> {
690
+ if (!this.refusing) return this.inner.pend(request);
691
+ this.pends++;
692
+ return {
693
+ success: false,
694
+ conflict: false,
695
+ reason: 'Failed to get super-majority: injected shortfall',
696
+ shortfall: { approvals: 1, rejections: 0, peerCount: 3, needed: 3, silentPeers: ['peer-b', 'peer-c'] },
697
+ };
698
+ }
699
+ }
700
+
659
701
  /** What one attempt of a write put on the wire: the pend's transforms, with the action id and
660
702
  * revision it was pended under. Recorded by {@link RecordsAttemptsRefusesFirstCommit}. */
661
703
  export type RecordedAttempt = {
@@ -857,6 +899,29 @@ export class GatedCommitTransactor extends DelegatingTransactor {
857
899
  openGate(): void { this.gate.resolve(); }
858
900
  }
859
901
 
902
+ /**
903
+ * Throws, nothing delegated, on every commit of the collection whose log tail is `tailId` while
904
+ * `armed` — the hard failure of one participant's commit after its siblings' landed, which a
905
+ * multi-collection commit reports as `CoordinatorPartialCommitError`. Disarmed, everything delegates.
906
+ */
907
+ export class ThrowsOnCommitOf extends DelegatingTransactor {
908
+ /** Commits thrown so far. */
909
+ thrown = 0;
910
+ armed = true;
911
+
912
+ constructor(inner: TestTransactor, private readonly tailId: BlockId) {
913
+ super(inner);
914
+ }
915
+
916
+ override async commit(request: CommitRequest): Promise<CommitResult> {
917
+ if (this.armed && request.tailId === this.tailId) {
918
+ this.thrown++;
919
+ throw new Error('connection dropped before the commit was sent');
920
+ }
921
+ return this.inner.commit(request);
922
+ }
923
+ }
924
+
860
925
  /**
861
926
  * Parks the FIRST pend BEFORE it reaches the inner transactor, so a rival can durably take the
862
927
  * revision while the coordinator is already committed to a set of transforms it captured at the
@@ -0,0 +1,133 @@
1
+ import { BlockUnavailableError, type BlockUnavailableReason } from "../network/struct.js";
2
+ import { PromiseShortfallError } from "../network/promise-shortfall-error.js";
3
+ import { ValidityRejectedError } from "../network/validity-rejected-error.js";
4
+ import { TransactionExpiredError } from "../network/transaction-expired-error.js";
5
+ import { TransactionTooLargeError } from "../network/transaction-size.js";
6
+ import { BlockTooLargeError } from "../network/block-size.js";
7
+ import { SyncRetryExhaustedError, TornActionError } from "../collection/struct.js";
8
+ import type { ActionRefusedError } from "../collection/struct.js";
9
+ import { TreeEntryChangedError, TreeGuardRefusedError } from "../collections/tree/struct.js";
10
+ import { CoordinatorPartialCommitError, CoordinatorStaleLossError } from "./errors.js";
11
+
12
+ /**
13
+ * What a failed commit attempt says about the write, sorted for a caller that has to decide whether
14
+ * to wait and send it again, give it up, or treat it as possibly saved (docs/offline-sync.md
15
+ * §Classifying an attempt's outcome). Each arm carries the error it was sorted from, narrowed to the
16
+ * classes that produce it.
17
+ *
18
+ * - `cohort-unreachable` — too few of the cohort answered, so the attempt that met it stored nothing.
19
+ * Wait for the cohort.
20
+ * - `contention` — the write lost races until its retry budget ran out and was not saved, though an
21
+ * earlier attempt's log entry may still stand (see {@link SyncRetryExhaustedError}). Back off.
22
+ * - `guard-refused` — a rival's commit made the write wrong: `constraint` for a uniqueness refusal,
23
+ * `concurrent-modification` for a lost update. Final.
24
+ * - `rejected` — the members that sank the write judged it invalid. Final.
25
+ * - `too-large` — the transaction, or a block it writes, is over the size limit. Final: it can never
26
+ * commit as it is.
27
+ * - `expired` — the attempt outlived its expiry; a new attempt gets a fresh one.
28
+ * - `torn-not-saved` — the write half-landed and is provably not saved; sending it again stores it once.
29
+ * - `in-doubt` — the write half-landed and may be saved or may still land.
30
+ * - `partial` — some collections of a multi-collection commit are saved and the rest are not.
31
+ * - `unknown` — anything else. Treat as in doubt: retry only under the attempt's own identity.
32
+ */
33
+ export type CommitFailureClass =
34
+ | { kind: 'cohort-unreachable'; error: PromiseShortfallError | BlockUnavailableError }
35
+ | { kind: 'contention'; error: SyncRetryExhaustedError | CoordinatorStaleLossError }
36
+ | { kind: 'guard-refused'; refusal: 'constraint' | 'concurrent-modification'; error: TreeGuardRefusedError }
37
+ | { kind: 'rejected'; error: ValidityRejectedError }
38
+ | { kind: 'too-large'; error: TransactionTooLargeError | BlockTooLargeError }
39
+ | { kind: 'expired'; error: TransactionExpiredError }
40
+ | { kind: 'torn-not-saved'; error: TornActionError }
41
+ | { kind: 'in-doubt'; error: TornActionError }
42
+ | { kind: 'partial'; error: CoordinatorPartialCommitError }
43
+ | { kind: 'unknown'; error: unknown };
44
+
45
+ /** The two unavailability reasons that mean the cohort could not be reached. The others are doubts
46
+ * about one block's read (a reconstruction gap, a claim nobody corroborated, a log naming a block
47
+ * nobody serves) and say nothing about whether a write could be sent. */
48
+ const cohortUnreachableReasons: ReadonlySet<BlockUnavailableReason> = new Set(['cohort-unreachable', 'peers-unreachable']);
49
+
50
+ /**
51
+ * Whether `error` is a read that failed because the cohort could not be reached: a
52
+ * {@link BlockUnavailableError} with one of the two unreachability reasons — exactly the errors
53
+ * {@link classifyCommitFailure} sorts as `cohort-unreachable` from that class. Every other
54
+ * unavailability reason is a doubt about one block that reaching the cohort would not settle. Shared
55
+ * with the Quereus plugin's live-read degrade (docs/offline-sync.md §Reads in offline mode), so a read
56
+ * served from this machine's own copy and a write left waiting for the cohort are sorted by one rule.
57
+ */
58
+ export function isCohortUnreachableRead(error: unknown): error is BlockUnavailableError {
59
+ return error instanceof BlockUnavailableError && cohortUnreachableReasons.has(error.reason);
60
+ }
61
+
62
+ /**
63
+ * Sorts a commit failure into a {@link CommitFailureClass} — the one place every commit failure is
64
+ * sorted, so no caller has to read an error's message to decide what to do with a write.
65
+ *
66
+ * Two rules keep the answer safe:
67
+ *
68
+ * - **Type only, never text.** It reads the error's class and the structured fields
69
+ * `BlockUnavailableError.reason` and `TornActionError.final`, never `message`.
70
+ * - **The error thrown, never its `cause`.** A commit-phase shortfall reaches a local writer nested
71
+ * as the `cause` of the transactor's plain `Some peers did not complete` aggregate; that write is
72
+ * in doubt, not "nothing sent", and walking `cause` would sort it as unreachable. A wrapper whose
73
+ * wrapping means something is its own arm (`CoordinatorPartialCommitError`).
74
+ *
75
+ * The Quereus bridge's mapped errors (`ConstraintError`, `ConcurrentModificationError`) are not
76
+ * recognised: classify the db-core error before mapping it.
77
+ *
78
+ * Classes are matched with `instanceof`, so an error constructed by a second copy of this package
79
+ * sorts as `unknown` — the conservative answer, but a host that installs two copies loses every
80
+ * other class. No guard in this repository checks for that.
81
+ */
82
+ export function classifyCommitFailure(error: unknown): CommitFailureClass {
83
+ if (error instanceof PromiseShortfallError) {
84
+ return { kind: 'cohort-unreachable', error };
85
+ }
86
+ if (error instanceof BlockUnavailableError) {
87
+ return isCohortUnreachableRead(error)
88
+ ? { kind: 'cohort-unreachable', error }
89
+ : { kind: 'unknown', error };
90
+ }
91
+ // `SyncRevisionStalledError` is a `SyncRetryExhaustedError`, so the base class covers it.
92
+ if (error instanceof SyncRetryExhaustedError || error instanceof CoordinatorStaleLossError) {
93
+ return { kind: 'contention', error };
94
+ }
95
+ if (error instanceof TreeGuardRefusedError) {
96
+ // Every guard refusal other than a lost update is a uniqueness refusal, including a subclass
97
+ // added later: the hierarchy's contract is that a refusal is never downgraded to retryable.
98
+ // NOTE: matched at the tree's class, not at its base `ActionRefusedError`, because the
99
+ // `constraint` / `concurrent-modification` split and the bridge's `mapRefusal` are tree
100
+ // vocabulary; the tree is the only collection type that refuses today. If another type ever
101
+ // throws an `ActionRefusedError`, widen this arm (and the `error` type on `guard-refused`)
102
+ // to the base, or its refusal sorts as `unknown` and the drain retries a final failure.
103
+ return { kind: 'guard-refused', refusal: refusalReason(error), error };
104
+ }
105
+ if (error instanceof ValidityRejectedError) {
106
+ return { kind: 'rejected', error };
107
+ }
108
+ if (error instanceof TransactionTooLargeError || error instanceof BlockTooLargeError) {
109
+ return { kind: 'too-large', error };
110
+ }
111
+ if (error instanceof TransactionExpiredError) {
112
+ return { kind: 'expired', error };
113
+ }
114
+ if (error instanceof TornActionError) {
115
+ return error.final ? { kind: 'torn-not-saved', error } : { kind: 'in-doubt', error };
116
+ }
117
+ if (error instanceof CoordinatorPartialCommitError) {
118
+ return { kind: 'partial', error };
119
+ }
120
+ return { kind: 'unknown', error };
121
+ }
122
+
123
+ /**
124
+ * The failure reason a guard refusal reports to an application: `concurrent-modification` for a lost
125
+ * update ({@link TreeEntryChangedError}), `constraint` for every other refusal — a uniqueness refusal,
126
+ * or a refusal by a collection type other than the tree, which has no finer vocabulary. The ONE
127
+ * mapping {@link classifyCommitFailure}'s `guard-refused` arm and the offline queue share — for the
128
+ * refusals a collection reports through `onSealedRefused`, which never pass through a commit — so the
129
+ * two cannot disagree about one error.
130
+ */
131
+ export function refusalReason(error: ActionRefusedError): 'constraint' | 'concurrent-modification' {
132
+ return error instanceof TreeEntryChangedError ? 'concurrent-modification' : 'constraint';
133
+ }