uvd-describe-sdk 0.3.0 → 0.4.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/CHANGELOG.md +116 -0
- package/README.md +80 -4
- package/dist/{client-BMfgl1zP.d.mts → client-0sg4J53x.d.mts} +256 -23
- package/dist/{client-BMfgl1zP.d.ts → client-0sg4J53x.d.ts} +256 -23
- package/dist/{config-DzzhWFYr.d.mts → config-gjJ08BUJ.d.mts} +1 -1
- package/dist/{config-DzzhWFYr.d.ts → config-gjJ08BUJ.d.ts} +1 -1
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +95 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +92 -3
- package/dist/index.mjs.map +1 -1
- package/dist/partner/index.d.mts +2 -2
- package/dist/partner/index.d.ts +2 -2
- package/dist/partner/index.js.map +1 -1
- package/dist/partner/index.mjs.map +1 -1
- package/dist/x402/index.d.mts +1 -1
- package/dist/x402/index.d.ts +1 -1
- package/package.json +2 -1
- package/src/caveats.ts +297 -21
- package/src/config.ts +1 -1
- package/src/index.ts +16 -1
- package/src/parse.ts +42 -0
- package/src/types.ts +50 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Newest first. A version listed here is a version on `main`, **not** a version on
|
|
4
|
+
npm: publishing is a `vX.Y.Z` tag, and the tag is pushed by whoever releases,
|
|
5
|
+
never by the change that bumps the number.
|
|
6
|
+
|
|
7
|
+
This file starts at 0.4.0. The versions before it are summarised from their
|
|
8
|
+
commits, so they are shorter than they deserve — `git log` has the measurements.
|
|
9
|
+
|
|
10
|
+
## 0.4.1 — 2026-09-15 (not published yet)
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **`CAVEAT_CODES` gains `thin-chain`** (ten codes, the same set describe.net
|
|
15
|
+
serves). Served since 2026-09-04 on the wallet scope, and evaluated on the free
|
|
16
|
+
route as well: `GET /wallets/{wallet}/chains` evaluates `burn-address` and
|
|
17
|
+
`thin-chain`, and declares the other seven wallet-scope codes in
|
|
18
|
+
`caveatsNotComputed`. `isKnownCaveatCode('thin-chain')` is now `true`. The
|
|
19
|
+
Python twin adds the same literal in its own release.
|
|
20
|
+
|
|
21
|
+
### Unchanged, on purpose
|
|
22
|
+
|
|
23
|
+
- Types, parsers, the client and `requireFullCaveats()` behave exactly as in
|
|
24
|
+
0.4.0. A `thin-chain` caveat already arrived whole; this release only makes it
|
|
25
|
+
a known code (autocomplete, `switch`, `isKnownCaveatCode`).
|
|
26
|
+
|
|
27
|
+
## 0.4.0 — 2026-09-15 (not published yet)
|
|
28
|
+
|
|
29
|
+
Types what describe.net has served since 2026-09-14 (`describe-net` PR #21,
|
|
30
|
+
deployed in `aa1bd75`). Upstream-first: this version exists so that Execution
|
|
31
|
+
Market, KarmaKadabra, MeshRelay and karma-hello adopt the fields through the SDK
|
|
32
|
+
instead of reading them by hand. The Python twin (`uvd-describe-sdk` 0.6.0) ships
|
|
33
|
+
the same contract in its own spelling — same states, same refusals, same class
|
|
34
|
+
name for the error. The one intended difference is the wording of that error's
|
|
35
|
+
`recovery`, which names each language's own API.
|
|
36
|
+
|
|
37
|
+
### Breaking — only for code that builds these objects by hand
|
|
38
|
+
|
|
39
|
+
- `WalletReputation.caveatsNotComputed` and `Rating.authorClass` are
|
|
40
|
+
**required** properties. An object literal typed as `WalletReputation`,
|
|
41
|
+
`Rating`, or `AgentReputation` (through `ratings`) that compiled against 0.3.0
|
|
42
|
+
no longer compiles against 0.4.0: `TS2741: Property 'caveatsNotComputed' is
|
|
43
|
+
missing` / `Property 'authorClass' is missing` (measured with `tsc --strict`).
|
|
44
|
+
Typically a test fixture or a mock. Fix: add the two fields, or build the
|
|
45
|
+
object from a payload with `parseWalletReputation()` / `parseAgentReputation()`,
|
|
46
|
+
which fill them.
|
|
47
|
+
- If you have nothing to put there, write `null` in both — never `[]`, which
|
|
48
|
+
claims every cut was evaluated, and never `'rater-authored'`, which claims a
|
|
49
|
+
signer the index cannot vouch for.
|
|
50
|
+
- They stay required on purpose, and what the parsers return is unchanged.
|
|
51
|
+
Making them optional would add a fourth state, `undefined`, to every result
|
|
52
|
+
of `wallet()` and `agent()`, next to the three (`[]`, a list, `null`) this
|
|
53
|
+
version exists to keep apart.
|
|
54
|
+
- Code that only reads what the client or the parsers return is not affected.
|
|
55
|
+
|
|
56
|
+
### Added
|
|
57
|
+
|
|
58
|
+
- **`WalletReputation.caveatsNotComputed: CaveatCode[] | null`** — the caveat
|
|
59
|
+
codes `GET /wallets/{wallet}/chains` did NOT evaluate (seven on 2026-09-15).
|
|
60
|
+
`null` means nothing readable was declared (a server older than 2026-09-14, a
|
|
61
|
+
stored payload, or a value that is not a list of non-empty strings) and is
|
|
62
|
+
deliberately **not** `[]`, which is a declaration.
|
|
63
|
+
- **`requireFullCaveats(rep)`** — returns `rep` only when it declared `[]`;
|
|
64
|
+
throws `CaveatsNotComputedError` for a declared list AND for `null`; throws a
|
|
65
|
+
`TypeError` for anything that is not the `WalletReputation` of `wallet()`
|
|
66
|
+
(a metered result, a `null` response, a raw payload).
|
|
67
|
+
- **`CaveatsNotComputedError`** (`wallet`, `notComputed`, `recovery`). Extends
|
|
68
|
+
`Error`, **not** `DescribeError`: a consumer's fail-open `catch` on
|
|
69
|
+
`DescribeError` must not be able to swallow a refusal as an outage.
|
|
70
|
+
- **`Rating.authorClass: AuthorClass | null`** — `facilitator-authored` or
|
|
71
|
+
`rater-authored`, per row. An unknown class arrives verbatim (never thrown,
|
|
72
|
+
never nulled); `null` means none was served.
|
|
73
|
+
- **`AUTHOR_CLASSES`, `isKnownAuthorClass()`, `AuthorClass`, `KnownAuthorClass`.**
|
|
74
|
+
- **`CAVEAT_CODES` gains `facilitator-authored`** (nine codes).
|
|
75
|
+
|
|
76
|
+
### Known gap
|
|
77
|
+
|
|
78
|
+
- describe.net serves ten caveat codes; **`thin-chain`** (upstream since
|
|
79
|
+
2026-09-04, on the free route since 2026-09-05) is still missing here and in
|
|
80
|
+
the Python twin. Left for one follow-up that adds it to both, so the set both
|
|
81
|
+
SDKs publish never differs. `isKnownCaveatCode('thin-chain')` is `false`; the
|
|
82
|
+
caveat itself still arrives whole.
|
|
83
|
+
|
|
84
|
+
### Changed
|
|
85
|
+
|
|
86
|
+
- `schema/openapi.snapshot.json` refreshed from the live API (2.0.0, 22 paths:
|
|
87
|
+
`GET /categories` and `GET /wallets/{wallet}/exists` are new and not wrapped).
|
|
88
|
+
- `npm run schema:check` now also watches `Rating`, and `types.schema.test.ts`
|
|
89
|
+
covers it. Neither did before, which is how `author_class` becoming a required
|
|
90
|
+
field upstream went unreported by the refresh.
|
|
91
|
+
|
|
92
|
+
### Unchanged, on purpose
|
|
93
|
+
|
|
94
|
+
- No method changed its return type (the types it returns gained two required
|
|
95
|
+
fields — see *Breaking*), nothing throws where it did not, and
|
|
96
|
+
`DescribeErrorKind` is untouched. The client never calls the gate; `failOpen`
|
|
97
|
+
and `onFailure` behave exactly as in 0.3.0.
|
|
98
|
+
|
|
99
|
+
## 0.3.0 — 2026-09-10
|
|
100
|
+
|
|
101
|
+
`freshness`: WHEN a subject was last described, with its scope
|
|
102
|
+
(`WalletBreakdown.freshness`, `IndexHealth.freshness`), plus
|
|
103
|
+
`IndexHealth.credibilityM`. (#1, `764cab1`)
|
|
104
|
+
|
|
105
|
+
## 0.2.0 — 2026-08-31
|
|
106
|
+
|
|
107
|
+
The SDK review round: the `pending` settlement sentinel moved out of `receipt`
|
|
108
|
+
into `settlementPending`, `DescribeHTTPError.serverReason`, and parsers that fail
|
|
109
|
+
loud when fed the wrong route's payload or their own output. (`923a9d6`)
|
|
110
|
+
|
|
111
|
+
## 0.1.0 — 2026-08-30
|
|
112
|
+
|
|
113
|
+
First version: the free routes with `failOpen`, the metered routes paid through
|
|
114
|
+
`uvd-describe-sdk/x402` (and, the same day, never failing open), the partner rail,
|
|
115
|
+
jitter, `resolveDistinctRaters`, hash-shape validation and `recovery`.
|
|
116
|
+
(`99a87b2` … `8deb0c9`)
|
package/README.md
CHANGED
|
@@ -119,16 +119,65 @@ if (hasCaveat(rep, 'burn-address')) { /* nobody controls this address */ }
|
|
|
119
119
|
if (hasCaveat(rep, 'few-raters')) { /* thin evidence */ }
|
|
120
120
|
```
|
|
121
121
|
|
|
122
|
-
The
|
|
122
|
+
The ten codes are exported and typed: `no-score`, `concentration-degraded`,
|
|
123
123
|
`single-rater`, `few-raters`, `top-client-share`, `campaign-per-rater`,
|
|
124
|
-
`self-rated`, `burn-address
|
|
125
|
-
|
|
124
|
+
`self-rated`, `burn-address`, `thin-chain` (since 0.4.1; served since 2026-09-04,
|
|
125
|
+
on the free route too), `facilitator-authored` (since 0.4.0). The union stays
|
|
126
|
+
**open**, so a code the server adds tomorrow will not be a type error in code you
|
|
127
|
+
already shipped: `isKnownCaveatCode()` answers `false` for it, and the caveat
|
|
128
|
+
still arrives whole.
|
|
126
129
|
|
|
127
130
|
⚠️ On free routes `caveats: []` means *no **public-data** caveat*, not "clean" —
|
|
128
131
|
the evidence-quality cuts need the grain and ride the metered routes. Check
|
|
129
132
|
`rep.caveatScope` (`public-data-subset` vs `full`) before calling anything
|
|
130
133
|
clean.
|
|
131
134
|
|
|
135
|
+
**Since 0.4.0 the free route names the cuts it skipped, and there is a gate for
|
|
136
|
+
it.** karma-hello found the trap (2026-08-31): a quality gate on `wallet()`
|
|
137
|
+
passes *every* wallet, because the cuts it checks never ran. describe.net now
|
|
138
|
+
declares them in `caveats_not_computed` (`rep.caveatsNotComputed`), and
|
|
139
|
+
`requireFullCaveats` is the gate that reads the declaration:
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
import { CaveatsNotComputedError, requireFullCaveats } from 'uvd-describe-sdk';
|
|
143
|
+
|
|
144
|
+
const rep = await describe.wallet(w);
|
|
145
|
+
if (rep === null) { /* no answer at all: decide that first */ }
|
|
146
|
+
|
|
147
|
+
try {
|
|
148
|
+
requireFullCaveats(rep);
|
|
149
|
+
} catch (e) {
|
|
150
|
+
if (e instanceof CaveatsNotComputedError) {
|
|
151
|
+
e.notComputed; // ['campaign-per-rater', …] — or null: nothing was declared
|
|
152
|
+
e.recovery; // the route that does evaluate them
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
| `rep.caveatsNotComputed` | `requireFullCaveats(rep)` |
|
|
158
|
+
|---|---|
|
|
159
|
+
| `[]` | returns `rep` — the only state that passes |
|
|
160
|
+
| `['few-raters', …]` | throws; `notComputed` is the list |
|
|
161
|
+
| `null` — a server before 2026-09-14, a payload stored before then, or a declaration that cannot be read whole | **throws**; `notComputed` is `null` |
|
|
162
|
+
|
|
163
|
+
🔴 **Today it throws for every free answer** (seven codes declared on
|
|
164
|
+
2026-09-15). That is the gate working: the evidence-quality cuts are what
|
|
165
|
+
`walletBreakdown()` sells, and a decision that needs them reads that — or the
|
|
166
|
+
partner rail. `null` is not `[]`: an old answer's silence is the old gap, not a
|
|
167
|
+
clean bill (describe.net's position of 2026-08-31 is *"el scope es la señal"*,
|
|
168
|
+
and its own MCP tool keeps the same `None`). Passing means the caveats are
|
|
169
|
+
**complete**, not empty — ask `hasCaveat()` after the gate.
|
|
170
|
+
|
|
171
|
+
Two things it is not, on purpose — and the Python twin (`require_full_caveats`,
|
|
172
|
+
`CaveatsNotComputedError`) makes the same two choices:
|
|
173
|
+
|
|
174
|
+
* **Not a `DescribeError`.** A refusal is a successful read that does not support
|
|
175
|
+
the decision. A `catch` that fails open on `DescribeError` must not be able to
|
|
176
|
+
read it as "describe is down" and wave the subject through.
|
|
177
|
+
* **Not for metered results.** It takes the `WalletReputation` of `wallet()` and
|
|
178
|
+
throws a `TypeError` for anything else: a breakdown evaluates its own scope and
|
|
179
|
+
declares no omissions.
|
|
180
|
+
|
|
132
181
|
### 4. One display format, ecosystem-wide
|
|
133
182
|
|
|
134
183
|
**Two decimals, trailing zeros trimmed.** `86.65`, `84.7`, `87` — never `82.0`.
|
|
@@ -548,6 +597,33 @@ and an alarm that screams about good data is worse than no alarm.
|
|
|
548
597
|
|
|
549
598
|
---
|
|
550
599
|
|
|
600
|
+
## Who signed a rating: `authorClass`
|
|
601
|
+
|
|
602
|
+
Since describe.net 2026-09-14 every row of `agent().ratings` carries the class of
|
|
603
|
+
whoever **signed** it:
|
|
604
|
+
|
|
605
|
+
```ts
|
|
606
|
+
const agent = await describe.agent('base', 42);
|
|
607
|
+
const relayed = agent.ratings.filter((r) => r.authorClass === 'facilitator-authored');
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
* `facilitator-authored` — `client` is a known relayer (today the x402
|
|
611
|
+
facilitator's EVM wallet) writing on behalf of the real rater. `client` is
|
|
612
|
+
**not** the counterparty, and every such row shares it, so any per-rater count
|
|
613
|
+
merges them into one voice. The agent answer then also carries the caveat of
|
|
614
|
+
the same name.
|
|
615
|
+
* `rater-authored` — `client` is not a relayer the index knows about. It does
|
|
616
|
+
**not** prove who signed.
|
|
617
|
+
* `null` — no class was served (an older server, or a stored payload). Unknown,
|
|
618
|
+
and never defaulted to `rater-authored`.
|
|
619
|
+
|
|
620
|
+
The union is **open**: a class the server adds later arrives verbatim — never
|
|
621
|
+
thrown, never nulled — and `isKnownAuthorClass()` tells you whether this SDK has
|
|
622
|
+
heard of it. There is no count or score by author class, upstream or here; what
|
|
623
|
+
to do with the rows you bought is your call.
|
|
624
|
+
|
|
625
|
+
---
|
|
626
|
+
|
|
551
627
|
## Counting distinct raters
|
|
552
628
|
|
|
553
629
|
```ts
|
|
@@ -650,7 +726,7 @@ cycle.
|
|
|
650
726
|
|
|
651
727
|
```bash
|
|
652
728
|
npm install
|
|
653
|
-
npm test # offline.
|
|
729
|
+
npm test # offline, no network. 227 tests on 2026-09-15
|
|
654
730
|
npm run typecheck
|
|
655
731
|
npm run lint
|
|
656
732
|
npm run build
|
|
@@ -524,40 +524,60 @@ declare function failedAfterPaying(error: unknown): error is DescribeError & {
|
|
|
524
524
|
* string comparison kept returning false and nobody was told.
|
|
525
525
|
*
|
|
526
526
|
* Exporting the set is one of the four "día 0" requirements the platform team
|
|
527
|
-
* put on any SDK of the house
|
|
528
|
-
* contrato exportado*. Typing them here means a consumer never re-types them,
|
|
527
|
+
* put on any SDK of the house: *los caveat `code`s como contrato exportado*. Typing them here means a consumer never re-types them,
|
|
529
528
|
* and a typo is a compile error rather than a branch that is never taken.
|
|
530
529
|
*
|
|
531
530
|
* ## Why the type is not a closed union
|
|
532
531
|
*
|
|
533
|
-
* `CaveatCode | (string & {})` gives autocomplete on the
|
|
534
|
-
*
|
|
535
|
-
*
|
|
536
|
-
*
|
|
537
|
-
*
|
|
538
|
-
*
|
|
539
|
-
*
|
|
532
|
+
* `CaveatCode | (string & {})` gives autocomplete on the codes that exist today
|
|
533
|
+
* AND still accepts one more the server adds tomorrow. A closed union would turn
|
|
534
|
+
* every new server-side code into a type error in code that is already deployed
|
|
535
|
+
* and working — the passthrough rule (tipar lo conocido, CONSERVAR lo que no)
|
|
536
|
+
* applied to the type system. The measured precedent is `Facet.direction`:
|
|
537
|
+
* FastAPI silently dropped a field nobody had declared, and the response looked
|
|
538
|
+
* correct with the data missing.
|
|
540
539
|
*
|
|
541
540
|
* The codes carry no version and never bump `POLICY_VERSION`: a caveat is
|
|
542
541
|
* advisory by construction and identifies a CUT, it never moves a score.
|
|
543
542
|
*/
|
|
543
|
+
|
|
544
544
|
/**
|
|
545
|
-
* The
|
|
546
|
-
* `describenet/caveats.py:
|
|
547
|
-
* `tests/test_caveat_codes.py` pins literally, so adding or
|
|
548
|
-
* there goes red on purpose
|
|
549
|
-
*
|
|
550
|
-
*
|
|
551
|
-
*
|
|
552
|
-
*
|
|
553
|
-
*
|
|
545
|
+
* The ten cuts describe.net serves on 2026-09-15, copied from the frozen set in
|
|
546
|
+
* `describenet/caveats.py:177-192` (describe-net `origin/main` at `4fd11c0`),
|
|
547
|
+
* which its own `tests/test_caveat_codes.py` pins literally, so adding or
|
|
548
|
+
* renaming one over there goes red on purpose. Same order as upstream.
|
|
549
|
+
*
|
|
550
|
+
* What the FREE route evaluates, per the server itself (`caveats.py:513`,
|
|
551
|
+
* `_publicos_evaluados`): `burn-address` always, and `thin-chain` when it has the
|
|
552
|
+
* per-chain rows — which `GET /wallets/{wallet}/chains` always has. Every other
|
|
553
|
+
* wallet-scope code is DECLARED as not evaluated, by name, in
|
|
554
|
+
* `WalletReputation.caveatsNotComputed`. `facilitator-authored` is agent scope
|
|
555
|
+
* and is in neither: a wallet profile lists no rows. An empty `caveats: []` on a
|
|
556
|
+
* free response therefore still means "no public-data caveat", NOT "clean" — and
|
|
557
|
+
* `requireFullCaveats()` is the gate that knows it. See `CAVEAT_SCOPE_FREE`.
|
|
558
|
+
*
|
|
559
|
+
* `thin-chain` (upstream since 2026-09-04, `cf8f806`; on the free route since
|
|
560
|
+
* 2026-09-05) is mirrored since 0.4.1, added to both twins together so the set
|
|
561
|
+
* both SDKs publish never differs. 0.4.0 shipped nine and knew it: until then
|
|
562
|
+
* `isKnownCaveatCode('thin-chain')` answered `false`, and the caveat still
|
|
563
|
+
* arrived whole — the tolerant answer this module was built to give.
|
|
564
|
+
*
|
|
565
|
+
* ⚠️ CORRECTED 2026-09-15, and the old text is left because somebody will look
|
|
566
|
+
* for it. It read: *"The eight cuts served on 2026-08-30, copied from the frozen
|
|
567
|
+
* set in `describenet/caveats.py:172-183` … Only `no-score` and `burn-address`
|
|
568
|
+
* are computable from public data, so the free routes serve a documented SUBSET
|
|
569
|
+
* … The other six need the grain and ride the metered routes."* Two codes had
|
|
570
|
+
* landed upstream since and this mirror carried neither; `facilitator-authored`
|
|
571
|
+
* (`6e25d71`, 2026-09-14) was mirrored in 0.4.0, `thin-chain` in 0.4.1. And
|
|
572
|
+
* `no-score` is not evaluated on the free route at all: the server declares it
|
|
573
|
+
* in the list.
|
|
554
574
|
*/
|
|
555
|
-
declare const CAVEAT_CODES: readonly ["no-score", "concentration-degraded", "single-rater", "few-raters", "top-client-share", "campaign-per-rater", "self-rated", "burn-address"];
|
|
556
|
-
/** The
|
|
575
|
+
declare const CAVEAT_CODES: readonly ["no-score", "concentration-degraded", "single-rater", "few-raters", "top-client-share", "campaign-per-rater", "self-rated", "burn-address", "thin-chain", "facilitator-authored"];
|
|
576
|
+
/** The known codes as a union — for `switch`, not for validation. */
|
|
557
577
|
type KnownCaveatCode = (typeof CAVEAT_CODES)[number];
|
|
558
578
|
/**
|
|
559
|
-
* What a caveat's `code` may be:
|
|
560
|
-
*
|
|
579
|
+
* What a caveat's `code` may be: a known one, or any string the server starts
|
|
580
|
+
* sending. The `(string & {})` half is what keeps autocomplete alive
|
|
561
581
|
* while leaving the union open.
|
|
562
582
|
*/
|
|
563
583
|
type CaveatCode = KnownCaveatCode | (string & {});
|
|
@@ -597,6 +617,170 @@ declare function isKnownCaveatCode(code: string): code is KnownCaveatCode;
|
|
|
597
617
|
declare function hasCaveat(subject: {
|
|
598
618
|
caveats?: readonly Caveat[];
|
|
599
619
|
} | null | undefined, code: CaveatCode): boolean;
|
|
620
|
+
/**
|
|
621
|
+
* `requireFullCaveats()` refused: this answer does not vouch for every cut.
|
|
622
|
+
*
|
|
623
|
+
* ## 🔴 NOT a `DescribeError`, and that is the decision
|
|
624
|
+
*
|
|
625
|
+
* `DescribeError` is the failure taxonomy — transport and protocol, "we could
|
|
626
|
+
* not read" — and consumers wrap it in their own fail-open:
|
|
627
|
+
* `catch (e) { if (e instanceof DescribeError) return null; }`. A refusal caught
|
|
628
|
+
* there degrades into "describe.net is down", and a gate built to tolerate
|
|
629
|
+
* outages lets the subject THROUGH: the same silent green the 2026-08-31 row
|
|
630
|
+
* exists to stop. This is not a failure to read; it is a successful read that
|
|
631
|
+
* does not support the decision being asked of it. So it extends `Error`, carries
|
|
632
|
+
* no `kind`, `transient` or `serviceFault`, and `failOpenCovers()` and
|
|
633
|
+
* `failedAfterPaying()` both answer `false` for it.
|
|
634
|
+
*
|
|
635
|
+
* Decided by the Python twin the same night (`CaveatsNotComputedError`,
|
|
636
|
+
* `uvd_describe_sdk/caveats.py`) and adopted here for parity. The first draft of
|
|
637
|
+
* this package made it a `DescribeError` with a new `kind`; the argument above is
|
|
638
|
+
* why that was the wrong door — and it would also have broken, at compile time,
|
|
639
|
+
* every exhaustive `switch` over `DescribeErrorKind`.
|
|
640
|
+
*
|
|
641
|
+
* ## `notComputed` — branch on it, never on the message
|
|
642
|
+
*
|
|
643
|
+
* ```
|
|
644
|
+
* ['few-raters', …] the answer DECLARED these unevaluated: unverified, not passed
|
|
645
|
+
* null the answer declared NOTHING — a server older than
|
|
646
|
+
* 2026-09-14, or a payload stored before then. Not `[]`.
|
|
647
|
+
* ```
|
|
648
|
+
*
|
|
649
|
+
* A declared `[]` never reaches this class: it passes the gate.
|
|
650
|
+
*/
|
|
651
|
+
declare class CaveatsNotComputedError extends Error {
|
|
652
|
+
/**
|
|
653
|
+
* What to do INSTEAD, as a frozen literal that interpolates nothing — the
|
|
654
|
+
* redaction rule of `recovery.ts` (invariant 11), without being an entry of
|
|
655
|
+
* that table, because this is not a `kind`. Same text on the class and on
|
|
656
|
+
* every instance.
|
|
657
|
+
*
|
|
658
|
+
* ⚠️ Not byte-identical to the Python twin's, and that is declared rather than
|
|
659
|
+
* hidden: theirs names `wallet_breakdown()`, `payer=`, `partner=` and
|
|
660
|
+
* `fallback_reader`, which are Python spellings. This one names what both SDKs
|
|
661
|
+
* share — the route, and the two ways through it.
|
|
662
|
+
*/
|
|
663
|
+
static readonly recovery: string;
|
|
664
|
+
/** Same literal as {@link CaveatsNotComputedError.recovery}, on the instance. */
|
|
665
|
+
readonly recovery: string;
|
|
666
|
+
/** The wallet whose answer was refused, as served. */
|
|
667
|
+
readonly wallet: string;
|
|
668
|
+
/** A COPY of what the answer declared, or `null` if it declared nothing. */
|
|
669
|
+
readonly notComputed: string[] | null;
|
|
670
|
+
constructor(message: string, opts: {
|
|
671
|
+
wallet: string;
|
|
672
|
+
notComputed: readonly string[] | null;
|
|
673
|
+
});
|
|
674
|
+
}
|
|
675
|
+
/**
|
|
676
|
+
* Return `result` only if its answer DECLARED it left no caveat code out.
|
|
677
|
+
*
|
|
678
|
+
* ```ts
|
|
679
|
+
* const rep = await describe.wallet(address);
|
|
680
|
+
* if (rep === null) { … } // no answer at all: decide THAT first
|
|
681
|
+
* requireFullCaveats(rep); // throws CaveatsNotComputedError
|
|
682
|
+
* ```
|
|
683
|
+
*
|
|
684
|
+
* ## The bug it closes, found by karma-hello
|
|
685
|
+
*
|
|
686
|
+
* A quality gate built on the FREE route passes everybody (karma-hello, channel,
|
|
687
|
+
* 2026-08-31; `describe-net/docs/BACKLOG.md:221`). The evidence-quality cuts —
|
|
688
|
+
* `single-rater`, `few-raters`, `campaign-per-rater`, … — are computed only by
|
|
689
|
+
* the paid decomposition, so on `GET /wallets/{wallet}/chains`
|
|
690
|
+
* `hasCaveat(rep, 'single-rater')` is `false` for every wallet, the one with a
|
|
691
|
+
* single rater included. Honest code, and a gate that cannot fail anyone.
|
|
692
|
+
*
|
|
693
|
+
* Since 2026-09-14 the free answer DECLARES the names it did not evaluate
|
|
694
|
+
* (`WalletReputation.caveatsNotComputed`), and the server names this very helper
|
|
695
|
+
* as the reason the declaration is a list and not a count
|
|
696
|
+
* (`describenet/caveats.py:493-494`: *"el SDK puede ofrecer
|
|
697
|
+
* `require_full_caveats()` sin tabla propia"*). No table of our own here either:
|
|
698
|
+
* the verdict is read off the answer, never off a list typed in this package.
|
|
699
|
+
*
|
|
700
|
+
* ## Three states, and only one passes
|
|
701
|
+
*
|
|
702
|
+
* ```
|
|
703
|
+
* caveatsNotComputed = [] → returns `result`, the same object
|
|
704
|
+
* caveatsNotComputed = ['…', …] → throws; `error.notComputed` is the list
|
|
705
|
+
* caveatsNotComputed = null → throws; `error.notComputed` is null
|
|
706
|
+
* ```
|
|
707
|
+
*
|
|
708
|
+
* 🔴 **Against the live index this throws for every `wallet()` today** —
|
|
709
|
+
* measured 2026-09-15: the same seven codes for a wallet with 471 distinct raters
|
|
710
|
+
* and for one with no identity at all. That is the gate working: the free route
|
|
711
|
+
* does not evaluate the evidence-quality cuts, and a decision that needs them has
|
|
712
|
+
* to buy `walletBreakdown()` (or read it over the partner rail). What changes is
|
|
713
|
+
* that the gate can no longer find that out by passing.
|
|
714
|
+
*
|
|
715
|
+
* ## 🔴 Why `null` THROWS — the decision, and its sources
|
|
716
|
+
*
|
|
717
|
+
* - The position of 2026-08-31, written in `describe-net/docs/BACKLOG.md:221`:
|
|
718
|
+
* *"la línea gratis/pago es regla de costo y **el scope es la señal**; el SDK
|
|
719
|
+
* puede ganar `require_full_caveats()`"*. That row is about a gate that goes
|
|
720
|
+
* green without knowing what was not computed. A `null` that passes is that
|
|
721
|
+
* gate, back — silently, on every old deployment and every stored payload.
|
|
722
|
+
* - The service refuses the same collapse on its own side: its MCP tool carries
|
|
723
|
+
* `None` *"cuando la API no lo trae: una API vieja no declaró nada, y `[]`
|
|
724
|
+
* afirmaría que lo calculó todo"* (`describenet/mcp_server.py:896-901`).
|
|
725
|
+
* - Before 2026-09-14 the free route did not evaluate those cuts either; it only
|
|
726
|
+
* did not SAY so (`caveatScope: 'public-data-subset'` was the whole signal). An
|
|
727
|
+
* old answer's silence is the old gap, not a clean bill.
|
|
728
|
+
*
|
|
729
|
+
* ## It takes a `WalletReputation`, and nothing else
|
|
730
|
+
*
|
|
731
|
+
* The one result that declares what it did not compute. Anything else is a
|
|
732
|
+
* `TypeError` naming the mistake — never a pass, and never the refusal above:
|
|
733
|
+
*
|
|
734
|
+
* - `null` is "describe.net did not answer", the third absence (invariant 3).
|
|
735
|
+
* Handle it before asking about caveats.
|
|
736
|
+
* - A `WalletBreakdown` or an `AgentReputation` comes from a metered route, which
|
|
737
|
+
* evaluates its own caveat scope and declares no omissions: there is nothing
|
|
738
|
+
* here for this gate to read.
|
|
739
|
+
* - A raw wire payload (snake_case) was never parsed: `parseWalletReputation()`.
|
|
740
|
+
*
|
|
741
|
+
* Never called by the client and never swallowed by `failOpen`. And passing
|
|
742
|
+
* means the caveats are COMPLETE, not that they are empty — `hasCaveat()` is
|
|
743
|
+
* still the question after the gate.
|
|
744
|
+
*/
|
|
745
|
+
declare function requireFullCaveats(result: WalletReputation): WalletReputation;
|
|
746
|
+
/**
|
|
747
|
+
* The two classes served in `ratings[].author_class` since describe.net
|
|
748
|
+
* 2026-09-14 — the schema's own enum (`describenet/api.py:962`,
|
|
749
|
+
* `Literal["facilitator-authored", "rater-authored"]`), and
|
|
750
|
+
* `types.schema.test.ts` pins this tuple against the snapshot's `enum`. The
|
|
751
|
+
* Python twin calls the same set `KNOWN_AUTHOR_CLASSES`, the way it calls
|
|
752
|
+
* `CAVEAT_CODES` `KNOWN_CAVEAT_CODES`.
|
|
753
|
+
*
|
|
754
|
+
* They live next to the caveat codes because one of them IS one: the agent-scope
|
|
755
|
+
* caveat `facilitator-authored` fires exactly when some row carries that class
|
|
756
|
+
* (`describenet/caveats.py:614`, which reads the field instead of recomputing it,
|
|
757
|
+
* so the two cannot disagree inside one answer).
|
|
758
|
+
*/
|
|
759
|
+
declare const AUTHOR_CLASSES: readonly ["facilitator-authored", "rater-authored"];
|
|
760
|
+
/** The known classes as a union — for `switch`, not for validation. */
|
|
761
|
+
type KnownAuthorClass = (typeof AUTHOR_CLASSES)[number];
|
|
762
|
+
/**
|
|
763
|
+
* What `Rating.authorClass` may be: a known class, or any string the server
|
|
764
|
+
* starts sending.
|
|
765
|
+
*
|
|
766
|
+
* Open, not closed, and recording that decision is why this type exists. The
|
|
767
|
+
* server's enum is closed TODAY; a third class there is a new contract on their
|
|
768
|
+
* side and must not become a type error — or worse, a thrown parse — on ours. A
|
|
769
|
+
* parser that rejected it would destroy a PAID read over one advisory field; one
|
|
770
|
+
* that nulled it would read as "no class served". So it arrives verbatim and
|
|
771
|
+
* `isKnownAuthorClass()` says whether this SDK has heard of it: the `CaveatCode`
|
|
772
|
+
* rule, applied one field over.
|
|
773
|
+
*/
|
|
774
|
+
type AuthorClass = KnownAuthorClass | (string & {});
|
|
775
|
+
/**
|
|
776
|
+
* Is this one of the author classes this SDK knows?
|
|
777
|
+
*
|
|
778
|
+
* NOT a validator, same as `isKnownCaveatCode`: `false` means "newer than this
|
|
779
|
+
* SDK" — or, for `null`, a row served before 2026-09-14 that carries no class at
|
|
780
|
+
* all. Neither is invalid. Before filtering rows on it, decide what an unknown
|
|
781
|
+
* class means for YOUR count; this SDK will not decide that for you.
|
|
782
|
+
*/
|
|
783
|
+
declare function isKnownAuthorClass(value: string | null | undefined): value is KnownAuthorClass;
|
|
600
784
|
|
|
601
785
|
/**
|
|
602
786
|
* The wire shapes — hand-written, and here is the argument for that.
|
|
@@ -784,6 +968,34 @@ interface WalletReputation extends Sealed {
|
|
|
784
968
|
chainsWithIdentity: number;
|
|
785
969
|
chainsWithReputation: number;
|
|
786
970
|
totalReviews: number;
|
|
971
|
+
/**
|
|
972
|
+
* The caveat codes that the paid decomposition evaluates and THIS free answer
|
|
973
|
+
* did not — sorted, served since describe.net 2026-09-14
|
|
974
|
+
* (`describenet/caveats.py:525-532`, `not_computed_public`, derived from the
|
|
975
|
+
* same module that builds `caveats`). **Names, never outcomes**: whether any of
|
|
976
|
+
* them fires for this wallet is exactly what stays paid.
|
|
977
|
+
*
|
|
978
|
+
* Seven codes on 2026-09-15, for a wallet with 471 raters and for `0xdead…beef`
|
|
979
|
+
* alike — the declaration depends on what the route evaluates, not on the
|
|
980
|
+
* subject. Read it live; the count is not a constant.
|
|
981
|
+
*
|
|
982
|
+
* 🔴 **Three states, and they stay three:**
|
|
983
|
+
*
|
|
984
|
+
* ```
|
|
985
|
+
* ['few-raters', …] NOT evaluated here — read each one as UNVERIFIED, never as passed
|
|
986
|
+
* [] the answer says it evaluated every wallet-scope cut
|
|
987
|
+
* null nothing readable was declared: a server older than 2026-09-14,
|
|
988
|
+
* a payload stored before then, or a value that is not a list
|
|
989
|
+
* of non-empty strings. NOT `[]` — nothing was promised, and
|
|
990
|
+
* `caveatScope` still says what was evaluated
|
|
991
|
+
* ```
|
|
992
|
+
*
|
|
993
|
+
* The failure this field closes is karma-hello's (2026-08-31): a quality gate
|
|
994
|
+
* built on this route passed every wallet, because `caveats: []` here is the
|
|
995
|
+
* silence of cuts that were never run. Do not gate on it by hand —
|
|
996
|
+
* `requireFullCaveats()` is the gate, and it reads the `null` correctly.
|
|
997
|
+
*/
|
|
998
|
+
caveatsNotComputed: CaveatCode[] | null;
|
|
787
999
|
}
|
|
788
1000
|
/** How lopsided the evidence is. `null` when there is not enough to say. */
|
|
789
1001
|
interface Concentration {
|
|
@@ -954,6 +1166,27 @@ interface WalletBreakdown extends Sealed {
|
|
|
954
1166
|
*/
|
|
955
1167
|
interface Rating {
|
|
956
1168
|
client: string;
|
|
1169
|
+
/**
|
|
1170
|
+
* Who SIGNED this row, as a class — served since describe.net 2026-09-14
|
|
1171
|
+
* (`describenet/api.py:962`, `rating_roles.author_class_of`).
|
|
1172
|
+
*
|
|
1173
|
+
* - `facilitator-authored` — `client` is a known relayer (today the x402
|
|
1174
|
+
* facilitator's EVM wallet) that wrote the rating on behalf of the real
|
|
1175
|
+
* rater. **`client` is NOT the counterparty**: every such row shares one
|
|
1176
|
+
* `client`, so any per-rater count — `concentration.distinctRaters`,
|
|
1177
|
+
* `topClientShare` — merges all of them into one voice. Filter on this
|
|
1178
|
+
* before reading `client` as "who rated".
|
|
1179
|
+
* - `rater-authored` — `client` is not a relayer the index knows about. 🔴 It
|
|
1180
|
+
* does NOT prove who signed; it is the absence of a known relayer.
|
|
1181
|
+
* - `null` — no class was served (a server older than 2026-09-14, or a stored
|
|
1182
|
+
* payload). Unknown, and deliberately NOT defaulted to `rater-authored`:
|
|
1183
|
+
* that would assert the one thing the index says it cannot.
|
|
1184
|
+
*
|
|
1185
|
+
* An unknown string arrives VERBATIM — the union is open, like `CaveatCode`,
|
|
1186
|
+
* and `isKnownAuthorClass()` says whether this SDK has heard of it. Per row
|
|
1187
|
+
* only: neither the index nor this SDK computes any score or count by class.
|
|
1188
|
+
*/
|
|
1189
|
+
authorClass: AuthorClass | null;
|
|
957
1190
|
feedbackIndex: number;
|
|
958
1191
|
value: number;
|
|
959
1192
|
valueDecimals: number;
|
|
@@ -1674,4 +1907,4 @@ declare class DescribeClient {
|
|
|
1674
1907
|
private assertPayableTo;
|
|
1675
1908
|
}
|
|
1676
1909
|
|
|
1677
|
-
export { type AgentReputation as A, type
|
|
1910
|
+
export { isKnownAuthorClass as $, type AgentReputation as A, type FreshnessScope as B, CAVEAT_CODES as C, type DescribeErrorKind as D, type KnownCaveatCode as E, type Facet as F, type PartnerSigner as G, type HealthChain as H, type IndexHealth as I, type PaymentAttempt as J, type KnownAuthorClass as K, type LeaderboardRow as L, type SelfRated as M, type Network as N, type Ownership as O, type PaymentEvidence as P, type Snapshot as Q, type Rating as R, type Sealed as S, type Timestamp as T, type WalletChainRow as U, type X402Payer as V, type WalletBreakdown as W, type X402Challenge as X, failOpenCovers as Y, failedAfterPaying as Z, hasCaveat as _, type WalletReputation as a, isKnownCaveatCode as a0, requireFullCaveats as a1, AUTHOR_CLASSES as b, type Activity as c, type AuthorClass as d, CAVEAT_SCOPE_FREE as e, CAVEAT_SCOPE_METERED as f, type Caveat as g, type CaveatCode as h, CaveatsNotComputedError as i, type Concentration as j, type Confidence as k, DescribeClient as l, type DescribeClientConfig as m, DescribeError as n, type DescribeFailure as o, DescribeHTTPError as p, DescribeMalformedHash as q, DescribeNotFound as r, DescribePartnerRejected as s, DescribePartnerUnsigned as t, DescribePaymentRefused as u, DescribePaymentRequired as v, DescribeTimeout as w, DescribeUnparseable as x, DescribeUnreachable as y, type Freshness as z };
|