@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
@@ -7,10 +7,12 @@ import { judgeCohortLineage, type CohortLineage, type MemberLineage } from "../n
7
7
  import { assertTransactionFits, transactionBytes, MAX_TRANSACTION_BYTES } from "../network/transaction-size.js";
8
8
  import type { ActionTransforms, ActionBlocks, ActionLineage, BlockActionStatus, ITransactor, PendSuccess, CommitSuccess, StaleFailure, WriteFailure, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, Transforms, CommitRequest, ActionId, RepoCommitRequest, ClusterNomineesResult, CollectionId, IBlock, GetBlockResult, CoordinatorIntent, BlockUnavailableReason, BlockContentDigests, BlockBaseRevs, WriteDurability } from "../index.js";
9
9
  import type { IBlockChangeNotifier, CollectionChangeListener } from "./change-notifier.js";
10
+ import type { HlcClock } from "../hlc/clock.js";
10
11
  import { transformForBlockId, concatTransforms, concatTransform, transformsFromTransform, blockIdsForTransforms } from "../transform/helpers.js";
11
12
  import { Tracker } from "../transform/tracker.js";
12
13
  import { blockDigestsField, baseRevsField } from "../transform/digest.js";
13
14
  import { refuseSoloField } from "../network/refuse-solo.js";
15
+ import { laneField } from "../lane/lane.js";
14
16
  import { CacheSource } from "../transform/cache-source.js";
15
17
  import { TransactorSource, servedRevision } from "./transactor-source.js";
16
18
  import { Log } from "../log/log.js";
@@ -75,6 +77,12 @@ type NetworkTransactorInit = {
75
77
  * re-send without waiting on the wall clock.
76
78
  */
77
79
  owedCancelClock?: OwedCancelClock;
80
+ /**
81
+ * The clock of the node this transactor runs on, exposed as {@link ITransactor.clock}. A node
82
+ * builds one per process and hands the same instance to every transactor over it; omit and
83
+ * writes mint from the process-wide fallback (`clockOf`).
84
+ */
85
+ clock?: HlcClock;
78
86
  }
79
87
 
80
88
  /**
@@ -87,6 +95,7 @@ type NetworkTransactorInit = {
87
95
  const DEFAULT_DIAL_TIMEOUT_MS = 3000;
88
96
 
89
97
  export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
98
+ readonly clock: HlcClock | undefined;
90
99
  private readonly keyNetwork: IKeyNetwork;
91
100
  private readonly timeoutMs: number;
92
101
  private readonly abortOrCancelTimeoutMs: number;
@@ -137,6 +146,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
137
146
  : (init.dialTimeoutMs > 0 ? init.dialTimeoutMs : undefined);
138
147
  this.getRepo = init.getRepo;
139
148
  this.localChangeNotifier = init.localChangeNotifier;
149
+ this.clock = init.clock;
140
150
  this.localPeerId = init.localPeerId?.toString();
141
151
  this.retryBackoff = { baseMs: init.retryBackoffBaseMs ?? 0, localPeerId: init.localPeerId, sleep: init.retrySleep };
142
152
  this.owedCancels = new OwedCancels({
@@ -1759,8 +1769,8 @@ function refusalFrom(responses: WriteFailure[]): WriteFailure {
1759
1769
  * cohort sign for blocks the request is not committing; and `processBatches` re-batches failed blocks
1760
1770
  * onto different coordinators, so only a send-time subset stays correct across retries.
1761
1771
  */
1762
- function repoCommitRequest(blockIds: BlockId[], { actionId, rev, tailId, blockDigests, refuseSolo }: RepoCommitRequest): RepoCommitRequest {
1763
- return { actionId, blockIds, rev, tailId, ...digestsFor(blockDigests, blockIds), ...refuseSoloField(refuseSolo) };
1772
+ function repoCommitRequest(blockIds: BlockId[], { actionId, rev, tailId, blockDigests, refuseSolo, lane }: RepoCommitRequest): RepoCommitRequest {
1773
+ return { actionId, blockIds, rev, tailId, ...digestsFor(blockDigests, blockIds), ...laneField(lane), ...refuseSoloField(refuseSolo) };
1764
1774
  }
1765
1775
 
1766
1776
  /** `request`'s commit of `blockIds` alone, for {@link NetworkTransactor}'s two-step path to hand to its
@@ -1768,7 +1778,7 @@ function repoCommitRequest(blockIds: BlockId[], { actionId, rev, tailId, blockDi
1768
1778
  * through {@link repoCommitRequest}, which narrows them to the blocks that send commits. */
1769
1779
  function commitOf(request: CommitRequest, blockIds: BlockId[]): RepoCommitRequest {
1770
1780
  return { blockIds, actionId: request.actionId, rev: request.rev, tailId: request.tailId, blockDigests: request.blockDigests,
1771
- ...refuseSoloField(request.refuseSolo) };
1781
+ ...laneField(request.lane), ...refuseSoloField(request.refuseSolo) };
1772
1782
  }
1773
1783
 
1774
1784
  /** `request`'s blocks with its log tail first, each once — the order a coordinator commits them in. */
@@ -1811,7 +1821,8 @@ function baseRevsFor(all: BlockBaseRevs | undefined, batchBlockIds: BlockId[]):
1811
1821
  * coordinators — by `consolidateCoordinators`, or by `processBatches` re-batching a failed batch — is
1812
1822
  * several reservations, which the field must never claim to be. Decided per send, like the bases.
1813
1823
  * Every other field goes on every batch as given — `refuseSolo` included, whose loss on one batch would
1814
- * let that coordinator's share be written by a lone node the write asked not to be written by. */
1824
+ * let that coordinator's share be written by a lone node the write asked not to be written by, and
1825
+ * `lane`, which every share of the write states alike. */
1815
1826
  function pendRequestForBatch(action: PendRequest, payload: Transforms): PendRequest {
1816
1827
  const { baseRevs, soleReservation, ...rest } = action;
1817
1828
  const batchBlockIds = blockIdsForTransforms(payload);
@@ -4,6 +4,8 @@ import type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, CommitResult,
4
4
  import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
5
5
  import { withBlockRevs } from "../network/durability.js";
6
6
  import type { ReadDependency } from "../transaction/transaction.js";
7
+ import type { Hlc } from "../hlc/hlc.js";
8
+ import { laneField, type Lane } from "../lane/lane.js";
7
9
  import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
8
10
  import { blockDigestsField, baseRevsField } from "../transform/digest.js";
9
11
  import { refuseSoloField } from "../network/refuse-solo.js";
@@ -30,6 +32,15 @@ export type TransactOptions = {
30
32
  /** Refuse to be committed by a lone coordinator that knows it is not alone
31
33
  * (`SyncOptions.refuseSoloCommit`): set on both the pend and the commit as `refuseSolo`. */
32
34
  readonly refuseSolo?: boolean;
35
+ /** The write's HLC (`WriteIdentity.hlc`), put on the pend (`PendRequest.hlc`) so a storage node
36
+ * observes it without parsing the log entry out of the transforms. Left off when the caller has
37
+ * none at hand — the re-send of a retained attempt, whose entry carries it inside the transforms. */
38
+ readonly hlc?: Hlc;
39
+ /** The write's lane (`WriteIdentity.lane`), put on the pend and the commit (`PendRequest.lane`,
40
+ * `CommitRequest.lane`) so a storage node reads it off either request. Every send of this build
41
+ * sets it, the re-send of a retained attempt included (`InFlightCycle.lane`); left off only by a
42
+ * caller that genuinely has none. */
43
+ readonly lane?: Lane;
33
44
  };
34
45
 
35
46
  /** The block `entry` answers for `id`, for a read at `context` (`undefined` for an unpinned "give me
@@ -250,10 +261,12 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
250
261
  * by comparing `quorum` (see {@link WriteDurability}).
251
262
  */
252
263
  async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId, options: TransactOptions = {}): Promise<CommitResult> {
253
- const { priority = 0, blockDigests, baseRevs, refuseSolo } = options;
264
+ const { priority = 0, blockDigests, baseRevs, refuseSolo, hlc, lane } = options;
254
265
  const pendResult = await this.transactor.pend({
255
266
  transforms: transform, actionId, rev, policy: 'r',
256
267
  ...(priority > 0 ? { priority } : {}),
268
+ ...(hlc === undefined ? {} : { hlc }),
269
+ ...laneField(lane),
257
270
  ...baseRevsField(baseRevs),
258
271
  // One collection, pended whole and then committed: the shape `PendRequest.soleReservation` names.
259
272
  soleReservation: true,
@@ -271,6 +284,7 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
271
284
  actionId,
272
285
  rev,
273
286
  ...blockDigestsField(blockDigests),
287
+ ...laneField(lane),
274
288
  ...refuseSoloField(refuseSolo)
275
289
  });
276
290
  if (!commitResult.success) {
@@ -1,5 +1,6 @@
1
1
  import type { GetBlockResults, ActionBlocks, ActionLineage, BlockActionStatus, PendResult, CommitResult, PendRequest, CommitRequest, BlockGets, BlockId } from "../index.js";
2
2
  import type { PeerId } from "../network/types.js";
3
+ import type { HlcClock } from "../hlc/clock.js";
3
4
 
4
5
  export type ClusterNomineesResult = {
5
6
  /** Peer IDs of the cluster members who can participate in consensus */
@@ -7,6 +8,14 @@ export type ClusterNomineesResult = {
7
8
  };
8
9
 
9
10
  export type ITransactor = {
11
+ /** The clock of the node this transactor runs on, which every write through it mints its HLC from.
12
+ - The transactor is the one node-scoped object every collection, coordinator and queue already
13
+ holds, so it carries the clock rather than an option threaded through each of them.
14
+ - Optional: a transactor that declares none gets the process-wide fallback, so a writer reads
15
+ it through `clockOf` rather than directly.
16
+ */
17
+ readonly clock?: HlcClock;
18
+
10
19
  /** Get blocks by their IDs and versions or a specific action
11
20
  - Does not update the version of the block, but the action is available for explicit reading, and for committing
12
21
  - If the action targets the correct version, the call succeeds, unless failIfPending and there are any pending actions - the caller may choose to wait for pending actions to clear rather than risk racing with them
@@ -301,27 +301,25 @@ export class CacheSource<T extends IBlock> implements BlockSource<T> {
301
301
  return this.source.createBlockHeader(type, newId);
302
302
  }
303
303
 
304
+ /** Forget `blockIds` — or, with none given, every id this cache holds or describes, an LRU-evicted
305
+ * id's lingering {@link revisions} entry included. Each forgotten id's generation moves, so a read
306
+ * of it already in flight is not kept when it lands ({@link stillWanted}), and a base pin or a
307
+ * materialized memo built on what was forgotten is re-judged. */
304
308
  clear(blockIds: BlockId[] | undefined = undefined) {
305
- if (blockIds) {
306
- for (const id of blockIds) {
307
- this.cache.delete(id);
308
- this.revisions.delete(id);
309
- this.unkept.delete(id);
310
- this.bump(id);
311
- }
312
- } else {
313
- for (const [id] of this.cache) {
314
- this.bump(id);
315
- }
316
- for (const id of this.unkept.keys()) {
317
- this.bump(id);
318
- }
319
- this.cache.clear();
320
- this.revisions.clear();
321
- this.unkept.clear();
309
+ for (const id of blockIds ?? this.describedIds()) {
310
+ this.cache.delete(id);
311
+ this.revisions.delete(id);
312
+ this.unkept.delete(id);
313
+ this.bump(id);
322
314
  }
323
315
  }
324
316
 
317
+ /** Every id this cache can say anything about: cached, evicted with its revision kept, or handed
318
+ * through unkept. */
319
+ private describedIds(): Set<BlockId> {
320
+ return new Set([...[...this.cache].map(([id]) => id), ...this.revisions.keys(), ...this.unkept.keys()]);
321
+ }
322
+
325
323
  /** A cloned copy of the current cache contents with each id's committed revision, in LRU
326
324
  * order (oldest first, so replaying into another LruMap preserves eviction order). For
327
325
  * building a pinned read view ONLY (see {@link Collection.createReadTracker}): pass the