@optimystic/db-core 1.22.0 → 1.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/README.md +8 -4
  2. package/dist/src/collection/action.d.ts +7 -4
  3. package/dist/src/collection/action.d.ts.map +1 -1
  4. package/dist/src/collection/action.js +13 -5
  5. package/dist/src/collection/action.js.map +1 -1
  6. package/dist/src/collection/collection.d.ts +134 -46
  7. package/dist/src/collection/collection.d.ts.map +1 -1
  8. package/dist/src/collection/collection.js +207 -70
  9. package/dist/src/collection/collection.js.map +1 -1
  10. package/dist/src/collection/struct.d.ts +38 -8
  11. package/dist/src/collection/struct.d.ts.map +1 -1
  12. package/dist/src/collection/struct.js.map +1 -1
  13. package/dist/src/collection/write-attempts.d.ts +138 -34
  14. package/dist/src/collection/write-attempts.d.ts.map +1 -1
  15. package/dist/src/collection/write-attempts.js +168 -101
  16. package/dist/src/collection/write-attempts.js.map +1 -1
  17. package/dist/src/collections/diary/diary.d.ts.map +1 -1
  18. package/dist/src/collections/diary/diary.js +5 -1
  19. package/dist/src/collections/diary/diary.js.map +1 -1
  20. package/dist/src/collections/tree/tree.d.ts +15 -9
  21. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  22. package/dist/src/collections/tree/tree.js +6 -4
  23. package/dist/src/collections/tree/tree.js.map +1 -1
  24. package/dist/src/hlc/clock-store.d.ts +63 -0
  25. package/dist/src/hlc/clock-store.d.ts.map +1 -0
  26. package/dist/src/hlc/clock-store.js +49 -0
  27. package/dist/src/hlc/clock-store.js.map +1 -0
  28. package/dist/src/hlc/clock.d.ts +64 -0
  29. package/dist/src/hlc/clock.d.ts.map +1 -0
  30. package/dist/src/hlc/clock.js +171 -0
  31. package/dist/src/hlc/clock.js.map +1 -0
  32. package/dist/src/hlc/hlc.d.ts +38 -0
  33. package/dist/src/hlc/hlc.d.ts.map +1 -0
  34. package/dist/src/hlc/hlc.js +41 -0
  35. package/dist/src/hlc/hlc.js.map +1 -0
  36. package/dist/src/hlc/index.d.ts +5 -0
  37. package/dist/src/hlc/index.d.ts.map +1 -0
  38. package/dist/src/hlc/index.js +5 -0
  39. package/dist/src/hlc/index.js.map +1 -0
  40. package/dist/src/hlc/skew.d.ts +35 -0
  41. package/dist/src/hlc/skew.d.ts.map +1 -0
  42. package/dist/src/hlc/skew.js +35 -0
  43. package/dist/src/hlc/skew.js.map +1 -0
  44. package/dist/src/index.d.ts +2 -0
  45. package/dist/src/index.d.ts.map +1 -1
  46. package/dist/src/index.js +2 -0
  47. package/dist/src/index.js.map +1 -1
  48. package/dist/src/lane/index.d.ts +2 -0
  49. package/dist/src/lane/index.d.ts.map +1 -0
  50. package/dist/src/lane/index.js +2 -0
  51. package/dist/src/lane/index.js.map +1 -0
  52. package/dist/src/lane/lane.d.ts +46 -0
  53. package/dist/src/lane/lane.d.ts.map +1 -0
  54. package/dist/src/lane/lane.js +26 -0
  55. package/dist/src/lane/lane.js.map +1 -0
  56. package/dist/src/log/log.d.ts +50 -22
  57. package/dist/src/log/log.d.ts.map +1 -1
  58. package/dist/src/log/log.js +21 -13
  59. package/dist/src/log/log.js.map +1 -1
  60. package/dist/src/log/struct.d.ts +61 -1
  61. package/dist/src/log/struct.d.ts.map +1 -1
  62. package/dist/src/log/struct.js +24 -0
  63. package/dist/src/log/struct.js.map +1 -1
  64. package/dist/src/network/i-repo.d.ts +10 -0
  65. package/dist/src/network/i-repo.d.ts.map +1 -1
  66. package/dist/src/network/stale-failure.d.ts +20 -7
  67. package/dist/src/network/stale-failure.d.ts.map +1 -1
  68. package/dist/src/network/stale-failure.js +29 -7
  69. package/dist/src/network/stale-failure.js.map +1 -1
  70. package/dist/src/network/struct.d.ts +35 -0
  71. package/dist/src/network/struct.d.ts.map +1 -1
  72. package/dist/src/network/struct.js.map +1 -1
  73. package/dist/src/offline/entry.d.ts +14 -0
  74. package/dist/src/offline/entry.d.ts.map +1 -1
  75. package/dist/src/offline/entry.js +2 -0
  76. package/dist/src/offline/entry.js.map +1 -1
  77. package/dist/src/offline/journal.d.ts +10 -0
  78. package/dist/src/offline/journal.d.ts.map +1 -1
  79. package/dist/src/offline/queue.d.ts +10 -0
  80. package/dist/src/offline/queue.d.ts.map +1 -1
  81. package/dist/src/offline/queue.js +29 -3
  82. package/dist/src/offline/queue.js.map +1 -1
  83. package/dist/src/offline/status.d.ts +7 -0
  84. package/dist/src/offline/status.d.ts.map +1 -1
  85. package/dist/src/offline/status.js.map +1 -1
  86. package/dist/src/testing/test-transactor.d.ts +9 -1
  87. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  88. package/dist/src/testing/test-transactor.js +6 -1
  89. package/dist/src/testing/test-transactor.js.map +1 -1
  90. package/dist/src/transaction/actions-engine.d.ts +3 -0
  91. package/dist/src/transaction/actions-engine.d.ts.map +1 -1
  92. package/dist/src/transaction/actions-engine.js +3 -0
  93. package/dist/src/transaction/actions-engine.js.map +1 -1
  94. package/dist/src/transaction/coordinator.d.ts +10 -5
  95. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  96. package/dist/src/transaction/coordinator.js +197 -48
  97. package/dist/src/transaction/coordinator.js.map +1 -1
  98. package/dist/src/transaction/entry-commit.d.ts +45 -10
  99. package/dist/src/transaction/entry-commit.d.ts.map +1 -1
  100. package/dist/src/transaction/entry-commit.js +20 -7
  101. package/dist/src/transaction/entry-commit.js.map +1 -1
  102. package/dist/src/transaction/errors.d.ts +69 -1
  103. package/dist/src/transaction/errors.d.ts.map +1 -1
  104. package/dist/src/transaction/errors.js +70 -1
  105. package/dist/src/transaction/errors.js.map +1 -1
  106. package/dist/src/transaction/index.d.ts +1 -1
  107. package/dist/src/transaction/index.d.ts.map +1 -1
  108. package/dist/src/transaction/index.js +1 -1
  109. package/dist/src/transaction/index.js.map +1 -1
  110. package/dist/src/transaction/session.d.ts.map +1 -1
  111. package/dist/src/transaction/session.js +18 -5
  112. package/dist/src/transaction/session.js.map +1 -1
  113. package/dist/src/transaction/transaction.d.ts +74 -15
  114. package/dist/src/transaction/transaction.d.ts.map +1 -1
  115. package/dist/src/transaction/transaction.js +35 -15
  116. package/dist/src/transaction/transaction.js.map +1 -1
  117. package/dist/src/transaction/validator.d.ts +25 -4
  118. package/dist/src/transaction/validator.d.ts.map +1 -1
  119. package/dist/src/transaction/validator.js +45 -5
  120. package/dist/src/transaction/validator.js.map +1 -1
  121. package/dist/src/transactor/block-floors.d.ts +12 -1
  122. package/dist/src/transactor/block-floors.d.ts.map +1 -1
  123. package/dist/src/transactor/block-floors.js +14 -1
  124. package/dist/src/transactor/block-floors.js.map +1 -1
  125. package/dist/src/transactor/network-transactor.d.ts +8 -0
  126. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  127. package/dist/src/transactor/network-transactor.js +8 -4
  128. package/dist/src/transactor/network-transactor.js.map +1 -1
  129. package/dist/src/transactor/transactor-source.d.ts +11 -0
  130. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  131. package/dist/src/transactor/transactor-source.js +5 -1
  132. package/dist/src/transactor/transactor-source.js.map +1 -1
  133. package/dist/src/transactor/transactor.d.ts +8 -0
  134. package/dist/src/transactor/transactor.d.ts.map +1 -1
  135. package/dist/src/transform/cache-source.d.ts +7 -0
  136. package/dist/src/transform/cache-source.d.ts.map +1 -1
  137. package/dist/src/transform/cache-source.js +14 -18
  138. package/dist/src/transform/cache-source.js.map +1 -1
  139. package/package.json +1 -1
  140. package/src/collection/action.ts +13 -5
  141. package/src/collection/collection.ts +250 -76
  142. package/src/collection/struct.ts +38 -8
  143. package/src/collection/write-attempts.ts +213 -109
  144. package/src/collections/diary/diary.ts +5 -1
  145. package/src/collections/tree/tree.ts +18 -11
  146. package/src/hlc/clock-store.ts +68 -0
  147. package/src/hlc/clock.ts +196 -0
  148. package/src/hlc/hlc.ts +56 -0
  149. package/src/hlc/index.ts +4 -0
  150. package/src/hlc/skew.ts +55 -0
  151. package/src/index.ts +2 -0
  152. package/src/lane/index.ts +1 -0
  153. package/src/lane/lane.ts +54 -0
  154. package/src/log/log.ts +341 -310
  155. package/src/log/struct.ts +62 -1
  156. package/src/network/i-repo.ts +11 -1
  157. package/src/network/stale-failure.ts +31 -7
  158. package/src/network/struct.ts +805 -770
  159. package/src/offline/entry.ts +16 -0
  160. package/src/offline/journal.ts +10 -0
  161. package/src/offline/queue.ts +38 -4
  162. package/src/offline/status.ts +7 -0
  163. package/src/testing/test-transactor.ts +1065 -1053
  164. package/src/transaction/actions-engine.ts +3 -0
  165. package/src/transaction/coordinator.ts +229 -54
  166. package/src/transaction/entry-commit.ts +56 -14
  167. package/src/transaction/errors.ts +60 -0
  168. package/src/transaction/index.ts +1 -1
  169. package/src/transaction/session.ts +18 -5
  170. package/src/transaction/transaction.ts +90 -17
  171. package/src/transaction/validator.ts +46 -5
  172. package/src/transactor/block-floors.ts +15 -1
  173. package/src/transactor/network-transactor.ts +15 -4
  174. package/src/transactor/transactor-source.ts +15 -1
  175. package/src/transactor/transactor.ts +9 -0
  176. package/src/transform/cache-source.ts +15 -17
@@ -1,4 +1,5 @@
1
1
  import { Log } from "../log/log.js";
2
+ import { hlcOf } from "../log/struct.js";
2
3
  import { Atomic } from "../transform/atomic.js";
3
4
  import { Tracker } from "../transform/tracker.js";
4
5
  import { CacheSource } from "../transform/cache-source.js";
@@ -12,6 +13,9 @@ import { actionIdAt, addTallies, ZeroTally } from "./action.js";
12
13
  import { AttemptCycle, resumedAttempt, retainedAttempt, stageAttempt } from "./write-attempts.js";
13
14
  import { driveHeadCommit } from "./head-commit.js";
14
15
  import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
16
+ import { clockOf } from "../hlc/clock.js";
17
+ import { maxHlc } from "../hlc/hlc.js";
18
+ import { stricterLane } from "../lane/lane.js";
15
19
  import { randomBytes } from '@noble/hashes/utils.js';
16
20
  import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
17
21
  import { Latches } from "../utility/latches.js";
@@ -25,7 +29,7 @@ export class Collection {
25
29
  sourceCache;
26
30
  tracker;
27
31
  floors;
28
- filterConflict;
32
+ merge;
29
33
  onSealedRefused;
30
34
  onViewChanged;
31
35
  instanceTag;
@@ -107,7 +111,7 @@ export class Collection {
107
111
  * ({@link InFlightCycle}) — read by {@link send} and by the re-send {@link completeOwnEntry} makes
108
112
  * to finish a torn attempt, so neither needs it threaded through. Set by
109
113
  * {@link beginInFlightAction} and cleared by its disposer. */
110
- inFlightCycle = {};
114
+ inFlightCycle;
111
115
  /** The head commit running on this instance ({@link openHeadCommit}), for the whole cycle — set and
112
116
  * cleared beside {@link inFlightActionId}: the sealed segment it is committing, and the hook told
113
117
  * what that segment accepted as already applied when it is dropped as committed
@@ -139,7 +143,9 @@ export class Collection {
139
143
  /** What each block named by a walked log entry must be at least as new as — raised by
140
144
  * {@link updateInternal}, and shared with every read source this handle builds (see
141
145
  * {@link BlockFloors}). */
142
- floors, filterConflict,
146
+ floors,
147
+ /** See {@link CollectionInitOptions.merge}. */
148
+ merge,
143
149
  /** See {@link CollectionInitOptions.onSealedRefused}. */
144
150
  onSealedRefused,
145
151
  /** See {@link CollectionInitOptions.onViewChanged}. */
@@ -155,7 +161,7 @@ export class Collection {
155
161
  this.sourceCache = sourceCache;
156
162
  this.tracker = tracker;
157
163
  this.floors = floors;
158
- this.filterConflict = filterConflict;
164
+ this.merge = merge;
159
165
  this.onSealedRefused = onSealedRefused;
160
166
  this.onViewChanged = onViewChanged;
161
167
  this.instanceTag = instanceTag;
@@ -201,8 +207,8 @@ export class Collection {
201
207
  // that ignores the undefined cannot later sync a phantom collection into existence.
202
208
  return undefined;
203
209
  }
204
- await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends);
205
- const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, init.onSealedRefused, init.onViewChanged, instanceTag);
210
+ await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends, clockOf(transactor));
211
+ const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.merge, init.onSealedRefused, init.onViewChanged, instanceTag);
206
212
  collection.logTailId = ends.header.tailId;
207
213
  return collection;
208
214
  }
@@ -218,7 +224,7 @@ export class Collection {
218
224
  const { source, sourceCache, tracker, floors, ends } = await Collection.probeHeader(transactor, id, instanceTag);
219
225
  let inventedBaseline;
220
226
  if (ends) { // Collection already exists
221
- await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends);
227
+ await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends, clockOf(transactor));
222
228
  }
223
229
  else { // Collection does not exist
224
230
  log('collection:invented id=%s — no committed header found; staging a fresh empty collection', id);
@@ -231,7 +237,7 @@ export class Collection {
231
237
  // replay has to put back while this collection has no committed revision.
232
238
  inventedBaseline = copyTransforms(tracker.transforms);
233
239
  }
234
- const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, init.onSealedRefused, init.onViewChanged, instanceTag);
240
+ const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.merge, init.onSealedRefused, init.onViewChanged, instanceTag);
235
241
  collection.logTailId = ends?.header.tailId;
236
242
  collection.inventedBaseline = inventedBaseline;
237
243
  return collection;
@@ -350,11 +356,14 @@ export class Collection {
350
356
  static async attachToLog(source, sourceCache, tracker, floors, id,
351
357
  /** The tag the calling open path minted for the Collection it is ABOUT to construct, so a
352
358
  * diagnostic emitted here carries the same instance name as every post-construction one. */
353
- instanceTag, ends) {
359
+ instanceTag, ends,
360
+ /** The clock the handle's writes will mint from, which observes the tail it read. */
361
+ clock) {
354
362
  // Bootstrap ActionContext from the committed tail before walking the chain.
355
363
  // This allows the transactor to serve pending non-tail blocks during Log.open.
356
364
  Collection.bootstrapContext(source, ends.tail);
357
365
  Collection.floorTailEntries(floors, ends);
366
+ Collection.observeTailEntries(clock, ends);
358
367
  // The walk starts from the header and the tail, which the probe just read: keep them, so the
359
368
  // walk reads neither again. Its first read of each through the cache then records the read
360
369
  // dependency the probe's own read of the header used to.
@@ -392,6 +401,22 @@ export class Collection {
392
401
  }
393
402
  }
394
403
  }
404
+ /** Have `clock` observe the highest HLC among the opened log's tail block entries, which the open
405
+ * has read but does not walk — the open's half of what a refresh's walk feeds the clock
406
+ * ({@link forgetAndAdopt}), so a write through this handle never mints below a write it has seen.
407
+ * Only the tail block, which the open read anyway; an older log block would cost a read for entries
408
+ * committed earlier. Their HLCs are usually lower, but not always — an offline entry keeps the HLC
409
+ * minted at enqueue and a retry its first attempt's (the `NOTE:` at `WriteIdentity.hlc`) — so
410
+ * a write may mint below an entry in an older block, one this handle never read. */
411
+ static observeTailEntries(clock, ends) {
412
+ const tail = ends.tail?.block;
413
+ let highWater;
414
+ for (const entry of tail?.entries ?? []) {
415
+ highWater = maxHlc(highWater, hlcOf(entry));
416
+ }
417
+ if (highWater !== undefined)
418
+ clock.observe(highWater);
419
+ }
395
420
  /** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
396
421
  *
397
422
  * The revision a collection last committed at is knowledge it earned; a read that found
@@ -418,23 +443,20 @@ export class Collection {
418
443
  * tag, two handles' lines interleave into what reads like one handle contradicting itself.
419
444
  *
420
445
  * Logs, does not throw — same reasoning as {@link reportShortfall}: `update()` runs
421
- * blanket-style over every registered collection between commit retries, and aborting here
422
- * would promote a diagnosis to production behaviour before the line has ever been seen to
423
- * fire in the wild. Adoption then proceeds unchanged, which means the line is a PER-DISCOVERY
424
- * report, not a per-refresh one: adopting `next` overwrites the held lineage marker with the
425
- * log's, so the next refresh of this instance compares log-to-log and stays silent — even
426
- * though block content materialized under the old lineage may still be in caches. The line
427
- * marks the refresh that first observed the disagreement.
428
- *
429
- * NOTE: adoption resolves the CONTEXT disagreement, not the content one — the read caches on
430
- * this instance still hold blocks materialized under the old lineage, and since the revision
431
- * did not change nothing re-reads them. Conditional today: no fork has been reproduced (see
432
- * the still-open upstream reproducer), so this instrument exists to find out whether one
433
- * happens at all. If the line is ever seen firing in the field, decide then whether a
434
- * divergence should also drop the read cache (and whether to keep re-reporting per refresh)
435
- * — that is a behaviour change, and this seam deliberately makes none.
436
- *
437
- * The comparison is {@link earliestFork}, not a single lookup at the current revision: the
446
+ * blanket-style over every registered collection between commit retries. Whether the read is
447
+ * adopted, and whether it is another lineage, is {@link judgeAdoption}'s call, made before this
448
+ * runs so a refresh can act on it first: a refresh that ADOPTS another lineage drops its whole
449
+ * read cache and its floors and re-stages every staged action ({@link forgetAndAdopt},
450
+ * {@link mustReplay}), since everything it cached and computed was computed against a history the
451
+ * network does not hold; an open has no cache to drop and nothing staged. The line is therefore a
452
+ * PER-DISCOVERY report: adopting `next` overwrites the held lineage marker with the log's, the
453
+ * drop leaves the handle consistent with the log, and the next refresh compares log to log and
454
+ * has nothing to report. A REFUSED read leaves the held marker in place, so a fork sealed by a
455
+ * `collection:context-not-lowered` refusal is reported on every refresh, beside that line, with
456
+ * nothing dropped — bringing such a handle onto the network's lineage is reconciliation, backlog
457
+ * `feat-replay-mode-collections-merge-divergent-histories`.
458
+ *
459
+ * The comparison printed is {@link earliestFork}, not a single lookup at the current revision: the
438
460
  * two `committed` lists overlap across several revisions, and the LOWEST one they disagree at
439
461
  * is where the lineages actually parted — a fork below the current revision was previously
440
462
  * silent. `forkRev=` names it, `heldAction=`/`readAction=` are the two ids AT it, and
@@ -451,14 +473,17 @@ export class Collection {
451
473
  * the NOTE in {@link bootstrapContext}), which is exactly the case {@link earliestFork} has no
452
474
  * shared revision to report on.
453
475
  *
454
- * Gated on `log.enabled`, like every {@link actionIdAt} caller: the comparison buys nothing
455
- * when the line has no sink, and the lists — one entry per commit between context reads,
456
- * truncated at each checkpoint — are only walked on a run that has the namespace turned on.
476
+ * The two printed comparisons are gated on `log.enabled`: they buy nothing when the line has no
477
+ * sink. Nothing the handle DOES is: the adoption and the lineage verdict behind it
478
+ * ({@link judgeAdoption}) run whatever the logging.
457
479
  * Silence proves nothing either way, because a revision is only comparable when BOTH sides
458
480
  * name an action for it: an invented collection has no context at all, a revision slot the log
459
481
  * gave to a checkpoint or invalidation entry names none, and a revision older than the read
460
- * log's most recent checkpoint has already fallen off the read side's list. */
461
- static advanceContext(source, id, instanceTag, site, next) {
482
+ * log's most recent checkpoint has already fallen off the read side's list.
483
+ *
484
+ * @param adoption what adopting `next` does, as {@link judgeAdoption} answers it for the context
485
+ * `source` holds now — passed in by a caller that had to act on it before calling. */
486
+ static advanceContext(source, id, instanceTag, site, next, adoption = Collection.judgeAdoption(source.actionContext, next)) {
462
487
  const current = source.actionContext;
463
488
  if (next === undefined) {
464
489
  return; // The read learned nothing — keep what we already know.
@@ -469,15 +494,47 @@ export class Collection {
469
494
  log('collection:lineage-divergence id=%s tag=%s site=%s forkRev=%d heldAction=%s readAction=%s heldRev=%d readRev=%d', id, instanceTag, site, fork.rev, fork.heldAction, fork.readAction, current.rev, next.rev);
470
495
  }
471
496
  }
472
- if (current !== undefined && next.rev < current.rev) {
497
+ if (adoption === 'refuse') {
473
498
  // The refusal itself is unconditional; only the id lookups that explain it are gated.
474
- if (log.enabled) {
499
+ if (current !== undefined && log.enabled) {
475
500
  log('collection:context-not-lowered id=%s tag=%s site=%s heldRev=%d readRev=%d heldAction=%s readAction=%s', id, instanceTag, site, current.rev, next.rev, actionIdAt(current, next.rev) ?? 'none', actionIdAt(next, next.rev) ?? 'none');
476
501
  }
477
502
  return;
478
503
  }
479
504
  source.actionContext = next;
480
505
  }
506
+ /** Whether a read context `next` is adopted over the `held` one, and whether it is another
507
+ * lineage ({@link Adoption}). Runs whatever the logging, because the answer is behaviour.
508
+ *
509
+ * Another lineage means the two name different actions at the HELD revision. One comparison is
510
+ * enough because an action id is unique per commit: two lineages that parted at or below the held
511
+ * revision name different actions at every revision both have reached since, the held one
512
+ * included. The exception, one action landing on both sides (a writer's torn retry), is the same
513
+ * lineage at that revision, which is the right answer. A side naming no action there is missing
514
+ * evidence, not disagreement, as in {@link earliestFork} — the held revision's slot went to an
515
+ * invalidation or checkpoint entry, or it predates the read side's most recent checkpoint — so a
516
+ * fork visible only below such a slot is not acted on (the line may still report it). A refused
517
+ * read names no action at the held revision, being below it, so `adopt-divergent` never comes
518
+ * with a refusal.
519
+ *
520
+ * NOTE: two {@link actionIdAt} scans per refresh that walks the log, never per read. Each searches
521
+ * from the end: the held side's entry is normally its last, and the read side's is as far back as
522
+ * the entries the walk found. Both lists truncate only at a checkpoint, which nothing writes yet
523
+ * (tickets/backlog/debt-the-collection-log-never-writes-a-checkpoint); if they grow long enough
524
+ * for that to show, index them by revision. */
525
+ static judgeAdoption(held, next) {
526
+ if (next === undefined || (held !== undefined && next.rev < held.rev)) {
527
+ return 'refuse';
528
+ }
529
+ if (held === undefined) {
530
+ return 'adopt';
531
+ }
532
+ const heldAction = actionIdAt(held, held.rev);
533
+ const readAction = actionIdAt(next, held.rev);
534
+ return heldAction !== undefined && readAction !== undefined && heldAction !== readAction
535
+ ? 'adopt-divergent'
536
+ : 'adopt';
537
+ }
481
538
  /** The EARLIEST revision the two contexts provably disagree about: the lowest revision both
482
539
  * `committed` lists name an action for, where the two ids differ.
483
540
  *
@@ -624,10 +681,8 @@ export class Collection {
624
681
  * ask for another (see {@link completeOwnEntry}).
625
682
  *
626
683
  * `tailFloor` is optional: a revision a responder confirmed is taken, when the caller has one (see
627
- * {@link updateInternal}). `TransactionCoordinator.commit` has none to pass today — its commit loop
628
- * does not see the confirmed revision (backlog:
629
- * debt-multi-collection-retry-cannot-see-the-taken-revision) — and this is the parameter it will
630
- * pass it through. */
684
+ * {@link updateInternal}). `TransactionCoordinator.commit` passes the highest one its refusals of
685
+ * THIS collection carried (`RetryBudget.tailFloor`), and nothing for a collection none did. */
631
686
  async refreshInFlight(report, lastChance, tailFloor) {
632
687
  const release = await Latches.acquire(this.latchId);
633
688
  try {
@@ -722,10 +777,19 @@ export class Collection {
722
777
  // pair is not obviously right either: a member re-executing the transaction after a sibling
723
778
  // participant has landed no longer sees the state it was staged against. Tracked as an arm
724
779
  // of tickets/backlog/feat-no-deployment-validates-transactions-at-pend.
780
+ // NOTE: the re-send carries no pend-level `hlc` either: the retained attempt holds the write's
781
+ // HLC only inside the log entry in its transforms, and the ActionEntry the refresh hands this
782
+ // method does not carry it. A member that missed the first pend and stores this re-send
783
+ // therefore observes the write's HLC when it next reads the entry, not at the pend. Fine while
784
+ // the HLC is observational; if a feed point at the pend ever becomes load-bearing, retain the
785
+ // HLC on `InFlightAttempt` beside the transforms and put it on this request. The write's LANE
786
+ // does ride here, from the in-flight cycle (`InFlightCycle.lane`), which every write path marks
787
+ // with the lane it minted: the same value the retained entry carries.
725
788
  const result = await this.source.transact(attempt.transforms, entry.actionId, rev, this.id, attempt.tailId, {
726
789
  blockDigests: attempt.blockDigests,
727
790
  baseRevs: attempt.baseRevs,
728
- refuseSolo: this.inFlightCycle.refuseSolo
791
+ lane: this.inFlightCycle?.lane,
792
+ refuseSolo: this.inFlightCycle?.refuseSolo
729
793
  });
730
794
  if (result.success) {
731
795
  return result.durability;
@@ -935,8 +999,11 @@ export class Collection {
935
999
  * replace => new instance.
936
1000
  *
937
1001
  * A SEALED segment's action list is the queue entry's own and is never rewritten (invariant 3
938
- * of docs/offline-sync.md §The segment model), so the hook is not offered them. `Tree` and
939
- * `Diary` install no hook, so nothing observable changes for them either way.
1002
+ * of docs/offline-sync.md §The segment model), so the hook is not offered them. The hook is the
1003
+ * convergent lane's rule ({@link ConvergentMerge.filterConflict}): {@link doFilterConflict} offers
1004
+ * it only an action the declaration classifies `convergent`, and keeps a serializable one as-is.
1005
+ * `Tree` declares nothing and `Diary` declares no hook, so nothing observable changes for them
1006
+ * either way.
940
1007
  *
941
1008
  * NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead of
942
1009
  * returning the same one forces a replay on every update — if that ever shows up as a hot path,
@@ -1085,11 +1152,11 @@ export class Collection {
1085
1152
  if (invalidations.length > 0 && this.segments.replayableCount() > 0) {
1086
1153
  anyConflicts = true;
1087
1154
  }
1088
- this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
1155
+ const adoption = this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
1089
1156
  Collection.reportShortfall(this.id, this.instanceTag, tailRev, actionContext?.rev, this.source.actionContext?.rev);
1090
1157
  // Re-stage the staged actions against the adopted revision. The affected
1091
- // blocks were already dropped from sourceCache above (per log entry / per invalidation),
1092
- // so the replay's reads re-materialize from the transactor.
1158
+ // blocks were already dropped from sourceCache above (per log entry / per invalidation, or
1159
+ // all of them on an adopted divergence), so the replay's reads re-materialize from the transactor.
1093
1160
  // NOTE: a throw out of replayActions — a refusal of the OPEN segment, or any non-refusal
1094
1161
  // error — leaves the tracker holding only the transforms replayed so far while the open
1095
1162
  // segment still lists all of its actions; the caller's error handling is expected to
@@ -1098,7 +1165,7 @@ export class Collection {
1098
1165
  // collection-half-restaged). A SEALED segment is not left half-replayed: it is staged
1099
1166
  // atomically, and a refusal of one is recorded and skipped rather than thrown. If replay ever
1100
1167
  // gains a routinely-throwing read path, rebuild into a scratch tracker and swap on success.
1101
- if (this.mustReplay(anyConflicts, actionContext)) {
1168
+ if (this.mustReplay(anyConflicts, actionContext, adoption)) {
1102
1169
  await this.replayActions();
1103
1170
  }
1104
1171
  }
@@ -1124,16 +1191,42 @@ export class Collection {
1124
1191
  * context at all, and a log read that lags what this handle already committed yields an older
1125
1192
  * one; neither is grounds for forgetting the revision held. It also has to precede
1126
1193
  * {@link replayActions}, which re-reads blocks through `this.source` at whatever revision the
1127
- * context names — replaying first would refill the cache at the revision being left. */
1194
+ * context names — replaying first would refill the cache at the revision being left.
1195
+ *
1196
+ * **An adopted divergence forgets everything first** ({@link judgeAdoption}): the whole read cache
1197
+ * and every floor, ahead of the per-entry loop so this walk's floors — the new lineage's — are the
1198
+ * ones left standing. Not just the blocks the walked entries name: the walk covers only entries
1199
+ * above the held revision, so the blocks the old lineage built at and below it are named by
1200
+ * entries this handle will never walk, the cache has no expiry, and an idle refresh stops after
1201
+ * one request while the log does not move — nothing would ever clear them. And not the floors
1202
+ * kept: a floor raised under the old lineage is no bound on the new one, where the block may
1203
+ * legitimately sit below it, and would make every read of it a below-floor answer for the life of
1204
+ * the handle. The header and tail {@link keepLogEnds} offers came from the new lineage and may be
1205
+ * kept. The staged actions were computed against the old content, so the verdict is returned for
1206
+ * {@link mustReplay}.
1207
+ *
1208
+ * The handle's clock observes the highest HLC the walk read (`GetFromResult.hlcHighWater`), so a
1209
+ * write through it never mints below an entry it has seen — whatever the verdict, since a clock
1210
+ * only rises and the entries were read either way.
1211
+ *
1212
+ * @returns what the adoption did, as {@link judgeAdoption} answered it before anything changed. */
1128
1213
  forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends) {
1214
+ const adoption = Collection.judgeAdoption(this.source.actionContext, latest?.context);
1215
+ if (latest?.hlcHighWater !== undefined)
1216
+ clockOf(this.transactor).observe(latest.hlcHighWater);
1129
1217
  this.viewChanged();
1218
+ if (adoption === 'adopt-divergent') {
1219
+ this.sourceCache.clear();
1220
+ this.floors.clear();
1221
+ }
1130
1222
  for (const entry of latest?.entries ?? []) {
1131
1223
  this.sourceCache.clear(entry.blockIds);
1132
1224
  this.raiseFloors(entry, entryRevs.get(entry.actionId));
1133
1225
  }
1134
1226
  this.sourceCache.clear(revertedBlockIds);
1135
- Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context);
1227
+ Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context, adoption);
1136
1228
  Collection.keepLogEnds(this.sourceCache, this.floors, this.source.actionContext, ends);
1229
+ return adoption;
1137
1230
  }
1138
1231
  /** Put the header and log tail block {@link readLogEnds} already fetched into a handle's own
1139
1232
  * cache, so the next read of either is a hit rather than a second fetch of a block just
@@ -1274,7 +1367,8 @@ export class Collection {
1274
1367
  * claim (`collection:context-short-of-tail`, or `collection:context-not-lowered` for a handle
1275
1368
  * pinned by an over-claiming tail), or an invalidation or checkpoint took the newest slot;
1276
1369
  * - any action entry in the tail block naming a different action than `held` names at the same
1277
- * revision (`collection:lineage-divergence`, and the walk's adoption of the log's list).
1370
+ * revision (`collection:lineage-divergence`, and the walk's adoption of the log's list, which
1371
+ * drops the read cache when it adopts another lineage — see {@link forgetAndAdopt}).
1278
1372
  *
1279
1373
  * NOTE: the lineage comparison sees only the entries the tail block holds. A fork below them, on
1280
1374
  * a log that has not moved, is not looked at again until a refresh finds something new — that
@@ -1336,8 +1430,10 @@ export class Collection {
1336
1430
  * (`index-backfill-cost.spec.ts`, `cold-apply-cost.spec.ts`), because the replay's reads are
1337
1431
  * served from `sourceCache`. If a long transaction's reads ever show up as slow, narrow the
1338
1432
  * replay to the actions whose reads the adopted entries actually invalidated — NOT back to
1339
- * conflicts alone, which is the defect above. */
1340
- mustReplay(anyConflicts, priorContext) {
1433
+ * conflicts alone, which is the defect above.
1434
+ *
1435
+ * @param adoption what the refresh's adoption did ({@link forgetAndAdopt}). */
1436
+ mustReplay(anyConflicts, priorContext, adoption) {
1341
1437
  if (anyConflicts) {
1342
1438
  return true;
1343
1439
  }
@@ -1346,6 +1442,14 @@ export class Collection {
1346
1442
  if (adoptedRev !== undefined && adoptedRev !== priorContext?.rev && replayable > 0) {
1347
1443
  return true;
1348
1444
  }
1445
+ // Fourth reason, ahead of the third: the refresh adopted another lineage, so every staged
1446
+ // action was computed against content the network does not hold. A fork at the SAME revision
1447
+ // advances nothing, so the reason above does not see it. The whole-cache clear behind it
1448
+ // would usually make every pinned base read as moved too, but this keeps the rule readable,
1449
+ // covers staged actions that pinned nothing, and spares a `restage-moved-base` line per pin.
1450
+ if (adoption === 'adopt-divergent' && replayable > 0) {
1451
+ return true;
1452
+ }
1349
1453
  // Third reason: a staged block's base has MOVED — the read cache no longer describes it at
1350
1454
  // the revision its operations were computed against (see `Tracker.movedBases`). A refresh
1351
1455
  // that adopted nothing and found no conflict can still be standing over such a block: a
@@ -1919,7 +2023,7 @@ export class Collection {
1919
2023
  *
1920
2024
  * `cycle` is what every send of the cycle carries ({@link InFlightCycle}); a re-mark replaces it,
1921
2025
  * which is harmless because every caller re-marks with what it marked. */
1922
- beginInFlightAction(actionId, cycle = {}) {
2026
+ beginInFlightAction(actionId, cycle) {
1923
2027
  if (this.inFlightActionId !== actionId) {
1924
2028
  // A different action's failed attempt cannot finish this one. Re-marking the SAME id (a
1925
2029
  // coordinator re-marks on every attempt) keeps what the previous attempt retained — that
@@ -1935,7 +2039,7 @@ export class Collection {
1935
2039
  this.inFlightActionId = undefined;
1936
2040
  this.inFlightAttempt = undefined;
1937
2041
  this.mintedLogBlockIds = undefined;
1938
- this.inFlightCycle = {};
2042
+ this.inFlightCycle = undefined;
1939
2043
  }
1940
2044
  };
1941
2045
  }
@@ -2037,12 +2141,21 @@ export class Collection {
2037
2141
  this.assertNoSealedSegments();
2038
2142
  const identity = {
2039
2143
  actionId: uint8ArrayToString(randomBytes(16), 'base64url'),
2040
- // One timestamp for the WRITE, minted here beside the action id and for the same reason: an
2041
- // attempt that takes its own would make the retry's log block differ from the one the
2042
- // attempt it repeats may already have stored under this `(action id, revision)`.
2144
+ // One timestamp, one HLC and one lane for the WRITE, minted here beside the action id and for
2145
+ // the same reason: an attempt that took its own would make the retry's log block differ from
2146
+ // the one the attempt it repeats may already have stored under this `(action id, revision)`.
2043
2147
  timestamp: Date.now(),
2148
+ hlc: clockOf(this.transactor).now(),
2149
+ // The caller's classification wins over the declaration, and the declaration over nothing
2150
+ // (`SyncOptions.lane`): the caller knows more about the write than the collection does.
2151
+ // NOTE: judged over the open segment as staged NOW and fixed for the write; a
2152
+ // `merge.filterConflict` hook that answered a replacement of a different lane during an
2153
+ // inter-attempt refresh would leave the entry claiming the lane of the action it replaced. No
2154
+ // hook in this repository replaces an action; if one ever does, the member-side lane check is
2155
+ // what catches the mismatch.
2156
+ lane: options?.lane ?? this.laneOf(this.segments.open),
2044
2157
  };
2045
- const endInFlight = this.beginInFlightAction(identity.actionId, { refuseSolo: options?.refuseSoloCommit });
2158
+ const endInFlight = this.beginInFlightAction(identity.actionId, { lane: identity.lane, refuseSolo: options?.refuseSoloCommit });
2046
2159
  try {
2047
2160
  return await this.syncAttempts(identity, options);
2048
2161
  }
@@ -2114,9 +2227,11 @@ export class Collection {
2114
2227
  send(staged, identity, priority) {
2115
2228
  return this.source.transact(staged.tracker.transforms, identity.actionId, staged.rev, this.id, staged.tailId, {
2116
2229
  priority,
2230
+ hlc: identity.hlc,
2231
+ lane: identity.lane,
2117
2232
  blockDigests: staged.blockDigests,
2118
2233
  baseRevs: staged.baseRevs,
2119
- refuseSolo: this.inFlightCycle.refuseSolo
2234
+ refuseSolo: this.inFlightCycle?.refuseSolo
2120
2235
  });
2121
2236
  }
2122
2237
  /** Fold a committed attempt's transforms — the log append included — into this instance's read
@@ -2158,7 +2273,7 @@ export class Collection {
2158
2273
  * when a refresh or the head tracker's staging refused it during the cycle; whatever
2159
2274
  * `options.recordAttempt` throws, before anything is sent; otherwise what {@link sync} throws. */
2160
2275
  async commitHead(entryId, options) {
2161
- const handle = await this.openHeadCommit(entryId, { actionId: options.actionId, timestamp: options.timestamp }, {
2276
+ const handle = await this.openHeadCommit(entryId, { actionId: options.actionId, timestamp: options.timestamp, hlc: options.hlc, lane: options.lane }, {
2162
2277
  refuseSolo: options.refuseSoloCommit,
2163
2278
  ...(options.resume === undefined ? {} : { resume: options.resume }),
2164
2279
  ...(options.onCommittedHead === undefined ? {} : { onCommittedHead: options.onCommittedHead }),
@@ -2181,9 +2296,9 @@ export class Collection {
2181
2296
  * segment; and seeds the retained attempt with `options.resume` when one is given, so that the
2182
2297
  * opening refresh can finish an earlier cycle's torn attempt from it ({@link completeOwnEntry}) —
2183
2298
  * and `stage()` re-sends it verbatim while the next attempt would request its revision
2184
- * ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}), recorded
2185
- * with the in-flight mark, so the handle's `send()` and a refresh's re-send of a torn attempt both
2186
- * carry it.
2299
+ * ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}, its lane
2300
+ * taken from `identity`), recorded with the in-flight mark, so the handle's `send()` and a
2301
+ * refresh's re-send of a torn attempt both carry it.
2187
2302
  *
2188
2303
  * **The target.** The live tracker holds every sealed segment and the open one, cumulatively, so
2189
2304
  * an attempt cannot run on a copy of it the way a sync's does. It runs on a HEAD TRACKER instead
@@ -2234,7 +2349,7 @@ export class Collection {
2234
2349
  release();
2235
2350
  throw err;
2236
2351
  }
2237
- const endInFlight = this.beginInFlightAction(identity.actionId, cycle);
2352
+ const endInFlight = this.beginInFlightAction(identity.actionId, { ...cycle, lane: identity.lane });
2238
2353
  this.headCommit = { entryId, ...(onCommittedHead === undefined ? {} : { onCommitted: onCommittedHead }) };
2239
2354
  if (resume !== undefined) {
2240
2355
  this.retainInFlightAttempt(resume);
@@ -2377,21 +2492,27 @@ export class Collection {
2377
2492
  /** The tracker a head attempt is built from (see {@link commitHead}): `current`, while it was
2378
2493
  * built for the revision the next attempt requests and no base under it has moved; otherwise a
2379
2494
  * fresh one ({@link buildHeadTracker}). A revision that moved is a write that is genuinely
2380
- * different. A base that moved at the same revision is re-judged exactly as
2381
- * {@link restageIfBasesMoved} re-judges the live queue before an attempt, and rebuilds.
2495
+ * different, and so is one whose held lineage moved at the same revision: a refresh between
2496
+ * attempts that adopted another lineage ({@link judgeAdoption}) dropped the read cache the
2497
+ * tracker was staged over, and an action that inserted a block computed from that content pinned
2498
+ * no base the re-judge below would see as moved. A base that moved at the same revision is
2499
+ * re-judged exactly as {@link restageIfBasesMoved} re-judges the live queue before an attempt,
2500
+ * and rebuilds.
2382
2501
  * NOTE: that rebuild is the same exception to the byte-identical retry that {@link syncAttempts}
2383
2502
  * records at its `restageIfBasesMoved` call — fresh ids for the blocks the actions insert under
2384
2503
  * an unchanged `(action id, revision)` — reached the same narrow way and refused by storage's
2385
2504
  * base guard on the same machines; the same answer applies if it is ever seen. */
2386
2505
  async headTrackerFor(segment, current) {
2387
2506
  const rev = this.getNextRev();
2388
- if (current?.rev === rev) {
2507
+ const held = this.source.actionContext;
2508
+ const lineage = held === undefined ? undefined : actionIdAt(held, held.rev);
2509
+ if (current?.rev === rev && current.lineage === lineage) {
2389
2510
  await this.rereadUnretainedBases(current.tracker);
2390
2511
  if (this.logMovedBases(current.tracker.movedBases()) === 0) {
2391
2512
  return current;
2392
2513
  }
2393
2514
  }
2394
- return { rev, tracker: await this.buildHeadTracker(segment) };
2515
+ return { rev, lineage, tracker: await this.buildHeadTracker(segment) };
2395
2516
  }
2396
2517
  /** A tracker over this instance's read cache, with pins of its own, holding `segment`'s actions
2397
2518
  * staged atomically over the committed state — from the invented baseline while this collection
@@ -2468,10 +2589,10 @@ export class Collection {
2468
2589
  * refresh would have done. */
2469
2590
  async unstage(actions, stagedBefore, revBefore) {
2470
2591
  // NOTE: matched by identity, which is what `filterAgainstEntry` promises for a kept action.
2471
- // A `filterConflict` hook that answers a REPLACEMENT instance for one of these actions would
2472
- // leave the replacement staged here. No collection installs such a hook today (`Tree` and
2473
- // `Diary` install none); if one ever does, carry a per-call token on the staged actions and
2474
- // match on that instead.
2592
+ // A `merge.filterConflict` hook that answers a REPLACEMENT instance for one of these actions
2593
+ // would leave the replacement staged here. No collection installs such a hook today (`Tree`
2594
+ // declares no merge and `Diary` declares no hook); if one ever does, carry a per-call token on
2595
+ // the staged actions and match on that instead.
2475
2596
  // The actions were staged into the OPEN segment (actAndSync refuses over sealed segments).
2476
2597
  this.segments.open = this.segments.open.filter(staged => !actions.includes(staged));
2477
2598
  if (this.source.actionContext?.rev === revBefore) {
@@ -2568,14 +2689,30 @@ export class Collection {
2568
2689
  clearReadDependencies() {
2569
2690
  this.source.clearReadDependencies();
2570
2691
  }
2692
+ /** The lane of a write made of `actions` under this collection's merge declaration
2693
+ * ({@link CollectionInitOptions.merge}): the stricter lane over the declaration's answer for each
2694
+ * (`stricterLane`), `serializable` without a declaration and for an empty list. Pure. The source
2695
+ * of a sync's lane when its caller gave none (`SyncOptions.lane`), and of a queued entry's
2696
+ * (`OfflineQueue.enqueue`). */
2697
+ laneOf(actions) {
2698
+ const merge = this.merge;
2699
+ return merge === undefined ? 'serializable' : stricterLane(actions.map(action => merge.laneOf(action)));
2700
+ }
2571
2701
  /** Called for each local action that may be in conflict with a remote action (always called under latch).
2702
+ * The merge declaration's hook ({@link ConvergentMerge.filterConflict}) decides only for an action the
2703
+ * declaration classifies `convergent`; a serializable action is kept as-is, since its guards decide
2704
+ * on replay, and so is every action of a collection with no declaration or no hook.
2572
2705
  * @param action - The local action to check
2573
2706
  * @param potential - The remote actions that are potentially in conflict
2574
2707
  * @returns The effective action to keep: the original (unchanged), a replacement
2575
2708
  * instance (applied instead of the original), or undefined to discard it.
2576
2709
  */
2577
2710
  doFilterConflict(action, potential) {
2578
- return this.filterConflict ? this.filterConflict(action, potential) : action;
2711
+ const merge = this.merge;
2712
+ if (merge?.filterConflict === undefined || merge.laneOf(action) !== 'convergent') {
2713
+ return action;
2714
+ }
2715
+ return merge.filterConflict(action, potential);
2579
2716
  }
2580
2717
  /** The two blocks every refresh starts from — the collection header and the log tail block it
2581
2718
  * names — read unpinned ("latest"), in ONE request when `knownTailId` is the tail the header