@optimystic/db-core 1.4.0 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. package/README.md +336 -336
  2. package/dist/src/collection/collection.d.ts +44 -4
  3. package/dist/src/collection/collection.d.ts.map +1 -1
  4. package/dist/src/collection/collection.js +95 -14
  5. package/dist/src/collection/collection.js.map +1 -1
  6. package/dist/src/collections/tree/struct.d.ts +9 -4
  7. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  8. package/dist/src/collections/tree/struct.js +9 -4
  9. package/dist/src/collections/tree/struct.js.map +1 -1
  10. package/dist/src/log/log.d.ts +41 -8
  11. package/dist/src/log/log.d.ts.map +1 -1
  12. package/dist/src/log/log.js +15 -10
  13. package/dist/src/log/log.js.map +1 -1
  14. package/dist/src/testing/test-transactor.d.ts +36 -0
  15. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  16. package/dist/src/testing/test-transactor.js +49 -0
  17. package/dist/src/testing/test-transactor.js.map +1 -1
  18. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  19. package/dist/src/transaction/coordinator.js +26 -9
  20. package/dist/src/transaction/coordinator.js.map +1 -1
  21. package/package.json +1 -1
  22. package/src/blocks/block-store.ts +31 -31
  23. package/src/blocks/block-types.ts +11 -11
  24. package/src/blocks/index.ts +5 -5
  25. package/src/blocks/structs.ts +17 -17
  26. package/src/btree/btree.ts +872 -872
  27. package/src/btree/independent-trunk.ts +53 -53
  28. package/src/btree/index.ts +5 -5
  29. package/src/btree/key-range.ts +15 -15
  30. package/src/btree/keyset.ts +6 -6
  31. package/src/btree/nodes.ts +25 -25
  32. package/src/btree/path.ts +37 -37
  33. package/src/btree/tree-block.ts +11 -11
  34. package/src/btree/trunk.ts +14 -14
  35. package/src/chain/chain-nodes.ts +26 -26
  36. package/src/chain/chain.ts +349 -349
  37. package/src/chain/index.ts +3 -3
  38. package/src/cluster/i-cluster.ts +6 -6
  39. package/src/cluster/index.ts +3 -3
  40. package/src/cohort-topic/addressing.ts +120 -120
  41. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  42. package/src/cohort-topic/antidos/index.ts +5 -5
  43. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  44. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  45. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  46. package/src/cohort-topic/antiflood/index.ts +2 -2
  47. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  48. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  49. package/src/cohort-topic/coldstart.ts +237 -237
  50. package/src/cohort-topic/dmax.ts +88 -88
  51. package/src/cohort-topic/gossip/bus.ts +254 -254
  52. package/src/cohort-topic/gossip/index.ts +3 -3
  53. package/src/cohort-topic/gossip/records.ts +45 -45
  54. package/src/cohort-topic/gossip/view.ts +91 -91
  55. package/src/cohort-topic/index.ts +20 -20
  56. package/src/cohort-topic/load/barometer.ts +134 -134
  57. package/src/cohort-topic/load/index.ts +1 -1
  58. package/src/cohort-topic/member-engine.ts +430 -430
  59. package/src/cohort-topic/membership/index.ts +3 -3
  60. package/src/cohort-topic/membership/publisher.ts +163 -163
  61. package/src/cohort-topic/membership/source.ts +41 -41
  62. package/src/cohort-topic/ports.ts +157 -157
  63. package/src/cohort-topic/promotion.ts +477 -477
  64. package/src/cohort-topic/registration/bytes.ts +37 -37
  65. package/src/cohort-topic/registration/handoff.ts +154 -154
  66. package/src/cohort-topic/registration/index.ts +6 -6
  67. package/src/cohort-topic/registration/renewal.ts +495 -495
  68. package/src/cohort-topic/registration/sharding.ts +61 -61
  69. package/src/cohort-topic/registration/store.ts +81 -81
  70. package/src/cohort-topic/registration/types.ts +91 -91
  71. package/src/cohort-topic/ring-hash.ts +50 -50
  72. package/src/cohort-topic/service.ts +416 -416
  73. package/src/cohort-topic/sig/index.ts +2 -2
  74. package/src/cohort-topic/sig/payloads.ts +59 -59
  75. package/src/cohort-topic/sig/threshold.ts +64 -64
  76. package/src/cohort-topic/tiers.ts +74 -74
  77. package/src/cohort-topic/traffic.ts +233 -233
  78. package/src/cohort-topic/walk.ts +326 -326
  79. package/src/cohort-topic/willingness.ts +237 -237
  80. package/src/cohort-topic/wire/index.ts +18 -18
  81. package/src/cohort-topic/wire/payloads.ts +126 -126
  82. package/src/collection/action.ts +48 -48
  83. package/src/collection/collection-type-registry.ts +37 -37
  84. package/src/collection/collection.ts +2203 -2118
  85. package/src/collection/index.ts +4 -4
  86. package/src/collections/diary/index.ts +2 -2
  87. package/src/collections/diary/struct.ts +3 -3
  88. package/src/collections/index.ts +2 -2
  89. package/src/collections/tree/collection-trunk.ts +25 -25
  90. package/src/collections/tree/index.ts +2 -2
  91. package/src/collections/tree/readme.md +55 -55
  92. package/src/collections/tree/struct.ts +9 -4
  93. package/src/log/index.ts +2 -2
  94. package/src/log/log.ts +304 -268
  95. package/src/log/struct.ts +165 -165
  96. package/src/matchmaking/capability-filter.ts +45 -45
  97. package/src/matchmaking/config.ts +98 -98
  98. package/src/matchmaking/index.ts +21 -21
  99. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  100. package/src/matchmaking/provider.ts +123 -123
  101. package/src/matchmaking/query-eval.ts +105 -105
  102. package/src/matchmaking/seeker-walk.ts +127 -127
  103. package/src/matchmaking/seeker.ts +86 -86
  104. package/src/matchmaking/topic-anchor.ts +90 -90
  105. package/src/matchmaking/voting-quorum.ts +394 -394
  106. package/src/network/i-peer-network.ts +25 -25
  107. package/src/network/repo-protocol.ts +13 -13
  108. package/src/network/types.ts +37 -37
  109. package/src/reactivity/backfill.ts +220 -220
  110. package/src/reactivity/backpressure.ts +191 -191
  111. package/src/reactivity/checkpoint.ts +308 -308
  112. package/src/reactivity/config.ts +172 -172
  113. package/src/reactivity/dedupe.ts +132 -132
  114. package/src/reactivity/forwarder.ts +87 -87
  115. package/src/reactivity/index.ts +34 -34
  116. package/src/reactivity/notification.ts +123 -123
  117. package/src/reactivity/policy.ts +79 -79
  118. package/src/reactivity/push-state.ts +310 -310
  119. package/src/reactivity/recover.ts +153 -153
  120. package/src/reactivity/replay-buffer.ts +141 -141
  121. package/src/reactivity/resume.ts +549 -549
  122. package/src/reactivity/rotation.ts +415 -415
  123. package/src/reactivity/subscriber.ts +132 -132
  124. package/src/reactivity/subscription.ts +66 -66
  125. package/src/reactivity/topic-anchor.ts +71 -71
  126. package/src/reactivity/verify.ts +73 -73
  127. package/src/reactivity/wire-validate.ts +13 -13
  128. package/src/testing/async-wait.ts +65 -65
  129. package/src/testing/index.ts +2 -2
  130. package/src/testing/test-transactor.ts +62 -0
  131. package/src/transaction/actions-engine.ts +68 -68
  132. package/src/transaction/coordinator.ts +28 -11
  133. package/src/transaction/index.ts +52 -52
  134. package/src/transaction/operations-hash.ts +196 -196
  135. package/src/transaction/read-dependency-collector.ts +78 -78
  136. package/src/transaction/session.ts +238 -238
  137. package/src/transaction/transaction.ts +442 -442
  138. package/src/transaction/validator.ts +197 -197
  139. package/src/transactor/block-floors.ts +126 -126
  140. package/src/transactor/index.ts +6 -6
  141. package/src/transactor/network-transactor.ts +1545 -1545
  142. package/src/transform/atomic-proxy.ts +92 -92
  143. package/src/transform/cache-source.ts +370 -370
  144. package/src/transform/helpers.ts +164 -164
  145. package/src/transform/index.ts +7 -7
  146. package/src/transform/struct.ts +21 -21
  147. package/src/utility/actor.ts +62 -62
  148. package/src/utility/backoff.ts +95 -95
  149. package/src/utility/batch-coordinator.ts +191 -191
  150. package/src/utility/ensured.ts +32 -32
  151. package/src/utility/groupby.ts +18 -18
  152. package/src/utility/hash-string.ts +14 -14
  153. package/src/utility/is-record-empty.ts +5 -5
  154. package/src/utility/latches.ts +42 -42
  155. package/src/utility/lru-map.ts +60 -60
  156. package/src/utility/nameof.ts +7 -7
  157. package/src/utility/pending.ts +43 -43
@@ -1,442 +1,442 @@
1
- import { randomBytes } from "@noble/hashes/utils.js";
2
- import { toString as uint8ArrayToString } from "uint8arrays/to-string";
3
- import type { BlockId } from "../blocks/index.js";
4
- import type { CollectionId } from "../collection/index.js";
5
- import { hashString } from "../utility/hash-string.js";
6
-
7
- /**
8
- * Transaction Stamp: Created at BEGIN, stable throughout transaction lifecycle.
9
- *
10
- * The stamp contains metadata about the transaction's origin and context.
11
- * The id is computed as a hash of these fields.
12
- */
13
- export type TransactionStamp = {
14
- /** Peer that initiated the transaction */
15
- peerId: string;
16
-
17
- /** When transaction started (milliseconds since epoch) */
18
- timestamp: number;
19
-
20
- /** Hash of schema version(s) for validation */
21
- schemaHash: string;
22
-
23
- /** Which engine (e.g., 'quereus@0.5.3', 'actions@1.0.0') */
24
- engineId: string;
25
-
26
- /** Absolute ms epoch after which transaction is invalid */
27
- expiration: number;
28
-
29
- /**
30
- * Random per-transaction nonce, folded into {@link TransactionStamp.id}.
31
- *
32
- * Anti-replay for read-free transactions: a transaction with no reads has nothing
33
- * binding it to a point in history beyond {@link expiration}, so without this a
34
- * captured signed read-free transaction could be re-submitted within the TTL window.
35
- * The nonce makes two otherwise-identical transactions from the same peer at the
36
- * same millisecond produce different ids (hence different signed bytes).
37
- */
38
- nonce: string;
39
-
40
- /** Hash of the stamp fields (computed) - stable identifier throughout transaction */
41
- id: string;
42
- };
43
-
44
- /**
45
- * Transaction: Finalized at COMMIT with complete statement history.
46
- *
47
- * Transactions span multiple collections and use pluggable engines for interpreting the statements.
48
- * The engine re-executes the statements to verify the resulting operations match what was proposed.
49
- */
50
- export type Transaction = {
51
- /** The transaction stamp (includes stable id) */
52
- stamp: TransactionStamp;
53
-
54
- /** Engine-specific statements (for replay/validation)
55
- * Array of statements executed during the transaction.
56
- * - For Quereus: SQL statements
57
- * - For ActionsEngine: JSON-encoded actions
58
- */
59
- statements: string[];
60
-
61
- /** Read dependencies for optimistic concurrency control */
62
- reads: ReadDependency[];
63
-
64
- /** Transaction identifier (hash of stamp.id + statements + reads)
65
- * Final transaction identity, used in logs
66
- */
67
- id: string;
68
-
69
- /**
70
- * Optional client signature (base64url) over {@link clientSignaturePayload}
71
- * `(stamp.id, statements, reads)`, produced at commit by an injected
72
- * {@link TransactionSigner}.
73
- *
74
- * A node that wires a {@link ClientSignatureVerifier} into its
75
- * {@link TransactionValidator} verifies this at pend; where no verifier is wired,
76
- * unsigned transactions are still accepted (migration / single-node-dev posture).
77
- * Plain field on the transaction, so it rides along through serialization/persistence
78
- * for later recovery-time re-verification.
79
- *
80
- * NOTE: preservation is verified only through JSON round-trip and an in-memory session commit —
81
- * NOT yet through the db-p2p cluster-repo on-disk transaction-log serialization. No recovery
82
- * reader exists today; when one lands, confirm this field survives that path so `verifyPeerSig`
83
- * can re-run at recovery time.
84
- */
85
- signature?: string;
86
-
87
- /**
88
- * Aged, advisory retry priority (default 0 when absent). Rises by one per failed retry
89
- * attempt (attempt-count-derived — deterministic, no wall clock, clock-skew-free) and is
90
- * capped at {@link MaxPriority}. A cluster member uses it ONLY as the first tiebreak in a
91
- * concurrent race between two simultaneously-pending conflicting transactions
92
- * (`resolveRace`), so a transaction that keeps losing races eventually out-ranks fresh
93
- * (priority-0) rivals instead of losing at random forever.
94
- *
95
- * FAIRNESS-ONLY — MUST NOT influence validity, the operations hash, stale-read checks, the
96
- * transaction id, or the client signature. It is deliberately excluded from
97
- * {@link createTransactionId} and {@link clientSignaturePayload} so two attempts of the same
98
- * logical transaction (differing only in priority) keep the same id and signature; folding it
99
- * into either would churn identity/anti-replay on every retry. It rides inside the signed
100
- * cluster `message` (via the pend operation), so it is integrity-protected in transit — a
101
- * relaying peer cannot strip or inflate it without invalidating the message hash — but the
102
- * originating coordinator can still self-assert it (a fairness concern, not a safety one; see
103
- * `docs/correctness.md` Theorem 9).
104
- */
105
- priority?: number;
106
- };
107
-
108
- /**
109
- * Read dependency for optimistic concurrency control.
110
- * Tracks which block revisions were read during transaction execution.
111
- */
112
- export type ReadDependency = {
113
- blockId: BlockId;
114
- /** Expected revision number at time of read */
115
- revision: number;
116
- };
117
-
118
- /**
119
- * Transaction reference embedded in actions.
120
- * Just the transaction ID - full transaction can be looked up separately if needed.
121
- */
122
- export type TransactionRef = string; // The transaction ID
123
-
124
- /** Default transaction time-to-live in milliseconds (30 seconds). */
125
- export const DEFAULT_TRANSACTION_TTL_MS = 30_000;
126
-
127
- /**
128
- * Upper bound on a transaction's aged {@link Transaction.priority}. Capping is essential: it
129
- * bounds the fairness effect (an aged transaction cannot accrue unlimited advantage) and bounds
130
- * the throughput cost (it can impose at most `MaxPriority` extra race-losses on rivals before it
131
- * commits). Two transactions capped out at `MaxPriority` fall back to the existing approval-count /
132
- * message-hash tiebreak, so behavior degrades gracefully to the pre-priority status quo.
133
- */
134
- export const MaxPriority = 8;
135
-
136
- /**
137
- * Clamp an attempt-derived priority into `[0, MaxPriority]`. Total: any non-finite / negative
138
- * input collapses to 0, anything above the cap to {@link MaxPriority}, and the result is floored
139
- * to an integer. Used both where priority is *set* (the retry loops) and where it is *read* (a
140
- * cluster member's `resolveRace`), so a Byzantine coordinator self-asserting an out-of-range value
141
- * cannot exceed the cap.
142
- */
143
- export function clampPriority(priority: number | undefined): number {
144
- if (typeof priority !== 'number' || Number.isNaN(priority) || priority <= 0) {
145
- return 0;
146
- }
147
- // A positive out-of-range value (including +Infinity, or a Byzantine self-asserted number) clamps
148
- // DOWN to the cap; anything strictly inside the range is floored to an integer.
149
- if (priority >= MaxPriority) {
150
- return MaxPriority;
151
- }
152
- return Math.floor(priority);
153
- }
154
-
155
- /** Check whether a transaction stamp has expired. */
156
- export function isTransactionExpired(stamp: TransactionStamp): boolean {
157
- return Date.now() > stamp.expiration;
158
- }
159
-
160
- /** The stamp fields that feed the id hash (everything except the id itself). */
161
- export type StampFields = Omit<TransactionStamp, 'id'>;
162
-
163
- /**
164
- * Compute the canonical stamp id from its fields. MUST match the historical field order
165
- * (peerId, timestamp, schemaHash, engineId, expiration, nonce) — changing it churns every
166
- * existing stamp id and client signature. Both {@link createTransactionStamp} and the
167
- * validator's integrity check derive the id through this one function, so a validating node
168
- * can re-derive the id and reject a stamp whose fields were tampered while id stayed fixed.
169
- */
170
- export async function computeStampId(fields: StampFields): Promise<string> {
171
- // Destructure and rebuild in fixed order rather than passing `fields` straight to
172
- // JSON.stringify — this ignores any stray `id` (or extra) property a caller slipped in,
173
- // so the serialized bytes depend on exactly the six fields and nothing else.
174
- const { peerId, timestamp, schemaHash, engineId, expiration, nonce } = fields;
175
- const stampData = JSON.stringify({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
176
- return `stamp:${await hashString(stampData)}`;
177
- }
178
-
179
- /**
180
- * Create a transaction stamp with computed id.
181
- * The id is a hash of the stamp fields (including expiration).
182
- */
183
- export async function createTransactionStamp(
184
- peerId: string,
185
- timestamp: number,
186
- schemaHash: string,
187
- engineId: string,
188
- ttlMs: number = DEFAULT_TRANSACTION_TTL_MS
189
- ): Promise<TransactionStamp> {
190
- const expiration = timestamp + ttlMs;
191
- // Cross-platform CSPRNG (Node + browser) via @noble/hashes — matches the rest of
192
- // db-core (see collection.ts, transactor-source.ts). The nonce is folded into the
193
- // id hash so two otherwise-identical stamps diverge.
194
- const nonce = uint8ArrayToString(randomBytes(16), 'base64url');
195
- const id = await computeStampId({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
196
- return { peerId, timestamp, schemaHash, engineId, expiration, nonce, id };
197
- }
198
-
199
- /**
200
- * Create a transaction id from stamp id, statements, and reads.
201
- * This is the final transaction identity used in logs.
202
- *
203
- * NOTE: reads are serialized in their given order here (non-canonical). This differs
204
- * from {@link clientSignaturePayload}, which canonicalises reads before hashing. That is
205
- * intentional for this ticket — the signature payload is self-contained — but the
206
- * non-canonical ordering here is a separate hygiene concern (see
207
- * design-consensus-hygiene-notes), NOT fixed here to avoid changing existing tx ids.
208
- *
209
- * NOTE: {@link Transaction.priority} is deliberately absent from this preimage — the id is a pure
210
- * function of `(stampId, statements, reads)`, so two retry attempts that differ only in aged
211
- * priority produce the SAME id. Do not add priority here.
212
- */
213
- export async function createTransactionId(
214
- stampId: string,
215
- statements: string[],
216
- reads: ReadDependency[]
217
- ): Promise<string> {
218
- const txData = JSON.stringify({ stampId, statements, reads });
219
- return `tx:${await hashString(txData)}`;
220
- }
221
-
222
- /**
223
- * Version prefix for the client-signature payload, so the signed form can evolve
224
- * without ambiguity. Distinct from (but consistent in spirit with) the operations-hash
225
- * canonical form — this covers transaction INPUTS, not operations.
226
- */
227
- export const CLIENT_SIG_VERSION = 'txsig:v1';
228
-
229
- /**
230
- * Canonical bytes a client signs and a node verifies. Deterministic: reads are sorted
231
- * (blockId, then revision); statements keep their sequential order.
232
- *
233
- * Binds three things at once: the CLIENT IDENTITY (via `stampId`, which hashes peerId +
234
- * nonce), the EXACT statements, and the OCC read set (blockId + revision — "tail
235
- * binding" for anti-replay). Both signer and verifier derive the bytes from
236
- * `transaction.stamp.id` + `transaction.statements` + `transaction.reads` through this
237
- * one function, so they reproduce identical bytes regardless of read ordering.
238
- *
239
- * NOTE: {@link Transaction.priority} is deliberately absent from the signed bytes — a retry that
240
- * only bumps priority keeps the same signature, so anti-replay / OCC binding never churns. Do not
241
- * add priority here.
242
- */
243
- export function clientSignaturePayload(
244
- stampId: string,
245
- statements: readonly string[],
246
- reads: readonly ReadDependency[]
247
- ): Uint8Array {
248
- const canonicalReads = [...reads].sort(
249
- (a, b) => a.blockId < b.blockId ? -1 : a.blockId > b.blockId ? 1
250
- : a.revision - b.revision
251
- );
252
- const body = JSON.stringify({ stampId, statements, reads: canonicalReads });
253
- return new TextEncoder().encode(`${CLIENT_SIG_VERSION}:${body}`);
254
- }
255
-
256
- /**
257
- * Signs the canonical client-signature payload, returning base64url. Async to allow
258
- * libp2p `PrivateKey.sign`; tests pass a synchronous fake.
259
- */
260
- export type TransactionSigner = (payload: Uint8Array) => Promise<string> | string;
261
-
262
- /**
263
- * Returns true iff `signature` (base64url) is a valid client signature over `payload`
264
- * for signer identity `peerId`. Total: returns false, never throws, on any malformed
265
- * input. The p2p wiring backs this with verifyPeerSig + peerIdBindsPublicKey; tests
266
- * pass a fake.
267
- */
268
- export type ClientSignatureVerifier =
269
- (peerId: string, payload: Uint8Array, signature: string) => boolean;
270
-
271
-
272
-
273
- /**
274
- * Transaction engine interface.
275
- * Pluggable engines implement this to process transaction statements.
276
- *
277
- * Engines are responsible for:
278
- * 1. Parsing the engine-specific statements
279
- * 2. Executing/re-executing to produce actions
280
- * 3. Returning the resulting actions per collection
281
- *
282
- * CONTRACT — an engine must never cause the same action to be applied twice. The
283
- * caller (a {@link TransactionSession} on the no-pre-supplied-actions branch, or a
284
- * {@link TransactionCoordinator} in `execute()`) applies whatever non-empty
285
- * `CollectionActions[]` this method RETURNS. Therefore `execute()` must satisfy
286
- * exactly ONE of:
287
- *
288
- * (a) PURE TRANSLATOR (preferred; how {@link ActionsEngine} works) — parse the
289
- * statements, RETURN the actions, and do NOT apply them / do NOT call
290
- * `coordinator.applyActions` / do NOT mutate any collection state. The caller
291
- * applies them exactly once.
292
- *
293
- * (b) SIDE-EFFECT APPLY — apply the actions itself while translating (e.g. the
294
- * Quereus vtab path stages rows into the coordinator during `db.exec`) and then
295
- * RETURN an EMPTY actions array, so the caller re-applies nothing.
296
- *
297
- * An engine that BOTH applies as a side effect AND returns those same actions
298
- * double-applies (the caller re-applies the returned actions). Additionally, a
299
- * side-effecting engine used for validation must apply only to the validator's
300
- * ISOLATED coordinator — applying to the main coordinator leaks into the validating
301
- * node's live state.
302
- */
303
- export interface ITransactionEngine {
304
- /**
305
- * Stable identifier for this engine.
306
- *
307
- * This is the value stamped into {@link TransactionStamp.engineId} when a
308
- * {@link TransactionSession} builds a transaction, and the key a
309
- * {@link TransactionValidator} resolves the engine by. It MUST match the key the
310
- * engine is registered under in the validator's `engines` map — otherwise a
311
- * validating node rejects the transaction as `Unknown engine: <id>` before it
312
- * ever re-executes.
313
- */
314
- readonly id: string;
315
-
316
- /**
317
- * Process a transaction statements to produce actions.
318
- *
319
- * Used both for:
320
- * - Initial execution (client creating transaction)
321
- * - Re-execution (validators verifying transaction)
322
- *
323
- * @param transaction - The transaction to process
324
- * @returns The resulting actions from execution
325
- */
326
- execute(transaction: Transaction): Promise<ExecutionResult>;
327
- }
328
-
329
- /**
330
- * Result of transaction execution.
331
- */
332
- export type ExecutionResult = {
333
- /** Whether execution succeeded */
334
- success: boolean;
335
- /** Actions produced by executing the transaction */
336
- actions?: CollectionActions[];
337
- /** Results from executing actions (e.g., return values from reads) */
338
- results?: Map<CollectionId, any[]>;
339
- /** Error message if execution failed */
340
- error?: string;
341
- /**
342
- * On a PARTIAL multi-collection commit failure, the collections that DID durably
343
- * commit through consensus before the failure (and thus CANNOT be rolled back —
344
- * reconciliation is required). Absent/empty means nothing durably committed, so
345
- * the caller may treat the failure as a clean abort — including calling
346
- * `coordinator.rollback(stampId)`, which is still a valid and complete recovery there.
347
- *
348
- * When this IS present, the coordinator has already given the committed collections
349
- * the success-path local treatment and restored the failed ones to their pre-staging
350
- * state, and has DROPPED the transaction's rollback tracking — so
351
- * `coordinator.rollback(stampId)` is a deliberate no-op rather than a rewind that
352
- * would corrupt the collections that did commit. Reconciliation means driving a NEW
353
- * transaction naming only the failed collections; re-driving THIS transaction through
354
- * `execute()` would re-stage and re-apply the committed half a second time.
355
- *
356
- * See {@link CoordinatorPartialCommitError} for the session-mode (commit) analog.
357
- */
358
- committedCollections?: CollectionId[];
359
- /** On a partial multi-collection commit failure, the collections that failed to commit. */
360
- failedCollections?: CollectionId[];
361
- };
362
-
363
- /**
364
- * Actions for a specific collection resulting from transaction execution.
365
- */
366
- export type CollectionActions = {
367
- /** Collection identifier */
368
- collectionId: string;
369
- /** Actions to apply to this collection */
370
- actions: unknown[];
371
- };
372
-
373
- /**
374
- * Helper to create an actions-based transaction statements array.
375
- * Each CollectionActions becomes a separate JSON-encoded statement.
376
- */
377
- export function createActionsStatements(collections: CollectionActions[]): string[] {
378
- return collections.map(c => JSON.stringify(c));
379
- }
380
-
381
- /**
382
- * Statement format for the actions engine (array of CollectionActions).
383
- * @deprecated Use CollectionActions[] directly
384
- */
385
- export type ActionsStatement = {
386
- collections: CollectionActions[];
387
- };
388
-
389
- /**
390
- * Result of transaction validation.
391
- */
392
- export type ValidationResult = {
393
- /** Whether validation succeeded */
394
- valid: boolean;
395
- /** Reason for validation failure (if valid=false) */
396
- reason?: string;
397
- /** The operations hash computed during validation (for debugging) */
398
- computedHash?: string;
399
- };
400
-
401
- /**
402
- * Transaction validator interface.
403
- * Pluggable validators implement this to verify transaction integrity.
404
- *
405
- * Validators are invoked when a node receives a PendRequest carrying a `validation`
406
- * payload (the transaction plus its operations hash). They re-execute the transaction
407
- * and verify the operations match. A throw out of {@link validate} is treated by
408
- * callers as a rejection ("validator-fault: …"), never as an approval or an abstain.
409
- */
410
- export interface ITransactionValidator {
411
- /**
412
- * Validate a transaction by re-executing and comparing operations hash.
413
- *
414
- * Validation steps (see TransactionValidator.validate for the authoritative order):
415
- * 0.0. Verify stamp.id is the true hash of the stamp fields (integrity — runs first,
416
- * since every later step trusts a stamp field)
417
- * 0. Verify the stamp has not expired
418
- * 0.5. Verify the client signature (only if a signature verifier is wired)
419
- * 1. Verify stamp.engineId matches a known engine
420
- * 2. Verify stamp.schemaHash matches local schema
421
- * 3. Verify read dependencies (no stale reads)
422
- * 4. Re-execute transaction.statements through engine (isolated state)
423
- * 5. Collect operations from re-execution
424
- * 6. Compute hash of operations
425
- * 7. Compare with sender's operationsHash
426
- *
427
- * @param transaction - The transaction to validate
428
- * @param operationsHash - The hash to compare against
429
- * @returns Validation result
430
- */
431
- validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult>;
432
-
433
- /**
434
- * Get the schema hash for a given engine.
435
- * Used to verify the sender's schema matches local schema.
436
- *
437
- * @param engineId - The engine identifier
438
- * @returns The schema hash, or undefined if engine not found
439
- */
440
- getSchemaHash(engineId: string): Promise<string | undefined>;
441
- }
442
-
1
+ import { randomBytes } from "@noble/hashes/utils.js";
2
+ import { toString as uint8ArrayToString } from "uint8arrays/to-string";
3
+ import type { BlockId } from "../blocks/index.js";
4
+ import type { CollectionId } from "../collection/index.js";
5
+ import { hashString } from "../utility/hash-string.js";
6
+
7
+ /**
8
+ * Transaction Stamp: Created at BEGIN, stable throughout transaction lifecycle.
9
+ *
10
+ * The stamp contains metadata about the transaction's origin and context.
11
+ * The id is computed as a hash of these fields.
12
+ */
13
+ export type TransactionStamp = {
14
+ /** Peer that initiated the transaction */
15
+ peerId: string;
16
+
17
+ /** When transaction started (milliseconds since epoch) */
18
+ timestamp: number;
19
+
20
+ /** Hash of schema version(s) for validation */
21
+ schemaHash: string;
22
+
23
+ /** Which engine (e.g., 'quereus@0.5.3', 'actions@1.0.0') */
24
+ engineId: string;
25
+
26
+ /** Absolute ms epoch after which transaction is invalid */
27
+ expiration: number;
28
+
29
+ /**
30
+ * Random per-transaction nonce, folded into {@link TransactionStamp.id}.
31
+ *
32
+ * Anti-replay for read-free transactions: a transaction with no reads has nothing
33
+ * binding it to a point in history beyond {@link expiration}, so without this a
34
+ * captured signed read-free transaction could be re-submitted within the TTL window.
35
+ * The nonce makes two otherwise-identical transactions from the same peer at the
36
+ * same millisecond produce different ids (hence different signed bytes).
37
+ */
38
+ nonce: string;
39
+
40
+ /** Hash of the stamp fields (computed) - stable identifier throughout transaction */
41
+ id: string;
42
+ };
43
+
44
+ /**
45
+ * Transaction: Finalized at COMMIT with complete statement history.
46
+ *
47
+ * Transactions span multiple collections and use pluggable engines for interpreting the statements.
48
+ * The engine re-executes the statements to verify the resulting operations match what was proposed.
49
+ */
50
+ export type Transaction = {
51
+ /** The transaction stamp (includes stable id) */
52
+ stamp: TransactionStamp;
53
+
54
+ /** Engine-specific statements (for replay/validation)
55
+ * Array of statements executed during the transaction.
56
+ * - For Quereus: SQL statements
57
+ * - For ActionsEngine: JSON-encoded actions
58
+ */
59
+ statements: string[];
60
+
61
+ /** Read dependencies for optimistic concurrency control */
62
+ reads: ReadDependency[];
63
+
64
+ /** Transaction identifier (hash of stamp.id + statements + reads)
65
+ * Final transaction identity, used in logs
66
+ */
67
+ id: string;
68
+
69
+ /**
70
+ * Optional client signature (base64url) over {@link clientSignaturePayload}
71
+ * `(stamp.id, statements, reads)`, produced at commit by an injected
72
+ * {@link TransactionSigner}.
73
+ *
74
+ * A node that wires a {@link ClientSignatureVerifier} into its
75
+ * {@link TransactionValidator} verifies this at pend; where no verifier is wired,
76
+ * unsigned transactions are still accepted (migration / single-node-dev posture).
77
+ * Plain field on the transaction, so it rides along through serialization/persistence
78
+ * for later recovery-time re-verification.
79
+ *
80
+ * NOTE: preservation is verified only through JSON round-trip and an in-memory session commit —
81
+ * NOT yet through the db-p2p cluster-repo on-disk transaction-log serialization. No recovery
82
+ * reader exists today; when one lands, confirm this field survives that path so `verifyPeerSig`
83
+ * can re-run at recovery time.
84
+ */
85
+ signature?: string;
86
+
87
+ /**
88
+ * Aged, advisory retry priority (default 0 when absent). Rises by one per failed retry
89
+ * attempt (attempt-count-derived — deterministic, no wall clock, clock-skew-free) and is
90
+ * capped at {@link MaxPriority}. A cluster member uses it ONLY as the first tiebreak in a
91
+ * concurrent race between two simultaneously-pending conflicting transactions
92
+ * (`resolveRace`), so a transaction that keeps losing races eventually out-ranks fresh
93
+ * (priority-0) rivals instead of losing at random forever.
94
+ *
95
+ * FAIRNESS-ONLY — MUST NOT influence validity, the operations hash, stale-read checks, the
96
+ * transaction id, or the client signature. It is deliberately excluded from
97
+ * {@link createTransactionId} and {@link clientSignaturePayload} so two attempts of the same
98
+ * logical transaction (differing only in priority) keep the same id and signature; folding it
99
+ * into either would churn identity/anti-replay on every retry. It rides inside the signed
100
+ * cluster `message` (via the pend operation), so it is integrity-protected in transit — a
101
+ * relaying peer cannot strip or inflate it without invalidating the message hash — but the
102
+ * originating coordinator can still self-assert it (a fairness concern, not a safety one; see
103
+ * `docs/correctness.md` Theorem 9).
104
+ */
105
+ priority?: number;
106
+ };
107
+
108
+ /**
109
+ * Read dependency for optimistic concurrency control.
110
+ * Tracks which block revisions were read during transaction execution.
111
+ */
112
+ export type ReadDependency = {
113
+ blockId: BlockId;
114
+ /** Expected revision number at time of read */
115
+ revision: number;
116
+ };
117
+
118
+ /**
119
+ * Transaction reference embedded in actions.
120
+ * Just the transaction ID - full transaction can be looked up separately if needed.
121
+ */
122
+ export type TransactionRef = string; // The transaction ID
123
+
124
+ /** Default transaction time-to-live in milliseconds (30 seconds). */
125
+ export const DEFAULT_TRANSACTION_TTL_MS = 30_000;
126
+
127
+ /**
128
+ * Upper bound on a transaction's aged {@link Transaction.priority}. Capping is essential: it
129
+ * bounds the fairness effect (an aged transaction cannot accrue unlimited advantage) and bounds
130
+ * the throughput cost (it can impose at most `MaxPriority` extra race-losses on rivals before it
131
+ * commits). Two transactions capped out at `MaxPriority` fall back to the existing approval-count /
132
+ * message-hash tiebreak, so behavior degrades gracefully to the pre-priority status quo.
133
+ */
134
+ export const MaxPriority = 8;
135
+
136
+ /**
137
+ * Clamp an attempt-derived priority into `[0, MaxPriority]`. Total: any non-finite / negative
138
+ * input collapses to 0, anything above the cap to {@link MaxPriority}, and the result is floored
139
+ * to an integer. Used both where priority is *set* (the retry loops) and where it is *read* (a
140
+ * cluster member's `resolveRace`), so a Byzantine coordinator self-asserting an out-of-range value
141
+ * cannot exceed the cap.
142
+ */
143
+ export function clampPriority(priority: number | undefined): number {
144
+ if (typeof priority !== 'number' || Number.isNaN(priority) || priority <= 0) {
145
+ return 0;
146
+ }
147
+ // A positive out-of-range value (including +Infinity, or a Byzantine self-asserted number) clamps
148
+ // DOWN to the cap; anything strictly inside the range is floored to an integer.
149
+ if (priority >= MaxPriority) {
150
+ return MaxPriority;
151
+ }
152
+ return Math.floor(priority);
153
+ }
154
+
155
+ /** Check whether a transaction stamp has expired. */
156
+ export function isTransactionExpired(stamp: TransactionStamp): boolean {
157
+ return Date.now() > stamp.expiration;
158
+ }
159
+
160
+ /** The stamp fields that feed the id hash (everything except the id itself). */
161
+ export type StampFields = Omit<TransactionStamp, 'id'>;
162
+
163
+ /**
164
+ * Compute the canonical stamp id from its fields. MUST match the historical field order
165
+ * (peerId, timestamp, schemaHash, engineId, expiration, nonce) — changing it churns every
166
+ * existing stamp id and client signature. Both {@link createTransactionStamp} and the
167
+ * validator's integrity check derive the id through this one function, so a validating node
168
+ * can re-derive the id and reject a stamp whose fields were tampered while id stayed fixed.
169
+ */
170
+ export async function computeStampId(fields: StampFields): Promise<string> {
171
+ // Destructure and rebuild in fixed order rather than passing `fields` straight to
172
+ // JSON.stringify — this ignores any stray `id` (or extra) property a caller slipped in,
173
+ // so the serialized bytes depend on exactly the six fields and nothing else.
174
+ const { peerId, timestamp, schemaHash, engineId, expiration, nonce } = fields;
175
+ const stampData = JSON.stringify({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
176
+ return `stamp:${await hashString(stampData)}`;
177
+ }
178
+
179
+ /**
180
+ * Create a transaction stamp with computed id.
181
+ * The id is a hash of the stamp fields (including expiration).
182
+ */
183
+ export async function createTransactionStamp(
184
+ peerId: string,
185
+ timestamp: number,
186
+ schemaHash: string,
187
+ engineId: string,
188
+ ttlMs: number = DEFAULT_TRANSACTION_TTL_MS
189
+ ): Promise<TransactionStamp> {
190
+ const expiration = timestamp + ttlMs;
191
+ // Cross-platform CSPRNG (Node + browser) via @noble/hashes — matches the rest of
192
+ // db-core (see collection.ts, transactor-source.ts). The nonce is folded into the
193
+ // id hash so two otherwise-identical stamps diverge.
194
+ const nonce = uint8ArrayToString(randomBytes(16), 'base64url');
195
+ const id = await computeStampId({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
196
+ return { peerId, timestamp, schemaHash, engineId, expiration, nonce, id };
197
+ }
198
+
199
+ /**
200
+ * Create a transaction id from stamp id, statements, and reads.
201
+ * This is the final transaction identity used in logs.
202
+ *
203
+ * NOTE: reads are serialized in their given order here (non-canonical). This differs
204
+ * from {@link clientSignaturePayload}, which canonicalises reads before hashing. That is
205
+ * intentional for this ticket — the signature payload is self-contained — but the
206
+ * non-canonical ordering here is a separate hygiene concern (see
207
+ * design-consensus-hygiene-notes), NOT fixed here to avoid changing existing tx ids.
208
+ *
209
+ * NOTE: {@link Transaction.priority} is deliberately absent from this preimage — the id is a pure
210
+ * function of `(stampId, statements, reads)`, so two retry attempts that differ only in aged
211
+ * priority produce the SAME id. Do not add priority here.
212
+ */
213
+ export async function createTransactionId(
214
+ stampId: string,
215
+ statements: string[],
216
+ reads: ReadDependency[]
217
+ ): Promise<string> {
218
+ const txData = JSON.stringify({ stampId, statements, reads });
219
+ return `tx:${await hashString(txData)}`;
220
+ }
221
+
222
+ /**
223
+ * Version prefix for the client-signature payload, so the signed form can evolve
224
+ * without ambiguity. Distinct from (but consistent in spirit with) the operations-hash
225
+ * canonical form — this covers transaction INPUTS, not operations.
226
+ */
227
+ export const CLIENT_SIG_VERSION = 'txsig:v1';
228
+
229
+ /**
230
+ * Canonical bytes a client signs and a node verifies. Deterministic: reads are sorted
231
+ * (blockId, then revision); statements keep their sequential order.
232
+ *
233
+ * Binds three things at once: the CLIENT IDENTITY (via `stampId`, which hashes peerId +
234
+ * nonce), the EXACT statements, and the OCC read set (blockId + revision — "tail
235
+ * binding" for anti-replay). Both signer and verifier derive the bytes from
236
+ * `transaction.stamp.id` + `transaction.statements` + `transaction.reads` through this
237
+ * one function, so they reproduce identical bytes regardless of read ordering.
238
+ *
239
+ * NOTE: {@link Transaction.priority} is deliberately absent from the signed bytes — a retry that
240
+ * only bumps priority keeps the same signature, so anti-replay / OCC binding never churns. Do not
241
+ * add priority here.
242
+ */
243
+ export function clientSignaturePayload(
244
+ stampId: string,
245
+ statements: readonly string[],
246
+ reads: readonly ReadDependency[]
247
+ ): Uint8Array {
248
+ const canonicalReads = [...reads].sort(
249
+ (a, b) => a.blockId < b.blockId ? -1 : a.blockId > b.blockId ? 1
250
+ : a.revision - b.revision
251
+ );
252
+ const body = JSON.stringify({ stampId, statements, reads: canonicalReads });
253
+ return new TextEncoder().encode(`${CLIENT_SIG_VERSION}:${body}`);
254
+ }
255
+
256
+ /**
257
+ * Signs the canonical client-signature payload, returning base64url. Async to allow
258
+ * libp2p `PrivateKey.sign`; tests pass a synchronous fake.
259
+ */
260
+ export type TransactionSigner = (payload: Uint8Array) => Promise<string> | string;
261
+
262
+ /**
263
+ * Returns true iff `signature` (base64url) is a valid client signature over `payload`
264
+ * for signer identity `peerId`. Total: returns false, never throws, on any malformed
265
+ * input. The p2p wiring backs this with verifyPeerSig + peerIdBindsPublicKey; tests
266
+ * pass a fake.
267
+ */
268
+ export type ClientSignatureVerifier =
269
+ (peerId: string, payload: Uint8Array, signature: string) => boolean;
270
+
271
+
272
+
273
+ /**
274
+ * Transaction engine interface.
275
+ * Pluggable engines implement this to process transaction statements.
276
+ *
277
+ * Engines are responsible for:
278
+ * 1. Parsing the engine-specific statements
279
+ * 2. Executing/re-executing to produce actions
280
+ * 3. Returning the resulting actions per collection
281
+ *
282
+ * CONTRACT — an engine must never cause the same action to be applied twice. The
283
+ * caller (a {@link TransactionSession} on the no-pre-supplied-actions branch, or a
284
+ * {@link TransactionCoordinator} in `execute()`) applies whatever non-empty
285
+ * `CollectionActions[]` this method RETURNS. Therefore `execute()` must satisfy
286
+ * exactly ONE of:
287
+ *
288
+ * (a) PURE TRANSLATOR (preferred; how {@link ActionsEngine} works) — parse the
289
+ * statements, RETURN the actions, and do NOT apply them / do NOT call
290
+ * `coordinator.applyActions` / do NOT mutate any collection state. The caller
291
+ * applies them exactly once.
292
+ *
293
+ * (b) SIDE-EFFECT APPLY — apply the actions itself while translating (e.g. the
294
+ * Quereus vtab path stages rows into the coordinator during `db.exec`) and then
295
+ * RETURN an EMPTY actions array, so the caller re-applies nothing.
296
+ *
297
+ * An engine that BOTH applies as a side effect AND returns those same actions
298
+ * double-applies (the caller re-applies the returned actions). Additionally, a
299
+ * side-effecting engine used for validation must apply only to the validator's
300
+ * ISOLATED coordinator — applying to the main coordinator leaks into the validating
301
+ * node's live state.
302
+ */
303
+ export interface ITransactionEngine {
304
+ /**
305
+ * Stable identifier for this engine.
306
+ *
307
+ * This is the value stamped into {@link TransactionStamp.engineId} when a
308
+ * {@link TransactionSession} builds a transaction, and the key a
309
+ * {@link TransactionValidator} resolves the engine by. It MUST match the key the
310
+ * engine is registered under in the validator's `engines` map — otherwise a
311
+ * validating node rejects the transaction as `Unknown engine: <id>` before it
312
+ * ever re-executes.
313
+ */
314
+ readonly id: string;
315
+
316
+ /**
317
+ * Process a transaction statements to produce actions.
318
+ *
319
+ * Used both for:
320
+ * - Initial execution (client creating transaction)
321
+ * - Re-execution (validators verifying transaction)
322
+ *
323
+ * @param transaction - The transaction to process
324
+ * @returns The resulting actions from execution
325
+ */
326
+ execute(transaction: Transaction): Promise<ExecutionResult>;
327
+ }
328
+
329
+ /**
330
+ * Result of transaction execution.
331
+ */
332
+ export type ExecutionResult = {
333
+ /** Whether execution succeeded */
334
+ success: boolean;
335
+ /** Actions produced by executing the transaction */
336
+ actions?: CollectionActions[];
337
+ /** Results from executing actions (e.g., return values from reads) */
338
+ results?: Map<CollectionId, any[]>;
339
+ /** Error message if execution failed */
340
+ error?: string;
341
+ /**
342
+ * On a PARTIAL multi-collection commit failure, the collections that DID durably
343
+ * commit through consensus before the failure (and thus CANNOT be rolled back —
344
+ * reconciliation is required). Absent/empty means nothing durably committed, so
345
+ * the caller may treat the failure as a clean abort — including calling
346
+ * `coordinator.rollback(stampId)`, which is still a valid and complete recovery there.
347
+ *
348
+ * When this IS present, the coordinator has already given the committed collections
349
+ * the success-path local treatment and restored the failed ones to their pre-staging
350
+ * state, and has DROPPED the transaction's rollback tracking — so
351
+ * `coordinator.rollback(stampId)` is a deliberate no-op rather than a rewind that
352
+ * would corrupt the collections that did commit. Reconciliation means driving a NEW
353
+ * transaction naming only the failed collections; re-driving THIS transaction through
354
+ * `execute()` would re-stage and re-apply the committed half a second time.
355
+ *
356
+ * See {@link CoordinatorPartialCommitError} for the session-mode (commit) analog.
357
+ */
358
+ committedCollections?: CollectionId[];
359
+ /** On a partial multi-collection commit failure, the collections that failed to commit. */
360
+ failedCollections?: CollectionId[];
361
+ };
362
+
363
+ /**
364
+ * Actions for a specific collection resulting from transaction execution.
365
+ */
366
+ export type CollectionActions = {
367
+ /** Collection identifier */
368
+ collectionId: string;
369
+ /** Actions to apply to this collection */
370
+ actions: unknown[];
371
+ };
372
+
373
+ /**
374
+ * Helper to create an actions-based transaction statements array.
375
+ * Each CollectionActions becomes a separate JSON-encoded statement.
376
+ */
377
+ export function createActionsStatements(collections: CollectionActions[]): string[] {
378
+ return collections.map(c => JSON.stringify(c));
379
+ }
380
+
381
+ /**
382
+ * Statement format for the actions engine (array of CollectionActions).
383
+ * @deprecated Use CollectionActions[] directly
384
+ */
385
+ export type ActionsStatement = {
386
+ collections: CollectionActions[];
387
+ };
388
+
389
+ /**
390
+ * Result of transaction validation.
391
+ */
392
+ export type ValidationResult = {
393
+ /** Whether validation succeeded */
394
+ valid: boolean;
395
+ /** Reason for validation failure (if valid=false) */
396
+ reason?: string;
397
+ /** The operations hash computed during validation (for debugging) */
398
+ computedHash?: string;
399
+ };
400
+
401
+ /**
402
+ * Transaction validator interface.
403
+ * Pluggable validators implement this to verify transaction integrity.
404
+ *
405
+ * Validators are invoked when a node receives a PendRequest carrying a `validation`
406
+ * payload (the transaction plus its operations hash). They re-execute the transaction
407
+ * and verify the operations match. A throw out of {@link validate} is treated by
408
+ * callers as a rejection ("validator-fault: …"), never as an approval or an abstain.
409
+ */
410
+ export interface ITransactionValidator {
411
+ /**
412
+ * Validate a transaction by re-executing and comparing operations hash.
413
+ *
414
+ * Validation steps (see TransactionValidator.validate for the authoritative order):
415
+ * 0.0. Verify stamp.id is the true hash of the stamp fields (integrity — runs first,
416
+ * since every later step trusts a stamp field)
417
+ * 0. Verify the stamp has not expired
418
+ * 0.5. Verify the client signature (only if a signature verifier is wired)
419
+ * 1. Verify stamp.engineId matches a known engine
420
+ * 2. Verify stamp.schemaHash matches local schema
421
+ * 3. Verify read dependencies (no stale reads)
422
+ * 4. Re-execute transaction.statements through engine (isolated state)
423
+ * 5. Collect operations from re-execution
424
+ * 6. Compute hash of operations
425
+ * 7. Compare with sender's operationsHash
426
+ *
427
+ * @param transaction - The transaction to validate
428
+ * @param operationsHash - The hash to compare against
429
+ * @returns Validation result
430
+ */
431
+ validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult>;
432
+
433
+ /**
434
+ * Get the schema hash for a given engine.
435
+ * Used to verify the sender's schema matches local schema.
436
+ *
437
+ * @param engineId - The engine identifier
438
+ * @returns The schema hash, or undefined if engine not found
439
+ */
440
+ getSchemaHash(engineId: string): Promise<string | undefined>;
441
+ }
442
+