@optimystic/db-core 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. package/README.md +336 -336
  2. package/dist/src/cluster/structs.d.ts +37 -0
  3. package/dist/src/cluster/structs.d.ts.map +1 -1
  4. package/dist/src/cluster/structs.js +13 -0
  5. package/dist/src/cluster/structs.js.map +1 -1
  6. package/dist/src/collection/collection.d.ts +44 -4
  7. package/dist/src/collection/collection.d.ts.map +1 -1
  8. package/dist/src/collection/collection.js +95 -14
  9. package/dist/src/collection/collection.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/cluster/structs.ts +38 -0
  41. package/src/cohort-topic/addressing.ts +120 -120
  42. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  43. package/src/cohort-topic/antidos/index.ts +5 -5
  44. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  45. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  46. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  47. package/src/cohort-topic/antiflood/index.ts +2 -2
  48. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  49. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  50. package/src/cohort-topic/coldstart.ts +237 -237
  51. package/src/cohort-topic/dmax.ts +88 -88
  52. package/src/cohort-topic/gossip/bus.ts +254 -254
  53. package/src/cohort-topic/gossip/index.ts +3 -3
  54. package/src/cohort-topic/gossip/records.ts +45 -45
  55. package/src/cohort-topic/gossip/view.ts +91 -91
  56. package/src/cohort-topic/index.ts +20 -20
  57. package/src/cohort-topic/load/barometer.ts +134 -134
  58. package/src/cohort-topic/load/index.ts +1 -1
  59. package/src/cohort-topic/member-engine.ts +430 -430
  60. package/src/cohort-topic/membership/index.ts +3 -3
  61. package/src/cohort-topic/membership/publisher.ts +163 -163
  62. package/src/cohort-topic/membership/source.ts +41 -41
  63. package/src/cohort-topic/ports.ts +157 -157
  64. package/src/cohort-topic/promotion.ts +477 -477
  65. package/src/cohort-topic/registration/bytes.ts +37 -37
  66. package/src/cohort-topic/registration/handoff.ts +154 -154
  67. package/src/cohort-topic/registration/index.ts +6 -6
  68. package/src/cohort-topic/registration/renewal.ts +495 -495
  69. package/src/cohort-topic/registration/sharding.ts +61 -61
  70. package/src/cohort-topic/registration/store.ts +81 -81
  71. package/src/cohort-topic/registration/types.ts +91 -91
  72. package/src/cohort-topic/ring-hash.ts +50 -50
  73. package/src/cohort-topic/service.ts +416 -416
  74. package/src/cohort-topic/sig/index.ts +2 -2
  75. package/src/cohort-topic/sig/payloads.ts +59 -59
  76. package/src/cohort-topic/sig/threshold.ts +64 -64
  77. package/src/cohort-topic/tiers.ts +74 -74
  78. package/src/cohort-topic/traffic.ts +233 -233
  79. package/src/cohort-topic/walk.ts +326 -326
  80. package/src/cohort-topic/willingness.ts +237 -237
  81. package/src/cohort-topic/wire/index.ts +18 -18
  82. package/src/cohort-topic/wire/payloads.ts +126 -126
  83. package/src/collection/action.ts +48 -48
  84. package/src/collection/collection-type-registry.ts +37 -37
  85. package/src/collection/collection.ts +2203 -2118
  86. package/src/collection/index.ts +4 -4
  87. package/src/collections/diary/index.ts +2 -2
  88. package/src/collections/diary/struct.ts +3 -3
  89. package/src/collections/index.ts +2 -2
  90. package/src/collections/tree/collection-trunk.ts +25 -25
  91. package/src/collections/tree/index.ts +2 -2
  92. package/src/collections/tree/readme.md +55 -55
  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
package/src/log/struct.ts CHANGED
@@ -1,165 +1,165 @@
1
- import type { BlockId, CollectionId, ActionContext, ActionId, ActionRev, ReadDependency } from "../index.js";
2
-
3
- /** A log entry - an action, a checkpoint, or an invalidation */
4
- export type LogEntry<TAction> = {
5
- /** Linux timestamp of the entry */
6
- readonly timestamp: number;
7
- /** Revision number - monotonically increasing from the prior entry's rev. Starts at 1. */
8
- readonly rev: number;
9
- readonly action?: ActionEntry<TAction>;
10
- readonly checkpoint?: CheckpointEntry;
11
- /** A compensating entry that reverses a previously-committed action proven invalid by dispute. */
12
- readonly invalidation?: InvalidationEntry;
13
- };
14
-
15
- /** An action entry represents a unit of work that is atomic */
16
- export type ActionEntry<TAction> = {
17
- /** Generated unique identifier for the action */
18
- readonly actionId: ActionId;
19
- /** Actions to be applied */
20
- readonly actions: TAction[];
21
- /** Block ids affected by the action - includes the log related blocks */
22
- blockIds: BlockId[]; // NOTE: this is updated after being generated to include the log-related block transforms
23
- /** Other collection ids affected by the action - this action is conditional on successful commit in all of these collections */
24
- readonly collectionIds?: CollectionId[];
25
- /**
26
- * The `(blockId, revision)` reads this transaction observed during execution — the same
27
- * read set the {@link Transaction} carried in its PEND request (see `Transaction.reads`).
28
- *
29
- * Persisted so a later invalidation cascade can discover this action's read-dependents:
30
- * a committed action is a read-dependent of an invalidated one iff its read set contains a
31
- * `(blockId, revision)` that the invalidated action produced.
32
- *
33
- * **Format / back-compat:** added by the invalidation-cascade work (ActionEntry v2). An entry
34
- * written before this field existed (or by a path that does not carry a `Transaction`, e.g. the
35
- * low-level `Collection.sync` direct-commit) has `reads === undefined` — treated by the cascade
36
- * as an *unknown dependency* (conservatively re-evaluated, never silently assumed independent).
37
- * `reads === []` is distinct: a transaction that genuinely read nothing.
38
- */
39
- readonly reads?: ReadDependency[];
40
- };
41
-
42
- /**
43
- * One arbitrator's signed verdict — the minimal subset of a dispute vote needed to re-verify
44
- * it independently. The Ed25519 public key that verifies {@link signature} is embedded in
45
- * {@link arbitratorPeerId} (a libp2p Ed25519 peer id).
46
- *
47
- * The signed payload is **target- and arbitrator-set-bound** (v3):
48
- * `utf8(`v3:${disputeId}:${vote}:${computedHash}:${targetHash}:${setHash}`)`, where
49
- * - `targetHash = hashString(`${messageHash}|${invalidatedActionId}|${sortedBlockIds.join(',')}`)`
50
- * commits the vote to the *specific* transaction being reversed (#2), and
51
- * - `setHash = hashString(sortedArbitratorSet.join(','))` commits it to the *legitimately-selected
52
- * arbitrator set* (#1) carried on {@link DisputeResolutionProof.arbitratorSet}.
53
- *
54
- * A verifier recomputes both digests from the proof plus the apply-path target, so a genuine vote can
55
- * neither be replayed against an unrelated transaction nor presented under a swapped cohort. v1/v2
56
- * (un-set-bound) votes are rejected, not accepted-by-default; the {@link version} marker is required.
57
- */
58
- export type ArbitrationVoteProof = {
59
- /** Wire-format version of the signed payload. Only `'v3'` is accepted; absent/unrecognized → rejected. */
60
- readonly version: 'v3';
61
- /** Peer id of the arbitrator; its embedded Ed25519 public key verifies {@link signature}. */
62
- readonly arbitratorPeerId: string;
63
- /** The arbitrator's verdict. */
64
- readonly vote: 'agree-with-challenger' | 'agree-with-majority' | 'inconclusive';
65
- /** The operations hash the arbitrator computed (part of the signed payload). */
66
- readonly computedHash: string;
67
- /** Base64url-encoded Ed25519 signature over `v3:${disputeId}:${vote}:${computedHash}:${targetHash}:${setHash}`. */
68
- readonly signature: string;
69
- };
70
-
71
- /**
72
- * The authoritative, independently-verifiable subset of a dispute resolution that proves a
73
- * committed transaction invalid. Carried inside an {@link InvalidationEntry}.
74
- *
75
- * Defined in db-core (the log layer) deliberately: the log must not import db-p2p, so the dispute
76
- * layer's richer `DisputeResolution` maps *onto* this proof rather than this proof importing it.
77
- * A member treats the proof as a reversal certificate — `outcome === 'challenger-wins'` with a
78
- * 2/3 super-majority of decisive votes agreeing with the challenger (each signature verifiable
79
- * against its arbitrator's embedded key, each vote target-bound, drawn from the legitimately-selected
80
- * {@link arbitratorSet}, and counted at most once per arbitrator).
81
- *
82
- * **Unforgeability.** Votes are bound to the reversed transaction (`targetHash`, #2), counted at most
83
- * once per arbitrator (#3), and bound to the legitimately-selected arbitrator set (#1):
84
- * {@link arbitratorSet} carries the K peer-ids the challenger selected, every counted vote must be a
85
- * member of it, and {@link arbitratorSetSignature} — the challenger's Ed25519 signature (verified
86
- * against {@link challengerPeerId}) over `(disputeId, target, arbitratorSet)` — binds the set to the
87
- * originator so a third-party relay cannot swap in its own sybils. A verifying member additionally
88
- * re-derives the eligible set from its own topology when it can (an injected recompute capability),
89
- * closing even a fully-malicious challenger; when it cannot (late-joiner / churned DHT view) it accepts
90
- * on the challenger-bound set + membership + dedup and *logs* the residual topology-anchoring gap rather
91
- * than silently accepting — a gap closed in full by the cohort-topic membership-cert trust-anchor chain
92
- * (`tickets/plan/cohort-topic-membership-cert-trust-anchoring.md`). Net: a compromised peer can withhold
93
- * an invalidation but cannot forge one.
94
- */
95
- export type DisputeResolutionProof = {
96
- /** Identifies the dispute these votes resolved. */
97
- readonly disputeId: string;
98
- /** messageHash of the original (now-invalid) committed transaction. */
99
- readonly messageHash: string;
100
- /** Resolution outcome; only `challenger-wins` authorizes an invalidation. */
101
- readonly outcome: 'challenger-wins' | 'majority-wins' | 'inconclusive';
102
- /**
103
- * Peer-id of the challenger (dissent coordinator) that selected the arbitrator set and produced
104
- * {@link arbitratorSetSignature}; its embedded Ed25519 key verifies that signature.
105
- */
106
- readonly challengerPeerId: string;
107
- /**
108
- * The legitimately-selected arbitrator set — the K peer-ids the challenger computed via `sampleArbitrators`
109
- * (verifiable dispersed sampling: the peers nearest K pseudo-random ring coordinates derived from
110
- * `hash(blockId ‖ round ‖ epoch ‖ i)`, spread across the whole keyspace rather than drawn from the disputed
111
- * block's neighborhood). Every counted vote's `arbitratorPeerId` must be a member; the set is bound to the
112
- * originator by {@link arbitratorSetSignature} and, when feasible, re-derived from the verifying member's topology.
113
- */
114
- readonly arbitratorSet: ReadonlyArray<string>;
115
- /**
116
- * The challenger's base64url Ed25519 signature (verified against {@link challengerPeerId}'s embedded
117
- * key) over `utf8(`v3set:${disputeId}:${targetHash}:${setHash}`)` — binds `(disputeId, target,
118
- * arbitratorSet)` to the originator so a relay cannot substitute its own cohort. Tampering with
119
- * {@link arbitratorSet} (e.g. adding sybils) invalidates this signature.
120
- */
121
- readonly arbitratorSetSignature: string;
122
- /** Signed arbitrator votes. */
123
- readonly votes: ReadonlyArray<ArbitrationVoteProof>;
124
- };
125
-
126
- /** Per-block compensating result an invalidation produced. */
127
- export type RevertedBlock = {
128
- /** Block whose tip was reverted. */
129
- readonly blockId: BlockId;
130
- /** Revision the block was at before this invalidation (the tip that was reverted). */
131
- readonly fromRev: number;
132
- /** Content hash of the new revision restoring the as-if-`T_inv`-absent content. */
133
- readonly restoredContentHash: string;
134
- };
135
-
136
- /** A compensating entry that reverses a previously-committed action proven invalid by dispute. */
137
- export type InvalidationEntry = {
138
- /** actionId of the committed {@link ActionEntry} being reversed. */
139
- readonly invalidatedActionId: ActionId;
140
- /** rev of the invalidated entry — pins which block revisions to roll back. */
141
- readonly invalidatedRev: number;
142
- /** Authoritative proof: a challenger-wins resolution carrying the signed arbitrator votes. */
143
- readonly resolution: DisputeResolutionProof;
144
- /** Per-block compensating result this entry produced (new monotonic revision restoring pre-`T_inv` content). */
145
- readonly reverted: ReadonlyArray<RevertedBlock>;
146
- /** When this invalidation is a cascade step, the root invalidation that triggered it (unused this ticket; see cascade ticket). */
147
- readonly cascadeRoot?: ActionId;
148
- };
149
-
150
- /** A checkpoint entry restates the currently uncheckpointed actions */
151
- export type CheckpointEntry = {
152
- /** The current set of pending action/revs
153
- * - actions implicitly increase the set of pending Ids
154
- * - this restates the entire current set
155
- * - missing from the set are the implicitly checkpointed ones */
156
- readonly pendings: ActionRev[];
157
- };
158
-
159
- export const LogDataBlockType = "LGD";
160
- export const LogHeaderBlockType = "LGH";
161
-
162
- export type GetFromResult<TAction> = {
163
- context: ActionContext | undefined;
164
- entries: ActionEntry<TAction>[];
165
- };
1
+ import type { BlockId, CollectionId, ActionContext, ActionId, ActionRev, ReadDependency } from "../index.js";
2
+
3
+ /** A log entry - an action, a checkpoint, or an invalidation */
4
+ export type LogEntry<TAction> = {
5
+ /** Linux timestamp of the entry */
6
+ readonly timestamp: number;
7
+ /** Revision number - monotonically increasing from the prior entry's rev. Starts at 1. */
8
+ readonly rev: number;
9
+ readonly action?: ActionEntry<TAction>;
10
+ readonly checkpoint?: CheckpointEntry;
11
+ /** A compensating entry that reverses a previously-committed action proven invalid by dispute. */
12
+ readonly invalidation?: InvalidationEntry;
13
+ };
14
+
15
+ /** An action entry represents a unit of work that is atomic */
16
+ export type ActionEntry<TAction> = {
17
+ /** Generated unique identifier for the action */
18
+ readonly actionId: ActionId;
19
+ /** Actions to be applied */
20
+ readonly actions: TAction[];
21
+ /** Block ids affected by the action - includes the log related blocks */
22
+ blockIds: BlockId[]; // NOTE: this is updated after being generated to include the log-related block transforms
23
+ /** Other collection ids affected by the action - this action is conditional on successful commit in all of these collections */
24
+ readonly collectionIds?: CollectionId[];
25
+ /**
26
+ * The `(blockId, revision)` reads this transaction observed during execution — the same
27
+ * read set the {@link Transaction} carried in its PEND request (see `Transaction.reads`).
28
+ *
29
+ * Persisted so a later invalidation cascade can discover this action's read-dependents:
30
+ * a committed action is a read-dependent of an invalidated one iff its read set contains a
31
+ * `(blockId, revision)` that the invalidated action produced.
32
+ *
33
+ * **Format / back-compat:** added by the invalidation-cascade work (ActionEntry v2). An entry
34
+ * written before this field existed (or by a path that does not carry a `Transaction`, e.g. the
35
+ * low-level `Collection.sync` direct-commit) has `reads === undefined` — treated by the cascade
36
+ * as an *unknown dependency* (conservatively re-evaluated, never silently assumed independent).
37
+ * `reads === []` is distinct: a transaction that genuinely read nothing.
38
+ */
39
+ readonly reads?: ReadDependency[];
40
+ };
41
+
42
+ /**
43
+ * One arbitrator's signed verdict — the minimal subset of a dispute vote needed to re-verify
44
+ * it independently. The Ed25519 public key that verifies {@link signature} is embedded in
45
+ * {@link arbitratorPeerId} (a libp2p Ed25519 peer id).
46
+ *
47
+ * The signed payload is **target- and arbitrator-set-bound** (v3):
48
+ * `utf8(`v3:${disputeId}:${vote}:${computedHash}:${targetHash}:${setHash}`)`, where
49
+ * - `targetHash = hashString(`${messageHash}|${invalidatedActionId}|${sortedBlockIds.join(',')}`)`
50
+ * commits the vote to the *specific* transaction being reversed (#2), and
51
+ * - `setHash = hashString(sortedArbitratorSet.join(','))` commits it to the *legitimately-selected
52
+ * arbitrator set* (#1) carried on {@link DisputeResolutionProof.arbitratorSet}.
53
+ *
54
+ * A verifier recomputes both digests from the proof plus the apply-path target, so a genuine vote can
55
+ * neither be replayed against an unrelated transaction nor presented under a swapped cohort. v1/v2
56
+ * (un-set-bound) votes are rejected, not accepted-by-default; the {@link version} marker is required.
57
+ */
58
+ export type ArbitrationVoteProof = {
59
+ /** Wire-format version of the signed payload. Only `'v3'` is accepted; absent/unrecognized → rejected. */
60
+ readonly version: 'v3';
61
+ /** Peer id of the arbitrator; its embedded Ed25519 public key verifies {@link signature}. */
62
+ readonly arbitratorPeerId: string;
63
+ /** The arbitrator's verdict. */
64
+ readonly vote: 'agree-with-challenger' | 'agree-with-majority' | 'inconclusive';
65
+ /** The operations hash the arbitrator computed (part of the signed payload). */
66
+ readonly computedHash: string;
67
+ /** Base64url-encoded Ed25519 signature over `v3:${disputeId}:${vote}:${computedHash}:${targetHash}:${setHash}`. */
68
+ readonly signature: string;
69
+ };
70
+
71
+ /**
72
+ * The authoritative, independently-verifiable subset of a dispute resolution that proves a
73
+ * committed transaction invalid. Carried inside an {@link InvalidationEntry}.
74
+ *
75
+ * Defined in db-core (the log layer) deliberately: the log must not import db-p2p, so the dispute
76
+ * layer's richer `DisputeResolution` maps *onto* this proof rather than this proof importing it.
77
+ * A member treats the proof as a reversal certificate — `outcome === 'challenger-wins'` with a
78
+ * 2/3 super-majority of decisive votes agreeing with the challenger (each signature verifiable
79
+ * against its arbitrator's embedded key, each vote target-bound, drawn from the legitimately-selected
80
+ * {@link arbitratorSet}, and counted at most once per arbitrator).
81
+ *
82
+ * **Unforgeability.** Votes are bound to the reversed transaction (`targetHash`, #2), counted at most
83
+ * once per arbitrator (#3), and bound to the legitimately-selected arbitrator set (#1):
84
+ * {@link arbitratorSet} carries the K peer-ids the challenger selected, every counted vote must be a
85
+ * member of it, and {@link arbitratorSetSignature} — the challenger's Ed25519 signature (verified
86
+ * against {@link challengerPeerId}) over `(disputeId, target, arbitratorSet)` — binds the set to the
87
+ * originator so a third-party relay cannot swap in its own sybils. A verifying member additionally
88
+ * re-derives the eligible set from its own topology when it can (an injected recompute capability),
89
+ * closing even a fully-malicious challenger; when it cannot (late-joiner / churned DHT view) it accepts
90
+ * on the challenger-bound set + membership + dedup and *logs* the residual topology-anchoring gap rather
91
+ * than silently accepting — a gap closed in full by the cohort-topic membership-cert trust-anchor chain
92
+ * (`tickets/plan/cohort-topic-membership-cert-trust-anchoring.md`). Net: a compromised peer can withhold
93
+ * an invalidation but cannot forge one.
94
+ */
95
+ export type DisputeResolutionProof = {
96
+ /** Identifies the dispute these votes resolved. */
97
+ readonly disputeId: string;
98
+ /** messageHash of the original (now-invalid) committed transaction. */
99
+ readonly messageHash: string;
100
+ /** Resolution outcome; only `challenger-wins` authorizes an invalidation. */
101
+ readonly outcome: 'challenger-wins' | 'majority-wins' | 'inconclusive';
102
+ /**
103
+ * Peer-id of the challenger (dissent coordinator) that selected the arbitrator set and produced
104
+ * {@link arbitratorSetSignature}; its embedded Ed25519 key verifies that signature.
105
+ */
106
+ readonly challengerPeerId: string;
107
+ /**
108
+ * The legitimately-selected arbitrator set — the K peer-ids the challenger computed via `sampleArbitrators`
109
+ * (verifiable dispersed sampling: the peers nearest K pseudo-random ring coordinates derived from
110
+ * `hash(blockId ‖ round ‖ epoch ‖ i)`, spread across the whole keyspace rather than drawn from the disputed
111
+ * block's neighborhood). Every counted vote's `arbitratorPeerId` must be a member; the set is bound to the
112
+ * originator by {@link arbitratorSetSignature} and, when feasible, re-derived from the verifying member's topology.
113
+ */
114
+ readonly arbitratorSet: ReadonlyArray<string>;
115
+ /**
116
+ * The challenger's base64url Ed25519 signature (verified against {@link challengerPeerId}'s embedded
117
+ * key) over `utf8(`v3set:${disputeId}:${targetHash}:${setHash}`)` — binds `(disputeId, target,
118
+ * arbitratorSet)` to the originator so a relay cannot substitute its own cohort. Tampering with
119
+ * {@link arbitratorSet} (e.g. adding sybils) invalidates this signature.
120
+ */
121
+ readonly arbitratorSetSignature: string;
122
+ /** Signed arbitrator votes. */
123
+ readonly votes: ReadonlyArray<ArbitrationVoteProof>;
124
+ };
125
+
126
+ /** Per-block compensating result an invalidation produced. */
127
+ export type RevertedBlock = {
128
+ /** Block whose tip was reverted. */
129
+ readonly blockId: BlockId;
130
+ /** Revision the block was at before this invalidation (the tip that was reverted). */
131
+ readonly fromRev: number;
132
+ /** Content hash of the new revision restoring the as-if-`T_inv`-absent content. */
133
+ readonly restoredContentHash: string;
134
+ };
135
+
136
+ /** A compensating entry that reverses a previously-committed action proven invalid by dispute. */
137
+ export type InvalidationEntry = {
138
+ /** actionId of the committed {@link ActionEntry} being reversed. */
139
+ readonly invalidatedActionId: ActionId;
140
+ /** rev of the invalidated entry — pins which block revisions to roll back. */
141
+ readonly invalidatedRev: number;
142
+ /** Authoritative proof: a challenger-wins resolution carrying the signed arbitrator votes. */
143
+ readonly resolution: DisputeResolutionProof;
144
+ /** Per-block compensating result this entry produced (new monotonic revision restoring pre-`T_inv` content). */
145
+ readonly reverted: ReadonlyArray<RevertedBlock>;
146
+ /** When this invalidation is a cascade step, the root invalidation that triggered it (unused this ticket; see cascade ticket). */
147
+ readonly cascadeRoot?: ActionId;
148
+ };
149
+
150
+ /** A checkpoint entry restates the currently uncheckpointed actions */
151
+ export type CheckpointEntry = {
152
+ /** The current set of pending action/revs
153
+ * - actions implicitly increase the set of pending Ids
154
+ * - this restates the entire current set
155
+ * - missing from the set are the implicitly checkpointed ones */
156
+ readonly pendings: ActionRev[];
157
+ };
158
+
159
+ export const LogDataBlockType = "LGD";
160
+ export const LogHeaderBlockType = "LGH";
161
+
162
+ export type GetFromResult<TAction> = {
163
+ context: ActionContext | undefined;
164
+ entries: ActionEntry<TAction>[];
165
+ };
@@ -1,45 +1,45 @@
1
- /**
2
- * Matchmaking — cohort-side capability-filter evaluation (db-core, pure).
3
- *
4
- * Per `docs/matchmaking.md` §Capability filter: the filter is evaluated **locally at the cohort** and
5
- * is **advisory only** — it biases which providers the cohort returns but is never admission. The
6
- * seeker re-validates the returned set (`registrationSig`) and escalates if the filter matches too
7
- * little (§Edge cases 4). A pathological filter that matches almost nothing is therefore acceptable.
8
- *
9
- * Semantics (`docs/matchmaking.md` §Capability filter / §Wire formats):
10
- * - `must` — every tag must be present in the provider's `capabilities`.
11
- * - `mustNot` — no tag may be present in the provider's `capabilities`.
12
- * - `minBudget` — when set, the provider's `capacityBudget` must be `>= minBudget`.
13
- *
14
- * An absent filter matches every provider.
15
- */
16
-
17
- import type { CapabilityFilter } from "./wire.js";
18
-
19
- /** The provider attributes a {@link CapabilityFilter} is evaluated against. */
20
- export interface FilterableProvider {
21
- readonly capabilities: readonly string[];
22
- readonly capacityBudget: number;
23
- }
24
-
25
- /** True iff `p` satisfies `f` (`must` ⊆ caps, `mustNot` ∩ caps = ∅, `capacityBudget >= minBudget`). */
26
- export function matchesFilter(p: FilterableProvider, f: CapabilityFilter | undefined): boolean {
27
- if (f === undefined) {
28
- return true;
29
- }
30
- const caps = new Set(p.capabilities);
31
- for (const tag of f.must) {
32
- if (!caps.has(tag)) {
33
- return false;
34
- }
35
- }
36
- for (const tag of f.mustNot) {
37
- if (caps.has(tag)) {
38
- return false;
39
- }
40
- }
41
- if (f.minBudget !== undefined && p.capacityBudget < f.minBudget) {
42
- return false;
43
- }
44
- return true;
45
- }
1
+ /**
2
+ * Matchmaking — cohort-side capability-filter evaluation (db-core, pure).
3
+ *
4
+ * Per `docs/matchmaking.md` §Capability filter: the filter is evaluated **locally at the cohort** and
5
+ * is **advisory only** — it biases which providers the cohort returns but is never admission. The
6
+ * seeker re-validates the returned set (`registrationSig`) and escalates if the filter matches too
7
+ * little (§Edge cases 4). A pathological filter that matches almost nothing is therefore acceptable.
8
+ *
9
+ * Semantics (`docs/matchmaking.md` §Capability filter / §Wire formats):
10
+ * - `must` — every tag must be present in the provider's `capabilities`.
11
+ * - `mustNot` — no tag may be present in the provider's `capabilities`.
12
+ * - `minBudget` — when set, the provider's `capacityBudget` must be `>= minBudget`.
13
+ *
14
+ * An absent filter matches every provider.
15
+ */
16
+
17
+ import type { CapabilityFilter } from "./wire.js";
18
+
19
+ /** The provider attributes a {@link CapabilityFilter} is evaluated against. */
20
+ export interface FilterableProvider {
21
+ readonly capabilities: readonly string[];
22
+ readonly capacityBudget: number;
23
+ }
24
+
25
+ /** True iff `p` satisfies `f` (`must` ⊆ caps, `mustNot` ∩ caps = ∅, `capacityBudget >= minBudget`). */
26
+ export function matchesFilter(p: FilterableProvider, f: CapabilityFilter | undefined): boolean {
27
+ if (f === undefined) {
28
+ return true;
29
+ }
30
+ const caps = new Set(p.capabilities);
31
+ for (const tag of f.must) {
32
+ if (!caps.has(tag)) {
33
+ return false;
34
+ }
35
+ }
36
+ for (const tag of f.mustNot) {
37
+ if (caps.has(tag)) {
38
+ return false;
39
+ }
40
+ }
41
+ if (f.minBudget !== undefined && p.capacityBudget < f.minBudget) {
42
+ return false;
43
+ }
44
+ return true;
45
+ }
@@ -1,98 +1,98 @@
1
- /**
2
- * Matchmaking — configuration defaults.
3
- *
4
- * Transcribed from `docs/matchmaking.md` §Configuration. This module owns the matchmaking config
5
- * surface: the **wire/TTL** constants (provider/seeker TTLs, the query limit, the seeker renew grace,
6
- * the aggregate-count minimum tier) AND the seeker **hang-out tuning** rows (`patience_*`,
7
- * `filter_accept_ratio_initial`, `contention_factor_cap`, `requery_interval_ms`, `mean_want_count`)
8
- * consumed by the {@link import("./seeker-walk.js").decide} engine and the db-p2p seeker-walk client.
9
- *
10
- * The TTL/limit constants are wire-stable and do **not** depend on simulator findings; the hang-out
11
- * rows DO (folded via `fold-simulator-findings-into-design-docs`) — they carry the simulator-validated
12
- * defaults (`contention_factor_cap = 4.0`, `mean_want_count = 3`, …; see `docs/matchmaking.md`
13
- * §Configuration "Defaults validated by simulator"). The `push_*` rows belong to the arrival-push
14
- * path (a separate slice) and are intentionally not modeled here.
15
- */
16
-
17
- import type { NodeProfile } from "../cohort-topic/tiers.js";
18
-
19
- /** Provider registration TTL on a Core node (ms). */
20
- export const PROVIDER_TTL_CORE_MS = 90_000;
21
- /** Provider registration TTL on an Edge node (ms). */
22
- export const PROVIDER_TTL_EDGE_MS = 60_000;
23
- /** Seeker registration TTL (ms) — short, since seekers normally don't wait long. */
24
- export const SEEKER_TTL_MS = 10_000;
25
- /** Documented seeker-TTL range (ms); `SEEKER_TTL_MS` sits inside it. */
26
- export const SEEKER_TTL_MIN_MS = 5_000;
27
- export const SEEKER_TTL_MAX_MS = 15_000;
28
- /** Max entries returned in a single `QueryV1` reply. */
29
- export const QUERY_LIMIT_MAX = 256;
30
- /** Grace window a seeker may keep querying after its TTL expires (ms). */
31
- export const SEEKER_RENEW_GRACE_MS = 5_000;
32
- /** Root cohorts produce aggregate counts only when tree depth ≥ this. */
33
- export const AGGREGATE_COUNT_MINIMUM_TIER = 1;
34
-
35
- // --- Seeker hang-out tuning (simulator-folded; consumed by seeker-walk.ts + the walk client) ---
36
-
37
- /** Fallback `patienceMs` when a caller does not specify it per-task (ms). */
38
- export const PATIENCE_DEFAULT_MS = 10_000;
39
- /** Fraction of remaining patience spent at one tier before considering escalation (1.0 = spend it all here). */
40
- export const PATIENCE_PER_TIER_FRACTION = 1.0;
41
- /** Starting estimate for `filterAcceptRatio`, refined per walk from observed query yields. */
42
- export const FILTER_ACCEPT_RATIO_INITIAL = 1.0;
43
- /** Upper bound on the contention multiplier in the hang-out decision (simulator-validated global scalar). */
44
- export const CONTENTION_FACTOR_CAP = 4.0;
45
- /** Mean `wantCount` assumed for competing seekers in the contention estimate (small constant; simulator value). */
46
- export const MEAN_WANT_COUNT_DEFAULT = 3;
47
- /** How often a hanging-out seeker re-issues `QueryV1` on the non-push (poll) path (ms). */
48
- export const REQUERY_INTERVAL_MS = 1_000;
49
- /** Window the seeker's primary batches fresh matchable arrivals before flushing one push (ms; arrival-push path). */
50
- export const PUSH_COALESCE_MS = 250;
51
- /** Sparse fallback `QueryV1` cadence for a push-aware hanging-out seeker (ms; arrival-push path). */
52
- export const PUSH_SAFETY_POLL_MS = 5_000;
53
-
54
- /**
55
- * The seeker hang-out decision tuning (`docs/matchmaking.md` §Hang-out vs. continue / §Configuration).
56
- * `meanWantCount` lives here because {@link import("./seeker-walk.js").SeekerDecisionInputs} carries it
57
- * per-call (it may be learned), but the default is this constant.
58
- */
59
- export interface HangOutConfig {
60
- /** Clamp on the contention multiplier; protects against pathological `queriesPerMin / arrivalsPerMin`. */
61
- readonly contentionFactorCap: number;
62
- /** Hang-out poll cadence on the non-push path. */
63
- readonly requeryIntervalMs: number;
64
- }
65
-
66
- /** The default hang-out decision config (simulator-validated). */
67
- export const DEFAULT_HANG_OUT_CONFIG: HangOutConfig = {
68
- contentionFactorCap: CONTENTION_FACTOR_CAP,
69
- requeryIntervalMs: REQUERY_INTERVAL_MS,
70
- };
71
-
72
- /** The full matchmaking config, with the documented defaults. */
73
- export interface MatchmakingConfig {
74
- readonly providerTtlCoreMs: number;
75
- readonly providerTtlEdgeMs: number;
76
- readonly seekerTtlMs: number;
77
- readonly queryLimitMax: number;
78
- readonly seekerRenewGraceMs: number;
79
- readonly aggregateCountMinimumTier: number;
80
- }
81
-
82
- /** The default matchmaking config (this ticket's slice). */
83
- export const DEFAULT_MATCHMAKING_CONFIG: MatchmakingConfig = {
84
- providerTtlCoreMs: PROVIDER_TTL_CORE_MS,
85
- providerTtlEdgeMs: PROVIDER_TTL_EDGE_MS,
86
- seekerTtlMs: SEEKER_TTL_MS,
87
- queryLimitMax: QUERY_LIMIT_MAX,
88
- seekerRenewGraceMs: SEEKER_RENEW_GRACE_MS,
89
- aggregateCountMinimumTier: AGGREGATE_COUNT_MINIMUM_TIER,
90
- };
91
-
92
- /**
93
- * Provider TTL for a node profile: Core nodes hold registrations for `PROVIDER_TTL_CORE_MS`, Edge
94
- * nodes for the shorter `PROVIDER_TTL_EDGE_MS` (`docs/matchmaking.md` §Provider registration).
95
- */
96
- export function providerTtlForProfile(profile: NodeProfile, config: MatchmakingConfig = DEFAULT_MATCHMAKING_CONFIG): number {
97
- return profile.kind === "edge" ? config.providerTtlEdgeMs : config.providerTtlCoreMs;
98
- }
1
+ /**
2
+ * Matchmaking — configuration defaults.
3
+ *
4
+ * Transcribed from `docs/matchmaking.md` §Configuration. This module owns the matchmaking config
5
+ * surface: the **wire/TTL** constants (provider/seeker TTLs, the query limit, the seeker renew grace,
6
+ * the aggregate-count minimum tier) AND the seeker **hang-out tuning** rows (`patience_*`,
7
+ * `filter_accept_ratio_initial`, `contention_factor_cap`, `requery_interval_ms`, `mean_want_count`)
8
+ * consumed by the {@link import("./seeker-walk.js").decide} engine and the db-p2p seeker-walk client.
9
+ *
10
+ * The TTL/limit constants are wire-stable and do **not** depend on simulator findings; the hang-out
11
+ * rows DO (folded via `fold-simulator-findings-into-design-docs`) — they carry the simulator-validated
12
+ * defaults (`contention_factor_cap = 4.0`, `mean_want_count = 3`, …; see `docs/matchmaking.md`
13
+ * §Configuration "Defaults validated by simulator"). The `push_*` rows belong to the arrival-push
14
+ * path (a separate slice) and are intentionally not modeled here.
15
+ */
16
+
17
+ import type { NodeProfile } from "../cohort-topic/tiers.js";
18
+
19
+ /** Provider registration TTL on a Core node (ms). */
20
+ export const PROVIDER_TTL_CORE_MS = 90_000;
21
+ /** Provider registration TTL on an Edge node (ms). */
22
+ export const PROVIDER_TTL_EDGE_MS = 60_000;
23
+ /** Seeker registration TTL (ms) — short, since seekers normally don't wait long. */
24
+ export const SEEKER_TTL_MS = 10_000;
25
+ /** Documented seeker-TTL range (ms); `SEEKER_TTL_MS` sits inside it. */
26
+ export const SEEKER_TTL_MIN_MS = 5_000;
27
+ export const SEEKER_TTL_MAX_MS = 15_000;
28
+ /** Max entries returned in a single `QueryV1` reply. */
29
+ export const QUERY_LIMIT_MAX = 256;
30
+ /** Grace window a seeker may keep querying after its TTL expires (ms). */
31
+ export const SEEKER_RENEW_GRACE_MS = 5_000;
32
+ /** Root cohorts produce aggregate counts only when tree depth ≥ this. */
33
+ export const AGGREGATE_COUNT_MINIMUM_TIER = 1;
34
+
35
+ // --- Seeker hang-out tuning (simulator-folded; consumed by seeker-walk.ts + the walk client) ---
36
+
37
+ /** Fallback `patienceMs` when a caller does not specify it per-task (ms). */
38
+ export const PATIENCE_DEFAULT_MS = 10_000;
39
+ /** Fraction of remaining patience spent at one tier before considering escalation (1.0 = spend it all here). */
40
+ export const PATIENCE_PER_TIER_FRACTION = 1.0;
41
+ /** Starting estimate for `filterAcceptRatio`, refined per walk from observed query yields. */
42
+ export const FILTER_ACCEPT_RATIO_INITIAL = 1.0;
43
+ /** Upper bound on the contention multiplier in the hang-out decision (simulator-validated global scalar). */
44
+ export const CONTENTION_FACTOR_CAP = 4.0;
45
+ /** Mean `wantCount` assumed for competing seekers in the contention estimate (small constant; simulator value). */
46
+ export const MEAN_WANT_COUNT_DEFAULT = 3;
47
+ /** How often a hanging-out seeker re-issues `QueryV1` on the non-push (poll) path (ms). */
48
+ export const REQUERY_INTERVAL_MS = 1_000;
49
+ /** Window the seeker's primary batches fresh matchable arrivals before flushing one push (ms; arrival-push path). */
50
+ export const PUSH_COALESCE_MS = 250;
51
+ /** Sparse fallback `QueryV1` cadence for a push-aware hanging-out seeker (ms; arrival-push path). */
52
+ export const PUSH_SAFETY_POLL_MS = 5_000;
53
+
54
+ /**
55
+ * The seeker hang-out decision tuning (`docs/matchmaking.md` §Hang-out vs. continue / §Configuration).
56
+ * `meanWantCount` lives here because {@link import("./seeker-walk.js").SeekerDecisionInputs} carries it
57
+ * per-call (it may be learned), but the default is this constant.
58
+ */
59
+ export interface HangOutConfig {
60
+ /** Clamp on the contention multiplier; protects against pathological `queriesPerMin / arrivalsPerMin`. */
61
+ readonly contentionFactorCap: number;
62
+ /** Hang-out poll cadence on the non-push path. */
63
+ readonly requeryIntervalMs: number;
64
+ }
65
+
66
+ /** The default hang-out decision config (simulator-validated). */
67
+ export const DEFAULT_HANG_OUT_CONFIG: HangOutConfig = {
68
+ contentionFactorCap: CONTENTION_FACTOR_CAP,
69
+ requeryIntervalMs: REQUERY_INTERVAL_MS,
70
+ };
71
+
72
+ /** The full matchmaking config, with the documented defaults. */
73
+ export interface MatchmakingConfig {
74
+ readonly providerTtlCoreMs: number;
75
+ readonly providerTtlEdgeMs: number;
76
+ readonly seekerTtlMs: number;
77
+ readonly queryLimitMax: number;
78
+ readonly seekerRenewGraceMs: number;
79
+ readonly aggregateCountMinimumTier: number;
80
+ }
81
+
82
+ /** The default matchmaking config (this ticket's slice). */
83
+ export const DEFAULT_MATCHMAKING_CONFIG: MatchmakingConfig = {
84
+ providerTtlCoreMs: PROVIDER_TTL_CORE_MS,
85
+ providerTtlEdgeMs: PROVIDER_TTL_EDGE_MS,
86
+ seekerTtlMs: SEEKER_TTL_MS,
87
+ queryLimitMax: QUERY_LIMIT_MAX,
88
+ seekerRenewGraceMs: SEEKER_RENEW_GRACE_MS,
89
+ aggregateCountMinimumTier: AGGREGATE_COUNT_MINIMUM_TIER,
90
+ };
91
+
92
+ /**
93
+ * Provider TTL for a node profile: Core nodes hold registrations for `PROVIDER_TTL_CORE_MS`, Edge
94
+ * nodes for the shorter `PROVIDER_TTL_EDGE_MS` (`docs/matchmaking.md` §Provider registration).
95
+ */
96
+ export function providerTtlForProfile(profile: NodeProfile, config: MatchmakingConfig = DEFAULT_MATCHMAKING_CONFIG): number {
97
+ return profile.kind === "edge" ? config.providerTtlEdgeMs : config.providerTtlCoreMs;
98
+ }