@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,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,8 +29,9 @@ export class Collection {
25
29
  sourceCache;
26
30
  tracker;
27
31
  floors;
28
- filterConflict;
32
+ merge;
29
33
  onSealedRefused;
34
+ onViewChanged;
30
35
  instanceTag;
31
36
  /** The staged actions: sealed segments, one per queued entry, ahead of the open segment the
32
37
  * current transaction stages into (see {@link SegmentList}). While nothing is sealed this is
@@ -106,7 +111,7 @@ export class Collection {
106
111
  * ({@link InFlightCycle}) — read by {@link send} and by the re-send {@link completeOwnEntry} makes
107
112
  * to finish a torn attempt, so neither needs it threaded through. Set by
108
113
  * {@link beginInFlightAction} and cleared by its disposer. */
109
- inFlightCycle = {};
114
+ inFlightCycle;
110
115
  /** The head commit running on this instance ({@link openHeadCommit}), for the whole cycle — set and
111
116
  * cleared beside {@link inFlightActionId}: the sealed segment it is committing, and the hook told
112
117
  * what that segment accepted as already applied when it is dropped as committed
@@ -138,9 +143,13 @@ export class Collection {
138
143
  /** What each block named by a walked log entry must be at least as new as — raised by
139
144
  * {@link updateInternal}, and shared with every read source this handle builds (see
140
145
  * {@link BlockFloors}). */
141
- floors, filterConflict,
146
+ floors,
147
+ /** See {@link CollectionInitOptions.merge}. */
148
+ merge,
142
149
  /** See {@link CollectionInitOptions.onSealedRefused}. */
143
150
  onSealedRefused,
151
+ /** See {@link CollectionInitOptions.onViewChanged}. */
152
+ onViewChanged,
144
153
  /** Short random tag naming THIS instance (see {@link newInstanceTag}). Open paths generate
145
154
  * it BEFORE construction (so pre-construction diagnostics such as attachToLog can carry it);
146
155
  * the default covers direct construction in tests. */
@@ -152,8 +161,9 @@ export class Collection {
152
161
  this.sourceCache = sourceCache;
153
162
  this.tracker = tracker;
154
163
  this.floors = floors;
155
- this.filterConflict = filterConflict;
164
+ this.merge = merge;
156
165
  this.onSealedRefused = onSealedRefused;
166
+ this.onViewChanged = onViewChanged;
157
167
  this.instanceTag = instanceTag;
158
168
  // Instance-scoped, deliberately NOT shared across instances of one collection id. The
159
169
  // latch protects per-instance state only — the tracker, the pending queue, and
@@ -197,8 +207,8 @@ export class Collection {
197
207
  // that ignores the undefined cannot later sync a phantom collection into existence.
198
208
  return undefined;
199
209
  }
200
- await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends);
201
- const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, init.onSealedRefused, 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);
202
212
  collection.logTailId = ends.header.tailId;
203
213
  return collection;
204
214
  }
@@ -214,7 +224,7 @@ export class Collection {
214
224
  const { source, sourceCache, tracker, floors, ends } = await Collection.probeHeader(transactor, id, instanceTag);
215
225
  let inventedBaseline;
216
226
  if (ends) { // Collection already exists
217
- await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends);
227
+ await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends, clockOf(transactor));
218
228
  }
219
229
  else { // Collection does not exist
220
230
  log('collection:invented id=%s — no committed header found; staging a fresh empty collection', id);
@@ -227,7 +237,7 @@ export class Collection {
227
237
  // replay has to put back while this collection has no committed revision.
228
238
  inventedBaseline = copyTransforms(tracker.transforms);
229
239
  }
230
- const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, init.onSealedRefused, instanceTag);
240
+ const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.merge, init.onSealedRefused, init.onViewChanged, instanceTag);
231
241
  collection.logTailId = ends?.header.tailId;
232
242
  collection.inventedBaseline = inventedBaseline;
233
243
  return collection;
@@ -264,10 +274,14 @@ export class Collection {
264
274
  * coordinator's answer leaves a block out — is not every collection's failure either:
265
275
  * {@link readAttributed} then reads each block alone and only the collections whose blocks failed
266
276
  * report an error. That fallback costs what reading each collection separately costs, and only
267
- * when a request fails. */
268
- static async readCommittedTails(transactor, queries) {
277
+ * when a request fails.
278
+ *
279
+ * `options.skipWindowConsult` puts {@link BlockGets.skipWindowConsult} on every request this read
280
+ * makes, the per-block fallback included. */
281
+ static async readCommittedTails(transactor, queries, options) {
282
+ const reads = Collection.tailReadFields(options);
269
283
  const knownTails = new Map(queries.map(query => [query.id, query.knownTailId]));
270
- const ends = await Collection.readAttributed(transactor, [...knownTails].flatMap(([id, knownTailId]) => knownTailId === undefined ? [id] : [id, knownTailId]));
284
+ const ends = await Collection.readAttributed(transactor, [...knownTails].flatMap(([id, knownTailId]) => knownTailId === undefined ? [id] : [id, knownTailId]), reads);
271
285
  const answers = new Map();
272
286
  /** Collections whose header names a tail other than the known one, with the tail it names. */
273
287
  const moved = new Map();
@@ -286,7 +300,7 @@ export class Collection {
286
300
  }
287
301
  }
288
302
  if (moved.size > 0) {
289
- const tails = await Collection.readAttributed(transactor, [...new Set(moved.values())]);
303
+ const tails = await Collection.readAttributed(transactor, [...new Set(moved.values())], reads);
290
304
  for (const [id, tailId] of moved) {
291
305
  try {
292
306
  answers.set(id, { tail: Collection.judgedTail(tailId, tails) });
@@ -342,11 +356,14 @@ export class Collection {
342
356
  static async attachToLog(source, sourceCache, tracker, floors, id,
343
357
  /** The tag the calling open path minted for the Collection it is ABOUT to construct, so a
344
358
  * diagnostic emitted here carries the same instance name as every post-construction one. */
345
- instanceTag, ends) {
359
+ instanceTag, ends,
360
+ /** The clock the handle's writes will mint from, which observes the tail it read. */
361
+ clock) {
346
362
  // Bootstrap ActionContext from the committed tail before walking the chain.
347
363
  // This allows the transactor to serve pending non-tail blocks during Log.open.
348
364
  Collection.bootstrapContext(source, ends.tail);
349
365
  Collection.floorTailEntries(floors, ends);
366
+ Collection.observeTailEntries(clock, ends);
350
367
  // The walk starts from the header and the tail, which the probe just read: keep them, so the
351
368
  // walk reads neither again. Its first read of each through the cache then records the read
352
369
  // dependency the probe's own read of the header used to.
@@ -384,6 +401,22 @@ export class Collection {
384
401
  }
385
402
  }
386
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
+ }
387
420
  /** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
388
421
  *
389
422
  * The revision a collection last committed at is knowledge it earned; a read that found
@@ -410,23 +443,20 @@ export class Collection {
410
443
  * tag, two handles' lines interleave into what reads like one handle contradicting itself.
411
444
  *
412
445
  * Logs, does not throw — same reasoning as {@link reportShortfall}: `update()` runs
413
- * blanket-style over every registered collection between commit retries, and aborting here
414
- * would promote a diagnosis to production behaviour before the line has ever been seen to
415
- * fire in the wild. Adoption then proceeds unchanged, which means the line is a PER-DISCOVERY
416
- * report, not a per-refresh one: adopting `next` overwrites the held lineage marker with the
417
- * log's, so the next refresh of this instance compares log-to-log and stays silent — even
418
- * though block content materialized under the old lineage may still be in caches. The line
419
- * marks the refresh that first observed the disagreement.
420
- *
421
- * NOTE: adoption resolves the CONTEXT disagreement, not the content one — the read caches on
422
- * this instance still hold blocks materialized under the old lineage, and since the revision
423
- * did not change nothing re-reads them. Conditional today: no fork has been reproduced (see
424
- * the still-open upstream reproducer), so this instrument exists to find out whether one
425
- * happens at all. If the line is ever seen firing in the field, decide then whether a
426
- * divergence should also drop the read cache (and whether to keep re-reporting per refresh)
427
- * — that is a behaviour change, and this seam deliberately makes none.
428
- *
429
- * 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
430
460
  * two `committed` lists overlap across several revisions, and the LOWEST one they disagree at
431
461
  * is where the lineages actually parted — a fork below the current revision was previously
432
462
  * silent. `forkRev=` names it, `heldAction=`/`readAction=` are the two ids AT it, and
@@ -443,14 +473,17 @@ export class Collection {
443
473
  * the NOTE in {@link bootstrapContext}), which is exactly the case {@link earliestFork} has no
444
474
  * shared revision to report on.
445
475
  *
446
- * Gated on `log.enabled`, like every {@link actionIdAt} caller: the comparison buys nothing
447
- * when the line has no sink, and the lists — one entry per commit between context reads,
448
- * 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.
449
479
  * Silence proves nothing either way, because a revision is only comparable when BOTH sides
450
480
  * name an action for it: an invented collection has no context at all, a revision slot the log
451
481
  * gave to a checkpoint or invalidation entry names none, and a revision older than the read
452
- * log's most recent checkpoint has already fallen off the read side's list. */
453
- 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)) {
454
487
  const current = source.actionContext;
455
488
  if (next === undefined) {
456
489
  return; // The read learned nothing — keep what we already know.
@@ -461,15 +494,47 @@ export class Collection {
461
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);
462
495
  }
463
496
  }
464
- if (current !== undefined && next.rev < current.rev) {
497
+ if (adoption === 'refuse') {
465
498
  // The refusal itself is unconditional; only the id lookups that explain it are gated.
466
- if (log.enabled) {
499
+ if (current !== undefined && log.enabled) {
467
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');
468
501
  }
469
502
  return;
470
503
  }
471
504
  source.actionContext = next;
472
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
+ }
473
538
  /** The EARLIEST revision the two contexts provably disagree about: the lowest revision both
474
539
  * `committed` lists name an action for, where the two ids differ.
475
540
  *
@@ -555,7 +620,9 @@ export class Collection {
555
620
  }
556
621
  /** Run `actions` through their handlers over `tracker` as ONE atomic unit: a throw from any
557
622
  * handler leaves none of their writes staged. The live tracker's path ({@link internalTransact})
558
- * and a head commit's tracker ({@link buildHeadTracker}) share it.
623
+ * and a head commit's tracker ({@link buildHeadTracker}) share it. Only the live tracker's
624
+ * commit changes what this collection's reads see ({@link viewChanged}); a head commit's tracker
625
+ * is private to the commit.
559
626
  *
560
627
  * @returns the sum of what the handlers accepted as already applied ({@link AlreadyAppliedTally});
561
628
  * a handler that answers nothing adds the zero tally. */
@@ -572,9 +639,24 @@ export class Collection {
572
639
  applied = addTallies(applied, tally);
573
640
  }
574
641
  }
642
+ if (tracker === this.tracker) {
643
+ this.viewChanged();
644
+ }
575
645
  atomic.commit();
576
646
  return applied;
577
647
  }
648
+ /** Tell {@link CollectionInitOptions.onViewChanged} that what this collection's reads see is
649
+ * about to change. Every caller calls it in the same synchronous step as the change itself — no
650
+ * `await` between them — which is what lets a reader trust "the counter did not move" as "nothing
651
+ * I read changed". */
652
+ viewChanged() {
653
+ try {
654
+ this.onViewChanged?.();
655
+ }
656
+ catch (err) {
657
+ log('collection:view-changed-callback-threw id=%s tag=%s error=%s', this.id, this.instanceTag, err instanceof Error ? err.message : String(err));
658
+ }
659
+ }
578
660
  /** Load external changes and update our context to the latest log revision - resolve any conflicts with our pending actions. */
579
661
  async update() {
580
662
  const release = await Latches.acquire(this.latchId);
@@ -599,10 +681,8 @@ export class Collection {
599
681
  * ask for another (see {@link completeOwnEntry}).
600
682
  *
601
683
  * `tailFloor` is optional: a revision a responder confirmed is taken, when the caller has one (see
602
- * {@link updateInternal}). `TransactionCoordinator.commit` has none to pass today — its commit loop
603
- * does not see the confirmed revision (backlog:
604
- * debt-multi-collection-retry-cannot-see-the-taken-revision) — and this is the parameter it will
605
- * 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. */
606
686
  async refreshInFlight(report, lastChance, tailFloor) {
607
687
  const release = await Latches.acquire(this.latchId);
608
688
  try {
@@ -697,10 +777,19 @@ export class Collection {
697
777
  // pair is not obviously right either: a member re-executing the transaction after a sibling
698
778
  // participant has landed no longer sees the state it was staged against. Tracked as an arm
699
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.
700
788
  const result = await this.source.transact(attempt.transforms, entry.actionId, rev, this.id, attempt.tailId, {
701
789
  blockDigests: attempt.blockDigests,
702
790
  baseRevs: attempt.baseRevs,
703
- refuseSolo: this.inFlightCycle.refuseSolo
791
+ lane: this.inFlightCycle?.lane,
792
+ refuseSolo: this.inFlightCycle?.refuseSolo
704
793
  });
705
794
  if (result.success) {
706
795
  return result.durability;
@@ -910,8 +999,11 @@ export class Collection {
910
999
  * replace => new instance.
911
1000
  *
912
1001
  * A SEALED segment's action list is the queue entry's own and is never rewritten (invariant 3
913
- * of docs/offline-sync.md §The segment model), so the hook is not offered them. `Tree` and
914
- * `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.
915
1007
  *
916
1008
  * NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead of
917
1009
  * returning the same one forces a replay on every update — if that ever shows up as a hot path,
@@ -1060,11 +1152,11 @@ export class Collection {
1060
1152
  if (invalidations.length > 0 && this.segments.replayableCount() > 0) {
1061
1153
  anyConflicts = true;
1062
1154
  }
1063
- this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
1155
+ const adoption = this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
1064
1156
  Collection.reportShortfall(this.id, this.instanceTag, tailRev, actionContext?.rev, this.source.actionContext?.rev);
1065
1157
  // Re-stage the staged actions against the adopted revision. The affected
1066
- // blocks were already dropped from sourceCache above (per log entry / per invalidation),
1067
- // 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.
1068
1160
  // NOTE: a throw out of replayActions — a refusal of the OPEN segment, or any non-refusal
1069
1161
  // error — leaves the tracker holding only the transforms replayed so far while the open
1070
1162
  // segment still lists all of its actions; the caller's error handling is expected to
@@ -1073,7 +1165,7 @@ export class Collection {
1073
1165
  // collection-half-restaged). A SEALED segment is not left half-replayed: it is staged
1074
1166
  // atomically, and a refusal of one is recorded and skipped rather than thrown. If replay ever
1075
1167
  // gains a routinely-throwing read path, rebuild into a scratch tracker and swap on success.
1076
- if (this.mustReplay(anyConflicts, actionContext)) {
1168
+ if (this.mustReplay(anyConflicts, actionContext, adoption)) {
1077
1169
  await this.replayActions();
1078
1170
  }
1079
1171
  }
@@ -1090,21 +1182,51 @@ export class Collection {
1090
1182
  * and the adopting, a concurrent read either lands before both and is forgotten with the rest,
1091
1183
  * or lands after both and is judged at the adopted revision — against the floor
1092
1184
  * ({@link TransactorSource.tryGet} reads its context when the answer arrives, not when it was
1093
- * asked for) and against the generation the clear moved (`CacheSource.stillWanted`).
1185
+ * asked for) and against the generation the clear moved (`CacheSource.stillWanted`). That keeps
1186
+ * each single read sound; a reader part-way through SEVERAL reads — a tree descent — can still hold
1187
+ * blocks of the revision being left while it reads the rest at the adopted one, so it is told
1188
+ * through {@link viewChanged}.
1094
1189
  *
1095
1190
  * The advance is monotonic (see {@link advanceContext}): an empty or unopenable log yields no
1096
1191
  * context at all, and a log read that lags what this handle already committed yields an older
1097
1192
  * one; neither is grounds for forgetting the revision held. It also has to precede
1098
1193
  * {@link replayActions}, which re-reads blocks through `this.source` at whatever revision the
1099
- * 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. */
1100
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);
1217
+ this.viewChanged();
1218
+ if (adoption === 'adopt-divergent') {
1219
+ this.sourceCache.clear();
1220
+ this.floors.clear();
1221
+ }
1101
1222
  for (const entry of latest?.entries ?? []) {
1102
1223
  this.sourceCache.clear(entry.blockIds);
1103
1224
  this.raiseFloors(entry, entryRevs.get(entry.actionId));
1104
1225
  }
1105
1226
  this.sourceCache.clear(revertedBlockIds);
1106
- Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context);
1227
+ Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context, adoption);
1107
1228
  Collection.keepLogEnds(this.sourceCache, this.floors, this.source.actionContext, ends);
1229
+ return adoption;
1108
1230
  }
1109
1231
  /** Put the header and log tail block {@link readLogEnds} already fetched into a handle's own
1110
1232
  * cache, so the next read of either is a hit rather than a second fetch of a block just
@@ -1245,7 +1367,8 @@ export class Collection {
1245
1367
  * claim (`collection:context-short-of-tail`, or `collection:context-not-lowered` for a handle
1246
1368
  * pinned by an over-claiming tail), or an invalidation or checkpoint took the newest slot;
1247
1369
  * - any action entry in the tail block naming a different action than `held` names at the same
1248
- * 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}).
1249
1372
  *
1250
1373
  * NOTE: the lineage comparison sees only the entries the tail block holds. A fork below them, on
1251
1374
  * a log that has not moved, is not looked at again until a refresh finds something new — that
@@ -1307,8 +1430,10 @@ export class Collection {
1307
1430
  * (`index-backfill-cost.spec.ts`, `cold-apply-cost.spec.ts`), because the replay's reads are
1308
1431
  * served from `sourceCache`. If a long transaction's reads ever show up as slow, narrow the
1309
1432
  * replay to the actions whose reads the adopted entries actually invalidated — NOT back to
1310
- * conflicts alone, which is the defect above. */
1311
- 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) {
1312
1437
  if (anyConflicts) {
1313
1438
  return true;
1314
1439
  }
@@ -1317,6 +1442,14 @@ export class Collection {
1317
1442
  if (adoptedRev !== undefined && adoptedRev !== priorContext?.rev && replayable > 0) {
1318
1443
  return true;
1319
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
+ }
1320
1453
  // Third reason: a staged block's base has MOVED — the read cache no longer describes it at
1321
1454
  // the revision its operations were computed against (see `Tracker.movedBases`). A refresh
1322
1455
  // that adopted nothing and found no conflict can still be standing over such a block: a
@@ -1469,6 +1602,7 @@ export class Collection {
1469
1602
  await this.replayActions();
1470
1603
  return;
1471
1604
  }
1605
+ this.viewChanged();
1472
1606
  if (boundaryMoved && snapshot.pending.length === 0) {
1473
1607
  this.tracker.reset();
1474
1608
  this.segments.open = [];
@@ -1801,9 +1935,14 @@ export class Collection {
1801
1935
  * revision because {@link update} sees its rev is already current and refetches
1802
1936
  * nothing. Call BEFORE resetting the tracker (the transforms are read live).
1803
1937
  *
1938
+ * Tells {@link viewChanged} for the fold AND for the tracker reset that follows it, so the
1939
+ * caller must reset in the same synchronous step, with no `await` between the two — every
1940
+ * coordinator site does.
1941
+ *
1804
1942
  * @param revision - the committed revision these transforms land at (from
1805
1943
  * {@link recordCommitted}), so cached read-dependency revisions advance to it. */
1806
1944
  applyCommittedToCache(transforms, revision) {
1945
+ this.viewChanged();
1807
1946
  this.sourceCache.transformCache(transforms, revision);
1808
1947
  }
1809
1948
  /** Next revision this collection would commit at (current committed rev + 1). */
@@ -1884,7 +2023,7 @@ export class Collection {
1884
2023
  *
1885
2024
  * `cycle` is what every send of the cycle carries ({@link InFlightCycle}); a re-mark replaces it,
1886
2025
  * which is harmless because every caller re-marks with what it marked. */
1887
- beginInFlightAction(actionId, cycle = {}) {
2026
+ beginInFlightAction(actionId, cycle) {
1888
2027
  if (this.inFlightActionId !== actionId) {
1889
2028
  // A different action's failed attempt cannot finish this one. Re-marking the SAME id (a
1890
2029
  // coordinator re-marks on every attempt) keeps what the previous attempt retained — that
@@ -1900,7 +2039,7 @@ export class Collection {
1900
2039
  this.inFlightActionId = undefined;
1901
2040
  this.inFlightAttempt = undefined;
1902
2041
  this.mintedLogBlockIds = undefined;
1903
- this.inFlightCycle = {};
2042
+ this.inFlightCycle = undefined;
1904
2043
  }
1905
2044
  };
1906
2045
  }
@@ -2002,12 +2141,21 @@ export class Collection {
2002
2141
  this.assertNoSealedSegments();
2003
2142
  const identity = {
2004
2143
  actionId: uint8ArrayToString(randomBytes(16), 'base64url'),
2005
- // One timestamp for the WRITE, minted here beside the action id and for the same reason: an
2006
- // attempt that takes its own would make the retry's log block differ from the one the
2007
- // 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)`.
2008
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),
2009
2157
  };
2010
- const endInFlight = this.beginInFlightAction(identity.actionId, { refuseSolo: options?.refuseSoloCommit });
2158
+ const endInFlight = this.beginInFlightAction(identity.actionId, { lane: identity.lane, refuseSolo: options?.refuseSoloCommit });
2011
2159
  try {
2012
2160
  return await this.syncAttempts(identity, options);
2013
2161
  }
@@ -2079,9 +2227,11 @@ export class Collection {
2079
2227
  send(staged, identity, priority) {
2080
2228
  return this.source.transact(staged.tracker.transforms, identity.actionId, staged.rev, this.id, staged.tailId, {
2081
2229
  priority,
2230
+ hlc: identity.hlc,
2231
+ lane: identity.lane,
2082
2232
  blockDigests: staged.blockDigests,
2083
2233
  baseRevs: staged.baseRevs,
2084
- refuseSolo: this.inFlightCycle.refuseSolo
2234
+ refuseSolo: this.inFlightCycle?.refuseSolo
2085
2235
  });
2086
2236
  }
2087
2237
  /** Fold a committed attempt's transforms — the log append included — into this instance's read
@@ -2089,6 +2239,7 @@ export class Collection {
2089
2239
  * still staged (see the note in {@link syncAttempts}). Takes the transforms out of the attempt's
2090
2240
  * tracker, which is finished with. */
2091
2241
  foldOwnCommit(staged, actionId) {
2242
+ this.viewChanged();
2092
2243
  this.sourceCache.transformCache(staged.tracker.reset(), staged.rev);
2093
2244
  this.recordCommitted(actionId, staged.rev);
2094
2245
  }
@@ -2122,7 +2273,7 @@ export class Collection {
2122
2273
  * when a refresh or the head tracker's staging refused it during the cycle; whatever
2123
2274
  * `options.recordAttempt` throws, before anything is sent; otherwise what {@link sync} throws. */
2124
2275
  async commitHead(entryId, options) {
2125
- 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 }, {
2126
2277
  refuseSolo: options.refuseSoloCommit,
2127
2278
  ...(options.resume === undefined ? {} : { resume: options.resume }),
2128
2279
  ...(options.onCommittedHead === undefined ? {} : { onCommittedHead: options.onCommittedHead }),
@@ -2145,9 +2296,9 @@ export class Collection {
2145
2296
  * segment; and seeds the retained attempt with `options.resume` when one is given, so that the
2146
2297
  * opening refresh can finish an earlier cycle's torn attempt from it ({@link completeOwnEntry}) —
2147
2298
  * and `stage()` re-sends it verbatim while the next attempt would request its revision
2148
- * ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}), recorded
2149
- * with the in-flight mark, so the handle's `send()` and a refresh's re-send of a torn attempt both
2150
- * 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.
2151
2302
  *
2152
2303
  * **The target.** The live tracker holds every sealed segment and the open one, cumulatively, so
2153
2304
  * an attempt cannot run on a copy of it the way a sync's does. It runs on a HEAD TRACKER instead
@@ -2198,7 +2349,7 @@ export class Collection {
2198
2349
  release();
2199
2350
  throw err;
2200
2351
  }
2201
- const endInFlight = this.beginInFlightAction(identity.actionId, cycle);
2352
+ const endInFlight = this.beginInFlightAction(identity.actionId, { ...cycle, lane: identity.lane });
2202
2353
  this.headCommit = { entryId, ...(onCommittedHead === undefined ? {} : { onCommitted: onCommittedHead }) };
2203
2354
  if (resume !== undefined) {
2204
2355
  this.retainInFlightAttempt(resume);
@@ -2341,21 +2492,27 @@ export class Collection {
2341
2492
  /** The tracker a head attempt is built from (see {@link commitHead}): `current`, while it was
2342
2493
  * built for the revision the next attempt requests and no base under it has moved; otherwise a
2343
2494
  * fresh one ({@link buildHeadTracker}). A revision that moved is a write that is genuinely
2344
- * different. A base that moved at the same revision is re-judged exactly as
2345
- * {@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.
2346
2501
  * NOTE: that rebuild is the same exception to the byte-identical retry that {@link syncAttempts}
2347
2502
  * records at its `restageIfBasesMoved` call — fresh ids for the blocks the actions insert under
2348
2503
  * an unchanged `(action id, revision)` — reached the same narrow way and refused by storage's
2349
2504
  * base guard on the same machines; the same answer applies if it is ever seen. */
2350
2505
  async headTrackerFor(segment, current) {
2351
2506
  const rev = this.getNextRev();
2352
- 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) {
2353
2510
  await this.rereadUnretainedBases(current.tracker);
2354
2511
  if (this.logMovedBases(current.tracker.movedBases()) === 0) {
2355
2512
  return current;
2356
2513
  }
2357
2514
  }
2358
- return { rev, tracker: await this.buildHeadTracker(segment) };
2515
+ return { rev, lineage, tracker: await this.buildHeadTracker(segment) };
2359
2516
  }
2360
2517
  /** A tracker over this instance's read cache, with pins of its own, holding `segment`'s actions
2361
2518
  * staged atomically over the committed state — from the invented baseline while this collection
@@ -2432,13 +2589,14 @@ export class Collection {
2432
2589
  * refresh would have done. */
2433
2590
  async unstage(actions, stagedBefore, revBefore) {
2434
2591
  // NOTE: matched by identity, which is what `filterAgainstEntry` promises for a kept action.
2435
- // A `filterConflict` hook that answers a REPLACEMENT instance for one of these actions would
2436
- // leave the replacement staged here. No collection installs such a hook today (`Tree` and
2437
- // `Diary` install none); if one ever does, carry a per-call token on the staged actions and
2438
- // 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.
2439
2596
  // The actions were staged into the OPEN segment (actAndSync refuses over sealed segments).
2440
2597
  this.segments.open = this.segments.open.filter(staged => !actions.includes(staged));
2441
2598
  if (this.source.actionContext?.rev === revBefore) {
2599
+ this.viewChanged();
2442
2600
  this.tracker.reset(stagedBefore);
2443
2601
  }
2444
2602
  else {
@@ -2476,10 +2634,16 @@ export class Collection {
2476
2634
  * sealed segment that staged records what its actions accepted as already applied
2477
2635
  * (`SealedSegment.applied`), the tally the head commit reports when the segment is committed.
2478
2636
  *
2637
+ * A replay changes the tree beneath unlatched readers twice over: the reset drops every block a
2638
+ * staged action inserted, and the re-staging inserts them again under fresh ids. Both are told
2639
+ * through {@link viewChanged} — the reset here, each re-staged unit in {@link stageInto} — so a
2640
+ * reader part-way through a descent knows to read again rather than follow an id that is gone.
2641
+ *
2479
2642
  * @param unreported - a segment whose refusal is recorded but NOT reported through
2480
2643
  * `onSealedRefused`: the one {@link restoreSealed} is inserting, whose caller reads the recorded
2481
2644
  * refusal off the segment itself. */
2482
2645
  async replayActions(unreported) {
2646
+ this.viewChanged();
2483
2647
  this.tracker.reset(this.replayBaseline());
2484
2648
  for (const segment of this.segments.replayable()) {
2485
2649
  try {
@@ -2525,14 +2689,30 @@ export class Collection {
2525
2689
  clearReadDependencies() {
2526
2690
  this.source.clearReadDependencies();
2527
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
+ }
2528
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.
2529
2705
  * @param action - The local action to check
2530
2706
  * @param potential - The remote actions that are potentially in conflict
2531
2707
  * @returns The effective action to keep: the original (unchanged), a replacement
2532
2708
  * instance (applied instead of the original), or undefined to discard it.
2533
2709
  */
2534
2710
  doFilterConflict(action, potential) {
2535
- 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);
2536
2716
  }
2537
2717
  /** The two blocks every refresh starts from — the collection header and the log tail block it
2538
2718
  * names — read unpinned ("latest"), in ONE request when `knownTailId` is the tail the header
@@ -2621,12 +2801,12 @@ export class Collection {
2621
2801
  * NOTE: the fallback is unbounded — two gets per collection at once, only after a failed
2622
2802
  * request. Fine for the tens of tables a host watches; if callers ever name hundreds, read the
2623
2803
  * fallback in bounded batches. */
2624
- static async readAttributed(transactor, blockIds) {
2804
+ static async readAttributed(transactor, blockIds, reads) {
2625
2805
  if (blockIds.length === 0) {
2626
2806
  return new Map();
2627
2807
  }
2628
2808
  try {
2629
- const results = await transactor.get({ blockIds });
2809
+ const results = await transactor.get({ blockIds, ...reads });
2630
2810
  return new Map(blockIds.map(id => [id, { entry: results?.[id] }]));
2631
2811
  }
2632
2812
  catch (error) {
@@ -2634,17 +2814,21 @@ export class Collection {
2634
2814
  return new Map([[blockIds[0], { error }]]);
2635
2815
  }
2636
2816
  log('collection:tails-read-split blocks=%d error=%o', blockIds.length, error);
2637
- return new Map(await Promise.all(blockIds.map(async (id) => [id, await Collection.readAlone(transactor, id)])));
2817
+ return new Map(await Promise.all(blockIds.map(async (id) => [id, await Collection.readAlone(transactor, id, reads)])));
2638
2818
  }
2639
2819
  }
2640
- static async readAlone(transactor, id) {
2820
+ static async readAlone(transactor, id, reads) {
2641
2821
  try {
2642
- return { entry: (await transactor.get({ blockIds: [id] }))?.[id] };
2822
+ return { entry: (await transactor.get({ blockIds: [id], ...reads }))?.[id] };
2643
2823
  }
2644
2824
  catch (error) {
2645
2825
  return { error };
2646
2826
  }
2647
2827
  }
2828
+ /** The `BlockGets` fields every request of a {@link readCommittedTails} carries. */
2829
+ static tailReadFields(options) {
2830
+ return options?.skipWindowConsult ? { skipWindowConsult: true } : {};
2831
+ }
2648
2832
  /** An unpinned read of the log tail block, checked as {@link checkedLogTail} describes, carrying
2649
2833
  * `tailFloor` when the caller has one (see {@link readLogEnds}). */
2650
2834
  static async readLogTail(transactor, tailId, tailFloor) {