@optimystic/db-core 1.22.0 → 1.23.0

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