@optimystic/db-core 1.16.0 → 1.17.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.
@@ -237,8 +237,18 @@ export declare class Collection<TAction> implements ICollection<TAction> {
237
237
  tailId: BlockId;
238
238
  rev: number;
239
239
  } | undefined>;
240
- /** The per-instance read wiring every open path needs, plus the header probe result.
241
- * Shared by {@link open} and {@link createOrOpen} so the two cannot drift. */
240
+ /** The per-instance read wiring every open path needs, plus the collection's log ends — the
241
+ * header, then the log tail block it names — read by {@link readLogEnds}, the reader every
242
+ * refresh uses. Two requests: the tail id is known only from the header, so an open cannot ask
243
+ * for both in one the way a refresh can. `ends` is `undefined` when the header is
244
+ * authoritatively absent. Shared by {@link open} and {@link createOrOpen} so the two cannot drift.
245
+ *
246
+ * The header used to be probed through `source.tryGet`, an unpinned read on a handle with no
247
+ * floors yet. That decided nothing {@link readLogEnds} does not decide — `answeredBlock(id, entry,
248
+ * undefined)` is the whole of its verdict for such a read, so an unretrievable or doubted header
249
+ * throws exactly as it did — except recording the header as a read dependency, which the walk's
250
+ * first read of it through the handle's cache now records, at the revision it was served at
251
+ * (see {@link attachToLog}). */
242
252
  private static probeHeader;
243
253
  /** A new handle's floors: none yet (opening walks no entries), wired to report every below-floor
244
254
  * answer any of the handle's read sources receives. The line is the only trace such an answer
@@ -249,8 +259,9 @@ export declare class Collection<TAction> implements ICollection<TAction> {
249
259
  private static newFloors;
250
260
  /** Walk an existing collection's log and point the source at its latest action context.
251
261
  * A header we just probed successfully but whose log will not open is a fault, not an
252
- * absence — throw rather than let the collection read as empty. (The re-read goes through
253
- * the tracker/cache, so it can disagree with the probe when storage is flaky mid-open.) */
262
+ * absence — throw rather than let the collection read as empty. (A header {@link keepLogEnds}
263
+ * declines to keep is re-read through the tracker/cache, so it can disagree with the probe when
264
+ * storage is flaky mid-open.) */
254
265
  private static attachToLog;
255
266
  /** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
256
267
  *
@@ -518,7 +529,7 @@ export declare class Collection<TAction> implements ICollection<TAction> {
518
529
  private updateInternal;
519
530
  /** Forget every block the refresh saw change, floor the ones a log entry names, adopt the
520
531
  * revision the log is at, and keep what the refresh already read
521
- * ({@link keepWhatTheRefreshRead}) — ONE synchronous step, which must stay free of any `await`.
532
+ * ({@link keepLogEnds}) — ONE synchronous step, which must stay free of any `await`.
522
533
  *
523
534
  * Reads are not latched, so one can run while a refresh is under way. Forgetting a block while
524
535
  * this handle still reads at the revision it is LEAVING invites exactly the wrong re-read: the
@@ -537,43 +548,79 @@ export declare class Collection<TAction> implements ICollection<TAction> {
537
548
  * {@link replayActions}, which re-reads blocks through `this.source` at whatever revision the
538
549
  * context names — replaying first would refill the cache at the revision being left. */
539
550
  private forgetAndAdopt;
540
- /** Put the header and log tail block {@link readLogEnds} already fetched into this handle's own
551
+ /** Put the header and log tail block {@link readLogEnds} already fetched into a handle's own
541
552
  * cache, so the next read of either is a hit rather than a second fetch of a block just
542
- * received. Without it, a write that follows ANOTHER handle's commit fetches the log tail twice:
543
- * the refresh reads it, the walked entry names it (a commit's blocks include the log block its
544
- * entry was appended to) so the clear above drops it, and `Chain.add` then reads it again to
545
- * append this write's own entry.
546
- *
547
- * Last in {@link forgetAndAdopt}'s one synchronous step, after BOTH clears — offering before
548
- * either would simply be undone by it. An id that an invalidation reverted is therefore
549
- * re-offered rather than left forgotten, which is sound because the revert is itself a commit
550
- * and {@link readLogEnds} read unpinned: what it read already includes the revert.
551
- *
552
- * An offer is made only when all three hold:
553
- * - **This handle holds a context.** With none adopted, every later read is unpinned and may
553
+ * received. Two sites, one rule:
554
+ * - **An open** ({@link attachToLog}), before the walk: `Log.open` and the tail lookup behind
555
+ * the context start from exactly these two blocks, and would otherwise fetch both again.
556
+ * - **A refresh that walked** ({@link forgetAndAdopt}). Without it, a write that follows ANOTHER
557
+ * handle's commit fetches the log tail twice: the refresh reads it, the walked entry names it
558
+ * (a commit's blocks include the log block its entry was appended to) so the clear drops it,
559
+ * and `Chain.add` then reads it again to append this write's own entry. Last in that one
560
+ * synchronous step, after BOTH clears — offering before either would simply be undone by it.
561
+ * An id that an invalidation reverted is therefore re-offered rather than left forgotten, which
562
+ * is sound because the revert is itself a commit and {@link readLogEnds} read unpinned: what it
563
+ * read already includes the revert.
564
+ *
565
+ * Static, taking the cache, the floors and the context rather than `this`, because an open keeps
566
+ * before the handle is constructed.
567
+ *
568
+ * An offer is made only when all of these hold:
569
+ * - **The handle holds a context.** With none adopted, every later read is unpinned and may
554
570
  * legitimately be answered newer than what was read here, so there is nothing to judge the
555
571
  * offer against.
556
572
  * - **The served revision is at or below the adopted one.** {@link readLogEnds} reads unpinned,
557
- * so it can come back newer than the view this handle now reads at — exactly the
573
+ * so it can come back newer than the view the handle now reads at — exactly the
558
574
  * `collection:context-short-of-tail` case. Serving that to a read pinned lower would fabricate
559
575
  * a view that never existed. At or below the pin it is sound: a block whose newest content is
560
576
  * at `rev <= context.rev` has the same content at `context.rev`.
561
577
  * - **The served revision meets any applicable floor.** A cache must never keep a below-floor
562
578
  * answer.
579
+ * - **For the header, nothing rewrote it after it was read** ({@link headerCurrentThroughTail}).
580
+ * "Newest at `rev`" above holds for each block at the moment it was read, and the header and
581
+ * the tail are not read at one moment.
563
582
  *
564
583
  * NOTE: the floor check lives here because {@link readLogEnds} reads around
565
584
  * {@link TransactorSource}, which is what applies floors on every other read — nothing else on
566
585
  * this path would apply one. It asks {@link BlockFloors.meetsApplicableFloor} rather than
567
586
  * spelling the comparison out, so it cannot drift from the one `answeredBelowFloor` makes, and
568
587
  * asks the non-reporting face because this is not an answer being served to a reader — the
569
- * `collection:block-below-floor` line would misdescribe it.
570
- *
571
- * Only this site seeds. The early return at {@link tailShowsNothingNewer} is deliberately left
572
- * alone: it fires when the log has not moved, and the cache is then already warm with the tail
573
- * (folded in by this handle's own commit, or kept from its last walk), so seeding there would
574
- * buy a fetch back only when the LRU had evicted it — at the cost of putting the one-synchronous-
575
- * step reasoning in a second place. */
576
- private keepWhatTheRefreshRead;
588
+ * `collection:block-below-floor` line would misdescribe it. An opening handle has no floors yet,
589
+ * so there the check passes by construction.
590
+ *
591
+ * The early return at {@link tailShowsNothingNewer} deliberately does not keep: it fires when
592
+ * the log has not moved, and the cache is then already warm with the tail (folded in by this
593
+ * handle's own commit, or kept from its last walk or its open), so keeping there would buy a
594
+ * fetch back only when the LRU had evicted it — at the cost of putting the one-synchronous-step
595
+ * reasoning in a second place. */
596
+ private static keepLogEnds;
597
+ /** Whether the header {@link readLogEnds} read is still the header at the revision of the tail
598
+ * block it read — what {@link keepLogEnds}' revision test cannot see for the header.
599
+ *
600
+ * That test keeps a block served at or below the adopted revision because a block whose newest
601
+ * content is at `rev` has the same content at every later revision. "Newest" held when the block
602
+ * was read, and the header and the tail are not read at one moment: an open asks for the tail in
603
+ * a second request, so does a refresh whose remembered tail is out of date, and even the
604
+ * refresh's one batched request may be answered by two machines. A commit that lands between the
605
+ * two reads and rewrites the header — a log roll-over (the header names the tail block) or a tree
606
+ * whose root moved (a tree's header names its root) — leaves the context adopted from the tail
607
+ * at that commit's revision while the header read before it is served there as if current. Kept,
608
+ * the handle would read the tree through a root it no longer has, and a write that changes the
609
+ * header again would be refused by storage's base guard and retried.
610
+ *
611
+ * Every commit and every invalidation appends an entry naming the blocks it changed, and only
612
+ * ever on the tail block; starting a new tail block rewrites the header. So every commit above
613
+ * the header's served revision sits in the tail block the header names, or past it. The header is
614
+ * current through that tail when the tail is still the last block (no `nextId`, so nothing rolled
615
+ * over since) and none of its entries above the header's revision changed the header. Otherwise
616
+ * the header is not kept, and the next read of it goes to storage pinned at the adopted revision.
617
+ *
618
+ * Cautious by design: an entry above the ADOPTED revision refuses too, as does a header served by
619
+ * a machine behind the log. Either costs one read of the header; neither keeps a wrong one. */
620
+ private static headerCurrentThroughTail;
621
+ /** Whether the log `entry` changed `blockId`: an action that wrote it, or an invalidation that
622
+ * reverted it. A checkpoint changes no block but the log block it is appended to. */
623
+ private static entryChanges;
577
624
  /** The revision each action in `context` committed at, keyed by action id. `Log.getFrom` returns
578
625
  * entries without their revisions; the context the same walk built is where they are restated. */
579
626
  private static revisionsByAction;
@@ -1032,11 +1079,12 @@ export declare class Collection<TAction> implements ICollection<TAction> {
1032
1079
  * letting that walk stop short, read the known tail in its own request instead.
1033
1080
  *
1034
1081
  * `tailFloor` (see {@link updateInternal}) goes on whichever request reads the tail — never on
1035
- * the header, which is rewritten only when the tail rolls over, so its revision says nothing about
1036
- * the collection's. It is not raised into the handle's {@link floors}: a standing floor on the tail
1037
- * id this handle remembers would be wrong once that tail rolls over, because a filled tail's last
1038
- * revision is the roll-over's, below the floor, so every later read of it (the chain walk, the
1039
- * invalidation walk) would be judged too old for the life of the handle.
1082
+ * the header, which is rewritten only when the tail rolls over or the collection changes it
1083
+ * itself (a tree's root moving), so its revision says nothing about the collection's. It is not
1084
+ * raised into the handle's {@link floors}: a standing floor on the tail id this handle remembers
1085
+ * would be wrong once that tail rolls over, because a filled tail's last revision is the
1086
+ * roll-over's, below the floor, so every later read of it (the chain walk, the invalidation walk)
1087
+ * would be judged too old for the life of the handle.
1040
1088
  *
1041
1089
  * @returns undefined when the header is authoritatively absent. */
1042
1090
  private static readLogEnds;
@@ -1 +1 @@
1
- {"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../../src/collection/collection.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../../src/collection/collection.ts"],"names":[],"mappings":"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"}
@@ -188,15 +188,15 @@ export class Collection {
188
188
  // wires up and the log-attach-time lines included — names the instance the same way
189
189
  // post-construction ones do.
190
190
  const instanceTag = Collection.newInstanceTag();
191
- const { source, sourceCache, tracker, floors, header } = await Collection.probeHeader(transactor, id, instanceTag);
192
- if (!header) {
191
+ const { source, sourceCache, tracker, floors, ends } = await Collection.probeHeader(transactor, id, instanceTag);
192
+ if (!ends) {
193
193
  // Return before anything is staged: the tracker's transforms stay empty, so a caller
194
194
  // that ignores the undefined cannot later sync a phantom collection into existence.
195
195
  return undefined;
196
196
  }
197
- await Collection.attachToLog(source, transactor, tracker, id, instanceTag, header);
197
+ await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends);
198
198
  const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, instanceTag);
199
- collection.logTailId = header.tailId;
199
+ collection.logTailId = ends.header.tailId;
200
200
  return collection;
201
201
  }
202
202
  /** Open an existing collection, or stage a fresh empty one in the local tracker when the
@@ -208,9 +208,9 @@ export class Collection {
208
208
  static async createOrOpen(transactor, id, init) {
209
209
  // Pre-construction for the same reason as in open(): see the comment there.
210
210
  const instanceTag = Collection.newInstanceTag();
211
- const { source, sourceCache, tracker, floors, header } = await Collection.probeHeader(transactor, id, instanceTag);
212
- if (header) { // Collection already exists
213
- await Collection.attachToLog(source, transactor, tracker, id, instanceTag, header);
211
+ const { source, sourceCache, tracker, floors, ends } = await Collection.probeHeader(transactor, id, instanceTag);
212
+ if (ends) { // Collection already exists
213
+ await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends);
214
214
  }
215
215
  else { // Collection does not exist
216
216
  log('collection:invented id=%s — no committed header found; staging a fresh empty collection', id);
@@ -220,7 +220,7 @@ export class Collection {
220
220
  await Log.open(tracker, id);
221
221
  }
222
222
  const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, instanceTag);
223
- collection.logTailId = header?.tailId;
223
+ collection.logTailId = ends?.header.tailId;
224
224
  return collection;
225
225
  }
226
226
  /** The committed tail of `id` — the tail block id its header names and that block's latest
@@ -242,8 +242,18 @@ export class Collection {
242
242
  const rev = ends?.tail?.state.latest?.rev;
243
243
  return tailId === undefined || rev === undefined ? undefined : { tailId, rev };
244
244
  }
245
- /** The per-instance read wiring every open path needs, plus the header probe result.
246
- * Shared by {@link open} and {@link createOrOpen} so the two cannot drift. */
245
+ /** The per-instance read wiring every open path needs, plus the collection's log ends — the
246
+ * header, then the log tail block it names — read by {@link readLogEnds}, the reader every
247
+ * refresh uses. Two requests: the tail id is known only from the header, so an open cannot ask
248
+ * for both in one the way a refresh can. `ends` is `undefined` when the header is
249
+ * authoritatively absent. Shared by {@link open} and {@link createOrOpen} so the two cannot drift.
250
+ *
251
+ * The header used to be probed through `source.tryGet`, an unpinned read on a handle with no
252
+ * floors yet. That decided nothing {@link readLogEnds} does not decide — `answeredBlock(id, entry,
253
+ * undefined)` is the whole of its verdict for such a read, so an unretrievable or doubted header
254
+ * throws exactly as it did — except recording the header as a read dependency, which the walk's
255
+ * first read of it through the handle's cache now records, at the revision it was served at
256
+ * (see {@link attachToLog}). */
247
257
  static async probeHeader(transactor, id, instanceTag) {
248
258
  // Start with a context that has an infinite revision number to ensure that we always fetch the latest log information.
249
259
  // One shared read-dependency collector feeds both the source (direct structural reads) and the cache (every
@@ -253,8 +263,8 @@ export class Collection {
253
263
  const source = new TransactorSource(id, transactor, undefined, collector, floors);
254
264
  const sourceCache = new CacheSource(source, undefined, collector);
255
265
  const tracker = new Tracker(sourceCache);
256
- const header = await source.tryGet(id);
257
- return { source, sourceCache, tracker, floors, header };
266
+ const ends = await Collection.readLogEnds(transactor, id, undefined);
267
+ return { source, sourceCache, tracker, floors, ends };
258
268
  }
259
269
  /** A new handle's floors: none yet (opening walks no entries), wired to report every below-floor
260
270
  * answer any of the handle's read sources receives. The line is the only trace such an answer
@@ -269,15 +279,20 @@ export class Collection {
269
279
  }
270
280
  /** Walk an existing collection's log and point the source at its latest action context.
271
281
  * A header we just probed successfully but whose log will not open is a fault, not an
272
- * absence — throw rather than let the collection read as empty. (The re-read goes through
273
- * the tracker/cache, so it can disagree with the probe when storage is flaky mid-open.) */
274
- static async attachToLog(source, transactor, tracker, id,
282
+ * absence — throw rather than let the collection read as empty. (A header {@link keepLogEnds}
283
+ * declines to keep is re-read through the tracker/cache, so it can disagree with the probe when
284
+ * storage is flaky mid-open.) */
285
+ static async attachToLog(source, sourceCache, tracker, floors, id,
275
286
  /** The tag the calling open path minted for the Collection it is ABOUT to construct, so a
276
287
  * diagnostic emitted here carries the same instance name as every post-construction one. */
277
- instanceTag, header) {
288
+ instanceTag, ends) {
278
289
  // Bootstrap ActionContext from the committed tail before walking the chain.
279
290
  // This allows the transactor to serve pending non-tail blocks during Log.open.
280
- Collection.bootstrapContext(source, header.tailId === undefined ? undefined : await Collection.readLogTail(transactor, header.tailId));
291
+ Collection.bootstrapContext(source, ends.tail);
292
+ // The walk starts from the header and the tail, which the probe just read: keep them, so the
293
+ // walk reads neither again. Its first read of each through the cache then records the read
294
+ // dependency the probe's own read of the header used to.
295
+ Collection.keepLogEnds(sourceCache, floors, source.actionContext, ends);
281
296
  const collectionLog = await Log.open(tracker, id);
282
297
  if (!collectionLog) {
283
298
  throw new Error(`Log not found for collection ${id}`);
@@ -798,8 +813,11 @@ export class Collection {
798
813
  // the entry walk and the invalidation walk each start again from the header and the tail, and
799
814
  // would otherwise fetch both every time. The seed came from UNPINNED reads and is served to
800
815
  // reads pinned at the tail's claim, which is sound: the tail's content at its own claimed
801
- // revision is that pinned view, and the header changes only when the tail block fills, which
802
- // Chain.getTail already tolerates by following `nextId` from whichever tail the header names.
816
+ // revision is that pinned view, and the only part of the header a log walk reads — where the
817
+ // chain starts and ends — changes only when the tail block fills, which Chain.getTail already
818
+ // tolerates by following `nextId` from whichever tail the header names. (The rest of the header,
819
+ // a tree's root for one, is not read here; the handle's own cache keeps the header only under
820
+ // the stricter rule in {@link keepLogEnds}.)
803
821
  // NOTE: the cache keeps its default size (128 blocks, about 4,000 log entries). The entry walk
804
822
  // reads every log block back to the head (no checkpoints), newest first, so past that size
805
823
  // the newest blocks are evicted first and the invalidation walk fetches them again. If logs
@@ -848,7 +866,7 @@ export class Collection {
848
866
  if (invalidations.length > 0 && this.pending.length > 0) {
849
867
  anyConflicts = true;
850
868
  }
851
- this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends.served);
869
+ this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
852
870
  Collection.reportShortfall(this.id, this.instanceTag, tailRev, actionContext?.rev, this.source.actionContext?.rev);
853
871
  // Re-stage the pending actions against the adopted revision. The affected
854
872
  // blocks were already dropped from sourceCache above (per log entry / per invalidation),
@@ -865,7 +883,7 @@ export class Collection {
865
883
  }
866
884
  /** Forget every block the refresh saw change, floor the ones a log entry names, adopt the
867
885
  * revision the log is at, and keep what the refresh already read
868
- * ({@link keepWhatTheRefreshRead}) — ONE synchronous step, which must stay free of any `await`.
886
+ * ({@link keepLogEnds}) — ONE synchronous step, which must stay free of any `await`.
869
887
  *
870
888
  * Reads are not latched, so one can run while a refresh is under way. Forgetting a block while
871
889
  * this handle still reads at the revision it is LEAVING invites exactly the wrong re-read: the
@@ -883,68 +901,116 @@ export class Collection {
883
901
  * one; neither is grounds for forgetting the revision held. It also has to precede
884
902
  * {@link replayActions}, which re-reads blocks through `this.source` at whatever revision the
885
903
  * context names — replaying first would refill the cache at the revision being left. */
886
- forgetAndAdopt(latest, entryRevs, revertedBlockIds, served) {
904
+ forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends) {
887
905
  for (const entry of latest?.entries ?? []) {
888
906
  this.sourceCache.clear(entry.blockIds);
889
907
  this.raiseFloors(entry, entryRevs.get(entry.actionId));
890
908
  }
891
909
  this.sourceCache.clear(revertedBlockIds);
892
910
  Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context);
893
- this.keepWhatTheRefreshRead(served);
911
+ Collection.keepLogEnds(this.sourceCache, this.floors, this.source.actionContext, ends);
894
912
  }
895
- /** Put the header and log tail block {@link readLogEnds} already fetched into this handle's own
913
+ /** Put the header and log tail block {@link readLogEnds} already fetched into a handle's own
896
914
  * cache, so the next read of either is a hit rather than a second fetch of a block just
897
- * received. Without it, a write that follows ANOTHER handle's commit fetches the log tail twice:
898
- * the refresh reads it, the walked entry names it (a commit's blocks include the log block its
899
- * entry was appended to) so the clear above drops it, and `Chain.add` then reads it again to
900
- * append this write's own entry.
901
- *
902
- * Last in {@link forgetAndAdopt}'s one synchronous step, after BOTH clears — offering before
903
- * either would simply be undone by it. An id that an invalidation reverted is therefore
904
- * re-offered rather than left forgotten, which is sound because the revert is itself a commit
905
- * and {@link readLogEnds} read unpinned: what it read already includes the revert.
906
- *
907
- * An offer is made only when all three hold:
908
- * - **This handle holds a context.** With none adopted, every later read is unpinned and may
915
+ * received. Two sites, one rule:
916
+ * - **An open** ({@link attachToLog}), before the walk: `Log.open` and the tail lookup behind
917
+ * the context start from exactly these two blocks, and would otherwise fetch both again.
918
+ * - **A refresh that walked** ({@link forgetAndAdopt}). Without it, a write that follows ANOTHER
919
+ * handle's commit fetches the log tail twice: the refresh reads it, the walked entry names it
920
+ * (a commit's blocks include the log block its entry was appended to) so the clear drops it,
921
+ * and `Chain.add` then reads it again to append this write's own entry. Last in that one
922
+ * synchronous step, after BOTH clears — offering before either would simply be undone by it.
923
+ * An id that an invalidation reverted is therefore re-offered rather than left forgotten, which
924
+ * is sound because the revert is itself a commit and {@link readLogEnds} read unpinned: what it
925
+ * read already includes the revert.
926
+ *
927
+ * Static, taking the cache, the floors and the context rather than `this`, because an open keeps
928
+ * before the handle is constructed.
929
+ *
930
+ * An offer is made only when all of these hold:
931
+ * - **The handle holds a context.** With none adopted, every later read is unpinned and may
909
932
  * legitimately be answered newer than what was read here, so there is nothing to judge the
910
933
  * offer against.
911
934
  * - **The served revision is at or below the adopted one.** {@link readLogEnds} reads unpinned,
912
- * so it can come back newer than the view this handle now reads at — exactly the
935
+ * so it can come back newer than the view the handle now reads at — exactly the
913
936
  * `collection:context-short-of-tail` case. Serving that to a read pinned lower would fabricate
914
937
  * a view that never existed. At or below the pin it is sound: a block whose newest content is
915
938
  * at `rev <= context.rev` has the same content at `context.rev`.
916
939
  * - **The served revision meets any applicable floor.** A cache must never keep a below-floor
917
940
  * answer.
941
+ * - **For the header, nothing rewrote it after it was read** ({@link headerCurrentThroughTail}).
942
+ * "Newest at `rev`" above holds for each block at the moment it was read, and the header and
943
+ * the tail are not read at one moment.
918
944
  *
919
945
  * NOTE: the floor check lives here because {@link readLogEnds} reads around
920
946
  * {@link TransactorSource}, which is what applies floors on every other read — nothing else on
921
947
  * this path would apply one. It asks {@link BlockFloors.meetsApplicableFloor} rather than
922
948
  * spelling the comparison out, so it cannot drift from the one `answeredBelowFloor` makes, and
923
949
  * asks the non-reporting face because this is not an answer being served to a reader — the
924
- * `collection:block-below-floor` line would misdescribe it.
925
- *
926
- * Only this site seeds. The early return at {@link tailShowsNothingNewer} is deliberately left
927
- * alone: it fires when the log has not moved, and the cache is then already warm with the tail
928
- * (folded in by this handle's own commit, or kept from its last walk), so seeding there would
929
- * buy a fetch back only when the LRU had evicted it — at the cost of putting the one-synchronous-
930
- * step reasoning in a second place. */
950
+ * `collection:block-below-floor` line would misdescribe it. An opening handle has no floors yet,
951
+ * so there the check passes by construction.
952
+ *
953
+ * The early return at {@link tailShowsNothingNewer} deliberately does not keep: it fires when
954
+ * the log has not moved, and the cache is then already warm with the tail (folded in by this
955
+ * handle's own commit, or kept from its last walk or its open), so keeping there would buy a
956
+ * fetch back only when the LRU had evicted it — at the cost of putting the one-synchronous-step
957
+ * reasoning in a second place. */
931
958
  // NOTE: an offer whose revision equals what the cache already holds is still kept, so a walking
932
959
  // refresh bumps the header's generation even when the header was neither cleared nor changed.
933
960
  // Over-bumping is safe (see `CacheSource.bump`) and costs a re-materialize of that block on its
934
961
  // next read; if that ever shows up, skip the offer when the cache already RETAINS the id at the
935
962
  // same revision — but note it would then also stop correcting a cached block whose content was
936
963
  // folded forward locally at that revision.
937
- keepWhatTheRefreshRead(served) {
938
- const context = this.source.actionContext;
964
+ static keepLogEnds(cache, floors, context, ends) {
939
965
  if (context === undefined) {
940
966
  return;
941
967
  }
942
- for (const [blockId, block, rev] of served) {
943
- if (rev <= context.rev && this.floors.meetsApplicableFloor(blockId, context, rev)) {
944
- this.sourceCache.offerServed(blockId, block, rev);
968
+ const headerId = ends.header.header.id;
969
+ const keepHeader = Collection.headerCurrentThroughTail(ends);
970
+ for (const [blockId, block, rev] of ends.served) {
971
+ if ((blockId !== headerId || keepHeader) && rev <= context.rev && floors.meetsApplicableFloor(blockId, context, rev)) {
972
+ cache.offerServed(blockId, block, rev);
945
973
  }
946
974
  }
947
975
  }
976
+ /** Whether the header {@link readLogEnds} read is still the header at the revision of the tail
977
+ * block it read — what {@link keepLogEnds}' revision test cannot see for the header.
978
+ *
979
+ * That test keeps a block served at or below the adopted revision because a block whose newest
980
+ * content is at `rev` has the same content at every later revision. "Newest" held when the block
981
+ * was read, and the header and the tail are not read at one moment: an open asks for the tail in
982
+ * a second request, so does a refresh whose remembered tail is out of date, and even the
983
+ * refresh's one batched request may be answered by two machines. A commit that lands between the
984
+ * two reads and rewrites the header — a log roll-over (the header names the tail block) or a tree
985
+ * whose root moved (a tree's header names its root) — leaves the context adopted from the tail
986
+ * at that commit's revision while the header read before it is served there as if current. Kept,
987
+ * the handle would read the tree through a root it no longer has, and a write that changes the
988
+ * header again would be refused by storage's base guard and retried.
989
+ *
990
+ * Every commit and every invalidation appends an entry naming the blocks it changed, and only
991
+ * ever on the tail block; starting a new tail block rewrites the header. So every commit above
992
+ * the header's served revision sits in the tail block the header names, or past it. The header is
993
+ * current through that tail when the tail is still the last block (no `nextId`, so nothing rolled
994
+ * over since) and none of its entries above the header's revision changed the header. Otherwise
995
+ * the header is not kept, and the next read of it goes to storage pinned at the adopted revision.
996
+ *
997
+ * Cautious by design: an entry above the ADOPTED revision refuses too, as does a header served by
998
+ * a machine behind the log. Either costs one read of the header; neither keeps a wrong one. */
999
+ static headerCurrentThroughTail(ends) {
1000
+ const tail = ends.tail?.block;
1001
+ const headerId = ends.header.header.id;
1002
+ const headerRev = ends.served.find(([blockId]) => blockId === headerId)?.[2];
1003
+ if (!tail || tail.nextId !== undefined || headerRev === undefined) {
1004
+ return false;
1005
+ }
1006
+ return !tail.entries.some(entry => entry.rev > headerRev && Collection.entryChanges(entry, headerId));
1007
+ }
1008
+ /** Whether the log `entry` changed `blockId`: an action that wrote it, or an invalidation that
1009
+ * reverted it. A checkpoint changes no block but the log block it is appended to. */
1010
+ static entryChanges(entry, blockId) {
1011
+ return (entry.action?.blockIds.includes(blockId) ?? false)
1012
+ || (entry.invalidation?.reverted.some(reverted => reverted.blockId === blockId) ?? false);
1013
+ }
948
1014
  /** The revision each action in `context` committed at, keyed by action id. `Log.getFrom` returns
949
1015
  * entries without their revisions; the context the same walk built is where they are restated. */
950
1016
  static revisionsByAction(context) {
@@ -1951,11 +2017,12 @@ export class Collection {
1951
2017
  * letting that walk stop short, read the known tail in its own request instead.
1952
2018
  *
1953
2019
  * `tailFloor` (see {@link updateInternal}) goes on whichever request reads the tail — never on
1954
- * the header, which is rewritten only when the tail rolls over, so its revision says nothing about
1955
- * the collection's. It is not raised into the handle's {@link floors}: a standing floor on the tail
1956
- * id this handle remembers would be wrong once that tail rolls over, because a filled tail's last
1957
- * revision is the roll-over's, below the floor, so every later read of it (the chain walk, the
1958
- * invalidation walk) would be judged too old for the life of the handle.
2020
+ * the header, which is rewritten only when the tail rolls over or the collection changes it
2021
+ * itself (a tree's root moving), so its revision says nothing about the collection's. It is not
2022
+ * raised into the handle's {@link floors}: a standing floor on the tail id this handle remembers
2023
+ * would be wrong once that tail rolls over, because a filled tail's last revision is the
2024
+ * roll-over's, below the floor, so every later read of it (the chain walk, the invalidation walk)
2025
+ * would be judged too old for the life of the handle.
1959
2026
  *
1960
2027
  * @returns undefined when the header is authoritatively absent. */
1961
2028
  static async readLogEnds(transactor, id, knownTailId, tailFloor) {