uvd-describe-sdk 0.1.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.
package/src/hashes.ts ADDED
@@ -0,0 +1,229 @@
1
+ /**
2
+ * Shape validation for the hash fields — *"el 200 sin tx"*, from KarmaKadabra.
3
+ *
4
+ * Pure: no network, no clock, no state. Strings in, booleans out.
5
+ *
6
+ * ## Where this comes from
7
+ *
8
+ * Contributed by **KarmaKadabra**, `#agents` on MeshRelay, **2026-08-30**. Their
9
+ * words:
10
+ *
11
+ * > *"Un 200 que no hizo la cosa es peor que un 503, porque el cliente lo toma
12
+ * > por bueno: si nosotros no chequeáramos el tx, habríamos contado 14 ratings
13
+ * > que no existen. Nosotros lo cazamos con un sello que exige forma de hash —
14
+ * > pero el contrato debería decirlo, no cada cliente descubrirlo."*
15
+ *
16
+ * The second half is why this lives in the SDK: the check is a property of the
17
+ * CONTRACT, and three consumers each discovering it separately is three chances
18
+ * to get it wrong. Verified before writing a line: neither this SDK nor its
19
+ * Python twin validated the shape of any hash field on 2026-08-30.
20
+ *
21
+ * ## 🔴 Why `^0x[0-9a-f]{64}$` alone would have been a disaster
22
+ *
23
+ * The obvious version of this file — one EVM regex — would have flagged **every
24
+ * Solana rating in the index** as malformed. Two independent confirmations, both
25
+ * read 2026-08-30:
26
+ *
27
+ * * from the writer: `describe-net/describenet/solana_indexer.py:436` puts
28
+ * `firma["signature"]` — a base58 signature — into the `tx_hash` column of
29
+ * the INSERT at `indexer.py:153-157`, the same column the EVM indexer fills
30
+ * with `0x…`. Solana writes to the same tables on purpose, so this is by
31
+ * construction and not an accident of one sample;
32
+ * * from the wire (measured by the Python twin against `GET /feed`): avalanche
33
+ * and celo serve 66-char `0x` + 64 hex, solana serves 87- and 88-char base58
34
+ * with no prefix.
35
+ *
36
+ * An alarm that screams about good data is worse than no alarm: people learn to
37
+ * ignore it, and then it is silent on the day it is right. So this validates the
38
+ * **union** of the legitimate shapes, never the intersection.
39
+ *
40
+ * The shapes the index emits today, each with its source:
41
+ *
42
+ * 1. **EVM hash** — `0x` + 64 hex. `chain/decode.py:253` does `"0x" + …hex()`
43
+ * over a `bytes32` (`_NEW_FEEDBACK_TYPES:85`). This is `tx_hash`,
44
+ * `revoked_tx` and `feedback_hash` on the ten EVM chains.
45
+ * 2. **Solana signature** — base58 (Bitcoin alphabet: no `0`, `O`, `I`, `l`),
46
+ * 86–88 characters. 64 bytes in base58 is 87–88; 86 is reachable with leading
47
+ * zero bytes. On Solana `feedback_hash` is **NULL on purpose**, so a hole
48
+ * there is correct and not a fault.
49
+ * 3. **Bare digest** — 64 hex with **no** `0x`. That is `Snapshot.inputs_digest`,
50
+ * which comes out of `hashlib.sha256(...).hexdigest()` in `aggregate.py:1920`.
51
+ * Demanding the `0x` prefix would have marked every citable snapshot as
52
+ * malformed.
53
+ * 4. **The `pending` sentinel** — only on the `X-Payment-Receipt` header, whose
54
+ * own OpenAPI declares it: the settlement hash *"or `pending` if settlement
55
+ * has not reported one"*. It is a LEGITIMATE value, which is why
56
+ * {@link looksLikeSettlementReceipt} exists separately: treating it as
57
+ * garbage would fire an alarm on the happy path of every fresh payment.
58
+ *
59
+ * ## 🔴 What is deliberately NOT validated: `build_sha`
60
+ *
61
+ * `IndexHealth.buildSha` looks like a hash and is not one, and the measurement
62
+ * that settles it is `describe-net/scripts/build_lambda_zip.py:64` (read
63
+ * 2026-08-30): `estampa = sha + ("-dirty" if sucio else "")`. A legitimate
64
+ * deploy can therefore publish `"<40 hex>-dirty"`, and a validator would scream
65
+ * about a perfectly good build — forever, on every `/health` call. The general
66
+ * rule that falls out of it, and it is the one to apply to the next field:
67
+ * **validate the identifiers a caller will carry somewhere to verify (an
68
+ * explorer, a digest comparison); leave alone the strings that only describe a
69
+ * build.** Nobody looks up a `build_sha`; the service already refuses to publish
70
+ * its `unknown` default as if it were a SHA (`api.py:2439-2456`).
71
+ *
72
+ * ## The question this module answers — and the one it does not
73
+ *
74
+ * It answers **"does this have the shape of an on-chain identifier?"**. It does
75
+ * NOT answer "does this transaction exist?" or "does it say what the index says
76
+ * it says": that is verified in an explorer, which is the entire point of the
77
+ * field (the service's own schema: *"go verify it in an explorer, which is the
78
+ * point"*). A shape check cannot prove existence and does not pretend to.
79
+ *
80
+ * What it does catch is what bit KarmaKadabra: the empty string, `"null"`,
81
+ * `"undefined"`, `"0x"`, `"0x0"`, a truncated hash, an error message parked in
82
+ * the field. Every one of those sails through an `if (rating.txHash)` today with
83
+ * nothing making a sound.
84
+ *
85
+ * 🔴 **And it deliberately does not validate per chain.** A `feedback_hash`
86
+ * shaped like a Solana signature is accepted even though Solana emits none
87
+ * today. Being strict per field would trade a cheap false negative (letting an
88
+ * odd-but-valid shape through) for an expensive false positive (screaming about
89
+ * good data the day the service extends a field), and that contradicts the
90
+ * passthrough rule this package is built on: type what is known, PRESERVE what
91
+ * is not.
92
+ */
93
+
94
+ /**
95
+ * `0x` + 64 hex. Case-insensitive: the index serves lowercase, but a hash
96
+ * written in mixed case is the same hash and flagging it would be a false
97
+ * positive.
98
+ */
99
+ const EVM_HASH = /^0x[0-9a-fA-F]{64}$/;
100
+
101
+ /** 64 hex with NO prefix — a `sha256(...).hexdigest()`, i.e. `inputs_digest`. */
102
+ const BARE_DIGEST = /^[0-9a-fA-F]{64}$/;
103
+
104
+ /**
105
+ * Base58, Bitcoin alphabet (no `0`, `O`, `I`, `l`), 86–88 characters: a Solana
106
+ * transaction signature. Both high lengths measured live on 2026-08-30.
107
+ */
108
+ const BASE58_SIGNATURE = /^[1-9A-HJ-NP-Za-km-z]{86,88}$/;
109
+
110
+ /**
111
+ * The one non-hash value the `X-Payment-Receipt` header declares legitimate.
112
+ *
113
+ * The live OpenAPI says it, not us: the settlement transaction hash *"or
114
+ * `pending` if settlement has not reported one"*.
115
+ */
116
+ export const SETTLEMENT_PENDING = 'pending';
117
+
118
+ /**
119
+ * Does `value` have the shape of an on-chain identifier this index emits?
120
+ *
121
+ * The UNION of the three measured shapes (EVM hash, Solana signature, bare
122
+ * digest) — never the intersection. See the module header for why an EVM-only
123
+ * regex would have marked every Solana rating as malformed.
124
+ *
125
+ * It does not prove the transaction exists. That is the explorer's job.
126
+ */
127
+ export function looksLikeOnchainId(value: string): boolean {
128
+ return EVM_HASH.test(value) || BASE58_SIGNATURE.test(value) || BARE_DIGEST.test(value);
129
+ }
130
+
131
+ /**
132
+ * The same, plus the `pending` sentinel. For `X-Payment-Receipt` and nothing
133
+ * else.
134
+ *
135
+ * `pending` is not garbage: it is the seller saying *"I charged you and
136
+ * settlement has not reported the hash yet"*, and it is in their OpenAPI.
137
+ * Marking it malformed would turn the happy path of every freshly settled
138
+ * payment into an alarm.
139
+ */
140
+ export function looksLikeSettlementReceipt(value: string): boolean {
141
+ return value === SETTLEMENT_PENDING || looksLikeOnchainId(value);
142
+ }
143
+
144
+ /**
145
+ * Read one hash field off a wire object: keep it if it has the shape of a hash,
146
+ * otherwise `null` **and a mark**.
147
+ *
148
+ * 🔴 **Absent and malformed are not the same thing** (R1, applied one level
149
+ * below where it usually lives) and this function is where the distinction is
150
+ * made, so read the two cases carefully:
151
+ *
152
+ * ```
153
+ * did not come → null, and `key` does NOT enter `malformed`. This is normal
154
+ * and documented: the schema itself says tx_hash is "null
155
+ * until the log scan reaches this entry, not null forever",
156
+ * and Solana writes feedback_hash NULL on purpose.
157
+ * came garbage → null AND `key` in `malformed`. THIS is the one that shouts.
158
+ * ```
159
+ *
160
+ * A caller therefore branches on the list, never on `field === null`.
161
+ *
162
+ * Why the value is dropped rather than passed through: the field exists so
163
+ * somebody can build an explorer link out of it, and a link built from garbage
164
+ * is the "200 that did not do the thing" arriving one layer later. Why it does
165
+ * not throw: the rest of the response is very likely useful, and killing a whole
166
+ * reputation breakdown over an accessory field would be worse than the bug being
167
+ * hunted. The original value is not lost — it stays in the result's `raw`, which
168
+ * is where it gets investigated.
169
+ *
170
+ * A non-string that is not `null`/`undefined` (a number, an object) counts as
171
+ * garbage, not as absence: the wire said something and it was not a hash.
172
+ */
173
+ export function hashField(
174
+ row: Record<string, unknown>,
175
+ key: string,
176
+ malformed: string[],
177
+ ok: (value: string) => boolean = looksLikeOnchainId,
178
+ ): string | null {
179
+ const value = row[key];
180
+ if (value === null || value === undefined) return null;
181
+ if (typeof value === 'string' && ok(value)) return value;
182
+ malformed.push(key);
183
+ return null;
184
+ }
185
+
186
+ /** Anything that carries the marks of its own malformed hash fields. */
187
+ interface MalformedCarrier {
188
+ malformedHashes?: readonly string[];
189
+ }
190
+
191
+ /**
192
+ * Every malformed hash field of a result, located.
193
+ *
194
+ * Walks the places a hash can hide in a parsed result and returns qualified
195
+ * paths, in the order they appear:
196
+ *
197
+ * ```ts
198
+ * ['ratings[3].tx_hash', 'snapshot.inputs_digest', 'payment.receipt']
199
+ * ```
200
+ *
201
+ * Wire names (`tx_hash`), not ours (`txHash`), on purpose: this string is what
202
+ * ends up in a log line or a ticket to whoever runs the index, and it has to
203
+ * name the field the way the API does.
204
+ *
205
+ * An empty array is the normal case and means "no field arrived malformed" — it
206
+ * says nothing about which fields arrived at all. An absent hash is legitimate
207
+ * and is not reported here.
208
+ */
209
+ export function malformedHashReport(
210
+ result:
211
+ | {
212
+ ratings?: readonly MalformedCarrier[];
213
+ snapshot?: MalformedCarrier | null;
214
+ payment?: MalformedCarrier | null;
215
+ }
216
+ | null
217
+ | undefined,
218
+ ): string[] {
219
+ if (!result) return [];
220
+ const fields: string[] = [];
221
+ (result.ratings ?? []).forEach((rating, i) => {
222
+ for (const name of rating.malformedHashes ?? []) fields.push(`ratings[${i}].${name}`);
223
+ });
224
+ for (const attr of ['snapshot', 'payment'] as const) {
225
+ const part = result[attr];
226
+ if (part) for (const name of part.malformedHashes ?? []) fields.push(`${attr}.${name}`);
227
+ }
228
+ return fields;
229
+ }
package/src/index.ts ADDED
@@ -0,0 +1,192 @@
1
+ /**
2
+ * uvd-describe-sdk — read reputation from describe.net.
3
+ *
4
+ * The ERC-8004 reputation index of Ultravioleta DAO, across 11 chains. Free
5
+ * lookups need no dependency and no credential; metered lookups pay their 402
6
+ * through `uvd-x402-sdk`, which lives behind the `uvd-describe-sdk/x402`
7
+ * subpath so a free-only consumer installs nothing.
8
+ *
9
+ * ```ts
10
+ * import { DescribeClient, formatScore } from 'uvd-describe-sdk';
11
+ *
12
+ * const describe = new DescribeClient({
13
+ * product: 'my-app',
14
+ * onFailure: (f) => console.warn('describe.net:', f.kind, f.path),
15
+ * });
16
+ *
17
+ * const rep = await describe.wallet('0x97cd…0996');
18
+ * if (rep === null) {
19
+ * // describe.net could not be reached. NOT "this wallet has no reputation".
20
+ * } else if (rep.globalScore === null) {
21
+ * // No eligible rating. That IS the answer — never render it as 0.
22
+ * } else {
23
+ * console.log(formatScore(rep.globalScore), rep.policyVersion, rep.caveats);
24
+ * }
25
+ * ```
26
+ *
27
+ * ## Three ways in, and only one of them costs anything
28
+ *
29
+ * Free routes need nothing. Metered routes are paid through `uvd-x402-sdk` via
30
+ * `uvd-describe-sdk/x402`, or read for FREE through `uvd-describe-sdk/partner`
31
+ * if your wallet is on describe.net's partner allowlist — a signature per
32
+ * request, no token, no secret held by the service. See `PartnerSigner`.
33
+ *
34
+ * ## The free routes degrade, the paid routes do not
35
+ *
36
+ * `wallet()`, `leaderboard()` and `health()` return `null` when describe.net
37
+ * cannot be reached (that is `failOpen`, on by default, always announced
38
+ * through `onFailure`). `walletBreakdown()` and `agent()` return no `null` at
39
+ * all and throw instead — including with `failOpen: true` — because between
40
+ * signing a payment and reading the answer there is a window where the USDC has
41
+ * already moved, and a `null` there hides a spend from the caller. Use
42
+ * `failedAfterPaying(error)` to tell "it broke before I paid" from "it broke
43
+ * after".
44
+ *
45
+ * ## Note on the public surface
46
+ *
47
+ * There is no function here that returns a bare score. `formatScore` takes a
48
+ * number you already pulled off a sealed result, and every result carries
49
+ * `policyVersion` and `caveats[]`. That is deliberate: *un score sin sus
50
+ * calificadores es un rumor*, and a `getScore(): number` would erase the reason
51
+ * the index exists. Reach into the object by hand — the friction is the point.
52
+ */
53
+
54
+ export { DescribeClient } from './client';
55
+ export type {
56
+ DescribeClientConfig,
57
+ DescribeFailure,
58
+ PartnerSigner,
59
+ X402Payer,
60
+ } from './client';
61
+
62
+ export {
63
+ DescribeError,
64
+ DescribeHTTPError,
65
+ /**
66
+ * 🔴 Exported to be RECOGNISED, never to be caught: it is never thrown. It
67
+ * arrives as the `error` of an `onFailure` notice whose `kind` is
68
+ * `malformed_hash`, saying a hash field was dropped because it was not a hash.
69
+ */
70
+ DescribeMalformedHash,
71
+ /**
72
+ * ⚠️ Exported since 2026-08-30 and it used to be deliberately absent: with the
73
+ * metered methods no longer nullable, a 404 on `walletBreakdown()` / `agent()`
74
+ * DOES reach the caller as a throw, so `instanceof` has to be possible. On the
75
+ * free routes it still never does.
76
+ */
77
+ DescribeNotFound,
78
+ /**
79
+ * The two partner-rail failures. Both are exported because both are meant to
80
+ * be caught by `instanceof`: `DescribePartnerUnsigned` is "fix your config",
81
+ * `DescribePartnerRejected` is "your free rail is off and we did NOT pay for
82
+ * you". Neither is ever swallowed by `failOpen`.
83
+ */
84
+ DescribePartnerRejected,
85
+ DescribePartnerUnsigned,
86
+ DescribePaymentRefused,
87
+ DescribePaymentRequired,
88
+ DescribeTimeout,
89
+ DescribeUnparseable,
90
+ DescribeUnreachable,
91
+ failedAfterPaying,
92
+ failOpenCovers,
93
+ } from './errors';
94
+ export type { DescribeErrorKind, PaymentAttempt, X402Challenge } from './errors';
95
+
96
+ /**
97
+ * The recovery table — what to do INSTEAD of the failure you are holding.
98
+ *
99
+ * Absorbed from **Execution Market** (`#agents`, 2026-08-30). Every
100
+ * `DescribeError` already carries its own text in `error.recovery`; the table
101
+ * is exported so a test can pin one without matching on prose, and so a router
102
+ * that has not failed yet can read the advice up front. `recoveryFor()` is the
103
+ * same lookup for a `kind` you hold without an instance.
104
+ *
105
+ * 🔴 Read it, never branch on it: `kind` is the enum.
106
+ */
107
+ export { RECOVERY, recoveryFor } from './recovery';
108
+ export type { RecoveryKey } from './recovery';
109
+
110
+ export {
111
+ CAVEAT_CODES,
112
+ CAVEAT_SCOPE_FREE,
113
+ CAVEAT_SCOPE_METERED,
114
+ hasCaveat,
115
+ isKnownCaveatCode,
116
+ } from './caveats';
117
+ export type { Caveat, CaveatCode, KnownCaveatCode } from './caveats';
118
+
119
+ export { formatScore, roundScore } from './format';
120
+
121
+ /**
122
+ * The distinct-rater helper, from MeshRelay. Read its docstring before using the
123
+ * number: summing the per-chain counts double-counts and taking the maximum
124
+ * underestimates, both measured, and this function does neither.
125
+ */
126
+ export { resolveDistinctRaters } from './raters';
127
+
128
+ /**
129
+ * The hash-shape contract, from KarmaKadabra's *"el 200 sin tx"*.
130
+ *
131
+ * Exported because the check belongs to the CONTRACT and not to each consumer —
132
+ * that was their whole point. `malformedHashReport` locates what a parsed result
133
+ * dropped; the two predicates are there for a payload you validate yourself.
134
+ */
135
+ export {
136
+ looksLikeOnchainId,
137
+ looksLikeSettlementReceipt,
138
+ malformedHashReport,
139
+ SETTLEMENT_PENDING,
140
+ } from './hashes';
141
+
142
+ export {
143
+ DEFAULT_BASE_URL,
144
+ DEFAULT_JITTER_MS,
145
+ DEFAULT_SITE_URL,
146
+ DEFAULT_TIMEOUT_MS,
147
+ PARTNER_CHAIN_ID,
148
+ PARTNER_KEY_ENV,
149
+ SDK_NAME,
150
+ SDK_VERSION,
151
+ TREASURY_EVM,
152
+ userAgent,
153
+ } from './config';
154
+
155
+ export type {
156
+ Activity,
157
+ AgentReputation,
158
+ Concentration,
159
+ Confidence,
160
+ Facet,
161
+ HealthChain,
162
+ IndexHealth,
163
+ LeaderboardRow,
164
+ Network,
165
+ Ownership,
166
+ PaymentEvidence,
167
+ Rating,
168
+ Sealed,
169
+ SelfRated,
170
+ Snapshot,
171
+ Timestamp,
172
+ WalletBreakdown,
173
+ WalletChainRow,
174
+ WalletReputation,
175
+ } from './types';
176
+
177
+ /**
178
+ * The parsers, exported for one reason: a consumer who already has a describe
179
+ * payload (from the MCP tools, the A2A gate, or a snapshot in their own
180
+ * database) can get the same typed shape without a second HTTP call.
181
+ *
182
+ * EM stores a snapshot in its own table and MeshRelay caches raw JSON — both
183
+ * re-derive shapes from stored payloads today. This is the seam that lets them
184
+ * stop.
185
+ */
186
+ export {
187
+ parseAgentReputation,
188
+ parseHealth,
189
+ parseLeaderboard,
190
+ parseWalletBreakdown,
191
+ parseWalletReputation,
192
+ } from './parse';
package/src/jitter.ts ADDED
@@ -0,0 +1,112 @@
1
+ /**
2
+ * A short random pause before a read, so a fleet does not arrive as one spike.
3
+ *
4
+ * ## Where this comes from, and what not having it cost
5
+ *
6
+ * Contributed by **KarmaKadabra**, `#agents` on MeshRelay, **2026-08-30**. They
7
+ * operate the largest fleet against this index — 27 agents — and their sentence
8
+ * is the whole specification:
9
+ *
10
+ * > *"27 agentes despiertan al MISMO tiempo por EventBridge y pegan simultáneo
11
+ * > contra su límite de rps COMPARTIDO con los otros consumidores. Sin jitter,
12
+ * > un enjambre es un DDoS educado."*
13
+ *
14
+ * They sleep `random.uniform(0, 0.4)` before every read
15
+ * (`karmakadabra/lib/reputation_scan.py:123`). Verified before writing a line:
16
+ * `grep -riE 'jitter|random|sleep' src/` in **both** SDKs returned zero hits on
17
+ * 2026-08-30. Neither of us had it.
18
+ *
19
+ * Two halves of what follows are theirs and two are ours, and the line matters
20
+ * because provenance is the reason to trust a number: **measured at
21
+ * KarmaKadabra** are the 0.4 s and the non-cryptographic uniform draw.
22
+ * **Designed here** are everything about it being a parameter at all — the
23
+ * default being ON, `0` switching it off, and a garbage value falling back to
24
+ * the default rather than to off. KarmaKadabra has no jitter option; they have
25
+ * a literal.
26
+ *
27
+ * The word that makes it the library's problem and not the fleet's is
28
+ * **COMPARTIDO**. describe.net's rate limit has no per-partner bucket (already
29
+ * written down in `config.ts`), so the agent that pays for an unjittered swarm
30
+ * is not the swarm's owner — it is the other consumer whose read gets the 429,
31
+ * and who has no lever to fix it. That is the shape of an externality, and a
32
+ * default that leaves the cost on someone with no lever is the wrong default.
33
+ *
34
+ * ## 🔴 Jitter is NOT backoff, and the day someone adds a retry this matters
35
+ *
36
+ * They look alike (both sleep) and they answer opposite questions. **Jitter
37
+ * disperses a herd that has not asked for anything yet**; it goes before a
38
+ * request and its size is about how many of us there are. **Backoff yields to a
39
+ * service that has already said no**; it goes before a RETRY and its size is
40
+ * about how hard it just refused. So a retry — this package has none,
41
+ * deliberately, see `client.ts` — takes backoff, never this.
42
+ *
43
+ * ## 🔴 It goes before EVERY request, not once per public call
44
+ *
45
+ * ⚠️ **This is a correction of the rule this file was first written with, and
46
+ * the old one is left here because it is the intuitive reading and the next
47
+ * person to touch this will want to "optimise" back to it.** The first version
48
+ * said *"once per public call, before the FIRST request"*. It sounds
49
+ * equivalent. It is not: a call that fires N requests would disperse one and
50
+ * let the other N−1 out in a pack — the exact problem this contribution came to
51
+ * fix, reintroduced through the back door.
52
+ *
53
+ * KarmaKadabra's own call site settles it, and it was read rather than assumed
54
+ * (2026-08-30): the sleep lives INSIDE `_scan_describenet()`, the function that
55
+ * performs the GET (`reputation_scan.py:123`), and that function runs **twice**
56
+ * on the real path — `:242` for the EVM address, `:245` for the Solana one. So
57
+ * their jitter is per REQUEST, and the reason they wrote next to it
58
+ * (`:121-122`) is per-PROCESS: it is anti-thundering-herd between agents that
59
+ * wake together against a shared ceiling, not a spacer inside one call.
60
+ *
61
+ * The paid replay sleeps too, and that is the same correction. It was going to
62
+ * be the one exception here, on the argument that delaying a signed envelope
63
+ * widens the window in which a crash loses a receipt. Measured against the
64
+ * numbers, that argument does not hold: the challenge this client answers
65
+ * carries `maxTimeoutSeconds: 120`, so 400 ms is a third of a percent of the
66
+ * envelope's own validity, while the herd argument applies to the replay in
67
+ * full — 27 agents that get their 402 in the same second replay in the same
68
+ * second. One rule with no exception, and nothing in the money path is
69
+ * measurably worse for it.
70
+ *
71
+ * ## 🔴 `Math.random`, and never `crypto.getRandomValues`
72
+ *
73
+ * This is dispersion, not a secret. Nothing about the delay needs to be
74
+ * unguessable: an adversary who predicts that this process will wait 213 ms
75
+ * learns nothing worth knowing, and cannot use it. Reaching for a CSPRNG here
76
+ * would be worse than useless — it tells the next reader that unpredictability
77
+ * is a security property of this value, which invites them to "harden" a
78
+ * sleep. `Math.random` is uniform enough for spreading arrivals, is available
79
+ * in every runtime this package targets (browser included), and costs nothing.
80
+ */
81
+
82
+ /**
83
+ * How long to wait, in milliseconds: a uniform draw from `[0, maxMs)`.
84
+ *
85
+ * Pure, so it is tested exhaustively without a clock. `random` is injectable for
86
+ * exactly that reason and for no other — production always passes `Math.random`.
87
+ *
88
+ * Garbage in gives the caller's own configured default nothing to stand on, so
89
+ * this function's contract is narrow: it clamps rather than throws. A `maxMs`
90
+ * that is not a finite positive number yields `0`, because a library that dies
91
+ * at read time over a mistyped option is worse than one that does not sleep.
92
+ * The decision about what a garbage OPTION means (fall back to the default, not
93
+ * to off) belongs one level up, in `DescribeClient` — see `jitterMs` there.
94
+ */
95
+ export function jitterDelayMs(maxMs: number, random: () => number = Math.random): number {
96
+ if (!Number.isFinite(maxMs) || maxMs <= 0) return 0;
97
+ const draw = random();
98
+ if (!Number.isFinite(draw) || draw < 0) return 0;
99
+ return Math.min(draw, 1) * maxMs;
100
+ }
101
+
102
+ /**
103
+ * The only timer in this package.
104
+ *
105
+ * `setTimeout` and not a busy loop, obviously — but also not `unref()`d: a
106
+ * process that exits while a read is pending would have dropped that read
107
+ * anyway, and `unref` is Node-only, which would break the browser target this
108
+ * package keeps.
109
+ */
110
+ export function sleep(ms: number): Promise<void> {
111
+ return new Promise((resolve) => setTimeout(resolve, ms));
112
+ }