@optimystic/db-core 1.5.0 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. package/README.md +336 -336
  2. package/dist/src/collection/collection.d.ts +44 -4
  3. package/dist/src/collection/collection.d.ts.map +1 -1
  4. package/dist/src/collection/collection.js +95 -14
  5. package/dist/src/collection/collection.js.map +1 -1
  6. package/dist/src/log/log.d.ts +41 -8
  7. package/dist/src/log/log.d.ts.map +1 -1
  8. package/dist/src/log/log.js +15 -10
  9. package/dist/src/log/log.js.map +1 -1
  10. package/dist/src/testing/test-transactor.d.ts +36 -0
  11. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  12. package/dist/src/testing/test-transactor.js +49 -0
  13. package/dist/src/testing/test-transactor.js.map +1 -1
  14. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  15. package/dist/src/transaction/coordinator.js +26 -9
  16. package/dist/src/transaction/coordinator.js.map +1 -1
  17. package/package.json +1 -1
  18. package/src/blocks/block-store.ts +31 -31
  19. package/src/blocks/block-types.ts +11 -11
  20. package/src/blocks/index.ts +5 -5
  21. package/src/blocks/structs.ts +17 -17
  22. package/src/btree/btree.ts +872 -872
  23. package/src/btree/independent-trunk.ts +53 -53
  24. package/src/btree/index.ts +5 -5
  25. package/src/btree/key-range.ts +15 -15
  26. package/src/btree/keyset.ts +6 -6
  27. package/src/btree/nodes.ts +25 -25
  28. package/src/btree/path.ts +37 -37
  29. package/src/btree/tree-block.ts +11 -11
  30. package/src/btree/trunk.ts +14 -14
  31. package/src/chain/chain-nodes.ts +26 -26
  32. package/src/chain/chain.ts +349 -349
  33. package/src/chain/index.ts +3 -3
  34. package/src/cluster/i-cluster.ts +6 -6
  35. package/src/cluster/index.ts +3 -3
  36. package/src/cohort-topic/addressing.ts +120 -120
  37. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  38. package/src/cohort-topic/antidos/index.ts +5 -5
  39. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  40. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  41. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  42. package/src/cohort-topic/antiflood/index.ts +2 -2
  43. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  44. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  45. package/src/cohort-topic/coldstart.ts +237 -237
  46. package/src/cohort-topic/dmax.ts +88 -88
  47. package/src/cohort-topic/gossip/bus.ts +254 -254
  48. package/src/cohort-topic/gossip/index.ts +3 -3
  49. package/src/cohort-topic/gossip/records.ts +45 -45
  50. package/src/cohort-topic/gossip/view.ts +91 -91
  51. package/src/cohort-topic/index.ts +20 -20
  52. package/src/cohort-topic/load/barometer.ts +134 -134
  53. package/src/cohort-topic/load/index.ts +1 -1
  54. package/src/cohort-topic/member-engine.ts +430 -430
  55. package/src/cohort-topic/membership/index.ts +3 -3
  56. package/src/cohort-topic/membership/publisher.ts +163 -163
  57. package/src/cohort-topic/membership/source.ts +41 -41
  58. package/src/cohort-topic/ports.ts +157 -157
  59. package/src/cohort-topic/promotion.ts +477 -477
  60. package/src/cohort-topic/registration/bytes.ts +37 -37
  61. package/src/cohort-topic/registration/handoff.ts +154 -154
  62. package/src/cohort-topic/registration/index.ts +6 -6
  63. package/src/cohort-topic/registration/renewal.ts +495 -495
  64. package/src/cohort-topic/registration/sharding.ts +61 -61
  65. package/src/cohort-topic/registration/store.ts +81 -81
  66. package/src/cohort-topic/registration/types.ts +91 -91
  67. package/src/cohort-topic/ring-hash.ts +50 -50
  68. package/src/cohort-topic/service.ts +416 -416
  69. package/src/cohort-topic/sig/index.ts +2 -2
  70. package/src/cohort-topic/sig/payloads.ts +59 -59
  71. package/src/cohort-topic/sig/threshold.ts +64 -64
  72. package/src/cohort-topic/tiers.ts +74 -74
  73. package/src/cohort-topic/traffic.ts +233 -233
  74. package/src/cohort-topic/walk.ts +326 -326
  75. package/src/cohort-topic/willingness.ts +237 -237
  76. package/src/cohort-topic/wire/index.ts +18 -18
  77. package/src/cohort-topic/wire/payloads.ts +126 -126
  78. package/src/collection/action.ts +48 -48
  79. package/src/collection/collection-type-registry.ts +37 -37
  80. package/src/collection/collection.ts +2203 -2118
  81. package/src/collection/index.ts +4 -4
  82. package/src/collections/diary/index.ts +2 -2
  83. package/src/collections/diary/struct.ts +3 -3
  84. package/src/collections/index.ts +2 -2
  85. package/src/collections/tree/collection-trunk.ts +25 -25
  86. package/src/collections/tree/index.ts +2 -2
  87. package/src/collections/tree/readme.md +55 -55
  88. package/src/log/index.ts +2 -2
  89. package/src/log/log.ts +304 -268
  90. package/src/log/struct.ts +165 -165
  91. package/src/matchmaking/capability-filter.ts +45 -45
  92. package/src/matchmaking/config.ts +98 -98
  93. package/src/matchmaking/index.ts +21 -21
  94. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  95. package/src/matchmaking/provider.ts +123 -123
  96. package/src/matchmaking/query-eval.ts +105 -105
  97. package/src/matchmaking/seeker-walk.ts +127 -127
  98. package/src/matchmaking/seeker.ts +86 -86
  99. package/src/matchmaking/topic-anchor.ts +90 -90
  100. package/src/matchmaking/voting-quorum.ts +394 -394
  101. package/src/network/i-peer-network.ts +25 -25
  102. package/src/network/repo-protocol.ts +13 -13
  103. package/src/network/types.ts +37 -37
  104. package/src/reactivity/backfill.ts +220 -220
  105. package/src/reactivity/backpressure.ts +191 -191
  106. package/src/reactivity/checkpoint.ts +308 -308
  107. package/src/reactivity/config.ts +172 -172
  108. package/src/reactivity/dedupe.ts +132 -132
  109. package/src/reactivity/forwarder.ts +87 -87
  110. package/src/reactivity/index.ts +34 -34
  111. package/src/reactivity/notification.ts +123 -123
  112. package/src/reactivity/policy.ts +79 -79
  113. package/src/reactivity/push-state.ts +310 -310
  114. package/src/reactivity/recover.ts +153 -153
  115. package/src/reactivity/replay-buffer.ts +141 -141
  116. package/src/reactivity/resume.ts +549 -549
  117. package/src/reactivity/rotation.ts +415 -415
  118. package/src/reactivity/subscriber.ts +132 -132
  119. package/src/reactivity/subscription.ts +66 -66
  120. package/src/reactivity/topic-anchor.ts +71 -71
  121. package/src/reactivity/verify.ts +73 -73
  122. package/src/reactivity/wire-validate.ts +13 -13
  123. package/src/testing/async-wait.ts +65 -65
  124. package/src/testing/index.ts +2 -2
  125. package/src/testing/test-transactor.ts +62 -0
  126. package/src/transaction/actions-engine.ts +68 -68
  127. package/src/transaction/coordinator.ts +28 -11
  128. package/src/transaction/index.ts +52 -52
  129. package/src/transaction/operations-hash.ts +196 -196
  130. package/src/transaction/read-dependency-collector.ts +78 -78
  131. package/src/transaction/session.ts +238 -238
  132. package/src/transaction/transaction.ts +442 -442
  133. package/src/transaction/validator.ts +197 -197
  134. package/src/transactor/block-floors.ts +126 -126
  135. package/src/transactor/index.ts +6 -6
  136. package/src/transactor/network-transactor.ts +1545 -1545
  137. package/src/transform/atomic-proxy.ts +92 -92
  138. package/src/transform/cache-source.ts +370 -370
  139. package/src/transform/helpers.ts +164 -164
  140. package/src/transform/index.ts +7 -7
  141. package/src/transform/struct.ts +21 -21
  142. package/src/utility/actor.ts +62 -62
  143. package/src/utility/backoff.ts +95 -95
  144. package/src/utility/batch-coordinator.ts +191 -191
  145. package/src/utility/ensured.ts +32 -32
  146. package/src/utility/groupby.ts +18 -18
  147. package/src/utility/hash-string.ts +14 -14
  148. package/src/utility/is-record-empty.ts +5 -5
  149. package/src/utility/latches.ts +42 -42
  150. package/src/utility/lru-map.ts +60 -60
  151. package/src/utility/nameof.ts +7 -7
  152. package/src/utility/pending.ts +43 -43
@@ -1,52 +1,52 @@
1
- export type {
2
- Transaction,
3
- TransactionStamp,
4
- StampFields,
5
- ReadDependency,
6
- TransactionRef,
7
- ITransactionEngine,
8
- ExecutionResult,
9
- CollectionActions,
10
- ValidationResult,
11
- ITransactionValidator,
12
- ActionsStatement,
13
- TransactionSigner,
14
- ClientSignatureVerifier
15
- } from './transaction.js';
16
-
17
- export {
18
- createTransactionStamp,
19
- computeStampId,
20
- createTransactionId,
21
- createActionsStatements,
22
- DEFAULT_TRANSACTION_TTL_MS,
23
- isTransactionExpired,
24
- clientSignaturePayload,
25
- CLIENT_SIG_VERSION,
26
- MaxPriority,
27
- clampPriority
28
- } from './transaction.js';
29
-
30
- export {
31
- ActionsEngine,
32
- ACTIONS_ENGINE_ID,
33
- } from './actions-engine.js';
34
-
35
- export { ReadDependencyCollector } from './read-dependency-collector.js';
36
- export { TransactionCoordinator } from './coordinator.js';
37
- export type { CoordinatorOptions, PendValidationMode } from './coordinator.js';
38
- export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from './errors.js';
39
- export { TransactionSession } from './session.js';
40
- export { TransactionValidator } from './validator.js';
41
- export type { EngineRegistration, ValidationCoordinatorFactory, BlockStateProvider } from './validator.js';
42
-
43
- export {
44
- collectOperations,
45
- hashOperations,
46
- canonicalStringify,
47
- canonicalOperationsPayload,
48
- opsHashVersion,
49
- OPS_HASH_VERSION,
50
- OPS_HASH_PREFIX,
51
- } from './operations-hash.js';
52
- export type { Operation } from './operations-hash.js';
1
+ export type {
2
+ Transaction,
3
+ TransactionStamp,
4
+ StampFields,
5
+ ReadDependency,
6
+ TransactionRef,
7
+ ITransactionEngine,
8
+ ExecutionResult,
9
+ CollectionActions,
10
+ ValidationResult,
11
+ ITransactionValidator,
12
+ ActionsStatement,
13
+ TransactionSigner,
14
+ ClientSignatureVerifier
15
+ } from './transaction.js';
16
+
17
+ export {
18
+ createTransactionStamp,
19
+ computeStampId,
20
+ createTransactionId,
21
+ createActionsStatements,
22
+ DEFAULT_TRANSACTION_TTL_MS,
23
+ isTransactionExpired,
24
+ clientSignaturePayload,
25
+ CLIENT_SIG_VERSION,
26
+ MaxPriority,
27
+ clampPriority
28
+ } from './transaction.js';
29
+
30
+ export {
31
+ ActionsEngine,
32
+ ACTIONS_ENGINE_ID,
33
+ } from './actions-engine.js';
34
+
35
+ export { ReadDependencyCollector } from './read-dependency-collector.js';
36
+ export { TransactionCoordinator } from './coordinator.js';
37
+ export type { CoordinatorOptions, PendValidationMode } from './coordinator.js';
38
+ export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from './errors.js';
39
+ export { TransactionSession } from './session.js';
40
+ export { TransactionValidator } from './validator.js';
41
+ export type { EngineRegistration, ValidationCoordinatorFactory, BlockStateProvider } from './validator.js';
42
+
43
+ export {
44
+ collectOperations,
45
+ hashOperations,
46
+ canonicalStringify,
47
+ canonicalOperationsPayload,
48
+ opsHashVersion,
49
+ OPS_HASH_VERSION,
50
+ OPS_HASH_PREFIX,
51
+ } from './operations-hash.js';
52
+ export type { Operation } from './operations-hash.js';
@@ -1,196 +1,196 @@
1
- import type { BlockId, IBlock, BlockOperations } from '../blocks/structs.js';
2
- import type { CollectionId } from '../collection/struct.js';
3
- import type { Transforms } from '../transform/struct.js';
4
- import { hashString } from '../utility/hash-string.js';
5
-
6
- /**
7
- * Represents an operation on a block within a collection.
8
- *
9
- * This is the SINGLE source of truth for the operation shape used by the
10
- * transaction "operations hash" — the fingerprint a coordinator sends and a
11
- * validator recomputes. Both {@link TransactionCoordinator} and
12
- * {@link TransactionValidator} import this type; it must never be duplicated,
13
- * because the two sides disagreeing is exactly the bug this module prevents.
14
- */
15
- export type Operation =
16
- | { readonly type: 'insert'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly block: IBlock }
17
- | { readonly type: 'update'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly operations: BlockOperations }
18
- | { readonly type: 'delete'; readonly collectionId: CollectionId; readonly blockId: BlockId };
19
-
20
- /**
21
- * Rank of each operation type, used ONLY as the final tiebreaker when the same
22
- * (collectionId, blockId) legitimately carries more than one operation — a block
23
- * staged, then mutated, then deleted within one transform (Transforms apply order
24
- * is insert → update → delete; see transform/struct.ts). This is the semantic
25
- * apply order. The exact ranking is arbitrary for correctness (both sides use it),
26
- * but it MUST be defined in exactly one place — here.
27
- */
28
- const TYPE_RANK: Record<Operation['type'], number> = {
29
- insert: 0,
30
- update: 1,
31
- delete: 2,
32
- };
33
-
34
- /**
35
- * Collect every block operation across all collections into a flat list.
36
- *
37
- * The returned order reflects Map/object insertion order and is therefore NOT
38
- * canonical — {@link hashOperations} sorts before hashing, so callers do not need
39
- * to pre-sort. Shared by the coordinator (both commit() and execute()) and the
40
- * validator so all three collect sites produce the identical logical set.
41
- */
42
- export function collectOperations(transforms: Map<CollectionId, Transforms>): Operation[] {
43
- const operations: Operation[] = [];
44
- for (const [collectionId, t] of transforms) {
45
- for (const [blockId, block] of Object.entries(t.inserts ?? {})) {
46
- operations.push({ type: 'insert', collectionId, blockId, block });
47
- }
48
- for (const [blockId, ops] of Object.entries(t.updates ?? {})) {
49
- operations.push({ type: 'update', collectionId, blockId, operations: ops });
50
- }
51
- for (const blockId of t.deletes ?? []) {
52
- operations.push({ type: 'delete', collectionId, blockId });
53
- }
54
- }
55
- return operations;
56
- }
57
-
58
- /**
59
- * Total order over operations by the tuple (collectionId, blockId, type), using
60
- * plain string comparison on the first two components and {@link TYPE_RANK} on the
61
- * third. This is the cross-node ordering contract: two honest nodes that see the
62
- * same logical set MUST produce the same sorted sequence regardless of the order
63
- * they happened to collect operations in.
64
- */
65
- function compareOperations(a: Operation, b: Operation): number {
66
- if (a.collectionId !== b.collectionId) return a.collectionId < b.collectionId ? -1 : 1;
67
- if (a.blockId !== b.blockId) return a.blockId < b.blockId ? -1 : 1;
68
- return TYPE_RANK[a.type] - TYPE_RANK[b.type];
69
- }
70
-
71
- /**
72
- * Canonical JSON encoder: recursively sorts object keys but PRESERVES array element
73
- * order, and matches JSON.stringify leaf semantics.
74
- *
75
- * - Object keys are emitted in ascending (sorted) order, so two objects with the
76
- * same content but different key-insertion order encode identically.
77
- * - Array element order is preserved because BlockOperations is an ordered list of
78
- * [entity, index, deleteCount, inserted] tuples whose order is semantically
79
- * meaningful (as are any data arrays nested inside an IBlock).
80
- * - Leaf semantics mirror JSON.stringify: `undefined`/function/symbol object-values
81
- * are dropped, the same in arrays encode as `null`, `null` encodes as `null`,
82
- * non-finite numbers as `null`, and other primitives via JSON.stringify.
83
- *
84
- * Exported so the order-independence test can exercise it directly.
85
- *
86
- * NOTE: no toJSON/Date special-casing — a value carrying toJSON (e.g. a Date)
87
- * encodes as its plain enumerable keys ({} for a Date), not JSON.stringify's
88
- * toJSON string. Harmless today (blocks hold plain JSON) and still deterministic
89
- * across nodes (both sides run this same encoder); if IBlock content ever grows
90
- * toJSON-bearing values and matching JSON.stringify exactly matters, add the hook.
91
- */
92
- export function canonicalStringify(value: unknown): string {
93
- if (value === null) return 'null';
94
-
95
- const type = typeof value;
96
- if (type === 'number') return Number.isFinite(value) ? JSON.stringify(value) : 'null';
97
- if (type === 'string' || type === 'boolean') return JSON.stringify(value);
98
- if (type === 'bigint') throw new TypeError('Do not know how to serialize a BigInt');
99
- if (type === 'undefined' || type === 'function' || type === 'symbol') return 'null';
100
-
101
- if (Array.isArray(value)) {
102
- const items = value.map(element => {
103
- const et = typeof element;
104
- // In arrays, undefined/function/symbol serialize as null (JSON.stringify semantics).
105
- if (element === undefined || et === 'function' || et === 'symbol') return 'null';
106
- return canonicalStringify(element);
107
- });
108
- return `[${items.join(',')}]`;
109
- }
110
-
111
- // Plain object: sort keys ascending, drop undefined/function/symbol values.
112
- const obj = value as Record<string, unknown>;
113
- const parts: string[] = [];
114
- for (const key of Object.keys(obj).sort()) {
115
- const v = obj[key];
116
- const vt = typeof v;
117
- if (v === undefined || vt === 'function' || vt === 'symbol') continue;
118
- parts.push(`${JSON.stringify(key)}:${canonicalStringify(v)}`);
119
- }
120
- return `{${parts.join(',')}}`;
121
- }
122
-
123
- /**
124
- * Current operations-hash FORMAT VERSION. Versions the *serialization* of operations
125
- * into bytes (the sort key, {@link canonicalStringify} rules, and the SHA-256/base64url
126
- * step) — distinct from `engineId` in the TransactionStamp, which versions the operation
127
- * *content* an engine produces from the same statements. Two honest nodes must agree on
128
- * BOTH dimensions to produce the same ops-hash.
129
- *
130
- * Bump this whenever a change to the canonical serialization alters the emitted bytes,
131
- * so a peer running the old format is *detected* (a legible version-skew error) rather
132
- * than mistaken for a content disagreement or a Byzantine lie. See docs/transactions.md
133
- * ("Operations Hash — Canonical Serialization").
134
- */
135
- export const OPS_HASH_VERSION = 'v1';
136
-
137
- /**
138
- * Wire-token prefix carrying {@link OPS_HASH_VERSION}: `ops.v1:`. The `.` delimiter is
139
- * outside the base64url alphabet (A–Z a–z 0–9 `-` `_`) that follows the trailing `:`, so
140
- * the version segment can always be sliced back out unambiguously — see {@link opsHashVersion}.
141
- */
142
- export const OPS_HASH_PREFIX = `ops.${OPS_HASH_VERSION}:`;
143
-
144
- /**
145
- * Extract the format-version segment from an ops-hash token — the `v1` in `ops.v1:<hash>` —
146
- * or `null` if the string is not a recognizable versioned ops-hash token.
147
- *
148
- * Total: never throws. A bare legacy `ops:<hash>` token (no `.` delimiter), an empty
149
- * string, or any garbage all return `null`. A validator treats a `null` (or a version it
150
- * does not recognize) as an unsupported/foreign format — a legible version-skew error —
151
- * never as an accidental content match.
152
- */
153
- export function opsHashVersion(token: string): string | null {
154
- if (typeof token !== 'string') return null;
155
- if (!token.startsWith('ops.')) return null;
156
- const colon = token.indexOf(':', 4);
157
- if (colon <= 4) return null; // no version characters between "ops." and ":"
158
- return token.slice(4, colon);
159
- }
160
-
161
- /**
162
- * The EXACT canonical byte-string {@link hashOperations} feeds into SHA-256: the operations
163
- * sorted by {@link compareOperations} and run through {@link canonicalStringify}. The version
164
- * token is NOT part of this preimage — it wraps the resulting hash, it is not hashed.
165
- *
166
- * Exposed so a future client signature (design-client-transaction-signatures) can bind the
167
- * IDENTICAL bytes the validators hash, rather than re-deriving the serialization and risking
168
- * drift. Pair it with {@link OPS_HASH_VERSION} to record which format the bytes belong to.
169
- */
170
- export function canonicalOperationsPayload(operations: readonly Operation[]): string {
171
- return canonicalStringify([...operations].sort(compareOperations));
172
- }
173
-
174
- /**
175
- * Compute the transaction operations hash: sort into canonical order, canonically
176
- * stringify, SHA-256 (base64url) via {@link hashString}, then prefix the versioned
177
- * {@link OPS_HASH_PREFIX} token (`ops.v1:`) so the wire string is self-describing.
178
- *
179
- * This is the fingerprint the coordinator sends in PendRequest.validation.operationsHash and
180
- * the validator recomputes; equality of this string is the cross-node agreement
181
- * that a transaction's operations match.
182
- *
183
- * NOTE: the ops-hash carries a format-version token, so a mixed-version cluster now
184
- * *detects* skew — a validator seeing a foreign/legacy version emits a distinct
185
- * "unsupported operations-hash format version" error instead of the ambiguous
186
- * "Operations hash mismatch" (see TransactionValidator). What it does NOT do is
187
- * *cross-compute* older formats: a node only recognizes that a peer speaks a different
188
- * version, it cannot reproduce that peer's historical bytes. Mixed-version clusters
189
- * therefore fail LEGIBLY, not interoperably; multi-version compatibility is future
190
- * work if rolling upgrades ship. The ops-hash is recomputed fresh on both sides and
191
- * never persisted, so bumping the version cannot retroactively invalidate committed
192
- * transactions (unlike transaction.id, which IS persisted — leave it untouched).
193
- */
194
- export async function hashOperations(operations: readonly Operation[]): Promise<string> {
195
- return `${OPS_HASH_PREFIX}${await hashString(canonicalOperationsPayload(operations))}`;
196
- }
1
+ import type { BlockId, IBlock, BlockOperations } from '../blocks/structs.js';
2
+ import type { CollectionId } from '../collection/struct.js';
3
+ import type { Transforms } from '../transform/struct.js';
4
+ import { hashString } from '../utility/hash-string.js';
5
+
6
+ /**
7
+ * Represents an operation on a block within a collection.
8
+ *
9
+ * This is the SINGLE source of truth for the operation shape used by the
10
+ * transaction "operations hash" — the fingerprint a coordinator sends and a
11
+ * validator recomputes. Both {@link TransactionCoordinator} and
12
+ * {@link TransactionValidator} import this type; it must never be duplicated,
13
+ * because the two sides disagreeing is exactly the bug this module prevents.
14
+ */
15
+ export type Operation =
16
+ | { readonly type: 'insert'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly block: IBlock }
17
+ | { readonly type: 'update'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly operations: BlockOperations }
18
+ | { readonly type: 'delete'; readonly collectionId: CollectionId; readonly blockId: BlockId };
19
+
20
+ /**
21
+ * Rank of each operation type, used ONLY as the final tiebreaker when the same
22
+ * (collectionId, blockId) legitimately carries more than one operation — a block
23
+ * staged, then mutated, then deleted within one transform (Transforms apply order
24
+ * is insert → update → delete; see transform/struct.ts). This is the semantic
25
+ * apply order. The exact ranking is arbitrary for correctness (both sides use it),
26
+ * but it MUST be defined in exactly one place — here.
27
+ */
28
+ const TYPE_RANK: Record<Operation['type'], number> = {
29
+ insert: 0,
30
+ update: 1,
31
+ delete: 2,
32
+ };
33
+
34
+ /**
35
+ * Collect every block operation across all collections into a flat list.
36
+ *
37
+ * The returned order reflects Map/object insertion order and is therefore NOT
38
+ * canonical — {@link hashOperations} sorts before hashing, so callers do not need
39
+ * to pre-sort. Shared by the coordinator (both commit() and execute()) and the
40
+ * validator so all three collect sites produce the identical logical set.
41
+ */
42
+ export function collectOperations(transforms: Map<CollectionId, Transforms>): Operation[] {
43
+ const operations: Operation[] = [];
44
+ for (const [collectionId, t] of transforms) {
45
+ for (const [blockId, block] of Object.entries(t.inserts ?? {})) {
46
+ operations.push({ type: 'insert', collectionId, blockId, block });
47
+ }
48
+ for (const [blockId, ops] of Object.entries(t.updates ?? {})) {
49
+ operations.push({ type: 'update', collectionId, blockId, operations: ops });
50
+ }
51
+ for (const blockId of t.deletes ?? []) {
52
+ operations.push({ type: 'delete', collectionId, blockId });
53
+ }
54
+ }
55
+ return operations;
56
+ }
57
+
58
+ /**
59
+ * Total order over operations by the tuple (collectionId, blockId, type), using
60
+ * plain string comparison on the first two components and {@link TYPE_RANK} on the
61
+ * third. This is the cross-node ordering contract: two honest nodes that see the
62
+ * same logical set MUST produce the same sorted sequence regardless of the order
63
+ * they happened to collect operations in.
64
+ */
65
+ function compareOperations(a: Operation, b: Operation): number {
66
+ if (a.collectionId !== b.collectionId) return a.collectionId < b.collectionId ? -1 : 1;
67
+ if (a.blockId !== b.blockId) return a.blockId < b.blockId ? -1 : 1;
68
+ return TYPE_RANK[a.type] - TYPE_RANK[b.type];
69
+ }
70
+
71
+ /**
72
+ * Canonical JSON encoder: recursively sorts object keys but PRESERVES array element
73
+ * order, and matches JSON.stringify leaf semantics.
74
+ *
75
+ * - Object keys are emitted in ascending (sorted) order, so two objects with the
76
+ * same content but different key-insertion order encode identically.
77
+ * - Array element order is preserved because BlockOperations is an ordered list of
78
+ * [entity, index, deleteCount, inserted] tuples whose order is semantically
79
+ * meaningful (as are any data arrays nested inside an IBlock).
80
+ * - Leaf semantics mirror JSON.stringify: `undefined`/function/symbol object-values
81
+ * are dropped, the same in arrays encode as `null`, `null` encodes as `null`,
82
+ * non-finite numbers as `null`, and other primitives via JSON.stringify.
83
+ *
84
+ * Exported so the order-independence test can exercise it directly.
85
+ *
86
+ * NOTE: no toJSON/Date special-casing — a value carrying toJSON (e.g. a Date)
87
+ * encodes as its plain enumerable keys ({} for a Date), not JSON.stringify's
88
+ * toJSON string. Harmless today (blocks hold plain JSON) and still deterministic
89
+ * across nodes (both sides run this same encoder); if IBlock content ever grows
90
+ * toJSON-bearing values and matching JSON.stringify exactly matters, add the hook.
91
+ */
92
+ export function canonicalStringify(value: unknown): string {
93
+ if (value === null) return 'null';
94
+
95
+ const type = typeof value;
96
+ if (type === 'number') return Number.isFinite(value) ? JSON.stringify(value) : 'null';
97
+ if (type === 'string' || type === 'boolean') return JSON.stringify(value);
98
+ if (type === 'bigint') throw new TypeError('Do not know how to serialize a BigInt');
99
+ if (type === 'undefined' || type === 'function' || type === 'symbol') return 'null';
100
+
101
+ if (Array.isArray(value)) {
102
+ const items = value.map(element => {
103
+ const et = typeof element;
104
+ // In arrays, undefined/function/symbol serialize as null (JSON.stringify semantics).
105
+ if (element === undefined || et === 'function' || et === 'symbol') return 'null';
106
+ return canonicalStringify(element);
107
+ });
108
+ return `[${items.join(',')}]`;
109
+ }
110
+
111
+ // Plain object: sort keys ascending, drop undefined/function/symbol values.
112
+ const obj = value as Record<string, unknown>;
113
+ const parts: string[] = [];
114
+ for (const key of Object.keys(obj).sort()) {
115
+ const v = obj[key];
116
+ const vt = typeof v;
117
+ if (v === undefined || vt === 'function' || vt === 'symbol') continue;
118
+ parts.push(`${JSON.stringify(key)}:${canonicalStringify(v)}`);
119
+ }
120
+ return `{${parts.join(',')}}`;
121
+ }
122
+
123
+ /**
124
+ * Current operations-hash FORMAT VERSION. Versions the *serialization* of operations
125
+ * into bytes (the sort key, {@link canonicalStringify} rules, and the SHA-256/base64url
126
+ * step) — distinct from `engineId` in the TransactionStamp, which versions the operation
127
+ * *content* an engine produces from the same statements. Two honest nodes must agree on
128
+ * BOTH dimensions to produce the same ops-hash.
129
+ *
130
+ * Bump this whenever a change to the canonical serialization alters the emitted bytes,
131
+ * so a peer running the old format is *detected* (a legible version-skew error) rather
132
+ * than mistaken for a content disagreement or a Byzantine lie. See docs/transactions.md
133
+ * ("Operations Hash — Canonical Serialization").
134
+ */
135
+ export const OPS_HASH_VERSION = 'v1';
136
+
137
+ /**
138
+ * Wire-token prefix carrying {@link OPS_HASH_VERSION}: `ops.v1:`. The `.` delimiter is
139
+ * outside the base64url alphabet (A–Z a–z 0–9 `-` `_`) that follows the trailing `:`, so
140
+ * the version segment can always be sliced back out unambiguously — see {@link opsHashVersion}.
141
+ */
142
+ export const OPS_HASH_PREFIX = `ops.${OPS_HASH_VERSION}:`;
143
+
144
+ /**
145
+ * Extract the format-version segment from an ops-hash token — the `v1` in `ops.v1:<hash>` —
146
+ * or `null` if the string is not a recognizable versioned ops-hash token.
147
+ *
148
+ * Total: never throws. A bare legacy `ops:<hash>` token (no `.` delimiter), an empty
149
+ * string, or any garbage all return `null`. A validator treats a `null` (or a version it
150
+ * does not recognize) as an unsupported/foreign format — a legible version-skew error —
151
+ * never as an accidental content match.
152
+ */
153
+ export function opsHashVersion(token: string): string | null {
154
+ if (typeof token !== 'string') return null;
155
+ if (!token.startsWith('ops.')) return null;
156
+ const colon = token.indexOf(':', 4);
157
+ if (colon <= 4) return null; // no version characters between "ops." and ":"
158
+ return token.slice(4, colon);
159
+ }
160
+
161
+ /**
162
+ * The EXACT canonical byte-string {@link hashOperations} feeds into SHA-256: the operations
163
+ * sorted by {@link compareOperations} and run through {@link canonicalStringify}. The version
164
+ * token is NOT part of this preimage — it wraps the resulting hash, it is not hashed.
165
+ *
166
+ * Exposed so a future client signature (design-client-transaction-signatures) can bind the
167
+ * IDENTICAL bytes the validators hash, rather than re-deriving the serialization and risking
168
+ * drift. Pair it with {@link OPS_HASH_VERSION} to record which format the bytes belong to.
169
+ */
170
+ export function canonicalOperationsPayload(operations: readonly Operation[]): string {
171
+ return canonicalStringify([...operations].sort(compareOperations));
172
+ }
173
+
174
+ /**
175
+ * Compute the transaction operations hash: sort into canonical order, canonically
176
+ * stringify, SHA-256 (base64url) via {@link hashString}, then prefix the versioned
177
+ * {@link OPS_HASH_PREFIX} token (`ops.v1:`) so the wire string is self-describing.
178
+ *
179
+ * This is the fingerprint the coordinator sends in PendRequest.validation.operationsHash and
180
+ * the validator recomputes; equality of this string is the cross-node agreement
181
+ * that a transaction's operations match.
182
+ *
183
+ * NOTE: the ops-hash carries a format-version token, so a mixed-version cluster now
184
+ * *detects* skew — a validator seeing a foreign/legacy version emits a distinct
185
+ * "unsupported operations-hash format version" error instead of the ambiguous
186
+ * "Operations hash mismatch" (see TransactionValidator). What it does NOT do is
187
+ * *cross-compute* older formats: a node only recognizes that a peer speaks a different
188
+ * version, it cannot reproduce that peer's historical bytes. Mixed-version clusters
189
+ * therefore fail LEGIBLY, not interoperably; multi-version compatibility is future
190
+ * work if rolling upgrades ship. The ops-hash is recomputed fresh on both sides and
191
+ * never persisted, so bumping the version cannot retroactively invalidate committed
192
+ * transactions (unlike transaction.id, which IS persisted — leave it untouched).
193
+ */
194
+ export async function hashOperations(operations: readonly Operation[]): Promise<string> {
195
+ return `${OPS_HASH_PREFIX}${await hashString(canonicalOperationsPayload(operations))}`;
196
+ }