@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
@@ -0,0 +1,68 @@
1
+ import type { Hlc } from './hlc.js';
2
+
3
+ /**
4
+ * Where an `HlcClock` keeps its high-water mark across restarts, so a node whose wall clock is
5
+ * behind at restart does not issue an HLC below ones it issued before.
6
+ *
7
+ * A binding only stores and returns the value. When to save, and what to make of the loaded value,
8
+ * is the clock's policy, so every binding behaves the same way: the clock saves on a jump and at
9
+ * most once per {@link DEFAULT_HLC_PERSIST_INTERVAL_MS} otherwise, never awaits a save on its write
10
+ * path, and resumes from {@link restartFloor}.
11
+ */
12
+ export interface HlcClockStore {
13
+ /** The mark last saved, or `undefined` when none was ever saved. */
14
+ load(): Promise<Hlc | undefined>;
15
+ /** Replace the mark. The clock has at most one call in flight; a rejection is logged by the clock and retried on its next qualifying advance. */
16
+ save(hlc: Hlc): Promise<void>;
17
+ }
18
+
19
+ /**
20
+ * How far `wallMs` must have moved past the last saved mark before the clock saves again: a node
21
+ * issuing on its own wall clock writes at most once a second under load and nothing while idle,
22
+ * while an observed HLC far ahead of local time moves it past this at once and is saved at once.
23
+ * It is also the larger part of what {@link DEFAULT_HLC_RESTART_SLACK_MS} has to cover.
24
+ */
25
+ export const DEFAULT_HLC_PERSIST_INTERVAL_MS = 1000;
26
+
27
+ /**
28
+ * How far above the stored mark a restarted clock resumes when its local clock has not already
29
+ * passed that point. It covers the HLCs issued after the stored mark: at most
30
+ * {@link DEFAULT_HLC_PERSIST_INTERVAL_MS} of wall time before the next save, plus whatever the
31
+ * binding's store had not yet made durable when the process stopped.
32
+ *
33
+ * The second part, for a db-p2p node: the clock never flushes, so its mark is durable once some
34
+ * flush of the store covers it. The longest any of a node's stores may defer that is the relaxed
35
+ * flush window's cap, `maxWindowMs`, 5000 ms by default (`resolveDurabilityWindowPolicy` in
36
+ * `packages/db-p2p/src/storage/durability-window.ts`, packages/db-p2p/docs/storage.md §6); a write
37
+ * no flush covers is synced by the write group's idle timer, one second after it. So at the defaults
38
+ * the durable mark trails what the clock issued by at most 1000 + 5000 = 6000 ms, and 10 s leaves
39
+ * 4 s of margin. A deployment that raises `maxWindowMs` past 9 s should raise this with it
40
+ * (`HlcClockStartOptions.restartSlackMs`).
41
+ *
42
+ * In the ordinary case a real restart takes longer than this and the local clock wins, so the floor
43
+ * costs nothing; it matters for a fast restart or a clock that went backwards, where the node's HLCs
44
+ * then sit up to this far ahead of its wall clock until wall time catches up.
45
+ *
46
+ * NOTE: the slack covers an unsaved stretch only while the mark tracked wall time. A mark that
47
+ * jumped — to an observed HLC far ahead, or to the restart floor itself — is saved at once but not
48
+ * flushed, so a crash inside the store's durability window loses the jump, and the next start can
49
+ * issue HLCs at or below ones the lost run issued (a crash loop faster than that window repeats one
50
+ * floor). Harmless while HLCs are observational (Stage 1 of docs/crdt-sync.md); once anything orders
51
+ * by them, the save after a jump must be durable before the clock issues past it.
52
+ *
53
+ * NOTE: the floor is saved, so each restart that comes faster than the slack resumes a further
54
+ * slack above the last one: a crash loop restarting every few seconds moves the node's HLCs ahead
55
+ * of its wall clock by about the slack less the restart interval, per restart, without bound. Fine
56
+ * while HLCs are observational; if HLCs start deciding order (Stage 2), a remedy is to wait out the
57
+ * floor at start rather than resume above it.
58
+ */
59
+ export const DEFAULT_HLC_RESTART_SLACK_MS = 10_000;
60
+
61
+ /**
62
+ * The HLC a clock restarted over `stored` treats as already observed: `slackMs` above the stored
63
+ * `wallMs`, logical 0, in this node's name. The clock only ever raises its mark, so a local clock
64
+ * already past this point simply wins.
65
+ */
66
+ export function restartFloor(stored: Hlc, slackMs: number, nodeId: string): Hlc {
67
+ return { wallMs: stored.wallMs + slackMs, logical: 0, nodeId };
68
+ }
@@ -0,0 +1,196 @@
1
+ import type { ITransactor } from '../transactor/transactor.js';
2
+ import { createLogger } from '../logger.js';
3
+ import { compareHlc, isHlc, type Hlc } from './hlc.js';
4
+ import { DEFAULT_HLC_PERSIST_INTERVAL_MS, DEFAULT_HLC_RESTART_SLACK_MS, restartFloor, type HlcClockStore } from './clock-store.js';
5
+
6
+ const log = createLogger('hlc');
7
+
8
+ export type HlcClockOptions = {
9
+ /** This node's peer id string, stamped on every HLC the clock issues. Never `''`, which marks a legacy HLC. */
10
+ readonly nodeId: string;
11
+ /** Wall-clock milliseconds. Defaults to `Date.now`; tests inject a fake. */
12
+ readonly localClock?: () => number;
13
+ };
14
+
15
+ export type HlcClockStartOptions = HlcClockOptions & {
16
+ /** Where the clock's high-water mark survives a restart. */
17
+ readonly store: HlcClockStore;
18
+ /** Default {@link DEFAULT_HLC_PERSIST_INTERVAL_MS}. */
19
+ readonly persistIntervalMs?: number;
20
+ /** Default {@link DEFAULT_HLC_RESTART_SLACK_MS}. */
21
+ readonly restartSlackMs?: number;
22
+ };
23
+
24
+ /**
25
+ * A node's hybrid logical clock: the only thing in the repository that mints an {@link Hlc}.
26
+ *
27
+ * It holds the last HLC it issued or observed. {@link now} issues above it, {@link observe} raises
28
+ * it. Built with `new`, the clock is purely in memory; {@link HlcClock.start} builds one whose mark
29
+ * survives a restart through an {@link HlcClockStore}, so a store-backed clock is always one that
30
+ * has loaded its mark before it can issue.
31
+ */
32
+ export class HlcClock {
33
+ readonly nodeId: string;
34
+ private readonly localClock: () => number;
35
+ private last: Hlc | undefined;
36
+ private persistence: MarkPersistence | undefined;
37
+
38
+ constructor(options: HlcClockOptions) {
39
+ if (typeof options.nodeId !== 'string' || options.nodeId === '') {
40
+ throw new Error('HlcClock needs a non-empty nodeId: the empty node id marks a legacy HLC');
41
+ }
42
+ this.nodeId = options.nodeId;
43
+ this.localClock = options.localClock ?? Date.now;
44
+ }
45
+
46
+ /**
47
+ * A clock that resumes from the mark `store` holds: it treats {@link restartFloor} of that mark as
48
+ * already observed, so it issues above every HLC it saved before the restart and, by the slack,
49
+ * above the ones it issued after its last save. A `load` that rejects starts the clock from the
50
+ * local clock alone, logged: refusing to start a node because its mark could not be read would turn
51
+ * a lost record into an outage.
52
+ */
53
+ static async start(options: HlcClockStartOptions): Promise<HlcClock> {
54
+ const persistIntervalMs = nonNegative('persistIntervalMs', options.persistIntervalMs ?? DEFAULT_HLC_PERSIST_INTERVAL_MS);
55
+ const restartSlackMs = nonNegative('restartSlackMs', options.restartSlackMs ?? DEFAULT_HLC_RESTART_SLACK_MS);
56
+ const clock = new HlcClock(options);
57
+ const stored = await loadMark(options.store);
58
+ clock.persistence = new MarkPersistence(options.store, persistIntervalMs, stored?.wallMs);
59
+ if (stored !== undefined) clock.observe(restartFloor(stored, restartSlackMs, clock.nodeId));
60
+ return clock;
61
+ }
62
+
63
+ /**
64
+ * The local wall clock's reading, the one this clock issues from, without issuing anything. What a
65
+ * peer's HLC is measured against (`SkewLedger`): the mark itself is no reference, since it has
66
+ * already moved up to whatever far-ahead HLC this clock observed.
67
+ */
68
+ localTime(): number {
69
+ return this.localClock();
70
+ }
71
+
72
+ /** Issue an HLC above every one this clock has issued or observed. */
73
+ now(): Hlc {
74
+ const issued = this.next();
75
+ this.advance(issued);
76
+ return issued;
77
+ }
78
+
79
+ /**
80
+ * Raise the mark to `hlc` when it is above it; otherwise nothing. A value without the shape of an
81
+ * HLC ({@link isHlc}) is ignored: a wire field is checked, and reported, by the
82
+ * caller that read it.
83
+ */
84
+ observe(hlc: Hlc): void {
85
+ if (!isHlc(hlc)) return;
86
+ if (this.last !== undefined && compareHlc(hlc, this.last) <= 0) return;
87
+ this.advance({ wallMs: hlc.wallMs, logical: hlc.logical, nodeId: hlc.nodeId });
88
+ }
89
+
90
+ /**
91
+ * The HLC after the mark at the local clock's reading. A logical count already at the top of the
92
+ * safe-integer range carries into `wallMs` instead: past it `logical + 1` stops changing the value,
93
+ * and the clock would issue one HLC twice after observing a peer's far-advanced count.
94
+ */
95
+ private next(): Hlc {
96
+ const prior = this.last;
97
+ const wallMs = Math.max(this.localClock(), prior?.wallMs ?? -Infinity);
98
+ if (prior === undefined || wallMs !== prior.wallMs) return { wallMs, logical: 0, nodeId: this.nodeId };
99
+ if (prior.logical < Number.MAX_SAFE_INTEGER) return { wallMs, logical: prior.logical + 1, nodeId: this.nodeId };
100
+ return { wallMs: wallMs + 1, logical: 0, nodeId: this.nodeId };
101
+ }
102
+
103
+ private advance(hlc: Hlc): void {
104
+ const moved = hlc.wallMs !== this.last?.wallMs;
105
+ this.last = hlc;
106
+ if (moved) this.persistence?.offer(hlc);
107
+ }
108
+ }
109
+
110
+ /**
111
+ * The clock for a transactor that declares none (`ITransactor.clock`): the reference peer's, the
112
+ * Quereus plugin's `local` and `test` transactors, a host's own. One per process, in the node id
113
+ * `'local'`, which is also the peer id `TransactionSession.create` stamps when none is given, so the
114
+ * two defaults agree. It has no store, so its mark does not survive a restart.
115
+ *
116
+ * This is the one place a second {@link HlcClock} can exist in a process beside a node's own;
117
+ * reach it only through {@link clockOf}.
118
+ */
119
+ let undeclaredClock: HlcClock | undefined;
120
+
121
+ /** The clock a write through `transactor` mints from: the transactor's own, or the process-wide fallback. */
122
+ export function clockOf(transactor: ITransactor): HlcClock {
123
+ return transactor.clock ?? (undeclaredClock ??= new HlcClock({ nodeId: 'local' }));
124
+ }
125
+
126
+ async function loadMark(store: HlcClockStore): Promise<Hlc | undefined> {
127
+ try {
128
+ const stored = await store.load();
129
+ if (stored === undefined || isHlc(stored)) return stored;
130
+ log('hlc:load-malformed value=%o', stored);
131
+ } catch (error) {
132
+ log('hlc:load-failed error=%s', error instanceof Error ? error.message : String(error));
133
+ }
134
+ return undefined;
135
+ }
136
+
137
+ function nonNegative(name: string, value: number): number {
138
+ if (!Number.isFinite(value) || value < 0) {
139
+ throw new RangeError(`HlcClock ${name} must be a finite number at or above 0, got ${value}`);
140
+ }
141
+ return value;
142
+ }
143
+
144
+ /**
145
+ * The clock's saves: one whenever `wallMs` has moved at least `intervalMs` past the last mark handed
146
+ * to the store, fire-and-forget, never awaited on a write path. At most one save is in flight; a mark
147
+ * offered meanwhile waits, replaced by any newer one. A rejection is logged and the next qualifying
148
+ * advance tries again.
149
+ */
150
+ class MarkPersistence {
151
+ private lastOfferedWallMs: number | undefined;
152
+ private inFlight = false;
153
+ private queued: Hlc | undefined;
154
+
155
+ constructor(
156
+ private readonly store: HlcClockStore,
157
+ private readonly intervalMs: number,
158
+ storedWallMs: number | undefined,
159
+ ) {
160
+ this.lastOfferedWallMs = storedWallMs;
161
+ }
162
+
163
+ offer(hlc: Hlc): void {
164
+ if (this.lastOfferedWallMs !== undefined && hlc.wallMs < this.lastOfferedWallMs + this.intervalMs) return;
165
+ this.lastOfferedWallMs = hlc.wallMs;
166
+ if (this.inFlight) {
167
+ this.queued = hlc;
168
+ return;
169
+ }
170
+ this.save(hlc);
171
+ }
172
+
173
+ private save(hlc: Hlc): void {
174
+ this.inFlight = true;
175
+ void this.callStore(hlc)
176
+ .catch(error => log('hlc:save-failed wallMs=%d logical=%d error=%s',
177
+ hlc.wallMs, hlc.logical, error instanceof Error ? error.message : String(error)))
178
+ .finally(() => this.settled());
179
+ }
180
+
181
+ /** The store's `save`, with a synchronous throw turned into a rejection so it never reaches the caller of `now`. */
182
+ private callStore(hlc: Hlc): Promise<void> {
183
+ try {
184
+ return this.store.save(hlc);
185
+ } catch (error) {
186
+ return Promise.reject(error);
187
+ }
188
+ }
189
+
190
+ private settled(): void {
191
+ this.inFlight = false;
192
+ const next = this.queued;
193
+ this.queued = undefined;
194
+ if (next !== undefined) this.save(next);
195
+ }
196
+ }
package/src/hlc/hlc.ts ADDED
@@ -0,0 +1,56 @@
1
+ /**
2
+ * A hybrid logical clock (HLC) value: the Kulkarni-Demirbas construction docs/crdt-sync.md
3
+ * §HLC Generation and Causal Tracking describes, as one plain JSON-safe object, since it travels
4
+ * inside log blocks and pend requests, both plain JSON on the wire.
5
+ *
6
+ * Only `HlcClock` mints one. The other constructors are {@link legacyHlc}, for a record written
7
+ * before the field existed, and test fixtures.
8
+ */
9
+ export type Hlc = {
10
+ /** Wall-clock milliseconds, or higher: the max of the issuer's clock and the highest HLC it had observed. */
11
+ readonly wallMs: number;
12
+ /** Breaks ties among HLCs issued within one `wallMs`. 0 whenever `wallMs` moved. */
13
+ readonly logical: number;
14
+ /** The issuing node's peer id string. `''` means legacy: an entry written before the field existed. */
15
+ readonly nodeId: string;
16
+ };
17
+
18
+ /**
19
+ * The total order on HLCs: `wallMs`, then `logical`, then `nodeId` by plain string (code unit)
20
+ * comparison. Two HLCs from one node never compare equal, because its clock never issues the same
21
+ * `(wallMs, logical)` twice; two from different nodes are separated by `nodeId`.
22
+ */
23
+ export function compareHlc(a: Hlc, b: Hlc): number {
24
+ if (a.wallMs !== b.wallMs) return a.wallMs < b.wallMs ? -1 : 1;
25
+ if (a.logical !== b.logical) return a.logical < b.logical ? -1 : 1;
26
+ if (a.nodeId === b.nodeId) return 0;
27
+ return a.nodeId < b.nodeId ? -1 : 1;
28
+ }
29
+
30
+ /** The later of `a` and `b` by {@link compareHlc}; `b` when `a` is absent. */
31
+ export function maxHlc(a: Hlc | undefined, b: Hlc): Hlc {
32
+ return a === undefined || compareHlc(b, a) > 0 ? b : a;
33
+ }
34
+
35
+ /**
36
+ * The HLC a reader derives for an entry or record written before the field existed: its plain
37
+ * timestamp, no logical count, and the empty node id. The empty id sorts before every real peer id,
38
+ * which is the only property anything relies on.
39
+ */
40
+ export function legacyHlc(timestamp: number): Hlc {
41
+ return { wallMs: timestamp, logical: 0, nodeId: '' };
42
+ }
43
+
44
+ /**
45
+ * Whether a value read off the wire has the shape of an {@link Hlc}: a finite `wallMs`, a `logical`
46
+ * that is a non-negative safe integer (what a clock issues, and what it can count past without
47
+ * losing precision), and a string node id. How far `wallMs` may sit from local time is not a shape
48
+ * question and is not checked here.
49
+ */
50
+ export function isHlc(value: unknown): value is Hlc {
51
+ if (typeof value !== 'object' || value === null) return false;
52
+ const { wallMs, logical, nodeId } = value as Record<string, unknown>;
53
+ return typeof wallMs === 'number' && Number.isFinite(wallMs)
54
+ && Number.isSafeInteger(logical) && (logical as number) >= 0
55
+ && typeof nodeId === 'string';
56
+ }
@@ -0,0 +1,4 @@
1
+ export * from './hlc.js';
2
+ export * from './clock-store.js';
3
+ export * from './clock.js';
4
+ export * from './skew.js';
@@ -0,0 +1,55 @@
1
+ import { LruMap } from '../utility/lru-map.js';
2
+
3
+ /** How many node ids a {@link SkewLedger} remembers; the least recently heard from is forgotten first. */
4
+ export const DEFAULT_SKEW_LEDGER_MAX_NODES = 256;
5
+
6
+ /**
7
+ * How far one node's HLCs have been from this node's wall clock, over the samples a
8
+ * {@link SkewLedger} kept for it. Both maxima are magnitudes, 0 when no sample fell on that side.
9
+ *
10
+ * A gap does not say which clock is wrong: a node whose own HLC jumped forward after it observed a
11
+ * far-ahead peer shows as ahead to everyone, and so does a node whose wall clock simply runs fast.
12
+ */
13
+ export type NodeSkew = {
14
+ readonly nodeId: string;
15
+ readonly samples: number;
16
+ /** The largest amount one of the node's HLCs sat ahead of local time, in milliseconds. */
17
+ readonly maxAheadMs: number;
18
+ /** The largest amount one of the node's HLCs sat behind local time, in milliseconds. */
19
+ readonly maxBehindMs: number;
20
+ };
21
+
22
+ /**
23
+ * The measurement docs/crdt-sync.md §Open Questions asks for before deciding whether members should
24
+ * refuse an HLC far from their own clock: per node id, how far the HLCs this node received from it
25
+ * sat from local time. Pure and in memory; it refuses nothing and nothing acts on it. A db-p2p
26
+ * storage repo records one sample per pend that carries an HLC (`StorageRepo.hlcSkew`).
27
+ */
28
+ export class SkewLedger {
29
+ private readonly nodes: LruMap<string, NodeSkew>;
30
+
31
+ constructor(maxNodes = DEFAULT_SKEW_LEDGER_MAX_NODES) {
32
+ this.nodes = new LruMap(maxNodes);
33
+ }
34
+
35
+ /**
36
+ * Add one sample: `gapMs` is the HLC's `wallMs` less local time, positive when the node's HLC was
37
+ * ahead. Returns the node's summary with the sample included.
38
+ */
39
+ record(nodeId: string, gapMs: number): NodeSkew {
40
+ const prior = this.nodes.get(nodeId);
41
+ const next: NodeSkew = {
42
+ nodeId,
43
+ samples: (prior?.samples ?? 0) + 1,
44
+ maxAheadMs: Math.max(prior?.maxAheadMs ?? 0, gapMs),
45
+ maxBehindMs: Math.max(prior?.maxBehindMs ?? 0, -gapMs),
46
+ };
47
+ this.nodes.set(nodeId, next);
48
+ return next;
49
+ }
50
+
51
+ /** Every node remembered, least recently heard from first. */
52
+ snapshot(): NodeSkew[] {
53
+ return [...this.nodes].map(([, skew]) => skew);
54
+ }
55
+ }
package/src/index.ts CHANGED
@@ -5,6 +5,8 @@ export * from "./cluster/index.js";
5
5
  export * from "./cohort-topic/index.js";
6
6
  export * from "./collection/index.js";
7
7
  export * from "./collections/index.js";
8
+ export * from "./hlc/index.js";
9
+ export * from "./lane/index.js";
8
10
  export * from "./log/index.js";
9
11
  export * from "./logger-registry.js";
10
12
  export * from "./matchmaking/index.js";
@@ -0,0 +1 @@
1
+ export * from './lane.js';
@@ -0,0 +1,54 @@
1
+ /**
2
+ * The lane of a write: how its conflicts with other machines' CONCURRENT writes are decided
3
+ * (docs/crdt-sync.md §Stage 5 — Tunable per-collection; docs/partition-healing.md §I-Confluence
4
+ * Classification).
5
+ *
6
+ * - `serializable` — the quorum lane. The write needs the collection's cohort to agree before it
7
+ * is committed, and the revision order decides every conflict: today's behaviour for every write.
8
+ * The tree entry guards (`TreeEntryGuard` in `packages/db-core/src/collections/tree/struct.ts`)
9
+ * are this lane's conflict rule, re-making every uniqueness and lost-update decision
10
+ * deterministically on replay.
11
+ * - `convergent` — the merge lane. The write may be committed by one machine without first agreeing
12
+ * with the others and merged into their concurrent writes later, because the invariants it is
13
+ * responsible for survive a merge: an append to an append-only set, an increment of an unbounded
14
+ * counter, a last-writer-wins field. The collection's merge declaration (`ConvergentMerge` in
15
+ * `packages/db-core/src/collection/collection.ts`) is this lane's conflict rule.
16
+ *
17
+ * Convergence is a property of an OPERATION, never of a system (the invariant-confluence result of
18
+ * Bailis et al., and Li et al.'s RedBlue consistency). **Idempotence is not the criterion**, and is
19
+ * the mistake a reader makes first: setting a column to a value is idempotent and still needs a
20
+ * tie-break under concurrency, while an increment is not idempotent and merges fine. The question is
21
+ * whether two machines applying the operation concurrently, each over its own view, leave the
22
+ * invariants the operation is responsible for true once the two views are merged.
23
+ *
24
+ * Nothing admits a write by its lane yet: the solo path, the offline queue and the conflict replay
25
+ * behave as they did before the field. The replay stage (backlog
26
+ * `feat-replay-mode-collections-merge-divergent-histories`) is what consumes it.
27
+ */
28
+ export type Lane = 'serializable' | 'convergent';
29
+
30
+ /**
31
+ * The lane of a write made of several parts: `serializable` if any part is. Convergence is a claim
32
+ * each part makes about itself, so a write is convergent only when every part claims it — and a
33
+ * write of NO parts claims nothing, so an empty set answers `serializable`, the lane every write
34
+ * takes without a declaration.
35
+ */
36
+ export function stricterLane(lanes: Iterable<Lane>): Lane {
37
+ let seen = false;
38
+ for (const lane of lanes) {
39
+ if (lane === 'serializable') return 'serializable';
40
+ seen = true;
41
+ }
42
+ return seen ? 'convergent' : 'serializable';
43
+ }
44
+
45
+ /**
46
+ * Wraps a request's optional `lane` (`PendRequest.lane`, `CommitRequest.lane`) so the field spreads
47
+ * onto the request only when the sender has one: omitted rather than sent as `undefined`, because the
48
+ * request is hashed verbatim into every cohort signature preimage, so a request that states no lane
49
+ * must serialize exactly as it did before the field existed. Every producer of the field goes
50
+ * through here, as `refuseSoloField` does for its field.
51
+ */
52
+ export function laneField(lane: Lane | undefined): { lane?: Lane } {
53
+ return lane === undefined ? {} : { lane };
54
+ }