@optimystic/db-core 1.22.0 → 1.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/README.md +8 -4
  2. package/dist/src/collection/action.d.ts +7 -4
  3. package/dist/src/collection/action.d.ts.map +1 -1
  4. package/dist/src/collection/action.js +13 -5
  5. package/dist/src/collection/action.js.map +1 -1
  6. package/dist/src/collection/collection.d.ts +134 -46
  7. package/dist/src/collection/collection.d.ts.map +1 -1
  8. package/dist/src/collection/collection.js +207 -70
  9. package/dist/src/collection/collection.js.map +1 -1
  10. package/dist/src/collection/struct.d.ts +38 -8
  11. package/dist/src/collection/struct.d.ts.map +1 -1
  12. package/dist/src/collection/struct.js.map +1 -1
  13. package/dist/src/collection/write-attempts.d.ts +138 -34
  14. package/dist/src/collection/write-attempts.d.ts.map +1 -1
  15. package/dist/src/collection/write-attempts.js +168 -101
  16. package/dist/src/collection/write-attempts.js.map +1 -1
  17. package/dist/src/collections/diary/diary.d.ts.map +1 -1
  18. package/dist/src/collections/diary/diary.js +5 -1
  19. package/dist/src/collections/diary/diary.js.map +1 -1
  20. package/dist/src/collections/tree/tree.d.ts +15 -9
  21. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  22. package/dist/src/collections/tree/tree.js +6 -4
  23. package/dist/src/collections/tree/tree.js.map +1 -1
  24. package/dist/src/hlc/clock-store.d.ts +63 -0
  25. package/dist/src/hlc/clock-store.d.ts.map +1 -0
  26. package/dist/src/hlc/clock-store.js +49 -0
  27. package/dist/src/hlc/clock-store.js.map +1 -0
  28. package/dist/src/hlc/clock.d.ts +64 -0
  29. package/dist/src/hlc/clock.d.ts.map +1 -0
  30. package/dist/src/hlc/clock.js +171 -0
  31. package/dist/src/hlc/clock.js.map +1 -0
  32. package/dist/src/hlc/hlc.d.ts +38 -0
  33. package/dist/src/hlc/hlc.d.ts.map +1 -0
  34. package/dist/src/hlc/hlc.js +41 -0
  35. package/dist/src/hlc/hlc.js.map +1 -0
  36. package/dist/src/hlc/index.d.ts +5 -0
  37. package/dist/src/hlc/index.d.ts.map +1 -0
  38. package/dist/src/hlc/index.js +5 -0
  39. package/dist/src/hlc/index.js.map +1 -0
  40. package/dist/src/hlc/skew.d.ts +35 -0
  41. package/dist/src/hlc/skew.d.ts.map +1 -0
  42. package/dist/src/hlc/skew.js +35 -0
  43. package/dist/src/hlc/skew.js.map +1 -0
  44. package/dist/src/index.d.ts +2 -0
  45. package/dist/src/index.d.ts.map +1 -1
  46. package/dist/src/index.js +2 -0
  47. package/dist/src/index.js.map +1 -1
  48. package/dist/src/lane/index.d.ts +2 -0
  49. package/dist/src/lane/index.d.ts.map +1 -0
  50. package/dist/src/lane/index.js +2 -0
  51. package/dist/src/lane/index.js.map +1 -0
  52. package/dist/src/lane/lane.d.ts +46 -0
  53. package/dist/src/lane/lane.d.ts.map +1 -0
  54. package/dist/src/lane/lane.js +26 -0
  55. package/dist/src/lane/lane.js.map +1 -0
  56. package/dist/src/log/log.d.ts +50 -22
  57. package/dist/src/log/log.d.ts.map +1 -1
  58. package/dist/src/log/log.js +21 -13
  59. package/dist/src/log/log.js.map +1 -1
  60. package/dist/src/log/struct.d.ts +61 -1
  61. package/dist/src/log/struct.d.ts.map +1 -1
  62. package/dist/src/log/struct.js +24 -0
  63. package/dist/src/log/struct.js.map +1 -1
  64. package/dist/src/network/i-repo.d.ts +10 -0
  65. package/dist/src/network/i-repo.d.ts.map +1 -1
  66. package/dist/src/network/stale-failure.d.ts +20 -7
  67. package/dist/src/network/stale-failure.d.ts.map +1 -1
  68. package/dist/src/network/stale-failure.js +29 -7
  69. package/dist/src/network/stale-failure.js.map +1 -1
  70. package/dist/src/network/struct.d.ts +35 -0
  71. package/dist/src/network/struct.d.ts.map +1 -1
  72. package/dist/src/network/struct.js.map +1 -1
  73. package/dist/src/offline/entry.d.ts +14 -0
  74. package/dist/src/offline/entry.d.ts.map +1 -1
  75. package/dist/src/offline/entry.js +2 -0
  76. package/dist/src/offline/entry.js.map +1 -1
  77. package/dist/src/offline/journal.d.ts +10 -0
  78. package/dist/src/offline/journal.d.ts.map +1 -1
  79. package/dist/src/offline/queue.d.ts +10 -0
  80. package/dist/src/offline/queue.d.ts.map +1 -1
  81. package/dist/src/offline/queue.js +29 -3
  82. package/dist/src/offline/queue.js.map +1 -1
  83. package/dist/src/offline/status.d.ts +7 -0
  84. package/dist/src/offline/status.d.ts.map +1 -1
  85. package/dist/src/offline/status.js.map +1 -1
  86. package/dist/src/testing/test-transactor.d.ts +9 -1
  87. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  88. package/dist/src/testing/test-transactor.js +6 -1
  89. package/dist/src/testing/test-transactor.js.map +1 -1
  90. package/dist/src/transaction/actions-engine.d.ts +3 -0
  91. package/dist/src/transaction/actions-engine.d.ts.map +1 -1
  92. package/dist/src/transaction/actions-engine.js +3 -0
  93. package/dist/src/transaction/actions-engine.js.map +1 -1
  94. package/dist/src/transaction/coordinator.d.ts +10 -5
  95. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  96. package/dist/src/transaction/coordinator.js +197 -48
  97. package/dist/src/transaction/coordinator.js.map +1 -1
  98. package/dist/src/transaction/entry-commit.d.ts +45 -10
  99. package/dist/src/transaction/entry-commit.d.ts.map +1 -1
  100. package/dist/src/transaction/entry-commit.js +20 -7
  101. package/dist/src/transaction/entry-commit.js.map +1 -1
  102. package/dist/src/transaction/errors.d.ts +69 -1
  103. package/dist/src/transaction/errors.d.ts.map +1 -1
  104. package/dist/src/transaction/errors.js +70 -1
  105. package/dist/src/transaction/errors.js.map +1 -1
  106. package/dist/src/transaction/index.d.ts +1 -1
  107. package/dist/src/transaction/index.d.ts.map +1 -1
  108. package/dist/src/transaction/index.js +1 -1
  109. package/dist/src/transaction/index.js.map +1 -1
  110. package/dist/src/transaction/session.d.ts.map +1 -1
  111. package/dist/src/transaction/session.js +18 -5
  112. package/dist/src/transaction/session.js.map +1 -1
  113. package/dist/src/transaction/transaction.d.ts +74 -15
  114. package/dist/src/transaction/transaction.d.ts.map +1 -1
  115. package/dist/src/transaction/transaction.js +35 -15
  116. package/dist/src/transaction/transaction.js.map +1 -1
  117. package/dist/src/transaction/validator.d.ts +25 -4
  118. package/dist/src/transaction/validator.d.ts.map +1 -1
  119. package/dist/src/transaction/validator.js +45 -5
  120. package/dist/src/transaction/validator.js.map +1 -1
  121. package/dist/src/transactor/block-floors.d.ts +12 -1
  122. package/dist/src/transactor/block-floors.d.ts.map +1 -1
  123. package/dist/src/transactor/block-floors.js +14 -1
  124. package/dist/src/transactor/block-floors.js.map +1 -1
  125. package/dist/src/transactor/network-transactor.d.ts +8 -0
  126. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  127. package/dist/src/transactor/network-transactor.js +8 -4
  128. package/dist/src/transactor/network-transactor.js.map +1 -1
  129. package/dist/src/transactor/transactor-source.d.ts +11 -0
  130. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  131. package/dist/src/transactor/transactor-source.js +5 -1
  132. package/dist/src/transactor/transactor-source.js.map +1 -1
  133. package/dist/src/transactor/transactor.d.ts +8 -0
  134. package/dist/src/transactor/transactor.d.ts.map +1 -1
  135. package/dist/src/transform/cache-source.d.ts +7 -0
  136. package/dist/src/transform/cache-source.d.ts.map +1 -1
  137. package/dist/src/transform/cache-source.js +14 -18
  138. package/dist/src/transform/cache-source.js.map +1 -1
  139. package/package.json +1 -1
  140. package/src/collection/action.ts +13 -5
  141. package/src/collection/collection.ts +250 -76
  142. package/src/collection/struct.ts +38 -8
  143. package/src/collection/write-attempts.ts +213 -109
  144. package/src/collections/diary/diary.ts +5 -1
  145. package/src/collections/tree/tree.ts +18 -11
  146. package/src/hlc/clock-store.ts +68 -0
  147. package/src/hlc/clock.ts +196 -0
  148. package/src/hlc/hlc.ts +56 -0
  149. package/src/hlc/index.ts +4 -0
  150. package/src/hlc/skew.ts +55 -0
  151. package/src/index.ts +2 -0
  152. package/src/lane/index.ts +1 -0
  153. package/src/lane/lane.ts +54 -0
  154. package/src/log/log.ts +341 -310
  155. package/src/log/struct.ts +62 -1
  156. package/src/network/i-repo.ts +11 -1
  157. package/src/network/stale-failure.ts +31 -7
  158. package/src/network/struct.ts +805 -770
  159. package/src/offline/entry.ts +16 -0
  160. package/src/offline/journal.ts +10 -0
  161. package/src/offline/queue.ts +38 -4
  162. package/src/offline/status.ts +7 -0
  163. package/src/testing/test-transactor.ts +1065 -1053
  164. package/src/transaction/actions-engine.ts +3 -0
  165. package/src/transaction/coordinator.ts +229 -54
  166. package/src/transaction/entry-commit.ts +56 -14
  167. package/src/transaction/errors.ts +60 -0
  168. package/src/transaction/index.ts +1 -1
  169. package/src/transaction/session.ts +18 -5
  170. package/src/transaction/transaction.ts +90 -17
  171. package/src/transaction/validator.ts +46 -5
  172. package/src/transactor/block-floors.ts +15 -1
  173. package/src/transactor/network-transactor.ts +15 -4
  174. package/src/transactor/transactor-source.ts +15 -1
  175. package/src/transactor/transactor.ts +9 -0
  176. package/src/transform/cache-source.ts +15 -17
@@ -2,6 +2,7 @@ import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, B
2
2
  import { Log } from "../log/log.js";
3
3
  import type { LogBlock } from "../log/log.js";
4
4
  import type { ActionEntry, GetFromResult, LogEntry } from "../log/struct.js";
5
+ import { hlcOf } from "../log/struct.js";
5
6
  import { Atomic } from "../transform/atomic.js";
6
7
  import { Tracker } from "../transform/tracker.js";
7
8
  import type { BasePins } from "../transform/base-pins.js";
@@ -24,6 +25,9 @@ import { driveHeadCommit } from "./head-commit.js";
24
25
  import type { HeadCommitHandle } from "./head-commit.js";
25
26
  import type { ReadDependency } from "../transaction/transaction.js";
26
27
  import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
28
+ import { clockOf, type HlcClock } from "../hlc/clock.js";
29
+ import { maxHlc, type Hlc } from "../hlc/hlc.js";
30
+ import { stricterLane, type Lane } from "../lane/lane.js";
27
31
  import { randomBytes } from '@noble/hashes/utils.js';
28
32
  import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
29
33
  import { Latches } from "../utility/latches.js";
@@ -52,6 +56,18 @@ type DivergenceSite = 'refresh' | 'attach';
52
56
  * as `forkRev=` / `heldAction=` / `readAction=`. */
53
57
  type LineageFork = { rev: number, heldAction: ActionId, readAction: ActionId };
54
58
 
59
+ /** What adopting a freshly-read context does to the one a handle holds — {@link Collection.judgeAdoption}'s
60
+ * answer, decided before anything changes because an adopted divergence has to clear the read cache
61
+ * and the floors before the refresh's walk raises the new lineage's floors.
62
+ *
63
+ * - `refuse` — the read is not adopted: it learned nothing, or it is older than the held revision
64
+ * (`collection:context-not-lowered`).
65
+ * - `adopt` — the read is adopted, and names the same action as the held context at the held
66
+ * revision, or one side names none there.
67
+ * - `adopt-divergent` — the read is adopted, and names a different action at the held revision: the
68
+ * handle has been reading another lineage than the one the network holds. */
69
+ type Adoption = 'refuse' | 'adopt' | 'adopt-divergent';
70
+
55
71
  /** What one refresh ({@link Collection.refreshInFlight}, and the refresh inside a sync) found out
56
72
  * about the write in flight on the instance's behalf. The caller hands in an empty report and the
57
73
  * refresh fills it in AS IT GOES, rather than returning it at the end, so a refresh that throws
@@ -90,27 +106,51 @@ type AttributedReads = Map<BlockId, AttributedRead>;
90
106
  type TailReadFields = Pick<BlockGets, 'skipWindowConsult'>;
91
107
 
92
108
  /** The tracker a head commit's attempts are built from: the head segment's actions staged over the
93
- * committed state, and the revision the attempt built from it requests (see
109
+ * committed state, the revision the attempt built from it requests, and the lineage it was staged
110
+ * over — the action the held context named at its own revision, `undefined` when none (see
94
111
  * {@link Collection.headTrackerFor}). */
95
112
  type HeadTracker = {
96
113
  rev: number;
114
+ lineage: ActionId | undefined;
97
115
  tracker: Tracker<IBlock>;
98
116
  };
99
117
 
118
+ /**
119
+ * The convergent lane's conflict rule for a collection (`Lane` in `packages/db-core/src/lane/lane.ts`):
120
+ * which of its actions may be committed by one machine without first agreeing with the others and
121
+ * merged into their concurrent writes later, and how such an action is rebased over a stranger's
122
+ * committed ones. A collection with NO declaration is strong: every action is `serializable`, the
123
+ * revision order decides every conflict, and nothing merges — today's behaviour, and `Tree`'s. The
124
+ * declaration is the opt-in; db-core has no notion of a table's profile beyond it.
125
+ *
126
+ * Convergence is a property of the OPERATION, never of the collection as a whole (idempotence is not
127
+ * the criterion — see `Lane`), which is why the declaration classifies per action.
128
+ */
129
+ export type ConvergentMerge<TAction> = {
130
+ /** The lane of one of this collection's actions when no engine has classified it: a bare
131
+ * `Collection.sync` with no `SyncOptions.lane`, or an offline-queue entry sealed without a
132
+ * classification (`OfflineQueue.enqueue`). The stricter answer over several actions is the write's
133
+ * (`Collection.laneOf`). */
134
+ laneOf(action: Action<TAction>): Lane;
135
+ /** Rebase one of this collection's CONVERGENT actions over a stranger's committed actions, which a
136
+ * refresh found in the log after the action was staged. Offered only an action whose
137
+ * {@link laneOf} is `convergent`: a serializable action is kept as-is, since its guards decide on
138
+ * replay. Return the same instance to keep the action unchanged, a new instance to apply in its
139
+ * place (re-staged by the conflict replay), or `undefined` to drop it. Optional, since a convergent
140
+ * action that touches no shared block (a diary append) has nothing to rebase. */
141
+ filterConflict?(action: Action<TAction>, committed: Action<TAction>[]): Action<TAction> | undefined;
142
+ };
143
+
100
144
  export type CollectionInitOptions<TAction> = {
101
145
  /** One handler per action type. A handler may answer what the action accepted as already applied
102
146
  * ({@link AlreadyAppliedTally}); one that answers nothing counts as the zero tally, so a collection
103
147
  * type with no such notion returns nothing. */
104
148
  modules: Record<ActionType, ActionHandler<TAction, AlreadyAppliedTally | void>>;
105
149
  createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => IBlock;
106
- /** Called for each local action that is potentially in conflict with a remote action.
107
- * @param action - The local action to check
108
- * @param potential - The remote actions that are potentially in conflict
109
- * @returns The original action (return the same instance to keep it as-is), a replacement
110
- * action (return a new instance to apply instead of the original — it is re-staged via
111
- * the conflict replay), or undefined to discard this action
112
- */
113
- filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined;
150
+ /** The convergent lane's conflict rule for this collection ({@link ConvergentMerge}): which of its
151
+ * actions are convergent, and how one is rebased over a stranger's committed actions. Omit for a
152
+ * strong collection, whose every action is `serializable` and is kept as-is through a refresh. */
153
+ merge?: ConvergentMerge<TAction>;
114
154
  /** Called once per refusal of a SEALED segment discovered by a replay (see
115
155
  * {@link Collection.replayActions}): the segment's entry id and the handler's refusal. Called
116
156
  * synchronously from inside the replay, under the collection latch, so it MUST NOT call a
@@ -267,7 +307,7 @@ export class Collection<TAction> implements ICollection<TAction> {
267
307
  * ({@link InFlightCycle}) — read by {@link send} and by the re-send {@link completeOwnEntry} makes
268
308
  * to finish a torn attempt, so neither needs it threaded through. Set by
269
309
  * {@link beginInFlightAction} and cleared by its disposer. */
270
- private inFlightCycle: InFlightCycle = {};
310
+ private inFlightCycle: InFlightCycle | undefined;
271
311
 
272
312
  /** The head commit running on this instance ({@link openHeadCommit}), for the whole cycle — set and
273
313
  * cleared beside {@link inFlightActionId}: the sealed segment it is committing, and the hook told
@@ -308,7 +348,8 @@ export class Collection<TAction> implements ICollection<TAction> {
308
348
  * {@link updateInternal}, and shared with every read source this handle builds (see
309
349
  * {@link BlockFloors}). */
310
350
  private readonly floors: BlockFloors,
311
- private readonly filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined,
351
+ /** See {@link CollectionInitOptions.merge}. */
352
+ private readonly merge?: ConvergentMerge<TAction>,
312
353
  /** See {@link CollectionInitOptions.onSealedRefused}. */
313
354
  private readonly onSealedRefused?: (entryId: EntryId, error: ActionRefusedError) => void,
314
355
  /** See {@link CollectionInitOptions.onViewChanged}. */
@@ -362,8 +403,8 @@ export class Collection<TAction> implements ICollection<TAction> {
362
403
  // that ignores the undefined cannot later sync a phantom collection into existence.
363
404
  return undefined;
364
405
  }
365
- await Collection.attachToLog<TAction>(source, sourceCache, tracker, floors, id, instanceTag, ends);
366
- const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, init.onSealedRefused, init.onViewChanged, instanceTag);
406
+ await Collection.attachToLog<TAction>(source, sourceCache, tracker, floors, id, instanceTag, ends, clockOf(transactor));
407
+ const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.merge, init.onSealedRefused, init.onViewChanged, instanceTag);
367
408
  collection.logTailId = ends.header.tailId;
368
409
  return collection;
369
410
  }
@@ -381,7 +422,7 @@ export class Collection<TAction> implements ICollection<TAction> {
381
422
 
382
423
  let inventedBaseline: Transforms | undefined;
383
424
  if (ends) { // Collection already exists
384
- await Collection.attachToLog<TAction>(source, sourceCache, tracker, floors, id, instanceTag, ends);
425
+ await Collection.attachToLog<TAction>(source, sourceCache, tracker, floors, id, instanceTag, ends, clockOf(transactor));
385
426
  } else { // Collection does not exist
386
427
  log('collection:invented id=%s — no committed header found; staging a fresh empty collection', id);
387
428
  const headerBlock = init.createHeaderBlock(id, tracker);
@@ -394,7 +435,7 @@ export class Collection<TAction> implements ICollection<TAction> {
394
435
  inventedBaseline = copyTransforms(tracker.transforms);
395
436
  }
396
437
 
397
- const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, init.onSealedRefused, init.onViewChanged, instanceTag);
438
+ const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.merge, init.onSealedRefused, init.onViewChanged, instanceTag);
398
439
  collection.logTailId = ends?.header.tailId;
399
440
  collection.inventedBaseline = inventedBaseline;
400
441
  return collection;
@@ -530,11 +571,14 @@ export class Collection<TAction> implements ICollection<TAction> {
530
571
  * diagnostic emitted here carries the same instance name as every post-construction one. */
531
572
  instanceTag: string,
532
573
  ends: LogEnds,
574
+ /** The clock the handle's writes will mint from, which observes the tail it read. */
575
+ clock: HlcClock,
533
576
  ): Promise<void> {
534
577
  // Bootstrap ActionContext from the committed tail before walking the chain.
535
578
  // This allows the transactor to serve pending non-tail blocks during Log.open.
536
579
  Collection.bootstrapContext(source, ends.tail);
537
580
  Collection.floorTailEntries(floors, ends);
581
+ Collection.observeTailEntries(clock, ends);
538
582
  // The walk starts from the header and the tail, which the probe just read: keep them, so the
539
583
  // walk reads neither again. Its first read of each through the cache then records the read
540
584
  // dependency the probe's own read of the header used to.
@@ -575,6 +619,22 @@ export class Collection<TAction> implements ICollection<TAction> {
575
619
  }
576
620
  }
577
621
 
622
+ /** Have `clock` observe the highest HLC among the opened log's tail block entries, which the open
623
+ * has read but does not walk — the open's half of what a refresh's walk feeds the clock
624
+ * ({@link forgetAndAdopt}), so a write through this handle never mints below a write it has seen.
625
+ * Only the tail block, which the open read anyway; an older log block would cost a read for entries
626
+ * committed earlier. Their HLCs are usually lower, but not always — an offline entry keeps the HLC
627
+ * minted at enqueue and a retry its first attempt's (the `NOTE:` at `WriteIdentity.hlc`) — so
628
+ * a write may mint below an entry in an older block, one this handle never read. */
629
+ private static observeTailEntries(clock: HlcClock, ends: LogEnds): void {
630
+ const tail = ends.tail?.block as LogBlock<unknown> | undefined;
631
+ let highWater: Hlc | undefined;
632
+ for (const entry of tail?.entries ?? []) {
633
+ highWater = maxHlc(highWater, hlcOf(entry));
634
+ }
635
+ if (highWater !== undefined) clock.observe(highWater);
636
+ }
637
+
578
638
  /** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
579
639
  *
580
640
  * The revision a collection last committed at is knowledge it earned; a read that found
@@ -601,23 +661,20 @@ export class Collection<TAction> implements ICollection<TAction> {
601
661
  * tag, two handles' lines interleave into what reads like one handle contradicting itself.
602
662
  *
603
663
  * Logs, does not throw — same reasoning as {@link reportShortfall}: `update()` runs
604
- * blanket-style over every registered collection between commit retries, and aborting here
605
- * would promote a diagnosis to production behaviour before the line has ever been seen to
606
- * fire in the wild. Adoption then proceeds unchanged, which means the line is a PER-DISCOVERY
607
- * report, not a per-refresh one: adopting `next` overwrites the held lineage marker with the
608
- * log's, so the next refresh of this instance compares log-to-log and stays silent — even
609
- * though block content materialized under the old lineage may still be in caches. The line
610
- * marks the refresh that first observed the disagreement.
611
- *
612
- * NOTE: adoption resolves the CONTEXT disagreement, not the content one — the read caches on
613
- * this instance still hold blocks materialized under the old lineage, and since the revision
614
- * did not change nothing re-reads them. Conditional today: no fork has been reproduced (see
615
- * the still-open upstream reproducer), so this instrument exists to find out whether one
616
- * happens at all. If the line is ever seen firing in the field, decide then whether a
617
- * divergence should also drop the read cache (and whether to keep re-reporting per refresh)
618
- * — that is a behaviour change, and this seam deliberately makes none.
619
- *
620
- * The comparison is {@link earliestFork}, not a single lookup at the current revision: the
664
+ * blanket-style over every registered collection between commit retries. Whether the read is
665
+ * adopted, and whether it is another lineage, is {@link judgeAdoption}'s call, made before this
666
+ * runs so a refresh can act on it first: a refresh that ADOPTS another lineage drops its whole
667
+ * read cache and its floors and re-stages every staged action ({@link forgetAndAdopt},
668
+ * {@link mustReplay}), since everything it cached and computed was computed against a history the
669
+ * network does not hold; an open has no cache to drop and nothing staged. The line is therefore a
670
+ * PER-DISCOVERY report: adopting `next` overwrites the held lineage marker with the log's, the
671
+ * drop leaves the handle consistent with the log, and the next refresh compares log to log and
672
+ * has nothing to report. A REFUSED read leaves the held marker in place, so a fork sealed by a
673
+ * `collection:context-not-lowered` refusal is reported on every refresh, beside that line, with
674
+ * nothing dropped — bringing such a handle onto the network's lineage is reconciliation, backlog
675
+ * `feat-replay-mode-collections-merge-divergent-histories`.
676
+ *
677
+ * The comparison printed is {@link earliestFork}, not a single lookup at the current revision: the
621
678
  * two `committed` lists overlap across several revisions, and the LOWEST one they disagree at
622
679
  * is where the lineages actually parted — a fork below the current revision was previously
623
680
  * silent. `forkRev=` names it, `heldAction=`/`readAction=` are the two ids AT it, and
@@ -634,19 +691,23 @@ export class Collection<TAction> implements ICollection<TAction> {
634
691
  * the NOTE in {@link bootstrapContext}), which is exactly the case {@link earliestFork} has no
635
692
  * shared revision to report on.
636
693
  *
637
- * Gated on `log.enabled`, like every {@link actionIdAt} caller: the comparison buys nothing
638
- * when the line has no sink, and the lists — one entry per commit between context reads,
639
- * truncated at each checkpoint — are only walked on a run that has the namespace turned on.
694
+ * The two printed comparisons are gated on `log.enabled`: they buy nothing when the line has no
695
+ * sink. Nothing the handle DOES is: the adoption and the lineage verdict behind it
696
+ * ({@link judgeAdoption}) run whatever the logging.
640
697
  * Silence proves nothing either way, because a revision is only comparable when BOTH sides
641
698
  * name an action for it: an invented collection has no context at all, a revision slot the log
642
699
  * gave to a checkpoint or invalidation entry names none, and a revision older than the read
643
- * log's most recent checkpoint has already fallen off the read side's list. */
700
+ * log's most recent checkpoint has already fallen off the read side's list.
701
+ *
702
+ * @param adoption what adopting `next` does, as {@link judgeAdoption} answers it for the context
703
+ * `source` holds now — passed in by a caller that had to act on it before calling. */
644
704
  private static advanceContext(
645
705
  source: TransactorSource<IBlock>,
646
706
  id: CollectionId,
647
707
  instanceTag: string,
648
708
  site: DivergenceSite,
649
709
  next: ActionContext | undefined,
710
+ adoption: Adoption = Collection.judgeAdoption(source.actionContext, next),
650
711
  ): void {
651
712
  const current = source.actionContext;
652
713
  if (next === undefined) {
@@ -659,9 +720,9 @@ export class Collection<TAction> implements ICollection<TAction> {
659
720
  id, instanceTag, site, fork.rev, fork.heldAction, fork.readAction, current.rev, next.rev);
660
721
  }
661
722
  }
662
- if (current !== undefined && next.rev < current.rev) {
723
+ if (adoption === 'refuse') {
663
724
  // The refusal itself is unconditional; only the id lookups that explain it are gated.
664
- if (log.enabled) {
725
+ if (current !== undefined && log.enabled) {
665
726
  log('collection:context-not-lowered id=%s tag=%s site=%s heldRev=%d readRev=%d heldAction=%s readAction=%s',
666
727
  id, instanceTag, site, current.rev, next.rev,
667
728
  actionIdAt(current, next.rev) ?? 'none', actionIdAt(next, next.rev) ?? 'none');
@@ -671,6 +732,39 @@ export class Collection<TAction> implements ICollection<TAction> {
671
732
  source.actionContext = next;
672
733
  }
673
734
 
735
+ /** Whether a read context `next` is adopted over the `held` one, and whether it is another
736
+ * lineage ({@link Adoption}). Runs whatever the logging, because the answer is behaviour.
737
+ *
738
+ * Another lineage means the two name different actions at the HELD revision. One comparison is
739
+ * enough because an action id is unique per commit: two lineages that parted at or below the held
740
+ * revision name different actions at every revision both have reached since, the held one
741
+ * included. The exception, one action landing on both sides (a writer's torn retry), is the same
742
+ * lineage at that revision, which is the right answer. A side naming no action there is missing
743
+ * evidence, not disagreement, as in {@link earliestFork} — the held revision's slot went to an
744
+ * invalidation or checkpoint entry, or it predates the read side's most recent checkpoint — so a
745
+ * fork visible only below such a slot is not acted on (the line may still report it). A refused
746
+ * read names no action at the held revision, being below it, so `adopt-divergent` never comes
747
+ * with a refusal.
748
+ *
749
+ * NOTE: two {@link actionIdAt} scans per refresh that walks the log, never per read. Each searches
750
+ * from the end: the held side's entry is normally its last, and the read side's is as far back as
751
+ * the entries the walk found. Both lists truncate only at a checkpoint, which nothing writes yet
752
+ * (tickets/backlog/debt-the-collection-log-never-writes-a-checkpoint); if they grow long enough
753
+ * for that to show, index them by revision. */
754
+ private static judgeAdoption(held: ActionContext | undefined, next: ActionContext | undefined): Adoption {
755
+ if (next === undefined || (held !== undefined && next.rev < held.rev)) {
756
+ return 'refuse';
757
+ }
758
+ if (held === undefined) {
759
+ return 'adopt';
760
+ }
761
+ const heldAction = actionIdAt(held, held.rev);
762
+ const readAction = actionIdAt(next, held.rev);
763
+ return heldAction !== undefined && readAction !== undefined && heldAction !== readAction
764
+ ? 'adopt-divergent'
765
+ : 'adopt';
766
+ }
767
+
674
768
  /** The EARLIEST revision the two contexts provably disagree about: the lowest revision both
675
769
  * `committed` lists name an action for, where the two ids differ.
676
770
  *
@@ -826,10 +920,8 @@ export class Collection<TAction> implements ICollection<TAction> {
826
920
  * ask for another (see {@link completeOwnEntry}).
827
921
  *
828
922
  * `tailFloor` is optional: a revision a responder confirmed is taken, when the caller has one (see
829
- * {@link updateInternal}). `TransactionCoordinator.commit` has none to pass today — its commit loop
830
- * does not see the confirmed revision (backlog:
831
- * debt-multi-collection-retry-cannot-see-the-taken-revision) — and this is the parameter it will
832
- * pass it through. */
923
+ * {@link updateInternal}). `TransactionCoordinator.commit` passes the highest one its refusals of
924
+ * THIS collection carried (`RetryBudget.tailFloor`), and nothing for a collection none did. */
833
925
  async refreshInFlight(report: RefreshReport, lastChance: boolean, tailFloor?: number): Promise<void> {
834
926
  const release = await Latches.acquire(this.latchId);
835
927
  try {
@@ -926,10 +1018,19 @@ export class Collection<TAction> implements ICollection<TAction> {
926
1018
  // pair is not obviously right either: a member re-executing the transaction after a sibling
927
1019
  // participant has landed no longer sees the state it was staged against. Tracked as an arm
928
1020
  // of tickets/backlog/feat-no-deployment-validates-transactions-at-pend.
1021
+ // NOTE: the re-send carries no pend-level `hlc` either: the retained attempt holds the write's
1022
+ // HLC only inside the log entry in its transforms, and the ActionEntry the refresh hands this
1023
+ // method does not carry it. A member that missed the first pend and stores this re-send
1024
+ // therefore observes the write's HLC when it next reads the entry, not at the pend. Fine while
1025
+ // the HLC is observational; if a feed point at the pend ever becomes load-bearing, retain the
1026
+ // HLC on `InFlightAttempt` beside the transforms and put it on this request. The write's LANE
1027
+ // does ride here, from the in-flight cycle (`InFlightCycle.lane`), which every write path marks
1028
+ // with the lane it minted: the same value the retained entry carries.
929
1029
  const result = await this.source.transact(attempt.transforms, entry.actionId, rev, this.id, attempt.tailId, {
930
1030
  blockDigests: attempt.blockDigests,
931
1031
  baseRevs: attempt.baseRevs,
932
- refuseSolo: this.inFlightCycle.refuseSolo
1032
+ lane: this.inFlightCycle?.lane,
1033
+ refuseSolo: this.inFlightCycle?.refuseSolo
933
1034
  });
934
1035
  if (result.success) {
935
1036
  return result.durability;
@@ -1172,8 +1273,11 @@ export class Collection<TAction> implements ICollection<TAction> {
1172
1273
  * replace => new instance.
1173
1274
  *
1174
1275
  * A SEALED segment's action list is the queue entry's own and is never rewritten (invariant 3
1175
- * of docs/offline-sync.md §The segment model), so the hook is not offered them. `Tree` and
1176
- * `Diary` install no hook, so nothing observable changes for them either way.
1276
+ * of docs/offline-sync.md §The segment model), so the hook is not offered them. The hook is the
1277
+ * convergent lane's rule ({@link ConvergentMerge.filterConflict}): {@link doFilterConflict} offers
1278
+ * it only an action the declaration classifies `convergent`, and keeps a serializable one as-is.
1279
+ * `Tree` declares nothing and `Diary` declares no hook, so nothing observable changes for them
1280
+ * either way.
1177
1281
  *
1178
1282
  * NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead of
1179
1283
  * returning the same one forces a replay on every update — if that ever shows up as a hot path,
@@ -1334,13 +1438,13 @@ export class Collection<TAction> implements ICollection<TAction> {
1334
1438
  anyConflicts = true;
1335
1439
  }
1336
1440
 
1337
- this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
1441
+ const adoption = this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
1338
1442
 
1339
1443
  Collection.reportShortfall(this.id, this.instanceTag, tailRev, actionContext?.rev, this.source.actionContext?.rev);
1340
1444
 
1341
1445
  // Re-stage the staged actions against the adopted revision. The affected
1342
- // blocks were already dropped from sourceCache above (per log entry / per invalidation),
1343
- // so the replay's reads re-materialize from the transactor.
1446
+ // blocks were already dropped from sourceCache above (per log entry / per invalidation, or
1447
+ // all of them on an adopted divergence), so the replay's reads re-materialize from the transactor.
1344
1448
  // NOTE: a throw out of replayActions — a refusal of the OPEN segment, or any non-refusal
1345
1449
  // error — leaves the tracker holding only the transforms replayed so far while the open
1346
1450
  // segment still lists all of its actions; the caller's error handling is expected to
@@ -1349,7 +1453,7 @@ export class Collection<TAction> implements ICollection<TAction> {
1349
1453
  // collection-half-restaged). A SEALED segment is not left half-replayed: it is staged
1350
1454
  // atomically, and a refusal of one is recorded and skipped rather than thrown. If replay ever
1351
1455
  // gains a routinely-throwing read path, rebuild into a scratch tracker and swap on success.
1352
- if (this.mustReplay(anyConflicts, actionContext)) {
1456
+ if (this.mustReplay(anyConflicts, actionContext, adoption)) {
1353
1457
  await this.replayActions();
1354
1458
  }
1355
1459
  }
@@ -1376,21 +1480,46 @@ export class Collection<TAction> implements ICollection<TAction> {
1376
1480
  * context at all, and a log read that lags what this handle already committed yields an older
1377
1481
  * one; neither is grounds for forgetting the revision held. It also has to precede
1378
1482
  * {@link replayActions}, which re-reads blocks through `this.source` at whatever revision the
1379
- * context names — replaying first would refill the cache at the revision being left. */
1483
+ * context names — replaying first would refill the cache at the revision being left.
1484
+ *
1485
+ * **An adopted divergence forgets everything first** ({@link judgeAdoption}): the whole read cache
1486
+ * and every floor, ahead of the per-entry loop so this walk's floors — the new lineage's — are the
1487
+ * ones left standing. Not just the blocks the walked entries name: the walk covers only entries
1488
+ * above the held revision, so the blocks the old lineage built at and below it are named by
1489
+ * entries this handle will never walk, the cache has no expiry, and an idle refresh stops after
1490
+ * one request while the log does not move — nothing would ever clear them. And not the floors
1491
+ * kept: a floor raised under the old lineage is no bound on the new one, where the block may
1492
+ * legitimately sit below it, and would make every read of it a below-floor answer for the life of
1493
+ * the handle. The header and tail {@link keepLogEnds} offers came from the new lineage and may be
1494
+ * kept. The staged actions were computed against the old content, so the verdict is returned for
1495
+ * {@link mustReplay}.
1496
+ *
1497
+ * The handle's clock observes the highest HLC the walk read (`GetFromResult.hlcHighWater`), so a
1498
+ * write through it never mints below an entry it has seen — whatever the verdict, since a clock
1499
+ * only rises and the entries were read either way.
1500
+ *
1501
+ * @returns what the adoption did, as {@link judgeAdoption} answered it before anything changed. */
1380
1502
  private forgetAndAdopt(
1381
1503
  latest: GetFromResult<Action<TAction>> | undefined,
1382
1504
  entryRevs: ReadonlyMap<ActionId, number>,
1383
1505
  revertedBlockIds: BlockId[],
1384
1506
  ends: LogEnds,
1385
- ): void {
1507
+ ): Adoption {
1508
+ const adoption = Collection.judgeAdoption(this.source.actionContext, latest?.context);
1509
+ if (latest?.hlcHighWater !== undefined) clockOf(this.transactor).observe(latest.hlcHighWater);
1386
1510
  this.viewChanged();
1511
+ if (adoption === 'adopt-divergent') {
1512
+ this.sourceCache.clear();
1513
+ this.floors.clear();
1514
+ }
1387
1515
  for (const entry of latest?.entries ?? []) {
1388
1516
  this.sourceCache.clear(entry.blockIds);
1389
1517
  this.raiseFloors(entry, entryRevs.get(entry.actionId));
1390
1518
  }
1391
1519
  this.sourceCache.clear(revertedBlockIds);
1392
- Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context);
1520
+ Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context, adoption);
1393
1521
  Collection.keepLogEnds(this.sourceCache, this.floors, this.source.actionContext, ends);
1522
+ return adoption;
1394
1523
  }
1395
1524
 
1396
1525
  /** Put the header and log tail block {@link readLogEnds} already fetched into a handle's own
@@ -1537,7 +1666,8 @@ export class Collection<TAction> implements ICollection<TAction> {
1537
1666
  * claim (`collection:context-short-of-tail`, or `collection:context-not-lowered` for a handle
1538
1667
  * pinned by an over-claiming tail), or an invalidation or checkpoint took the newest slot;
1539
1668
  * - any action entry in the tail block naming a different action than `held` names at the same
1540
- * revision (`collection:lineage-divergence`, and the walk's adoption of the log's list).
1669
+ * revision (`collection:lineage-divergence`, and the walk's adoption of the log's list, which
1670
+ * drops the read cache when it adopts another lineage — see {@link forgetAndAdopt}).
1541
1671
  *
1542
1672
  * NOTE: the lineage comparison sees only the entries the tail block holds. A fork below them, on
1543
1673
  * a log that has not moved, is not looked at again until a refresh finds something new — that
@@ -1601,8 +1731,10 @@ export class Collection<TAction> implements ICollection<TAction> {
1601
1731
  * (`index-backfill-cost.spec.ts`, `cold-apply-cost.spec.ts`), because the replay's reads are
1602
1732
  * served from `sourceCache`. If a long transaction's reads ever show up as slow, narrow the
1603
1733
  * replay to the actions whose reads the adopted entries actually invalidated — NOT back to
1604
- * conflicts alone, which is the defect above. */
1605
- private mustReplay(anyConflicts: boolean, priorContext: ActionContext | undefined): boolean {
1734
+ * conflicts alone, which is the defect above.
1735
+ *
1736
+ * @param adoption what the refresh's adoption did ({@link forgetAndAdopt}). */
1737
+ private mustReplay(anyConflicts: boolean, priorContext: ActionContext | undefined, adoption: Adoption): boolean {
1606
1738
  if (anyConflicts) {
1607
1739
  return true;
1608
1740
  }
@@ -1611,6 +1743,14 @@ export class Collection<TAction> implements ICollection<TAction> {
1611
1743
  if (adoptedRev !== undefined && adoptedRev !== priorContext?.rev && replayable > 0) {
1612
1744
  return true;
1613
1745
  }
1746
+ // Fourth reason, ahead of the third: the refresh adopted another lineage, so every staged
1747
+ // action was computed against content the network does not hold. A fork at the SAME revision
1748
+ // advances nothing, so the reason above does not see it. The whole-cache clear behind it
1749
+ // would usually make every pinned base read as moved too, but this keeps the rule readable,
1750
+ // covers staged actions that pinned nothing, and spares a `restage-moved-base` line per pin.
1751
+ if (adoption === 'adopt-divergent' && replayable > 0) {
1752
+ return true;
1753
+ }
1614
1754
  // Third reason: a staged block's base has MOVED — the read cache no longer describes it at
1615
1755
  // the revision its operations were computed against (see `Tracker.movedBases`). A refresh
1616
1756
  // that adopted nothing and found no conflict can still be standing over such a block: a
@@ -2212,7 +2352,7 @@ export class Collection<TAction> implements ICollection<TAction> {
2212
2352
  *
2213
2353
  * `cycle` is what every send of the cycle carries ({@link InFlightCycle}); a re-mark replaces it,
2214
2354
  * which is harmless because every caller re-marks with what it marked. */
2215
- beginInFlightAction(actionId: ActionId, cycle: InFlightCycle = {}): () => void {
2355
+ beginInFlightAction(actionId: ActionId, cycle: InFlightCycle): () => void {
2216
2356
  if (this.inFlightActionId !== actionId) {
2217
2357
  // A different action's failed attempt cannot finish this one. Re-marking the SAME id (a
2218
2358
  // coordinator re-marks on every attempt) keeps what the previous attempt retained — that
@@ -2228,7 +2368,7 @@ export class Collection<TAction> implements ICollection<TAction> {
2228
2368
  this.inFlightActionId = undefined;
2229
2369
  this.inFlightAttempt = undefined;
2230
2370
  this.mintedLogBlockIds = undefined;
2231
- this.inFlightCycle = {};
2371
+ this.inFlightCycle = undefined;
2232
2372
  }
2233
2373
  };
2234
2374
  }
@@ -2335,13 +2475,22 @@ export class Collection<TAction> implements ICollection<TAction> {
2335
2475
  this.assertNoSealedSegments();
2336
2476
  const identity: WriteIdentity = {
2337
2477
  actionId: uint8ArrayToString(randomBytes(16), 'base64url'),
2338
- // One timestamp for the WRITE, minted here beside the action id and for the same reason: an
2339
- // attempt that takes its own would make the retry's log block differ from the one the
2340
- // attempt it repeats may already have stored under this `(action id, revision)`.
2478
+ // One timestamp, one HLC and one lane for the WRITE, minted here beside the action id and for
2479
+ // the same reason: an attempt that took its own would make the retry's log block differ from
2480
+ // the one the attempt it repeats may already have stored under this `(action id, revision)`.
2341
2481
  timestamp: Date.now(),
2482
+ hlc: clockOf(this.transactor).now(),
2483
+ // The caller's classification wins over the declaration, and the declaration over nothing
2484
+ // (`SyncOptions.lane`): the caller knows more about the write than the collection does.
2485
+ // NOTE: judged over the open segment as staged NOW and fixed for the write; a
2486
+ // `merge.filterConflict` hook that answered a replacement of a different lane during an
2487
+ // inter-attempt refresh would leave the entry claiming the lane of the action it replaced. No
2488
+ // hook in this repository replaces an action; if one ever does, the member-side lane check is
2489
+ // what catches the mismatch.
2490
+ lane: options?.lane ?? this.laneOf(this.segments.open),
2342
2491
  };
2343
2492
 
2344
- const endInFlight = this.beginInFlightAction(identity.actionId, { refuseSolo: options?.refuseSoloCommit });
2493
+ const endInFlight = this.beginInFlightAction(identity.actionId, { lane: identity.lane, refuseSolo: options?.refuseSoloCommit });
2345
2494
  try {
2346
2495
  return await this.syncAttempts(identity, options);
2347
2496
  } finally {
@@ -2417,9 +2566,11 @@ export class Collection<TAction> implements ICollection<TAction> {
2417
2566
  private send(staged: StagedAttempt, identity: WriteIdentity, priority: number): Promise<CommitResult> {
2418
2567
  return this.source.transact(staged.tracker.transforms, identity.actionId, staged.rev, this.id, staged.tailId, {
2419
2568
  priority,
2569
+ hlc: identity.hlc,
2570
+ lane: identity.lane,
2420
2571
  blockDigests: staged.blockDigests,
2421
2572
  baseRevs: staged.baseRevs,
2422
- refuseSolo: this.inFlightCycle.refuseSolo
2573
+ refuseSolo: this.inFlightCycle?.refuseSolo
2423
2574
  });
2424
2575
  }
2425
2576
 
@@ -2463,7 +2614,7 @@ export class Collection<TAction> implements ICollection<TAction> {
2463
2614
  * when a refresh or the head tracker's staging refused it during the cycle; whatever
2464
2615
  * `options.recordAttempt` throws, before anything is sent; otherwise what {@link sync} throws. */
2465
2616
  async commitHead(entryId: EntryId, options: HeadCommitOptions): Promise<WriteDurability | undefined> {
2466
- const handle = await this.openHeadCommit(entryId, { actionId: options.actionId, timestamp: options.timestamp }, {
2617
+ const handle = await this.openHeadCommit(entryId, { actionId: options.actionId, timestamp: options.timestamp, hlc: options.hlc, lane: options.lane }, {
2467
2618
  refuseSolo: options.refuseSoloCommit,
2468
2619
  ...(options.resume === undefined ? {} : { resume: options.resume }),
2469
2620
  ...(options.onCommittedHead === undefined ? {} : { onCommittedHead: options.onCommittedHead }),
@@ -2486,9 +2637,9 @@ export class Collection<TAction> implements ICollection<TAction> {
2486
2637
  * segment; and seeds the retained attempt with `options.resume` when one is given, so that the
2487
2638
  * opening refresh can finish an earlier cycle's torn attempt from it ({@link completeOwnEntry}) —
2488
2639
  * and `stage()` re-sends it verbatim while the next attempt would request its revision
2489
- * ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}), recorded
2490
- * with the in-flight mark, so the handle's `send()` and a refresh's re-send of a torn attempt both
2491
- * carry it.
2640
+ * ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}, its lane
2641
+ * taken from `identity`), recorded with the in-flight mark, so the handle's `send()` and a
2642
+ * refresh's re-send of a torn attempt both carry it.
2492
2643
  *
2493
2644
  * **The target.** The live tracker holds every sealed segment and the open one, cumulatively, so
2494
2645
  * an attempt cannot run on a copy of it the way a sync's does. It runs on a HEAD TRACKER instead
@@ -2538,7 +2689,7 @@ export class Collection<TAction> implements ICollection<TAction> {
2538
2689
  release();
2539
2690
  throw err;
2540
2691
  }
2541
- const endInFlight = this.beginInFlightAction(identity.actionId, cycle);
2692
+ const endInFlight = this.beginInFlightAction(identity.actionId, { ...cycle, lane: identity.lane });
2542
2693
  this.headCommit = { entryId, ...(onCommittedHead === undefined ? {} : { onCommitted: onCommittedHead }) };
2543
2694
  if (resume !== undefined) {
2544
2695
  this.retainInFlightAttempt(resume);
@@ -2686,21 +2837,27 @@ export class Collection<TAction> implements ICollection<TAction> {
2686
2837
  /** The tracker a head attempt is built from (see {@link commitHead}): `current`, while it was
2687
2838
  * built for the revision the next attempt requests and no base under it has moved; otherwise a
2688
2839
  * fresh one ({@link buildHeadTracker}). A revision that moved is a write that is genuinely
2689
- * different. A base that moved at the same revision is re-judged exactly as
2690
- * {@link restageIfBasesMoved} re-judges the live queue before an attempt, and rebuilds.
2840
+ * different, and so is one whose held lineage moved at the same revision: a refresh between
2841
+ * attempts that adopted another lineage ({@link judgeAdoption}) dropped the read cache the
2842
+ * tracker was staged over, and an action that inserted a block computed from that content pinned
2843
+ * no base the re-judge below would see as moved. A base that moved at the same revision is
2844
+ * re-judged exactly as {@link restageIfBasesMoved} re-judges the live queue before an attempt,
2845
+ * and rebuilds.
2691
2846
  * NOTE: that rebuild is the same exception to the byte-identical retry that {@link syncAttempts}
2692
2847
  * records at its `restageIfBasesMoved` call — fresh ids for the blocks the actions insert under
2693
2848
  * an unchanged `(action id, revision)` — reached the same narrow way and refused by storage's
2694
2849
  * base guard on the same machines; the same answer applies if it is ever seen. */
2695
2850
  private async headTrackerFor(segment: SealedSegment<TAction>, current: HeadTracker | undefined): Promise<HeadTracker> {
2696
2851
  const rev = this.getNextRev();
2697
- if (current?.rev === rev) {
2852
+ const held = this.source.actionContext;
2853
+ const lineage = held === undefined ? undefined : actionIdAt(held, held.rev);
2854
+ if (current?.rev === rev && current.lineage === lineage) {
2698
2855
  await this.rereadUnretainedBases(current.tracker);
2699
2856
  if (this.logMovedBases(current.tracker.movedBases()) === 0) {
2700
2857
  return current;
2701
2858
  }
2702
2859
  }
2703
- return { rev, tracker: await this.buildHeadTracker(segment) };
2860
+ return { rev, lineage, tracker: await this.buildHeadTracker(segment) };
2704
2861
  }
2705
2862
 
2706
2863
  /** A tracker over this instance's read cache, with pins of its own, holding `segment`'s actions
@@ -2777,10 +2934,10 @@ export class Collection<TAction> implements ICollection<TAction> {
2777
2934
  * refresh would have done. */
2778
2935
  private async unstage(actions: Action<TAction>[], stagedBefore: Transforms, revBefore: number | undefined): Promise<void> {
2779
2936
  // NOTE: matched by identity, which is what `filterAgainstEntry` promises for a kept action.
2780
- // A `filterConflict` hook that answers a REPLACEMENT instance for one of these actions would
2781
- // leave the replacement staged here. No collection installs such a hook today (`Tree` and
2782
- // `Diary` install none); if one ever does, carry a per-call token on the staged actions and
2783
- // match on that instead.
2937
+ // A `merge.filterConflict` hook that answers a REPLACEMENT instance for one of these actions
2938
+ // would leave the replacement staged here. No collection installs such a hook today (`Tree`
2939
+ // declares no merge and `Diary` declares no hook); if one ever does, carry a per-call token on
2940
+ // the staged actions and match on that instead.
2784
2941
  // The actions were staged into the OPEN segment (actAndSync refuses over sealed segments).
2785
2942
  this.segments.open = this.segments.open.filter(staged => !actions.includes(staged));
2786
2943
  if (this.source.actionContext?.rev === revBefore) {
@@ -2883,14 +3040,31 @@ export class Collection<TAction> implements ICollection<TAction> {
2883
3040
  this.source.clearReadDependencies();
2884
3041
  }
2885
3042
 
3043
+ /** The lane of a write made of `actions` under this collection's merge declaration
3044
+ * ({@link CollectionInitOptions.merge}): the stricter lane over the declaration's answer for each
3045
+ * (`stricterLane`), `serializable` without a declaration and for an empty list. Pure. The source
3046
+ * of a sync's lane when its caller gave none (`SyncOptions.lane`), and of a queued entry's
3047
+ * (`OfflineQueue.enqueue`). */
3048
+ laneOf(actions: readonly Action<TAction>[]): Lane {
3049
+ const merge = this.merge;
3050
+ return merge === undefined ? 'serializable' : stricterLane(actions.map(action => merge.laneOf(action)));
3051
+ }
3052
+
2886
3053
  /** Called for each local action that may be in conflict with a remote action (always called under latch).
3054
+ * The merge declaration's hook ({@link ConvergentMerge.filterConflict}) decides only for an action the
3055
+ * declaration classifies `convergent`; a serializable action is kept as-is, since its guards decide
3056
+ * on replay, and so is every action of a collection with no declaration or no hook.
2887
3057
  * @param action - The local action to check
2888
3058
  * @param potential - The remote actions that are potentially in conflict
2889
3059
  * @returns The effective action to keep: the original (unchanged), a replacement
2890
3060
  * instance (applied instead of the original), or undefined to discard it.
2891
3061
  */
2892
3062
  protected doFilterConflict(action: Action<TAction>, potential: Action<TAction>[]): Action<TAction> | undefined {
2893
- return this.filterConflict ? this.filterConflict(action, potential) : action;
3063
+ const merge = this.merge;
3064
+ if (merge?.filterConflict === undefined || merge.laneOf(action) !== 'convergent') {
3065
+ return action;
3066
+ }
3067
+ return merge.filterConflict(action, potential);
2894
3068
  }
2895
3069
 
2896
3070
  /** The two blocks every refresh starts from — the collection header and the log tail block it