@optimystic/db-core 1.5.0 → 1.6.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 (157) hide show
  1. package/README.md +336 -336
  2. package/dist/src/cluster/structs.d.ts +37 -0
  3. package/dist/src/cluster/structs.d.ts.map +1 -1
  4. package/dist/src/cluster/structs.js +13 -0
  5. package/dist/src/cluster/structs.js.map +1 -1
  6. package/dist/src/collection/collection.d.ts +44 -4
  7. package/dist/src/collection/collection.d.ts.map +1 -1
  8. package/dist/src/collection/collection.js +95 -14
  9. package/dist/src/collection/collection.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/cluster/structs.ts +38 -0
  41. package/src/cohort-topic/addressing.ts +120 -120
  42. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  43. package/src/cohort-topic/antidos/index.ts +5 -5
  44. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  45. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  46. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  47. package/src/cohort-topic/antiflood/index.ts +2 -2
  48. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  49. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  50. package/src/cohort-topic/coldstart.ts +237 -237
  51. package/src/cohort-topic/dmax.ts +88 -88
  52. package/src/cohort-topic/gossip/bus.ts +254 -254
  53. package/src/cohort-topic/gossip/index.ts +3 -3
  54. package/src/cohort-topic/gossip/records.ts +45 -45
  55. package/src/cohort-topic/gossip/view.ts +91 -91
  56. package/src/cohort-topic/index.ts +20 -20
  57. package/src/cohort-topic/load/barometer.ts +134 -134
  58. package/src/cohort-topic/load/index.ts +1 -1
  59. package/src/cohort-topic/member-engine.ts +430 -430
  60. package/src/cohort-topic/membership/index.ts +3 -3
  61. package/src/cohort-topic/membership/publisher.ts +163 -163
  62. package/src/cohort-topic/membership/source.ts +41 -41
  63. package/src/cohort-topic/ports.ts +157 -157
  64. package/src/cohort-topic/promotion.ts +477 -477
  65. package/src/cohort-topic/registration/bytes.ts +37 -37
  66. package/src/cohort-topic/registration/handoff.ts +154 -154
  67. package/src/cohort-topic/registration/index.ts +6 -6
  68. package/src/cohort-topic/registration/renewal.ts +495 -495
  69. package/src/cohort-topic/registration/sharding.ts +61 -61
  70. package/src/cohort-topic/registration/store.ts +81 -81
  71. package/src/cohort-topic/registration/types.ts +91 -91
  72. package/src/cohort-topic/ring-hash.ts +50 -50
  73. package/src/cohort-topic/service.ts +416 -416
  74. package/src/cohort-topic/sig/index.ts +2 -2
  75. package/src/cohort-topic/sig/payloads.ts +59 -59
  76. package/src/cohort-topic/sig/threshold.ts +64 -64
  77. package/src/cohort-topic/tiers.ts +74 -74
  78. package/src/cohort-topic/traffic.ts +233 -233
  79. package/src/cohort-topic/walk.ts +326 -326
  80. package/src/cohort-topic/willingness.ts +237 -237
  81. package/src/cohort-topic/wire/index.ts +18 -18
  82. package/src/cohort-topic/wire/payloads.ts +126 -126
  83. package/src/collection/action.ts +48 -48
  84. package/src/collection/collection-type-registry.ts +37 -37
  85. package/src/collection/collection.ts +2203 -2118
  86. package/src/collection/index.ts +4 -4
  87. package/src/collections/diary/index.ts +2 -2
  88. package/src/collections/diary/struct.ts +3 -3
  89. package/src/collections/index.ts +2 -2
  90. package/src/collections/tree/collection-trunk.ts +25 -25
  91. package/src/collections/tree/index.ts +2 -2
  92. package/src/collections/tree/readme.md +55 -55
  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
package/src/log/log.ts CHANGED
@@ -1,268 +1,304 @@
1
- import { sha256 } from 'multiformats/hashes/sha2'
2
- import { Chain, entryAt } from "../chain/chain.js";
3
- import { nameof } from "../utility/nameof.js";
4
- import type { IBlock, BlockId, ActionId, CollectionId, ChainPath, ActionRev, ActionContext, ChainInitOptions, BlockStore, ReadDependency } from "../index.js";
5
- import type { ChainDataNode } from '../chain/chain-nodes.js';
6
- import type { LogEntry, ActionEntry, DisputeResolutionProof, InvalidationEntry, RevertedBlock } from "./index.js";
7
- import { LogDataBlockType, LogHeaderBlockType } from "./struct.js";
8
- import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
9
- import type { GetFromResult } from './struct.js';
10
-
11
- export type LogBlock<TAction> = ChainDataNode<LogEntry<TAction>>
12
- & {
13
- /** Base64url encoded Sha256 hash of the prior (predecessor) block - present on every block except the head */
14
- priorHash?: string,
15
- };
16
-
17
- export const priorHash$ = nameof<LogBlock<any>>("priorHash");
18
-
19
- /**
20
- * Canonical byte payload covered by {@link LogBlock.priorHash}: every field of a log block EXCEPT
21
- * the mutable structural links (`nextId`/`priorId`). Those links are rewritten *after* the hash is
22
- * taken — `nextId` when the following block is appended ({@link Chain.add}), and `priorId`/`nextId`
23
- * when blocks are removed ({@link Chain.pop}/{@link Chain.dequeue}) — so hashing the raw block would
24
- * not match the bytes that end up stored. The content-bearing fields (`header`, `entries`,
25
- * `priorHash`) are covered. Any verifier that re-hashes a stored block to check `priorHash` MUST
26
- * reproduce exactly this payload (strip `nextId` and `priorId`; hash the rest).
27
- *
28
- * NOTE: the caller hashes `JSON.stringify` of this object, which is key-order dependent and not a
29
- * canonical encoding. Fine today (blocks are built with a stable key order and the in-process store
30
- * preserves it), but if a block is ever re-serialized by a store/codec that reorders keys or drops
31
- * `undefined`s differently, a re-hash won't match the recorded priorHash — switch to a canonical
32
- * encoding (sorted keys / dag-cbor) before that happens.
33
- */
34
- export function logBlockHashPayload<TAction>(block: LogBlock<TAction>) {
35
- const { nextId, priorId, ...covered } = block;
36
- return covered;
37
- }
38
-
39
- export class Log<TAction> {
40
- protected constructor(
41
- private readonly chain: Chain<LogEntry<TAction>>,
42
- ) {
43
- }
44
-
45
- get id() {
46
- return this.chain.id;
47
- }
48
-
49
- /** Opens a presumably existing log. */
50
- static async open<TAction>(store: BlockStore<IBlock>, id: BlockId): Promise<Log<TAction> | undefined> {
51
- const chain = await Chain.open<LogEntry<TAction>>(store, id, Log.getChainOptions(store));
52
- return chain ? new Log<TAction>(chain) : undefined;
53
- }
54
-
55
- /** Creates a new log. */
56
- static async create<TAction>(store: BlockStore<IBlock>, options?: { newId?: BlockId; existingHeaderId?: BlockId }) {
57
- return new Log<TAction>(await Chain.create<LogEntry<TAction>>(store, {
58
- ...Log.getChainOptions(store),
59
- newId: options?.newId,
60
- existingHeaderId: options?.existingHeaderId,
61
- }));
62
- }
63
-
64
- /**
65
- * Adds a new action entry to the log.
66
- *
67
- * `reads` is the transaction's `(blockId, revision)` read set, persisted on the entry so the
68
- * invalidation cascade can later discover this action's read-dependents (see
69
- * {@link ActionEntry.reads}). Omit it (or pass `undefined`) on the low-level direct-commit path
70
- * that carries no `Transaction`; the cascade then treats the entry as an unknown dependency.
71
- */
72
- async addActions(actions: TAction[], actionId: ActionId, rev: number, getBlockIds: () => BlockId[], collectionIds: CollectionId[] = [], reads?: ReadDependency[], timestamp: number = Date.now()) {
73
- const action = reads !== undefined
74
- ? { actionId, actions, blockIds: [], collectionIds, reads }
75
- : { actionId, actions, blockIds: [], collectionIds };
76
- const entry = { timestamp, rev, action } as LogEntry<TAction>;
77
- const tailPath = await this.chain.add(entry);
78
- const entryWithBlockIds = { ...entry, action: { ...entry.action!, blockIds: getBlockIds() } };
79
- this.chain.updateAt(tailPath, entryWithBlockIds);
80
- return { entry: entryWithBlockIds, tailPath };
81
- }
82
-
83
- /** Adds a checkpoint to the log. */
84
- async addCheckpoint(pendings: ActionRev[], rev: number, timestamp: number = Date.now()) {
85
- const entry = { timestamp, rev, checkpoint: { pendings } };
86
- const tailPath = await this.chain.add(entry);
87
- return { entry, tailPath };
88
- }
89
-
90
- /**
91
- * Appends a compensating invalidation entry that reverses a previously-committed action proven
92
- * invalid by dispute. The committed history is never rewritten — this is a new, append-only,
93
- * prior-hash-linked entry, recoverable on sync exactly like a commit. The caller has already
94
- * verified `resolution` is a challenger-wins certificate and computed the per-block `reverted`
95
- * targets (the new revisions restoring the as-if-`T_inv`-absent content).
96
- */
97
- async addInvalidation(
98
- invalidatedActionId: ActionId,
99
- invalidatedRev: number,
100
- resolution: DisputeResolutionProof,
101
- reverted: ReadonlyArray<RevertedBlock>,
102
- rev: number,
103
- cascadeRoot?: ActionId,
104
- timestamp: number = Date.now()
105
- ) {
106
- const invalidation: InvalidationEntry = cascadeRoot !== undefined
107
- ? { invalidatedActionId, invalidatedRev, resolution, reverted, cascadeRoot }
108
- : { invalidatedActionId, invalidatedRev, resolution, reverted };
109
- const entry = { timestamp, rev, invalidation } as LogEntry<TAction>;
110
- const tailPath = await this.chain.add(entry);
111
- return { entry, tailPath };
112
- }
113
-
114
- /**
115
- * Finds the most recent invalidation entry that reverses the given committed action, if any.
116
- * This is the durable source of truth for `committed-invalidated` status — once the entry has
117
- * landed in the log, the reversal is recoverable on sync independent of any in-memory cache.
118
- * Scans newest→oldest (O(n) over the chain, matching {@link getFrom}); returns the first match.
119
- */
120
- async findInvalidation(invalidatedActionId: ActionId): Promise<InvalidationEntry | undefined> {
121
- for await (const path of this.chain.select(undefined, false)) {
122
- const invalidation = entryAt<LogEntry<TAction>>(path)!.invalidation;
123
- if (invalidation && invalidation.invalidatedActionId === invalidatedActionId) {
124
- return invalidation;
125
- }
126
- }
127
- return undefined;
128
- }
129
-
130
- /**
131
- * Returns the invalidation entries appended after `startRev` (exclusive), newest-first. Used by
132
- * {@link import("../collection/collection.js").Collection} on `update` to discover reversals that
133
- * landed since the client last synced: a client holding a result derived from now-reverted content
134
- * drops it and replays against the reverted base — the same "your base moved, re-sync and retry"
135
- * path a stale read triggers (`docs/right-is-right.md` §Client notification). Unlike {@link getFrom}
136
- * (which skips invalidation entries — they are not pending/committed actions), this surfaces exactly
137
- * the invalidations. Scans newest→oldest and stops once at/below `startRev` (revs are monotonic), so
138
- * the walk is bounded to the unsynced tail.
139
- */
140
- async getInvalidationsFrom(startRev: number | undefined): Promise<InvalidationEntry[]> {
141
- const invalidations: InvalidationEntry[] = [];
142
- for await (const path of this.chain.select(undefined, false)) {
143
- const entry = entryAt<LogEntry<TAction>>(path)!;
144
- if (startRev !== undefined && entry.rev <= startRev) {
145
- break;
146
- }
147
- if (entry.invalidation) {
148
- invalidations.push(entry.invalidation);
149
- }
150
- }
151
- return invalidations;
152
- }
153
-
154
- /** Gets the action context of the log. */
155
- async getActionContext(): Promise<ActionContext | undefined> {
156
- const tailPath = await this.chain.getTail();
157
- if (!tailPath || tailPath.block.entries.length === 0) {
158
- return undefined;
159
- }
160
- const checkpoint = await this.findCheckpoint(tailPath);
161
- // Hermes V1 codegen bug: `[...arr, ...await asyncCall()]` evaluated as an
162
- // object-literal field value silently produces the number 0 instead of an
163
- // array. Extracting the await into a local variable bypasses the buggy
164
- // codegen path. Keep this workaround until Hermes V1 ships a fix.
165
- const additional = checkpoint ? await this.pendingFrom(checkpoint.path) : [];
166
- return {
167
- committed: checkpoint ? [...checkpoint.pendings, ...additional] : [],
168
- rev: checkpoint?.rev ?? 0,
169
- };
170
- }
171
-
172
- /** Gets the actions from startRev (exclusive), to latest in the log. */
173
- async getFrom(startRev: number | undefined): Promise<GetFromResult<TAction>> {
174
- const entriesFromTail: ActionEntry<TAction>[] = [];
175
- const pendingActions: ActionRev[] = [];
176
- let checkpointPendings: ActionRev[] = [];
177
- let rev: number | undefined;
178
- let checkpointPath: ChainPath<LogEntry<TAction>> | undefined;
179
- // Step through collecting both pending and entries until a checkpoint is found
180
- for await (const path of this.chain.select(undefined, false)) {
181
- const entry = entryAt<LogEntry<TAction>>(path)!;
182
- rev = rev ?? entry.rev;
183
- if (entry.checkpoint) {
184
- checkpointPath = path;
185
- checkpointPendings = entry.checkpoint.pendings;
186
- break;
187
- }
188
- // Invalidation entries take a rev slot but are not pending actions — skip them in
189
- // the committed/pending set (the reversal is surfaced via findInvalidation instead).
190
- if (!entry.action) {
191
- continue;
192
- }
193
- pendingActions.push({ actionId: entry.action.actionId, rev: entry.rev });
194
- if (startRev !== undefined && entry.rev > startRev) {
195
- entriesFromTail.push(entry.action);
196
- } // Can't stop at rev, because we need to collect all pending actions for the context
197
- }
198
- // Continue stepping past the checkpoint until the given rev is reached
199
- const entriesFromCheckpoint: ActionEntry<TAction>[] = [];
200
- if (checkpointPath) {
201
- for await (const path of this.chain.select(checkpointPath, false)) {
202
- const entry = entryAt<LogEntry<TAction>>(path)!;
203
- if (startRev !== undefined && entry.rev > startRev) {
204
- if (entry.action) {
205
- entriesFromCheckpoint.push(entry.action);
206
- }
207
- } else {
208
- break;
209
- }
210
- }
211
- }
212
- const pendings = [...checkpointPendings, ...pendingActions.reverse()];
213
- const entries = [...entriesFromCheckpoint.reverse(), ...entriesFromTail.reverse()];
214
- return { context: rev ? { committed: pendings, rev } : undefined, entries };
215
- }
216
-
217
- /** Enumerates log entries from the given starting path or end if undefined, in forward (from tail to head) or reverse (from head to tail) order. */
218
- async *select(starting?: ChainPath<LogEntry<TAction>>, forward = true) {
219
- for await (const path of this.chain.select(starting, forward)) {
220
- yield entryAt<LogEntry<TAction>>(path)!;
221
- }
222
- }
223
-
224
- /** Returns the set of pending transactions in the most recent checkpoint, at or preceding the given path. */
225
- private async findCheckpoint(starting: ChainPath<LogEntry<TAction>>) {
226
- let lastPath: ChainPath<LogEntry<TAction>> | undefined;
227
- let rev: number | undefined;
228
- for await (const path of this.chain.select(starting, false)) {
229
- const entry = entryAt<LogEntry<TAction>>(path)!;
230
- rev = rev ?? entry.rev;
231
- if (entry.checkpoint) {
232
- return { path, pendings: entry.checkpoint.pendings, rev };
233
- }
234
- lastPath = path;
235
- }
236
- return lastPath ? { path: lastPath, pendings: [], rev } : undefined;
237
- }
238
-
239
- /** Returns the set of pending actions following, the given checkpoint path. */
240
- private async pendingFrom(starting: ChainPath<LogEntry<TAction>>) {
241
- const pendings: ActionRev[] = [];
242
- for await (const actionPath of this.chain.select(starting)) {
243
- const entry = entryAt<LogEntry<TAction>>(actionPath);
244
- if (entry?.action) {
245
- pendings.push({ actionId: entry.action.actionId, rev: entry.rev });
246
- }
247
- }
248
- return pendings;
249
- }
250
-
251
- /** Chain options used by every log: block type factories plus the priorHash `newBlock` hook.
252
- * Exposed (not private) so tests can drive a raw {@link Chain} through the exact same hook. */
253
- static getChainOptions<TAction>(store: BlockStore<IBlock>) {
254
- return {
255
- createDataBlock: () => ({ header: store.createBlockHeader(LogDataBlockType) }),
256
- createHeaderBlock: (id?: BlockId) => ({ header: store.createBlockHeader(LogHeaderBlockType, id) }),
257
- newBlock: async (newTail: LogBlock<TAction>, oldTail: LogBlock<TAction> | undefined) => {
258
- if (oldTail) {
259
- // Hash the canonical payload (excludes the mutable nextId/priorId links) so the
260
- // recorded priorHash matches a later re-hash of the stored predecessor block.
261
- const hash = await sha256.digest(new TextEncoder().encode(JSON.stringify(logBlockHashPayload(oldTail))));
262
- newTail.priorHash = uint8ArrayToString(hash.digest, 'base64url');
263
- }
264
- },
265
- } as ChainInitOptions<LogEntry<TAction>>;
266
-
267
- }
268
- }
1
+ import { sha256 } from 'multiformats/hashes/sha2'
2
+ import { Chain, entryAt } from "../chain/chain.js";
3
+ import { nameof } from "../utility/nameof.js";
4
+ import type { IBlock, BlockId, ActionId, CollectionId, ChainPath, ActionRev, ActionContext, ChainInitOptions, BlockStore, ReadDependency } from "../index.js";
5
+ import type { ChainDataNode } from '../chain/chain-nodes.js';
6
+ import type { LogEntry, ActionEntry, DisputeResolutionProof, InvalidationEntry, RevertedBlock } from "./index.js";
7
+ import { LogDataBlockType, LogHeaderBlockType } from "./struct.js";
8
+ import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
9
+ import type { GetFromResult } from './struct.js';
10
+
11
+ export type LogBlock<TAction> = ChainDataNode<LogEntry<TAction>>
12
+ & {
13
+ /** Base64url encoded Sha256 hash of the prior (predecessor) block - present on every block except the head */
14
+ priorHash?: string,
15
+ };
16
+
17
+ export const priorHash$ = nameof<LogBlock<any>>("priorHash");
18
+
19
+ /**
20
+ * Canonical byte payload covered by {@link LogBlock.priorHash}: every field of a log block EXCEPT
21
+ * the mutable structural links (`nextId`/`priorId`). Those links are rewritten *after* the hash is
22
+ * taken — `nextId` when the following block is appended ({@link Chain.add}), and `priorId`/`nextId`
23
+ * when blocks are removed ({@link Chain.pop}/{@link Chain.dequeue}) — so hashing the raw block would
24
+ * not match the bytes that end up stored. The content-bearing fields (`header`, `entries`,
25
+ * `priorHash`) are covered. Any verifier that re-hashes a stored block to check `priorHash` MUST
26
+ * reproduce exactly this payload (strip `nextId` and `priorId`; hash the rest).
27
+ *
28
+ * NOTE: the caller hashes `JSON.stringify` of this object, which is key-order dependent and not a
29
+ * canonical encoding. Fine today (blocks are built with a stable key order and the in-process store
30
+ * preserves it), but if a block is ever re-serialized by a store/codec that reorders keys or drops
31
+ * `undefined`s differently, a re-hash won't match the recorded priorHash — switch to a canonical
32
+ * encoding (sorted keys / dag-cbor) before that happens.
33
+ */
34
+ export function logBlockHashPayload<TAction>(block: LogBlock<TAction>) {
35
+ const { nextId, priorId, ...covered } = block;
36
+ return covered;
37
+ }
38
+
39
+ /** What {@link Log.open} may be told beyond the block it opens. */
40
+ export type LogOpenOptions = {
41
+ /** Supplies the id for each data block an append mints, in place of a fresh random one. */
42
+ newDataBlockId?: () => BlockId;
43
+ };
44
+
45
+ /** The trailing, mostly-optional inputs to {@link Log.addActions}. An options object rather than
46
+ * positional parameters because the two most interesting ones are the last two, and a caller that
47
+ * needs only the timestamp should not have to spell out the two before it. */
48
+ export type AddActionsOptions = {
49
+ /** Every collection participating in the action this entry records. */
50
+ collectionIds?: CollectionId[];
51
+ /** The transaction's `(blockId, revision)` read set, persisted on the entry so the invalidation
52
+ * cascade can later discover this action's read-dependents (see {@link ActionEntry.reads}).
53
+ * Omit it on the low-level direct-commit path that carries no `Transaction`; the cascade then
54
+ * treats the entry as an unknown dependency. */
55
+ reads?: ReadDependency[];
56
+ /**
57
+ * When the entry was written. Nothing in the tree reads it for logic — it is informational —
58
+ * which is what makes it safe for a writer to supply the time of the WRITE rather than of the
59
+ * attempt, and arguably the more honest value.
60
+ *
61
+ * A writer whose attempt may be retried MUST supply it. Storage identifies a saved block
62
+ * revision by `(action id, revision)` and accepts a retry of the same action at the same
63
+ * revision, so a retry that took a fresh timestamp here would store a second, different log
64
+ * block under one `(action, revision)` on every machine that missed the first attempt.
65
+ * Defaults to `Date.now()` for a caller that appends once.
66
+ */
67
+ timestamp?: number;
68
+ };
69
+
70
+ export class Log<TAction> {
71
+ protected constructor(
72
+ private readonly chain: Chain<LogEntry<TAction>>,
73
+ ) {
74
+ }
75
+
76
+ get id() {
77
+ return this.chain.id;
78
+ }
79
+
80
+ /** Opens a presumably existing log.
81
+ *
82
+ * `options.newDataBlockId` supplies the id for each data block an append has to mint, in place
83
+ * of a fresh random one. A writer whose attempt may be RETRIED passes a source that hands back
84
+ * the ids its earlier attempt minted, so the retry's transforms are byte-identical to the
85
+ * attempt it repeats (see {@link Collection.logAppendBlockIds}); everything else omits it and
86
+ * mints at random exactly as before. */
87
+ static async open<TAction>(store: BlockStore<IBlock>, id: BlockId, options?: LogOpenOptions): Promise<Log<TAction> | undefined> {
88
+ const chain = await Chain.open<LogEntry<TAction>>(store, id, Log.getChainOptions(store, options?.newDataBlockId));
89
+ return chain ? new Log<TAction>(chain) : undefined;
90
+ }
91
+
92
+ /** Creates a new log. */
93
+ static async create<TAction>(store: BlockStore<IBlock>, options?: { newId?: BlockId; existingHeaderId?: BlockId }) {
94
+ return new Log<TAction>(await Chain.create<LogEntry<TAction>>(store, {
95
+ ...Log.getChainOptions(store),
96
+ newId: options?.newId,
97
+ existingHeaderId: options?.existingHeaderId,
98
+ }));
99
+ }
100
+
101
+ /**
102
+ * Adds a new action entry to the log.
103
+ *
104
+ * See {@link AddActionsOptions} for what the trailing options carry, and in particular why a
105
+ * writer that may retry passes its own `timestamp` rather than letting each attempt take one.
106
+ */
107
+ async addActions(actions: TAction[], actionId: ActionId, rev: number, getBlockIds: () => BlockId[], options?: AddActionsOptions) {
108
+ const { collectionIds = [], reads, timestamp = Date.now() } = options ?? {};
109
+ const action = reads !== undefined
110
+ ? { actionId, actions, blockIds: [], collectionIds, reads }
111
+ : { actionId, actions, blockIds: [], collectionIds };
112
+ const entry = { timestamp, rev, action } as LogEntry<TAction>;
113
+ const tailPath = await this.chain.add(entry);
114
+ const entryWithBlockIds = { ...entry, action: { ...entry.action!, blockIds: getBlockIds() } };
115
+ this.chain.updateAt(tailPath, entryWithBlockIds);
116
+ return { entry: entryWithBlockIds, tailPath };
117
+ }
118
+
119
+ /** Adds a checkpoint to the log. */
120
+ async addCheckpoint(pendings: ActionRev[], rev: number, timestamp: number = Date.now()) {
121
+ const entry = { timestamp, rev, checkpoint: { pendings } };
122
+ const tailPath = await this.chain.add(entry);
123
+ return { entry, tailPath };
124
+ }
125
+
126
+ /**
127
+ * Appends a compensating invalidation entry that reverses a previously-committed action proven
128
+ * invalid by dispute. The committed history is never rewritten — this is a new, append-only,
129
+ * prior-hash-linked entry, recoverable on sync exactly like a commit. The caller has already
130
+ * verified `resolution` is a challenger-wins certificate and computed the per-block `reverted`
131
+ * targets (the new revisions restoring the as-if-`T_inv`-absent content).
132
+ */
133
+ async addInvalidation(
134
+ invalidatedActionId: ActionId,
135
+ invalidatedRev: number,
136
+ resolution: DisputeResolutionProof,
137
+ reverted: ReadonlyArray<RevertedBlock>,
138
+ rev: number,
139
+ cascadeRoot?: ActionId,
140
+ timestamp: number = Date.now()
141
+ ) {
142
+ const invalidation: InvalidationEntry = cascadeRoot !== undefined
143
+ ? { invalidatedActionId, invalidatedRev, resolution, reverted, cascadeRoot }
144
+ : { invalidatedActionId, invalidatedRev, resolution, reverted };
145
+ const entry = { timestamp, rev, invalidation } as LogEntry<TAction>;
146
+ const tailPath = await this.chain.add(entry);
147
+ return { entry, tailPath };
148
+ }
149
+
150
+ /**
151
+ * Finds the most recent invalidation entry that reverses the given committed action, if any.
152
+ * This is the durable source of truth for `committed-invalidated` status — once the entry has
153
+ * landed in the log, the reversal is recoverable on sync independent of any in-memory cache.
154
+ * Scans newest→oldest (O(n) over the chain, matching {@link getFrom}); returns the first match.
155
+ */
156
+ async findInvalidation(invalidatedActionId: ActionId): Promise<InvalidationEntry | undefined> {
157
+ for await (const path of this.chain.select(undefined, false)) {
158
+ const invalidation = entryAt<LogEntry<TAction>>(path)!.invalidation;
159
+ if (invalidation && invalidation.invalidatedActionId === invalidatedActionId) {
160
+ return invalidation;
161
+ }
162
+ }
163
+ return undefined;
164
+ }
165
+
166
+ /**
167
+ * Returns the invalidation entries appended after `startRev` (exclusive), newest-first. Used by
168
+ * {@link import("../collection/collection.js").Collection} on `update` to discover reversals that
169
+ * landed since the client last synced: a client holding a result derived from now-reverted content
170
+ * drops it and replays against the reverted base — the same "your base moved, re-sync and retry"
171
+ * path a stale read triggers (`docs/right-is-right.md` §Client notification). Unlike {@link getFrom}
172
+ * (which skips invalidation entries — they are not pending/committed actions), this surfaces exactly
173
+ * the invalidations. Scans newest→oldest and stops once at/below `startRev` (revs are monotonic), so
174
+ * the walk is bounded to the unsynced tail.
175
+ */
176
+ async getInvalidationsFrom(startRev: number | undefined): Promise<InvalidationEntry[]> {
177
+ const invalidations: InvalidationEntry[] = [];
178
+ for await (const path of this.chain.select(undefined, false)) {
179
+ const entry = entryAt<LogEntry<TAction>>(path)!;
180
+ if (startRev !== undefined && entry.rev <= startRev) {
181
+ break;
182
+ }
183
+ if (entry.invalidation) {
184
+ invalidations.push(entry.invalidation);
185
+ }
186
+ }
187
+ return invalidations;
188
+ }
189
+
190
+ /** Gets the action context of the log. */
191
+ async getActionContext(): Promise<ActionContext | undefined> {
192
+ const tailPath = await this.chain.getTail();
193
+ if (!tailPath || tailPath.block.entries.length === 0) {
194
+ return undefined;
195
+ }
196
+ const checkpoint = await this.findCheckpoint(tailPath);
197
+ // Hermes V1 codegen bug: `[...arr, ...await asyncCall()]` evaluated as an
198
+ // object-literal field value silently produces the number 0 instead of an
199
+ // array. Extracting the await into a local variable bypasses the buggy
200
+ // codegen path. Keep this workaround until Hermes V1 ships a fix.
201
+ const additional = checkpoint ? await this.pendingFrom(checkpoint.path) : [];
202
+ return {
203
+ committed: checkpoint ? [...checkpoint.pendings, ...additional] : [],
204
+ rev: checkpoint?.rev ?? 0,
205
+ };
206
+ }
207
+
208
+ /** Gets the actions from startRev (exclusive), to latest in the log. */
209
+ async getFrom(startRev: number | undefined): Promise<GetFromResult<TAction>> {
210
+ const entriesFromTail: ActionEntry<TAction>[] = [];
211
+ const pendingActions: ActionRev[] = [];
212
+ let checkpointPendings: ActionRev[] = [];
213
+ let rev: number | undefined;
214
+ let checkpointPath: ChainPath<LogEntry<TAction>> | undefined;
215
+ // Step through collecting both pending and entries until a checkpoint is found
216
+ for await (const path of this.chain.select(undefined, false)) {
217
+ const entry = entryAt<LogEntry<TAction>>(path)!;
218
+ rev = rev ?? entry.rev;
219
+ if (entry.checkpoint) {
220
+ checkpointPath = path;
221
+ checkpointPendings = entry.checkpoint.pendings;
222
+ break;
223
+ }
224
+ // Invalidation entries take a rev slot but are not pending actions — skip them in
225
+ // the committed/pending set (the reversal is surfaced via findInvalidation instead).
226
+ if (!entry.action) {
227
+ continue;
228
+ }
229
+ pendingActions.push({ actionId: entry.action.actionId, rev: entry.rev });
230
+ if (startRev !== undefined && entry.rev > startRev) {
231
+ entriesFromTail.push(entry.action);
232
+ } // Can't stop at rev, because we need to collect all pending actions for the context
233
+ }
234
+ // Continue stepping past the checkpoint until the given rev is reached
235
+ const entriesFromCheckpoint: ActionEntry<TAction>[] = [];
236
+ if (checkpointPath) {
237
+ for await (const path of this.chain.select(checkpointPath, false)) {
238
+ const entry = entryAt<LogEntry<TAction>>(path)!;
239
+ if (startRev !== undefined && entry.rev > startRev) {
240
+ if (entry.action) {
241
+ entriesFromCheckpoint.push(entry.action);
242
+ }
243
+ } else {
244
+ break;
245
+ }
246
+ }
247
+ }
248
+ const pendings = [...checkpointPendings, ...pendingActions.reverse()];
249
+ const entries = [...entriesFromCheckpoint.reverse(), ...entriesFromTail.reverse()];
250
+ return { context: rev ? { committed: pendings, rev } : undefined, entries };
251
+ }
252
+
253
+ /** Enumerates log entries from the given starting path or end if undefined, in forward (from tail to head) or reverse (from head to tail) order. */
254
+ async *select(starting?: ChainPath<LogEntry<TAction>>, forward = true) {
255
+ for await (const path of this.chain.select(starting, forward)) {
256
+ yield entryAt<LogEntry<TAction>>(path)!;
257
+ }
258
+ }
259
+
260
+ /** Returns the set of pending transactions in the most recent checkpoint, at or preceding the given path. */
261
+ private async findCheckpoint(starting: ChainPath<LogEntry<TAction>>) {
262
+ let lastPath: ChainPath<LogEntry<TAction>> | undefined;
263
+ let rev: number | undefined;
264
+ for await (const path of this.chain.select(starting, false)) {
265
+ const entry = entryAt<LogEntry<TAction>>(path)!;
266
+ rev = rev ?? entry.rev;
267
+ if (entry.checkpoint) {
268
+ return { path, pendings: entry.checkpoint.pendings, rev };
269
+ }
270
+ lastPath = path;
271
+ }
272
+ return lastPath ? { path: lastPath, pendings: [], rev } : undefined;
273
+ }
274
+
275
+ /** Returns the set of pending actions following, the given checkpoint path. */
276
+ private async pendingFrom(starting: ChainPath<LogEntry<TAction>>) {
277
+ const pendings: ActionRev[] = [];
278
+ for await (const actionPath of this.chain.select(starting)) {
279
+ const entry = entryAt<LogEntry<TAction>>(actionPath);
280
+ if (entry?.action) {
281
+ pendings.push({ actionId: entry.action.actionId, rev: entry.rev });
282
+ }
283
+ }
284
+ return pendings;
285
+ }
286
+
287
+ /** Chain options used by every log: block type factories plus the priorHash `newBlock` hook.
288
+ * Exposed (not private) so tests can drive a raw {@link Chain} through the exact same hook. */
289
+ static getChainOptions<TAction>(store: BlockStore<IBlock>, newDataBlockId?: () => BlockId) {
290
+ return {
291
+ createDataBlock: () => ({ header: store.createBlockHeader(LogDataBlockType, newDataBlockId?.()) }),
292
+ createHeaderBlock: (id?: BlockId) => ({ header: store.createBlockHeader(LogHeaderBlockType, id) }),
293
+ newBlock: async (newTail: LogBlock<TAction>, oldTail: LogBlock<TAction> | undefined) => {
294
+ if (oldTail) {
295
+ // Hash the canonical payload (excludes the mutable nextId/priorId links) so the
296
+ // recorded priorHash matches a later re-hash of the stored predecessor block.
297
+ const hash = await sha256.digest(new TextEncoder().encode(JSON.stringify(logBlockHashPayload(oldTail))));
298
+ newTail.priorHash = uint8ArrayToString(hash.digest, 'base64url');
299
+ }
300
+ },
301
+ } as ChainInitOptions<LogEntry<TAction>>;
302
+
303
+ }
304
+ }