@optimystic/db-core 1.21.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 (181) hide show
  1. package/README.md +8 -4
  2. package/dist/src/btree/btree.d.ts +36 -4
  3. package/dist/src/btree/btree.d.ts.map +1 -1
  4. package/dist/src/btree/btree.js +86 -18
  5. package/dist/src/btree/btree.js.map +1 -1
  6. package/dist/src/collection/action.d.ts +7 -4
  7. package/dist/src/collection/action.d.ts.map +1 -1
  8. package/dist/src/collection/action.js +13 -5
  9. package/dist/src/collection/action.js.map +1 -1
  10. package/dist/src/collection/collection.d.ts +177 -51
  11. package/dist/src/collection/collection.d.ts.map +1 -1
  12. package/dist/src/collection/collection.js +265 -81
  13. package/dist/src/collection/collection.js.map +1 -1
  14. package/dist/src/collection/struct.d.ts +44 -8
  15. package/dist/src/collection/struct.d.ts.map +1 -1
  16. package/dist/src/collection/struct.js.map +1 -1
  17. package/dist/src/collection/write-attempts.d.ts +138 -34
  18. package/dist/src/collection/write-attempts.d.ts.map +1 -1
  19. package/dist/src/collection/write-attempts.js +168 -101
  20. package/dist/src/collection/write-attempts.js.map +1 -1
  21. package/dist/src/collections/diary/diary.d.ts.map +1 -1
  22. package/dist/src/collections/diary/diary.js +5 -1
  23. package/dist/src/collections/diary/diary.js.map +1 -1
  24. package/dist/src/collections/tree/tree.d.ts +18 -10
  25. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  26. package/dist/src/collections/tree/tree.js +17 -9
  27. package/dist/src/collections/tree/tree.js.map +1 -1
  28. package/dist/src/hlc/clock-store.d.ts +63 -0
  29. package/dist/src/hlc/clock-store.d.ts.map +1 -0
  30. package/dist/src/hlc/clock-store.js +49 -0
  31. package/dist/src/hlc/clock-store.js.map +1 -0
  32. package/dist/src/hlc/clock.d.ts +64 -0
  33. package/dist/src/hlc/clock.d.ts.map +1 -0
  34. package/dist/src/hlc/clock.js +171 -0
  35. package/dist/src/hlc/clock.js.map +1 -0
  36. package/dist/src/hlc/hlc.d.ts +38 -0
  37. package/dist/src/hlc/hlc.d.ts.map +1 -0
  38. package/dist/src/hlc/hlc.js +41 -0
  39. package/dist/src/hlc/hlc.js.map +1 -0
  40. package/dist/src/hlc/index.d.ts +5 -0
  41. package/dist/src/hlc/index.d.ts.map +1 -0
  42. package/dist/src/hlc/index.js +5 -0
  43. package/dist/src/hlc/index.js.map +1 -0
  44. package/dist/src/hlc/skew.d.ts +35 -0
  45. package/dist/src/hlc/skew.d.ts.map +1 -0
  46. package/dist/src/hlc/skew.js +35 -0
  47. package/dist/src/hlc/skew.js.map +1 -0
  48. package/dist/src/index.d.ts +2 -0
  49. package/dist/src/index.d.ts.map +1 -1
  50. package/dist/src/index.js +2 -0
  51. package/dist/src/index.js.map +1 -1
  52. package/dist/src/lane/index.d.ts +2 -0
  53. package/dist/src/lane/index.d.ts.map +1 -0
  54. package/dist/src/lane/index.js +2 -0
  55. package/dist/src/lane/index.js.map +1 -0
  56. package/dist/src/lane/lane.d.ts +46 -0
  57. package/dist/src/lane/lane.d.ts.map +1 -0
  58. package/dist/src/lane/lane.js +26 -0
  59. package/dist/src/lane/lane.js.map +1 -0
  60. package/dist/src/log/log.d.ts +50 -22
  61. package/dist/src/log/log.d.ts.map +1 -1
  62. package/dist/src/log/log.js +21 -13
  63. package/dist/src/log/log.js.map +1 -1
  64. package/dist/src/log/struct.d.ts +61 -1
  65. package/dist/src/log/struct.d.ts.map +1 -1
  66. package/dist/src/log/struct.js +24 -0
  67. package/dist/src/log/struct.js.map +1 -1
  68. package/dist/src/network/i-repo.d.ts +10 -0
  69. package/dist/src/network/i-repo.d.ts.map +1 -1
  70. package/dist/src/network/stale-failure.d.ts +20 -7
  71. package/dist/src/network/stale-failure.d.ts.map +1 -1
  72. package/dist/src/network/stale-failure.js +29 -7
  73. package/dist/src/network/stale-failure.js.map +1 -1
  74. package/dist/src/network/struct.d.ts +50 -0
  75. package/dist/src/network/struct.d.ts.map +1 -1
  76. package/dist/src/network/struct.js.map +1 -1
  77. package/dist/src/offline/entry.d.ts +14 -0
  78. package/dist/src/offline/entry.d.ts.map +1 -1
  79. package/dist/src/offline/entry.js +2 -0
  80. package/dist/src/offline/entry.js.map +1 -1
  81. package/dist/src/offline/journal.d.ts +10 -0
  82. package/dist/src/offline/journal.d.ts.map +1 -1
  83. package/dist/src/offline/queue.d.ts +10 -0
  84. package/dist/src/offline/queue.d.ts.map +1 -1
  85. package/dist/src/offline/queue.js +29 -3
  86. package/dist/src/offline/queue.js.map +1 -1
  87. package/dist/src/offline/status.d.ts +7 -0
  88. package/dist/src/offline/status.d.ts.map +1 -1
  89. package/dist/src/offline/status.js.map +1 -1
  90. package/dist/src/testing/test-transactor.d.ts +9 -1
  91. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  92. package/dist/src/testing/test-transactor.js +12 -3
  93. package/dist/src/testing/test-transactor.js.map +1 -1
  94. package/dist/src/transaction/actions-engine.d.ts +3 -0
  95. package/dist/src/transaction/actions-engine.d.ts.map +1 -1
  96. package/dist/src/transaction/actions-engine.js +3 -0
  97. package/dist/src/transaction/actions-engine.js.map +1 -1
  98. package/dist/src/transaction/coordinator.d.ts +16 -5
  99. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  100. package/dist/src/transaction/coordinator.js +203 -48
  101. package/dist/src/transaction/coordinator.js.map +1 -1
  102. package/dist/src/transaction/entry-commit.d.ts +45 -10
  103. package/dist/src/transaction/entry-commit.d.ts.map +1 -1
  104. package/dist/src/transaction/entry-commit.js +20 -7
  105. package/dist/src/transaction/entry-commit.js.map +1 -1
  106. package/dist/src/transaction/errors.d.ts +69 -1
  107. package/dist/src/transaction/errors.d.ts.map +1 -1
  108. package/dist/src/transaction/errors.js +70 -1
  109. package/dist/src/transaction/errors.js.map +1 -1
  110. package/dist/src/transaction/index.d.ts +1 -1
  111. package/dist/src/transaction/index.d.ts.map +1 -1
  112. package/dist/src/transaction/index.js +1 -1
  113. package/dist/src/transaction/index.js.map +1 -1
  114. package/dist/src/transaction/session.d.ts.map +1 -1
  115. package/dist/src/transaction/session.js +18 -5
  116. package/dist/src/transaction/session.js.map +1 -1
  117. package/dist/src/transaction/transaction.d.ts +74 -15
  118. package/dist/src/transaction/transaction.d.ts.map +1 -1
  119. package/dist/src/transaction/transaction.js +35 -15
  120. package/dist/src/transaction/transaction.js.map +1 -1
  121. package/dist/src/transaction/validator.d.ts +25 -4
  122. package/dist/src/transaction/validator.d.ts.map +1 -1
  123. package/dist/src/transaction/validator.js +45 -5
  124. package/dist/src/transaction/validator.js.map +1 -1
  125. package/dist/src/transactor/block-floors.d.ts +12 -1
  126. package/dist/src/transactor/block-floors.d.ts.map +1 -1
  127. package/dist/src/transactor/block-floors.js +14 -1
  128. package/dist/src/transactor/block-floors.js.map +1 -1
  129. package/dist/src/transactor/network-transactor.d.ts +8 -0
  130. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  131. package/dist/src/transactor/network-transactor.js +9 -4
  132. package/dist/src/transactor/network-transactor.js.map +1 -1
  133. package/dist/src/transactor/transactor-source.d.ts +11 -0
  134. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  135. package/dist/src/transactor/transactor-source.js +5 -1
  136. package/dist/src/transactor/transactor-source.js.map +1 -1
  137. package/dist/src/transactor/transactor.d.ts +8 -0
  138. package/dist/src/transactor/transactor.d.ts.map +1 -1
  139. package/dist/src/transform/cache-source.d.ts +7 -0
  140. package/dist/src/transform/cache-source.d.ts.map +1 -1
  141. package/dist/src/transform/cache-source.js +14 -18
  142. package/dist/src/transform/cache-source.js.map +1 -1
  143. package/package.json +1 -1
  144. package/src/btree/btree.ts +92 -18
  145. package/src/collection/action.ts +13 -5
  146. package/src/collection/collection.ts +3272 -3039
  147. package/src/collection/struct.ts +493 -456
  148. package/src/collection/write-attempts.ts +213 -109
  149. package/src/collections/diary/diary.ts +5 -1
  150. package/src/collections/tree/tree.ts +33 -18
  151. package/src/hlc/clock-store.ts +68 -0
  152. package/src/hlc/clock.ts +196 -0
  153. package/src/hlc/hlc.ts +56 -0
  154. package/src/hlc/index.ts +4 -0
  155. package/src/hlc/skew.ts +55 -0
  156. package/src/index.ts +2 -0
  157. package/src/lane/index.ts +1 -0
  158. package/src/lane/lane.ts +54 -0
  159. package/src/log/log.ts +341 -310
  160. package/src/log/struct.ts +62 -1
  161. package/src/network/i-repo.ts +11 -1
  162. package/src/network/stale-failure.ts +31 -7
  163. package/src/network/struct.ts +50 -0
  164. package/src/offline/entry.ts +16 -0
  165. package/src/offline/journal.ts +10 -0
  166. package/src/offline/queue.ts +38 -4
  167. package/src/offline/status.ts +7 -0
  168. package/src/testing/test-transactor.ts +1065 -1050
  169. package/src/transaction/actions-engine.ts +3 -0
  170. package/src/transaction/coordinator.ts +235 -54
  171. package/src/transaction/entry-commit.ts +56 -14
  172. package/src/transaction/errors.ts +60 -0
  173. package/src/transaction/index.ts +1 -1
  174. package/src/transaction/session.ts +18 -5
  175. package/src/transaction/transaction.ts +90 -17
  176. package/src/transaction/validator.ts +46 -5
  177. package/src/transactor/block-floors.ts +15 -1
  178. package/src/transactor/network-transactor.ts +1908 -1896
  179. package/src/transactor/transactor-source.ts +15 -1
  180. package/src/transactor/transactor.ts +9 -0
  181. 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.
@@ -2,6 +2,8 @@ import type { CollectionId, BlockId, IBlock, ActionId, Transform, Transforms } f
2
2
  import type { ActionContext, ActionRev } from "../collection/action.js";
3
3
  import type { Transaction, ValidityRejection } from "../transaction/transaction.js";
4
4
  import type { DisputeResolutionProof } from "../log/struct.js";
5
+ import type { Hlc } from "../hlc/hlc.js";
6
+ import type { Lane } from "../lane/lane.js";
5
7
  import type { PeerId } from "./types.js";
6
8
 
7
9
  export type ActionBlocks = {
@@ -54,6 +56,31 @@ export type PendRequest = ActionTransforms & {
54
56
  };
55
57
  /** For multi-collection transactions: supercluster nominees for consensus */
56
58
  superclusterNominees?: PeerId[];
59
+ /**
60
+ * The HLC of the write this pend carries (`LogEntry.hlc`, `Transaction.hlc`): the same value the
61
+ * log entry inside `transforms` carries, put here so a storage node observes the HLC of every
62
+ * write it stores without parsing log blocks out of transforms (docs/crdt-sync.md §Migration
63
+ * Path, Stage 1). The writer always sets it (`TransactorSource.transact`,
64
+ * `TransactionCoordinator.pendRequestFor`); optional on the wire because an older writer sends
65
+ * none, and because the re-send of a retained attempt has none at hand. Observational: a member
66
+ * reads it into its clock and never judges the pend by it. Omitted rather than `undefined`, for
67
+ * the same preimage reason as {@link baseRevs}.
68
+ */
69
+ hlc?: Hlc;
70
+ /**
71
+ * The lane of the write this pend carries (`ActionEntry.lane`, `Transaction.lane`): whether its
72
+ * conflicts with concurrent writes are the quorum's to decide (`serializable`) or may be merged
73
+ * later under the collection's declaration (`convergent`) — see `Lane` in
74
+ * `packages/db-core/src/lane/lane.ts`. The same value the log entry inside `transforms` carries,
75
+ * put here so a storage node reads it without parsing log blocks. Every writer of this build sets
76
+ * it (`TransactorSource.transact`, `TransactionCoordinator.pendRequestFor`); optional on the wire
77
+ * because an older writer sends none. A reader treats absence as "not stated", never as a lane.
78
+ * Observational: nothing judges the pend by it — a validating member checks the lane the
79
+ * transaction inside {@link validation} claims (`TransactionValidator.validate`) — and the
80
+ * coordinator's solo log lines report it. Omitted rather than `undefined`, for the same preimage
81
+ * reason as {@link baseRevs}.
82
+ */
83
+ lane?: Lane;
57
84
  /**
58
85
  * Aged, advisory retry priority for a pend that carries no transaction (default 0 when absent).
59
86
  * A validated multi-collection pend instead carries priority on the transaction inside
@@ -474,6 +501,14 @@ export type CommitRequest = ActionBlocks & {
474
501
  * {@link blockDigests} is.
475
502
  */
476
503
  refuseSolo?: true;
504
+ /**
505
+ * {@link PendRequest.lane}, on the commit, so a coordinator handling the commit reads the write's
506
+ * lane with no memory of the pend. Carried through every per-coordinator rebuild of the commit
507
+ * (`repoCommitRequest` in `NetworkTransactor`); optional on the wire for an older writer, and
508
+ * absence is "not stated". Omitted rather than `undefined`, for the preimage reason
509
+ * {@link blockDigests} is.
510
+ */
511
+ lane?: Lane;
477
512
  };
478
513
 
479
514
  /**
@@ -576,6 +611,21 @@ export type BlockGets = {
576
611
  * reads as `unknown`. Asked only by a writer deciding whether its own superseded write is saved
577
612
  * (`ITransactor.getLineage`); an ordinary read never sets it. */
578
613
  lineageOf?: ActionRev;
614
+ /** The asker does not want this read to start the read-repair consult that the lazy window alone
615
+ * would run BEHIND the read: a held block whose window has expired (or that the lazy mode's
616
+ * `readRepairSampleRate` picked for a re-check) is answered from the answering repo's own copy and
617
+ * no cohort consult is started for it. An effort hint, never a correctness one —
618
+ * the doubt an earlier consult recorded still stamps `unconfirmedAheadRev`, and the window's
619
+ * freshness stamp is untouched, so the next read without the flag consults as before.
620
+ *
621
+ * It never skips a consult whose answer the read depends on: a block missing locally (the absence
622
+ * verdict), a held block whose read carries a floor above it ({@link floors}), and every consult
623
+ * under `'paranoid'` read-repair still run and still block. Whole-read, so `NetworkTransactor.get`
624
+ * forwards it on every batch: a remote coordinator also skips its own background consult. A peer
625
+ * that predates the field ignores it and consults as before. Meant for the node's watch tick,
626
+ * through `Collection.readCommittedTails`, which reads every watched tail on a timer. Distinct from
627
+ * `skipClusterFetch`, the sync protocol's guard, which skips every consult and never flags. */
628
+ skipWindowConsult?: true;
579
629
  };
580
630
 
581
631
  /**
@@ -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[];