@optimystic/db-core 1.5.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 (152) 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/log/log.d.ts +41 -8
  7. package/dist/src/log/log.d.ts.map +1 -1
  8. package/dist/src/log/log.js +15 -10
  9. package/dist/src/log/log.js.map +1 -1
  10. package/dist/src/testing/test-transactor.d.ts +36 -0
  11. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  12. package/dist/src/testing/test-transactor.js +49 -0
  13. package/dist/src/testing/test-transactor.js.map +1 -1
  14. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  15. package/dist/src/transaction/coordinator.js +26 -9
  16. package/dist/src/transaction/coordinator.js.map +1 -1
  17. package/package.json +1 -1
  18. package/src/blocks/block-store.ts +31 -31
  19. package/src/blocks/block-types.ts +11 -11
  20. package/src/blocks/index.ts +5 -5
  21. package/src/blocks/structs.ts +17 -17
  22. package/src/btree/btree.ts +872 -872
  23. package/src/btree/independent-trunk.ts +53 -53
  24. package/src/btree/index.ts +5 -5
  25. package/src/btree/key-range.ts +15 -15
  26. package/src/btree/keyset.ts +6 -6
  27. package/src/btree/nodes.ts +25 -25
  28. package/src/btree/path.ts +37 -37
  29. package/src/btree/tree-block.ts +11 -11
  30. package/src/btree/trunk.ts +14 -14
  31. package/src/chain/chain-nodes.ts +26 -26
  32. package/src/chain/chain.ts +349 -349
  33. package/src/chain/index.ts +3 -3
  34. package/src/cluster/i-cluster.ts +6 -6
  35. package/src/cluster/index.ts +3 -3
  36. package/src/cohort-topic/addressing.ts +120 -120
  37. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  38. package/src/cohort-topic/antidos/index.ts +5 -5
  39. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  40. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  41. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  42. package/src/cohort-topic/antiflood/index.ts +2 -2
  43. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  44. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  45. package/src/cohort-topic/coldstart.ts +237 -237
  46. package/src/cohort-topic/dmax.ts +88 -88
  47. package/src/cohort-topic/gossip/bus.ts +254 -254
  48. package/src/cohort-topic/gossip/index.ts +3 -3
  49. package/src/cohort-topic/gossip/records.ts +45 -45
  50. package/src/cohort-topic/gossip/view.ts +91 -91
  51. package/src/cohort-topic/index.ts +20 -20
  52. package/src/cohort-topic/load/barometer.ts +134 -134
  53. package/src/cohort-topic/load/index.ts +1 -1
  54. package/src/cohort-topic/member-engine.ts +430 -430
  55. package/src/cohort-topic/membership/index.ts +3 -3
  56. package/src/cohort-topic/membership/publisher.ts +163 -163
  57. package/src/cohort-topic/membership/source.ts +41 -41
  58. package/src/cohort-topic/ports.ts +157 -157
  59. package/src/cohort-topic/promotion.ts +477 -477
  60. package/src/cohort-topic/registration/bytes.ts +37 -37
  61. package/src/cohort-topic/registration/handoff.ts +154 -154
  62. package/src/cohort-topic/registration/index.ts +6 -6
  63. package/src/cohort-topic/registration/renewal.ts +495 -495
  64. package/src/cohort-topic/registration/sharding.ts +61 -61
  65. package/src/cohort-topic/registration/store.ts +81 -81
  66. package/src/cohort-topic/registration/types.ts +91 -91
  67. package/src/cohort-topic/ring-hash.ts +50 -50
  68. package/src/cohort-topic/service.ts +416 -416
  69. package/src/cohort-topic/sig/index.ts +2 -2
  70. package/src/cohort-topic/sig/payloads.ts +59 -59
  71. package/src/cohort-topic/sig/threshold.ts +64 -64
  72. package/src/cohort-topic/tiers.ts +74 -74
  73. package/src/cohort-topic/traffic.ts +233 -233
  74. package/src/cohort-topic/walk.ts +326 -326
  75. package/src/cohort-topic/willingness.ts +237 -237
  76. package/src/cohort-topic/wire/index.ts +18 -18
  77. package/src/cohort-topic/wire/payloads.ts +126 -126
  78. package/src/collection/action.ts +48 -48
  79. package/src/collection/collection-type-registry.ts +37 -37
  80. package/src/collection/collection.ts +2203 -2118
  81. package/src/collection/index.ts +4 -4
  82. package/src/collections/diary/index.ts +2 -2
  83. package/src/collections/diary/struct.ts +3 -3
  84. package/src/collections/index.ts +2 -2
  85. package/src/collections/tree/collection-trunk.ts +25 -25
  86. package/src/collections/tree/index.ts +2 -2
  87. package/src/collections/tree/readme.md +55 -55
  88. package/src/log/index.ts +2 -2
  89. package/src/log/log.ts +304 -268
  90. package/src/log/struct.ts +165 -165
  91. package/src/matchmaking/capability-filter.ts +45 -45
  92. package/src/matchmaking/config.ts +98 -98
  93. package/src/matchmaking/index.ts +21 -21
  94. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  95. package/src/matchmaking/provider.ts +123 -123
  96. package/src/matchmaking/query-eval.ts +105 -105
  97. package/src/matchmaking/seeker-walk.ts +127 -127
  98. package/src/matchmaking/seeker.ts +86 -86
  99. package/src/matchmaking/topic-anchor.ts +90 -90
  100. package/src/matchmaking/voting-quorum.ts +394 -394
  101. package/src/network/i-peer-network.ts +25 -25
  102. package/src/network/repo-protocol.ts +13 -13
  103. package/src/network/types.ts +37 -37
  104. package/src/reactivity/backfill.ts +220 -220
  105. package/src/reactivity/backpressure.ts +191 -191
  106. package/src/reactivity/checkpoint.ts +308 -308
  107. package/src/reactivity/config.ts +172 -172
  108. package/src/reactivity/dedupe.ts +132 -132
  109. package/src/reactivity/forwarder.ts +87 -87
  110. package/src/reactivity/index.ts +34 -34
  111. package/src/reactivity/notification.ts +123 -123
  112. package/src/reactivity/policy.ts +79 -79
  113. package/src/reactivity/push-state.ts +310 -310
  114. package/src/reactivity/recover.ts +153 -153
  115. package/src/reactivity/replay-buffer.ts +141 -141
  116. package/src/reactivity/resume.ts +549 -549
  117. package/src/reactivity/rotation.ts +415 -415
  118. package/src/reactivity/subscriber.ts +132 -132
  119. package/src/reactivity/subscription.ts +66 -66
  120. package/src/reactivity/topic-anchor.ts +71 -71
  121. package/src/reactivity/verify.ts +73 -73
  122. package/src/reactivity/wire-validate.ts +13 -13
  123. package/src/testing/async-wait.ts +65 -65
  124. package/src/testing/index.ts +2 -2
  125. package/src/testing/test-transactor.ts +62 -0
  126. package/src/transaction/actions-engine.ts +68 -68
  127. package/src/transaction/coordinator.ts +28 -11
  128. package/src/transaction/index.ts +52 -52
  129. package/src/transaction/operations-hash.ts +196 -196
  130. package/src/transaction/read-dependency-collector.ts +78 -78
  131. package/src/transaction/session.ts +238 -238
  132. package/src/transaction/transaction.ts +442 -442
  133. package/src/transaction/validator.ts +197 -197
  134. package/src/transactor/block-floors.ts +126 -126
  135. package/src/transactor/index.ts +6 -6
  136. package/src/transactor/network-transactor.ts +1545 -1545
  137. package/src/transform/atomic-proxy.ts +92 -92
  138. package/src/transform/cache-source.ts +370 -370
  139. package/src/transform/helpers.ts +164 -164
  140. package/src/transform/index.ts +7 -7
  141. package/src/transform/struct.ts +21 -21
  142. package/src/utility/actor.ts +62 -62
  143. package/src/utility/backoff.ts +95 -95
  144. package/src/utility/batch-coordinator.ts +191 -191
  145. package/src/utility/ensured.ts +32 -32
  146. package/src/utility/groupby.ts +18 -18
  147. package/src/utility/hash-string.ts +14 -14
  148. package/src/utility/is-record-empty.ts +5 -5
  149. package/src/utility/latches.ts +42 -42
  150. package/src/utility/lru-map.ts +60 -60
  151. package/src/utility/nameof.ts +7 -7
  152. 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
+ }