@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
@@ -1,5 +1,7 @@
1
1
  import type { ActionId, AlreadyAppliedTally, CollectionId } from "../index.js";
2
2
  import type { ReadDependency, Transaction } from "./transaction.js";
3
+ import type { Hlc } from "../hlc/hlc.js";
4
+ import type { Lane } from "../lane/lane.js";
3
5
  import { clampPriority } from "./transaction.js";
4
6
  import type { Collection, RefreshReport } from "../collection/collection.js";
5
7
  import type { HeadCommitHandle } from "../collection/head-commit.js";
@@ -12,8 +14,9 @@ import { refuseSoloField } from "../network/refuse-solo.js";
12
14
 
13
15
  /**
14
16
  * What the coordinator's phases know about the write they are sending — everything they used to
15
- * read off a `Transaction`: the action id every pend and commit names, the timestamp its log entries
16
- * carry, the reads recorded on them, and the aged retry priority an unvalidated pend carries.
17
+ * read off a `Transaction`: the action id every pend and commit names, the timestamp, HLC and lane
18
+ * its log entries carry, the reads recorded on them, and the aged retry priority an unvalidated pend
19
+ * carries.
17
20
  * `commit` and `execute` derive one from their transaction ({@link writeContextOf}); the per-entry
18
21
  * commit (`TransactionCoordinator.commitEntry`) builds its own, since a queued entry has no
19
22
  * transaction. A `TransactionStamp` is deliberately NOT fabricated for it: a stamp carries a peer id,
@@ -21,8 +24,16 @@ import { refuseSoloField } from "../network/refuse-solo.js";
21
24
  */
22
25
  export type WriteContext = {
23
26
  readonly actionId: ActionId;
24
- /** Stamped on every log entry of the write; fixed per write, never per attempt. */
27
+ /** Stamped on every log entry of the write; fixed per write, never per attempt. The second
28
+ * per-write value, {@link hlc}, follows the same rule. */
25
29
  readonly timestamp: number;
30
+ /** Stamped on every log entry of the write (`LogEntry.hlc`) and carried on every pend of it
31
+ * (`PendRequest.hlc`): one HLC for every participant, the transaction's own or the queued entry's. */
32
+ readonly hlc: Hlc;
33
+ /** Stamped on every log entry of the write (`ActionEntry.lane`) and carried on every pend and
34
+ * commit of it (`PendRequest.lane`, `CommitRequest.lane`): one lane for every participant, the
35
+ * transaction's own (`Transaction.lane`) or the queued entry's (`EntryCommit.lane`). */
36
+ readonly lane: Lane;
26
37
  /** Recorded on every log entry of the write (`ActionEntry.reads`). */
27
38
  readonly reads: readonly ReadDependency[];
28
39
  /** Already clamped (`clampPriority`); 0 on a first attempt. */
@@ -35,11 +46,14 @@ export type WriteContext = {
35
46
 
36
47
  /** The write context of a transaction's attempt, read when the attempt starts: `commitAttempts` ages
37
48
  * the transaction's priority between attempts, so it is read per attempt rather than once. `cycle`
38
- * is what the commit was asked of every send ({@link InFlightCycle}). */
39
- export function writeContextOf(transaction: Transaction, cycle: InFlightCycle = {}): WriteContext {
49
+ * is what the commit was asked of every send ({@link InFlightCycle}) beyond the lane, which is the
50
+ * transaction's own. */
51
+ export function writeContextOf(transaction: Transaction, cycle: Omit<InFlightCycle, 'lane'> = {}): WriteContext {
40
52
  return {
41
53
  actionId: transaction.id as ActionId,
42
54
  timestamp: transaction.stamp.timestamp,
55
+ hlc: transaction.hlc,
56
+ lane: transaction.lane,
43
57
  reads: transaction.reads,
44
58
  priority: clampPriority(transaction.priority),
45
59
  ...refuseSoloField(cycle.refuseSolo),
@@ -60,6 +74,12 @@ export type EntryCommit = {
60
74
  readonly actionId: ActionId;
61
75
  /** The entry's local commit time: every participant's log entry carries it (`WriteIdentity`). */
62
76
  readonly timestamp: number;
77
+ /** The entry's local commit time as an HLC, minted by the queue at enqueue and re-supplied on every
78
+ * drive: every participant's log entry carries it (`WriteIdentity.hlc`). */
79
+ readonly hlc: Hlc;
80
+ /** The entry's lane, fixed at enqueue and re-supplied on every drive: one lane for every
81
+ * participant's log entry, pend and commit (`WriteIdentity.lane`, `HeadCommitOptions.lane`). */
82
+ readonly lane: Lane;
63
83
  /** The collections the entry wrote, each of which must hold `entryId` as its HEAD sealed segment. */
64
84
  readonly collectionIds: readonly CollectionId[];
65
85
  /** Attempts an earlier `commitEntry` under this action id recorded through {@link recordAttempt}
@@ -82,12 +102,23 @@ export type EntryCommit = {
82
102
  export type RefreshParticipant = {
83
103
  readonly collectionId: CollectionId;
84
104
  /** The refresh itself — `Collection.refreshInFlight` for a transaction's participant, the
85
- * handle's `refresh` for an entry's — with the write's own report. */
86
- refresh(report: RefreshReport, lastChance: boolean): Promise<void>;
105
+ * handle's `refresh` for an entry's — with the write's own report. `tailFloor` is the highest
106
+ * revision a responder confirmed is taken under THIS collection, for the refresh's log-tail read
107
+ * (see `Collection.updateInternal`); `undefined` when no refusal of it carried one. */
108
+ refresh(report: RefreshReport, lastChance: boolean, tailFloor: number | undefined): Promise<void>;
87
109
  /** Called after the refresh finished the write's own entry and the round recorded it as saved. */
88
110
  saved?(): void;
89
111
  };
90
112
 
113
+ /** What one participant's next attempt would request, for the stall check the coordinator's retry
114
+ * loop runs per participant (`RevisionStallWatch.check`): the revision it would request and the one
115
+ * it holds (`Collection.getNextRev` and `committedRevision`, or the handle's `nextRev` and `heldRev`). */
116
+ export type NextRevision = {
117
+ readonly collectionId: CollectionId;
118
+ readonly requestedRev: number;
119
+ readonly heldRev: number | undefined;
120
+ };
121
+
91
122
  /**
92
123
  * The handles of one entry's participants — a `HeadCommitHandle` per collection the entry wrote —
93
124
  * and the moves the per-entry commit makes over all of them in lock-step. The handles are opened in
@@ -112,10 +143,10 @@ export class EntryParticipants {
112
143
  * one twice (opening it twice would deadlock on its own latch) or names one `collections` does
113
144
  * not hold; and closes the handles already opened when a later `openHeadCommit` throws (a
114
145
  * `SealedSegmentsError` precondition, say), so no latch is left held. Every handle's cycle carries
115
- * `cycle` ({@link InFlightCycle}), so a refresh that finishes a torn attempt re-sends it on the
116
- * same terms the coordinator's own round sends it.
146
+ * `cycle` ({@link InFlightCycle}, whose lane is the entry's), so a refresh that finishes a torn
147
+ * attempt re-sends it on the same terms the coordinator's own round sends it.
117
148
  */
118
- static async open(collections: ReadonlyMap<CollectionId, Collection<any>>, entry: EntryCommit, cycle: InFlightCycle = {}): Promise<EntryParticipants> {
149
+ static async open(collections: ReadonlyMap<CollectionId, Collection<any>>, entry: EntryCommit, cycle: Omit<InFlightCycle, 'lane'> = {}): Promise<EntryParticipants> {
119
150
  if (entry.collectionIds.length === 0) {
120
151
  throw new Error(`commitEntry ${entry.entryId}: an entry commit names at least one collection`);
121
152
  }
@@ -136,7 +167,7 @@ export class EntryParticipants {
136
167
  for (const { collectionId, collection } of participants) {
137
168
  const resume = entry.resume?.get(collectionId);
138
169
  handles.set(collectionId, await collection.openHeadCommit(entry.entryId,
139
- { actionId: entry.actionId, timestamp: entry.timestamp },
170
+ { actionId: entry.actionId, timestamp: entry.timestamp, hlc: entry.hlc, lane: entry.lane },
140
171
  {
141
172
  ...cycle,
142
173
  ...(resume === undefined ? {} : { resume }),
@@ -167,11 +198,21 @@ export class EntryParticipants {
167
198
  refreshers(): RefreshParticipant[] {
168
199
  return [...this.handles].map(([collectionId, handle]) => ({
169
200
  collectionId,
170
- refresh: (report, lastChance) => handle.refresh(report, lastChance),
201
+ refresh: (report, lastChance, tailFloor) => handle.refresh(report, lastChance, tailFloor),
171
202
  saved: () => this.drop(collectionId),
172
203
  }));
173
204
  }
174
205
 
206
+ /** What every remaining participant's next attempt would request, in sorted order, for the retry
207
+ * loop's stall check. Read under the latches the handles hold, so nothing moves it meanwhile. */
208
+ nextRevisions(): NextRevision[] {
209
+ return [...this.handles].map(([collectionId, handle]) => ({
210
+ collectionId,
211
+ requestedRev: handle.nextRev(),
212
+ heldRev: handle.heldRev(),
213
+ }));
214
+ }
215
+
175
216
  /** Build the attempt of every remaining participant, in sorted order, under the latches
176
217
  * (`HeadCommitHandle.stage`). A throw — a participant's recorded refusal, a block too large to
177
218
  * send — leaves nothing sent and nothing on any participant changed: an attempt is built on a
@@ -271,8 +312,9 @@ export class EntryParticipants {
271
312
  }
272
313
 
273
314
  /** The latch-acquisition order of `TransactionCoordinator.commitOnce` and `execute`, spelled the
274
- * same way: a plain string comparison. Change all three together. */
275
- function compareCollectionIds(a: CollectionId, b: CollectionId): number {
315
+ * same way: a plain string comparison. Change all three together. Also the order the retry loop's
316
+ * stall check visits participants in (`RetryBudget.assertNotStalled`), where only determinism matters. */
317
+ export function compareCollectionIds(a: CollectionId, b: CollectionId): number {
276
318
  return a < b ? -1 : a > b ? 1 : 0;
277
319
  }
278
320
 
@@ -1,4 +1,5 @@
1
1
  import type { CollectionId } from "../collection/index.js";
2
+ import type { ConfirmedRevision } from "../collection/write-attempts.js";
2
3
  import type { WriteDurability } from "../network/struct.js";
3
4
  import { transactionDurability, type TransactionDurability } from "./durability.js";
4
5
 
@@ -119,6 +120,13 @@ export class CoordinatorStaleLossError extends Error {
119
120
  public readonly failedCollections: readonly CollectionId[],
120
121
  /** The underlying stale/conflict reason surfaced by the failed pend/commit phase. */
121
122
  public readonly reason?: string,
123
+ /** Per collection, the revision a responder CONFIRMED is committed under another action
124
+ * (`StaleFailure.staleAt`), for every failed collection whose refusal carried one. A collection
125
+ * refused with no confirmed number, cancelled because a sibling was refused, or refused in a
126
+ * batch whose number belongs to a sibling (see `staleAtOwner`) has no entry. Revisions are
127
+ * per-collection counters, which is why this is a map and not one number; the coordinator's
128
+ * retry loop reads each entry against its own collection's next revision (`RevisionStallWatch`). */
129
+ public readonly staleAtByCollection: ReadonlyMap<CollectionId, ConfirmedRevision> = new Map(),
122
130
  ) {
123
131
  // Deliberately does not assert that nothing committed: this is also the internal signal a
124
132
  // half-landed attempt retries on, and it then surfaces as a partial error's `reason`.
@@ -130,6 +138,58 @@ export class CoordinatorStaleLossError extends Error {
130
138
  }
131
139
  }
132
140
 
141
+ /**
142
+ * Thrown by {@link TransactionCoordinator.commit} and {@link TransactionCoordinator.commitEntry}
143
+ * when refreshing repeatedly moved one participant nowhere at all while a responder confirmed a
144
+ * revision at or above the one that participant's next attempt would request — the client's view
145
+ * of that collection disagrees with the cluster's, and retrying would re-send the identical taken
146
+ * number. The multi-collection counterpart of `SyncRevisionStalledError`, decided by the same rule
147
+ * per participant (`RevisionStallWatch` in `packages/db-core/src/collection/write-attempts.ts`,
148
+ * `SyncOptions.maxStalledAttempts` strikes), and reported as `commit:revision-stalled`.
149
+ *
150
+ * The distinction from plain stale-loss exhaustion matters because the two failures need different
151
+ * responses: a budget spent on lost races can succeed on a later try, where this one is provably
152
+ * identical on every remaining attempt, so the caller's view of {@link collectionId} has to be
153
+ * repaired first. The coordinator deliberately does NOT adopt the confirmed revision to get past
154
+ * it, for the reason `SyncRevisionStalledError` gives.
155
+ *
156
+ * Extends {@link CoordinatorStaleLossError} so existing catches keep working and
157
+ * `classifyCommitFailure` files it as `contention`, the choice `SyncRevisionStalledError` made by
158
+ * subclassing exhaustion. Like any error escaping the retry loop after a participant was saved, it
159
+ * surfaces inside a {@link CoordinatorPartialCommitError} as its `reason`.
160
+ */
161
+ export class CoordinatorRevisionStalledError extends CoordinatorStaleLossError {
162
+ constructor(
163
+ /** The participant whose view is wedged. */
164
+ public readonly collectionId: CollectionId,
165
+ /** The confirmed revision the stall is based on: the block a responder named, and the
166
+ * revision it reported that block already committed at, under {@link collectionId}'s counter. */
167
+ public readonly staleAt: ConfirmedRevision,
168
+ /** The revision the participant's next attempt would have requested. */
169
+ public readonly requestedRev: number,
170
+ /** The revision this client holds for the participant; `undefined` for a collection that has
171
+ * committed nothing. */
172
+ public readonly heldRev: number | undefined,
173
+ /** Losses the commit took before stopping — attempts refused, and refresh rounds refused for a
174
+ * cause that can clear. */
175
+ public readonly attempts: number,
176
+ /** Every participant still to commit when the commit stopped, the wedged one included. */
177
+ failedCollections: readonly CollectionId[],
178
+ /** The last refusal's reason, when one was given. */
179
+ reason?: string,
180
+ ) {
181
+ super(failedCollections, reason, new Map([[collectionId, staleAt]]));
182
+ // The base class's "lost a stale race" wording is deliberately NOT reused: it reads as
183
+ // ordinary contention, which is exactly the misdiagnosis this class exists to prevent.
184
+ this.message = `Multi-collection commit stopped after ${attempts} attempts: `
185
+ + `this client holds rev ${heldRev ?? 'none'} of collection ${collectionId} and would request rev ${requestedRev}, `
186
+ + `but block ${staleAt.blockId} is confirmed committed at rev ${staleAt.rev} and `
187
+ + `refreshing did not close the gap`
188
+ + (reason ? `: ${reason}` : '');
189
+ this.name = 'CoordinatorRevisionStalledError';
190
+ }
191
+ }
192
+
133
193
  /**
134
194
  * Thrown by {@link TransactionCoordinator.applyActions} and {@link TransactionCoordinator.commit}
135
195
  * (and returned as a failure result by {@link TransactionCoordinator.execute}) when a second
@@ -37,7 +37,7 @@ export {
37
37
  export { ReadDependencyCollector } from './read-dependency-collector.js';
38
38
  export { TransactionCoordinator } from './coordinator.js';
39
39
  export type { CoordinatorOptions, PendValidationMode } from './coordinator.js';
40
- export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from './errors.js';
40
+ export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError, CoordinatorRevisionStalledError } from './errors.js';
41
41
  export { classifyCommitFailure, isCohortUnreachableRead, refusalReason } from './commit-failure-class.js';
42
42
  export type { CommitFailureClass } from './commit-failure-class.js';
43
43
  export { transactionDurability, recordCollectionDurability } from './durability.js';
@@ -88,11 +88,15 @@ export class TransactionSession {
88
88
  actionsToApply = actions;
89
89
  } else {
90
90
  // Create a temporary transaction with just this statement for translation
91
+ // Temporary, for translation only: neither the id, the HLC nor the lane is ever read,
92
+ // since the engine translates statements here and commits nothing.
91
93
  const tempTransaction: Transaction = {
92
94
  stamp: this.stamp,
93
95
  statements: [statement],
94
96
  reads: [],
95
- id: 'temp' // Temporary ID for translation only
97
+ hlc: this.coordinator.clock.now(),
98
+ lane: 'serializable',
99
+ id: 'temp'
96
100
  };
97
101
  const result = await this.engine.execute(tempTransaction);
98
102
  if (!result.success || !result.actions) {
@@ -139,22 +143,31 @@ export class TransactionSession {
139
143
 
140
144
  // Collect read dependencies from all participating collections
141
145
  const reads = this.coordinator.getReadDependencies();
146
+ // The HLC is minted AFTER the read set is final, so it sits above every HLC a read of this
147
+ // transaction observed (see Transaction.hlc), and once per transaction: the coordinator's
148
+ // retries re-send this same object.
149
+ const hlc = this.coordinator.clock.now();
150
+ // The lane is the caller's classification of the whole transaction (`SyncOptions.lane`, one
151
+ // lane over every participant), and `serializable` for an engine that declared nothing.
152
+ const lane = options?.lane ?? 'serializable';
142
153
 
143
154
  // Create the complete transaction
144
155
  const transaction: Transaction = {
145
156
  stamp: this.stamp,
146
157
  statements: this.statements,
147
158
  reads,
148
- id: await createTransactionId(this.stamp.id, this.statements, reads)
159
+ hlc,
160
+ lane,
161
+ id: await createTransactionId(this.stamp.id, this.statements, reads, hlc, lane)
149
162
  };
150
163
 
151
- // Sign the canonical client-signature payload if a signer was supplied. The
152
- // payload covers stamp.id + statements + reads, which are all final now. A signer failure
164
+ // Sign the canonical client-signature payload if a signer was supplied. The payload covers
165
+ // stamp.id + statements + reads + hlc + lane, which are all final now. A signer failure
153
166
  // (e.g. a wrong-key-type libp2p sign) is caught and surfaced as a clean commit failure BEFORE
154
167
  // coordinator.commit runs — the transaction object is local and discarded, so a failed sign can
155
168
  // never leak a partially-built unsigned transaction into consensus.
156
169
  if (this.signer) {
157
- const payload = clientSignaturePayload(this.stamp.id, this.statements, reads);
170
+ const payload = clientSignaturePayload(this.stamp.id, this.statements, reads, hlc, lane);
158
171
  try {
159
172
  transaction.signature = await this.signer(payload);
160
173
  } catch (error) {
@@ -3,6 +3,8 @@ import { toString as uint8ArrayToString } from "uint8arrays/to-string";
3
3
  import type { BlockId } from "../blocks/index.js";
4
4
  import type { CollectionId } from "../collection/index.js";
5
5
  import type { TransactionDurability } from "./durability.js";
6
+ import type { Hlc } from "../hlc/hlc.js";
7
+ import type { Lane } from "../lane/lane.js";
6
8
  import { hashString } from "../utility/hash-string.js";
7
9
 
8
10
  /**
@@ -62,14 +64,47 @@ export type Transaction = {
62
64
  /** Read dependencies for optimistic concurrency control */
63
65
  reads: ReadDependency[];
64
66
 
65
- /** Transaction identifier (hash of stamp.id + statements + reads)
67
+ /**
68
+ * The transaction's hybrid logical clock value (docs/crdt-sync.md §Migration Path, Stage 1):
69
+ * minted at COMMIT, after the read set is final, from the committing transactor's clock
70
+ * (`clockOf(transactor).now()`), and stamped on every participant's log entry (`LogEntry.hlc`,
71
+ * through `WriteContext.hlc`). On the transaction rather than the stamp because the stamp is
72
+ * fixed at BEGIN, before any of the transaction's reads, and an HLC minted then could sit below
73
+ * one a later read observed — the causal rule the HLC exists to keep. Folded into {@link id} and
74
+ * into the client signature ({@link clientSignaturePayload}), so a relaying peer cannot alter
75
+ * it; excluded from nothing else. Fixed per transaction: a retry of the same `Transaction` object
76
+ * re-sends it, like `stamp.timestamp`.
77
+ *
78
+ * Required of every transaction this build builds; a validator meeting one from an older build
79
+ * on the wire tolerates its absence at that one ingress (`TransactionValidator.validate`).
80
+ */
81
+ hlc: Hlc;
82
+
83
+ /**
84
+ * The transaction's lane (`Lane` in `packages/db-core/src/lane/lane.ts`): whether its conflicts
85
+ * with other machines' concurrent writes are the quorum's to decide (`serializable`) or may be
86
+ * merged later under each collection's declaration (`convergent`). ONE lane for every
87
+ * participant: a transaction over several collections takes the stricter of its parts, decided by
88
+ * the caller before the transaction is built (`TransactionSession.commit` takes it from
89
+ * `SyncOptions.lane`, `serializable` when the engine declared nothing), and stamped on every
90
+ * participant's log entry (`ActionEntry.lane`, through `WriteContext.lane`) and on every pend and
91
+ * commit of it. Folded into {@link id} and into the client signature
92
+ * ({@link clientSignaturePayload}), so a relaying peer cannot alter it. Nothing admits by it yet.
93
+ *
94
+ * Required of every transaction this build builds; a validator meeting one from an older build
95
+ * on the wire tolerates its absence at that one ingress as `serializable`
96
+ * (`TransactionValidator.validate`), every write then having been serializable.
97
+ */
98
+ lane: Lane;
99
+
100
+ /** Transaction identifier (hash of stamp.id + statements + reads + hlc + lane)
66
101
  * Final transaction identity, used in logs
67
102
  */
68
103
  id: string;
69
104
 
70
105
  /**
71
106
  * Optional client signature (base64url) over {@link clientSignaturePayload}
72
- * `(stamp.id, statements, reads)`, produced at commit by an injected
107
+ * `(stamp.id, statements, reads, hlc, lane)`, produced at commit by an injected
73
108
  * {@link TransactionSigner}.
74
109
  *
75
110
  * A node that wires a {@link ClientSignatureVerifier} into its
@@ -226,8 +261,9 @@ export async function createTransactionStamp(
226
261
  }
227
262
 
228
263
  /**
229
- * Create a transaction id from stamp id, statements, and reads.
230
- * This is the final transaction identity used in logs.
264
+ * Create a transaction id from stamp id, statements, reads, the transaction's HLC and its lane.
265
+ * This is the final transaction identity used in logs, and the action id the log records, so two
266
+ * transactions that differ only in when they committed, or in the lane they claim, differ in id.
231
267
  *
232
268
  * NOTE: reads are serialized in their given order here (non-canonical). This differs
233
269
  * from {@link clientSignaturePayload}, which canonicalises reads before hashing. That is
@@ -236,15 +272,17 @@ export async function createTransactionStamp(
236
272
  * design-consensus-hygiene-notes), NOT fixed here to avoid changing existing tx ids.
237
273
  *
238
274
  * NOTE: {@link Transaction.priority} is deliberately absent from this preimage — the id is a pure
239
- * function of `(stampId, statements, reads)`, so two retry attempts that differ only in aged
240
- * priority produce the SAME id. Do not add priority here.
275
+ * function of `(stampId, statements, reads, hlc, lane)`, so two retry attempts that differ only in
276
+ * aged priority produce the SAME id. Do not add priority here.
241
277
  */
242
278
  export async function createTransactionId(
243
279
  stampId: string,
244
280
  statements: string[],
245
- reads: ReadDependency[]
281
+ reads: ReadDependency[],
282
+ hlc: Hlc,
283
+ lane: Lane
246
284
  ): Promise<string> {
247
- const txData = JSON.stringify({ stampId, statements, reads });
285
+ const txData = JSON.stringify({ stampId, statements, reads, hlc: canonicalHlc(hlc), lane });
248
286
  return `tx:${await hashString(txData)}`;
249
287
  }
250
288
 
@@ -252,18 +290,31 @@ export async function createTransactionId(
252
290
  * Version prefix for the client-signature payload, so the signed form can evolve
253
291
  * without ambiguity. Distinct from (but consistent in spirit with) the operations-hash
254
292
  * canonical form — this covers transaction INPUTS, not operations.
293
+ *
294
+ * `v2` added the transaction's HLC to the signed bytes, and `v3` its lane. Mixed-version cost, the
295
+ * same for both bumps: a writer on an earlier build signs the old payload, and a verifier on this
296
+ * build reports `Invalid client signature` against it. Accepted on the precedent the validity marker
297
+ * set (docs/internals.md, *A reject that judges the transaction itself wrong*), because no deployment
298
+ * wires a `ClientSignatureVerifier` today (backlog `feat-no-deployment-validates-transactions-at-pend`),
299
+ * and because the question "can a relaying peer alter the HLC, or the lane a write claims" is best
300
+ * settled while nothing verifies.
255
301
  */
256
- export const CLIENT_SIG_VERSION = 'txsig:v1';
302
+ export const CLIENT_SIG_VERSION = 'txsig:v3';
257
303
 
258
304
  /**
259
305
  * Canonical bytes a client signs and a node verifies. Deterministic: reads are sorted
260
- * (blockId, then revision); statements keep their sequential order.
306
+ * (blockId, then revision); statements keep their sequential order; the HLC's three fields are
307
+ * written in a fixed order; the lane is one of two literal strings.
261
308
  *
262
- * Binds three things at once: the CLIENT IDENTITY (via `stampId`, which hashes peerId +
263
- * nonce), the EXACT statements, and the OCC read set (blockId + revision — "tail
264
- * binding" for anti-replay). Both signer and verifier derive the bytes from
265
- * `transaction.stamp.id` + `transaction.statements` + `transaction.reads` through this
266
- * one function, so they reproduce identical bytes regardless of read ordering.
309
+ * Binds five things at once: the CLIENT IDENTITY (via `stampId`, which hashes peerId +
310
+ * nonce), the EXACT statements, the OCC read set (blockId + revision — "tail
311
+ * binding" for anti-replay), the transaction's HLC, which validators order by in a later
312
+ * stage and a relaying peer must therefore not be able to alter, and the lane the writer claims,
313
+ * which a member checks against the collections' declarations in a later stage and a relaying peer
314
+ * must not be able to loosen. Both signer and verifier derive the bytes from
315
+ * `transaction.stamp.id` + `transaction.statements` + `transaction.reads` + `transaction.hlc` +
316
+ * `transaction.lane` through this one function, so they reproduce identical bytes regardless of
317
+ * read ordering.
267
318
  *
268
319
  * NOTE: {@link Transaction.priority} is deliberately absent from the signed bytes — a retry that
269
320
  * only bumps priority keeps the same signature, so anti-replay / OCC binding never churns. Do not
@@ -272,16 +323,25 @@ export const CLIENT_SIG_VERSION = 'txsig:v1';
272
323
  export function clientSignaturePayload(
273
324
  stampId: string,
274
325
  statements: readonly string[],
275
- reads: readonly ReadDependency[]
326
+ reads: readonly ReadDependency[],
327
+ hlc: Hlc,
328
+ lane: Lane
276
329
  ): Uint8Array {
277
330
  const canonicalReads = [...reads].sort(
278
331
  (a, b) => a.blockId < b.blockId ? -1 : a.blockId > b.blockId ? 1
279
332
  : a.revision - b.revision
280
333
  );
281
- const body = JSON.stringify({ stampId, statements, reads: canonicalReads });
334
+ const body = JSON.stringify({ stampId, statements, reads: canonicalReads, hlc: canonicalHlc(hlc), lane });
282
335
  return new TextEncoder().encode(`${CLIENT_SIG_VERSION}:${body}`);
283
336
  }
284
337
 
338
+ /** The HLC's three fields in one fixed key order, so the two preimages above do not depend on the
339
+ * key order of whatever object carried the value — a JSON round trip preserves order, but a value
340
+ * rebuilt by hand need not. */
341
+ function canonicalHlc(hlc: Hlc): Hlc {
342
+ return { wallMs: hlc.wallMs, logical: hlc.logical, nodeId: hlc.nodeId };
343
+ }
344
+
285
345
  /**
286
346
  * Signs the canonical client-signature payload, returning base64url. Async to allow
287
347
  * libp2p `PrivateKey.sign`; tests pass a synchronous fake.
@@ -353,6 +413,18 @@ export interface ITransactionEngine {
353
413
  * @returns The resulting actions from execution
354
414
  */
355
415
  execute(transaction: Transaction): Promise<ExecutionResult>;
416
+
417
+ /**
418
+ * The strictest lane this engine's catalog allows the transaction's statements: `serializable`
419
+ * when any statement's write must be ordered by the quorum, else `convergent`. What a
420
+ * {@link TransactionValidator} checks a `convergent` claim against (docs/transactions.md §Which
421
+ * lane a transaction takes), so it must be computable identically by every machine whose schema
422
+ * hash matches the writer's, from the statements as replicated — never from what only the writer
423
+ * saw (a key's provenance, a value read). Omitted by an engine with no catalog to classify against
424
+ * ({@link ActionsEngine}), whose transactions' lanes a validator then accepts unchecked; a throw
425
+ * means this node could not judge.
426
+ */
427
+ laneCeiling?(transaction: Transaction): Promise<Lane>;
356
428
  }
357
429
 
358
430
  /**
@@ -476,6 +548,7 @@ export interface ITransactionValidator {
476
548
  * 0.5. Verify the client signature (only if a signature verifier is wired)
477
549
  * 1. Verify stamp.engineId matches a known engine
478
550
  * 2. Verify stamp.schemaHash matches local schema
551
+ * 2.5. Verify a `convergent` lane claim against the engine's ceiling (only if the engine offers one)
479
552
  * 3. Verify read dependencies (no stale reads)
480
553
  * 4. Re-execute transaction.statements through engine (isolated state)
481
554
  * 5. Collect operations from re-execution
@@ -3,6 +3,7 @@ import type { Transaction, ITransactionEngine, ITransactionValidator, Validation
3
3
  import type { BlockActionState } from '../network/struct.js';
4
4
  import { isTransactionExpired, clientSignaturePayload, computeStampId } from './transaction.js';
5
5
  import { collectOperations, hashOperations, opsHashVersion, OPS_HASH_VERSION } from './operations-hash.js';
6
+ import { legacyHlc } from '../hlc/hlc.js';
6
7
 
7
8
  /**
8
9
  * Engine registration for validation.
@@ -50,11 +51,12 @@ function validityRefusal(reason: string, computedHash?: string): ValidationResul
50
51
  * Used by cluster participants when receiving PendRequests.
51
52
  *
52
53
  * Every refusal is classed, because a writer and the dispute path act on the class and must never
53
- * read the prose to find it. Five refusals judge the transaction itself wrong and carry
54
+ * read the prose to find it. Six refusals judge the transaction itself wrong and carry
54
55
  * `validity` ({@link validityRefusal}): a tampered stamp, a missing or invalid client signature, a
55
- * failed re-execution, and an operations-hash mismatch. The rest carry none: an expired stamp (a
56
- * clock judgement), a stale read (out of date — a re-read can win), and an unknown engine, a schema
57
- * mismatch or an operations-hash format this node does not produce (this node cannot judge).
56
+ * lane mismatch, a failed re-execution, and an operations-hash mismatch. The rest carry none: an
57
+ * expired stamp (a clock judgement), a stale read (out of date — a re-read can win), and an unknown
58
+ * engine, a schema mismatch or an operations-hash format this node does not produce (this node
59
+ * cannot judge).
58
60
  */
59
61
  export class TransactionValidator implements ITransactionValidator {
60
62
  constructor(
@@ -92,7 +94,16 @@ export class TransactionValidator implements ITransactionValidator {
92
94
  if (transaction.signature === undefined) {
93
95
  return validityRefusal('Missing client signature');
94
96
  }
95
- const payload = clientSignaturePayload(stamp.id, transaction.statements, transaction.reads);
97
+ // The one wire ingress that tolerates a transaction without an HLC or a lane: a writer on
98
+ // a build before either field. Its payload is derived from the stamp's time and the lane
99
+ // every write then took (`serializable`) so the check is well-typed; such a writer signed
100
+ // the `txsig:v1` or `v2` bytes, so it is refused here regardless (see CLIENT_SIG_VERSION
101
+ // for the accepted mixed-version cost). The derived values are used for this check only:
102
+ // the transaction object is handed on unchanged, never rewritten with a value its writer
103
+ // did not stamp.
104
+ const hlc = transaction.hlc ?? legacyHlc(stamp.timestamp);
105
+ const lane = transaction.lane ?? 'serializable';
106
+ const payload = clientSignaturePayload(stamp.id, transaction.statements, transaction.reads, hlc, lane);
96
107
  if (!this.verifyClientSignature(stamp.peerId, payload, transaction.signature)) {
97
108
  return validityRefusal('Invalid client signature');
98
109
  }
@@ -116,6 +127,12 @@ export class TransactionValidator implements ITransactionValidator {
116
127
  };
117
128
  }
118
129
 
130
+ // 2.5. Check the lane the transaction claims. Here because the ceiling reads only the
131
+ // statements and the catalog step 2 just proved equal, and needs no re-execution.
132
+ if (await this.claimsLaneAboveCeiling(transaction, registration.engine)) {
133
+ return validityRefusal('Lane mismatch: transaction claims convergent, this node computes serializable');
134
+ }
135
+
119
136
  // 3. Verify read dependencies (optimistic concurrency)
120
137
  if (this.blockStateProvider && transaction.reads.length > 0) {
121
138
  for (const read of transaction.reads) {
@@ -199,6 +216,30 @@ export class TransactionValidator implements ITransactionValidator {
199
216
  }
200
217
  }
201
218
 
219
+ /**
220
+ * Whether `transaction` claims `convergent` where this node's engine computes `serializable`
221
+ * (docs/transactions.md §Which lane a transaction takes). The classification is the writer's
222
+ * engine's; this node never reclassifies, it only refuses a claim it can disprove. Only a
223
+ * `convergent` claim is checked, since `serializable` is always acceptable; an absent lane (a
224
+ * writer on a build before the field) is `serializable`; an engine without `laneCeiling` is not
225
+ * asked. A throw out of the engine propagates: the node could not judge, which the pend check in
226
+ * db-p2p turns into an unmarked `validator-fault` reject.
227
+ *
228
+ * The bound of the check: the ceiling is what every machine with the writer's schema computes
229
+ * from the replicated statements alone, and an honest writer's lane is at or below it. What only
230
+ * the writer saw is not in the replicated statements — a key's provenance, a value it read, and
231
+ * for Quereus's rebuilt statements which columns an UPDATE assigned — so a writer that lies about
232
+ * those passes here; the replay stage's guards are what catch that, at merge time.
233
+ *
234
+ * NOTE: no deployment validates at pend today (backlog
235
+ * `feat-no-deployment-validates-transactions-at-pend`), so this runs only where a validator is
236
+ * wired by hand — db-p2p's mesh specs and unit tests.
237
+ */
238
+ private async claimsLaneAboveCeiling(transaction: Transaction, engine: ITransactionEngine): Promise<boolean> {
239
+ if (transaction.lane !== 'convergent' || engine.laneCeiling === undefined) return false;
240
+ return await engine.laneCeiling(transaction) === 'serializable';
241
+ }
242
+
202
243
  async getSchemaHash(engineId: string): Promise<string | undefined> {
203
244
  const registration = this.engines.get(engineId);
204
245
  return registration ? await registration.getSchemaHash() : undefined;
@@ -56,7 +56,8 @@ export interface BlockFloorCheck {
56
56
  *
57
57
  * Raised where log entries are consumed (`Collection.updateInternal`) and checked where answers
58
58
  * arrive (`TransactorSource.tryGet`). A floor, once raised, STANDS for the life of the handle: an
59
- * answer that meets it does not remove it.
59
+ * answer that meets it does not remove it. The one thing that does is the handle adopting another
60
+ * lineage ({@link clear}).
60
61
  *
61
62
  * Why a met floor is not dropped. The source that judges an answer cannot know whether any cache
62
63
  * went on to keep it, and "an answer met the floor" is not "the cache now holds that answer": the
@@ -93,6 +94,19 @@ export class BlockFloors implements BlockFloorCheck {
93
94
  }
94
95
  }
95
96
 
97
+ /** Drop every floor. Only for a handle that has learned its floors describe a history the network
98
+ * does not hold — a refresh adopting another lineage (`Collection.forgetAndAdopt`). A floor raised
99
+ * under the old lineage says nothing about the new one, where the block may legitimately sit below
100
+ * it, and a standing floor would then make every read of the block a below-floor answer for the
101
+ * life of the handle. The exception to "a floor, once raised, stands".
102
+ *
103
+ * Every read source the handle built shares these floors, so a pinned read view created before
104
+ * the drop loses its floors too. It reads at the old boundary of the old lineage, which the
105
+ * network does not hold either, so the floors it loses bound content no machine will serve it. */
106
+ clear(): void {
107
+ this.floors.clear();
108
+ }
109
+
96
110
  applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined {
97
111
  const floor = this.floors.get(blockId);
98
112
  return floor !== undefined && (context === undefined || context.rev >= floor.rev) ? floor : undefined;