@optimystic/db-core 1.21.0 → 1.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. package/README.md +8 -4
  2. package/dist/src/btree/btree.d.ts +36 -4
  3. package/dist/src/btree/btree.d.ts.map +1 -1
  4. package/dist/src/btree/btree.js +86 -18
  5. package/dist/src/btree/btree.js.map +1 -1
  6. package/dist/src/collection/action.d.ts +7 -4
  7. package/dist/src/collection/action.d.ts.map +1 -1
  8. package/dist/src/collection/action.js +13 -5
  9. package/dist/src/collection/action.js.map +1 -1
  10. package/dist/src/collection/collection.d.ts +177 -51
  11. package/dist/src/collection/collection.d.ts.map +1 -1
  12. package/dist/src/collection/collection.js +265 -81
  13. package/dist/src/collection/collection.js.map +1 -1
  14. package/dist/src/collection/struct.d.ts +44 -8
  15. package/dist/src/collection/struct.d.ts.map +1 -1
  16. package/dist/src/collection/struct.js.map +1 -1
  17. package/dist/src/collection/write-attempts.d.ts +138 -34
  18. package/dist/src/collection/write-attempts.d.ts.map +1 -1
  19. package/dist/src/collection/write-attempts.js +168 -101
  20. package/dist/src/collection/write-attempts.js.map +1 -1
  21. package/dist/src/collections/diary/diary.d.ts.map +1 -1
  22. package/dist/src/collections/diary/diary.js +5 -1
  23. package/dist/src/collections/diary/diary.js.map +1 -1
  24. package/dist/src/collections/tree/tree.d.ts +18 -10
  25. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  26. package/dist/src/collections/tree/tree.js +17 -9
  27. package/dist/src/collections/tree/tree.js.map +1 -1
  28. package/dist/src/hlc/clock-store.d.ts +63 -0
  29. package/dist/src/hlc/clock-store.d.ts.map +1 -0
  30. package/dist/src/hlc/clock-store.js +49 -0
  31. package/dist/src/hlc/clock-store.js.map +1 -0
  32. package/dist/src/hlc/clock.d.ts +64 -0
  33. package/dist/src/hlc/clock.d.ts.map +1 -0
  34. package/dist/src/hlc/clock.js +171 -0
  35. package/dist/src/hlc/clock.js.map +1 -0
  36. package/dist/src/hlc/hlc.d.ts +38 -0
  37. package/dist/src/hlc/hlc.d.ts.map +1 -0
  38. package/dist/src/hlc/hlc.js +41 -0
  39. package/dist/src/hlc/hlc.js.map +1 -0
  40. package/dist/src/hlc/index.d.ts +5 -0
  41. package/dist/src/hlc/index.d.ts.map +1 -0
  42. package/dist/src/hlc/index.js +5 -0
  43. package/dist/src/hlc/index.js.map +1 -0
  44. package/dist/src/hlc/skew.d.ts +35 -0
  45. package/dist/src/hlc/skew.d.ts.map +1 -0
  46. package/dist/src/hlc/skew.js +35 -0
  47. package/dist/src/hlc/skew.js.map +1 -0
  48. package/dist/src/index.d.ts +2 -0
  49. package/dist/src/index.d.ts.map +1 -1
  50. package/dist/src/index.js +2 -0
  51. package/dist/src/index.js.map +1 -1
  52. package/dist/src/lane/index.d.ts +2 -0
  53. package/dist/src/lane/index.d.ts.map +1 -0
  54. package/dist/src/lane/index.js +2 -0
  55. package/dist/src/lane/index.js.map +1 -0
  56. package/dist/src/lane/lane.d.ts +46 -0
  57. package/dist/src/lane/lane.d.ts.map +1 -0
  58. package/dist/src/lane/lane.js +26 -0
  59. package/dist/src/lane/lane.js.map +1 -0
  60. package/dist/src/log/log.d.ts +50 -22
  61. package/dist/src/log/log.d.ts.map +1 -1
  62. package/dist/src/log/log.js +21 -13
  63. package/dist/src/log/log.js.map +1 -1
  64. package/dist/src/log/struct.d.ts +61 -1
  65. package/dist/src/log/struct.d.ts.map +1 -1
  66. package/dist/src/log/struct.js +24 -0
  67. package/dist/src/log/struct.js.map +1 -1
  68. package/dist/src/network/i-repo.d.ts +10 -0
  69. package/dist/src/network/i-repo.d.ts.map +1 -1
  70. package/dist/src/network/stale-failure.d.ts +20 -7
  71. package/dist/src/network/stale-failure.d.ts.map +1 -1
  72. package/dist/src/network/stale-failure.js +29 -7
  73. package/dist/src/network/stale-failure.js.map +1 -1
  74. package/dist/src/network/struct.d.ts +50 -0
  75. package/dist/src/network/struct.d.ts.map +1 -1
  76. package/dist/src/network/struct.js.map +1 -1
  77. package/dist/src/offline/entry.d.ts +14 -0
  78. package/dist/src/offline/entry.d.ts.map +1 -1
  79. package/dist/src/offline/entry.js +2 -0
  80. package/dist/src/offline/entry.js.map +1 -1
  81. package/dist/src/offline/journal.d.ts +10 -0
  82. package/dist/src/offline/journal.d.ts.map +1 -1
  83. package/dist/src/offline/queue.d.ts +10 -0
  84. package/dist/src/offline/queue.d.ts.map +1 -1
  85. package/dist/src/offline/queue.js +29 -3
  86. package/dist/src/offline/queue.js.map +1 -1
  87. package/dist/src/offline/status.d.ts +7 -0
  88. package/dist/src/offline/status.d.ts.map +1 -1
  89. package/dist/src/offline/status.js.map +1 -1
  90. package/dist/src/testing/test-transactor.d.ts +9 -1
  91. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  92. package/dist/src/testing/test-transactor.js +12 -3
  93. package/dist/src/testing/test-transactor.js.map +1 -1
  94. package/dist/src/transaction/actions-engine.d.ts +3 -0
  95. package/dist/src/transaction/actions-engine.d.ts.map +1 -1
  96. package/dist/src/transaction/actions-engine.js +3 -0
  97. package/dist/src/transaction/actions-engine.js.map +1 -1
  98. package/dist/src/transaction/coordinator.d.ts +16 -5
  99. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  100. package/dist/src/transaction/coordinator.js +203 -48
  101. package/dist/src/transaction/coordinator.js.map +1 -1
  102. package/dist/src/transaction/entry-commit.d.ts +45 -10
  103. package/dist/src/transaction/entry-commit.d.ts.map +1 -1
  104. package/dist/src/transaction/entry-commit.js +20 -7
  105. package/dist/src/transaction/entry-commit.js.map +1 -1
  106. package/dist/src/transaction/errors.d.ts +69 -1
  107. package/dist/src/transaction/errors.d.ts.map +1 -1
  108. package/dist/src/transaction/errors.js +70 -1
  109. package/dist/src/transaction/errors.js.map +1 -1
  110. package/dist/src/transaction/index.d.ts +1 -1
  111. package/dist/src/transaction/index.d.ts.map +1 -1
  112. package/dist/src/transaction/index.js +1 -1
  113. package/dist/src/transaction/index.js.map +1 -1
  114. package/dist/src/transaction/session.d.ts.map +1 -1
  115. package/dist/src/transaction/session.js +18 -5
  116. package/dist/src/transaction/session.js.map +1 -1
  117. package/dist/src/transaction/transaction.d.ts +74 -15
  118. package/dist/src/transaction/transaction.d.ts.map +1 -1
  119. package/dist/src/transaction/transaction.js +35 -15
  120. package/dist/src/transaction/transaction.js.map +1 -1
  121. package/dist/src/transaction/validator.d.ts +25 -4
  122. package/dist/src/transaction/validator.d.ts.map +1 -1
  123. package/dist/src/transaction/validator.js +45 -5
  124. package/dist/src/transaction/validator.js.map +1 -1
  125. package/dist/src/transactor/block-floors.d.ts +12 -1
  126. package/dist/src/transactor/block-floors.d.ts.map +1 -1
  127. package/dist/src/transactor/block-floors.js +14 -1
  128. package/dist/src/transactor/block-floors.js.map +1 -1
  129. package/dist/src/transactor/network-transactor.d.ts +8 -0
  130. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  131. package/dist/src/transactor/network-transactor.js +9 -4
  132. package/dist/src/transactor/network-transactor.js.map +1 -1
  133. package/dist/src/transactor/transactor-source.d.ts +11 -0
  134. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  135. package/dist/src/transactor/transactor-source.js +5 -1
  136. package/dist/src/transactor/transactor-source.js.map +1 -1
  137. package/dist/src/transactor/transactor.d.ts +8 -0
  138. package/dist/src/transactor/transactor.d.ts.map +1 -1
  139. package/dist/src/transform/cache-source.d.ts +7 -0
  140. package/dist/src/transform/cache-source.d.ts.map +1 -1
  141. package/dist/src/transform/cache-source.js +14 -18
  142. package/dist/src/transform/cache-source.js.map +1 -1
  143. package/package.json +1 -1
  144. package/src/btree/btree.ts +92 -18
  145. package/src/collection/action.ts +13 -5
  146. package/src/collection/collection.ts +3272 -3039
  147. package/src/collection/struct.ts +493 -456
  148. package/src/collection/write-attempts.ts +213 -109
  149. package/src/collections/diary/diary.ts +5 -1
  150. package/src/collections/tree/tree.ts +33 -18
  151. package/src/hlc/clock-store.ts +68 -0
  152. package/src/hlc/clock.ts +196 -0
  153. package/src/hlc/hlc.ts +56 -0
  154. package/src/hlc/index.ts +4 -0
  155. package/src/hlc/skew.ts +55 -0
  156. package/src/index.ts +2 -0
  157. package/src/lane/index.ts +1 -0
  158. package/src/lane/lane.ts +54 -0
  159. package/src/log/log.ts +341 -310
  160. package/src/log/struct.ts +62 -1
  161. package/src/network/i-repo.ts +11 -1
  162. package/src/network/stale-failure.ts +31 -7
  163. package/src/network/struct.ts +50 -0
  164. package/src/offline/entry.ts +16 -0
  165. package/src/offline/journal.ts +10 -0
  166. package/src/offline/queue.ts +38 -4
  167. package/src/offline/status.ts +7 -0
  168. package/src/testing/test-transactor.ts +1065 -1050
  169. package/src/transaction/actions-engine.ts +3 -0
  170. package/src/transaction/coordinator.ts +235 -54
  171. package/src/transaction/entry-commit.ts +56 -14
  172. package/src/transaction/errors.ts +60 -0
  173. package/src/transaction/index.ts +1 -1
  174. package/src/transaction/session.ts +18 -5
  175. package/src/transaction/transaction.ts +90 -17
  176. package/src/transaction/validator.ts +46 -5
  177. package/src/transactor/block-floors.ts +15 -1
  178. package/src/transactor/network-transactor.ts +1908 -1896
  179. package/src/transactor/transactor-source.ts +15 -1
  180. package/src/transactor/transactor.ts +9 -0
  181. package/src/transform/cache-source.ts +15 -17
@@ -1,1050 +1,1065 @@
1
- import type { ITransactor, GetBlockResults, ActionBlocks, ActionLineage, BlockLineage, BlockActionStatus, PendResult, CommitResult, PendRequest, BlockId, CommitRequest, BlockGets, IBlock, ActionId, ActionRev, ActionTransforms, StaleFailure, Transform, Transforms, ClusterNomineesResult, CollectionId } from "../index.js";
2
- import { highestStaleAt, isOwnRevision } from "../network/stale-failure.js";
3
- import { localDurability } from "../network/durability.js";
4
- import { ensuredMap } from "../utility/ensured.js";
5
- import { Latches } from "../utility/latches.js";
6
- import { applyTransform, blockIdsForTransforms, transformForBlockId, emptyTransforms, concatTransform, transformsFromTransform } from "../transform/index.js";
7
- import { Tree } from "../collections/tree/tree.js";
8
- import type { TreeReplaceAction } from "../collections/tree/struct.js";
9
- import type { Collection } from "../collection/collection.js";
10
-
11
- type RevisionNumber = number;
12
-
13
- type BlockState = {
14
- /** The current materialized block at each revision */
15
- materializedBlocks: Map<RevisionNumber, IBlock>;
16
- /** The latest revision number */
17
- latestRev: RevisionNumber;
18
- /** The action that created each revision */
19
- revisionActions: Map<RevisionNumber, ActionId>;
20
- /** Currently pending actions */
21
- pendingActions: Map<ActionId, Transform>;
22
- /** Committed actions */
23
- committedActions: Map<ActionId, Transform>;
24
- }
25
-
26
- // Simple in-memory transactor for testing that maintains materialized blocks for every revision
27
- export class TestTransactor implements ITransactor {
28
- private blocks = new Map<BlockId, BlockState>();
29
- available = true;
30
- private getLocks = new Map<BlockId, Promise<() => void>>(); // Track lock releases
31
-
32
- constructor() {}
33
-
34
- async get(blockGets: BlockGets): Promise<GetBlockResults> {
35
- this.checkAvailable();
36
- const results: GetBlockResults = {};
37
- const uniqueBlockIds = [...new Set(blockGets.blockIds)].sort(); // Ensure consistent lock order if needed, though get is read-only
38
- const releases: (() => void)[] = [];
39
-
40
- try {
41
- // Acquire locks for all requested blocks to ensure consistent read
42
- for (const blockId of uniqueBlockIds) {
43
- const lockId = `TestTransactor.commit:${blockId}`; // Use the same lock as commit
44
- // Wait for any existing lock promise to resolve before acquiring the next
45
- let release = await this.getLocks.get(lockId);
46
- if (release) await Promise.resolve(release); // Ensure previous lock released if overlapping calls happen
47
-
48
- const releasePromise = Latches.acquire(lockId);
49
- this.getLocks.set(blockId, releasePromise.then(r => () => {
50
- r();
51
- this.getLocks.delete(blockId); // Clean up map entry after release
52
- }));
53
- release = await releasePromise;
54
- releases.push(release);
55
- }
56
-
57
- // --- Start of Critical Section (Read) ---
58
- for (const blockId of blockGets.blockIds) {
59
- const blockState = this.blocks.get(blockId);
60
- if (!blockState) {
61
- // Block doesn't exist yet
62
- results[blockId] = {
63
- block: undefined,
64
- state: { latest: undefined, pendings: [] }
65
- };
66
- continue;
67
- }
68
-
69
- // Get the appropriate materialized block based on context
70
- let block: IBlock | undefined;
71
- // The revision `block` was actually materialized at, reported (with its action id) as
72
- // GetBlockResult.materialized. Equals `latestRev` on every unpinned path; only a
73
- // revision-pinned read of a block committed further since the pin makes them differ,
74
- // and there the pinned value is what the reader observed (see the field's doc).
75
- let materializedRev: number | undefined;
76
- // A named pending is overlaid only where this block holds it; every other block gets the
77
- // plain answer for the same context (mirrors StorageRepo.get).
78
- const pin = blockGets.context?.rev;
79
- const namedPending = blockGets.context?.actionId !== undefined
80
- ? blockState.pendingActions.get(blockGets.context.actionId) : undefined;
81
- if (namedPending) {
82
- // Overlay over the committed base at the context's pin, as StorageRepo does.
83
- const base = committedAt(blockState, pin);
84
- block = applyTransformSafe(base?.block, namedPending);
85
- // A pending carries no revision of its own — report the committed base it was
86
- // applied over. Absent when there was no base (a pending-only insert).
87
- materializedRev = base?.rev;
88
- } else {
89
- // context.committed proves its actions succeeded, so a block still holding one of them
90
- // pending is served with it applied — mirrors the coordinator's read-driven promotion.
91
- for (const { actionId: cId } of blockGets.context?.committed ?? []) {
92
- const pendingTransform = blockState.pendingActions.get(cId);
93
- if (pendingTransform) {
94
- const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
95
- block = applyTransformSafe(baseBlock, pendingTransform);
96
- if (baseBlock) materializedRev = blockState.latestRev;
97
- break;
98
- }
99
- }
100
- // Otherwise the committed content at the highest revision ≤ the pin, or the latest.
101
- if (block === undefined) {
102
- const found = committedAt(blockState, pin);
103
- block = structuredClone(found?.block);
104
- materializedRev = found?.rev;
105
- }
106
- }
107
-
108
- const actionId = blockState.revisionActions.get(blockState.latestRev);
109
- // The materialized revision travels WITH its action id (one field, so the pair can
110
- // never disagree) — the same `(rev, actionId)` the commit recorded for it.
111
- const materializedActionId = materializedRev !== undefined
112
- ? blockState.revisionActions.get(materializedRev) : undefined;
113
- results[blockId] = {
114
- block,
115
- ...(materializedRev !== undefined && materializedActionId !== undefined
116
- ? { materialized: { rev: materializedRev, actionId: materializedActionId } } : {}),
117
- state: {
118
- latest: actionId !== undefined ? {
119
- rev: blockState.latestRev,
120
- actionId
121
- } : undefined,
122
- pendings: Array.from(blockState.pendingActions.keys())
123
- }
124
- };
125
- }
126
- // --- End of Critical Section (Read) ---
127
-
128
- } finally {
129
- // Release locks in reverse order
130
- releases.reverse().forEach(release => release());
131
- }
132
- return results;
133
- }
134
-
135
- async getStatus(actionRefs: ActionBlocks[]): Promise<BlockActionStatus[]> {
136
- return actionRefs.map(ref => ({
137
- ...ref,
138
- statuses: ref.blockIds.map(blockId => {
139
- const blockState = this.blocks.get(blockId);
140
- if (!blockState) return 'aborted';
141
- return blockState.pendingActions.has(ref.actionId) ? 'pending'
142
- : Array.from(blockState.revisionActions.values()).some(actionId => actionId === ref.actionId) ? 'committed'
143
- : 'aborted';
144
- })
145
- }));
146
- }
147
-
148
- /** One store, no replicas: every revision was applied here onto the one before it, so the
149
- * revision index answers for lineage outright — mirroring `BlockStorage.lineageOf`, including
150
- * the one way a later revision does NOT build on its predecessor (an insert replaces the block
151
- * wholesale). The "cohort" is this store alone, which is what the durability says. */
152
- async getLineage(ref: ActionBlocks & { rev: number }): Promise<ActionLineage> {
153
- this.checkAvailable();
154
- const blocks = ref.blockIds.map((blockId): BlockLineage => {
155
- const blockState = this.blocks.get(blockId);
156
- if (!blockState || blockState.latestRev < ref.rev) return 'behind';
157
- if (blockState.revisionActions.get(ref.rev) !== ref.actionId) return 'excludes';
158
- const replacedSince = Array.from(blockState.revisionActions.entries()).some(([rev, actionId]) =>
159
- rev > ref.rev && blockState.committedActions.get(actionId)?.insert !== undefined);
160
- return replacedSince ? 'unknown' : 'contains';
161
- });
162
- return {
163
- blocks,
164
- ...(blocks.length > 0 && blocks.every(lineage => lineage === 'contains') ? { durability: localDurability() } : {})
165
- };
166
- }
167
-
168
- async pend(request: PendRequest): Promise<PendResult> {
169
- this.checkAvailable();
170
- const { actionId, transforms, policy, rev } = request;
171
- const blockIds = blockIdsForTransforms(transforms);
172
- const conflictingPendings: { blockId: BlockId, actionId: ActionId }[] = [];
173
- const missing: ActionTransforms[] = [];
174
- // Confirmed revisions this pend is up against, mirroring StorageRepo.pend: a block whose own
175
- // storage is already at or past the requested revision, held by someone other than this same
176
- // action. Reported as `staleAt` so a caller reading the shared harness sees the real shape.
177
- const staleCandidates: StaleFailure['staleAt'][] = [];
178
- // Blocks this SAME action already committed at exactly the requested revision — the durable
179
- // half of a torn action, met again by its own retry. Mirrors StorageRepo.pend's `satisfied`
180
- // set: such a block is neither a committed conflict nor a pending one, and no pending record
181
- // is written for it (commit's own-revision arm below never promotes one, so it would never
182
- // clear). It still rides in the returned `blockIds`, as in the real repo, so `cancel` covers it.
183
- const satisfied = new Set<BlockId>();
184
-
185
- // Check for conflicts (pending or committed based on rev/insert)
186
- for (const blockId of blockIds) {
187
- const blockState = this.blocks.get(blockId);
188
- const blockTransform = transformForBlockId(transforms, blockId);
189
- if (!blockTransform) continue; // Should not happen
190
-
191
- if (blockState && isOwnRevision(latestActionRev(blockState), rev, actionId)) {
192
- satisfied.add(blockId);
193
- continue;
194
- }
195
-
196
- if (blockState) {
197
- // Check for existing pending actions
198
- if (blockState.pendingActions.size > 0) {
199
- blockState.pendingActions.forEach((_, pendingActionId) => {
200
- conflictingPendings.push({ blockId, actionId: pendingActionId });
201
- });
202
- }
203
-
204
- // Check for conflicting committed revisions (if rev specified or it's an insert)
205
- if (rev !== undefined || blockTransform.insert) {
206
- const checkRev = rev ?? 0; // Check from revision 0 if it's an insert
207
- if (blockState.latestRev >= checkRev) {
208
- // Mirrors StorageRepo.pend exactly: only a real revision race yields a
209
- // meaningful `staleAt`. A rev-less pend reaches here as an insert collision
210
- // (`checkRev` degraded to 0), where the block's revision answers a question
211
- // nobody asked. (Our own durable half of a torn action never reaches here —
212
- // it was set aside as `satisfied` above.)
213
- if (rev !== undefined) {
214
- staleCandidates.push({ blockId, rev: blockState.latestRev });
215
- }
216
- // Collect conflicting committed actions
217
- const missingForBlock = new Map<ActionId, { rev: number, transform: Transform }>();
218
- for (let r = checkRev as number; r <= blockState.latestRev; r++) {
219
- const committedActionId = blockState.revisionActions.get(r);
220
- if (committedActionId !== undefined) {
221
- const committedTransform = blockState.committedActions.get(committedActionId);
222
- if (committedTransform) {
223
- missingForBlock.set(committedActionId, { rev: r, transform: committedTransform });
224
- }
225
- }
226
- }
227
-
228
- // Add collected missing transforms for this block to the main missing list
229
- for (const [mActionId, data] of missingForBlock.entries()) {
230
- let existing = missing.find(m => m.actionId === mActionId);
231
- if (!existing) {
232
- existing = { actionId: mActionId, rev: data.rev, transforms: emptyTransforms() };
233
- missing.push(existing);
234
- }
235
- existing.rev = Math.max(existing.rev ?? 0, data.rev);
236
- existing.transforms = concatTransform(existing.transforms, blockId, data.transform);
237
- }
238
- }
239
- }
240
- }
241
- }
242
-
243
- // Handle failure due to committed conflicts first.
244
- // `conflict: true` on the three optimistic-concurrency returns below mirrors what
245
- // StorageRepo.pend now emits, so consumers of this test transactor see the real shape.
246
- if (missing.length > 0) {
247
- const staleAt = highestStaleAt(staleCandidates);
248
- return {
249
- success: false,
250
- conflict: true,
251
- missing,
252
- ...(staleAt ? { staleAt } : {})
253
- };
254
- }
255
-
256
- // Handle failure/retry due to pending conflicts
257
- if (conflictingPendings.length > 0) {
258
- if (policy === 'f') {
259
- return { success: false, conflict: true, pending: conflictingPendings };
260
- } else if (policy === 'r') {
261
- // Simulate fetching pending transforms for 'r' policy
262
- const pendingWithTransforms = conflictingPendings
263
- .map(({ blockId: pBlockId, actionId: pActionId }) => {
264
- const pBlockState = this.blocks.get(pBlockId);
265
- const pTransform = pBlockState?.pendingActions.get(pActionId)
266
- ?? pBlockState?.committedActions.get(pActionId); // Might have been committed since check
267
- if (pTransform) {
268
- return { blockId: pBlockId, actionId: pActionId, transform: pTransform };
269
- }
270
- return null; // Handle case where it disappeared (cancelled?)
271
- })
272
- .filter(p => p !== null) as { blockId: BlockId, actionId: ActionId, transform: Transform }[];
273
-
274
- return {
275
- success: false,
276
- conflict: true,
277
- pending: pendingWithTransforms
278
- };
279
- }
280
- // Policy 'w' allows proceeding despite pending transactions
281
- }
282
-
283
- // No fatal conflicts found, proceed to pend
284
- for (const blockId of blockIds) {
285
- if (satisfied.has(blockId)) continue;
286
- const blockTransform = transformForBlockId(transforms, blockId);
287
- if (blockTransform) {
288
- const blockState = ensuredMap(this.blocks, blockId, () => newBlockState());
289
- blockState.pendingActions.set(actionId, blockTransform);
290
- }
291
- }
292
-
293
- // Return success, include pending list as per StorageRepo behavior. The in-memory double is one
294
- // node with no cohort, so its honest class is `local` — exactly what a bare StorageRepo answers.
295
- return {
296
- success: true,
297
- pending: conflictingPendings,
298
- blockIds,
299
- durability: localDurability()
300
- } as PendResult;
301
- }
302
-
303
- async cancel(actionRef: ActionBlocks): Promise<void> {
304
- this.checkAvailable();
305
- for (const blockId of actionRef.blockIds) {
306
- const blockState = this.blocks.get(blockId);
307
- if (blockState) {
308
- blockState.pendingActions.delete(actionRef.actionId);
309
- }
310
- }
311
- }
312
-
313
- async commit(request: CommitRequest): Promise<CommitResult> {
314
- this.checkAvailable();
315
- const { actionId, rev, blockIds } = request;
316
- const uniqueBlockIds = [...new Set(blockIds)].sort();
317
- const releases: (() => void)[] = [];
318
-
319
- try {
320
- // Simulate acquiring locks sequentially like StorageRepo
321
- for (const id of uniqueBlockIds) {
322
- const lockId = `TestTransactor.commit:${id}`;
323
- const release = await Latches.acquire(lockId);
324
- releases.push(release);
325
- }
326
-
327
- // --- Start of Critical Section (Simulated) ---
328
-
329
- // Blocks this same action already committed at exactly this revision: an idempotent no-op,
330
- // mirroring StorageRepo.commit's `alreadyDone` partition. They are neither stale nor in need
331
- // of a pending record (pend wrote none for them — see `satisfied` there), which is what lets
332
- // a torn action's retry roll its remaining blocks forward.
333
- const alreadyDone = new Set(blockIds.filter(blockId => {
334
- const blockState = this.blocks.get(blockId);
335
- return blockState !== undefined && isOwnRevision(latestActionRev(blockState), rev, actionId);
336
- }));
337
-
338
- // Check for stale revisions
339
- const staleBlocks = blockIds.filter(blockId => {
340
- const blockState = this.blocks.get(blockId);
341
- return blockState && blockState.latestRev >= rev && !alreadyDone.has(blockId);
342
- });
343
-
344
- if (staleBlocks.length > 0) {
345
- // Collect missing actions for stale blocks
346
- const missingByAction = new Map<ActionId, Transforms>();
347
- for (const blockId of staleBlocks) {
348
- const blockState = this.blocks.get(blockId)!;
349
- for (let r = rev; r <= blockState.latestRev; r++) {
350
- const committedActionId = blockState.revisionActions.get(r);
351
- if (committedActionId) {
352
- const transform = blockState.committedActions.get(committedActionId);
353
- if (transform) {
354
- const existing = missingByAction.get(committedActionId) ?? emptyTransforms();
355
- missingByAction.set(committedActionId, concatTransform(existing, blockId, transform));
356
- }
357
- }
358
- }
359
- }
360
-
361
- const missing: ActionTransforms[] = Array.from(missingByAction.entries()).map(([actionId, transforms]) => ({
362
- actionId,
363
- rev: Array.from(this.blocks.values())
364
- .flatMap(bs => Array.from(bs.revisionActions.entries()))
365
- .find(([, aId]) => aId === actionId)?.[0] ?? rev,
366
- transforms
367
- }));
368
- // Same rule as StorageRepo.commit's missedCommits branch: report the highest confirmed
369
- // revision a stale block is already at. A block held by this very action never reaches
370
- // here — it was partitioned out as `alreadyDone` above.
371
- const staleAt = highestStaleAt(staleBlocks.map(blockId =>
372
- ({ blockId, rev: this.blocks.get(blockId)!.latestRev })));
373
- return { success: false, missing, ...(staleAt ? { staleAt } : {}) };
374
- }
375
-
376
- const toCommit = blockIds.filter(blockId => !alreadyDone.has(blockId));
377
-
378
- // Verify all blocks that still need committing have the pending action
379
- for (const blockId of toCommit) {
380
- const blockState = this.blocks.get(blockId);
381
- if (!blockState || !blockState.pendingActions.has(actionId)) {
382
- return {
383
- success: false,
384
- reason: `Action ${actionId} not found or not pending for block ${blockId}`
385
- };
386
- }
387
- }
388
-
389
- // Commit the action for each block
390
- for (const blockId of toCommit) {
391
- const blockState = this.blocks.get(blockId)!;
392
- const transform = blockState.pendingActions.get(actionId)!;
393
-
394
- // Get base block to apply transform to
395
- const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
396
-
397
- let newBlock: IBlock | undefined;
398
- if (!baseBlock) {
399
- if (!transform.insert) {
400
- throw new Error(`Commit Error: Action ${actionId} has no insert for new block ${blockId}`);
401
- }
402
- newBlock = structuredClone(transform.insert);
403
- } else {
404
- newBlock = applyTransformSafe(baseBlock, transform);
405
- if (!newBlock && !transform.delete) {
406
- throw new Error(`Commit Error: Action ${actionId} resulted in undefined block but had no delete flag for block ${blockId}`);
407
- }
408
- }
409
-
410
- if (newBlock) {
411
- blockState.materializedBlocks.set(rev, newBlock);
412
- }
413
-
414
- // Update block state
415
- blockState.latestRev = rev;
416
- blockState.revisionActions.set(rev, actionId);
417
- blockState.committedActions.set(actionId, transform);
418
- blockState.pendingActions.delete(actionId);
419
- }
420
-
421
- // --- End of Critical Section (Simulated) ---
422
-
423
- return { success: true, durability: localDurability() };
424
-
425
- } finally {
426
- // Release locks in reverse order
427
- releases.reverse().forEach(release => release());
428
- }
429
- }
430
-
431
- // Helper methods for testing
432
- reset() {
433
- this.blocks.clear();
434
- }
435
-
436
- getPendingActions(): Map<ActionId, ActionTransforms> {
437
- const allPending = new Map<ActionId, ActionTransforms>();
438
- for (const [blockId, blockState] of this.blocks.entries()) {
439
- for (const [actionId, transform] of blockState.pendingActions) {
440
- const existing = allPending.get(actionId);
441
- if (!existing) {
442
- allPending.set(actionId, { actionId, transforms: transformsFromTransform(transform, blockId) });
443
- } else {
444
- existing.transforms = concatTransform(existing.transforms, blockId, transform);
445
- }
446
- }
447
- }
448
- return allPending;
449
- }
450
-
451
- getCommittedActions(): Map<ActionId, ActionTransforms> {
452
- const allCommitted = new Map<ActionId, ActionTransforms>();
453
- for (const [blockId, blockState] of this.blocks.entries()) {
454
- for (const [rev, actionId] of blockState.revisionActions) {
455
- const transform = blockState.committedActions.get(actionId);
456
- if (transform) {
457
- const existing = allCommitted.get(actionId);
458
- if (!existing) {
459
- allCommitted.set(actionId, {
460
- actionId,
461
- rev,
462
- transforms: transformsFromTransform(transform, blockId)
463
- });
464
- } else {
465
- existing.transforms = concatTransform(existing.transforms, blockId, transform);
466
- }
467
- }
468
- }
469
- }
470
- return allCommitted;
471
- }
472
-
473
- setAvailable(available: boolean) {
474
- this.available = available;
475
- }
476
-
477
- checkAvailable() {
478
- if (!this.available) {
479
- throw new Error('Transactor is not available');
480
- }
481
- }
482
-
483
- /** Optional method for querying cluster nominees (used in GATHER phase for multi-collection transactions) */
484
- queryClusterNominees?: (blockId: BlockId) => Promise<ClusterNomineesResult>;
485
- }
486
-
487
- /**
488
- * Base for the intercepting wrappers below: forwards every {@link ITransactor} member to `inner`,
489
- * so a wrapper overrides only the one call it intercepts and cannot silently drop the rest.
490
- *
491
- * `queryClusterNominees` is forwarded through a GETTER rather than a method, because the coordinator
492
- * treats its ABSENCE as "no supercluster" (see `gatherPhase`). A wrapper that always defined it
493
- * would push every wrapped multi-collection test onto the GATHER path even when the inner
494
- * transactor never opted in; a wrapper that omits it (as these did before) does the opposite —
495
- * a test that sets `inner.queryClusterNominees` and then wraps would skip GATHER and pass
496
- * vacuously. The getter reproduces the inner transactor's own answer either way.
497
- */
498
- export abstract class DelegatingTransactor implements ITransactor {
499
- protected constructor(protected readonly inner: TestTransactor) {}
500
-
501
- get(b: BlockGets): Promise<GetBlockResults> { return this.inner.get(b); }
502
- getStatus(a: ActionBlocks[]): Promise<BlockActionStatus[]> { return this.inner.getStatus(a); }
503
- pend(r: PendRequest): Promise<PendResult> { return this.inner.pend(r); }
504
- cancel(a: ActionBlocks): Promise<void> { return this.inner.cancel(a); }
505
- commit(r: CommitRequest): Promise<CommitResult> { return this.inner.commit(r); }
506
- getLineage(ref: ActionBlocks & { rev: number }): Promise<ActionLineage> { return this.inner.getLineage(ref); }
507
-
508
- get queryClusterNominees(): ((blockId: BlockId) => Promise<ClusterNomineesResult>) | undefined {
509
- return this.inner.queryClusterNominees?.bind(this.inner);
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
- }
523
- }
524
-
525
- /**
526
- * Wraps a {@link TestTransactor} and forces its commit phase to fail a bounded (or unbounded)
527
- * number of times before delegating, so tests can exercise the sync retry / backoff / give-up
528
- * path deterministically. Everything else delegates unchanged, so the pend→commit→cancel
529
- * round-trip runs exactly as in production.
530
- */
531
- export class FlakyCommitTransactor extends DelegatingTransactor {
532
- /** Number of commit() calls observed so far (across success and forced failure). */
533
- commitAttempts = 0;
534
-
535
- /**
536
- * @param inner delegate transactor
537
- * @param failFirstN number of initial commit() calls to fail; Infinity to always fail
538
- * @param reason the StaleFailure.reason returned on a forced failure
539
- */
540
- constructor(
541
- inner: TestTransactor,
542
- private readonly failFirstN: number,
543
- private readonly reason = 'forced stale',
544
- ) {
545
- super(inner);
546
- }
547
-
548
- override async commit(request: CommitRequest): Promise<CommitResult> {
549
- this.commitAttempts++;
550
- if (this.commitAttempts <= this.failFirstN) {
551
- return { success: false, reason: this.reason };
552
- }
553
- return this.inner.commit(request);
554
- }
555
- }
556
-
557
- /**
558
- * Commits the WHOLE action durably on the inner {@link TestTransactor}, then reports a stale
559
- * failure anyway — a write that fully landed but whose writer was told it failed.
560
- *
561
- * This is NOT the shape `NetworkTransactor.commit` produces when it refuses a write whose log tail
562
- * landed: there the tail is committed BEFORE the sweep of the remaining blocks, so the blocks after
563
- * the tail did NOT land. That shape is {@link TailLandsButReportsStale}, and it is the one that
564
- * matters in production. This double makes "my own log entry is visible" and "my action is fully
565
- * durable" the same thing, so on its own it cannot tell a writer that finishes its half-landed
566
- * action from one that merely assumes it is finished. Keep it for the case it does model — every
567
- * block already holds the action's revision, so the writer's completion pass has nothing left to
568
- * land and must not duplicate or move the entry.
569
- *
570
- * Safe against the inner transactor's bookkeeping because `TransactorSource.transact` cancels
571
- * the pend on the reported failure and {@link TestTransactor.cancel} only deletes PENDING records
572
- * — the real commit already promoted them, so the cancel is a no-op.
573
- *
574
- * `afterLanding`, when given, runs a competing writer ONCE, after the first masked commit has
575
- * landed and before its failure is reported: the rival reads the landed write and commits the next
576
- * revision ON TOP of it, so by the time the writer looks again every block it wrote has moved past
577
- * its revision while still containing it. Safe to await from inside `commit` here (unlike
578
- * {@link TailLandsButReportsStale}'s rival, which has to wait for the cancel): the whole action
579
- * landed, so it left no pending record for the rival's pend to collide with.
580
- *
581
- * Used by both write paths' own-entry regression suites (collection-own-action-replay.spec.ts and
582
- * coordinator-own-action-replay.spec.ts); it lives here so the two cannot drift apart.
583
- */
584
- export class CommitLandsButReportsStale extends DelegatingTransactor {
585
- /** Remaining number of successful commits to mask as stale failures. */
586
- private injections: number;
587
- /** Commits that actually landed on the inner transactor (masked or not). */
588
- landedCommits = 0;
589
- private rivalDue: boolean;
590
-
591
- constructor(inner: TestTransactor, injections = 1, private readonly afterLanding?: RivalWrite) {
592
- super(inner);
593
- this.injections = injections;
594
- this.rivalDue = afterLanding !== undefined;
595
- }
596
-
597
- override async commit(request: CommitRequest): Promise<CommitResult> {
598
- const result = await this.inner.commit(request);
599
- if (result.success) {
600
- this.landedCommits++;
601
- if (this.injections-- > 0) {
602
- if (this.rivalDue) {
603
- this.rivalDue = false;
604
- await this.afterLanding!(this.inner);
605
- }
606
- return { success: false, conflict: true, reason: 'stale commit: injected torn-action conflict' };
607
- }
608
- }
609
- return result;
610
- }
611
- }
612
-
613
- /**
614
- * Lands ONLY the action's log tail on the inner {@link TestTransactor}, then reports a retryable
615
- * failure — the shape `NetworkTransactor.commit` actually produces for a half-landed write. It
616
- * commits the tail first and sweeps the remaining blocks only if the tail answered success, and a
617
- * failed tail answer does not mean the tail is absent: the coordinator's durability gate answers
618
- * `commit-not-durable` whenever fewer than a majority of the cohort hold the revision, even though
619
- * some members stored it. So the writer is told "failed" over a log entry that is durable, while
620
- * none of the entry's other blocks were ever committed — and the writer's own cancel then drops
621
- * their pending records.
622
- *
623
- * A commit carrying nothing but the tail is delegated untouched (there is nothing to abandon), and
624
- * does not consume an injection.
625
- *
626
- * `afterCancel`, when given, runs a competing writer ONCE, right after the writer's cancel of the
627
- * torn attempt has been delegated. It is on `cancel` and not inside `commit` for the reason
628
- * {@link CompetingWriterTransactor} documents: until that cancel lands, the torn action's data
629
- * blocks still carry its pending records, a rival pending with policy `'r'` collides with them, and
630
- * awaiting that rival from inside the writer's own commit is a livelock.
631
- */
632
- export class TailLandsButReportsStale extends DelegatingTransactor {
633
- /** Remaining number of commits to tear. */
634
- private injections: number;
635
- /** Commits torn so far: the tail landed, every other block of the action was abandoned. */
636
- tears = 0;
637
- /** Commits delegated whole that succeeded on the inner transactor. */
638
- landedCommits = 0;
639
- private rivalDue = false;
640
-
641
- constructor(inner: TestTransactor, injections = 1, private readonly afterCancel?: RivalWrite) {
642
- super(inner);
643
- this.injections = injections;
644
- }
645
-
646
- override async commit(request: CommitRequest): Promise<CommitResult> {
647
- if (this.injections > 0 && request.blockIds.some(blockId => blockId !== request.tailId)) {
648
- const tail = await this.inner.commit({ ...request, blockIds: [request.tailId] });
649
- // A tail that itself lost is an ordinary loss — nothing is torn, so report it verbatim
650
- // and keep the injection for a commit that can actually tear.
651
- if (!tail.success) return tail;
652
- this.injections--;
653
- this.tears++;
654
- this.rivalDue = this.afterCancel !== undefined;
655
- return { success: false, conflict: true, reason: 'commit-not-durable: injected tail-only landing' };
656
- }
657
- const result = await this.inner.commit(request);
658
- if (result.success) this.landedCommits++;
659
- return result;
660
- }
661
-
662
- override async cancel(actionRef: ActionBlocks): Promise<void> {
663
- await this.inner.cancel(actionRef);
664
- if (this.rivalDue) {
665
- this.rivalDue = false;
666
- await this.afterCancel!(this.inner);
667
- }
668
- }
669
- }
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
-
701
- /** What one attempt of a write put on the wire: the pend's transforms, with the action id and
702
- * revision it was pended under. Recorded by {@link RecordsAttemptsRefusesFirstCommit}. */
703
- export type RecordedAttempt = {
704
- actionId: ActionId;
705
- rev?: number;
706
- transforms: Transforms;
707
- };
708
-
709
- /**
710
- * Records what every attempt of a write pends, and refuses the FIRST commit outright — nothing is
711
- * delegated, so nothing lands and the retry's refresh cannot find the write's own log entry.
712
- *
713
- * That is the case `Collection.completeOwnEntry` does NOT reach: the refused commit left the log
714
- * block (and, for a brand-new collection, the header) uncommitted, so the refresh has no entry to
715
- * finish from and the retry REBUILDS its log append from scratch. Storage identifies a saved block
716
- * revision by `(action id, revision)` and deliberately accepts a retry of the same action at the
717
- * same revision, so any per-attempt value in that rebuild becomes two contents under one
718
- * `(action, revision)` across the machines that landed different attempts.
719
- *
720
- * `attempts` is therefore asserted on WHOLE — not field by field — so the rule it pins ("a retry at
721
- * the same revision sends byte-identical transforms") fails for any future per-attempt value, not
722
- * only the ones known today. Transforms are cloned on the way in, since the caller keeps mutating
723
- * the live tracker afterwards.
724
- *
725
- * Lives here beside {@link CommitLandsButReportsStale} for the reason that one gives: the
726
- * collection-path and coordinator-path specs must not drift apart on the double they share.
727
- */
728
- export class RecordsAttemptsRefusesFirstCommit extends DelegatingTransactor {
729
- readonly attempts: RecordedAttempt[] = [];
730
- private refusals: number;
731
-
732
- constructor(inner: TestTransactor, refusals = 1) {
733
- super(inner);
734
- this.refusals = refusals;
735
- }
736
-
737
- /** Arm (or re-arm) the refusal counter, so a test can let its setup writes land cleanly and
738
- * then refuse only the write under test. Replaces whatever is left of the current count. */
739
- refuseNextCommits(count: number): void {
740
- this.refusals = count;
741
- }
742
-
743
- override async pend(request: PendRequest): Promise<PendResult> {
744
- this.attempts.push({
745
- actionId: request.actionId,
746
- rev: request.rev,
747
- transforms: structuredClone(request.transforms),
748
- });
749
- return this.inner.pend(request);
750
- }
751
-
752
- override async commit(request: CommitRequest): Promise<CommitResult> {
753
- if (this.refusals > 0) {
754
- this.refusals--;
755
- // Never delegated: nothing of this attempt is durable, so `TransactorSource.transact`
756
- // cancels the pend and the writer re-drives at the same action id and revision.
757
- return { success: false, conflict: true, reason: 'stale commit: injected refusal, nothing landed' };
758
- }
759
- return this.inner.commit(request);
760
- }
761
- }
762
-
763
- /** A competing writer: a real write driven against the UNWRAPPED transactor, so its own
764
- * pend/commit calls are invisible to {@link CompetingWriterTransactor}'s counters and cannot
765
- * re-trigger the interception. See {@link commitRivalTreeWrite} for the usual implementation. */
766
- export type RivalWrite = (inner: ITransactor) => Promise<void>;
767
-
768
- export type CompetingWriterOptions = {
769
- /** Fires on the first pend whose request satisfies this predicate. `callIndex` is 1-based over
770
- * ALL pend calls seen (not only matching ones). Default: fire on the first pend call. */
771
- when?: (request: PendRequest, callIndex: number) => boolean;
772
- };
773
-
774
- /**
775
- * Wraps a {@link TestTransactor} and, exactly once, runs a real competing writer to completion
776
- * BEFORE delegating the intercepted pend. The rival durably commits (real log entry, real
777
- * revision bump), so the delegated pend then fails as a GENUINE optimistic-concurrency loss —
778
- * nothing is forced or faked, unlike {@link FlakyCommitTransactor}, which returns a stale failure
779
- * without ever advancing a block's revision.
780
- *
781
- * That distinction is the whole point: only a rival that actually landed can prove the loser
782
- * OBSERVED a newer revision, re-applied its work on top of it, and did not lose an update.
783
- *
784
- * Two deliberate design constraints:
785
- *
786
- * 1. **The trigger is on PEND, and there is no commit trigger.** The rival is a real
787
- * Collection/Tree, so its write pends with policy `'r'` (see `TransactorSource.transact`), and
788
- * {@link TestTransactor.pend} rejects a pend whose blocks already carry a *pending* action.
789
- * Firing before the loser's pend delegates means the loser has pended nothing yet, so the
790
- * rival pends and commits cleanly and the loser's delegated pend then fails with `missing` — a
791
- * real conflict. Firing at COMMIT time instead would leave the loser already pending on the
792
- * shared log-tail block, so the rival's own pend would collide with it and spin through its
793
- * sync retry budget (~10 attempts, ~21s) while the loser sits awaiting the rival inside its
794
- * own commit: a livelock dressed up as a slow test. Do not add a commit trigger.
795
- *
796
- * 2. **The rival runs before delegation, never inside {@link TestTransactor}'s critical section.**
797
- * `TestTransactor.get`/`commit` hold per-block latches (`TestTransactor.commit:${blockId}`), and
798
- * those latch keys are process-global — a rival invoked from inside one of them would
799
- * self-deadlock on its own reads. Intercepting here in the wrapper, before
800
- * `await this.inner.pend(...)`, is outside every such section.
801
- */
802
- export class CompetingWriterTransactor extends DelegatingTransactor {
803
- /** Pend calls observed (including the intercepted one). */
804
- pendCalls = 0;
805
- /** Commit calls observed. */
806
- commitCalls = 0;
807
- /** The 1-based pend call index the rival fired on; undefined if it never fired. */
808
- firedAtCall?: number;
809
- /** How many times the rival ran. Latched to at most 1 — a second firing would collide with the
810
- * loser's now-pending blocks and the transaction under test could never win. */
811
- rivalRuns = 0;
812
-
813
- constructor(
814
- inner: TestTransactor,
815
- private readonly rival: RivalWrite,
816
- private readonly options?: CompetingWriterOptions,
817
- ) {
818
- super(inner);
819
- }
820
-
821
- override async pend(request: PendRequest): Promise<PendResult> {
822
- // Increment synchronously, before any await, so call indexes reflect the caller's fan-out
823
- // order rather than scheduling order.
824
- const callIndex = ++this.pendCalls;
825
- const matches = this.options?.when
826
- ? this.options.when(request, callIndex)
827
- : callIndex === 1;
828
- if (this.rivalRuns === 0 && matches) {
829
- this.rivalRuns++;
830
- this.firedAtCall = callIndex;
831
- // A throwing rival escapes as a rejected pend, which pendPhase flattens to a bare message
832
- // string ("hard failure") with the stack discarded — so name the source in the message, or
833
- // a broken rival reads as an unexplained coordinator pend failure.
834
- try {
835
- await this.rival(this.inner);
836
- } catch (e) {
837
- throw new Error(`competing writer failed: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
838
- }
839
- }
840
- return this.inner.pend(request);
841
- }
842
-
843
- override async commit(request: CommitRequest): Promise<CommitResult> {
844
- this.commitCalls++;
845
- return this.inner.commit(request);
846
- }
847
- }
848
-
849
- type Deferred = { promise: Promise<void>; resolve: () => void };
850
-
851
- function deferred(): Deferred {
852
- let resolve!: () => void;
853
- const promise = new Promise<void>(r => { resolve = r; });
854
- return { promise, resolve };
855
- }
856
-
857
- /**
858
- * Parks the commit AFTER the inner transactor has made it durable and BEFORE the result gets back
859
- * to the coordinator — precisely the window in which storage already holds the new revision but
860
- * the caller's local fold (`Collection.recordCommitted`) has not run.
861
- *
862
- * Everything else delegates, so the pend/commit round trip is otherwise the real one.
863
- *
864
- * Parks only the FIRST commit call and delegates every later one: a multi-collection commit issues
865
- * one `commit` per participant, and parking all of them would mean the span never completes.
866
- */
867
- export class GatedCommitTransactor extends DelegatingTransactor {
868
- /** The `rev` carried on each pend request seen, in call order. */
869
- readonly pendRevs: (number | undefined)[] = [];
870
- /** The `rev` carried on each commit request seen, in call order. */
871
- readonly commitRevs: number[] = [];
872
- /** Resolves once a commit has landed durably in the inner transactor and is parked. */
873
- readonly commitParked: Promise<void>;
874
- private readonly parked = deferred();
875
- private readonly gate = deferred();
876
- private parkedOnce = false;
877
-
878
- constructor(inner: TestTransactor) {
879
- super(inner);
880
- this.commitParked = this.parked.promise;
881
- }
882
-
883
- override async pend(request: PendRequest): Promise<PendResult> {
884
- this.pendRevs.push(request.rev);
885
- return this.inner.pend(request);
886
- }
887
-
888
- override async commit(request: CommitRequest): Promise<CommitResult> {
889
- this.commitRevs.push(request.rev);
890
- const result = await this.inner.commit(request); // durable FIRST
891
- if (!this.parkedOnce) {
892
- this.parkedOnce = true;
893
- this.parked.resolve();
894
- await this.gate.promise;
895
- }
896
- return result;
897
- }
898
-
899
- openGate(): void { this.gate.resolve(); }
900
- }
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
-
925
- /**
926
- * Parks the FIRST pend BEFORE it reaches the inner transactor, so a rival can durably take the
927
- * revision while the coordinator is already committed to a set of transforms it captured at the
928
- * log append.
929
- *
930
- * Snapshots the pair `(what was handed to the network, what the collection's tracker held)` at
931
- * DELEGATION time — after the gate — for every pend, so a refresh that swapped the tracker's
932
- * transforms object out from under the coordinator shows up as a divergent pair.
933
- */
934
- export class GatedPendTransactor<TAction> extends DelegatingTransactor {
935
- /** One entry per delegated pend, in call order. */
936
- readonly snapshots: { pended: Transforms; staged: Transforms }[] = [];
937
- /** Resolves once a pend is parked and has NOT yet reached the inner transactor. */
938
- readonly pendParked: Promise<void>;
939
- /** The collection under test. Assigned after construction — the collection is built over this
940
- * wrapper, so it cannot be a constructor argument. */
941
- collection?: Collection<TAction>;
942
- private readonly parked = deferred();
943
- private readonly gate = deferred();
944
- private parkedOnce = false;
945
-
946
- constructor(inner: TestTransactor) {
947
- super(inner);
948
- this.pendParked = this.parked.promise;
949
- }
950
-
951
- override async pend(request: PendRequest): Promise<PendResult> {
952
- if (!this.parkedOnce) {
953
- this.parkedOnce = true;
954
- this.parked.resolve();
955
- await this.gate.promise;
956
- }
957
- this.snapshots.push({
958
- pended: structuredClone(request.transforms),
959
- staged: structuredClone(this.collection!.tracker.transforms),
960
- });
961
- return this.inner.pend(request);
962
- }
963
-
964
- openGate(): void { this.gate.resolve(); }
965
- }
966
-
967
- /**
968
- * Durably commit a conflicting change to a tree collection: opens a SECOND {@link Tree} over the
969
- * same transactor + collection id and replaces `entries` through it, producing a real log entry
970
- * and a real revision bump — the durable competitor a {@link CompetingWriterTransactor} needs.
971
- *
972
- * `Tree.replace` is act + `updateAndSync`, i.e. a full commit through the single-collection sync
973
- * path, so the rival's write is indistinguishable from any other client's.
974
- *
975
- * Pass the UNWRAPPED transactor (that is what {@link RivalWrite} receives).
976
- *
977
- * NOTE: opens the rival tree at the DEFAULT node capacity (64), because fan-out is not persisted
978
- * in the collection header (see Tree.createOrOpen's `nodeCapacity` note). Fine while every rival
979
- * race is between default-fan-out trees; if a test ever needs to race a small-capacity tree, add a
980
- * capacity parameter here and pass the same value both sides, or the two writers will split nodes
981
- * at different fan-outs.
982
- */
983
- export async function commitRivalTreeWrite<TKey, TEntry>(
984
- inner: ITransactor,
985
- collectionId: CollectionId,
986
- keyFromEntry: (entry: TEntry) => TKey,
987
- entries: TreeReplaceAction<TKey, TEntry>,
988
- ): Promise<void> {
989
- const tree = await Tree.createOrOpen<TKey, TEntry>(inner, collectionId, keyFromEntry);
990
- await tree.replace(entries);
991
- }
992
-
993
- function newBlockState(): BlockState {
994
- return {
995
- materializedBlocks: new Map(),
996
- latestRev: 0,
997
- revisionActions: new Map(),
998
- pendingActions: new Map(),
999
- committedActions: new Map()
1000
- };
1001
- }
1002
-
1003
- /** This block's latest committed revision in the shape {@link isOwnRevision} compares — the
1004
- * harness equivalent of `IBlockStorage.getLatest()`. `undefined` when nothing is recorded at that
1005
- * revision, which is how a never-written block reads (`latestRev` starts at 0 with no entry). */
1006
- function latestActionRev(blockState: BlockState): ActionRev | undefined {
1007
- const actionId = blockState.revisionActions.get(blockState.latestRev);
1008
- return actionId === undefined ? undefined : { actionId, rev: blockState.latestRev };
1009
- }
1010
-
1011
- /** The committed content a read at `pin` sees — the highest materialized revision at or below
1012
- * it — or the latest revision's content when the read is unpinned. */
1013
- function committedAt(blockState: BlockState, pin: number | undefined): { block: IBlock, rev: number } | undefined {
1014
- if (pin !== undefined) return latestMaterializedAt(blockState, pin);
1015
- const block = blockState.materializedBlocks.get(blockState.latestRev);
1016
- return block ? { block, rev: blockState.latestRev } : undefined;
1017
- }
1018
-
1019
- /** Returns the materialized block at the highest revision ≤ the given revision, together with
1020
- * that revision — the caller reports it as {@link GetBlockResult.materialized}. */
1021
- function latestMaterializedAt(blockState: BlockState, maxRev: number): { block: IBlock, rev: number } | undefined {
1022
- for (let rev = maxRev; rev >= 0; rev--) {
1023
- const block = blockState.materializedBlocks.get(rev);
1024
- if (block) return { block, rev };
1025
- }
1026
- return undefined;
1027
- }
1028
-
1029
- /**
1030
- * `applyTransform` over cloned inputs, so a returned block never aliases stored state.
1031
- *
1032
- * The `insert` clone here is not redundant with `transformForBlockId`'s: callers pass `Transform`
1033
- * values pulled straight out of `blockState.pendingActions` (a `Map<ActionId, Transform>` written
1034
- * once by `pend()`), which can be `get()`'d more than once and read again at commit time before
1035
- * being superseded. `applyTransform` mutates `transform.insert` in place when `updates` ride
1036
- * along, so cloning immediately before each call is what keeps that stored entry pristine across
1037
- * repeated reads.
1038
- *
1039
- * An absent base is NOT a short circuit: an insert needs no base — `applyTransform` adopts it as
1040
- * the block. Bailing out on `!block` made this double silently drop a pending-only insert read
1041
- * through the pending overlay, the one shape `StorageRepo.get` serves with content but no
1042
- * `materialized` (see docs/internals.md § the `unavailable`/`materialized` bullets). A
1043
- * pending UPDATE over an absent base still resolves to undefined, matching the real repo.
1044
- */
1045
- function applyTransformSafe(block: IBlock | undefined, transform: Transform): IBlock | undefined {
1046
- return applyTransform(
1047
- block ? structuredClone(block) : undefined,
1048
- transform.insert ? { ...transform, insert: structuredClone(transform.insert) } : transform
1049
- );
1050
- }
1
+ import type { ITransactor, GetBlockResults, ActionBlocks, ActionLineage, BlockLineage, BlockActionStatus, PendResult, CommitResult, PendRequest, BlockId, CommitRequest, BlockGets, IBlock, ActionId, ActionRev, ActionTransforms, StaleFailure, Transform, Transforms, ClusterNomineesResult, CollectionId } from "../index.js";
2
+ import { highestStaleAt, isOwnRevision } from "../network/stale-failure.js";
3
+ import { localDurability } from "../network/durability.js";
4
+ import { ensuredMap } from "../utility/ensured.js";
5
+ import { Latches } from "../utility/latches.js";
6
+ import { applyTransform, blockIdsForTransforms, transformForBlockId, emptyTransforms, concatTransform, transformsFromTransform } from "../transform/index.js";
7
+ import { Tree } from "../collections/tree/tree.js";
8
+ import type { TreeReplaceAction } from "../collections/tree/struct.js";
9
+ import type { Collection } from "../collection/collection.js";
10
+ import { HlcClock } from "../hlc/clock.js";
11
+
12
+ type RevisionNumber = number;
13
+
14
+ type BlockState = {
15
+ /** The current materialized block at each revision */
16
+ materializedBlocks: Map<RevisionNumber, IBlock>;
17
+ /** The latest revision number */
18
+ latestRev: RevisionNumber;
19
+ /** The action that created each revision */
20
+ revisionActions: Map<RevisionNumber, ActionId>;
21
+ /** Currently pending actions */
22
+ pendingActions: Map<ActionId, Transform>;
23
+ /** Committed actions */
24
+ committedActions: Map<ActionId, Transform>;
25
+ }
26
+
27
+ export type TestTransactorOptions = {
28
+ /** The clock writes through this transactor mint from. Default: a fresh in-memory clock in the node id `'test'`;
29
+ * inject one to drive a fake local clock, or to have two transactors mint from one sequence. */
30
+ clock?: HlcClock;
31
+ };
32
+
33
+ // Simple in-memory transactor for testing that maintains materialized blocks for every revision
34
+ export class TestTransactor implements ITransactor {
35
+ private blocks = new Map<BlockId, BlockState>();
36
+ available = true;
37
+ private getLocks = new Map<BlockId, Promise<() => void>>(); // Track lock releases
38
+ readonly clock: HlcClock;
39
+
40
+ constructor(options?: TestTransactorOptions) {
41
+ this.clock = options?.clock ?? new HlcClock({ nodeId: 'test' });
42
+ }
43
+
44
+ async get(blockGets: BlockGets): Promise<GetBlockResults> {
45
+ this.checkAvailable();
46
+ const results: GetBlockResults = {};
47
+ const uniqueBlockIds = [...new Set(blockGets.blockIds)].sort(); // Ensure consistent lock order if needed, though get is read-only
48
+ const releases: (() => void)[] = [];
49
+
50
+ try {
51
+ // Acquire locks for all requested blocks to ensure consistent read
52
+ for (const blockId of uniqueBlockIds) {
53
+ const lockId = `TestTransactor.commit:${blockId}`; // Use the same lock as commit
54
+ // Wait for any existing lock promise to resolve before acquiring the next
55
+ let release = await this.getLocks.get(lockId);
56
+ if (release) await Promise.resolve(release); // Ensure previous lock released if overlapping calls happen
57
+
58
+ const releasePromise = Latches.acquire(lockId);
59
+ this.getLocks.set(blockId, releasePromise.then(r => () => {
60
+ r();
61
+ this.getLocks.delete(blockId); // Clean up map entry after release
62
+ }));
63
+ release = await releasePromise;
64
+ releases.push(release);
65
+ }
66
+
67
+ // --- Start of Critical Section (Read) ---
68
+ for (const blockId of blockGets.blockIds) {
69
+ const blockState = this.blocks.get(blockId);
70
+ if (!blockState) {
71
+ // Block doesn't exist yet
72
+ results[blockId] = {
73
+ block: undefined,
74
+ state: { latest: undefined, pendings: [] }
75
+ };
76
+ continue;
77
+ }
78
+
79
+ // Get the appropriate materialized block based on context
80
+ let block: IBlock | undefined;
81
+ // The revision `block` was actually materialized at, reported (with its action id) as
82
+ // GetBlockResult.materialized. Equals `latestRev` on every unpinned path; only a
83
+ // revision-pinned read of a block committed further since the pin makes them differ,
84
+ // and there the pinned value is what the reader observed (see the field's doc).
85
+ let materializedRev: number | undefined;
86
+ // A named pending is overlaid only where this block holds it; every other block gets the
87
+ // plain answer for the same context (mirrors StorageRepo.get).
88
+ const pin = blockGets.context?.rev;
89
+ const namedPending = blockGets.context?.actionId !== undefined
90
+ ? blockState.pendingActions.get(blockGets.context.actionId) : undefined;
91
+ if (namedPending) {
92
+ // Overlay over the committed base at the context's pin, as StorageRepo does.
93
+ const base = committedAt(blockState, pin);
94
+ block = applyTransformSafe(base?.block, namedPending);
95
+ // A pending carries no revision of its own — report the committed base it was
96
+ // applied over. Absent when there was no base (a pending-only insert).
97
+ materializedRev = base?.rev;
98
+ } else {
99
+ // context.committed proves its actions succeeded, so a block still holding one of them
100
+ // pending is served with it applied — mirrors the coordinator's read-driven promotion.
101
+ for (const { actionId: cId } of blockGets.context?.committed ?? []) {
102
+ const pendingTransform = blockState.pendingActions.get(cId);
103
+ if (pendingTransform) {
104
+ const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
105
+ block = applyTransformSafe(baseBlock, pendingTransform);
106
+ if (baseBlock) materializedRev = blockState.latestRev;
107
+ break;
108
+ }
109
+ }
110
+ // Otherwise the committed content at the highest revision ≤ the pin, or the latest.
111
+ if (block === undefined) {
112
+ const found = committedAt(blockState, pin);
113
+ block = structuredClone(found?.block);
114
+ materializedRev = found?.rev;
115
+ }
116
+ }
117
+
118
+ const actionId = blockState.revisionActions.get(blockState.latestRev);
119
+ // The materialized revision travels WITH its action id (one field, so the pair can
120
+ // never disagree) — the same `(rev, actionId)` the commit recorded for it.
121
+ const materializedActionId = materializedRev !== undefined
122
+ ? blockState.revisionActions.get(materializedRev) : undefined;
123
+ results[blockId] = {
124
+ block,
125
+ ...(materializedRev !== undefined && materializedActionId !== undefined
126
+ ? { materialized: { rev: materializedRev, actionId: materializedActionId } } : {}),
127
+ state: {
128
+ latest: actionId !== undefined ? {
129
+ rev: blockState.latestRev,
130
+ actionId
131
+ } : undefined,
132
+ pendings: Array.from(blockState.pendingActions.keys())
133
+ }
134
+ };
135
+ }
136
+ // --- End of Critical Section (Read) ---
137
+
138
+ } finally {
139
+ // Release locks in reverse order
140
+ releases.reverse().forEach(release => release());
141
+ }
142
+ return results;
143
+ }
144
+
145
+ async getStatus(actionRefs: ActionBlocks[]): Promise<BlockActionStatus[]> {
146
+ return actionRefs.map(ref => ({
147
+ ...ref,
148
+ statuses: ref.blockIds.map(blockId => {
149
+ const blockState = this.blocks.get(blockId);
150
+ if (!blockState) return 'aborted';
151
+ return blockState.pendingActions.has(ref.actionId) ? 'pending'
152
+ : Array.from(blockState.revisionActions.values()).some(actionId => actionId === ref.actionId) ? 'committed'
153
+ : 'aborted';
154
+ })
155
+ }));
156
+ }
157
+
158
+ /** One store, no replicas: every revision was applied here onto the one before it, so the
159
+ * revision index answers for lineage outright — mirroring `BlockStorage.lineageOf`, including
160
+ * the one way a later revision does NOT build on its predecessor (an insert replaces the block
161
+ * wholesale). The "cohort" is this store alone, which is what the durability says. */
162
+ async getLineage(ref: ActionBlocks & { rev: number }): Promise<ActionLineage> {
163
+ this.checkAvailable();
164
+ const blocks = ref.blockIds.map((blockId): BlockLineage => {
165
+ const blockState = this.blocks.get(blockId);
166
+ if (!blockState || blockState.latestRev < ref.rev) return 'behind';
167
+ if (blockState.revisionActions.get(ref.rev) !== ref.actionId) return 'excludes';
168
+ const replacedSince = Array.from(blockState.revisionActions.entries()).some(([rev, actionId]) =>
169
+ rev > ref.rev && blockState.committedActions.get(actionId)?.insert !== undefined);
170
+ return replacedSince ? 'unknown' : 'contains';
171
+ });
172
+ return {
173
+ blocks,
174
+ ...(blocks.length > 0 && blocks.every(lineage => lineage === 'contains') ? { durability: localDurability() } : {})
175
+ };
176
+ }
177
+
178
+ async pend(request: PendRequest): Promise<PendResult> {
179
+ this.checkAvailable();
180
+ const { actionId, transforms, policy, rev } = request;
181
+ const blockIds = blockIdsForTransforms(transforms);
182
+ const conflictingPendings: { blockId: BlockId, actionId: ActionId }[] = [];
183
+ const missing: ActionTransforms[] = [];
184
+ // Confirmed revisions this pend is up against, mirroring StorageRepo.pend: a block whose own
185
+ // storage is already at or past the requested revision, held by someone other than this same
186
+ // action. Reported as `staleAt` so a caller reading the shared harness sees the real shape.
187
+ const staleCandidates: StaleFailure['staleAt'][] = [];
188
+ // Blocks this SAME action already committed at exactly the requested revision — the durable
189
+ // half of a torn action, met again by its own retry. Mirrors StorageRepo.pend's `satisfied`
190
+ // set: such a block is neither a committed conflict nor a pending one, and no pending record
191
+ // is written for it (commit's own-revision arm below never promotes one, so it would never
192
+ // clear). It still rides in the returned `blockIds`, as in the real repo, so `cancel` covers it.
193
+ const satisfied = new Set<BlockId>();
194
+
195
+ // Check for conflicts (pending or committed based on rev/insert)
196
+ for (const blockId of blockIds) {
197
+ const blockState = this.blocks.get(blockId);
198
+ const blockTransform = transformForBlockId(transforms, blockId);
199
+ if (!blockTransform) continue; // Should not happen
200
+
201
+ if (blockState && isOwnRevision(latestActionRev(blockState), rev, actionId)) {
202
+ satisfied.add(blockId);
203
+ continue;
204
+ }
205
+
206
+ if (blockState) {
207
+ // Check for existing pending actions
208
+ if (blockState.pendingActions.size > 0) {
209
+ blockState.pendingActions.forEach((_, pendingActionId) => {
210
+ conflictingPendings.push({ blockId, actionId: pendingActionId });
211
+ });
212
+ }
213
+
214
+ // Check for conflicting committed revisions (if rev specified or it's an insert)
215
+ if (rev !== undefined || blockTransform.insert) {
216
+ const checkRev = rev ?? 0; // Check from revision 0 if it's an insert
217
+ if (blockState.latestRev >= checkRev) {
218
+ // Mirrors StorageRepo.pend exactly: only a real revision race yields a
219
+ // meaningful `staleAt`. A rev-less pend reaches here as an insert collision
220
+ // (`checkRev` degraded to 0), where the block's revision answers a question
221
+ // nobody asked. (Our own durable half of a torn action never reaches here —
222
+ // it was set aside as `satisfied` above.)
223
+ if (rev !== undefined) {
224
+ staleCandidates.push({ blockId, rev: blockState.latestRev });
225
+ }
226
+ // Collect conflicting committed actions
227
+ const missingForBlock = new Map<ActionId, { rev: number, transform: Transform }>();
228
+ for (let r = checkRev as number; r <= blockState.latestRev; r++) {
229
+ const committedActionId = blockState.revisionActions.get(r);
230
+ if (committedActionId !== undefined) {
231
+ const committedTransform = blockState.committedActions.get(committedActionId);
232
+ if (committedTransform) {
233
+ missingForBlock.set(committedActionId, { rev: r, transform: committedTransform });
234
+ }
235
+ }
236
+ }
237
+
238
+ // Add collected missing transforms for this block to the main missing list
239
+ for (const [mActionId, data] of missingForBlock.entries()) {
240
+ let existing = missing.find(m => m.actionId === mActionId);
241
+ if (!existing) {
242
+ existing = { actionId: mActionId, rev: data.rev, transforms: emptyTransforms() };
243
+ missing.push(existing);
244
+ }
245
+ existing.rev = Math.max(existing.rev ?? 0, data.rev);
246
+ existing.transforms = concatTransform(existing.transforms, blockId, data.transform);
247
+ }
248
+ }
249
+ }
250
+ }
251
+ }
252
+
253
+ // Handle failure due to committed conflicts first.
254
+ // `conflict: true` on the three optimistic-concurrency returns below mirrors what
255
+ // StorageRepo.pend now emits, so consumers of this test transactor see the real shape.
256
+ if (missing.length > 0) {
257
+ const staleAt = highestStaleAt(staleCandidates);
258
+ return {
259
+ success: false,
260
+ conflict: true,
261
+ missing,
262
+ ...(staleAt ? { staleAt } : {})
263
+ };
264
+ }
265
+
266
+ // Handle failure/retry due to pending conflicts
267
+ if (conflictingPendings.length > 0) {
268
+ if (policy === 'f') {
269
+ return { success: false, conflict: true, pending: conflictingPendings };
270
+ } else if (policy === 'r') {
271
+ // Simulate fetching pending transforms for 'r' policy
272
+ const pendingWithTransforms = conflictingPendings
273
+ .map(({ blockId: pBlockId, actionId: pActionId }) => {
274
+ const pBlockState = this.blocks.get(pBlockId);
275
+ const pTransform = pBlockState?.pendingActions.get(pActionId)
276
+ ?? pBlockState?.committedActions.get(pActionId); // Might have been committed since check
277
+ if (pTransform) {
278
+ return { blockId: pBlockId, actionId: pActionId, transform: pTransform };
279
+ }
280
+ return null; // Handle case where it disappeared (cancelled?)
281
+ })
282
+ .filter(p => p !== null) as { blockId: BlockId, actionId: ActionId, transform: Transform }[];
283
+
284
+ return {
285
+ success: false,
286
+ conflict: true,
287
+ pending: pendingWithTransforms
288
+ };
289
+ }
290
+ // Policy 'w' allows proceeding despite pending transactions
291
+ }
292
+
293
+ // No fatal conflicts found, proceed to pend
294
+ for (const blockId of blockIds) {
295
+ if (satisfied.has(blockId)) continue;
296
+ const blockTransform = transformForBlockId(transforms, blockId);
297
+ if (blockTransform) {
298
+ const blockState = ensuredMap(this.blocks, blockId, () => newBlockState());
299
+ blockState.pendingActions.set(actionId, blockTransform);
300
+ }
301
+ }
302
+
303
+ // Return success, include pending list as per StorageRepo behavior. The in-memory double is one
304
+ // node with no cohort, so its honest class is `local` — exactly what a bare StorageRepo answers.
305
+ return {
306
+ success: true,
307
+ pending: conflictingPendings,
308
+ blockIds,
309
+ durability: localDurability()
310
+ } as PendResult;
311
+ }
312
+
313
+ async cancel(actionRef: ActionBlocks): Promise<void> {
314
+ this.checkAvailable();
315
+ for (const blockId of actionRef.blockIds) {
316
+ const blockState = this.blocks.get(blockId);
317
+ if (blockState) {
318
+ blockState.pendingActions.delete(actionRef.actionId);
319
+ }
320
+ }
321
+ }
322
+
323
+ async commit(request: CommitRequest): Promise<CommitResult> {
324
+ this.checkAvailable();
325
+ const { actionId, rev, blockIds } = request;
326
+ const uniqueBlockIds = [...new Set(blockIds)].sort();
327
+ const releases: (() => void)[] = [];
328
+
329
+ try {
330
+ // Simulate acquiring locks sequentially like StorageRepo
331
+ for (const id of uniqueBlockIds) {
332
+ const lockId = `TestTransactor.commit:${id}`;
333
+ const release = await Latches.acquire(lockId);
334
+ releases.push(release);
335
+ }
336
+
337
+ // --- Start of Critical Section (Simulated) ---
338
+
339
+ // Blocks this same action already committed at exactly this revision: an idempotent no-op,
340
+ // mirroring StorageRepo.commit's `alreadyDone` partition. They are neither stale nor in need
341
+ // of a pending record (pend wrote none for them — see `satisfied` there), which is what lets
342
+ // a torn action's retry roll its remaining blocks forward.
343
+ const alreadyDone = new Set(blockIds.filter(blockId => {
344
+ const blockState = this.blocks.get(blockId);
345
+ return blockState !== undefined && isOwnRevision(latestActionRev(blockState), rev, actionId);
346
+ }));
347
+
348
+ // Check for stale revisions
349
+ const staleBlocks = blockIds.filter(blockId => {
350
+ const blockState = this.blocks.get(blockId);
351
+ return blockState && blockState.latestRev >= rev && !alreadyDone.has(blockId);
352
+ });
353
+
354
+ if (staleBlocks.length > 0) {
355
+ // Collect missing actions for stale blocks
356
+ const missingByAction = new Map<ActionId, Transforms>();
357
+ for (const blockId of staleBlocks) {
358
+ const blockState = this.blocks.get(blockId)!;
359
+ for (let r = rev; r <= blockState.latestRev; r++) {
360
+ const committedActionId = blockState.revisionActions.get(r);
361
+ if (committedActionId) {
362
+ const transform = blockState.committedActions.get(committedActionId);
363
+ if (transform) {
364
+ const existing = missingByAction.get(committedActionId) ?? emptyTransforms();
365
+ missingByAction.set(committedActionId, concatTransform(existing, blockId, transform));
366
+ }
367
+ }
368
+ }
369
+ }
370
+
371
+ const missing: ActionTransforms[] = Array.from(missingByAction.entries()).map(([actionId, transforms]) => ({
372
+ actionId,
373
+ rev: Array.from(this.blocks.values())
374
+ .flatMap(bs => Array.from(bs.revisionActions.entries()))
375
+ .find(([, aId]) => aId === actionId)?.[0] ?? rev,
376
+ transforms
377
+ }));
378
+ // Same rule as StorageRepo.commit's missedCommits branch: report the highest confirmed
379
+ // revision a stale block is already at. A block held by this very action never reaches
380
+ // here — it was partitioned out as `alreadyDone` above.
381
+ const staleAt = highestStaleAt(staleBlocks.map(blockId =>
382
+ ({ blockId, rev: this.blocks.get(blockId)!.latestRev })));
383
+ return { success: false, missing, ...(staleAt ? { staleAt } : {}) };
384
+ }
385
+
386
+ const toCommit = blockIds.filter(blockId => !alreadyDone.has(blockId));
387
+
388
+ // Verify all blocks that still need committing have the pending action
389
+ for (const blockId of toCommit) {
390
+ const blockState = this.blocks.get(blockId);
391
+ if (!blockState || !blockState.pendingActions.has(actionId)) {
392
+ return {
393
+ success: false,
394
+ reason: `Action ${actionId} not found or not pending for block ${blockId}`
395
+ };
396
+ }
397
+ }
398
+
399
+ // Commit the action for each block
400
+ for (const blockId of toCommit) {
401
+ const blockState = this.blocks.get(blockId)!;
402
+ const transform = blockState.pendingActions.get(actionId)!;
403
+
404
+ // Get base block to apply transform to
405
+ const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
406
+
407
+ let newBlock: IBlock | undefined;
408
+ if (!baseBlock) {
409
+ if (!transform.insert) {
410
+ throw new Error(`Commit Error: Action ${actionId} has no insert for new block ${blockId}`);
411
+ }
412
+ newBlock = structuredClone(transform.insert);
413
+ } else {
414
+ newBlock = applyTransformSafe(baseBlock, transform);
415
+ if (!newBlock && !transform.delete) {
416
+ throw new Error(`Commit Error: Action ${actionId} resulted in undefined block but had no delete flag for block ${blockId}`);
417
+ }
418
+ }
419
+
420
+ if (newBlock) {
421
+ blockState.materializedBlocks.set(rev, newBlock);
422
+ }
423
+
424
+ // Update block state
425
+ blockState.latestRev = rev;
426
+ blockState.revisionActions.set(rev, actionId);
427
+ blockState.committedActions.set(actionId, transform);
428
+ blockState.pendingActions.delete(actionId);
429
+ }
430
+
431
+ // --- End of Critical Section (Simulated) ---
432
+
433
+ return { success: true, durability: localDurability() };
434
+
435
+ } finally {
436
+ // Release locks in reverse order
437
+ releases.reverse().forEach(release => release());
438
+ }
439
+ }
440
+
441
+ // Helper methods for testing
442
+ reset() {
443
+ this.blocks.clear();
444
+ }
445
+
446
+ getPendingActions(): Map<ActionId, ActionTransforms> {
447
+ const allPending = new Map<ActionId, ActionTransforms>();
448
+ for (const [blockId, blockState] of this.blocks.entries()) {
449
+ for (const [actionId, transform] of blockState.pendingActions) {
450
+ const existing = allPending.get(actionId);
451
+ if (!existing) {
452
+ allPending.set(actionId, { actionId, transforms: transformsFromTransform(transform, blockId) });
453
+ } else {
454
+ existing.transforms = concatTransform(existing.transforms, blockId, transform);
455
+ }
456
+ }
457
+ }
458
+ return allPending;
459
+ }
460
+
461
+ getCommittedActions(): Map<ActionId, ActionTransforms> {
462
+ const allCommitted = new Map<ActionId, ActionTransforms>();
463
+ for (const [blockId, blockState] of this.blocks.entries()) {
464
+ for (const [rev, actionId] of blockState.revisionActions) {
465
+ const transform = blockState.committedActions.get(actionId);
466
+ if (transform) {
467
+ const existing = allCommitted.get(actionId);
468
+ if (!existing) {
469
+ allCommitted.set(actionId, {
470
+ actionId,
471
+ rev,
472
+ transforms: transformsFromTransform(transform, blockId)
473
+ });
474
+ } else {
475
+ existing.transforms = concatTransform(existing.transforms, blockId, transform);
476
+ }
477
+ }
478
+ }
479
+ }
480
+ return allCommitted;
481
+ }
482
+
483
+ setAvailable(available: boolean) {
484
+ this.available = available;
485
+ }
486
+
487
+ checkAvailable() {
488
+ if (!this.available) {
489
+ throw new Error('Transactor is not available');
490
+ }
491
+ }
492
+
493
+ /** Optional method for querying cluster nominees (used in GATHER phase for multi-collection transactions) */
494
+ queryClusterNominees?: (blockId: BlockId) => Promise<ClusterNomineesResult>;
495
+ }
496
+
497
+ /**
498
+ * Base for the intercepting wrappers below: forwards every {@link ITransactor} member to `inner`,
499
+ * so a wrapper overrides only the one call it intercepts and cannot silently drop the rest.
500
+ *
501
+ * `queryClusterNominees` is forwarded through a GETTER rather than a method, because the coordinator
502
+ * treats its ABSENCE as "no supercluster" (see `gatherPhase`). A wrapper that always defined it
503
+ * would push every wrapped multi-collection test onto the GATHER path even when the inner
504
+ * transactor never opted in; a wrapper that omits it (as these did before) does the opposite —
505
+ * a test that sets `inner.queryClusterNominees` and then wraps would skip GATHER and pass
506
+ * vacuously. The getter reproduces the inner transactor's own answer either way.
507
+ */
508
+ export abstract class DelegatingTransactor implements ITransactor {
509
+ protected constructor(protected readonly inner: TestTransactor) {}
510
+
511
+ get clock(): HlcClock { return this.inner.clock; }
512
+
513
+ get(b: BlockGets): Promise<GetBlockResults> { return this.inner.get(b); }
514
+ getStatus(a: ActionBlocks[]): Promise<BlockActionStatus[]> { return this.inner.getStatus(a); }
515
+ pend(r: PendRequest): Promise<PendResult> { return this.inner.pend(r); }
516
+ cancel(a: ActionBlocks): Promise<void> { return this.inner.cancel(a); }
517
+ commit(r: CommitRequest): Promise<CommitResult> { return this.inner.commit(r); }
518
+ getLineage(ref: ActionBlocks & { rev: number }): Promise<ActionLineage> { return this.inner.getLineage(ref); }
519
+
520
+ get queryClusterNominees(): ((blockId: BlockId) => Promise<ClusterNomineesResult>) | undefined {
521
+ return this.inner.queryClusterNominees?.bind(this.inner);
522
+ }
523
+
524
+ // Getters for the same reason: the coordinator treats their absence as "pend and commit each
525
+ // collection on its own". `TestTransactor` offers neither, so a wrapped one keeps that path.
526
+ get pendMany(): ITransactor['pendMany'] {
527
+ const inner: ITransactor = this.inner;
528
+ return inner.pendMany?.bind(inner);
529
+ }
530
+
531
+ get commitMany(): ITransactor['commitMany'] {
532
+ const inner: ITransactor = this.inner;
533
+ return inner.commitMany?.bind(inner);
534
+ }
535
+ }
536
+
537
+ /**
538
+ * Wraps a {@link TestTransactor} and forces its commit phase to fail a bounded (or unbounded)
539
+ * number of times before delegating, so tests can exercise the sync retry / backoff / give-up
540
+ * path deterministically. Everything else delegates unchanged, so the pend→commit→cancel
541
+ * round-trip runs exactly as in production.
542
+ */
543
+ export class FlakyCommitTransactor extends DelegatingTransactor {
544
+ /** Number of commit() calls observed so far (across success and forced failure). */
545
+ commitAttempts = 0;
546
+
547
+ /**
548
+ * @param inner delegate transactor
549
+ * @param failFirstN number of initial commit() calls to fail; Infinity to always fail
550
+ * @param reason the StaleFailure.reason returned on a forced failure
551
+ */
552
+ constructor(
553
+ inner: TestTransactor,
554
+ private readonly failFirstN: number,
555
+ private readonly reason = 'forced stale',
556
+ ) {
557
+ super(inner);
558
+ }
559
+
560
+ override async commit(request: CommitRequest): Promise<CommitResult> {
561
+ this.commitAttempts++;
562
+ if (this.commitAttempts <= this.failFirstN) {
563
+ return { success: false, reason: this.reason };
564
+ }
565
+ return this.inner.commit(request);
566
+ }
567
+ }
568
+
569
+ /**
570
+ * Commits the WHOLE action durably on the inner {@link TestTransactor}, then reports a stale
571
+ * failure anyway — a write that fully landed but whose writer was told it failed.
572
+ *
573
+ * This is NOT the shape `NetworkTransactor.commit` produces when it refuses a write whose log tail
574
+ * landed: there the tail is committed BEFORE the sweep of the remaining blocks, so the blocks after
575
+ * the tail did NOT land. That shape is {@link TailLandsButReportsStale}, and it is the one that
576
+ * matters in production. This double makes "my own log entry is visible" and "my action is fully
577
+ * durable" the same thing, so on its own it cannot tell a writer that finishes its half-landed
578
+ * action from one that merely assumes it is finished. Keep it for the case it does model — every
579
+ * block already holds the action's revision, so the writer's completion pass has nothing left to
580
+ * land and must not duplicate or move the entry.
581
+ *
582
+ * Safe against the inner transactor's bookkeeping because `TransactorSource.transact` cancels
583
+ * the pend on the reported failure and {@link TestTransactor.cancel} only deletes PENDING records
584
+ * — the real commit already promoted them, so the cancel is a no-op.
585
+ *
586
+ * `afterLanding`, when given, runs a competing writer ONCE, after the first masked commit has
587
+ * landed and before its failure is reported: the rival reads the landed write and commits the next
588
+ * revision ON TOP of it, so by the time the writer looks again every block it wrote has moved past
589
+ * its revision while still containing it. Safe to await from inside `commit` here (unlike
590
+ * {@link TailLandsButReportsStale}'s rival, which has to wait for the cancel): the whole action
591
+ * landed, so it left no pending record for the rival's pend to collide with.
592
+ *
593
+ * Used by both write paths' own-entry regression suites (collection-own-action-replay.spec.ts and
594
+ * coordinator-own-action-replay.spec.ts); it lives here so the two cannot drift apart.
595
+ */
596
+ export class CommitLandsButReportsStale extends DelegatingTransactor {
597
+ /** Remaining number of successful commits to mask as stale failures. */
598
+ private injections: number;
599
+ /** Commits that actually landed on the inner transactor (masked or not). */
600
+ landedCommits = 0;
601
+ private rivalDue: boolean;
602
+
603
+ constructor(inner: TestTransactor, injections = 1, private readonly afterLanding?: RivalWrite) {
604
+ super(inner);
605
+ this.injections = injections;
606
+ this.rivalDue = afterLanding !== undefined;
607
+ }
608
+
609
+ override async commit(request: CommitRequest): Promise<CommitResult> {
610
+ const result = await this.inner.commit(request);
611
+ if (result.success) {
612
+ this.landedCommits++;
613
+ if (this.injections-- > 0) {
614
+ if (this.rivalDue) {
615
+ this.rivalDue = false;
616
+ await this.afterLanding!(this.inner);
617
+ }
618
+ return { success: false, conflict: true, reason: 'stale commit: injected torn-action conflict' };
619
+ }
620
+ }
621
+ return result;
622
+ }
623
+ }
624
+
625
+ /**
626
+ * Lands ONLY the action's log tail on the inner {@link TestTransactor}, then reports a retryable
627
+ * failure — the shape `NetworkTransactor.commit` actually produces for a half-landed write. It
628
+ * commits the tail first and sweeps the remaining blocks only if the tail answered success, and a
629
+ * failed tail answer does not mean the tail is absent: the coordinator's durability gate answers
630
+ * `commit-not-durable` whenever fewer than a majority of the cohort hold the revision, even though
631
+ * some members stored it. So the writer is told "failed" over a log entry that is durable, while
632
+ * none of the entry's other blocks were ever committed — and the writer's own cancel then drops
633
+ * their pending records.
634
+ *
635
+ * A commit carrying nothing but the tail is delegated untouched (there is nothing to abandon), and
636
+ * does not consume an injection.
637
+ *
638
+ * `afterCancel`, when given, runs a competing writer ONCE, right after the writer's cancel of the
639
+ * torn attempt has been delegated. It is on `cancel` and not inside `commit` for the reason
640
+ * {@link CompetingWriterTransactor} documents: until that cancel lands, the torn action's data
641
+ * blocks still carry its pending records, a rival pending with policy `'r'` collides with them, and
642
+ * awaiting that rival from inside the writer's own commit is a livelock.
643
+ */
644
+ export class TailLandsButReportsStale extends DelegatingTransactor {
645
+ /** Remaining number of commits to tear. */
646
+ private injections: number;
647
+ /** Commits torn so far: the tail landed, every other block of the action was abandoned. */
648
+ tears = 0;
649
+ /** Commits delegated whole that succeeded on the inner transactor. */
650
+ landedCommits = 0;
651
+ private rivalDue = false;
652
+
653
+ constructor(inner: TestTransactor, injections = 1, private readonly afterCancel?: RivalWrite) {
654
+ super(inner);
655
+ this.injections = injections;
656
+ }
657
+
658
+ override async commit(request: CommitRequest): Promise<CommitResult> {
659
+ if (this.injections > 0 && request.blockIds.some(blockId => blockId !== request.tailId)) {
660
+ const tail = await this.inner.commit({ ...request, blockIds: [request.tailId] });
661
+ // A tail that itself lost is an ordinary loss — nothing is torn, so report it verbatim
662
+ // and keep the injection for a commit that can actually tear.
663
+ if (!tail.success) return tail;
664
+ this.injections--;
665
+ this.tears++;
666
+ this.rivalDue = this.afterCancel !== undefined;
667
+ return { success: false, conflict: true, reason: 'commit-not-durable: injected tail-only landing' };
668
+ }
669
+ const result = await this.inner.commit(request);
670
+ if (result.success) this.landedCommits++;
671
+ return result;
672
+ }
673
+
674
+ override async cancel(actionRef: ActionBlocks): Promise<void> {
675
+ await this.inner.cancel(actionRef);
676
+ if (this.rivalDue) {
677
+ this.rivalDue = false;
678
+ await this.afterCancel!(this.inner);
679
+ }
680
+ }
681
+ }
682
+
683
+ /**
684
+ * Answers every pend with a promise shortfall — the cohort's silence, in the shape
685
+ * `CoordinatorRepo.pend` returns it — and delegates nothing, so nothing is reserved and nothing
686
+ * lands. For the write paths' "stopped by name" cases: a shortfall is not a conflict a retry can
687
+ * win, so one attempt is made and `PromiseShortfallError` escapes with every staged action still
688
+ * staged.
689
+ */
690
+ export class RefusesPendsAsShortfall extends DelegatingTransactor {
691
+ /** Pends refused so far. */
692
+ pends = 0;
693
+ /** While `true` every pend is refused; set `false` to let pends through again — the cohort back
694
+ * in reach, for a test of what waits on it. */
695
+ refusing = true;
696
+
697
+ constructor(inner: TestTransactor) {
698
+ super(inner);
699
+ }
700
+
701
+ override async pend(request: PendRequest): Promise<PendResult> {
702
+ if (!this.refusing) return this.inner.pend(request);
703
+ this.pends++;
704
+ return {
705
+ success: false,
706
+ conflict: false,
707
+ reason: 'Failed to get super-majority: injected shortfall',
708
+ shortfall: { approvals: 1, rejections: 0, peerCount: 3, needed: 3, silentPeers: ['peer-b', 'peer-c'] },
709
+ };
710
+ }
711
+ }
712
+
713
+ /** What one attempt of a write put on the wire: the pend's transforms, with the action id and
714
+ * revision it was pended under. Recorded by {@link RecordsAttemptsRefusesFirstCommit}. */
715
+ export type RecordedAttempt = {
716
+ actionId: ActionId;
717
+ rev?: number;
718
+ transforms: Transforms;
719
+ };
720
+
721
+ /**
722
+ * Records what every attempt of a write pends, and refuses the FIRST commit outright — nothing is
723
+ * delegated, so nothing lands and the retry's refresh cannot find the write's own log entry.
724
+ *
725
+ * That is the case `Collection.completeOwnEntry` does NOT reach: the refused commit left the log
726
+ * block (and, for a brand-new collection, the header) uncommitted, so the refresh has no entry to
727
+ * finish from and the retry REBUILDS its log append from scratch. Storage identifies a saved block
728
+ * revision by `(action id, revision)` and deliberately accepts a retry of the same action at the
729
+ * same revision, so any per-attempt value in that rebuild becomes two contents under one
730
+ * `(action, revision)` across the machines that landed different attempts.
731
+ *
732
+ * `attempts` is therefore asserted on WHOLE — not field by field — so the rule it pins ("a retry at
733
+ * the same revision sends byte-identical transforms") fails for any future per-attempt value, not
734
+ * only the ones known today. Transforms are cloned on the way in, since the caller keeps mutating
735
+ * the live tracker afterwards.
736
+ *
737
+ * Lives here beside {@link CommitLandsButReportsStale} for the reason that one gives: the
738
+ * collection-path and coordinator-path specs must not drift apart on the double they share.
739
+ */
740
+ export class RecordsAttemptsRefusesFirstCommit extends DelegatingTransactor {
741
+ readonly attempts: RecordedAttempt[] = [];
742
+ private refusals: number;
743
+
744
+ constructor(inner: TestTransactor, refusals = 1) {
745
+ super(inner);
746
+ this.refusals = refusals;
747
+ }
748
+
749
+ /** Arm (or re-arm) the refusal counter, so a test can let its setup writes land cleanly and
750
+ * then refuse only the write under test. Replaces whatever is left of the current count. */
751
+ refuseNextCommits(count: number): void {
752
+ this.refusals = count;
753
+ }
754
+
755
+ override async pend(request: PendRequest): Promise<PendResult> {
756
+ this.attempts.push({
757
+ actionId: request.actionId,
758
+ rev: request.rev,
759
+ transforms: structuredClone(request.transforms),
760
+ });
761
+ return this.inner.pend(request);
762
+ }
763
+
764
+ override async commit(request: CommitRequest): Promise<CommitResult> {
765
+ if (this.refusals > 0) {
766
+ this.refusals--;
767
+ // Never delegated: nothing of this attempt is durable, so `TransactorSource.transact`
768
+ // cancels the pend and the writer re-drives at the same action id and revision.
769
+ return { success: false, conflict: true, reason: 'stale commit: injected refusal, nothing landed' };
770
+ }
771
+ return this.inner.commit(request);
772
+ }
773
+ }
774
+
775
+ /** A competing writer: a real write driven against the UNWRAPPED transactor, so its own
776
+ * pend/commit calls are invisible to {@link CompetingWriterTransactor}'s counters and cannot
777
+ * re-trigger the interception. See {@link commitRivalTreeWrite} for the usual implementation. */
778
+ export type RivalWrite = (inner: ITransactor) => Promise<void>;
779
+
780
+ export type CompetingWriterOptions = {
781
+ /** Fires on the first pend whose request satisfies this predicate. `callIndex` is 1-based over
782
+ * ALL pend calls seen (not only matching ones). Default: fire on the first pend call. */
783
+ when?: (request: PendRequest, callIndex: number) => boolean;
784
+ };
785
+
786
+ /**
787
+ * Wraps a {@link TestTransactor} and, exactly once, runs a real competing writer to completion
788
+ * BEFORE delegating the intercepted pend. The rival durably commits (real log entry, real
789
+ * revision bump), so the delegated pend then fails as a GENUINE optimistic-concurrency loss —
790
+ * nothing is forced or faked, unlike {@link FlakyCommitTransactor}, which returns a stale failure
791
+ * without ever advancing a block's revision.
792
+ *
793
+ * That distinction is the whole point: only a rival that actually landed can prove the loser
794
+ * OBSERVED a newer revision, re-applied its work on top of it, and did not lose an update.
795
+ *
796
+ * Two deliberate design constraints:
797
+ *
798
+ * 1. **The trigger is on PEND, and there is no commit trigger.** The rival is a real
799
+ * Collection/Tree, so its write pends with policy `'r'` (see `TransactorSource.transact`), and
800
+ * {@link TestTransactor.pend} rejects a pend whose blocks already carry a *pending* action.
801
+ * Firing before the loser's pend delegates means the loser has pended nothing yet, so the
802
+ * rival pends and commits cleanly and the loser's delegated pend then fails with `missing` — a
803
+ * real conflict. Firing at COMMIT time instead would leave the loser already pending on the
804
+ * shared log-tail block, so the rival's own pend would collide with it and spin through its
805
+ * sync retry budget (~10 attempts, ~21s) while the loser sits awaiting the rival inside its
806
+ * own commit: a livelock dressed up as a slow test. Do not add a commit trigger.
807
+ *
808
+ * 2. **The rival runs before delegation, never inside {@link TestTransactor}'s critical section.**
809
+ * `TestTransactor.get`/`commit` hold per-block latches (`TestTransactor.commit:${blockId}`), and
810
+ * those latch keys are process-global — a rival invoked from inside one of them would
811
+ * self-deadlock on its own reads. Intercepting here in the wrapper, before
812
+ * `await this.inner.pend(...)`, is outside every such section.
813
+ */
814
+ export class CompetingWriterTransactor extends DelegatingTransactor {
815
+ /** Pend calls observed (including the intercepted one). */
816
+ pendCalls = 0;
817
+ /** Commit calls observed. */
818
+ commitCalls = 0;
819
+ /** The 1-based pend call index the rival fired on; undefined if it never fired. */
820
+ firedAtCall?: number;
821
+ /** How many times the rival ran. Latched to at most 1 — a second firing would collide with the
822
+ * loser's now-pending blocks and the transaction under test could never win. */
823
+ rivalRuns = 0;
824
+
825
+ constructor(
826
+ inner: TestTransactor,
827
+ private readonly rival: RivalWrite,
828
+ private readonly options?: CompetingWriterOptions,
829
+ ) {
830
+ super(inner);
831
+ }
832
+
833
+ override async pend(request: PendRequest): Promise<PendResult> {
834
+ // Increment synchronously, before any await, so call indexes reflect the caller's fan-out
835
+ // order rather than scheduling order.
836
+ const callIndex = ++this.pendCalls;
837
+ const matches = this.options?.when
838
+ ? this.options.when(request, callIndex)
839
+ : callIndex === 1;
840
+ if (this.rivalRuns === 0 && matches) {
841
+ this.rivalRuns++;
842
+ this.firedAtCall = callIndex;
843
+ // A throwing rival escapes as a rejected pend, which pendPhase flattens to a bare message
844
+ // string ("hard failure") with the stack discarded — so name the source in the message, or
845
+ // a broken rival reads as an unexplained coordinator pend failure.
846
+ try {
847
+ await this.rival(this.inner);
848
+ } catch (e) {
849
+ throw new Error(`competing writer failed: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
850
+ }
851
+ }
852
+ return this.inner.pend(request);
853
+ }
854
+
855
+ override async commit(request: CommitRequest): Promise<CommitResult> {
856
+ this.commitCalls++;
857
+ return this.inner.commit(request);
858
+ }
859
+ }
860
+
861
+ type Deferred = { promise: Promise<void>; resolve: () => void };
862
+
863
+ function deferred(): Deferred {
864
+ let resolve!: () => void;
865
+ const promise = new Promise<void>(r => { resolve = r; });
866
+ return { promise, resolve };
867
+ }
868
+
869
+ /**
870
+ * Parks the commit AFTER the inner transactor has made it durable and BEFORE the result gets back
871
+ * to the coordinator — precisely the window in which storage already holds the new revision but
872
+ * the caller's local fold (`Collection.recordCommitted`) has not run.
873
+ *
874
+ * Everything else delegates, so the pend/commit round trip is otherwise the real one.
875
+ *
876
+ * Parks only the FIRST commit call and delegates every later one: a multi-collection commit issues
877
+ * one `commit` per participant, and parking all of them would mean the span never completes.
878
+ */
879
+ export class GatedCommitTransactor extends DelegatingTransactor {
880
+ /** The `rev` carried on each pend request seen, in call order. */
881
+ readonly pendRevs: (number | undefined)[] = [];
882
+ /** The `rev` carried on each commit request seen, in call order. */
883
+ readonly commitRevs: number[] = [];
884
+ /** Resolves once a commit has landed durably in the inner transactor and is parked. */
885
+ readonly commitParked: Promise<void>;
886
+ private readonly parked = deferred();
887
+ private readonly gate = deferred();
888
+ private parkedOnce = false;
889
+
890
+ constructor(inner: TestTransactor) {
891
+ super(inner);
892
+ this.commitParked = this.parked.promise;
893
+ }
894
+
895
+ override async pend(request: PendRequest): Promise<PendResult> {
896
+ this.pendRevs.push(request.rev);
897
+ return this.inner.pend(request);
898
+ }
899
+
900
+ override async commit(request: CommitRequest): Promise<CommitResult> {
901
+ this.commitRevs.push(request.rev);
902
+ const result = await this.inner.commit(request); // durable FIRST
903
+ if (!this.parkedOnce) {
904
+ this.parkedOnce = true;
905
+ this.parked.resolve();
906
+ await this.gate.promise;
907
+ }
908
+ return result;
909
+ }
910
+
911
+ openGate(): void { this.gate.resolve(); }
912
+ }
913
+
914
+ /**
915
+ * Throws, nothing delegated, on every commit of the collection whose log tail is `tailId` while
916
+ * `armed` — the hard failure of one participant's commit after its siblings' landed, which a
917
+ * multi-collection commit reports as `CoordinatorPartialCommitError`. Disarmed, everything delegates.
918
+ */
919
+ export class ThrowsOnCommitOf extends DelegatingTransactor {
920
+ /** Commits thrown so far. */
921
+ thrown = 0;
922
+ armed = true;
923
+
924
+ constructor(inner: TestTransactor, private readonly tailId: BlockId) {
925
+ super(inner);
926
+ }
927
+
928
+ override async commit(request: CommitRequest): Promise<CommitResult> {
929
+ if (this.armed && request.tailId === this.tailId) {
930
+ this.thrown++;
931
+ throw new Error('connection dropped before the commit was sent');
932
+ }
933
+ return this.inner.commit(request);
934
+ }
935
+ }
936
+
937
+ /**
938
+ * Parks the FIRST pend BEFORE it reaches the inner transactor, so a rival can durably take the
939
+ * revision while the coordinator is already committed to a set of transforms it captured at the
940
+ * log append.
941
+ *
942
+ * Snapshots the pair `(what was handed to the network, what the collection's tracker held)` at
943
+ * DELEGATION time — after the gate — for every pend, so a refresh that swapped the tracker's
944
+ * transforms object out from under the coordinator shows up as a divergent pair.
945
+ */
946
+ export class GatedPendTransactor<TAction> extends DelegatingTransactor {
947
+ /** One entry per delegated pend, in call order. */
948
+ readonly snapshots: { pended: Transforms; staged: Transforms }[] = [];
949
+ /** Resolves once a pend is parked and has NOT yet reached the inner transactor. */
950
+ readonly pendParked: Promise<void>;
951
+ /** The collection under test. Assigned after construction — the collection is built over this
952
+ * wrapper, so it cannot be a constructor argument. */
953
+ collection?: Collection<TAction>;
954
+ private readonly parked = deferred();
955
+ private readonly gate = deferred();
956
+ private parkedOnce = false;
957
+
958
+ constructor(inner: TestTransactor) {
959
+ super(inner);
960
+ this.pendParked = this.parked.promise;
961
+ }
962
+
963
+ override async pend(request: PendRequest): Promise<PendResult> {
964
+ if (!this.parkedOnce) {
965
+ this.parkedOnce = true;
966
+ this.parked.resolve();
967
+ await this.gate.promise;
968
+ }
969
+ this.snapshots.push({
970
+ pended: structuredClone(request.transforms),
971
+ staged: structuredClone(this.collection!.tracker.transforms),
972
+ });
973
+ return this.inner.pend(request);
974
+ }
975
+
976
+ openGate(): void { this.gate.resolve(); }
977
+ }
978
+
979
+ /**
980
+ * Durably commit a conflicting change to a tree collection: opens a SECOND {@link Tree} over the
981
+ * same transactor + collection id and replaces `entries` through it, producing a real log entry
982
+ * and a real revision bump — the durable competitor a {@link CompetingWriterTransactor} needs.
983
+ *
984
+ * `Tree.replace` is act + `updateAndSync`, i.e. a full commit through the single-collection sync
985
+ * path, so the rival's write is indistinguishable from any other client's.
986
+ *
987
+ * Pass the UNWRAPPED transactor (that is what {@link RivalWrite} receives).
988
+ *
989
+ * NOTE: opens the rival tree at the DEFAULT node capacity (64), because fan-out is not persisted
990
+ * in the collection header (see Tree.createOrOpen's `nodeCapacity` note). Fine while every rival
991
+ * race is between default-fan-out trees; if a test ever needs to race a small-capacity tree, add a
992
+ * capacity parameter here and pass the same value both sides, or the two writers will split nodes
993
+ * at different fan-outs.
994
+ */
995
+ export async function commitRivalTreeWrite<TKey, TEntry>(
996
+ inner: ITransactor,
997
+ collectionId: CollectionId,
998
+ keyFromEntry: (entry: TEntry) => TKey,
999
+ entries: TreeReplaceAction<TKey, TEntry>,
1000
+ ): Promise<void> {
1001
+ const tree = await Tree.createOrOpen<TKey, TEntry>(inner, collectionId, keyFromEntry);
1002
+ await tree.replace(entries);
1003
+ }
1004
+
1005
+ function newBlockState(): BlockState {
1006
+ return {
1007
+ materializedBlocks: new Map(),
1008
+ latestRev: 0,
1009
+ revisionActions: new Map(),
1010
+ pendingActions: new Map(),
1011
+ committedActions: new Map()
1012
+ };
1013
+ }
1014
+
1015
+ /** This block's latest committed revision in the shape {@link isOwnRevision} compares — the
1016
+ * harness equivalent of `IBlockStorage.getLatest()`. `undefined` when nothing is recorded at that
1017
+ * revision, which is how a never-written block reads (`latestRev` starts at 0 with no entry). */
1018
+ function latestActionRev(blockState: BlockState): ActionRev | undefined {
1019
+ const actionId = blockState.revisionActions.get(blockState.latestRev);
1020
+ return actionId === undefined ? undefined : { actionId, rev: blockState.latestRev };
1021
+ }
1022
+
1023
+ /** The committed content a read at `pin` sees — the highest materialized revision at or below
1024
+ * it — or the latest revision's content when the read is unpinned. */
1025
+ function committedAt(blockState: BlockState, pin: number | undefined): { block: IBlock, rev: number } | undefined {
1026
+ if (pin !== undefined) return latestMaterializedAt(blockState, pin);
1027
+ const block = blockState.materializedBlocks.get(blockState.latestRev);
1028
+ return block ? { block, rev: blockState.latestRev } : undefined;
1029
+ }
1030
+
1031
+ /** Returns the block as it stood at the highest revision ≤ the given revision that committed it,
1032
+ * together with that revision — the caller reports it as {@link GetBlockResult.materialized} — or
1033
+ * `undefined` when that revision deleted it, as storage answers a tombstone: a committed revision
1034
+ * with no materialized block is a delete, never a reason to serve the content before it. */
1035
+ function latestMaterializedAt(blockState: BlockState, maxRev: number): { block: IBlock, rev: number } | undefined {
1036
+ for (let rev = maxRev; rev >= 0; rev--) {
1037
+ const block = blockState.materializedBlocks.get(rev);
1038
+ if (block) return { block, rev };
1039
+ if (blockState.revisionActions.has(rev)) return undefined;
1040
+ }
1041
+ return undefined;
1042
+ }
1043
+
1044
+ /**
1045
+ * `applyTransform` over cloned inputs, so a returned block never aliases stored state.
1046
+ *
1047
+ * The `insert` clone here is not redundant with `transformForBlockId`'s: callers pass `Transform`
1048
+ * values pulled straight out of `blockState.pendingActions` (a `Map<ActionId, Transform>` written
1049
+ * once by `pend()`), which can be `get()`'d more than once and read again at commit time before
1050
+ * being superseded. `applyTransform` mutates `transform.insert` in place when `updates` ride
1051
+ * along, so cloning immediately before each call is what keeps that stored entry pristine across
1052
+ * repeated reads.
1053
+ *
1054
+ * An absent base is NOT a short circuit: an insert needs no base — `applyTransform` adopts it as
1055
+ * the block. Bailing out on `!block` made this double silently drop a pending-only insert read
1056
+ * through the pending overlay, the one shape `StorageRepo.get` serves with content but no
1057
+ * `materialized` (see docs/internals.md § the `unavailable`/`materialized` bullets). A
1058
+ * pending UPDATE over an absent base still resolves to undefined, matching the real repo.
1059
+ */
1060
+ function applyTransformSafe(block: IBlock | undefined, transform: Transform): IBlock | undefined {
1061
+ return applyTransform(
1062
+ block ? structuredClone(block) : undefined,
1063
+ transform.insert ? { ...transform, insert: structuredClone(transform.insert) } : transform
1064
+ );
1065
+ }