@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,4 +1,4 @@
1
- export * from "./collection.js";
2
- export * from "./struct.js";
3
- export * from "./action.js";
4
- export * from "./collection-type-registry.js";
1
+ export * from "./collection.js";
2
+ export * from "./struct.js";
3
+ export * from "./action.js";
4
+ export * from "./collection-type-registry.js";
@@ -1,2 +1,2 @@
1
- export * from "./diary.js";
2
- export * from "./struct.js";
1
+ export * from "./diary.js";
2
+ export * from "./struct.js";
@@ -1,3 +1,3 @@
1
- import { registerBlockType } from "../../blocks/block-types.js";
2
-
3
- export const DiaryHeaderBlockType = registerBlockType("DIH", "DiaryHeaderBlock");
1
+ import { registerBlockType } from "../../blocks/block-types.js";
2
+
3
+ export const DiaryHeaderBlockType = registerBlockType("DIH", "DiaryHeaderBlock");
@@ -1,2 +1,2 @@
1
- export * from "./diary/index.js";
2
- export * from "./tree/index.js";
1
+ export * from "./diary/index.js";
2
+ export * from "./tree/index.js";
@@ -1,25 +1,25 @@
1
- import { apply, get } from "../../blocks/helpers.js";
2
- import type { BlockId, BlockStore, IBlock, ITreeTrunk } from "../../index.js";
3
- import type { ITreeNode } from "../../btree/nodes.js";
4
- import { rootId$, type TreeCollectionHeaderBlock } from "./struct.js";
5
-
6
- export class CollectionTrunk implements ITreeTrunk {
7
- constructor(
8
- private readonly store: BlockStore<IBlock>,
9
- private readonly collectionId: BlockId,
10
- ) {}
11
-
12
- async get(): Promise<ITreeNode> {
13
- return await get(this.store, await this.getId());
14
- }
15
-
16
- async set(node: ITreeNode): Promise<void> {
17
- const header = await get(this.store, this.collectionId) as TreeCollectionHeaderBlock;
18
- apply(this.store, header, [rootId$, 0, 1, node.header.id]);
19
- }
20
-
21
- async getId(): Promise<BlockId> {
22
- const header = await get(this.store, this.collectionId) as TreeCollectionHeaderBlock;
23
- return header.rootId;
24
- }
25
- }
1
+ import { apply, get } from "../../blocks/helpers.js";
2
+ import type { BlockId, BlockStore, IBlock, ITreeTrunk } from "../../index.js";
3
+ import type { ITreeNode } from "../../btree/nodes.js";
4
+ import { rootId$, type TreeCollectionHeaderBlock } from "./struct.js";
5
+
6
+ export class CollectionTrunk implements ITreeTrunk {
7
+ constructor(
8
+ private readonly store: BlockStore<IBlock>,
9
+ private readonly collectionId: BlockId,
10
+ ) {}
11
+
12
+ async get(): Promise<ITreeNode> {
13
+ return await get(this.store, await this.getId());
14
+ }
15
+
16
+ async set(node: ITreeNode): Promise<void> {
17
+ const header = await get(this.store, this.collectionId) as TreeCollectionHeaderBlock;
18
+ apply(this.store, header, [rootId$, 0, 1, node.header.id]);
19
+ }
20
+
21
+ async getId(): Promise<BlockId> {
22
+ const header = await get(this.store, this.collectionId) as TreeCollectionHeaderBlock;
23
+ return header.rootId;
24
+ }
25
+ }
@@ -1,2 +1,2 @@
1
- export * from "./tree.js";
2
- export * from "./struct.js";
1
+ export * from "./tree.js";
2
+ export * from "./struct.js";
@@ -1,55 +1,55 @@
1
- # Tree Collection
2
-
3
- The Tree Collection combines the logical transaction logging of a collection, with a BTree data structure.
4
-
5
- ## CollectionTrunk
6
-
7
- To avoid having both a collection header and a btree header, we enable the collection header to double as the btree header. This is accomplished using the "...Trunk" abstraction provided by the BTree. The trunk interface abstracts accessing or updating the root of the tree, from the btree proper. For this implementation, we introduce a CollectionTrunk class that implements the trunk interface. The CollectionTrunk reads the root id from the collection header, and updates the collection header with the new root id when the root changes.
8
-
9
- ## Replace Action
10
-
11
- The replace action is a unit of change to the tree collection. It is a list of key-value pairs, where the key is the key to replace, and the value is the new value to replace the old value with. If the value is not provided, the key is deleted.
12
-
13
- ```ts
14
- tree.replace([
15
- { key: 5, value: { a: 1, b: 'Value' } },
16
- { key: 10 },
17
- ]);
18
- ```
19
- Replaces the value at key 5 with { a: 1, b: 'Value' }, and deletes the value at key 10.
20
-
21
- ## Committed read views (`readView`)
22
-
23
- `tree.readView(snapshot)` builds a read-only view of the tree as captured by an earlier
24
- `tree.snapshot()` — typically the pre-transaction state recorded before any DML was staged.
25
- It is how a `committed.<Table>` reference (e.g. inside a deferred CHECK) reads committed
26
- rows while the live tree still holds the transaction's in-flight changes.
27
-
28
- The view guarantees **one consistent answer from first read to last**:
29
-
30
- - It never sees mutations staged into the live tree after the snapshot was taken.
31
- - It is pinned to the **snapshot's** committed boundary — the revision the collection held
32
- when `snapshot()` was called (`CollectionSnapshot.context`), not the revision at
33
- view-creation time. So a view built AFTER the same tree flushed a further commit still
34
- describes the snapshot's boundary (the multi-tree commit-sweep case: tree N already
35
- flushed, tree N+1 not — views of both describe the one pre-sweep boundary). Commits
36
- that fold into the live tree's cache — or clear it (a live read's `update()` after
37
- another writer commits) — while the view is being walked do not change what the view
38
- returns. This holds even for blocks the view has to fetch from storage mid-scan (the
39
- view carries its own frozen action context, which the transactor honours on `get`, and
40
- cache entries newer than the pin are excluded from the view's warm seed). A hand-built
41
- snapshot with no recorded boundary falls back to the collection's context at
42
- view-creation time.
43
- - A block the storage layer cannot reconstruct at the pinned revision surfaces as
44
- `BlockUnavailableError`, never as a silently absent block.
45
- - A block served at a revision the repo could not confirm is the newest one *inside the
46
- pinned view* (a cohort peer claims a revision at or below the pin that nothing could
47
- corroborate) surfaces as `BlockPossiblyStaleError`, never as a snapshot silently missing
48
- a committed update. A claim ABOVE the pin is irrelevant to the view and is not raised.
49
-
50
- By default a view records **no read dependencies** — it is not part of any transaction's
51
- conflict set, so an unrelated committed read can never fail a writer's commit validation.
52
- Pass `{ recordReads: true }` to opt back in.
53
-
54
- Each view privately holds up to the block-cache LRU budget (128 blocks, cloned at creation)
55
- plus whatever it faults in; views are intended to be per-scan and dropped when the scan ends.
1
+ # Tree Collection
2
+
3
+ The Tree Collection combines the logical transaction logging of a collection, with a BTree data structure.
4
+
5
+ ## CollectionTrunk
6
+
7
+ To avoid having both a collection header and a btree header, we enable the collection header to double as the btree header. This is accomplished using the "...Trunk" abstraction provided by the BTree. The trunk interface abstracts accessing or updating the root of the tree, from the btree proper. For this implementation, we introduce a CollectionTrunk class that implements the trunk interface. The CollectionTrunk reads the root id from the collection header, and updates the collection header with the new root id when the root changes.
8
+
9
+ ## Replace Action
10
+
11
+ The replace action is a unit of change to the tree collection. It is a list of key-value pairs, where the key is the key to replace, and the value is the new value to replace the old value with. If the value is not provided, the key is deleted.
12
+
13
+ ```ts
14
+ tree.replace([
15
+ { key: 5, value: { a: 1, b: 'Value' } },
16
+ { key: 10 },
17
+ ]);
18
+ ```
19
+ Replaces the value at key 5 with { a: 1, b: 'Value' }, and deletes the value at key 10.
20
+
21
+ ## Committed read views (`readView`)
22
+
23
+ `tree.readView(snapshot)` builds a read-only view of the tree as captured by an earlier
24
+ `tree.snapshot()` — typically the pre-transaction state recorded before any DML was staged.
25
+ It is how a `committed.<Table>` reference (e.g. inside a deferred CHECK) reads committed
26
+ rows while the live tree still holds the transaction's in-flight changes.
27
+
28
+ The view guarantees **one consistent answer from first read to last**:
29
+
30
+ - It never sees mutations staged into the live tree after the snapshot was taken.
31
+ - It is pinned to the **snapshot's** committed boundary — the revision the collection held
32
+ when `snapshot()` was called (`CollectionSnapshot.context`), not the revision at
33
+ view-creation time. So a view built AFTER the same tree flushed a further commit still
34
+ describes the snapshot's boundary (the multi-tree commit-sweep case: tree N already
35
+ flushed, tree N+1 not — views of both describe the one pre-sweep boundary). Commits
36
+ that fold into the live tree's cache — or clear it (a live read's `update()` after
37
+ another writer commits) — while the view is being walked do not change what the view
38
+ returns. This holds even for blocks the view has to fetch from storage mid-scan (the
39
+ view carries its own frozen action context, which the transactor honours on `get`, and
40
+ cache entries newer than the pin are excluded from the view's warm seed). A hand-built
41
+ snapshot with no recorded boundary falls back to the collection's context at
42
+ view-creation time.
43
+ - A block the storage layer cannot reconstruct at the pinned revision surfaces as
44
+ `BlockUnavailableError`, never as a silently absent block.
45
+ - A block served at a revision the repo could not confirm is the newest one *inside the
46
+ pinned view* (a cohort peer claims a revision at or below the pin that nothing could
47
+ corroborate) surfaces as `BlockPossiblyStaleError`, never as a snapshot silently missing
48
+ a committed update. A claim ABOVE the pin is irrelevant to the view and is not raised.
49
+
50
+ By default a view records **no read dependencies** — it is not part of any transaction's
51
+ conflict set, so an unrelated committed read can never fail a writer's commit validation.
52
+ Pass `{ recordReads: true }` to opt back in.
53
+
54
+ Each view privately holds up to the block-cache LRU budget (128 blocks, cloned at creation)
55
+ plus whatever it faults in; views are intended to be per-scan and dropped when the scan ends.
@@ -125,7 +125,9 @@ export type TreeReplaceAction<TKey, TEntry> = (
125
125
  *
126
126
  * Subclasses split by WHAT was refused, because consumers map them differently: a
127
127
  * {@link TreeKeyTakenError} is a uniqueness violation (the Quereus bridge renders it as
128
- * `UNIQUE constraint failed`), while a {@link TreeEntryChangedError} is a lost update. Catch
128
+ * `UNIQUE constraint failed` and raises the engine's `ConstraintError`), while a
129
+ * {@link TreeEntryChangedError} is a lost update (the bridge raises its
130
+ * `ConcurrentModificationError`, status code BUSY, which is not a constraint error). Catch
129
131
  * this base to treat any guard refusal uniformly; catch a subclass to say which happened.
130
132
  */
131
133
  export class TreeGuardRefusedError<TKey = unknown> extends Error {
@@ -166,8 +168,9 @@ export class TreeKeyTakenError<TKey = unknown> extends TreeGuardRefusedError<TKe
166
168
  * index tree, a rival's row carrying the same unique value under a different primary
167
169
  * key. A subclass of {@link TreeKeyTakenError} on purpose: every consumer that treats a
168
170
  * key refusal as a non-retryable uniqueness failure (the sync/commit retry loops let it
169
- * escape; the Quereus bridge maps it by `collectionId` to a `UNIQUE constraint failed`
170
- * message) handles this one identically without a second arm. `collectionId` is the
171
+ * escape; the Quereus bridge maps it by `collectionId` to a `ConstraintError` carrying the
172
+ * `UNIQUE constraint failed` message) handles this one identically without a second arm.
173
+ * `collectionId` is the
171
174
  * discriminator that names WHICH constraint fired — each unique index is its own
172
175
  * collection — so the bridge needs nothing beyond it.
173
176
  */
@@ -193,9 +196,11 @@ export class TreeRangeTakenError<TKey = unknown> extends TreeKeyTakenError<TKey>
193
196
  * write read — a rival committed a different entry there, or removed it (`actual` is
194
197
  * `undefined`). A lost update, NOT a uniqueness violation, which is why this deliberately does
195
198
  * NOT subclass {@link TreeKeyTakenError}: the Quereus bridge renders every `TreeKeyTakenError`
196
- * as that collection's registered `UNIQUE constraint failed` message (`mapCommitRefusal` in
199
+ * as that collection's registered `UNIQUE constraint failed` message and raises the engine's
200
+ * `ConstraintError` for it (`mapCommitRefusal` in
197
201
  * `packages/quereus-plugin-optimystic/src/optimystic-adapter/txn-bridge.ts`), and reporting a
198
202
  * concurrent-update refusal as a uniqueness failure would mislead every client that reads it.
203
+ * The bridge raises its own `ConcurrentModificationError` (status code BUSY) for this one instead.
199
204
  * The shared contract lives on {@link TreeGuardRefusedError}.
200
205
  */
201
206
  export class TreeEntryChangedError<TKey = unknown, TEntry = unknown> extends TreeGuardRefusedError<TKey> {
package/src/log/index.ts CHANGED
@@ -1,2 +1,2 @@
1
- export * from "./log.js";
2
- export * from "./struct.js";
1
+ export * from "./log.js";
2
+ export * from "./struct.js";