@optimystic/db-core 1.5.0 → 1.5.1

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 (152) hide show
  1. package/README.md +336 -336
  2. package/dist/src/collection/collection.d.ts +44 -4
  3. package/dist/src/collection/collection.d.ts.map +1 -1
  4. package/dist/src/collection/collection.js +95 -14
  5. package/dist/src/collection/collection.js.map +1 -1
  6. package/dist/src/log/log.d.ts +41 -8
  7. package/dist/src/log/log.d.ts.map +1 -1
  8. package/dist/src/log/log.js +15 -10
  9. package/dist/src/log/log.js.map +1 -1
  10. package/dist/src/testing/test-transactor.d.ts +36 -0
  11. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  12. package/dist/src/testing/test-transactor.js +49 -0
  13. package/dist/src/testing/test-transactor.js.map +1 -1
  14. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  15. package/dist/src/transaction/coordinator.js +26 -9
  16. package/dist/src/transaction/coordinator.js.map +1 -1
  17. package/package.json +1 -1
  18. package/src/blocks/block-store.ts +31 -31
  19. package/src/blocks/block-types.ts +11 -11
  20. package/src/blocks/index.ts +5 -5
  21. package/src/blocks/structs.ts +17 -17
  22. package/src/btree/btree.ts +872 -872
  23. package/src/btree/independent-trunk.ts +53 -53
  24. package/src/btree/index.ts +5 -5
  25. package/src/btree/key-range.ts +15 -15
  26. package/src/btree/keyset.ts +6 -6
  27. package/src/btree/nodes.ts +25 -25
  28. package/src/btree/path.ts +37 -37
  29. package/src/btree/tree-block.ts +11 -11
  30. package/src/btree/trunk.ts +14 -14
  31. package/src/chain/chain-nodes.ts +26 -26
  32. package/src/chain/chain.ts +349 -349
  33. package/src/chain/index.ts +3 -3
  34. package/src/cluster/i-cluster.ts +6 -6
  35. package/src/cluster/index.ts +3 -3
  36. package/src/cohort-topic/addressing.ts +120 -120
  37. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  38. package/src/cohort-topic/antidos/index.ts +5 -5
  39. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  40. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  41. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  42. package/src/cohort-topic/antiflood/index.ts +2 -2
  43. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  44. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  45. package/src/cohort-topic/coldstart.ts +237 -237
  46. package/src/cohort-topic/dmax.ts +88 -88
  47. package/src/cohort-topic/gossip/bus.ts +254 -254
  48. package/src/cohort-topic/gossip/index.ts +3 -3
  49. package/src/cohort-topic/gossip/records.ts +45 -45
  50. package/src/cohort-topic/gossip/view.ts +91 -91
  51. package/src/cohort-topic/index.ts +20 -20
  52. package/src/cohort-topic/load/barometer.ts +134 -134
  53. package/src/cohort-topic/load/index.ts +1 -1
  54. package/src/cohort-topic/member-engine.ts +430 -430
  55. package/src/cohort-topic/membership/index.ts +3 -3
  56. package/src/cohort-topic/membership/publisher.ts +163 -163
  57. package/src/cohort-topic/membership/source.ts +41 -41
  58. package/src/cohort-topic/ports.ts +157 -157
  59. package/src/cohort-topic/promotion.ts +477 -477
  60. package/src/cohort-topic/registration/bytes.ts +37 -37
  61. package/src/cohort-topic/registration/handoff.ts +154 -154
  62. package/src/cohort-topic/registration/index.ts +6 -6
  63. package/src/cohort-topic/registration/renewal.ts +495 -495
  64. package/src/cohort-topic/registration/sharding.ts +61 -61
  65. package/src/cohort-topic/registration/store.ts +81 -81
  66. package/src/cohort-topic/registration/types.ts +91 -91
  67. package/src/cohort-topic/ring-hash.ts +50 -50
  68. package/src/cohort-topic/service.ts +416 -416
  69. package/src/cohort-topic/sig/index.ts +2 -2
  70. package/src/cohort-topic/sig/payloads.ts +59 -59
  71. package/src/cohort-topic/sig/threshold.ts +64 -64
  72. package/src/cohort-topic/tiers.ts +74 -74
  73. package/src/cohort-topic/traffic.ts +233 -233
  74. package/src/cohort-topic/walk.ts +326 -326
  75. package/src/cohort-topic/willingness.ts +237 -237
  76. package/src/cohort-topic/wire/index.ts +18 -18
  77. package/src/cohort-topic/wire/payloads.ts +126 -126
  78. package/src/collection/action.ts +48 -48
  79. package/src/collection/collection-type-registry.ts +37 -37
  80. package/src/collection/collection.ts +2203 -2118
  81. package/src/collection/index.ts +4 -4
  82. package/src/collections/diary/index.ts +2 -2
  83. package/src/collections/diary/struct.ts +3 -3
  84. package/src/collections/index.ts +2 -2
  85. package/src/collections/tree/collection-trunk.ts +25 -25
  86. package/src/collections/tree/index.ts +2 -2
  87. package/src/collections/tree/readme.md +55 -55
  88. package/src/log/index.ts +2 -2
  89. package/src/log/log.ts +304 -268
  90. package/src/log/struct.ts +165 -165
  91. package/src/matchmaking/capability-filter.ts +45 -45
  92. package/src/matchmaking/config.ts +98 -98
  93. package/src/matchmaking/index.ts +21 -21
  94. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  95. package/src/matchmaking/provider.ts +123 -123
  96. package/src/matchmaking/query-eval.ts +105 -105
  97. package/src/matchmaking/seeker-walk.ts +127 -127
  98. package/src/matchmaking/seeker.ts +86 -86
  99. package/src/matchmaking/topic-anchor.ts +90 -90
  100. package/src/matchmaking/voting-quorum.ts +394 -394
  101. package/src/network/i-peer-network.ts +25 -25
  102. package/src/network/repo-protocol.ts +13 -13
  103. package/src/network/types.ts +37 -37
  104. package/src/reactivity/backfill.ts +220 -220
  105. package/src/reactivity/backpressure.ts +191 -191
  106. package/src/reactivity/checkpoint.ts +308 -308
  107. package/src/reactivity/config.ts +172 -172
  108. package/src/reactivity/dedupe.ts +132 -132
  109. package/src/reactivity/forwarder.ts +87 -87
  110. package/src/reactivity/index.ts +34 -34
  111. package/src/reactivity/notification.ts +123 -123
  112. package/src/reactivity/policy.ts +79 -79
  113. package/src/reactivity/push-state.ts +310 -310
  114. package/src/reactivity/recover.ts +153 -153
  115. package/src/reactivity/replay-buffer.ts +141 -141
  116. package/src/reactivity/resume.ts +549 -549
  117. package/src/reactivity/rotation.ts +415 -415
  118. package/src/reactivity/subscriber.ts +132 -132
  119. package/src/reactivity/subscription.ts +66 -66
  120. package/src/reactivity/topic-anchor.ts +71 -71
  121. package/src/reactivity/verify.ts +73 -73
  122. package/src/reactivity/wire-validate.ts +13 -13
  123. package/src/testing/async-wait.ts +65 -65
  124. package/src/testing/index.ts +2 -2
  125. package/src/testing/test-transactor.ts +62 -0
  126. package/src/transaction/actions-engine.ts +68 -68
  127. package/src/transaction/coordinator.ts +28 -11
  128. package/src/transaction/index.ts +52 -52
  129. package/src/transaction/operations-hash.ts +196 -196
  130. package/src/transaction/read-dependency-collector.ts +78 -78
  131. package/src/transaction/session.ts +238 -238
  132. package/src/transaction/transaction.ts +442 -442
  133. package/src/transaction/validator.ts +197 -197
  134. package/src/transactor/block-floors.ts +126 -126
  135. package/src/transactor/index.ts +6 -6
  136. package/src/transactor/network-transactor.ts +1545 -1545
  137. package/src/transform/atomic-proxy.ts +92 -92
  138. package/src/transform/cache-source.ts +370 -370
  139. package/src/transform/helpers.ts +164 -164
  140. package/src/transform/index.ts +7 -7
  141. package/src/transform/struct.ts +21 -21
  142. package/src/utility/actor.ts +62 -62
  143. package/src/utility/backoff.ts +95 -95
  144. package/src/utility/batch-coordinator.ts +191 -191
  145. package/src/utility/ensured.ts +32 -32
  146. package/src/utility/groupby.ts +18 -18
  147. package/src/utility/hash-string.ts +14 -14
  148. package/src/utility/is-record-empty.ts +5 -5
  149. package/src/utility/latches.ts +42 -42
  150. package/src/utility/lru-map.ts +60 -60
  151. package/src/utility/nameof.ts +7 -7
  152. package/src/utility/pending.ts +43 -43
@@ -1,349 +1,349 @@
1
- import { Atomic } from "../transform/atomic.js";
2
- import type { BlockStore, BlockId, IBlock } from "../index.js";
3
- import { ChainDataBlockType, ChainHeaderBlockType, entries$, headId$, nextId$, priorId$, tailId$ } from "./chain-nodes.js";
4
- import type { ChainDataNode, ChainHeaderNode } from "./chain-nodes.js";
5
- import { apply } from "../blocks/index.js";
6
-
7
- export const EntriesPerBlock = 32;
8
-
9
- export type ChainPath<TEntry> = {
10
- headerBlock: ChainHeaderNode;
11
- block: ChainDataNode<TEntry>;
12
- index: number; // Index of the entry in the block
13
- };
14
-
15
- export type ChainNodeInit<T> = IBlock & {
16
- [K in keyof Omit<T, keyof IBlock>]?: T[K];
17
- };
18
-
19
- export type ChainInitOptions<TEntry> = {
20
- createDataBlock?: () => ChainNodeInit<ChainDataNode<TEntry>>;
21
- createHeaderBlock?: (id?: BlockId) => ChainNodeInit<ChainHeaderNode>;
22
- newBlock?: (newTail: ChainDataNode<TEntry>, oldTail: ChainDataNode<TEntry> | undefined) => Promise<void>;
23
- }
24
-
25
- export type ChainCreateOptions<TEntry> = ChainInitOptions<TEntry> & {
26
- newId?: BlockId;
27
- /** Use an already-inserted block as the chain header instead of creating a new one.
28
- * headId and tailId will be set on it via apply(). */
29
- existingHeaderId?: BlockId;
30
- };
31
-
32
- /** Represents a chain of blocks, forming a stack, queue, or log. */
33
- export class Chain<TEntry> {
34
- private constructor(
35
- readonly store: BlockStore<IBlock>,
36
- public readonly id: BlockId,
37
- private readonly options?: ChainInitOptions<TEntry>,
38
- ) {
39
- }
40
-
41
- /** Creates a new queue, with an optional given id. */
42
- static async create<TEntry>(store: BlockStore<IBlock>, options?: ChainCreateOptions<TEntry>) {
43
- const tailBlock = Chain.createTailBlock<TEntry>(store, options);
44
-
45
- if (options?.existingHeaderId) {
46
- // Use an already-inserted block as the chain header
47
- const existing = await store.tryGet(options.existingHeaderId);
48
- if (!existing) {
49
- throw new Error(`Existing header block ${options.existingHeaderId} not found`);
50
- }
51
- apply(store, existing, [headId$, 0, 0, tailBlock.header.id]);
52
- apply(store, existing, [tailId$, 0, 0, tailBlock.header.id]);
53
- store.insert(tailBlock);
54
- return new Chain<TEntry>(store, existing.header.id, options);
55
- }
56
-
57
- const headerBlock = {
58
- ...(options?.createHeaderBlock?.(options?.newId) ?? { header: store.createBlockHeader(ChainHeaderBlockType, options?.newId) }),
59
- headId: tailBlock.header.id,
60
- tailId: tailBlock.header.id,
61
- } as ChainHeaderNode;
62
- store.insert(headerBlock);
63
- store.insert(tailBlock);
64
- return new Chain<TEntry>(store, headerBlock.header.id, options);
65
- }
66
-
67
- private static createTailBlock<TEntry>(store: BlockStore<IBlock>, options: ChainCreateOptions<TEntry> | undefined) {
68
- return {
69
- ...(options?.createDataBlock?.() ?? { header: store.createBlockHeader(ChainDataBlockType) }),
70
- entries: [] as TEntry[],
71
- priorId: undefined,
72
- nextId: undefined,
73
- } as ChainDataNode<TEntry>;
74
- }
75
-
76
- /** Opens an existing chain, verifying and potentially initializing the header. */
77
- static async open<TEntry>(store: BlockStore<IBlock>, id: BlockId, options?: ChainInitOptions<TEntry>): Promise<Chain<TEntry> | undefined> {
78
- const headerBlock = await store.tryGet(id) as ChainHeaderNode | undefined;
79
- if (!headerBlock) {
80
- return undefined;
81
- }
82
-
83
- // If the header block is missing headId or tailId, create a tail block and update the header
84
- const headerAny = headerBlock as any; // Use 'any' for easier property checking/setting
85
- if (!Object.hasOwn(headerAny, 'headId') || !Object.hasOwn(headerAny, 'tailId')) {
86
- const tailBlock = Chain.createTailBlock<TEntry>(store, options);
87
- store.insert(tailBlock);
88
- apply(store, headerBlock, [headId$, 0, 0, tailBlock.header.id]);
89
- apply(store, headerBlock, [tailId$, 0, 0, tailBlock.header.id]);
90
- }
91
-
92
- return new Chain<TEntry>(store, id, options);
93
- }
94
-
95
- /**
96
- * Adds entries to the tail (last-in end) of the chain. Equivalent of enqueue or push.
97
- * @param entries - The entries to add.
98
- * @returns Path to the new tail of the chain (entry just past the end).
99
- */
100
- async add(...entries: TEntry[]): Promise<ChainPath<TEntry>> {
101
- const path = await this.getTail();
102
- if (!path) {
103
- throw new Error("Cannot add to non-existent chain");
104
- }
105
-
106
- const { headerBlock, block: oldTail } = path;
107
- let tail = oldTail;
108
-
109
- const trx = new Atomic(this.store);
110
-
111
- // Attempt to fit in current block
112
- const copied = entries.slice(0, EntriesPerBlock - tail.entries.length);
113
- if (copied.length > 0) {
114
- apply(trx, tail, [entries$, tail.entries.length, 0, copied]);
115
- entries = entries.slice(copied.length);
116
- }
117
-
118
- while (entries.length > 0) {
119
- const newTail = {
120
- ...(this.options?.createDataBlock?.() ?? { header: this.store.createBlockHeader(ChainDataBlockType) }),
121
- entries: entries.splice(0, Math.min(EntriesPerBlock, entries.length)),
122
- priorId: tail.header.id,
123
- nextId: undefined,
124
- } as ChainDataNode<TEntry>;
125
- // Predecessor is the running `tail` (immediately preceding block), NOT the original
126
- // `oldTail`: across a multi-block append each new block links to the one before it.
127
- await this.options?.newBlock?.(newTail, tail);
128
- trx.insert(newTail);
129
- apply(trx, tail, [nextId$, 0, 0, newTail.header.id]);
130
- tail = newTail;
131
- }
132
-
133
- if (tail !== oldTail) {
134
- apply(trx, headerBlock, [tailId$, 0, 0, tail.header.id]);
135
- }
136
-
137
- trx.commit();
138
-
139
- return { headerBlock, block: tail, index: tail.entries.length - 1 };
140
- }
141
-
142
- /** Updates the entry at the given path. */
143
- updateAt(path: ChainPath<TEntry>, entry: TEntry) {
144
- if (!pathValid(path)) {
145
- throw new Error("Invalid path");
146
- }
147
- const { index, block } = path;
148
- apply(this.store, block, [entries$, index, 1, [entry]]);
149
- }
150
-
151
- /**
152
- * Removes up to n entries from the tail (last-in end) of the chain.
153
- * @param n - The number of entries to remove. If n is greater than the number of entries in the chain, the chain is emptied with no error.
154
- * @returns An array of the removed entries. May be less than n if the chain is exhausted.
155
- */
156
- async pop(n = 1) {
157
- if (n <= 0) {
158
- return [];
159
- }
160
-
161
- const path = await this.getTail();
162
- if (!path) {
163
- return [];
164
- }
165
-
166
- const { headerBlock, block: oldTail } = path;
167
- let tail = oldTail;
168
- const result = [];
169
-
170
- const trx = new Atomic(this.store);
171
-
172
- while (n > 0) {
173
- if (tail.entries.length > n) { // Partial removal
174
- const removed = tail.entries.slice(-n);
175
- result.unshift(...removed);
176
- apply(trx, tail, [entries$, tail.entries.length - n, n, []]);
177
- break;
178
- } else { // Entire block removal
179
- result.unshift(...tail.entries);
180
- n -= tail.entries.length;
181
- if (tail.priorId) {
182
- trx.delete(tail.header.id);
183
- tail = await trx.tryGet(tail.priorId) as ChainDataNode<TEntry>;
184
- apply(trx, tail, [nextId$, 0, 0, undefined]);
185
- } else { // No more blocks... just empty what's left
186
- apply(trx, tail, [entries$, 0, tail.entries.length, []]);
187
- break;
188
- }
189
- }
190
- }
191
-
192
- if (tail !== oldTail) {
193
- apply(trx, headerBlock, [tailId$, 0, 0, tail.header.id]);
194
- }
195
-
196
- trx.commit();
197
-
198
- return result;
199
- }
200
-
201
- /**
202
- * Removes up to n entries from the head (first-in end) of the queue.
203
- * @param n - The number of entries to remove. If n is greater than the number of entries in the chain, the chain is emptied with no error.
204
- * @returns An array of the removed entries. May be less than n if the queue is exhausted.
205
- */
206
- async dequeue(n = 1) {
207
- if (n <= 0) {
208
- return [];
209
- }
210
-
211
- const trx = new Atomic(this.store);
212
-
213
- const path = await this.getHead();
214
- if (!path) {
215
- return [];
216
- }
217
-
218
- const { headerBlock, block: oldHead } = path;
219
- let head = oldHead;
220
- const result = [];
221
-
222
- while (n > 0) {
223
- if (head.entries.length > n) { // Consumes part of block
224
- result.push(...head.entries.slice(0, n));
225
- apply(trx, head, [entries$, 0, n, []]);
226
- break;
227
- } else { // Consumes entire block
228
- result.push(...head.entries);
229
- n -= head.entries.length;
230
- if (head.nextId) {
231
- trx.delete(head.header.id);
232
- head = await trx.tryGet(head.nextId) as ChainDataNode<TEntry>;
233
- apply(trx, head, [priorId$, 0, 0, undefined]);
234
- } else { // No more blocks... just empty what's left
235
- apply(trx, head, [entries$, 0, head.entries.length, []]);
236
- break;
237
- }
238
- }
239
- }
240
- if (head !== oldHead) {
241
- apply(trx, headerBlock, [headId$, 0, 0, head.header.id]);
242
- }
243
-
244
- trx.commit();
245
-
246
- return result;
247
- }
248
-
249
- /** Iterates over the chain, starting at the given path, or the head or tail if not given.
250
- * If forward is true (default), the iteration is from head (oldest) to tail (latest); otherwise, it is from tail to head.
251
- */
252
- async *select(starting?: ChainPath<TEntry>, forward = true): AsyncIterableIterator<ChainPath<TEntry>> {
253
- const path = starting ?? (forward ? await this.getHead() : await this.getTail());
254
- if (!path) {
255
- return;
256
- }
257
- let block: ChainDataNode<TEntry> | undefined = path.block;
258
-
259
- let index = path.index;
260
- if (forward) {
261
- while (block) {
262
- for (; index < block.entries.length; ++index) {
263
- yield { headerBlock: path.headerBlock, block, index };
264
- }
265
- block = block.nextId ? await this.store.tryGet(block.nextId) as ChainDataNode<TEntry> : undefined;
266
- index = 0;
267
- }
268
- } else {
269
- while (block) {
270
- for (; index >= 0; --index) {
271
- yield { headerBlock: path.headerBlock, block, index };
272
- }
273
- block = block.priorId ? await this.store.tryGet(block.priorId) as ChainDataNode<TEntry> : undefined;
274
- index = (block?.entries.length ?? 0) - 1;
275
- }
276
- }
277
- }
278
-
279
- /** Returns the next entry in the chain; returns an off-the-end path if the end is reached. */
280
- async next(path: ChainPath<TEntry>) {
281
- const { headerBlock, block, index } = path;
282
- if (index < block.entries.length - 1 || !block.nextId) {
283
- return { headerBlock, block, index: index + 1 };
284
- }
285
- return {
286
- headerBlock,
287
- block: await this.store.tryGet(block.nextId) as ChainDataNode<TEntry>,
288
- index: 0,
289
- };
290
- }
291
-
292
- /** Returns the previous entry in the chain; returns an off-the-start path if the start is reached. */
293
- async prev(path: ChainPath<TEntry>) {
294
- const { headerBlock, block, index } = path;
295
- if (index > 0 || !block.priorId) {
296
- return { headerBlock, block, index: index - 1 };
297
- }
298
- const priorBlock = await this.store.tryGet(block.priorId) as ChainDataNode<TEntry>;
299
- return {
300
- headerBlock,
301
- block: priorBlock,
302
- index: priorBlock.entries.length - 1,
303
- };
304
- }
305
-
306
- // NOTE: chain walks (getTail/getHead/select/next/prev) read via `store.tryGet(id)` with the
307
- // DEFAULT read purpose (`value`), so every chain node stays in the OCC conflict set. This is
308
- // deliberate: the chain backs the log, whose tail is the commit-ordering race arbiter (OCC
309
- // "tail binding"), and enumerations return a shape-dependent result set — both are load-bearing
310
- // reads that MUST be retained. The B-tree point-lookup navigation exclusion (ticket 4.7) is NOT
311
- // applied here. If chain navigation reads ever need excluding, tag ONLY intermediate hops of a
312
- // walk that terminates in a consumed entry, and NEVER the tail/header — get the safety predicate
313
- // right first (docs/correctness.md Theorem 5).
314
- async getTail(header?: ChainHeaderNode): Promise<ChainPath<TEntry> | undefined> {
315
- const headerBlock = header ?? await this.getHeader();
316
- let tail = headerBlock ? await this.store.tryGet(headerBlock.tailId) as ChainDataNode<TEntry> : undefined;
317
- // Possible that the block has filled between reading the header and reading the block... follow nextId links to find true end
318
- while (tail?.nextId) {
319
- tail = await this.store.tryGet(tail.nextId) as ChainDataNode<TEntry>;
320
- }
321
- return tail ? { headerBlock, block: tail, index: tail.entries.length - 1 } as ChainPath<TEntry> : undefined;
322
- }
323
-
324
-
325
- async getHead(header?: ChainHeaderNode): Promise<ChainPath<TEntry> | undefined> {
326
- const headerBlock = header ?? await this.getHeader();
327
- let head = headerBlock ? await this.store.tryGet(headerBlock.headId) as ChainDataNode<TEntry> : undefined;
328
- // Possible that the block has filled between reading the header and reading the block... follow priorId links to find true start
329
- while (head?.priorId) {
330
- head = await this.store.tryGet(head.priorId) as ChainDataNode<TEntry>;
331
- }
332
- return head ? { headerBlock, block: head, index: 0 } as ChainPath<TEntry> : undefined;
333
- }
334
-
335
-
336
- async getHeader() {
337
- return await this.store.tryGet(this.id) as ChainHeaderNode | undefined;
338
- }
339
- }
340
-
341
- /** Returns true if the given path is located on an entry (not a crack). */
342
- export function pathValid<TEntry>(path: ChainPath<TEntry>) {
343
- return path.block.entries.length > path.index && path.index >= 0;
344
- }
345
-
346
- /** Gets the entry at the given path; undefined if the path is not valid. */
347
- export function entryAt<TEntry>(path: ChainPath<TEntry>): TEntry | undefined {
348
- return path.block.entries[path.index];
349
- }
1
+ import { Atomic } from "../transform/atomic.js";
2
+ import type { BlockStore, BlockId, IBlock } from "../index.js";
3
+ import { ChainDataBlockType, ChainHeaderBlockType, entries$, headId$, nextId$, priorId$, tailId$ } from "./chain-nodes.js";
4
+ import type { ChainDataNode, ChainHeaderNode } from "./chain-nodes.js";
5
+ import { apply } from "../blocks/index.js";
6
+
7
+ export const EntriesPerBlock = 32;
8
+
9
+ export type ChainPath<TEntry> = {
10
+ headerBlock: ChainHeaderNode;
11
+ block: ChainDataNode<TEntry>;
12
+ index: number; // Index of the entry in the block
13
+ };
14
+
15
+ export type ChainNodeInit<T> = IBlock & {
16
+ [K in keyof Omit<T, keyof IBlock>]?: T[K];
17
+ };
18
+
19
+ export type ChainInitOptions<TEntry> = {
20
+ createDataBlock?: () => ChainNodeInit<ChainDataNode<TEntry>>;
21
+ createHeaderBlock?: (id?: BlockId) => ChainNodeInit<ChainHeaderNode>;
22
+ newBlock?: (newTail: ChainDataNode<TEntry>, oldTail: ChainDataNode<TEntry> | undefined) => Promise<void>;
23
+ }
24
+
25
+ export type ChainCreateOptions<TEntry> = ChainInitOptions<TEntry> & {
26
+ newId?: BlockId;
27
+ /** Use an already-inserted block as the chain header instead of creating a new one.
28
+ * headId and tailId will be set on it via apply(). */
29
+ existingHeaderId?: BlockId;
30
+ };
31
+
32
+ /** Represents a chain of blocks, forming a stack, queue, or log. */
33
+ export class Chain<TEntry> {
34
+ private constructor(
35
+ readonly store: BlockStore<IBlock>,
36
+ public readonly id: BlockId,
37
+ private readonly options?: ChainInitOptions<TEntry>,
38
+ ) {
39
+ }
40
+
41
+ /** Creates a new queue, with an optional given id. */
42
+ static async create<TEntry>(store: BlockStore<IBlock>, options?: ChainCreateOptions<TEntry>) {
43
+ const tailBlock = Chain.createTailBlock<TEntry>(store, options);
44
+
45
+ if (options?.existingHeaderId) {
46
+ // Use an already-inserted block as the chain header
47
+ const existing = await store.tryGet(options.existingHeaderId);
48
+ if (!existing) {
49
+ throw new Error(`Existing header block ${options.existingHeaderId} not found`);
50
+ }
51
+ apply(store, existing, [headId$, 0, 0, tailBlock.header.id]);
52
+ apply(store, existing, [tailId$, 0, 0, tailBlock.header.id]);
53
+ store.insert(tailBlock);
54
+ return new Chain<TEntry>(store, existing.header.id, options);
55
+ }
56
+
57
+ const headerBlock = {
58
+ ...(options?.createHeaderBlock?.(options?.newId) ?? { header: store.createBlockHeader(ChainHeaderBlockType, options?.newId) }),
59
+ headId: tailBlock.header.id,
60
+ tailId: tailBlock.header.id,
61
+ } as ChainHeaderNode;
62
+ store.insert(headerBlock);
63
+ store.insert(tailBlock);
64
+ return new Chain<TEntry>(store, headerBlock.header.id, options);
65
+ }
66
+
67
+ private static createTailBlock<TEntry>(store: BlockStore<IBlock>, options: ChainCreateOptions<TEntry> | undefined) {
68
+ return {
69
+ ...(options?.createDataBlock?.() ?? { header: store.createBlockHeader(ChainDataBlockType) }),
70
+ entries: [] as TEntry[],
71
+ priorId: undefined,
72
+ nextId: undefined,
73
+ } as ChainDataNode<TEntry>;
74
+ }
75
+
76
+ /** Opens an existing chain, verifying and potentially initializing the header. */
77
+ static async open<TEntry>(store: BlockStore<IBlock>, id: BlockId, options?: ChainInitOptions<TEntry>): Promise<Chain<TEntry> | undefined> {
78
+ const headerBlock = await store.tryGet(id) as ChainHeaderNode | undefined;
79
+ if (!headerBlock) {
80
+ return undefined;
81
+ }
82
+
83
+ // If the header block is missing headId or tailId, create a tail block and update the header
84
+ const headerAny = headerBlock as any; // Use 'any' for easier property checking/setting
85
+ if (!Object.hasOwn(headerAny, 'headId') || !Object.hasOwn(headerAny, 'tailId')) {
86
+ const tailBlock = Chain.createTailBlock<TEntry>(store, options);
87
+ store.insert(tailBlock);
88
+ apply(store, headerBlock, [headId$, 0, 0, tailBlock.header.id]);
89
+ apply(store, headerBlock, [tailId$, 0, 0, tailBlock.header.id]);
90
+ }
91
+
92
+ return new Chain<TEntry>(store, id, options);
93
+ }
94
+
95
+ /**
96
+ * Adds entries to the tail (last-in end) of the chain. Equivalent of enqueue or push.
97
+ * @param entries - The entries to add.
98
+ * @returns Path to the new tail of the chain (entry just past the end).
99
+ */
100
+ async add(...entries: TEntry[]): Promise<ChainPath<TEntry>> {
101
+ const path = await this.getTail();
102
+ if (!path) {
103
+ throw new Error("Cannot add to non-existent chain");
104
+ }
105
+
106
+ const { headerBlock, block: oldTail } = path;
107
+ let tail = oldTail;
108
+
109
+ const trx = new Atomic(this.store);
110
+
111
+ // Attempt to fit in current block
112
+ const copied = entries.slice(0, EntriesPerBlock - tail.entries.length);
113
+ if (copied.length > 0) {
114
+ apply(trx, tail, [entries$, tail.entries.length, 0, copied]);
115
+ entries = entries.slice(copied.length);
116
+ }
117
+
118
+ while (entries.length > 0) {
119
+ const newTail = {
120
+ ...(this.options?.createDataBlock?.() ?? { header: this.store.createBlockHeader(ChainDataBlockType) }),
121
+ entries: entries.splice(0, Math.min(EntriesPerBlock, entries.length)),
122
+ priorId: tail.header.id,
123
+ nextId: undefined,
124
+ } as ChainDataNode<TEntry>;
125
+ // Predecessor is the running `tail` (immediately preceding block), NOT the original
126
+ // `oldTail`: across a multi-block append each new block links to the one before it.
127
+ await this.options?.newBlock?.(newTail, tail);
128
+ trx.insert(newTail);
129
+ apply(trx, tail, [nextId$, 0, 0, newTail.header.id]);
130
+ tail = newTail;
131
+ }
132
+
133
+ if (tail !== oldTail) {
134
+ apply(trx, headerBlock, [tailId$, 0, 0, tail.header.id]);
135
+ }
136
+
137
+ trx.commit();
138
+
139
+ return { headerBlock, block: tail, index: tail.entries.length - 1 };
140
+ }
141
+
142
+ /** Updates the entry at the given path. */
143
+ updateAt(path: ChainPath<TEntry>, entry: TEntry) {
144
+ if (!pathValid(path)) {
145
+ throw new Error("Invalid path");
146
+ }
147
+ const { index, block } = path;
148
+ apply(this.store, block, [entries$, index, 1, [entry]]);
149
+ }
150
+
151
+ /**
152
+ * Removes up to n entries from the tail (last-in end) of the chain.
153
+ * @param n - The number of entries to remove. If n is greater than the number of entries in the chain, the chain is emptied with no error.
154
+ * @returns An array of the removed entries. May be less than n if the chain is exhausted.
155
+ */
156
+ async pop(n = 1) {
157
+ if (n <= 0) {
158
+ return [];
159
+ }
160
+
161
+ const path = await this.getTail();
162
+ if (!path) {
163
+ return [];
164
+ }
165
+
166
+ const { headerBlock, block: oldTail } = path;
167
+ let tail = oldTail;
168
+ const result = [];
169
+
170
+ const trx = new Atomic(this.store);
171
+
172
+ while (n > 0) {
173
+ if (tail.entries.length > n) { // Partial removal
174
+ const removed = tail.entries.slice(-n);
175
+ result.unshift(...removed);
176
+ apply(trx, tail, [entries$, tail.entries.length - n, n, []]);
177
+ break;
178
+ } else { // Entire block removal
179
+ result.unshift(...tail.entries);
180
+ n -= tail.entries.length;
181
+ if (tail.priorId) {
182
+ trx.delete(tail.header.id);
183
+ tail = await trx.tryGet(tail.priorId) as ChainDataNode<TEntry>;
184
+ apply(trx, tail, [nextId$, 0, 0, undefined]);
185
+ } else { // No more blocks... just empty what's left
186
+ apply(trx, tail, [entries$, 0, tail.entries.length, []]);
187
+ break;
188
+ }
189
+ }
190
+ }
191
+
192
+ if (tail !== oldTail) {
193
+ apply(trx, headerBlock, [tailId$, 0, 0, tail.header.id]);
194
+ }
195
+
196
+ trx.commit();
197
+
198
+ return result;
199
+ }
200
+
201
+ /**
202
+ * Removes up to n entries from the head (first-in end) of the queue.
203
+ * @param n - The number of entries to remove. If n is greater than the number of entries in the chain, the chain is emptied with no error.
204
+ * @returns An array of the removed entries. May be less than n if the queue is exhausted.
205
+ */
206
+ async dequeue(n = 1) {
207
+ if (n <= 0) {
208
+ return [];
209
+ }
210
+
211
+ const trx = new Atomic(this.store);
212
+
213
+ const path = await this.getHead();
214
+ if (!path) {
215
+ return [];
216
+ }
217
+
218
+ const { headerBlock, block: oldHead } = path;
219
+ let head = oldHead;
220
+ const result = [];
221
+
222
+ while (n > 0) {
223
+ if (head.entries.length > n) { // Consumes part of block
224
+ result.push(...head.entries.slice(0, n));
225
+ apply(trx, head, [entries$, 0, n, []]);
226
+ break;
227
+ } else { // Consumes entire block
228
+ result.push(...head.entries);
229
+ n -= head.entries.length;
230
+ if (head.nextId) {
231
+ trx.delete(head.header.id);
232
+ head = await trx.tryGet(head.nextId) as ChainDataNode<TEntry>;
233
+ apply(trx, head, [priorId$, 0, 0, undefined]);
234
+ } else { // No more blocks... just empty what's left
235
+ apply(trx, head, [entries$, 0, head.entries.length, []]);
236
+ break;
237
+ }
238
+ }
239
+ }
240
+ if (head !== oldHead) {
241
+ apply(trx, headerBlock, [headId$, 0, 0, head.header.id]);
242
+ }
243
+
244
+ trx.commit();
245
+
246
+ return result;
247
+ }
248
+
249
+ /** Iterates over the chain, starting at the given path, or the head or tail if not given.
250
+ * If forward is true (default), the iteration is from head (oldest) to tail (latest); otherwise, it is from tail to head.
251
+ */
252
+ async *select(starting?: ChainPath<TEntry>, forward = true): AsyncIterableIterator<ChainPath<TEntry>> {
253
+ const path = starting ?? (forward ? await this.getHead() : await this.getTail());
254
+ if (!path) {
255
+ return;
256
+ }
257
+ let block: ChainDataNode<TEntry> | undefined = path.block;
258
+
259
+ let index = path.index;
260
+ if (forward) {
261
+ while (block) {
262
+ for (; index < block.entries.length; ++index) {
263
+ yield { headerBlock: path.headerBlock, block, index };
264
+ }
265
+ block = block.nextId ? await this.store.tryGet(block.nextId) as ChainDataNode<TEntry> : undefined;
266
+ index = 0;
267
+ }
268
+ } else {
269
+ while (block) {
270
+ for (; index >= 0; --index) {
271
+ yield { headerBlock: path.headerBlock, block, index };
272
+ }
273
+ block = block.priorId ? await this.store.tryGet(block.priorId) as ChainDataNode<TEntry> : undefined;
274
+ index = (block?.entries.length ?? 0) - 1;
275
+ }
276
+ }
277
+ }
278
+
279
+ /** Returns the next entry in the chain; returns an off-the-end path if the end is reached. */
280
+ async next(path: ChainPath<TEntry>) {
281
+ const { headerBlock, block, index } = path;
282
+ if (index < block.entries.length - 1 || !block.nextId) {
283
+ return { headerBlock, block, index: index + 1 };
284
+ }
285
+ return {
286
+ headerBlock,
287
+ block: await this.store.tryGet(block.nextId) as ChainDataNode<TEntry>,
288
+ index: 0,
289
+ };
290
+ }
291
+
292
+ /** Returns the previous entry in the chain; returns an off-the-start path if the start is reached. */
293
+ async prev(path: ChainPath<TEntry>) {
294
+ const { headerBlock, block, index } = path;
295
+ if (index > 0 || !block.priorId) {
296
+ return { headerBlock, block, index: index - 1 };
297
+ }
298
+ const priorBlock = await this.store.tryGet(block.priorId) as ChainDataNode<TEntry>;
299
+ return {
300
+ headerBlock,
301
+ block: priorBlock,
302
+ index: priorBlock.entries.length - 1,
303
+ };
304
+ }
305
+
306
+ // NOTE: chain walks (getTail/getHead/select/next/prev) read via `store.tryGet(id)` with the
307
+ // DEFAULT read purpose (`value`), so every chain node stays in the OCC conflict set. This is
308
+ // deliberate: the chain backs the log, whose tail is the commit-ordering race arbiter (OCC
309
+ // "tail binding"), and enumerations return a shape-dependent result set — both are load-bearing
310
+ // reads that MUST be retained. The B-tree point-lookup navigation exclusion (ticket 4.7) is NOT
311
+ // applied here. If chain navigation reads ever need excluding, tag ONLY intermediate hops of a
312
+ // walk that terminates in a consumed entry, and NEVER the tail/header — get the safety predicate
313
+ // right first (docs/correctness.md Theorem 5).
314
+ async getTail(header?: ChainHeaderNode): Promise<ChainPath<TEntry> | undefined> {
315
+ const headerBlock = header ?? await this.getHeader();
316
+ let tail = headerBlock ? await this.store.tryGet(headerBlock.tailId) as ChainDataNode<TEntry> : undefined;
317
+ // Possible that the block has filled between reading the header and reading the block... follow nextId links to find true end
318
+ while (tail?.nextId) {
319
+ tail = await this.store.tryGet(tail.nextId) as ChainDataNode<TEntry>;
320
+ }
321
+ return tail ? { headerBlock, block: tail, index: tail.entries.length - 1 } as ChainPath<TEntry> : undefined;
322
+ }
323
+
324
+
325
+ async getHead(header?: ChainHeaderNode): Promise<ChainPath<TEntry> | undefined> {
326
+ const headerBlock = header ?? await this.getHeader();
327
+ let head = headerBlock ? await this.store.tryGet(headerBlock.headId) as ChainDataNode<TEntry> : undefined;
328
+ // Possible that the block has filled between reading the header and reading the block... follow priorId links to find true start
329
+ while (head?.priorId) {
330
+ head = await this.store.tryGet(head.priorId) as ChainDataNode<TEntry>;
331
+ }
332
+ return head ? { headerBlock, block: head, index: 0 } as ChainPath<TEntry> : undefined;
333
+ }
334
+
335
+
336
+ async getHeader() {
337
+ return await this.store.tryGet(this.id) as ChainHeaderNode | undefined;
338
+ }
339
+ }
340
+
341
+ /** Returns true if the given path is located on an entry (not a crack). */
342
+ export function pathValid<TEntry>(path: ChainPath<TEntry>) {
343
+ return path.block.entries.length > path.index && path.index >= 0;
344
+ }
345
+
346
+ /** Gets the entry at the given path; undefined if the path is not valid. */
347
+ export function entryAt<TEntry>(path: ChainPath<TEntry>): TEntry | undefined {
348
+ return path.block.entries[path.index];
349
+ }