@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,197 +1,197 @@
1
- import type { BlockId, CollectionId, Transforms } from '../index.js';
2
- import type { Transaction, ITransactionEngine, ITransactionValidator, ValidationResult, CollectionActions, ClientSignatureVerifier } from './transaction.js';
3
- import type { BlockActionState } from '../network/struct.js';
4
- import { isTransactionExpired, clientSignaturePayload, computeStampId } from './transaction.js';
5
- import { collectOperations, hashOperations, opsHashVersion, OPS_HASH_VERSION } from './operations-hash.js';
6
-
7
- /**
8
- * Engine registration for validation.
9
- */
10
- export type EngineRegistration = {
11
- /** The transaction engine instance */
12
- engine: ITransactionEngine;
13
- /** Get the current schema hash for this engine */
14
- getSchemaHash: () => Promise<string>;
15
- };
16
-
17
- /**
18
- * Factory function to create a validation coordinator.
19
- * This allows isolated execution of transactions for validation.
20
- */
21
- export type ValidationCoordinatorFactory = () => {
22
- /** Apply actions to collections in isolated state */
23
- applyActions(actions: CollectionActions[], stampId: string): Promise<void>;
24
- /** Get all transforms from the validation state */
25
- getTransforms(): Map<CollectionId, Transforms>;
26
- /** Dispose of the validation coordinator */
27
- dispose(): void;
28
- };
29
-
30
- /**
31
- * Provides current block state for read dependency validation.
32
- * Returns the latest BlockActionState for a given block, or undefined if the block doesn't exist.
33
- */
34
- export type BlockStateProvider = (blockId: BlockId) => Promise<BlockActionState | undefined>;
35
-
36
- /**
37
- * Transaction validator implementation.
38
- *
39
- * Validates transactions by re-executing them and comparing operations hash.
40
- * Used by cluster participants when receiving PendRequests.
41
- */
42
- export class TransactionValidator implements ITransactionValidator {
43
- constructor(
44
- private readonly engines: Map<string, EngineRegistration>,
45
- private readonly createValidationCoordinator: ValidationCoordinatorFactory,
46
- private readonly blockStateProvider?: BlockStateProvider,
47
- private readonly verifyClientSignature?: ClientSignatureVerifier
48
- ) {}
49
-
50
- async validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult> {
51
- const { stamp } = transaction;
52
-
53
- // 0.0. Integrity: the id must be the true hash of the stamp fields. Runs FIRST because
54
- // every later step (expiration, signature, engine/schema selection) trusts a stamp field.
55
- // Always-on (one SHA-256, cheap) and independent of whether a signature verifier is wired —
56
- // a tampered stamp corrupts expiration and engine selection regardless of signatures.
57
- const expectedId = await computeStampId(stamp);
58
- if (expectedId !== stamp.id) {
59
- return { valid: false, reason: 'Tampered transaction stamp' };
60
- }
61
-
62
- // 0. Check expiration before any other work. Ordered BEFORE the signature check so
63
- // an attacker cannot learn signature-validity for an already-expired transaction.
64
- if (isTransactionExpired(stamp)) {
65
- return {
66
- valid: false,
67
- reason: `Transaction expired at ${stamp.expiration}`
68
- };
69
- }
70
-
71
- // 0.5. Verify the client signature, if a verifier port is wired. When the port is
72
- // absent (migration / single-node-dev posture) unsigned AND signed transactions
73
- // both pass — the p2p enforcement flag decides whether to inject the port at all.
74
- if (this.verifyClientSignature) {
75
- if (transaction.signature === undefined) {
76
- return { valid: false, reason: 'Missing client signature' };
77
- }
78
- const payload = clientSignaturePayload(stamp.id, transaction.statements, transaction.reads);
79
- if (!this.verifyClientSignature(stamp.peerId, payload, transaction.signature)) {
80
- return { valid: false, reason: 'Invalid client signature' };
81
- }
82
- }
83
-
84
- // 1. Verify engine exists
85
- const registration = this.engines.get(stamp.engineId);
86
- if (!registration) {
87
- return {
88
- valid: false,
89
- reason: `Unknown engine: ${stamp.engineId}`
90
- };
91
- }
92
-
93
- // 2. Verify schema hash matches
94
- const localSchemaHash = await registration.getSchemaHash();
95
- if (localSchemaHash !== stamp.schemaHash) {
96
- return {
97
- valid: false,
98
- reason: `Schema mismatch: local=${localSchemaHash}, sender=${stamp.schemaHash}`
99
- };
100
- }
101
-
102
- // 3. Verify read dependencies (optimistic concurrency)
103
- if (this.blockStateProvider && transaction.reads.length > 0) {
104
- for (const read of transaction.reads) {
105
- const currentState = await this.blockStateProvider(read.blockId);
106
- const currentRev = currentState?.latest?.rev ?? 0;
107
- if (currentRev !== read.revision) {
108
- return {
109
- valid: false,
110
- reason: `Stale read: block ${read.blockId} was at revision ${read.revision} but is now at ${currentRev}`
111
- };
112
- }
113
- }
114
- }
115
-
116
- // 4. Create isolated validation coordinator
117
- const validationCoordinator = this.createValidationCoordinator();
118
-
119
- try {
120
- // 5. Re-execute transaction through engine.
121
- //
122
- // Which of the two ITransactionEngine models the registered engine uses decides
123
- // where isolation comes from (see the contract in transaction.ts):
124
- //
125
- // (a) PURE TRANSLATOR (ActionsEngine) — execute() parses statements into
126
- // actions and mutates NOTHING, so even an engine constructed against the
127
- // MAIN coordinator cannot leak into main state here. The returned actions
128
- // are applied once, on the isolated validationCoordinator at step 6.
129
- //
130
- // (b) SIDE-EFFECT APPLY (QuereusEngine) — execute() applies while translating
131
- // (db.exec drives the vtab into coordinator.applyActions) and returns EMPTY
132
- // actions. That application lands on whatever coordinator the engine/vtab is
133
- // bound to, NOT on validationCoordinator, so isolation is the caller's job:
134
- // the createValidationCoordinator wiring must bind/reset an isolated world
135
- // (see quereus-validator, which resets the coordinator before each run and
136
- // makes its validationCoordinator.applyActions a no-op). Step 6 is then
137
- // skipped by the empty-actions guard.
138
- const result = await registration.engine.execute(transaction);
139
- if (!result.success) {
140
- return {
141
- valid: false,
142
- reason: `Re-execution failed: ${result.error}`
143
- };
144
- }
145
-
146
- // 6. Apply actions to the isolated validation coordinator (builds transforms).
147
- // Reached only for pure-translator engines that RETURNED actions; a side-effect
148
- // engine returns empty and already applied during execute() (see above).
149
- if (result.actions && result.actions.length > 0) {
150
- await validationCoordinator.applyActions(result.actions, stamp.id);
151
- }
152
-
153
- // 7. Collect operations from validation coordinator
154
- const transforms = validationCoordinator.getTransforms();
155
-
156
- // 8. Compute hash via the shared operations-hash module — the SAME collect +
157
- // canonicalise + hash the coordinator ran, so an honest sender and this
158
- // validator cannot diverge on ordering.
159
- const computedHash = await hashOperations(collectOperations(transforms));
160
-
161
- // 9. Compare with sender's hash. Split the failure into two distinct causes so
162
- // version skew is diagnosable rather than looking like a content fault:
163
- // - VERSION SKEW: the sender's token carries a format version this node does not
164
- // produce (a foreign vN, a bare legacy `ops:`, or an unparseable token → null).
165
- // These bytes are not even comparable, so surface a clear "unsupported format
166
- // version" error. This is DETECTION only — the node cannot cross-compute the
167
- // peer's format, so a mixed-version cluster fails legibly, not silently.
168
- // - CONTENT MISMATCH: same format version, different bytes — a genuine operations
169
- // disagreement (or a Byzantine lie); the existing error is unchanged.
170
- if (computedHash !== operationsHash) {
171
- const senderVersion = opsHashVersion(operationsHash);
172
- if (senderVersion !== OPS_HASH_VERSION) {
173
- return {
174
- valid: false,
175
- reason: `Unsupported operations-hash format version: local=${OPS_HASH_VERSION}, sender=${senderVersion ?? 'unrecognized'}`,
176
- computedHash
177
- };
178
- }
179
- return {
180
- valid: false,
181
- reason: `Operations hash mismatch`,
182
- computedHash
183
- };
184
- }
185
-
186
- return { valid: true, computedHash };
187
- } finally {
188
- validationCoordinator.dispose();
189
- }
190
- }
191
-
192
- async getSchemaHash(engineId: string): Promise<string | undefined> {
193
- const registration = this.engines.get(engineId);
194
- return registration ? await registration.getSchemaHash() : undefined;
195
- }
196
- }
197
-
1
+ import type { BlockId, CollectionId, Transforms } from '../index.js';
2
+ import type { Transaction, ITransactionEngine, ITransactionValidator, ValidationResult, CollectionActions, ClientSignatureVerifier } from './transaction.js';
3
+ import type { BlockActionState } from '../network/struct.js';
4
+ import { isTransactionExpired, clientSignaturePayload, computeStampId } from './transaction.js';
5
+ import { collectOperations, hashOperations, opsHashVersion, OPS_HASH_VERSION } from './operations-hash.js';
6
+
7
+ /**
8
+ * Engine registration for validation.
9
+ */
10
+ export type EngineRegistration = {
11
+ /** The transaction engine instance */
12
+ engine: ITransactionEngine;
13
+ /** Get the current schema hash for this engine */
14
+ getSchemaHash: () => Promise<string>;
15
+ };
16
+
17
+ /**
18
+ * Factory function to create a validation coordinator.
19
+ * This allows isolated execution of transactions for validation.
20
+ */
21
+ export type ValidationCoordinatorFactory = () => {
22
+ /** Apply actions to collections in isolated state */
23
+ applyActions(actions: CollectionActions[], stampId: string): Promise<void>;
24
+ /** Get all transforms from the validation state */
25
+ getTransforms(): Map<CollectionId, Transforms>;
26
+ /** Dispose of the validation coordinator */
27
+ dispose(): void;
28
+ };
29
+
30
+ /**
31
+ * Provides current block state for read dependency validation.
32
+ * Returns the latest BlockActionState for a given block, or undefined if the block doesn't exist.
33
+ */
34
+ export type BlockStateProvider = (blockId: BlockId) => Promise<BlockActionState | undefined>;
35
+
36
+ /**
37
+ * Transaction validator implementation.
38
+ *
39
+ * Validates transactions by re-executing them and comparing operations hash.
40
+ * Used by cluster participants when receiving PendRequests.
41
+ */
42
+ export class TransactionValidator implements ITransactionValidator {
43
+ constructor(
44
+ private readonly engines: Map<string, EngineRegistration>,
45
+ private readonly createValidationCoordinator: ValidationCoordinatorFactory,
46
+ private readonly blockStateProvider?: BlockStateProvider,
47
+ private readonly verifyClientSignature?: ClientSignatureVerifier
48
+ ) {}
49
+
50
+ async validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult> {
51
+ const { stamp } = transaction;
52
+
53
+ // 0.0. Integrity: the id must be the true hash of the stamp fields. Runs FIRST because
54
+ // every later step (expiration, signature, engine/schema selection) trusts a stamp field.
55
+ // Always-on (one SHA-256, cheap) and independent of whether a signature verifier is wired —
56
+ // a tampered stamp corrupts expiration and engine selection regardless of signatures.
57
+ const expectedId = await computeStampId(stamp);
58
+ if (expectedId !== stamp.id) {
59
+ return { valid: false, reason: 'Tampered transaction stamp' };
60
+ }
61
+
62
+ // 0. Check expiration before any other work. Ordered BEFORE the signature check so
63
+ // an attacker cannot learn signature-validity for an already-expired transaction.
64
+ if (isTransactionExpired(stamp)) {
65
+ return {
66
+ valid: false,
67
+ reason: `Transaction expired at ${stamp.expiration}`
68
+ };
69
+ }
70
+
71
+ // 0.5. Verify the client signature, if a verifier port is wired. When the port is
72
+ // absent (migration / single-node-dev posture) unsigned AND signed transactions
73
+ // both pass — the p2p enforcement flag decides whether to inject the port at all.
74
+ if (this.verifyClientSignature) {
75
+ if (transaction.signature === undefined) {
76
+ return { valid: false, reason: 'Missing client signature' };
77
+ }
78
+ const payload = clientSignaturePayload(stamp.id, transaction.statements, transaction.reads);
79
+ if (!this.verifyClientSignature(stamp.peerId, payload, transaction.signature)) {
80
+ return { valid: false, reason: 'Invalid client signature' };
81
+ }
82
+ }
83
+
84
+ // 1. Verify engine exists
85
+ const registration = this.engines.get(stamp.engineId);
86
+ if (!registration) {
87
+ return {
88
+ valid: false,
89
+ reason: `Unknown engine: ${stamp.engineId}`
90
+ };
91
+ }
92
+
93
+ // 2. Verify schema hash matches
94
+ const localSchemaHash = await registration.getSchemaHash();
95
+ if (localSchemaHash !== stamp.schemaHash) {
96
+ return {
97
+ valid: false,
98
+ reason: `Schema mismatch: local=${localSchemaHash}, sender=${stamp.schemaHash}`
99
+ };
100
+ }
101
+
102
+ // 3. Verify read dependencies (optimistic concurrency)
103
+ if (this.blockStateProvider && transaction.reads.length > 0) {
104
+ for (const read of transaction.reads) {
105
+ const currentState = await this.blockStateProvider(read.blockId);
106
+ const currentRev = currentState?.latest?.rev ?? 0;
107
+ if (currentRev !== read.revision) {
108
+ return {
109
+ valid: false,
110
+ reason: `Stale read: block ${read.blockId} was at revision ${read.revision} but is now at ${currentRev}`
111
+ };
112
+ }
113
+ }
114
+ }
115
+
116
+ // 4. Create isolated validation coordinator
117
+ const validationCoordinator = this.createValidationCoordinator();
118
+
119
+ try {
120
+ // 5. Re-execute transaction through engine.
121
+ //
122
+ // Which of the two ITransactionEngine models the registered engine uses decides
123
+ // where isolation comes from (see the contract in transaction.ts):
124
+ //
125
+ // (a) PURE TRANSLATOR (ActionsEngine) — execute() parses statements into
126
+ // actions and mutates NOTHING, so even an engine constructed against the
127
+ // MAIN coordinator cannot leak into main state here. The returned actions
128
+ // are applied once, on the isolated validationCoordinator at step 6.
129
+ //
130
+ // (b) SIDE-EFFECT APPLY (QuereusEngine) — execute() applies while translating
131
+ // (db.exec drives the vtab into coordinator.applyActions) and returns EMPTY
132
+ // actions. That application lands on whatever coordinator the engine/vtab is
133
+ // bound to, NOT on validationCoordinator, so isolation is the caller's job:
134
+ // the createValidationCoordinator wiring must bind/reset an isolated world
135
+ // (see quereus-validator, which resets the coordinator before each run and
136
+ // makes its validationCoordinator.applyActions a no-op). Step 6 is then
137
+ // skipped by the empty-actions guard.
138
+ const result = await registration.engine.execute(transaction);
139
+ if (!result.success) {
140
+ return {
141
+ valid: false,
142
+ reason: `Re-execution failed: ${result.error}`
143
+ };
144
+ }
145
+
146
+ // 6. Apply actions to the isolated validation coordinator (builds transforms).
147
+ // Reached only for pure-translator engines that RETURNED actions; a side-effect
148
+ // engine returns empty and already applied during execute() (see above).
149
+ if (result.actions && result.actions.length > 0) {
150
+ await validationCoordinator.applyActions(result.actions, stamp.id);
151
+ }
152
+
153
+ // 7. Collect operations from validation coordinator
154
+ const transforms = validationCoordinator.getTransforms();
155
+
156
+ // 8. Compute hash via the shared operations-hash module — the SAME collect +
157
+ // canonicalise + hash the coordinator ran, so an honest sender and this
158
+ // validator cannot diverge on ordering.
159
+ const computedHash = await hashOperations(collectOperations(transforms));
160
+
161
+ // 9. Compare with sender's hash. Split the failure into two distinct causes so
162
+ // version skew is diagnosable rather than looking like a content fault:
163
+ // - VERSION SKEW: the sender's token carries a format version this node does not
164
+ // produce (a foreign vN, a bare legacy `ops:`, or an unparseable token → null).
165
+ // These bytes are not even comparable, so surface a clear "unsupported format
166
+ // version" error. This is DETECTION only — the node cannot cross-compute the
167
+ // peer's format, so a mixed-version cluster fails legibly, not silently.
168
+ // - CONTENT MISMATCH: same format version, different bytes — a genuine operations
169
+ // disagreement (or a Byzantine lie); the existing error is unchanged.
170
+ if (computedHash !== operationsHash) {
171
+ const senderVersion = opsHashVersion(operationsHash);
172
+ if (senderVersion !== OPS_HASH_VERSION) {
173
+ return {
174
+ valid: false,
175
+ reason: `Unsupported operations-hash format version: local=${OPS_HASH_VERSION}, sender=${senderVersion ?? 'unrecognized'}`,
176
+ computedHash
177
+ };
178
+ }
179
+ return {
180
+ valid: false,
181
+ reason: `Operations hash mismatch`,
182
+ computedHash
183
+ };
184
+ }
185
+
186
+ return { valid: true, computedHash };
187
+ } finally {
188
+ validationCoordinator.dispose();
189
+ }
190
+ }
191
+
192
+ async getSchemaHash(engineId: string): Promise<string | undefined> {
193
+ const registration = this.engines.get(engineId);
194
+ return registration ? await registration.getSchemaHash() : undefined;
195
+ }
196
+ }
197
+
@@ -1,126 +1,126 @@
1
- import type { ActionContext, ActionId, BlockId } from "../index.js";
2
-
3
- /** The lowest revision a block may be served at, and the action that set it.
4
- *
5
- * A refresh walks the log entries that landed since the collection last looked. Each entry says
6
- * "action `actionId`, committed at revision `rev`, changed these blocks", and every block an action
7
- * changes is committed at that action's revision. So once an entry has been walked, a read of a
8
- * block it names — made at a context at or above `rev` — must come back materialized at `rev` or
9
- * later; anything lower is provably not the view that was asked for. The FLOOR of a block is that
10
- * bound: the revision and action id of the newest walked entry naming it. */
11
- export type BlockFloor = {
12
- readonly rev: number;
13
- readonly actionId: ActionId;
14
- };
15
-
16
- /** A BELOW-FLOOR ANSWER: a block served at a revision under the floor that applied to the read. */
17
- export type BelowFloorAnswer = {
18
- blockId: BlockId;
19
- floor: BlockFloor;
20
- /** The revision the served content actually is (`servedRevision` of the answer). */
21
- servedRev: number;
22
- };
23
-
24
- /** What a read source needs from a collection's floors: which floor applies to a read, and whether
25
- * an answer fell under it. The narrow face of {@link BlockFloors} that `TransactorSource` holds. */
26
- export interface BlockFloorCheck {
27
- /** The floor a read of `blockId` at `context` must meet, or `undefined` when none applies.
28
- *
29
- * A floor applies only to a view that should CONTAIN the entry that set it: an unpinned read, or
30
- * one pinned at or above the floor's revision. A read pinned strictly below it legitimately asks
31
- * for an older view and is served — and remembered — exactly as if there were no floor. (The same
32
- * at-or-above test `answeredBlock` applies to `unconfirmedAheadRev`.) */
33
- applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined;
34
-
35
- /** Weighs a served block against the floor that applies to the read that fetched it.
36
- *
37
- * @param servedRev the revision the served content is — `servedRevision` of the answer.
38
- * @returns `true` for a below-floor answer, which the caller hands on but must not let any cache
39
- * remember (see `TransactorSource.describeServed`). */
40
- answeredBelowFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean;
41
-
42
- /** The same comparison {@link answeredBelowFloor} makes, without reporting it — for content that
43
- * is not an answer being served to a reader, where the `collection:block-below-floor` line would
44
- * misdescribe what happened. `Collection.keepWhatTheRefreshRead` weighs the header and log tail
45
- * its refresh read around `TransactorSource` this way.
46
- *
47
- * @param servedRev the revision the content is.
48
- * @returns `true` when no floor applies or the content meets the one that does. */
49
- meetsApplicableFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean;
50
- }
51
-
52
- /** The floors of one collection handle, shared by EVERY read source that handle builds — its own
53
- * and each pinned read view's — the way the `ReadDependencyCollector` is shared. Held on one
54
- * source only, a view created right after a refresh would fetch the changed block through a source
55
- * that knows no floor.
56
- *
57
- * Raised where log entries are consumed (`Collection.updateInternal`) and checked where answers
58
- * arrive (`TransactorSource.tryGet`). A floor, once raised, STANDS for the life of the handle: an
59
- * answer that meets it does not remove it.
60
- *
61
- * Why a met floor is not dropped. The source that judges an answer cannot know whether any cache
62
- * went on to keep it, and "an answer met the floor" is not "the cache now holds that answer": the
63
- * cache drops an answer that was overtaken while in flight (`CacheSource.stillWanted`), and evicts
64
- * kept content under pressure (128 blocks). Either way the next read of the block goes back to
65
- * storage, where nothing says the same machine answers twice — and with the floor gone, a too-old
66
- * answer to THAT read is judged against nothing and kept for good, which is the defect floors exist
67
- * to prevent. Reproduced with the floor dropped when met: a too-old answer, then a current one that
68
- * the cache dropped as overtaken (but which removed the floor), then a too-old one — kept, and
69
- * served after storage had caught up (`refresh-below-floor.spec.ts`, "a current answer the cache
70
- * dropped..."). A standing floor costs one map lookup per fetched block and is always true of a
71
- * correct answer: a block never goes back below a revision it was committed at.
72
- *
73
- * NOTE: the map is never pruned, so it holds one small entry per distinct block named by entries
74
- * this handle walked — the same ids, and so the same bound, as `CacheSource`'s never-pruned
75
- * `generations` map, which `clear(entry.blockIds)` populates beside every `raise`. If that ever
76
- * grows large enough to matter, prune the two together (oldest floors first); a dropped floor only
77
- * forfeits the check for that block, it never serves anything wrong by itself. */
78
- export class BlockFloors implements BlockFloorCheck {
79
- private readonly floors = new Map<BlockId, BlockFloor>();
80
-
81
- /** @param onBelowFloor told about every below-floor answer, from any source sharing these floors
82
- * — the collection reports them as `collection:block-below-floor`. */
83
- constructor(private readonly onBelowFloor?: (answer: BelowFloorAnswer) => void) {}
84
-
85
- /** Record that the walked entry `floor` describes changed `blockIds`. Highest revision wins, so
86
- * entries may be walked in any order and re-walked harmlessly. */
87
- raise(blockIds: readonly BlockId[], floor: BlockFloor): void {
88
- for (const blockId of blockIds) {
89
- const held = this.floors.get(blockId);
90
- if (held === undefined || floor.rev > held.rev) {
91
- this.floors.set(blockId, floor);
92
- }
93
- }
94
- }
95
-
96
- applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined {
97
- const floor = this.floors.get(blockId);
98
- return floor !== undefined && (context === undefined || context.rev >= floor.rev) ? floor : undefined;
99
- }
100
-
101
- answeredBelowFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean {
102
- const floor = this.unmetFloor(blockId, context, servedRev);
103
- if (floor === undefined) {
104
- return false;
105
- }
106
- this.onBelowFloor?.({ blockId, floor, servedRev });
107
- return true;
108
- }
109
-
110
- meetsApplicableFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean {
111
- return this.unmetFloor(blockId, context, servedRev) === undefined;
112
- }
113
-
114
- /** The applicable floor that `servedRev` FAILS, or undefined when it meets it (or none applies).
115
- * The one comparison behind both public checks, so a caller that only asks the question cannot
116
- * drift from the one that also reports the answer. */
117
- private unmetFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): BlockFloor | undefined {
118
- const floor = this.applicableTo(blockId, context);
119
- return floor !== undefined && servedRev < floor.rev ? floor : undefined;
120
- }
121
-
122
- /** How many blocks have a floor. */
123
- get size(): number {
124
- return this.floors.size;
125
- }
126
- }
1
+ import type { ActionContext, ActionId, BlockId } from "../index.js";
2
+
3
+ /** The lowest revision a block may be served at, and the action that set it.
4
+ *
5
+ * A refresh walks the log entries that landed since the collection last looked. Each entry says
6
+ * "action `actionId`, committed at revision `rev`, changed these blocks", and every block an action
7
+ * changes is committed at that action's revision. So once an entry has been walked, a read of a
8
+ * block it names — made at a context at or above `rev` — must come back materialized at `rev` or
9
+ * later; anything lower is provably not the view that was asked for. The FLOOR of a block is that
10
+ * bound: the revision and action id of the newest walked entry naming it. */
11
+ export type BlockFloor = {
12
+ readonly rev: number;
13
+ readonly actionId: ActionId;
14
+ };
15
+
16
+ /** A BELOW-FLOOR ANSWER: a block served at a revision under the floor that applied to the read. */
17
+ export type BelowFloorAnswer = {
18
+ blockId: BlockId;
19
+ floor: BlockFloor;
20
+ /** The revision the served content actually is (`servedRevision` of the answer). */
21
+ servedRev: number;
22
+ };
23
+
24
+ /** What a read source needs from a collection's floors: which floor applies to a read, and whether
25
+ * an answer fell under it. The narrow face of {@link BlockFloors} that `TransactorSource` holds. */
26
+ export interface BlockFloorCheck {
27
+ /** The floor a read of `blockId` at `context` must meet, or `undefined` when none applies.
28
+ *
29
+ * A floor applies only to a view that should CONTAIN the entry that set it: an unpinned read, or
30
+ * one pinned at or above the floor's revision. A read pinned strictly below it legitimately asks
31
+ * for an older view and is served — and remembered — exactly as if there were no floor. (The same
32
+ * at-or-above test `answeredBlock` applies to `unconfirmedAheadRev`.) */
33
+ applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined;
34
+
35
+ /** Weighs a served block against the floor that applies to the read that fetched it.
36
+ *
37
+ * @param servedRev the revision the served content is — `servedRevision` of the answer.
38
+ * @returns `true` for a below-floor answer, which the caller hands on but must not let any cache
39
+ * remember (see `TransactorSource.describeServed`). */
40
+ answeredBelowFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean;
41
+
42
+ /** The same comparison {@link answeredBelowFloor} makes, without reporting it — for content that
43
+ * is not an answer being served to a reader, where the `collection:block-below-floor` line would
44
+ * misdescribe what happened. `Collection.keepWhatTheRefreshRead` weighs the header and log tail
45
+ * its refresh read around `TransactorSource` this way.
46
+ *
47
+ * @param servedRev the revision the content is.
48
+ * @returns `true` when no floor applies or the content meets the one that does. */
49
+ meetsApplicableFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean;
50
+ }
51
+
52
+ /** The floors of one collection handle, shared by EVERY read source that handle builds — its own
53
+ * and each pinned read view's — the way the `ReadDependencyCollector` is shared. Held on one
54
+ * source only, a view created right after a refresh would fetch the changed block through a source
55
+ * that knows no floor.
56
+ *
57
+ * Raised where log entries are consumed (`Collection.updateInternal`) and checked where answers
58
+ * arrive (`TransactorSource.tryGet`). A floor, once raised, STANDS for the life of the handle: an
59
+ * answer that meets it does not remove it.
60
+ *
61
+ * Why a met floor is not dropped. The source that judges an answer cannot know whether any cache
62
+ * went on to keep it, and "an answer met the floor" is not "the cache now holds that answer": the
63
+ * cache drops an answer that was overtaken while in flight (`CacheSource.stillWanted`), and evicts
64
+ * kept content under pressure (128 blocks). Either way the next read of the block goes back to
65
+ * storage, where nothing says the same machine answers twice — and with the floor gone, a too-old
66
+ * answer to THAT read is judged against nothing and kept for good, which is the defect floors exist
67
+ * to prevent. Reproduced with the floor dropped when met: a too-old answer, then a current one that
68
+ * the cache dropped as overtaken (but which removed the floor), then a too-old one — kept, and
69
+ * served after storage had caught up (`refresh-below-floor.spec.ts`, "a current answer the cache
70
+ * dropped..."). A standing floor costs one map lookup per fetched block and is always true of a
71
+ * correct answer: a block never goes back below a revision it was committed at.
72
+ *
73
+ * NOTE: the map is never pruned, so it holds one small entry per distinct block named by entries
74
+ * this handle walked — the same ids, and so the same bound, as `CacheSource`'s never-pruned
75
+ * `generations` map, which `clear(entry.blockIds)` populates beside every `raise`. If that ever
76
+ * grows large enough to matter, prune the two together (oldest floors first); a dropped floor only
77
+ * forfeits the check for that block, it never serves anything wrong by itself. */
78
+ export class BlockFloors implements BlockFloorCheck {
79
+ private readonly floors = new Map<BlockId, BlockFloor>();
80
+
81
+ /** @param onBelowFloor told about every below-floor answer, from any source sharing these floors
82
+ * — the collection reports them as `collection:block-below-floor`. */
83
+ constructor(private readonly onBelowFloor?: (answer: BelowFloorAnswer) => void) {}
84
+
85
+ /** Record that the walked entry `floor` describes changed `blockIds`. Highest revision wins, so
86
+ * entries may be walked in any order and re-walked harmlessly. */
87
+ raise(blockIds: readonly BlockId[], floor: BlockFloor): void {
88
+ for (const blockId of blockIds) {
89
+ const held = this.floors.get(blockId);
90
+ if (held === undefined || floor.rev > held.rev) {
91
+ this.floors.set(blockId, floor);
92
+ }
93
+ }
94
+ }
95
+
96
+ applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined {
97
+ const floor = this.floors.get(blockId);
98
+ return floor !== undefined && (context === undefined || context.rev >= floor.rev) ? floor : undefined;
99
+ }
100
+
101
+ answeredBelowFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean {
102
+ const floor = this.unmetFloor(blockId, context, servedRev);
103
+ if (floor === undefined) {
104
+ return false;
105
+ }
106
+ this.onBelowFloor?.({ blockId, floor, servedRev });
107
+ return true;
108
+ }
109
+
110
+ meetsApplicableFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean {
111
+ return this.unmetFloor(blockId, context, servedRev) === undefined;
112
+ }
113
+
114
+ /** The applicable floor that `servedRev` FAILS, or undefined when it meets it (or none applies).
115
+ * The one comparison behind both public checks, so a caller that only asks the question cannot
116
+ * drift from the one that also reports the answer. */
117
+ private unmetFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): BlockFloor | undefined {
118
+ const floor = this.applicableTo(blockId, context);
119
+ return floor !== undefined && servedRev < floor.rev ? floor : undefined;
120
+ }
121
+
122
+ /** How many blocks have a floor. */
123
+ get size(): number {
124
+ return this.floors.size;
125
+ }
126
+ }