@optimystic/db-core 1.4.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 (157) 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/collections/tree/struct.d.ts +9 -4
  7. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  8. package/dist/src/collections/tree/struct.js +9 -4
  9. package/dist/src/collections/tree/struct.js.map +1 -1
  10. package/dist/src/log/log.d.ts +41 -8
  11. package/dist/src/log/log.d.ts.map +1 -1
  12. package/dist/src/log/log.js +15 -10
  13. package/dist/src/log/log.js.map +1 -1
  14. package/dist/src/testing/test-transactor.d.ts +36 -0
  15. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  16. package/dist/src/testing/test-transactor.js +49 -0
  17. package/dist/src/testing/test-transactor.js.map +1 -1
  18. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  19. package/dist/src/transaction/coordinator.js +26 -9
  20. package/dist/src/transaction/coordinator.js.map +1 -1
  21. package/package.json +1 -1
  22. package/src/blocks/block-store.ts +31 -31
  23. package/src/blocks/block-types.ts +11 -11
  24. package/src/blocks/index.ts +5 -5
  25. package/src/blocks/structs.ts +17 -17
  26. package/src/btree/btree.ts +872 -872
  27. package/src/btree/independent-trunk.ts +53 -53
  28. package/src/btree/index.ts +5 -5
  29. package/src/btree/key-range.ts +15 -15
  30. package/src/btree/keyset.ts +6 -6
  31. package/src/btree/nodes.ts +25 -25
  32. package/src/btree/path.ts +37 -37
  33. package/src/btree/tree-block.ts +11 -11
  34. package/src/btree/trunk.ts +14 -14
  35. package/src/chain/chain-nodes.ts +26 -26
  36. package/src/chain/chain.ts +349 -349
  37. package/src/chain/index.ts +3 -3
  38. package/src/cluster/i-cluster.ts +6 -6
  39. package/src/cluster/index.ts +3 -3
  40. package/src/cohort-topic/addressing.ts +120 -120
  41. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  42. package/src/cohort-topic/antidos/index.ts +5 -5
  43. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  44. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  45. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  46. package/src/cohort-topic/antiflood/index.ts +2 -2
  47. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  48. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  49. package/src/cohort-topic/coldstart.ts +237 -237
  50. package/src/cohort-topic/dmax.ts +88 -88
  51. package/src/cohort-topic/gossip/bus.ts +254 -254
  52. package/src/cohort-topic/gossip/index.ts +3 -3
  53. package/src/cohort-topic/gossip/records.ts +45 -45
  54. package/src/cohort-topic/gossip/view.ts +91 -91
  55. package/src/cohort-topic/index.ts +20 -20
  56. package/src/cohort-topic/load/barometer.ts +134 -134
  57. package/src/cohort-topic/load/index.ts +1 -1
  58. package/src/cohort-topic/member-engine.ts +430 -430
  59. package/src/cohort-topic/membership/index.ts +3 -3
  60. package/src/cohort-topic/membership/publisher.ts +163 -163
  61. package/src/cohort-topic/membership/source.ts +41 -41
  62. package/src/cohort-topic/ports.ts +157 -157
  63. package/src/cohort-topic/promotion.ts +477 -477
  64. package/src/cohort-topic/registration/bytes.ts +37 -37
  65. package/src/cohort-topic/registration/handoff.ts +154 -154
  66. package/src/cohort-topic/registration/index.ts +6 -6
  67. package/src/cohort-topic/registration/renewal.ts +495 -495
  68. package/src/cohort-topic/registration/sharding.ts +61 -61
  69. package/src/cohort-topic/registration/store.ts +81 -81
  70. package/src/cohort-topic/registration/types.ts +91 -91
  71. package/src/cohort-topic/ring-hash.ts +50 -50
  72. package/src/cohort-topic/service.ts +416 -416
  73. package/src/cohort-topic/sig/index.ts +2 -2
  74. package/src/cohort-topic/sig/payloads.ts +59 -59
  75. package/src/cohort-topic/sig/threshold.ts +64 -64
  76. package/src/cohort-topic/tiers.ts +74 -74
  77. package/src/cohort-topic/traffic.ts +233 -233
  78. package/src/cohort-topic/walk.ts +326 -326
  79. package/src/cohort-topic/willingness.ts +237 -237
  80. package/src/cohort-topic/wire/index.ts +18 -18
  81. package/src/cohort-topic/wire/payloads.ts +126 -126
  82. package/src/collection/action.ts +48 -48
  83. package/src/collection/collection-type-registry.ts +37 -37
  84. package/src/collection/collection.ts +2203 -2118
  85. package/src/collection/index.ts +4 -4
  86. package/src/collections/diary/index.ts +2 -2
  87. package/src/collections/diary/struct.ts +3 -3
  88. package/src/collections/index.ts +2 -2
  89. package/src/collections/tree/collection-trunk.ts +25 -25
  90. package/src/collections/tree/index.ts +2 -2
  91. package/src/collections/tree/readme.md +55 -55
  92. package/src/collections/tree/struct.ts +9 -4
  93. package/src/log/index.ts +2 -2
  94. package/src/log/log.ts +304 -268
  95. package/src/log/struct.ts +165 -165
  96. package/src/matchmaking/capability-filter.ts +45 -45
  97. package/src/matchmaking/config.ts +98 -98
  98. package/src/matchmaking/index.ts +21 -21
  99. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  100. package/src/matchmaking/provider.ts +123 -123
  101. package/src/matchmaking/query-eval.ts +105 -105
  102. package/src/matchmaking/seeker-walk.ts +127 -127
  103. package/src/matchmaking/seeker.ts +86 -86
  104. package/src/matchmaking/topic-anchor.ts +90 -90
  105. package/src/matchmaking/voting-quorum.ts +394 -394
  106. package/src/network/i-peer-network.ts +25 -25
  107. package/src/network/repo-protocol.ts +13 -13
  108. package/src/network/types.ts +37 -37
  109. package/src/reactivity/backfill.ts +220 -220
  110. package/src/reactivity/backpressure.ts +191 -191
  111. package/src/reactivity/checkpoint.ts +308 -308
  112. package/src/reactivity/config.ts +172 -172
  113. package/src/reactivity/dedupe.ts +132 -132
  114. package/src/reactivity/forwarder.ts +87 -87
  115. package/src/reactivity/index.ts +34 -34
  116. package/src/reactivity/notification.ts +123 -123
  117. package/src/reactivity/policy.ts +79 -79
  118. package/src/reactivity/push-state.ts +310 -310
  119. package/src/reactivity/recover.ts +153 -153
  120. package/src/reactivity/replay-buffer.ts +141 -141
  121. package/src/reactivity/resume.ts +549 -549
  122. package/src/reactivity/rotation.ts +415 -415
  123. package/src/reactivity/subscriber.ts +132 -132
  124. package/src/reactivity/subscription.ts +66 -66
  125. package/src/reactivity/topic-anchor.ts +71 -71
  126. package/src/reactivity/verify.ts +73 -73
  127. package/src/reactivity/wire-validate.ts +13 -13
  128. package/src/testing/async-wait.ts +65 -65
  129. package/src/testing/index.ts +2 -2
  130. package/src/testing/test-transactor.ts +62 -0
  131. package/src/transaction/actions-engine.ts +68 -68
  132. package/src/transaction/coordinator.ts +28 -11
  133. package/src/transaction/index.ts +52 -52
  134. package/src/transaction/operations-hash.ts +196 -196
  135. package/src/transaction/read-dependency-collector.ts +78 -78
  136. package/src/transaction/session.ts +238 -238
  137. package/src/transaction/transaction.ts +442 -442
  138. package/src/transaction/validator.ts +197 -197
  139. package/src/transactor/block-floors.ts +126 -126
  140. package/src/transactor/index.ts +6 -6
  141. package/src/transactor/network-transactor.ts +1545 -1545
  142. package/src/transform/atomic-proxy.ts +92 -92
  143. package/src/transform/cache-source.ts +370 -370
  144. package/src/transform/helpers.ts +164 -164
  145. package/src/transform/index.ts +7 -7
  146. package/src/transform/struct.ts +21 -21
  147. package/src/utility/actor.ts +62 -62
  148. package/src/utility/backoff.ts +95 -95
  149. package/src/utility/batch-coordinator.ts +191 -191
  150. package/src/utility/ensured.ts +32 -32
  151. package/src/utility/groupby.ts +18 -18
  152. package/src/utility/hash-string.ts +14 -14
  153. package/src/utility/is-record-empty.ts +5 -5
  154. package/src/utility/latches.ts +42 -42
  155. package/src/utility/lru-map.ts +60 -60
  156. package/src/utility/nameof.ts +7 -7
  157. 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
+ }