@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.
- package/README.md +336 -336
- package/dist/src/collection/collection.d.ts +44 -4
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +95 -14
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/log/log.d.ts +41 -8
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +15 -10
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +36 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +49 -0
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +26 -9
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/package.json +1 -1
- package/src/blocks/block-store.ts +31 -31
- package/src/blocks/block-types.ts +11 -11
- package/src/blocks/index.ts +5 -5
- package/src/blocks/structs.ts +17 -17
- package/src/btree/btree.ts +872 -872
- package/src/btree/independent-trunk.ts +53 -53
- package/src/btree/index.ts +5 -5
- package/src/btree/key-range.ts +15 -15
- package/src/btree/keyset.ts +6 -6
- package/src/btree/nodes.ts +25 -25
- package/src/btree/path.ts +37 -37
- package/src/btree/tree-block.ts +11 -11
- package/src/btree/trunk.ts +14 -14
- package/src/chain/chain-nodes.ts +26 -26
- package/src/chain/chain.ts +349 -349
- package/src/chain/index.ts +3 -3
- package/src/cluster/i-cluster.ts +6 -6
- package/src/cluster/index.ts +3 -3
- package/src/cohort-topic/addressing.ts +120 -120
- package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
- package/src/cohort-topic/antidos/index.ts +5 -5
- package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
- package/src/cohort-topic/antidos/replay-guard.ts +146 -146
- package/src/cohort-topic/antidos/topic-budget.ts +160 -160
- package/src/cohort-topic/antiflood/index.ts +2 -2
- package/src/cohort-topic/antiflood/invariants.ts +108 -108
- package/src/cohort-topic/antiflood/jitter.ts +117 -117
- package/src/cohort-topic/coldstart.ts +237 -237
- package/src/cohort-topic/dmax.ts +88 -88
- package/src/cohort-topic/gossip/bus.ts +254 -254
- package/src/cohort-topic/gossip/index.ts +3 -3
- package/src/cohort-topic/gossip/records.ts +45 -45
- package/src/cohort-topic/gossip/view.ts +91 -91
- package/src/cohort-topic/index.ts +20 -20
- package/src/cohort-topic/load/barometer.ts +134 -134
- package/src/cohort-topic/load/index.ts +1 -1
- package/src/cohort-topic/member-engine.ts +430 -430
- package/src/cohort-topic/membership/index.ts +3 -3
- package/src/cohort-topic/membership/publisher.ts +163 -163
- package/src/cohort-topic/membership/source.ts +41 -41
- package/src/cohort-topic/ports.ts +157 -157
- package/src/cohort-topic/promotion.ts +477 -477
- package/src/cohort-topic/registration/bytes.ts +37 -37
- package/src/cohort-topic/registration/handoff.ts +154 -154
- package/src/cohort-topic/registration/index.ts +6 -6
- package/src/cohort-topic/registration/renewal.ts +495 -495
- package/src/cohort-topic/registration/sharding.ts +61 -61
- package/src/cohort-topic/registration/store.ts +81 -81
- package/src/cohort-topic/registration/types.ts +91 -91
- package/src/cohort-topic/ring-hash.ts +50 -50
- package/src/cohort-topic/service.ts +416 -416
- package/src/cohort-topic/sig/index.ts +2 -2
- package/src/cohort-topic/sig/payloads.ts +59 -59
- package/src/cohort-topic/sig/threshold.ts +64 -64
- package/src/cohort-topic/tiers.ts +74 -74
- package/src/cohort-topic/traffic.ts +233 -233
- package/src/cohort-topic/walk.ts +326 -326
- package/src/cohort-topic/willingness.ts +237 -237
- package/src/cohort-topic/wire/index.ts +18 -18
- package/src/cohort-topic/wire/payloads.ts +126 -126
- package/src/collection/action.ts +48 -48
- package/src/collection/collection-type-registry.ts +37 -37
- package/src/collection/collection.ts +2203 -2118
- package/src/collection/index.ts +4 -4
- package/src/collections/diary/index.ts +2 -2
- package/src/collections/diary/struct.ts +3 -3
- package/src/collections/index.ts +2 -2
- package/src/collections/tree/collection-trunk.ts +25 -25
- package/src/collections/tree/index.ts +2 -2
- package/src/collections/tree/readme.md +55 -55
- package/src/log/index.ts +2 -2
- package/src/log/log.ts +304 -268
- package/src/log/struct.ts +165 -165
- package/src/matchmaking/capability-filter.ts +45 -45
- package/src/matchmaking/config.ts +98 -98
- package/src/matchmaking/index.ts +21 -21
- package/src/matchmaking/multi-cohort-seeker.ts +234 -234
- package/src/matchmaking/provider.ts +123 -123
- package/src/matchmaking/query-eval.ts +105 -105
- package/src/matchmaking/seeker-walk.ts +127 -127
- package/src/matchmaking/seeker.ts +86 -86
- package/src/matchmaking/topic-anchor.ts +90 -90
- package/src/matchmaking/voting-quorum.ts +394 -394
- package/src/network/i-peer-network.ts +25 -25
- package/src/network/repo-protocol.ts +13 -13
- package/src/network/types.ts +37 -37
- package/src/reactivity/backfill.ts +220 -220
- package/src/reactivity/backpressure.ts +191 -191
- package/src/reactivity/checkpoint.ts +308 -308
- package/src/reactivity/config.ts +172 -172
- package/src/reactivity/dedupe.ts +132 -132
- package/src/reactivity/forwarder.ts +87 -87
- package/src/reactivity/index.ts +34 -34
- package/src/reactivity/notification.ts +123 -123
- package/src/reactivity/policy.ts +79 -79
- package/src/reactivity/push-state.ts +310 -310
- package/src/reactivity/recover.ts +153 -153
- package/src/reactivity/replay-buffer.ts +141 -141
- package/src/reactivity/resume.ts +549 -549
- package/src/reactivity/rotation.ts +415 -415
- package/src/reactivity/subscriber.ts +132 -132
- package/src/reactivity/subscription.ts +66 -66
- package/src/reactivity/topic-anchor.ts +71 -71
- package/src/reactivity/verify.ts +73 -73
- package/src/reactivity/wire-validate.ts +13 -13
- package/src/testing/async-wait.ts +65 -65
- package/src/testing/index.ts +2 -2
- package/src/testing/test-transactor.ts +62 -0
- package/src/transaction/actions-engine.ts +68 -68
- package/src/transaction/coordinator.ts +28 -11
- package/src/transaction/index.ts +52 -52
- package/src/transaction/operations-hash.ts +196 -196
- package/src/transaction/read-dependency-collector.ts +78 -78
- package/src/transaction/session.ts +238 -238
- package/src/transaction/transaction.ts +442 -442
- package/src/transaction/validator.ts +197 -197
- package/src/transactor/block-floors.ts +126 -126
- package/src/transactor/index.ts +6 -6
- package/src/transactor/network-transactor.ts +1545 -1545
- package/src/transform/atomic-proxy.ts +92 -92
- package/src/transform/cache-source.ts +370 -370
- package/src/transform/helpers.ts +164 -164
- package/src/transform/index.ts +7 -7
- package/src/transform/struct.ts +21 -21
- package/src/utility/actor.ts +62 -62
- package/src/utility/backoff.ts +95 -95
- package/src/utility/batch-coordinator.ts +191 -191
- package/src/utility/ensured.ts +32 -32
- package/src/utility/groupby.ts +18 -18
- package/src/utility/hash-string.ts +14 -14
- package/src/utility/is-record-empty.ts +5 -5
- package/src/utility/latches.ts +42 -42
- package/src/utility/lru-map.ts +60 -60
- package/src/utility/nameof.ts +7 -7
- 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
|
+
}
|