@optimystic/db-core 1.22.0 → 1.24.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
@@ -4,6 +4,8 @@ import type { Collection } from '../collection/collection.js';
4
4
  import type { EntryId } from '../collection/segments.js';
5
5
  import type { CollectionId, InFlightAttempt } from '../collection/struct.js';
6
6
  import type { WriteDurability } from '../network/struct.js';
7
+ import type { Hlc } from '../hlc/hlc.js';
8
+ import type { Lane } from '../lane/lane.js';
7
9
  import type { CommittedEffect, EntryStatus, EntryWaitingFor, QueuedEntry } from './status.js';
8
10
  import type { JournalDriveState } from './journal.js';
9
11
 
@@ -12,6 +14,18 @@ export type Entry = {
12
14
  readonly id: EntryId;
13
15
  readonly seq: number;
14
16
  readonly queuedAt: number;
17
+ /** The local commit time as an HLC (`JournalEntryRecord.hlc`): minted at enqueue from the sealed
18
+ * collections' transactor clock, restored from the journal, and passed to every drive of the entry
19
+ * as the write's HLC. Fixed for the entry's whole life, like `queuedAt` — a renewed action id
20
+ * does not renew it, since the entry is the same local commit. */
21
+ readonly hlc: Hlc;
22
+ /** The entry's lane (`JournalEntryRecord.lane`): the caller's classification at enqueue, or the
23
+ * stricter of the sealed collections' own declarations over their segments, restored from the
24
+ * journal, and passed to every drive as the write's lane. Fixed for the entry's whole life, like
25
+ * `hlc`: a later change to a collection's declaration, or to a SQL table's tags, does not
26
+ * reclassify an entry already queued — its lane is what was true of its statements when the
27
+ * application made them. */
28
+ readonly lane: Lane;
15
29
  readonly expiresAt: number | undefined;
16
30
  /** The collections the entry sealed a segment in — the ones `sealPending` answered `true` for. */
17
31
  readonly collections: readonly Collection<any>[];
@@ -56,6 +70,7 @@ export function queuedStatus(entry: Entry): QueuedStatus {
56
70
  seq: entry.seq,
57
71
  collections: entry.collections.map(collection => collection.id),
58
72
  queuedAt: entry.queuedAt,
73
+ lane: entry.lane,
59
74
  attempts: entry.attempts,
60
75
  inDoubt: entry.inDoubt,
61
76
  waitingFor: entry.waitingFor,
@@ -82,6 +97,7 @@ export function snapshot(entry: Entry): QueuedEntry {
82
97
  id: entry.id,
83
98
  seq: entry.seq,
84
99
  queuedAt: entry.queuedAt,
100
+ lane: entry.lane,
85
101
  collections: entry.collections.map(collection => collection.id),
86
102
  ...committedField(entry),
87
103
  status: currentStatus(entry),
@@ -2,6 +2,8 @@ import type { Action, ActionId } from '../collection/action.js';
2
2
  import type { EntryId } from '../collection/segments.js';
3
3
  import type { CollectionId, InFlightAttempt } from '../collection/struct.js';
4
4
  import type { WriteDurability } from '../network/struct.js';
5
+ import type { Hlc } from '../hlc/hlc.js';
6
+ import type { Lane } from '../lane/lane.js';
5
7
  import type { EntryStatus } from './status.js';
6
8
 
7
9
  /**
@@ -21,6 +23,14 @@ export type JournalEntryRecord = {
21
23
  readonly id: EntryId;
22
24
  readonly seq: number;
23
25
  readonly queuedAt: number;
26
+ /** The entry's local commit time as an HLC, minted at enqueue and carried on every log entry the
27
+ * entry's drives append (`HeadCommitOptions.hlc`, `EntryCommit.hlc`), so a restore re-supplies the
28
+ * value the first drive used. */
29
+ readonly hlc: Hlc;
30
+ /** The entry's lane, fixed at enqueue and carried on every log entry, pend and commit the entry's
31
+ * drives make (`HeadCommitOptions.lane`, `EntryCommit.lane`), so a restore re-supplies the value the
32
+ * first drive used rather than reclassifying the entry under declarations that may have changed. */
33
+ readonly lane: Lane;
24
34
  readonly expiresAt?: number;
25
35
  /** One per collection the entry sealed a segment in, in sealing order: the segment's actions,
26
36
  * verbatim — the array the segment holds, which the journal serialises and never mutates. */
@@ -6,6 +6,9 @@ import { ActionRefusedError, SealedSegmentsError } from '../collection/struct.js
6
6
  import type { CollectionId, InFlightAttempt, SyncOptions } from '../collection/struct.js';
7
7
  import type { AlreadyAppliedTally } from '../collection/action.js';
8
8
  import type { ITransactor } from '../transactor/transactor.js';
9
+ import { clockOf } from '../hlc/clock.js';
10
+ import type { Hlc } from '../hlc/hlc.js';
11
+ import { stricterLane, type Lane } from '../lane/lane.js';
9
12
  import { TransactionCoordinator } from '../transaction/coordinator.js';
10
13
  import { classifyCommitFailure, refusalReason } from '../transaction/commit-failure-class.js';
11
14
  import { recordCollectionDurability, transactionDurability } from '../transaction/durability.js';
@@ -73,6 +76,12 @@ export type RestoreInit = {
73
76
  readonly id: EntryId;
74
77
  readonly seq: number;
75
78
  readonly queuedAt: number;
79
+ /** The record's HLC (`JournalEntryRecord.hlc`); a record written before the field existed is
80
+ * restored with `legacyHlc(queuedAt)`, the one shape a legacy entry already has. */
81
+ readonly hlc: Hlc;
82
+ /** The record's lane (`JournalEntryRecord.lane`); a record written before the field existed is
83
+ * restored as `serializable`, the lane every entry then took. */
84
+ readonly lane: Lane;
76
85
  readonly expiresAt?: number;
77
86
  /** The collections the entry sealed a segment in, in the record's order — `stage` is called for
78
87
  * each, in this order. */
@@ -140,21 +149,29 @@ function entryDurability(entry: Entry, written: TransactionDurability | undefine
140
149
  * is its own storage); the queue's callers never seal such a set together, so this is a defect that
141
150
  * stops the drain rather than a failure of the entry.
142
151
  */
143
- function sharedTransactor(entry: Entry, remaining: readonly Collection<any>[]): ITransactor {
152
+ function sharedTransactor(entryId: EntryId, remaining: readonly Collection<any>[]): ITransactor {
144
153
  const transactor = remaining[0]!.transactor;
145
154
  const stranger = remaining.find(collection => collection.transactor !== transactor);
146
155
  if (stranger !== undefined) {
147
- throw new Error(`offline queue: entry ${entry.id} spans collections on different transactors (${remaining[0]!.id} and ${stranger.id}); an entry is one network transaction on one transactor`);
156
+ throw new Error(`offline queue: entry ${entryId} spans collections on different transactors (${remaining[0]!.id} and ${stranger.id}); an entry is one network transaction on one transactor`);
148
157
  }
149
158
  return transactor;
150
159
  }
151
160
 
161
+ /** The lane of an entry nobody classified: the stricter of each sealed collection's own declaration
162
+ * over the segment it sealed under `entryId` (`Collection.laneOf`). */
163
+ function sealedLaneOf(sealed: readonly Collection<any>[], entryId: EntryId): Lane {
164
+ return stricterLane(sealed.map(collection => collection.laneOf(collection.sealedActions(entryId) ?? [])));
165
+ }
166
+
152
167
  /** The journal's entry record for `entry`, built from each sealed collection's segment. */
153
168
  function entryRecord(entry: Entry): JournalEntryRecord {
154
169
  return {
155
170
  id: entry.id,
156
171
  seq: entry.seq,
157
172
  queuedAt: entry.queuedAt,
173
+ hlc: entry.hlc,
174
+ lane: entry.lane,
158
175
  ...(entry.expiresAt === undefined ? {} : { expiresAt: entry.expiresAt }),
159
176
  segments: entry.collections.map(collection => {
160
177
  const actions = collection.sealedActions(entry.id);
@@ -294,7 +311,7 @@ export class OfflineQueue {
294
311
  *
295
312
  * @throws QueueDisposedError after {@link dispose}; the drain's defect, as `cause`, once the
296
313
  * drain has stopped on one (nothing queued then would ever drain); whatever the journal threw. */
297
- async enqueue(collections: readonly Collection<any>[], init?: { id?: EntryId; timestamp?: number }): Promise<QueuedEntry | undefined> {
314
+ async enqueue(collections: readonly Collection<any>[], init?: { id?: EntryId; timestamp?: number; hlc?: Hlc; lane?: Lane }): Promise<QueuedEntry | undefined> {
298
315
  this.assertAccepting();
299
316
  const id = init?.id ?? mintId();
300
317
  if (this.byId.has(id)) throw new Error(`entry ${id} is already queued`);
@@ -305,6 +322,17 @@ export class OfflineQueue {
305
322
  id,
306
323
  seq: this.nextSeq,
307
324
  queuedAt,
325
+ // The local commit time in HLC form, from the clock the entry will be sent through. Minted
326
+ // here, once, so every drive of the entry — first or re-drive, after a restart or not —
327
+ // appends the same entry. Read off the first sealed collection rather than through
328
+ // `sharedTransactor`, whose stranger check must not fail an enqueue that has already sealed:
329
+ // it runs, and throws, at the send.
330
+ hlc: init?.hlc ?? clockOf(sealed[0]!.transactor).now(),
331
+ // The caller's classification when it gave one (the SQL bridge's, from the statements), else
332
+ // the stricter of the sealed collections' own declarations over what each sealed. Fixed here
333
+ // for the entry's life and journaled: a reclassification later would make a re-drive differ
334
+ // from the attempt it repeats.
335
+ lane: init?.lane ?? sealedLaneOf(sealed, id),
308
336
  expiresAt: this.expireAfterMs === undefined ? undefined : queuedAt + this.expireAfterMs,
309
337
  collections: sealed,
310
338
  actionId: mintId(),
@@ -732,19 +760,23 @@ export class OfflineQueue {
732
760
  ...submit,
733
761
  actionId: entry.actionId,
734
762
  timestamp: entry.queuedAt,
763
+ hlc: entry.hlc,
764
+ lane: entry.lane,
735
765
  recordAttempt: attempt => recordAttempt(new Map([[collection.id, attempt]])),
736
766
  onCommittedHead: applied => onCommittedHead(collection.id, applied),
737
767
  ...(resume === undefined ? {} : { resume }),
738
768
  });
739
769
  return transactionDurability(new Map([[collection.id, written]]));
740
770
  }
741
- const coordinator = new TransactionCoordinator(sharedTransactor(entry, remaining),
771
+ const coordinator = new TransactionCoordinator(sharedTransactor(entry.id, remaining),
742
772
  new Map(remaining.map(collection => [collection.id, collection])), { pendValidation: 'none' });
743
773
  const resume = new Map([...entry.retained].filter(([collectionId]) => remaining.some(collection => collection.id === collectionId)));
744
774
  return coordinator.commitEntry({
745
775
  entryId: entry.id,
746
776
  actionId: entry.actionId,
747
777
  timestamp: entry.queuedAt,
778
+ hlc: entry.hlc,
779
+ lane: entry.lane,
748
780
  collectionIds: remaining.map(collection => collection.id),
749
781
  recordAttempt,
750
782
  onCommittedHead,
@@ -1058,6 +1090,8 @@ export class OfflineQueue {
1058
1090
  id: init.id,
1059
1091
  seq: init.seq,
1060
1092
  queuedAt: init.queuedAt,
1093
+ hlc: init.hlc,
1094
+ lane: init.lane,
1061
1095
  expiresAt: init.expiresAt,
1062
1096
  collections: init.collections,
1063
1097
  actionId: drive?.actionId ?? mintId(),
@@ -1,6 +1,7 @@
1
1
  import type { CollectionId } from '../collection/struct.js';
2
2
  import type { EntryId } from '../collection/segments.js';
3
3
  import type { TransactionDurability } from '../transaction/durability.js';
4
+ import type { Lane } from '../lane/lane.js';
4
5
 
5
6
  /**
6
7
  * The status an offline-sync queue reports for each entry (docs/offline-sync.md §Following
@@ -42,6 +43,10 @@ export type EntryStatus =
42
43
  /** The collections the entry sealed a segment in — every collection it changed. */
43
44
  collections: readonly CollectionId[];
44
45
  queuedAt: number;
46
+ /** The entry's lane (`Lane` in `packages/db-core/src/lane/lane.ts`): whether a later merge
47
+ * will handle it (`convergent`) or the cohort must agree to it (`serializable`). Fixed at
48
+ * enqueue for the entry's whole life, so it is never announced on its own. */
49
+ lane: Lane;
45
50
  /** Submissions made so far. */
46
51
  attempts: number;
47
52
  /** Whether an attempt may have landed (see `OfflineQueue`'s in-doubt rule): such an entry can
@@ -115,6 +120,8 @@ export type QueuedEntry = {
115
120
  readonly id: EntryId;
116
121
  readonly seq: number;
117
122
  readonly queuedAt: number;
123
+ /** As on the `queued` status. */
124
+ readonly lane: Lane;
118
125
  readonly collections: readonly CollectionId[];
119
126
  /** As on the `queued` status: the collections already committed, once part of the entry is. */
120
127
  readonly committedCollections?: readonly CollectionId[];