@optimystic/db-core 1.4.0 → 1.5.1

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 (157) hide show
  1. package/README.md +336 -336
  2. package/dist/src/collection/collection.d.ts +44 -4
  3. package/dist/src/collection/collection.d.ts.map +1 -1
  4. package/dist/src/collection/collection.js +95 -14
  5. package/dist/src/collection/collection.js.map +1 -1
  6. package/dist/src/collections/tree/struct.d.ts +9 -4
  7. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  8. package/dist/src/collections/tree/struct.js +9 -4
  9. package/dist/src/collections/tree/struct.js.map +1 -1
  10. package/dist/src/log/log.d.ts +41 -8
  11. package/dist/src/log/log.d.ts.map +1 -1
  12. package/dist/src/log/log.js +15 -10
  13. package/dist/src/log/log.js.map +1 -1
  14. package/dist/src/testing/test-transactor.d.ts +36 -0
  15. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  16. package/dist/src/testing/test-transactor.js +49 -0
  17. package/dist/src/testing/test-transactor.js.map +1 -1
  18. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  19. package/dist/src/transaction/coordinator.js +26 -9
  20. package/dist/src/transaction/coordinator.js.map +1 -1
  21. package/package.json +1 -1
  22. package/src/blocks/block-store.ts +31 -31
  23. package/src/blocks/block-types.ts +11 -11
  24. package/src/blocks/index.ts +5 -5
  25. package/src/blocks/structs.ts +17 -17
  26. package/src/btree/btree.ts +872 -872
  27. package/src/btree/independent-trunk.ts +53 -53
  28. package/src/btree/index.ts +5 -5
  29. package/src/btree/key-range.ts +15 -15
  30. package/src/btree/keyset.ts +6 -6
  31. package/src/btree/nodes.ts +25 -25
  32. package/src/btree/path.ts +37 -37
  33. package/src/btree/tree-block.ts +11 -11
  34. package/src/btree/trunk.ts +14 -14
  35. package/src/chain/chain-nodes.ts +26 -26
  36. package/src/chain/chain.ts +349 -349
  37. package/src/chain/index.ts +3 -3
  38. package/src/cluster/i-cluster.ts +6 -6
  39. package/src/cluster/index.ts +3 -3
  40. package/src/cohort-topic/addressing.ts +120 -120
  41. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  42. package/src/cohort-topic/antidos/index.ts +5 -5
  43. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  44. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  45. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  46. package/src/cohort-topic/antiflood/index.ts +2 -2
  47. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  48. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  49. package/src/cohort-topic/coldstart.ts +237 -237
  50. package/src/cohort-topic/dmax.ts +88 -88
  51. package/src/cohort-topic/gossip/bus.ts +254 -254
  52. package/src/cohort-topic/gossip/index.ts +3 -3
  53. package/src/cohort-topic/gossip/records.ts +45 -45
  54. package/src/cohort-topic/gossip/view.ts +91 -91
  55. package/src/cohort-topic/index.ts +20 -20
  56. package/src/cohort-topic/load/barometer.ts +134 -134
  57. package/src/cohort-topic/load/index.ts +1 -1
  58. package/src/cohort-topic/member-engine.ts +430 -430
  59. package/src/cohort-topic/membership/index.ts +3 -3
  60. package/src/cohort-topic/membership/publisher.ts +163 -163
  61. package/src/cohort-topic/membership/source.ts +41 -41
  62. package/src/cohort-topic/ports.ts +157 -157
  63. package/src/cohort-topic/promotion.ts +477 -477
  64. package/src/cohort-topic/registration/bytes.ts +37 -37
  65. package/src/cohort-topic/registration/handoff.ts +154 -154
  66. package/src/cohort-topic/registration/index.ts +6 -6
  67. package/src/cohort-topic/registration/renewal.ts +495 -495
  68. package/src/cohort-topic/registration/sharding.ts +61 -61
  69. package/src/cohort-topic/registration/store.ts +81 -81
  70. package/src/cohort-topic/registration/types.ts +91 -91
  71. package/src/cohort-topic/ring-hash.ts +50 -50
  72. package/src/cohort-topic/service.ts +416 -416
  73. package/src/cohort-topic/sig/index.ts +2 -2
  74. package/src/cohort-topic/sig/payloads.ts +59 -59
  75. package/src/cohort-topic/sig/threshold.ts +64 -64
  76. package/src/cohort-topic/tiers.ts +74 -74
  77. package/src/cohort-topic/traffic.ts +233 -233
  78. package/src/cohort-topic/walk.ts +326 -326
  79. package/src/cohort-topic/willingness.ts +237 -237
  80. package/src/cohort-topic/wire/index.ts +18 -18
  81. package/src/cohort-topic/wire/payloads.ts +126 -126
  82. package/src/collection/action.ts +48 -48
  83. package/src/collection/collection-type-registry.ts +37 -37
  84. package/src/collection/collection.ts +2203 -2118
  85. package/src/collection/index.ts +4 -4
  86. package/src/collections/diary/index.ts +2 -2
  87. package/src/collections/diary/struct.ts +3 -3
  88. package/src/collections/index.ts +2 -2
  89. package/src/collections/tree/collection-trunk.ts +25 -25
  90. package/src/collections/tree/index.ts +2 -2
  91. package/src/collections/tree/readme.md +55 -55
  92. package/src/collections/tree/struct.ts +9 -4
  93. package/src/log/index.ts +2 -2
  94. package/src/log/log.ts +304 -268
  95. package/src/log/struct.ts +165 -165
  96. package/src/matchmaking/capability-filter.ts +45 -45
  97. package/src/matchmaking/config.ts +98 -98
  98. package/src/matchmaking/index.ts +21 -21
  99. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  100. package/src/matchmaking/provider.ts +123 -123
  101. package/src/matchmaking/query-eval.ts +105 -105
  102. package/src/matchmaking/seeker-walk.ts +127 -127
  103. package/src/matchmaking/seeker.ts +86 -86
  104. package/src/matchmaking/topic-anchor.ts +90 -90
  105. package/src/matchmaking/voting-quorum.ts +394 -394
  106. package/src/network/i-peer-network.ts +25 -25
  107. package/src/network/repo-protocol.ts +13 -13
  108. package/src/network/types.ts +37 -37
  109. package/src/reactivity/backfill.ts +220 -220
  110. package/src/reactivity/backpressure.ts +191 -191
  111. package/src/reactivity/checkpoint.ts +308 -308
  112. package/src/reactivity/config.ts +172 -172
  113. package/src/reactivity/dedupe.ts +132 -132
  114. package/src/reactivity/forwarder.ts +87 -87
  115. package/src/reactivity/index.ts +34 -34
  116. package/src/reactivity/notification.ts +123 -123
  117. package/src/reactivity/policy.ts +79 -79
  118. package/src/reactivity/push-state.ts +310 -310
  119. package/src/reactivity/recover.ts +153 -153
  120. package/src/reactivity/replay-buffer.ts +141 -141
  121. package/src/reactivity/resume.ts +549 -549
  122. package/src/reactivity/rotation.ts +415 -415
  123. package/src/reactivity/subscriber.ts +132 -132
  124. package/src/reactivity/subscription.ts +66 -66
  125. package/src/reactivity/topic-anchor.ts +71 -71
  126. package/src/reactivity/verify.ts +73 -73
  127. package/src/reactivity/wire-validate.ts +13 -13
  128. package/src/testing/async-wait.ts +65 -65
  129. package/src/testing/index.ts +2 -2
  130. package/src/testing/test-transactor.ts +62 -0
  131. package/src/transaction/actions-engine.ts +68 -68
  132. package/src/transaction/coordinator.ts +28 -11
  133. package/src/transaction/index.ts +52 -52
  134. package/src/transaction/operations-hash.ts +196 -196
  135. package/src/transaction/read-dependency-collector.ts +78 -78
  136. package/src/transaction/session.ts +238 -238
  137. package/src/transaction/transaction.ts +442 -442
  138. package/src/transaction/validator.ts +197 -197
  139. package/src/transactor/block-floors.ts +126 -126
  140. package/src/transactor/index.ts +6 -6
  141. package/src/transactor/network-transactor.ts +1545 -1545
  142. package/src/transform/atomic-proxy.ts +92 -92
  143. package/src/transform/cache-source.ts +370 -370
  144. package/src/transform/helpers.ts +164 -164
  145. package/src/transform/index.ts +7 -7
  146. package/src/transform/struct.ts +21 -21
  147. package/src/utility/actor.ts +62 -62
  148. package/src/utility/backoff.ts +95 -95
  149. package/src/utility/batch-coordinator.ts +191 -191
  150. package/src/utility/ensured.ts +32 -32
  151. package/src/utility/groupby.ts +18 -18
  152. package/src/utility/hash-string.ts +14 -14
  153. package/src/utility/is-record-empty.ts +5 -5
  154. package/src/utility/latches.ts +42 -42
  155. package/src/utility/lru-map.ts +60 -60
  156. package/src/utility/nameof.ts +7 -7
  157. package/src/utility/pending.ts +43 -43
@@ -1,370 +1,370 @@
1
- import type { IBlock, BlockHeader, BlockId, BlockSource, BlockType, ReadPurpose, Transforms } from "../index.js";
2
- import { applyOperation } from "./helpers.js";
3
- import { LruMap } from "../utility/lru-map.js";
4
- import { createLogger } from "../logger.js";
5
- import type { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
6
-
7
- const log = createLogger('cache');
8
-
9
- const DefaultMaxSize = 128;
10
-
11
- /** The revision a source reports for an id, or undefined if the source can't report one.
12
- * Duck-typed exactly like {@link Tracker}'s getGeneration probe — CacheSource layers over
13
- * arbitrary BlockSources (including test doubles) that need not implement it. */
14
- function sourceReadRevision(source: unknown, id: BlockId): number | undefined {
15
- const src = source as { getReadRevision?: (id: BlockId) => number | undefined };
16
- return typeof src.getReadRevision === 'function' ? src.getReadRevision(id) : undefined;
17
- }
18
-
19
- /** What the source says about `block`, the object it just returned for `id`: the revision the
20
- * content is, and whether it may be kept and served again without re-asking.
21
- *
22
- * Prefers the source's per-OBJECT answer (`describeServed`, which TransactorSource provides) over
23
- * the by-id {@link sourceReadRevision}. This runs after an `await`, so with two reads of one id in
24
- * flight a by-id record describes whichever answer the source processed last — not necessarily
25
- * this one — and would stamp one answer's content with the other's revision and verdict. A source
26
- * that offers neither allows keeping at revision 0, the behaviour before either probe existed. */
27
- function sourceServed(source: unknown, id: BlockId, block: IBlock): { rev: number; mayRetain: boolean } {
28
- const src = source as { describeServed?: (block: IBlock) => { rev: number; mayRetain: boolean } | undefined };
29
- const described = typeof src.describeServed === 'function' ? src.describeServed(block) : undefined;
30
- return described ?? { rev: sourceReadRevision(source, id) ?? 0, mayRetain: true };
31
- }
32
-
33
- export class CacheSource<T extends IBlock> implements BlockSource<T> {
34
- protected cache: LruMap<BlockId, T>;
35
- /** Per-id monotonic counter, bumped whenever the cached content for an id changes.
36
- * Consumers (e.g. {@link Tracker}'s materialized-block memo) read it via
37
- * {@link getGeneration} to detect that a cached "source + ops" result has gone stale.
38
- * Over-bumping is safe (it only forces a re-materialize); under-bumping is a correctness
39
- * bug, so every content-changing site bumps. A benign LRU evict + reload also bumps. */
40
- // NOTE: generations is never pruned — it retains one small (id → number) entry per distinct id
41
- // ever touched, even after LRU eviction from `cache`. Bounded by the number of distinct blocks a
42
- // collection sees over its lifetime; if that ever grows large enough to matter, evict alongside
43
- // the LRU (dropping a generation is safe — a reload re-bumps from 0/absent, forcing re-materialize).
44
- private generations = new Map<BlockId, number>();
45
- /** Per-id committed revision of the content currently cached for that id. Learned from the
46
- * source on a miss-load, advanced by {@link transformCache} when a commit folds new content
47
- * in, and dropped alongside the cached block on delete/clear. Re-emitted on every cache HIT
48
- * so a hit records a read dependency at the right revision — the whole point of this map, since
49
- * the underlying source is never consulted on a hit. */
50
- // NOTE: an LRU-evicted id keeps its `revisions` entry (eviction drops `cache` but not this map).
51
- // That lingering entry is LOAD-BEARING, not a leak: every path that serves or forgets content for
52
- // an id writes this map in the same step (keep, handThrough, clear, transformCache), so the entry
53
- // is always the revision of the content LAST SERVED for the id — which is exactly what a write
54
- // staged over a since-evicted read needs to declare as its base (a rev-only pin, see
55
- // `PinnedBase.block` in base-pins.ts). Only `peek` pairs a revision with content, and it answers
56
- // nothing for an evicted id, so the revision never pairs with a block it does not describe.
57
- private revisions = new Map<BlockId, number>();
58
- /** The most recent answer per id that this cache returned to a reader but did not keep — a
59
- * below-floor answer, content older than a log entry the collection already walked says the
60
- * block is (see {@link sourceServed}), or an answer overtaken while in flight over an id nothing
61
- * is held for (see {@link admit}). NEVER served to a read: {@link tryGet} re-asks the source
62
- * every time such an id is read, which is the whole point. It exists for the base probes alone
63
- * ({@link peek} / {@link getCachedRevision}): a write staged over this content must declare the
64
- * base it was really built on, at the revision it was really served at, so that the storage-side
65
- * guard which refuses a transform whose declared base is not the one the member holds can fire
66
- * instead of abstaining and applying edits computed against the old content over newer content.
67
- * An id is never in both this map and `cache`/`revisions`. It leaves on its next keepable answer,
68
- * on {@link clear}, and on any {@link transformCache} that touches it, so the map is bounded by
69
- * the source's unmet floors plus the ids caught mid-flight by a clear or a fold. */
70
- private unkept = new Map<BlockId, { block: T; rev: number }>();
71
-
72
- constructor(
73
- protected readonly source: BlockSource<T>,
74
- maxSize = DefaultMaxSize,
75
- /** Shared per-transaction read-dependency accumulator (same instance the collection's
76
- * TransactorSource holds). Optional: log-walk caches that never form a transaction omit it. */
77
- private readonly collector?: ReadDependencyCollector,
78
- /** Pre-warm entries: the output of another cache's {@link snapshotEntries} for a pinned read
79
- * view, or the blocks a refresh already fetched for its own log walk
80
- * (`Collection.readLogEnds`). Blocks are adopted BY REFERENCE — a seeder that keeps its own
81
- * handle on one must not mutate it, which is why {@link offerServed}, whose caller does keep
82
- * one, clones instead. Per-id revisions ride along so a seeded HIT still records at the
83
- * revision the block was committed at. Seeding does not bump generations (a fresh
84
- * cache has no consumers with stale memos). */
85
- seed?: ReadonlyArray<[BlockId, T, number]>,
86
- ) {
87
- this.cache = new LruMap(maxSize);
88
- if (seed) {
89
- for (const [id, block, revision] of seed) {
90
- this.cache.set(id, block);
91
- this.revisions.set(id, revision);
92
- }
93
- }
94
- }
95
-
96
- private bump(id: BlockId) {
97
- this.generations.set(id, (this.generations.get(id) ?? 0) + 1);
98
- }
99
-
100
- /** The current generation for an id — advances every time this cache's content for
101
- * the id changes (miss-load, clear, or transformCache). Stable across pure cache hits. */
102
- getGeneration(id: BlockId): number {
103
- return this.generations.get(id) ?? 0;
104
- }
105
-
106
- /** INVARIANT: what a read returns for an id is what this cache then describes for it — the
107
- * block {@link peek} answers and the revision {@link getCachedRevision} answers, immediately
108
- * after, are the content the reader holds, on every path (hit, kept, handed through, evicted
109
- * since). A write staged over the returned content pins that revision as its base, so a read
110
- * that returned one thing while the cache described another would put a wrong base on the
111
- * commit — the one direction the storage-side guard cannot catch. {@link admit} is where the
112
- * two are decided together. */
113
- async tryGet(id: BlockId, purpose: ReadPurpose = 'value'): Promise<T | undefined> {
114
- const hit = this.cache.get(id);
115
- if (hit) {
116
- // Cache hit: the source is never consulted, so re-emit the revision we learned when this
117
- // id was first loaded/folded. Without this a block served from cache records NO read
118
- // dependency (the original bug), so its stale-read check could never fire. Carry the
119
- // caller's purpose so a navigation-only cache hit stays droppable from the conflict set.
120
- const rev = this.revisions.get(id);
121
- if (rev !== undefined) this.collector?.record(id, rev, purpose);
122
- log('hit id=%s', id);
123
- return structuredClone(hit);
124
- }
125
- const generationAtMiss = this.getGeneration(id);
126
- const answer = await this.source.tryGet(id, purpose);
127
- if (!answer) {
128
- // Absent block: record nothing (matches TransactorSource, which skips missing blocks).
129
- log('miss:absent id=%s', id);
130
- return undefined;
131
- }
132
- const { rev, mayRetain } = sourceServed(this.source, id, answer);
133
- const served = this.admit(id, answer, rev, mayRetain, generationAtMiss);
134
- // Record the dependency at the revision RETURNED. On a miss the underlying TransactorSource
135
- // already recorded the answer's own id@rev/purpose into the shared collector; max-wins
136
- // (revision) + value-wins (purpose) collapse the two to one entry, at the higher revision.
137
- this.collector?.record(id, served.rev, purpose);
138
- return structuredClone(served.block);
139
- }
140
-
141
- /** Decide, for an answer the source just gave for `id`, what the reader gets and what this cache
142
- * describes for the id from now on — one decision, so the two cannot come apart.
143
- *
144
- * A keepable answer that is {@link stillWanted} is kept and returned. Otherwise the answer is
145
- * either below its floor or was overtaken while in flight, and of two answers to one id the
146
- * higher revision is the truer — so if content is HELD for the id (a concurrent read answered
147
- * well, a folded commit, or content that met a floor this answer does not), the held content is
148
- * what the reader gets, exactly as a hit a moment later would get it; the answer leaves no trace.
149
- * Held content is never older than a below-floor answer: raising a floor forgets the id in the
150
- * same step, so anything held for it since met the floor. With nothing held, the answer is
151
- * handed through (see {@link handThrough}): returned, described, not kept. */
152
- private admit(id: BlockId, answer: T, rev: number, mayRetain: boolean, generationAtMiss: number): { block: T; rev: number } {
153
- if (mayRetain && this.stillWanted(id, rev, generationAtMiss)) {
154
- this.keep(id, answer, rev, 'miss:loaded');
155
- return { block: answer, rev };
156
- }
157
- const held = this.cache.get(id);
158
- const heldRev = held === undefined ? undefined : this.revisions.get(id);
159
- if (held !== undefined && heldRev !== undefined) {
160
- log('miss:superseded id=%s rev=%d heldRev=%d unkeepable=%s', id, rev, heldRev, !mayRetain);
161
- return { block: held, rev: heldRev };
162
- }
163
- this.handThrough(id, answer, rev);
164
- return { block: answer, rev };
165
- }
166
-
167
- /** Whether an answer at `rev`, asked for when this id's generation was `generationAtMiss`, is
168
- * still one to keep now that it has arrived.
169
- *
170
- * A miss is decided before the `await` and acted on after it. If the generation has not moved,
171
- * nothing happened to the id meanwhile and the answer is kept. If it has — a second read of the
172
- * id landed first, a refresh cleared it, a commit folded in ({@link transformCache}) — this answer
173
- * was asked for in a world that has since changed, and keeping it blindly is how old content gets
174
- * remembered for good: nothing clears a block but a log entry naming it, and that entry may be
175
- * the very thing that moved the generation. So it is then kept only to REPLACE strictly older
176
- * content (every answer to one source is for one view, so of two the higher revision is the
177
- * truer, whichever arrives last); what an overtaken answer's reader gets is {@link admit}'s call.
178
- * Only a CACHED id is compared: `revisions` outlives an LRU-evicted block (see its NOTE). */
179
- private stillWanted(id: BlockId, rev: number, generationAtMiss: number): boolean {
180
- if (this.getGeneration(id) === generationAtMiss) {
181
- return true;
182
- }
183
- const held = this.cache.has(id) ? this.revisions.get(id) : undefined;
184
- const replacesOlder = held !== undefined && held < rev;
185
- if (!replacesOlder) {
186
- log('miss:overtaken id=%s rev=%d heldRev=%s', id, rev, held ?? 'none');
187
- }
188
- return replacesOlder;
189
- }
190
-
191
- /** Adopt an answer some other read already obtained for `id` — the collection header and log
192
- * tail block that `Collection.readLogEnds` fetches AROUND this cache — so the next read of the
193
- * id is a hit rather than a second fetch of a block this handle just received.
194
- *
195
- * Kept only when nothing strictly newer is held ({@link heldRevision}), on the same ground
196
- * {@link admit} stands on: of two answers to one source the higher revision is the truer. The
197
- * block is cloned on the way in — this cache stores the reference, and the caller's array is
198
- * handed to other caches as a seed as well — and goes through {@link keep}, so the generation
199
- * bump, the {@link unkept} eviction and the {@link revisions} entry all happen exactly as they
200
- * do for an answer this cache fetched itself.
201
- *
202
- * The CALLER owns the floor and pin checks. The offered block did not come through this cache's
203
- * source, so `sourceServed` can say nothing about it: there is no `describeServed` record for a
204
- * block the source never returned, and the by-id fallback would describe some other read. */
205
- offerServed(id: BlockId, block: T, rev: number): void {
206
- const heldRev = this.heldRevision(id);
207
- if (heldRev !== undefined && heldRev > rev) {
208
- log('offer:superseded id=%s rev=%d heldRev=%d', id, rev, heldRev);
209
- return;
210
- }
211
- this.keep(id, structuredClone(block), rev, 'offer:kept');
212
- }
213
-
214
- /** The revision of the content this cache HOLDS for `id` right now — cached, or handed through
215
- * unkept — and `undefined` when it holds none. Distinct from {@link getCachedRevision}, which
216
- * also answers for an LRU-evicted id: that revision describes content this cache no longer has,
217
- * so it is the right answer for a base probe and the wrong one for "is there anything here to
218
- * weigh an offer against?". */
219
- // NOTE: the consequence is that an offer over an LRU-evicted id is accepted even when it is
220
- // OLDER than the revision this cache last served for the id — a lagging replica answering the
221
- // unpinned refresh read below what this handle has already seen, with no walked entry to floor
222
- // the block. That is the same answer a pinned re-read of the evicted id would have been kept at,
223
- // so the offer path is no worse than the read path it replaces; if lagging-replica staleness on
224
- // the header or log tail ever shows up, refuse an offer below `getCachedRevision` here (a block
225
- // never goes back a revision, so refusing is always right) rather than adding a floor for it.
226
- private heldRevision(id: BlockId): number | undefined {
227
- return this.cache.has(id) ? this.revisions.get(id) : this.unkept.get(id)?.rev;
228
- }
229
-
230
- /** A keepable answer: cached, and served to every later read of `id` until something clears it.
231
- * `reason` names how the content got here, so a log read to count source loads is not misled by
232
- * an offer this cache never fetched. */
233
- private keep(id: BlockId, block: T, rev: number, reason: 'miss:loaded' | 'offer:kept') {
234
- this.cache.set(id, block);
235
- this.revisions.set(id, rev);
236
- this.unkept.delete(id);
237
- this.bump(id);
238
- log('%s id=%s cacheSize=%d', reason, id, this.cache.size);
239
- }
240
-
241
- /** An answer this cache will not keep, over an id it holds nothing for: returned to this one
242
- * reader and described to the base probes (see {@link unkept}), but the next read of `id` asks
243
- * the source again. Only {@link admit} calls this, after establishing that nothing is held —
244
- * a cached id is never also in {@link unkept}.
245
- *
246
- * Bumped like a load: the answer changes what this cache can say about the id, and the bump is
247
- * what sends a base pin or a materialized memo built on the previous answer back to be
248
- * re-judged. */
249
- private handThrough(id: BlockId, block: T, rev: number) {
250
- this.revisions.delete(id);
251
- this.unkept.set(id, { block, rev });
252
- this.bump(id);
253
- log('miss:unkept id=%s rev=%d', id, rev);
254
- }
255
-
256
- /** The base this cache can describe for `id`, without consulting the source: the cached block,
257
- * or the content last handed through unkept (see {@link unkept}) — either way the content the
258
- * most recent {@link tryGet} of the id returned, unless it has been evicted since. Cloned
259
- * (callers apply ops to it) and recency-neutral ({@link LruMap.peek}) — an observation pass must
260
- * neither pay a network read nor reshape eviction order. Records no read dependency: the caller
261
- * that peeks already read the block through {@link tryGet} (that is how this cache learned it),
262
- * so the dependency exists; a digest pass merely re-describes it. */
263
- peek(id: BlockId): T | undefined {
264
- const block = this.cache.peek(id) ?? this.unkept.get(id)?.block;
265
- return block === undefined ? undefined : structuredClone(block);
266
- }
267
-
268
- /** Whether a later {@link tryGet} of `id` is answered from memory with the content this cache
269
- * holds now. `false` for content handed through unkept, which {@link peek} still describes — so
270
- * a consumer that would FREEZE a read result ({@link Tracker}'s materialized memo) asks this, not
271
- * {@link peek}. Recency-neutral. */
272
- retains(id: BlockId): boolean {
273
- return this.cache.has(id);
274
- }
275
-
276
- /** The committed revision of the content this cache last served for `id` — the source-reported
277
- * materialized revision learned on miss-load (see {@link revisions}) or handed through
278
- * ({@link unkept}), NOT the block's own `state.latest.rev`. Answers for an LRU-evicted id too
279
- * (see the NOTE on {@link revisions}): that is the revision a write staged over the evicted
280
- * read was computed against, and what a rev-only base pin carries. {@link peek} returns
281
- * `undefined` for the evicted id, so the revision never pairs with content it does not describe.
282
- * `undefined` once the id has been cleared or folded away, or if it was never served. */
283
- getCachedRevision(id: BlockId): number | undefined {
284
- return this.revisions.get(id) ?? this.unkept.get(id)?.rev;
285
- }
286
-
287
- /** Upgrade an already-captured read of `id` to a `value` read in the shared collector,
288
- * retaining it in the conflict set. The B-tree point-lookup descent calls this (through the
289
- * Tracker, which forwards) to pin the terminal leaf after recording the interior nodes as
290
- * `navigation`. No-op when no collector is wired (log-walk caches) or the id was never
291
- * recorded. Duck-typed by the Tracker; keep the name in sync with Tracker.markReadValue. */
292
- markReadValue(id: BlockId): void {
293
- this.collector?.markValue(id);
294
- }
295
-
296
- generateId(): BlockId {
297
- return this.source.generateId();
298
- }
299
-
300
- createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader {
301
- return this.source.createBlockHeader(type, newId);
302
- }
303
-
304
- clear(blockIds: BlockId[] | undefined = undefined) {
305
- if (blockIds) {
306
- for (const id of blockIds) {
307
- this.cache.delete(id);
308
- this.revisions.delete(id);
309
- this.unkept.delete(id);
310
- this.bump(id);
311
- }
312
- } else {
313
- for (const [id] of this.cache) {
314
- this.bump(id);
315
- }
316
- for (const id of this.unkept.keys()) {
317
- this.bump(id);
318
- }
319
- this.cache.clear();
320
- this.revisions.clear();
321
- this.unkept.clear();
322
- }
323
- }
324
-
325
- /** A cloned copy of the current cache contents with each id's committed revision, in LRU
326
- * order (oldest first, so replaying into another LruMap preserves eviction order). For
327
- * building a pinned read view ONLY (see {@link Collection.createReadTracker}): pass the
328
- * result as the `seed` of a fresh, PRIVATE CacheSource. Blocks are cloned on the way out,
329
- * so the seeded cache shares no mutable state with this one. */
330
- snapshotEntries(): Array<[BlockId, T, number]> {
331
- const entries: Array<[BlockId, T, number]> = [];
332
- for (const [id, block] of this.cache) {
333
- entries.push([id, structuredClone(block), this.revisions.get(id) ?? 0]);
334
- }
335
- return entries;
336
- }
337
-
338
- /** Mutates the cache without affecting the source. `revision` is the committed revision this
339
- * transform lands at; the stored per-id revision advances to it so a later read records a
340
- * dependency at the NEW revision (recording the old one would spuriously fail validation). */
341
- transformCache(transform: Transforms, revision: number) {
342
- for (const blockId of transform.deletes ?? []) {
343
- this.cache.delete(blockId);
344
- this.revisions.delete(blockId);
345
- this.unkept.delete(blockId);
346
- this.bump(blockId);
347
- }
348
- for (const [, block] of Object.entries(transform.inserts ?? {})) {
349
- this.cache.set(block.header.id, structuredClone(block) as T);
350
- this.revisions.set(block.header.id, revision);
351
- this.unkept.delete(block.header.id);
352
- this.bump(block.header.id);
353
- }
354
- for (const [blockId, operations] of Object.entries(transform.updates ?? {})) {
355
- const block = this.cache.get(blockId);
356
- if (block) {
357
- for (const op of operations) {
358
- applyOperation(block, op);
359
- this.bump(blockId);
360
- }
361
- this.revisions.set(blockId, revision);
362
- } else if (this.unkept.delete(blockId)) {
363
- // The commit superseded the unkept base, and the ops are NOT folded into it: it was
364
- // never trusted as this id's content, so the result would not be either. The id stays
365
- // out of memory and the next read asks the source, which now holds `revision`.
366
- this.bump(blockId);
367
- }
368
- }
369
- }
370
- }
1
+ import type { IBlock, BlockHeader, BlockId, BlockSource, BlockType, ReadPurpose, Transforms } from "../index.js";
2
+ import { applyOperation } from "./helpers.js";
3
+ import { LruMap } from "../utility/lru-map.js";
4
+ import { createLogger } from "../logger.js";
5
+ import type { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
6
+
7
+ const log = createLogger('cache');
8
+
9
+ const DefaultMaxSize = 128;
10
+
11
+ /** The revision a source reports for an id, or undefined if the source can't report one.
12
+ * Duck-typed exactly like {@link Tracker}'s getGeneration probe — CacheSource layers over
13
+ * arbitrary BlockSources (including test doubles) that need not implement it. */
14
+ function sourceReadRevision(source: unknown, id: BlockId): number | undefined {
15
+ const src = source as { getReadRevision?: (id: BlockId) => number | undefined };
16
+ return typeof src.getReadRevision === 'function' ? src.getReadRevision(id) : undefined;
17
+ }
18
+
19
+ /** What the source says about `block`, the object it just returned for `id`: the revision the
20
+ * content is, and whether it may be kept and served again without re-asking.
21
+ *
22
+ * Prefers the source's per-OBJECT answer (`describeServed`, which TransactorSource provides) over
23
+ * the by-id {@link sourceReadRevision}. This runs after an `await`, so with two reads of one id in
24
+ * flight a by-id record describes whichever answer the source processed last — not necessarily
25
+ * this one — and would stamp one answer's content with the other's revision and verdict. A source
26
+ * that offers neither allows keeping at revision 0, the behaviour before either probe existed. */
27
+ function sourceServed(source: unknown, id: BlockId, block: IBlock): { rev: number; mayRetain: boolean } {
28
+ const src = source as { describeServed?: (block: IBlock) => { rev: number; mayRetain: boolean } | undefined };
29
+ const described = typeof src.describeServed === 'function' ? src.describeServed(block) : undefined;
30
+ return described ?? { rev: sourceReadRevision(source, id) ?? 0, mayRetain: true };
31
+ }
32
+
33
+ export class CacheSource<T extends IBlock> implements BlockSource<T> {
34
+ protected cache: LruMap<BlockId, T>;
35
+ /** Per-id monotonic counter, bumped whenever the cached content for an id changes.
36
+ * Consumers (e.g. {@link Tracker}'s materialized-block memo) read it via
37
+ * {@link getGeneration} to detect that a cached "source + ops" result has gone stale.
38
+ * Over-bumping is safe (it only forces a re-materialize); under-bumping is a correctness
39
+ * bug, so every content-changing site bumps. A benign LRU evict + reload also bumps. */
40
+ // NOTE: generations is never pruned — it retains one small (id → number) entry per distinct id
41
+ // ever touched, even after LRU eviction from `cache`. Bounded by the number of distinct blocks a
42
+ // collection sees over its lifetime; if that ever grows large enough to matter, evict alongside
43
+ // the LRU (dropping a generation is safe — a reload re-bumps from 0/absent, forcing re-materialize).
44
+ private generations = new Map<BlockId, number>();
45
+ /** Per-id committed revision of the content currently cached for that id. Learned from the
46
+ * source on a miss-load, advanced by {@link transformCache} when a commit folds new content
47
+ * in, and dropped alongside the cached block on delete/clear. Re-emitted on every cache HIT
48
+ * so a hit records a read dependency at the right revision — the whole point of this map, since
49
+ * the underlying source is never consulted on a hit. */
50
+ // NOTE: an LRU-evicted id keeps its `revisions` entry (eviction drops `cache` but not this map).
51
+ // That lingering entry is LOAD-BEARING, not a leak: every path that serves or forgets content for
52
+ // an id writes this map in the same step (keep, handThrough, clear, transformCache), so the entry
53
+ // is always the revision of the content LAST SERVED for the id — which is exactly what a write
54
+ // staged over a since-evicted read needs to declare as its base (a rev-only pin, see
55
+ // `PinnedBase.block` in base-pins.ts). Only `peek` pairs a revision with content, and it answers
56
+ // nothing for an evicted id, so the revision never pairs with a block it does not describe.
57
+ private revisions = new Map<BlockId, number>();
58
+ /** The most recent answer per id that this cache returned to a reader but did not keep — a
59
+ * below-floor answer, content older than a log entry the collection already walked says the
60
+ * block is (see {@link sourceServed}), or an answer overtaken while in flight over an id nothing
61
+ * is held for (see {@link admit}). NEVER served to a read: {@link tryGet} re-asks the source
62
+ * every time such an id is read, which is the whole point. It exists for the base probes alone
63
+ * ({@link peek} / {@link getCachedRevision}): a write staged over this content must declare the
64
+ * base it was really built on, at the revision it was really served at, so that the storage-side
65
+ * guard which refuses a transform whose declared base is not the one the member holds can fire
66
+ * instead of abstaining and applying edits computed against the old content over newer content.
67
+ * An id is never in both this map and `cache`/`revisions`. It leaves on its next keepable answer,
68
+ * on {@link clear}, and on any {@link transformCache} that touches it, so the map is bounded by
69
+ * the source's unmet floors plus the ids caught mid-flight by a clear or a fold. */
70
+ private unkept = new Map<BlockId, { block: T; rev: number }>();
71
+
72
+ constructor(
73
+ protected readonly source: BlockSource<T>,
74
+ maxSize = DefaultMaxSize,
75
+ /** Shared per-transaction read-dependency accumulator (same instance the collection's
76
+ * TransactorSource holds). Optional: log-walk caches that never form a transaction omit it. */
77
+ private readonly collector?: ReadDependencyCollector,
78
+ /** Pre-warm entries: the output of another cache's {@link snapshotEntries} for a pinned read
79
+ * view, or the blocks a refresh already fetched for its own log walk
80
+ * (`Collection.readLogEnds`). Blocks are adopted BY REFERENCE — a seeder that keeps its own
81
+ * handle on one must not mutate it, which is why {@link offerServed}, whose caller does keep
82
+ * one, clones instead. Per-id revisions ride along so a seeded HIT still records at the
83
+ * revision the block was committed at. Seeding does not bump generations (a fresh
84
+ * cache has no consumers with stale memos). */
85
+ seed?: ReadonlyArray<[BlockId, T, number]>,
86
+ ) {
87
+ this.cache = new LruMap(maxSize);
88
+ if (seed) {
89
+ for (const [id, block, revision] of seed) {
90
+ this.cache.set(id, block);
91
+ this.revisions.set(id, revision);
92
+ }
93
+ }
94
+ }
95
+
96
+ private bump(id: BlockId) {
97
+ this.generations.set(id, (this.generations.get(id) ?? 0) + 1);
98
+ }
99
+
100
+ /** The current generation for an id — advances every time this cache's content for
101
+ * the id changes (miss-load, clear, or transformCache). Stable across pure cache hits. */
102
+ getGeneration(id: BlockId): number {
103
+ return this.generations.get(id) ?? 0;
104
+ }
105
+
106
+ /** INVARIANT: what a read returns for an id is what this cache then describes for it — the
107
+ * block {@link peek} answers and the revision {@link getCachedRevision} answers, immediately
108
+ * after, are the content the reader holds, on every path (hit, kept, handed through, evicted
109
+ * since). A write staged over the returned content pins that revision as its base, so a read
110
+ * that returned one thing while the cache described another would put a wrong base on the
111
+ * commit — the one direction the storage-side guard cannot catch. {@link admit} is where the
112
+ * two are decided together. */
113
+ async tryGet(id: BlockId, purpose: ReadPurpose = 'value'): Promise<T | undefined> {
114
+ const hit = this.cache.get(id);
115
+ if (hit) {
116
+ // Cache hit: the source is never consulted, so re-emit the revision we learned when this
117
+ // id was first loaded/folded. Without this a block served from cache records NO read
118
+ // dependency (the original bug), so its stale-read check could never fire. Carry the
119
+ // caller's purpose so a navigation-only cache hit stays droppable from the conflict set.
120
+ const rev = this.revisions.get(id);
121
+ if (rev !== undefined) this.collector?.record(id, rev, purpose);
122
+ log('hit id=%s', id);
123
+ return structuredClone(hit);
124
+ }
125
+ const generationAtMiss = this.getGeneration(id);
126
+ const answer = await this.source.tryGet(id, purpose);
127
+ if (!answer) {
128
+ // Absent block: record nothing (matches TransactorSource, which skips missing blocks).
129
+ log('miss:absent id=%s', id);
130
+ return undefined;
131
+ }
132
+ const { rev, mayRetain } = sourceServed(this.source, id, answer);
133
+ const served = this.admit(id, answer, rev, mayRetain, generationAtMiss);
134
+ // Record the dependency at the revision RETURNED. On a miss the underlying TransactorSource
135
+ // already recorded the answer's own id@rev/purpose into the shared collector; max-wins
136
+ // (revision) + value-wins (purpose) collapse the two to one entry, at the higher revision.
137
+ this.collector?.record(id, served.rev, purpose);
138
+ return structuredClone(served.block);
139
+ }
140
+
141
+ /** Decide, for an answer the source just gave for `id`, what the reader gets and what this cache
142
+ * describes for the id from now on — one decision, so the two cannot come apart.
143
+ *
144
+ * A keepable answer that is {@link stillWanted} is kept and returned. Otherwise the answer is
145
+ * either below its floor or was overtaken while in flight, and of two answers to one id the
146
+ * higher revision is the truer — so if content is HELD for the id (a concurrent read answered
147
+ * well, a folded commit, or content that met a floor this answer does not), the held content is
148
+ * what the reader gets, exactly as a hit a moment later would get it; the answer leaves no trace.
149
+ * Held content is never older than a below-floor answer: raising a floor forgets the id in the
150
+ * same step, so anything held for it since met the floor. With nothing held, the answer is
151
+ * handed through (see {@link handThrough}): returned, described, not kept. */
152
+ private admit(id: BlockId, answer: T, rev: number, mayRetain: boolean, generationAtMiss: number): { block: T; rev: number } {
153
+ if (mayRetain && this.stillWanted(id, rev, generationAtMiss)) {
154
+ this.keep(id, answer, rev, 'miss:loaded');
155
+ return { block: answer, rev };
156
+ }
157
+ const held = this.cache.get(id);
158
+ const heldRev = held === undefined ? undefined : this.revisions.get(id);
159
+ if (held !== undefined && heldRev !== undefined) {
160
+ log('miss:superseded id=%s rev=%d heldRev=%d unkeepable=%s', id, rev, heldRev, !mayRetain);
161
+ return { block: held, rev: heldRev };
162
+ }
163
+ this.handThrough(id, answer, rev);
164
+ return { block: answer, rev };
165
+ }
166
+
167
+ /** Whether an answer at `rev`, asked for when this id's generation was `generationAtMiss`, is
168
+ * still one to keep now that it has arrived.
169
+ *
170
+ * A miss is decided before the `await` and acted on after it. If the generation has not moved,
171
+ * nothing happened to the id meanwhile and the answer is kept. If it has — a second read of the
172
+ * id landed first, a refresh cleared it, a commit folded in ({@link transformCache}) — this answer
173
+ * was asked for in a world that has since changed, and keeping it blindly is how old content gets
174
+ * remembered for good: nothing clears a block but a log entry naming it, and that entry may be
175
+ * the very thing that moved the generation. So it is then kept only to REPLACE strictly older
176
+ * content (every answer to one source is for one view, so of two the higher revision is the
177
+ * truer, whichever arrives last); what an overtaken answer's reader gets is {@link admit}'s call.
178
+ * Only a CACHED id is compared: `revisions` outlives an LRU-evicted block (see its NOTE). */
179
+ private stillWanted(id: BlockId, rev: number, generationAtMiss: number): boolean {
180
+ if (this.getGeneration(id) === generationAtMiss) {
181
+ return true;
182
+ }
183
+ const held = this.cache.has(id) ? this.revisions.get(id) : undefined;
184
+ const replacesOlder = held !== undefined && held < rev;
185
+ if (!replacesOlder) {
186
+ log('miss:overtaken id=%s rev=%d heldRev=%s', id, rev, held ?? 'none');
187
+ }
188
+ return replacesOlder;
189
+ }
190
+
191
+ /** Adopt an answer some other read already obtained for `id` — the collection header and log
192
+ * tail block that `Collection.readLogEnds` fetches AROUND this cache — so the next read of the
193
+ * id is a hit rather than a second fetch of a block this handle just received.
194
+ *
195
+ * Kept only when nothing strictly newer is held ({@link heldRevision}), on the same ground
196
+ * {@link admit} stands on: of two answers to one source the higher revision is the truer. The
197
+ * block is cloned on the way in — this cache stores the reference, and the caller's array is
198
+ * handed to other caches as a seed as well — and goes through {@link keep}, so the generation
199
+ * bump, the {@link unkept} eviction and the {@link revisions} entry all happen exactly as they
200
+ * do for an answer this cache fetched itself.
201
+ *
202
+ * The CALLER owns the floor and pin checks. The offered block did not come through this cache's
203
+ * source, so `sourceServed` can say nothing about it: there is no `describeServed` record for a
204
+ * block the source never returned, and the by-id fallback would describe some other read. */
205
+ offerServed(id: BlockId, block: T, rev: number): void {
206
+ const heldRev = this.heldRevision(id);
207
+ if (heldRev !== undefined && heldRev > rev) {
208
+ log('offer:superseded id=%s rev=%d heldRev=%d', id, rev, heldRev);
209
+ return;
210
+ }
211
+ this.keep(id, structuredClone(block), rev, 'offer:kept');
212
+ }
213
+
214
+ /** The revision of the content this cache HOLDS for `id` right now — cached, or handed through
215
+ * unkept — and `undefined` when it holds none. Distinct from {@link getCachedRevision}, which
216
+ * also answers for an LRU-evicted id: that revision describes content this cache no longer has,
217
+ * so it is the right answer for a base probe and the wrong one for "is there anything here to
218
+ * weigh an offer against?". */
219
+ // NOTE: the consequence is that an offer over an LRU-evicted id is accepted even when it is
220
+ // OLDER than the revision this cache last served for the id — a lagging replica answering the
221
+ // unpinned refresh read below what this handle has already seen, with no walked entry to floor
222
+ // the block. That is the same answer a pinned re-read of the evicted id would have been kept at,
223
+ // so the offer path is no worse than the read path it replaces; if lagging-replica staleness on
224
+ // the header or log tail ever shows up, refuse an offer below `getCachedRevision` here (a block
225
+ // never goes back a revision, so refusing is always right) rather than adding a floor for it.
226
+ private heldRevision(id: BlockId): number | undefined {
227
+ return this.cache.has(id) ? this.revisions.get(id) : this.unkept.get(id)?.rev;
228
+ }
229
+
230
+ /** A keepable answer: cached, and served to every later read of `id` until something clears it.
231
+ * `reason` names how the content got here, so a log read to count source loads is not misled by
232
+ * an offer this cache never fetched. */
233
+ private keep(id: BlockId, block: T, rev: number, reason: 'miss:loaded' | 'offer:kept') {
234
+ this.cache.set(id, block);
235
+ this.revisions.set(id, rev);
236
+ this.unkept.delete(id);
237
+ this.bump(id);
238
+ log('%s id=%s cacheSize=%d', reason, id, this.cache.size);
239
+ }
240
+
241
+ /** An answer this cache will not keep, over an id it holds nothing for: returned to this one
242
+ * reader and described to the base probes (see {@link unkept}), but the next read of `id` asks
243
+ * the source again. Only {@link admit} calls this, after establishing that nothing is held —
244
+ * a cached id is never also in {@link unkept}.
245
+ *
246
+ * Bumped like a load: the answer changes what this cache can say about the id, and the bump is
247
+ * what sends a base pin or a materialized memo built on the previous answer back to be
248
+ * re-judged. */
249
+ private handThrough(id: BlockId, block: T, rev: number) {
250
+ this.revisions.delete(id);
251
+ this.unkept.set(id, { block, rev });
252
+ this.bump(id);
253
+ log('miss:unkept id=%s rev=%d', id, rev);
254
+ }
255
+
256
+ /** The base this cache can describe for `id`, without consulting the source: the cached block,
257
+ * or the content last handed through unkept (see {@link unkept}) — either way the content the
258
+ * most recent {@link tryGet} of the id returned, unless it has been evicted since. Cloned
259
+ * (callers apply ops to it) and recency-neutral ({@link LruMap.peek}) — an observation pass must
260
+ * neither pay a network read nor reshape eviction order. Records no read dependency: the caller
261
+ * that peeks already read the block through {@link tryGet} (that is how this cache learned it),
262
+ * so the dependency exists; a digest pass merely re-describes it. */
263
+ peek(id: BlockId): T | undefined {
264
+ const block = this.cache.peek(id) ?? this.unkept.get(id)?.block;
265
+ return block === undefined ? undefined : structuredClone(block);
266
+ }
267
+
268
+ /** Whether a later {@link tryGet} of `id` is answered from memory with the content this cache
269
+ * holds now. `false` for content handed through unkept, which {@link peek} still describes — so
270
+ * a consumer that would FREEZE a read result ({@link Tracker}'s materialized memo) asks this, not
271
+ * {@link peek}. Recency-neutral. */
272
+ retains(id: BlockId): boolean {
273
+ return this.cache.has(id);
274
+ }
275
+
276
+ /** The committed revision of the content this cache last served for `id` — the source-reported
277
+ * materialized revision learned on miss-load (see {@link revisions}) or handed through
278
+ * ({@link unkept}), NOT the block's own `state.latest.rev`. Answers for an LRU-evicted id too
279
+ * (see the NOTE on {@link revisions}): that is the revision a write staged over the evicted
280
+ * read was computed against, and what a rev-only base pin carries. {@link peek} returns
281
+ * `undefined` for the evicted id, so the revision never pairs with content it does not describe.
282
+ * `undefined` once the id has been cleared or folded away, or if it was never served. */
283
+ getCachedRevision(id: BlockId): number | undefined {
284
+ return this.revisions.get(id) ?? this.unkept.get(id)?.rev;
285
+ }
286
+
287
+ /** Upgrade an already-captured read of `id` to a `value` read in the shared collector,
288
+ * retaining it in the conflict set. The B-tree point-lookup descent calls this (through the
289
+ * Tracker, which forwards) to pin the terminal leaf after recording the interior nodes as
290
+ * `navigation`. No-op when no collector is wired (log-walk caches) or the id was never
291
+ * recorded. Duck-typed by the Tracker; keep the name in sync with Tracker.markReadValue. */
292
+ markReadValue(id: BlockId): void {
293
+ this.collector?.markValue(id);
294
+ }
295
+
296
+ generateId(): BlockId {
297
+ return this.source.generateId();
298
+ }
299
+
300
+ createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader {
301
+ return this.source.createBlockHeader(type, newId);
302
+ }
303
+
304
+ clear(blockIds: BlockId[] | undefined = undefined) {
305
+ if (blockIds) {
306
+ for (const id of blockIds) {
307
+ this.cache.delete(id);
308
+ this.revisions.delete(id);
309
+ this.unkept.delete(id);
310
+ this.bump(id);
311
+ }
312
+ } else {
313
+ for (const [id] of this.cache) {
314
+ this.bump(id);
315
+ }
316
+ for (const id of this.unkept.keys()) {
317
+ this.bump(id);
318
+ }
319
+ this.cache.clear();
320
+ this.revisions.clear();
321
+ this.unkept.clear();
322
+ }
323
+ }
324
+
325
+ /** A cloned copy of the current cache contents with each id's committed revision, in LRU
326
+ * order (oldest first, so replaying into another LruMap preserves eviction order). For
327
+ * building a pinned read view ONLY (see {@link Collection.createReadTracker}): pass the
328
+ * result as the `seed` of a fresh, PRIVATE CacheSource. Blocks are cloned on the way out,
329
+ * so the seeded cache shares no mutable state with this one. */
330
+ snapshotEntries(): Array<[BlockId, T, number]> {
331
+ const entries: Array<[BlockId, T, number]> = [];
332
+ for (const [id, block] of this.cache) {
333
+ entries.push([id, structuredClone(block), this.revisions.get(id) ?? 0]);
334
+ }
335
+ return entries;
336
+ }
337
+
338
+ /** Mutates the cache without affecting the source. `revision` is the committed revision this
339
+ * transform lands at; the stored per-id revision advances to it so a later read records a
340
+ * dependency at the NEW revision (recording the old one would spuriously fail validation). */
341
+ transformCache(transform: Transforms, revision: number) {
342
+ for (const blockId of transform.deletes ?? []) {
343
+ this.cache.delete(blockId);
344
+ this.revisions.delete(blockId);
345
+ this.unkept.delete(blockId);
346
+ this.bump(blockId);
347
+ }
348
+ for (const [, block] of Object.entries(transform.inserts ?? {})) {
349
+ this.cache.set(block.header.id, structuredClone(block) as T);
350
+ this.revisions.set(block.header.id, revision);
351
+ this.unkept.delete(block.header.id);
352
+ this.bump(block.header.id);
353
+ }
354
+ for (const [blockId, operations] of Object.entries(transform.updates ?? {})) {
355
+ const block = this.cache.get(blockId);
356
+ if (block) {
357
+ for (const op of operations) {
358
+ applyOperation(block, op);
359
+ this.bump(blockId);
360
+ }
361
+ this.revisions.set(blockId, revision);
362
+ } else if (this.unkept.delete(blockId)) {
363
+ // The commit superseded the unkept base, and the ops are NOT folded into it: it was
364
+ // never trusted as this id's content, so the result would not be either. The id stays
365
+ // out of memory and the next read asks the source, which now holds `revision`.
366
+ this.bump(blockId);
367
+ }
368
+ }
369
+ }
370
+ }