@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,285 @@
1
+ import type { ActionId, AlreadyAppliedTally, CollectionId } from "../index.js";
2
+ import type { ReadDependency, Transaction } from "./transaction.js";
3
+ import { clampPriority } from "./transaction.js";
4
+ import type { Collection, RefreshReport } from "../collection/collection.js";
5
+ import type { HeadCommitHandle } from "../collection/head-commit.js";
6
+ import type { EntryId } from "../collection/segments.js";
7
+ import type { InFlightAttempt, InFlightCycle } from "../collection/struct.js";
8
+ import type { StagedAttempt } from "../collection/write-attempts.js";
9
+ import { retainedAttempt } from "../collection/write-attempts.js";
10
+ import { visitEveryThenThrow } from "../utility/visit-every.js";
11
+ import { refuseSoloField } from "../network/refuse-solo.js";
12
+
13
+ /**
14
+ * What the coordinator's phases know about the write they are sending — everything they used to
15
+ * read off a `Transaction`: the action id every pend and commit names, the timestamp its log entries
16
+ * carry, the reads recorded on them, and the aged retry priority an unvalidated pend carries.
17
+ * `commit` and `execute` derive one from their transaction ({@link writeContextOf}); the per-entry
18
+ * commit (`TransactionCoordinator.commitEntry`) builds its own, since a queued entry has no
19
+ * transaction. A `TransactionStamp` is deliberately NOT fabricated for it: a stamp carries a peer id,
20
+ * a schema hash and an expiry, all of which would be lies for an entry.
21
+ */
22
+ export type WriteContext = {
23
+ readonly actionId: ActionId;
24
+ /** Stamped on every log entry of the write; fixed per write, never per attempt. */
25
+ readonly timestamp: number;
26
+ /** Recorded on every log entry of the write (`ActionEntry.reads`). */
27
+ readonly reads: readonly ReadDependency[];
28
+ /** Already clamped (`clampPriority`); 0 on a first attempt. */
29
+ readonly priority: number;
30
+ /** The write refuses to be committed by a lone coordinator that knows it is not alone
31
+ * (`SyncOptions.refuseSoloCommit`): spread onto every pend and commit request the phases build
32
+ * (`PendRequest.refuseSolo`, `CommitRequest.refuseSolo`). Absent rather than `false`. */
33
+ readonly refuseSolo?: true;
34
+ };
35
+
36
+ /** The write context of a transaction's attempt, read when the attempt starts: `commitAttempts` ages
37
+ * the transaction's priority between attempts, so it is read per attempt rather than once. `cycle`
38
+ * is what the commit was asked of every send ({@link InFlightCycle}). */
39
+ export function writeContextOf(transaction: Transaction, cycle: InFlightCycle = {}): WriteContext {
40
+ return {
41
+ actionId: transaction.id as ActionId,
42
+ timestamp: transaction.stamp.timestamp,
43
+ reads: transaction.reads,
44
+ priority: clampPriority(transaction.priority),
45
+ ...refuseSoloField(cycle.refuseSolo),
46
+ };
47
+ }
48
+
49
+ /**
50
+ * One queued entry's commit across the collections it wrote — the input of
51
+ * `TransactionCoordinator.commitEntry` (docs/offline-sync.md §One entry, one network transaction).
52
+ * The queue builds it; the identity fields are the queue's, exactly as `HeadCommitOptions` carries
53
+ * them for a one-collection entry (docs/offline-sync.md §Identity across attempts).
54
+ */
55
+ export type EntryCommit = {
56
+ readonly entryId: EntryId;
57
+ /** The action id every attempt of the entry runs under; re-supplied when an entry is re-driven
58
+ * after an attempt that may have landed, so the opening refresh recognises that attempt's log
59
+ * entries as the write's own. */
60
+ readonly actionId: ActionId;
61
+ /** The entry's local commit time: every participant's log entry carries it (`WriteIdentity`). */
62
+ readonly timestamp: number;
63
+ /** The collections the entry wrote, each of which must hold `entryId` as its HEAD sealed segment. */
64
+ readonly collectionIds: readonly CollectionId[];
65
+ /** Attempts an earlier `commitEntry` under this action id recorded through {@link recordAttempt}
66
+ * and did not resolve, per collection (see `HeadCommitOptions.resume`). */
67
+ readonly resume?: ReadonlyMap<CollectionId, InFlightAttempt>;
68
+ /** Write-ahead hook, awaited with every participant's attempt before any latch is released
69
+ * (see `HeadCommitOptions.recordAttempt`). A throw aborts the cycle with nothing sent. */
70
+ readonly recordAttempt?: (attempts: ReadonlyMap<CollectionId, InFlightAttempt>) => Promise<void>;
71
+ /** Called once per participant, under that collection's latch, with what its head segment accepted
72
+ * as already applied when the segment is dropped as committed — on the fold of a committed attempt,
73
+ * the committed half of a partial landing included, and when the opening refresh finds the
74
+ * entry's own log entry and consumes the head (see `HeadCommitOptions.onCommittedHead`, whose
75
+ * contract this is, per collection). */
76
+ readonly onCommittedHead?: (collectionId: CollectionId, applied: AlreadyAppliedTally) => void;
77
+ };
78
+
79
+ /** One collection's part in a refresh round between attempts
80
+ * (`TransactionCoordinator.refreshBetweenAttempts`): its refresh, and what to do once that refresh
81
+ * finished the write's own log entry. */
82
+ export type RefreshParticipant = {
83
+ readonly collectionId: CollectionId;
84
+ /** The refresh itself — `Collection.refreshInFlight` for a transaction's participant, the
85
+ * handle's `refresh` for an entry's — with the write's own report. */
86
+ refresh(report: RefreshReport, lastChance: boolean): Promise<void>;
87
+ /** Called after the refresh finished the write's own entry and the round recorded it as saved. */
88
+ saved?(): void;
89
+ };
90
+
91
+ /**
92
+ * The handles of one entry's participants — a `HeadCommitHandle` per collection the entry wrote —
93
+ * and the moves the per-entry commit makes over all of them in lock-step. The handles are opened in
94
+ * SORTED collection-id order, the order `TransactionCoordinator.commitOnce` acquires the same latches
95
+ * in, so a concurrent `commit` over overlapping collections cannot deadlock against this; they are
96
+ * held for the whole cycle and closed in reverse order by {@link close}. A participant leaves the set
97
+ * when it is saved — its refresh finished the entry's own log entry, or an attempt committed it
98
+ * while a sibling was refused — so the set is always what is left to commit.
99
+ */
100
+ export class EntryParticipants {
101
+ /** In sorted collection-id order. */
102
+ private readonly handles: Map<CollectionId, HeadCommitHandle>;
103
+
104
+ private constructor(private readonly entry: EntryCommit, handles: Map<CollectionId, HeadCommitHandle>) {
105
+ this.handles = handles;
106
+ }
107
+
108
+ /**
109
+ * Open a handle on every collection the entry wrote, in sorted collection-id order, under the
110
+ * entry's identity and with that collection's recorded attempt, if any, to resume from. Throws
111
+ * before opening anything — a defect of the caller — when the entry names no collection, names
112
+ * one twice (opening it twice would deadlock on its own latch) or names one `collections` does
113
+ * not hold; and closes the handles already opened when a later `openHeadCommit` throws (a
114
+ * `SealedSegmentsError` precondition, say), so no latch is left held. Every handle's cycle carries
115
+ * `cycle` ({@link InFlightCycle}), so a refresh that finishes a torn attempt re-sends it on the
116
+ * same terms the coordinator's own round sends it.
117
+ */
118
+ static async open(collections: ReadonlyMap<CollectionId, Collection<any>>, entry: EntryCommit, cycle: InFlightCycle = {}): Promise<EntryParticipants> {
119
+ if (entry.collectionIds.length === 0) {
120
+ throw new Error(`commitEntry ${entry.entryId}: an entry commit names at least one collection`);
121
+ }
122
+ const sorted = [...new Set(entry.collectionIds)].sort(compareCollectionIds);
123
+ if (sorted.length !== entry.collectionIds.length) {
124
+ throw new Error(`commitEntry ${entry.entryId}: a collection is named twice in ${entry.collectionIds.join(', ')}`);
125
+ }
126
+ const participants = sorted.map(collectionId => {
127
+ const collection = collections.get(collectionId);
128
+ if (!collection) {
129
+ throw new Error(`commitEntry ${entry.entryId}: collection ${collectionId} is not registered with this coordinator`);
130
+ }
131
+ return { collectionId, collection };
132
+ });
133
+ const handles = new Map<CollectionId, HeadCommitHandle>();
134
+ const onCommittedHead = entry.onCommittedHead;
135
+ try {
136
+ for (const { collectionId, collection } of participants) {
137
+ const resume = entry.resume?.get(collectionId);
138
+ handles.set(collectionId, await collection.openHeadCommit(entry.entryId,
139
+ { actionId: entry.actionId, timestamp: entry.timestamp },
140
+ {
141
+ ...cycle,
142
+ ...(resume === undefined ? {} : { resume }),
143
+ ...(onCommittedHead === undefined ? {} : { onCommittedHead: (applied: AlreadyAppliedTally) => onCommittedHead(collectionId, applied) }),
144
+ }));
145
+ }
146
+ } catch (err) {
147
+ closeAll(handles);
148
+ throw err;
149
+ }
150
+ return new EntryParticipants(entry, handles);
151
+ }
152
+
153
+ /** How many participants are left to commit. */
154
+ get size(): number {
155
+ return this.handles.size;
156
+ }
157
+
158
+ /** The participants left to commit, in sorted order. */
159
+ ids(): CollectionId[] {
160
+ return [...this.handles.keys()];
161
+ }
162
+
163
+ /** Every remaining participant as a refresh-round participant: its handle's refresh, and
164
+ * leaving the set once the refresh finished the entry's own log entry (the handle consumed the
165
+ * head meanwhile, `Collection.consumeHead`). A snapshot, since a saved participant leaves the
166
+ * set mid-round. */
167
+ refreshers(): RefreshParticipant[] {
168
+ return [...this.handles].map(([collectionId, handle]) => ({
169
+ collectionId,
170
+ refresh: (report, lastChance) => handle.refresh(report, lastChance),
171
+ saved: () => this.drop(collectionId),
172
+ }));
173
+ }
174
+
175
+ /** Build the attempt of every remaining participant, in sorted order, under the latches
176
+ * (`HeadCommitHandle.stage`). A throw — a participant's recorded refusal, a block too large to
177
+ * send — leaves nothing sent and nothing on any participant changed: an attempt is built on a
178
+ * tracker of its own. */
179
+ async stage(): Promise<Map<CollectionId, StagedAttempt>> {
180
+ const staged = new Map<CollectionId, StagedAttempt>();
181
+ for (const [collectionId, handle] of this.handles) {
182
+ staged.set(collectionId, await handle.stage());
183
+ }
184
+ return staged;
185
+ }
186
+
187
+ /** Every participant's attempt as the write-ahead hook and the retained attempt carry it. */
188
+ retainedAttempts(staged: ReadonlyMap<CollectionId, StagedAttempt>): Map<CollectionId, InFlightAttempt> {
189
+ return new Map([...staged].map(([collectionId, attempt]) => [collectionId, retainedAttempt(attempt, this.entry.actionId)]));
190
+ }
191
+
192
+ /** Release every participant's latch for the network round; see `HeadCommitHandle.release`. */
193
+ release(): void {
194
+ for (const handle of this.handles.values()) {
195
+ handle.release();
196
+ }
197
+ }
198
+
199
+ /** Retake every participant's latch, in sorted order, every one even after one throws (a throw
200
+ * here is a driver defect, and a handle left released is tolerated by {@link close}). */
201
+ retake(): Promise<void> {
202
+ return visitEveryThenThrow(this.handles.values(), handle => handle.retake());
203
+ }
204
+
205
+ /**
206
+ * The local treatment of the participants in `ids`, which an attempt committed: fold every one's
207
+ * attempt in one await-free pass (`HeadCommitHandle.fold` — the head segment removed, the
208
+ * attempt's transforms in the cache, its revision adopted), so a committed read observes every
209
+ * committed participant pre-fold or post-fold, the event-loop atomicity
210
+ * `TransactionCoordinator.commitOnceLatched`'s success fold promises; then replay each one's
211
+ * remaining segments over the committed state (`HeadCommitHandle.replay`), every one even after
212
+ * one throws; then close them, since they are saved and leave the set.
213
+ */
214
+ async landed(staged: ReadonlyMap<CollectionId, StagedAttempt>, ids: Iterable<CollectionId>): Promise<void> {
215
+ const committed = [...ids].map(collectionId => ({ collectionId, handle: this.handle(collectionId), attempt: staged.get(collectionId) }));
216
+ for (const { collectionId, handle, attempt } of committed) {
217
+ if (attempt === undefined) {
218
+ throw new Error(`commitEntry ${this.entry.entryId}: no attempt was staged for committed participant ${collectionId}`);
219
+ }
220
+ handle.fold(attempt);
221
+ }
222
+ try {
223
+ await visitEveryThenThrow(committed, ({ handle }) => handle.replay());
224
+ } finally {
225
+ for (const { collectionId } of committed) {
226
+ this.drop(collectionId);
227
+ }
228
+ }
229
+ }
230
+
231
+ /** The participants in `ids` had their attempt refused: re-check each one's recorded refusal and
232
+ * retain its attempt for the next refresh to finish from (`HeadCommitHandle.refused`), every one
233
+ * even after one throws, then throw the first recorded refusal met. */
234
+ refused(staged: ReadonlyMap<CollectionId, StagedAttempt>, ids: Iterable<CollectionId>): void {
235
+ let first: { error: unknown } | undefined;
236
+ for (const collectionId of ids) {
237
+ const attempt = staged.get(collectionId);
238
+ if (attempt === undefined) {
239
+ throw new Error(`commitEntry ${this.entry.entryId}: no attempt was staged for refused participant ${collectionId}`);
240
+ }
241
+ try {
242
+ this.handle(collectionId).refused(attempt);
243
+ } catch (error) {
244
+ first ??= { error };
245
+ }
246
+ }
247
+ if (first !== undefined) {
248
+ throw first.error;
249
+ }
250
+ }
251
+
252
+ /** Close every remaining handle, in reverse order. Idempotent, like the handles' own `close`. */
253
+ close(): void {
254
+ closeAll(this.handles);
255
+ this.handles.clear();
256
+ }
257
+
258
+ /** A participant leaves the set: its handle is closed (the latch released, the marks cleared). */
259
+ private drop(collectionId: CollectionId): void {
260
+ this.handle(collectionId).close();
261
+ this.handles.delete(collectionId);
262
+ }
263
+
264
+ private handle(collectionId: CollectionId): HeadCommitHandle {
265
+ const handle = this.handles.get(collectionId);
266
+ if (handle === undefined) {
267
+ throw new Error(`commitEntry ${this.entry.entryId}: ${collectionId} is not a remaining participant`);
268
+ }
269
+ return handle;
270
+ }
271
+ }
272
+
273
+ /** The latch-acquisition order of `TransactionCoordinator.commitOnce` and `execute`, spelled the
274
+ * same way: a plain string comparison. Change all three together. */
275
+ function compareCollectionIds(a: CollectionId, b: CollectionId): number {
276
+ return a < b ? -1 : a > b ? 1 : 0;
277
+ }
278
+
279
+ /** Close `handles` in reverse order of opening — latches are released in the reverse of the order
280
+ * they were taken, as the coordinator's commit span releases its. */
281
+ function closeAll(handles: ReadonlyMap<CollectionId, HeadCommitHandle>): void {
282
+ for (const handle of [...handles.values()].reverse()) {
283
+ handle.close();
284
+ }
285
+ }
@@ -8,6 +8,7 @@ export type {
8
8
  ExecutionResult,
9
9
  CollectionActions,
10
10
  ValidationResult,
11
+ ValidityRejection,
11
12
  ITransactionValidator,
12
13
  ActionsStatement,
13
14
  TransactionSigner,
@@ -37,8 +38,11 @@ export { ReadDependencyCollector } from './read-dependency-collector.js';
37
38
  export { TransactionCoordinator } from './coordinator.js';
38
39
  export type { CoordinatorOptions, PendValidationMode } from './coordinator.js';
39
40
  export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from './errors.js';
41
+ export { classifyCommitFailure, isCohortUnreachableRead, refusalReason } from './commit-failure-class.js';
42
+ export type { CommitFailureClass } from './commit-failure-class.js';
40
43
  export { transactionDurability, recordCollectionDurability } from './durability.js';
41
44
  export type { TransactionDurability } from './durability.js';
45
+ export type { EntryCommit } from './entry-commit.js';
42
46
  export { TransactionSession } from './session.js';
43
47
  export { TransactionValidator } from './validator.js';
44
48
  export type { EngineRegistration, ValidationCoordinatorFactory, BlockStateProvider } from './validator.js';
@@ -423,6 +423,25 @@ export type ActionsStatement = {
423
423
  collections: CollectionActions[];
424
424
  };
425
425
 
426
+ /**
427
+ * The structured class on a refusal that judges the transaction ITSELF wrong: the checker re-ran it,
428
+ * or checked what it claims about itself, and found it false. Such a refusal fails the same way on
429
+ * every retry and at every honest validator.
430
+ *
431
+ * Present only for that class. A refusal that is out of date (a stale read), expired, or that this
432
+ * node could not judge (an unknown engine, a schema it does not hold, an operations-hash format it
433
+ * does not produce, a checker that threw) carries none — so absent means "not known to be a validity
434
+ * judgement", which is also what an older build that never sets it means.
435
+ *
436
+ * It exists because the refusal's `reason` is free-form prose that must never become control flow: a
437
+ * cluster member signs this into its reject vote (`Signature`'s `validity`), and that signed marker is
438
+ * what lets a writer tell "refused for good" from "try again".
439
+ */
440
+ export type ValidityRejection = {
441
+ /** The operations hash this node computed by re-executing the transaction, when it got that far. */
442
+ computedHash?: string;
443
+ };
444
+
426
445
  /**
427
446
  * Result of transaction validation.
428
447
  */
@@ -433,6 +452,8 @@ export type ValidationResult = {
433
452
  reason?: string;
434
453
  /** The operations hash computed during validation (for debugging) */
435
454
  computedHash?: string;
455
+ /** Set only on a failure that judges the transaction itself wrong; see {@link ValidityRejection}. */
456
+ validity?: ValidityRejection;
436
457
  };
437
458
 
438
459
  /**
@@ -33,11 +33,28 @@ export type ValidationCoordinatorFactory = () => {
33
33
  */
34
34
  export type BlockStateProvider = (blockId: BlockId) => Promise<BlockActionState | undefined>;
35
35
 
36
+ /**
37
+ * A refusal that judges the transaction itself wrong, marked so (see {@link ValidityRejection}).
38
+ * `computedHash` is this node's own re-execution result, present once re-execution produced one.
39
+ */
40
+ function validityRefusal(reason: string, computedHash?: string): ValidationResult {
41
+ return computedHash === undefined
42
+ ? { valid: false, reason, validity: {} }
43
+ : { valid: false, reason, computedHash, validity: { computedHash } };
44
+ }
45
+
36
46
  /**
37
47
  * Transaction validator implementation.
38
48
  *
39
49
  * Validates transactions by re-executing them and comparing operations hash.
40
50
  * Used by cluster participants when receiving PendRequests.
51
+ *
52
+ * Every refusal is classed, because a writer and the dispute path act on the class and must never
53
+ * read the prose to find it. Five refusals judge the transaction itself wrong and carry
54
+ * `validity` ({@link validityRefusal}): a tampered stamp, a missing or invalid client signature, a
55
+ * failed re-execution, and an operations-hash mismatch. The rest carry none: an expired stamp (a
56
+ * clock judgement), a stale read (out of date — a re-read can win), and an unknown engine, a schema
57
+ * mismatch or an operations-hash format this node does not produce (this node cannot judge).
41
58
  */
42
59
  export class TransactionValidator implements ITransactionValidator {
43
60
  constructor(
@@ -56,7 +73,7 @@ export class TransactionValidator implements ITransactionValidator {
56
73
  // a tampered stamp corrupts expiration and engine selection regardless of signatures.
57
74
  const expectedId = await computeStampId(stamp);
58
75
  if (expectedId !== stamp.id) {
59
- return { valid: false, reason: 'Tampered transaction stamp' };
76
+ return validityRefusal('Tampered transaction stamp');
60
77
  }
61
78
 
62
79
  // 0. Check expiration before any other work. Ordered BEFORE the signature check so
@@ -73,11 +90,11 @@ export class TransactionValidator implements ITransactionValidator {
73
90
  // both pass — the p2p enforcement flag decides whether to inject the port at all.
74
91
  if (this.verifyClientSignature) {
75
92
  if (transaction.signature === undefined) {
76
- return { valid: false, reason: 'Missing client signature' };
93
+ return validityRefusal('Missing client signature');
77
94
  }
78
95
  const payload = clientSignaturePayload(stamp.id, transaction.statements, transaction.reads);
79
96
  if (!this.verifyClientSignature(stamp.peerId, payload, transaction.signature)) {
80
- return { valid: false, reason: 'Invalid client signature' };
97
+ return validityRefusal('Invalid client signature');
81
98
  }
82
99
  }
83
100
 
@@ -137,10 +154,7 @@ export class TransactionValidator implements ITransactionValidator {
137
154
  // skipped by the empty-actions guard.
138
155
  const result = await registration.engine.execute(transaction);
139
156
  if (!result.success) {
140
- return {
141
- valid: false,
142
- reason: `Re-execution failed: ${result.error}`
143
- };
157
+ return validityRefusal(`Re-execution failed: ${result.error}`);
144
158
  }
145
159
 
146
160
  // 6. Apply actions to the isolated validation coordinator (builds transforms).
@@ -176,11 +190,7 @@ export class TransactionValidator implements ITransactionValidator {
176
190
  computedHash
177
191
  };
178
192
  }
179
- return {
180
- valid: false,
181
- reason: `Operations hash mismatch`,
182
- computedHash
183
- };
193
+ return validityRefusal('Operations hash mismatch', computedHash);
184
194
  }
185
195
 
186
196
  return { valid: true, computedHash };
@@ -67,10 +67,19 @@ export type CommitCert = {
67
67
 
68
68
  export interface IBlockChangeNotifier {
69
69
  /**
70
- * Subscribe to commits that mutate the given collection. Returns an
71
- * idempotent unsubscribe. Listeners are invoked AFTER the commit's critical
72
- * section (locks released), synchronously in commit order; a throwing
73
- * listener must not break the commit or other listeners (log + continue).
70
+ * Subscribe to commits that mutate the given collection. Returns an idempotent unsubscribe.
71
+ * Listeners are invoked AFTER the commit's critical section (locks released), in commit order,
72
+ * never from inside it; a throwing listener must not break the commit or other listeners (log +
73
+ * continue).
74
+ *
75
+ * A listener may be invoked later than the call that landed the change: a transaction that
76
+ * writes several collections (a table and its indexes) commits each as its own request under one
77
+ * action id, and a node's storage holds one collection's event while another collection of the
78
+ * same action is still pending there, releasing it when that collection lands, is cancelled, or
79
+ * a bound elapses (`StorageRepo.emitCollectionChanges` in
80
+ * `packages/db-p2p/src/storage/storage-repo.ts`). So an event may arrive from a later call of
81
+ * the storage, or from a timer, and a held event can fire after the event of a commit that landed
82
+ * later. Every change still produces exactly one event.
74
83
  */
75
84
  onCollectionChange(collectionId: CollectionId, listener: CollectionChangeListener): () => void;
76
85
  }