@optimystic/db-core 1.22.0 → 1.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/README.md +8 -4
  2. package/dist/src/collection/action.d.ts +7 -4
  3. package/dist/src/collection/action.d.ts.map +1 -1
  4. package/dist/src/collection/action.js +13 -5
  5. package/dist/src/collection/action.js.map +1 -1
  6. package/dist/src/collection/collection.d.ts +134 -46
  7. package/dist/src/collection/collection.d.ts.map +1 -1
  8. package/dist/src/collection/collection.js +207 -70
  9. package/dist/src/collection/collection.js.map +1 -1
  10. package/dist/src/collection/struct.d.ts +38 -8
  11. package/dist/src/collection/struct.d.ts.map +1 -1
  12. package/dist/src/collection/struct.js.map +1 -1
  13. package/dist/src/collection/write-attempts.d.ts +138 -34
  14. package/dist/src/collection/write-attempts.d.ts.map +1 -1
  15. package/dist/src/collection/write-attempts.js +168 -101
  16. package/dist/src/collection/write-attempts.js.map +1 -1
  17. package/dist/src/collections/diary/diary.d.ts.map +1 -1
  18. package/dist/src/collections/diary/diary.js +5 -1
  19. package/dist/src/collections/diary/diary.js.map +1 -1
  20. package/dist/src/collections/tree/tree.d.ts +15 -9
  21. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  22. package/dist/src/collections/tree/tree.js +6 -4
  23. package/dist/src/collections/tree/tree.js.map +1 -1
  24. package/dist/src/hlc/clock-store.d.ts +63 -0
  25. package/dist/src/hlc/clock-store.d.ts.map +1 -0
  26. package/dist/src/hlc/clock-store.js +49 -0
  27. package/dist/src/hlc/clock-store.js.map +1 -0
  28. package/dist/src/hlc/clock.d.ts +64 -0
  29. package/dist/src/hlc/clock.d.ts.map +1 -0
  30. package/dist/src/hlc/clock.js +171 -0
  31. package/dist/src/hlc/clock.js.map +1 -0
  32. package/dist/src/hlc/hlc.d.ts +38 -0
  33. package/dist/src/hlc/hlc.d.ts.map +1 -0
  34. package/dist/src/hlc/hlc.js +41 -0
  35. package/dist/src/hlc/hlc.js.map +1 -0
  36. package/dist/src/hlc/index.d.ts +5 -0
  37. package/dist/src/hlc/index.d.ts.map +1 -0
  38. package/dist/src/hlc/index.js +5 -0
  39. package/dist/src/hlc/index.js.map +1 -0
  40. package/dist/src/hlc/skew.d.ts +35 -0
  41. package/dist/src/hlc/skew.d.ts.map +1 -0
  42. package/dist/src/hlc/skew.js +35 -0
  43. package/dist/src/hlc/skew.js.map +1 -0
  44. package/dist/src/index.d.ts +2 -0
  45. package/dist/src/index.d.ts.map +1 -1
  46. package/dist/src/index.js +2 -0
  47. package/dist/src/index.js.map +1 -1
  48. package/dist/src/lane/index.d.ts +2 -0
  49. package/dist/src/lane/index.d.ts.map +1 -0
  50. package/dist/src/lane/index.js +2 -0
  51. package/dist/src/lane/index.js.map +1 -0
  52. package/dist/src/lane/lane.d.ts +46 -0
  53. package/dist/src/lane/lane.d.ts.map +1 -0
  54. package/dist/src/lane/lane.js +26 -0
  55. package/dist/src/lane/lane.js.map +1 -0
  56. package/dist/src/log/log.d.ts +50 -22
  57. package/dist/src/log/log.d.ts.map +1 -1
  58. package/dist/src/log/log.js +21 -13
  59. package/dist/src/log/log.js.map +1 -1
  60. package/dist/src/log/struct.d.ts +61 -1
  61. package/dist/src/log/struct.d.ts.map +1 -1
  62. package/dist/src/log/struct.js +24 -0
  63. package/dist/src/log/struct.js.map +1 -1
  64. package/dist/src/network/i-repo.d.ts +10 -0
  65. package/dist/src/network/i-repo.d.ts.map +1 -1
  66. package/dist/src/network/stale-failure.d.ts +20 -7
  67. package/dist/src/network/stale-failure.d.ts.map +1 -1
  68. package/dist/src/network/stale-failure.js +29 -7
  69. package/dist/src/network/stale-failure.js.map +1 -1
  70. package/dist/src/network/struct.d.ts +35 -0
  71. package/dist/src/network/struct.d.ts.map +1 -1
  72. package/dist/src/network/struct.js.map +1 -1
  73. package/dist/src/offline/entry.d.ts +14 -0
  74. package/dist/src/offline/entry.d.ts.map +1 -1
  75. package/dist/src/offline/entry.js +2 -0
  76. package/dist/src/offline/entry.js.map +1 -1
  77. package/dist/src/offline/journal.d.ts +10 -0
  78. package/dist/src/offline/journal.d.ts.map +1 -1
  79. package/dist/src/offline/queue.d.ts +10 -0
  80. package/dist/src/offline/queue.d.ts.map +1 -1
  81. package/dist/src/offline/queue.js +29 -3
  82. package/dist/src/offline/queue.js.map +1 -1
  83. package/dist/src/offline/status.d.ts +7 -0
  84. package/dist/src/offline/status.d.ts.map +1 -1
  85. package/dist/src/offline/status.js.map +1 -1
  86. package/dist/src/testing/test-transactor.d.ts +9 -1
  87. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  88. package/dist/src/testing/test-transactor.js +6 -1
  89. package/dist/src/testing/test-transactor.js.map +1 -1
  90. package/dist/src/transaction/actions-engine.d.ts +3 -0
  91. package/dist/src/transaction/actions-engine.d.ts.map +1 -1
  92. package/dist/src/transaction/actions-engine.js +3 -0
  93. package/dist/src/transaction/actions-engine.js.map +1 -1
  94. package/dist/src/transaction/coordinator.d.ts +10 -5
  95. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  96. package/dist/src/transaction/coordinator.js +197 -48
  97. package/dist/src/transaction/coordinator.js.map +1 -1
  98. package/dist/src/transaction/entry-commit.d.ts +45 -10
  99. package/dist/src/transaction/entry-commit.d.ts.map +1 -1
  100. package/dist/src/transaction/entry-commit.js +20 -7
  101. package/dist/src/transaction/entry-commit.js.map +1 -1
  102. package/dist/src/transaction/errors.d.ts +69 -1
  103. package/dist/src/transaction/errors.d.ts.map +1 -1
  104. package/dist/src/transaction/errors.js +70 -1
  105. package/dist/src/transaction/errors.js.map +1 -1
  106. package/dist/src/transaction/index.d.ts +1 -1
  107. package/dist/src/transaction/index.d.ts.map +1 -1
  108. package/dist/src/transaction/index.js +1 -1
  109. package/dist/src/transaction/index.js.map +1 -1
  110. package/dist/src/transaction/session.d.ts.map +1 -1
  111. package/dist/src/transaction/session.js +18 -5
  112. package/dist/src/transaction/session.js.map +1 -1
  113. package/dist/src/transaction/transaction.d.ts +74 -15
  114. package/dist/src/transaction/transaction.d.ts.map +1 -1
  115. package/dist/src/transaction/transaction.js +35 -15
  116. package/dist/src/transaction/transaction.js.map +1 -1
  117. package/dist/src/transaction/validator.d.ts +25 -4
  118. package/dist/src/transaction/validator.d.ts.map +1 -1
  119. package/dist/src/transaction/validator.js +45 -5
  120. package/dist/src/transaction/validator.js.map +1 -1
  121. package/dist/src/transactor/block-floors.d.ts +12 -1
  122. package/dist/src/transactor/block-floors.d.ts.map +1 -1
  123. package/dist/src/transactor/block-floors.js +14 -1
  124. package/dist/src/transactor/block-floors.js.map +1 -1
  125. package/dist/src/transactor/network-transactor.d.ts +8 -0
  126. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  127. package/dist/src/transactor/network-transactor.js +8 -4
  128. package/dist/src/transactor/network-transactor.js.map +1 -1
  129. package/dist/src/transactor/transactor-source.d.ts +11 -0
  130. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  131. package/dist/src/transactor/transactor-source.js +5 -1
  132. package/dist/src/transactor/transactor-source.js.map +1 -1
  133. package/dist/src/transactor/transactor.d.ts +8 -0
  134. package/dist/src/transactor/transactor.d.ts.map +1 -1
  135. package/dist/src/transform/cache-source.d.ts +7 -0
  136. package/dist/src/transform/cache-source.d.ts.map +1 -1
  137. package/dist/src/transform/cache-source.js +14 -18
  138. package/dist/src/transform/cache-source.js.map +1 -1
  139. package/package.json +1 -1
  140. package/src/collection/action.ts +13 -5
  141. package/src/collection/collection.ts +250 -76
  142. package/src/collection/struct.ts +38 -8
  143. package/src/collection/write-attempts.ts +213 -109
  144. package/src/collections/diary/diary.ts +5 -1
  145. package/src/collections/tree/tree.ts +18 -11
  146. package/src/hlc/clock-store.ts +68 -0
  147. package/src/hlc/clock.ts +196 -0
  148. package/src/hlc/hlc.ts +56 -0
  149. package/src/hlc/index.ts +4 -0
  150. package/src/hlc/skew.ts +55 -0
  151. package/src/index.ts +2 -0
  152. package/src/lane/index.ts +1 -0
  153. package/src/lane/lane.ts +54 -0
  154. package/src/log/log.ts +341 -310
  155. package/src/log/struct.ts +62 -1
  156. package/src/network/i-repo.ts +11 -1
  157. package/src/network/stale-failure.ts +31 -7
  158. package/src/network/struct.ts +805 -770
  159. package/src/offline/entry.ts +16 -0
  160. package/src/offline/journal.ts +10 -0
  161. package/src/offline/queue.ts +38 -4
  162. package/src/offline/status.ts +7 -0
  163. package/src/testing/test-transactor.ts +1065 -1053
  164. package/src/transaction/actions-engine.ts +3 -0
  165. package/src/transaction/coordinator.ts +229 -54
  166. package/src/transaction/entry-commit.ts +56 -14
  167. package/src/transaction/errors.ts +60 -0
  168. package/src/transaction/index.ts +1 -1
  169. package/src/transaction/session.ts +18 -5
  170. package/src/transaction/transaction.ts +90 -17
  171. package/src/transaction/validator.ts +46 -5
  172. package/src/transactor/block-floors.ts +15 -1
  173. package/src/transactor/network-transactor.ts +15 -4
  174. package/src/transactor/transactor-source.ts +15 -1
  175. package/src/transactor/transactor.ts +9 -0
  176. package/src/transform/cache-source.ts +15 -17
package/src/log/struct.ts CHANGED
@@ -1,9 +1,24 @@
1
1
  import type { BlockId, CollectionId, ActionContext, ActionId, ActionRev, ReadDependency } from "../index.js";
2
+ import { legacyHlc, type Hlc } from "../hlc/hlc.js";
3
+ import type { Lane } from "../lane/lane.js";
2
4
 
3
5
  /** A log entry - an action, a checkpoint, or an invalidation */
4
6
  export type LogEntry<TAction> = {
5
- /** Linux timestamp of the entry */
7
+ /** The wall-clock time the writer's clock read when it wrote the entry. Informational: nothing
8
+ * orders by it. Kept beside {@link hlc}, which is a second fact, not this one twice — its `wallMs`
9
+ * is at or above this and may be a future time after the writer's clock observed a jump. */
6
10
  readonly timestamp: number;
11
+ /**
12
+ * The hybrid logical clock value the writer minted for the write this entry records
13
+ * (docs/crdt-sync.md §Migration Path, Stage 1). Minted once per write and re-sent verbatim by
14
+ * every retry, like {@link timestamp}; one value for every entry of a multi-collection write.
15
+ * Nothing orders by it yet — the revision is the order within a collection — but it is what a
16
+ * later merge of divergent histories orders by, and the entry is the unit such a merge orders.
17
+ *
18
+ * Every entry this build writes carries it. A STORED entry written before the field existed lacks
19
+ * it; read an entry's HLC through {@link hlcOf}, never off the field.
20
+ */
21
+ readonly hlc: Hlc;
7
22
  /** Revision number - monotonically increasing from the prior entry's rev. Starts at 1. */
8
23
  readonly rev: number;
9
24
  readonly action?: ActionEntry<TAction>;
@@ -22,6 +37,20 @@ export type ActionEntry<TAction> = {
22
37
  blockIds: BlockId[]; // NOTE: this is updated after being generated to include the log-related block transforms
23
38
  /** Other collection ids affected by the action - this action is conditional on successful commit in all of these collections */
24
39
  readonly collectionIds?: CollectionId[];
40
+ /**
41
+ * The write's lane (`Lane` in `packages/db-core/src/lane/lane.ts`): whether its conflicts with
42
+ * other machines' concurrent writes are decided by the quorum and the revision order
43
+ * (`serializable`) or may be merged later under the collection's declaration (`convergent`).
44
+ * Minted once per write beside the action id, timestamp and HLC (`WriteIdentity.lane`,
45
+ * `Transaction.lane`), and re-sent verbatim by every retry; one lane for every entry of a
46
+ * multi-collection write. On the action entry rather than the log entry because a checkpoint has
47
+ * no lane and an invalidation reverses an action under the strong rules. Nothing admits by it yet.
48
+ *
49
+ * Every entry this build writes carries it. A STORED entry written before the field existed lacks
50
+ * it (every write then was serializable); read an entry's lane through {@link laneOf}, never off
51
+ * the field.
52
+ */
53
+ readonly lane: Lane;
25
54
  /**
26
55
  * The `(blockId, revision)` reads this transaction observed during execution — the same
27
56
  * read set the {@link Transaction} carried in its PEND request (see `Transaction.reads`).
@@ -156,10 +185,42 @@ export type CheckpointEntry = {
156
185
  readonly pendings: ActionRev[];
157
186
  };
158
187
 
188
+ /**
189
+ * The one reader rule for an entry's HLC: the field when the entry carries one, else the legacy
190
+ * value derived from its timestamp (`legacyHlc`: the wall time, no logical count, the empty node
191
+ * id). The parameter admits an absent field because a stored entry written before the field existed
192
+ * has none, whatever {@link LogEntry} declares about the entries this build writes.
193
+ */
194
+ export function hlcOf(entry: { readonly timestamp: number; readonly hlc?: Hlc }): Hlc {
195
+ return entry.hlc ?? legacyHlc(entry.timestamp);
196
+ }
197
+
198
+ /**
199
+ * The one reader rule for an action entry's lane: the field when the entry carries one, else
200
+ * `serializable`, since every write made before the field existed took the quorum lane. The
201
+ * parameter admits an absent field because a stored entry written before the field existed has
202
+ * none, whatever {@link ActionEntry} declares about the entries this build writes.
203
+ *
204
+ * NOTE: `ActionEntry.lane` is declared required while a stored legacy entry lacks it, so a reader
205
+ * that takes the field directly compiles and meets `undefined` on such an entry — the same tripwire
206
+ * `hlcOf` records for `LogEntry.hlc`. Read through here. Splitting the stored and written shapes
207
+ * into two types was declined for one reader; if a second direct reader ever appears, split then.
208
+ */
209
+ export function laneOf(entry: { readonly lane?: Lane }): Lane {
210
+ return entry.lane ?? 'serializable';
211
+ }
212
+
159
213
  export const LogDataBlockType = "LGD";
160
214
  export const LogHeaderBlockType = "LGH";
161
215
 
162
216
  export type GetFromResult<TAction> = {
163
217
  context: ActionContext | undefined;
164
218
  entries: ActionEntry<TAction>[];
219
+ /**
220
+ * The highest HLC ({@link hlcOf}) among every entry the walk read — action, checkpoint and
221
+ * invalidation entries alike, the ones below `startRev` it read to find its way included — so the
222
+ * reader's clock can observe it (docs/crdt-sync.md §Migration Path, Stage 1). One value rather than
223
+ * one per entry, since the clock keeps only a maximum. Absent when the walk read no entry.
224
+ */
225
+ hlcHighWater?: Hlc;
165
226
  };
@@ -1,4 +1,5 @@
1
- import type { ActionBlocks, BlockContentDigests, CommitResult, GetBlockResults, PendResult, PendRequest, BlockGets, BlockId, ActionId } from "../index.js";
1
+ import type { ActionBlocks, BlockContentDigests, CommitResult, GetBlockResults, PendResult, PendRequest, BlockGets, BlockId, ActionId, CommitRequest } from "../index.js";
2
+ import type { Lane } from "../lane/lane.js";
2
3
 
3
4
  export type MessageOptions = {
4
5
  expiration?: number;
@@ -29,12 +30,21 @@ export type MessageOptions = {
29
30
  * call, where there is no asker to stand in for.
30
31
  */
31
32
  asker?: string;
33
+ /**
34
+ * Answer a read from this node's own storage alone: no cohort consult, and no consult-derived
35
+ * flag. Set by every block-repair answer (an archive, a consult answer, a lineage answer), so a
36
+ * peer reports what it holds itself, never what its cohort says. Never sent.
37
+ */
38
+ skipClusterFetch?: boolean;
32
39
  }
33
40
 
34
41
  export type RepoCommitRequest = {
35
42
  blockIds: BlockId[];
36
43
  actionId: ActionId;
37
44
  rev: number;
45
+ /** The write's lane ({@link CommitRequest.lane}), carried onto every per-block commit the
46
+ * transactor sends; absent on bare per-block paths and for an older writer. */
47
+ lane?: Lane;
38
48
  /**
39
49
  * The collection's chain tail block id (the {@link CommitRequest.tailId}). Optional on the per-block
40
50
  * repo operation: the transactor threads the committing collection's tail through every per-block
@@ -1,3 +1,4 @@
1
+ import type { BlockId } from "../index.js";
1
2
  import type { ActionId, ActionRev } from "../collection/action.js";
2
3
  import type { ExpiredFailure, RejectedFailure, ShortfallFailure, StaleFailure, WriteFailure } from "./struct.js";
3
4
 
@@ -67,13 +68,12 @@ export function isRejectedFailure(failure: WriteFailure): failure is RejectedFai
67
68
  * NOTE: comparing revisions across blocks is meaningful only within one collection, where every
68
69
  * candidate comes from the same revision counter. A batch (`IRepo.pendMany` / `commitMany`) spans
69
70
  * collections, and `CoordinatorRepo` still picks the highest across them, so its `staleAt` names the
70
- * block — and so the collection — of one loser among several counters. That is harmless while the
71
- * multi-collection coordinator, the only writer that sends a batch, does not read the number (backlog
72
- * `debt-multi-collection-retry-cannot-see-the-taken-revision`). A consumer that compares it against a
73
- * revision counter, as `Collection.syncAttempts` does against its OWN next revision to decide whether a
74
- * retry could differ (`SyncRevisionStalledError`), must compare it against the counter of the
75
- * collection owning `staleAt.blockId` — and once one does for a batch, selection must become
76
- * per-collection.
71
+ * block — and so the collection — of one loser among several counters. The multi-collection
72
+ * coordinator, the only writer that sends a batch, therefore attributes a batched answer's number by
73
+ * its block id ({@link staleAtOwner}): the collection owning `staleAt.blockId` gets the number, and
74
+ * every other collection of the batch is treated as refused with no confirmed number. The other
75
+ * collections' losses are understated by that, never overstated — a number is only ever compared
76
+ * against the counter it came from.
77
77
  */
78
78
  export function highestStaleAt(candidates: readonly StaleFailure['staleAt'][]): StaleFailure['staleAt'] {
79
79
  let best: StaleFailure['staleAt'];
@@ -85,6 +85,30 @@ export function highestStaleAt(candidates: readonly StaleFailure['staleAt'][]):
85
85
  return best;
86
86
  }
87
87
 
88
+ /**
89
+ * The single rule for attributing a {@link StaleFailure.staleAt} that answered a request spanning
90
+ * several collections: the one collection whose blocks include `staleAt.blockId`, or `undefined`
91
+ * when no candidate owns it (a block none of them sent, or no number at all).
92
+ *
93
+ * A revision is a per-collection counter, so the number is meaningful only against the counter of
94
+ * the collection that owns the block it names. A request for ONE collection needs no attribution —
95
+ * its number is that collection's whatever block it names — so this is for the batched answer
96
+ * (`IRepo.pendMany` / `commitMany`), where `CoordinatorRepo` reports one number, the highest across
97
+ * the batch's collections ({@link highestStaleAt}), and only the owner of the named block may count
98
+ * it as its own.
99
+ */
100
+ export function staleAtOwner<Owner>(staleAt: StaleFailure['staleAt'], blocksByOwner: ReadonlyMap<Owner, readonly BlockId[]>): Owner | undefined {
101
+ if (staleAt === undefined) {
102
+ return undefined;
103
+ }
104
+ for (const [owner, blockIds] of blocksByOwner) {
105
+ if (blockIds.includes(staleAt.blockId)) {
106
+ return owner;
107
+ }
108
+ }
109
+ return undefined;
110
+ }
111
+
88
112
  /**
89
113
  * The single rule for "is the action holding this revision OUR OWN?" — true only when `latest`
90
114
  * names exactly the revision being requested AND the same action requesting it.