@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,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
+ }