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/src/caveats.ts CHANGED
@@ -15,34 +15,55 @@
15
15
  * string comparison kept returning false and nobody was told.
16
16
  *
17
17
  * Exporting the set is one of the four "día 0" requirements the platform team
18
- * put on any SDK of the house (`D9-c0der.md:234-241`): *los caveat `code`s como
19
- * contrato exportado*. Typing them here means a consumer never re-types them,
18
+ * put on any SDK of the house: *los caveat `code`s como contrato exportado*. Typing them here means a consumer never re-types them,
20
19
  * and a typo is a compile error rather than a branch that is never taken.
21
20
  *
22
21
  * ## Why the type is not a closed union
23
22
  *
24
- * `CaveatCode | (string & {})` gives autocomplete on the eight codes that exist
25
- * today AND still accepts a ninth one the server adds tomorrow. A closed union
26
- * would turn every new server-side code into a type error in code that is
27
- * already deployed and working — the passthrough rule (tipar lo conocido,
28
- * CONSERVAR lo que no) applied to the type system. The measured precedent is
29
- * `Facet.direction`: FastAPI silently dropped a field nobody had declared, and
30
- * the response looked correct with the data missing.
23
+ * `CaveatCode | (string & {})` gives autocomplete on the codes that exist today
24
+ * AND still accepts one more the server adds tomorrow. A closed union would turn
25
+ * every new server-side code into a type error in code that is already deployed
26
+ * and working — the passthrough rule (tipar lo conocido, CONSERVAR lo que no)
27
+ * applied to the type system. The measured precedent is `Facet.direction`:
28
+ * FastAPI silently dropped a field nobody had declared, and the response looked
29
+ * correct with the data missing.
31
30
  *
32
31
  * The codes carry no version and never bump `POLICY_VERSION`: a caveat is
33
32
  * advisory by construction and identifies a CUT, it never moves a score.
34
33
  */
35
34
 
35
+ import type { WalletReputation } from './types';
36
+
36
37
  /**
37
- * The eight cuts served on 2026-08-30, copied from the frozen set in
38
- * `describenet/caveats.py:172-183` (which its own
39
- * `tests/test_caveat_codes.py` pins literally, so adding or renaming one over
40
- * there goes red on purpose).
41
- *
42
- * Only `no-score` and `burn-address` are computable from public data, so the
43
- * free routes serve a documented SUBSET — an empty `caveats: []` on a free
44
- * response means "no public-data caveat", NOT "clean". The other six need the
45
- * grain and ride the metered routes. See `CAVEAT_SCOPE_FREE`.
38
+ * The ten cuts describe.net serves on 2026-09-15, copied from the frozen set in
39
+ * `describenet/caveats.py:177-192` (describe-net `origin/main` at `4fd11c0`),
40
+ * which its own `tests/test_caveat_codes.py` pins literally, so adding or
41
+ * renaming one over there goes red on purpose. Same order as upstream.
42
+ *
43
+ * What the FREE route evaluates, per the server itself (`caveats.py:513`,
44
+ * `_publicos_evaluados`): `burn-address` always, and `thin-chain` when it has the
45
+ * per-chain rows — which `GET /wallets/{wallet}/chains` always has. Every other
46
+ * wallet-scope code is DECLARED as not evaluated, by name, in
47
+ * `WalletReputation.caveatsNotComputed`. `facilitator-authored` is agent scope
48
+ * and is in neither: a wallet profile lists no rows. An empty `caveats: []` on a
49
+ * free response therefore still means "no public-data caveat", NOT "clean" — and
50
+ * `requireFullCaveats()` is the gate that knows it. See `CAVEAT_SCOPE_FREE`.
51
+ *
52
+ * `thin-chain` (upstream since 2026-09-04, `cf8f806`; on the free route since
53
+ * 2026-09-05) is mirrored since 0.4.1, added to both twins together so the set
54
+ * both SDKs publish never differs. 0.4.0 shipped nine and knew it: until then
55
+ * `isKnownCaveatCode('thin-chain')` answered `false`, and the caveat still
56
+ * arrived whole — the tolerant answer this module was built to give.
57
+ *
58
+ * ⚠️ CORRECTED 2026-09-15, and the old text is left because somebody will look
59
+ * for it. It read: *"The eight cuts served on 2026-08-30, copied from the frozen
60
+ * set in `describenet/caveats.py:172-183` … Only `no-score` and `burn-address`
61
+ * are computable from public data, so the free routes serve a documented SUBSET
62
+ * … The other six need the grain and ride the metered routes."* Two codes had
63
+ * landed upstream since and this mirror carried neither; `facilitator-authored`
64
+ * (`6e25d71`, 2026-09-14) was mirrored in 0.4.0, `thin-chain` in 0.4.1. And
65
+ * `no-score` is not evaluated on the free route at all: the server declares it
66
+ * in the list.
46
67
  */
47
68
  export const CAVEAT_CODES = [
48
69
  /** No score to qualify: there is no eligible rating at all. */
@@ -65,14 +86,32 @@ export const CAVEAT_CODES = [
65
86
  * — which is why they are still served — but the subject is not an identity.
66
87
  */
67
88
  'burn-address',
89
+ /**
90
+ * At least one of two or more scored chains rests on fewer than
91
+ * `reading_policy.min_raters` distinct raters. Its weight in the global score
92
+ * is small but never zero, so it still moves the number: read the per-chain
93
+ * composition before the global. Never fires on a single chain — there the
94
+ * weight cancels and `single-rater` / `few-raters` already say it. Wallet
95
+ * scope, and evaluated on the FREE route too (from `chains[]`). Since
96
+ * 2026-09-04; mirrored since 0.4.1.
97
+ */
98
+ 'thin-chain',
99
+ /**
100
+ * Some rows of `ratings[]` carry `authorClass: 'facilitator-authored'`: a
101
+ * relayer signed them, so their `client` is not the counterparty and every
102
+ * per-rater count merges them into one voice. AGENT scope only — the one
103
+ * metered answer that lists rows — and it carries no numbers, on purpose: the
104
+ * aggregate by author was cancelled upstream on 2026-08-29. Since 2026-09-14.
105
+ */
106
+ 'facilitator-authored',
68
107
  ] as const;
69
108
 
70
- /** The eight known codes as a union — for `switch`, not for validation. */
109
+ /** The known codes as a union — for `switch`, not for validation. */
71
110
  export type KnownCaveatCode = (typeof CAVEAT_CODES)[number];
72
111
 
73
112
  /**
74
- * What a caveat's `code` may be: one of the eight, or any string the server
75
- * starts sending. The `(string & {})` half is what keeps autocomplete alive
113
+ * What a caveat's `code` may be: a known one, or any string the server starts
114
+ * sending. The `(string & {})` half is what keeps autocomplete alive
76
115
  * while leaving the union open.
77
116
  */
78
117
  export type CaveatCode = KnownCaveatCode | (string & {});
@@ -122,3 +161,240 @@ export function hasCaveat(
122
161
  ): boolean {
123
162
  return (subject?.caveats ?? []).some((c) => c.code === code);
124
163
  }
164
+
165
+ // ---------------------------------------------------------------------------
166
+ // The gate — added 2026-09-15 (0.4.0)
167
+ // ---------------------------------------------------------------------------
168
+
169
+ /**
170
+ * `requireFullCaveats()` refused: this answer does not vouch for every cut.
171
+ *
172
+ * ## 🔴 NOT a `DescribeError`, and that is the decision
173
+ *
174
+ * `DescribeError` is the failure taxonomy — transport and protocol, "we could
175
+ * not read" — and consumers wrap it in their own fail-open:
176
+ * `catch (e) { if (e instanceof DescribeError) return null; }`. A refusal caught
177
+ * there degrades into "describe.net is down", and a gate built to tolerate
178
+ * outages lets the subject THROUGH: the same silent green the 2026-08-31 row
179
+ * exists to stop. This is not a failure to read; it is a successful read that
180
+ * does not support the decision being asked of it. So it extends `Error`, carries
181
+ * no `kind`, `transient` or `serviceFault`, and `failOpenCovers()` and
182
+ * `failedAfterPaying()` both answer `false` for it.
183
+ *
184
+ * Decided by the Python twin the same night (`CaveatsNotComputedError`,
185
+ * `uvd_describe_sdk/caveats.py`) and adopted here for parity. The first draft of
186
+ * this package made it a `DescribeError` with a new `kind`; the argument above is
187
+ * why that was the wrong door — and it would also have broken, at compile time,
188
+ * every exhaustive `switch` over `DescribeErrorKind`.
189
+ *
190
+ * ## `notComputed` — branch on it, never on the message
191
+ *
192
+ * ```
193
+ * ['few-raters', …] the answer DECLARED these unevaluated: unverified, not passed
194
+ * null the answer declared NOTHING — a server older than
195
+ * 2026-09-14, or a payload stored before then. Not `[]`.
196
+ * ```
197
+ *
198
+ * A declared `[]` never reaches this class: it passes the gate.
199
+ */
200
+ export class CaveatsNotComputedError extends Error {
201
+ /**
202
+ * What to do INSTEAD, as a frozen literal that interpolates nothing — the
203
+ * redaction rule of `recovery.ts` (invariant 11), without being an entry of
204
+ * that table, because this is not a `kind`. Same text on the class and on
205
+ * every instance.
206
+ *
207
+ * ⚠️ Not byte-identical to the Python twin's, and that is declared rather than
208
+ * hidden: theirs names `wallet_breakdown()`, `payer=`, `partner=` and
209
+ * `fallback_reader`, which are Python spellings. This one names what both SDKs
210
+ * share — the route, and the two ways through it.
211
+ */
212
+ static readonly recovery: string =
213
+ 'What this free answer did not evaluate is what the metered decomposition sells: ' +
214
+ '`GET /reputation/wallet/{wallet}` evaluates the wallet-scope cuts this error lists — paid ' +
215
+ "per call with x402, or free for a wallet on describe.net's partner allowlist. If the error " +
216
+ 'lists nothing, the answer declared nothing (a server older than 2026-09-14, or a payload ' +
217
+ 'stored before then), and that is not a pass either: the decomposition is still the route ' +
218
+ 'that evaluates them.';
219
+
220
+ /** Same literal as {@link CaveatsNotComputedError.recovery}, on the instance. */
221
+ readonly recovery: string = CaveatsNotComputedError.recovery;
222
+ /** The wallet whose answer was refused, as served. */
223
+ readonly wallet: string;
224
+ /** A COPY of what the answer declared, or `null` if it declared nothing. */
225
+ readonly notComputed: string[] | null;
226
+
227
+ constructor(message: string, opts: { wallet: string; notComputed: readonly string[] | null }) {
228
+ super(message);
229
+ this.name = 'CaveatsNotComputedError';
230
+ this.wallet = opts.wallet;
231
+ this.notComputed = opts.notComputed === null ? null : [...opts.notComputed];
232
+ }
233
+ }
234
+
235
+ /**
236
+ * Is this the object `wallet()` / `parseWalletReputation()` returns?
237
+ *
238
+ * By KEYS, the way `parse.ts` tells the doors apart (rule 5): `globalScore` is
239
+ * only ever in a parsed free answer, `finalScore` only in a parsed breakdown,
240
+ * `agentId` only in a parsed agent. `caveatsNotComputed` is deliberately NOT
241
+ * required — a result parsed by 0.3.0 and stored has no such key, and that is an
242
+ * undeclared answer (refused as such), not a wrong argument.
243
+ */
244
+ function isWalletReputation(v: unknown): v is WalletReputation {
245
+ if (typeof v !== 'object' || v === null || Array.isArray(v)) return false;
246
+ return (
247
+ typeof (v as { wallet?: unknown }).wallet === 'string' &&
248
+ 'globalScore' in v &&
249
+ !('finalScore' in v) &&
250
+ !('agentId' in v)
251
+ );
252
+ }
253
+
254
+ /**
255
+ * Return `result` only if its answer DECLARED it left no caveat code out.
256
+ *
257
+ * ```ts
258
+ * const rep = await describe.wallet(address);
259
+ * if (rep === null) { … } // no answer at all: decide THAT first
260
+ * requireFullCaveats(rep); // throws CaveatsNotComputedError
261
+ * ```
262
+ *
263
+ * ## The bug it closes, found by karma-hello
264
+ *
265
+ * A quality gate built on the FREE route passes everybody (karma-hello, channel,
266
+ * 2026-08-31; `describe-net/docs/BACKLOG.md:221`). The evidence-quality cuts —
267
+ * `single-rater`, `few-raters`, `campaign-per-rater`, … — are computed only by
268
+ * the paid decomposition, so on `GET /wallets/{wallet}/chains`
269
+ * `hasCaveat(rep, 'single-rater')` is `false` for every wallet, the one with a
270
+ * single rater included. Honest code, and a gate that cannot fail anyone.
271
+ *
272
+ * Since 2026-09-14 the free answer DECLARES the names it did not evaluate
273
+ * (`WalletReputation.caveatsNotComputed`), and the server names this very helper
274
+ * as the reason the declaration is a list and not a count
275
+ * (`describenet/caveats.py:493-494`: *"el SDK puede ofrecer
276
+ * `require_full_caveats()` sin tabla propia"*). No table of our own here either:
277
+ * the verdict is read off the answer, never off a list typed in this package.
278
+ *
279
+ * ## Three states, and only one passes
280
+ *
281
+ * ```
282
+ * caveatsNotComputed = [] → returns `result`, the same object
283
+ * caveatsNotComputed = ['…', …] → throws; `error.notComputed` is the list
284
+ * caveatsNotComputed = null → throws; `error.notComputed` is null
285
+ * ```
286
+ *
287
+ * 🔴 **Against the live index this throws for every `wallet()` today** —
288
+ * measured 2026-09-15: the same seven codes for a wallet with 471 distinct raters
289
+ * and for one with no identity at all. That is the gate working: the free route
290
+ * does not evaluate the evidence-quality cuts, and a decision that needs them has
291
+ * to buy `walletBreakdown()` (or read it over the partner rail). What changes is
292
+ * that the gate can no longer find that out by passing.
293
+ *
294
+ * ## 🔴 Why `null` THROWS — the decision, and its sources
295
+ *
296
+ * - The position of 2026-08-31, written in `describe-net/docs/BACKLOG.md:221`:
297
+ * *"la línea gratis/pago es regla de costo y **el scope es la señal**; el SDK
298
+ * puede ganar `require_full_caveats()`"*. That row is about a gate that goes
299
+ * green without knowing what was not computed. A `null` that passes is that
300
+ * gate, back — silently, on every old deployment and every stored payload.
301
+ * - The service refuses the same collapse on its own side: its MCP tool carries
302
+ * `None` *"cuando la API no lo trae: una API vieja no declaró nada, y `[]`
303
+ * afirmaría que lo calculó todo"* (`describenet/mcp_server.py:896-901`).
304
+ * - Before 2026-09-14 the free route did not evaluate those cuts either; it only
305
+ * did not SAY so (`caveatScope: 'public-data-subset'` was the whole signal). An
306
+ * old answer's silence is the old gap, not a clean bill.
307
+ *
308
+ * ## It takes a `WalletReputation`, and nothing else
309
+ *
310
+ * The one result that declares what it did not compute. Anything else is a
311
+ * `TypeError` naming the mistake — never a pass, and never the refusal above:
312
+ *
313
+ * - `null` is "describe.net did not answer", the third absence (invariant 3).
314
+ * Handle it before asking about caveats.
315
+ * - A `WalletBreakdown` or an `AgentReputation` comes from a metered route, which
316
+ * evaluates its own caveat scope and declares no omissions: there is nothing
317
+ * here for this gate to read.
318
+ * - A raw wire payload (snake_case) was never parsed: `parseWalletReputation()`.
319
+ *
320
+ * Never called by the client and never swallowed by `failOpen`. And passing
321
+ * means the caveats are COMPLETE, not that they are empty — `hasCaveat()` is
322
+ * still the question after the gate.
323
+ */
324
+ export function requireFullCaveats(result: WalletReputation): WalletReputation {
325
+ if (!isWalletReputation(result)) {
326
+ throw new TypeError(
327
+ 'requireFullCaveats() takes the WalletReputation that wallet() returns. A null means ' +
328
+ 'describe.net did NOT answer — handle that before asking about caveats. A WalletBreakdown ' +
329
+ 'or an AgentReputation comes from a metered route, which evaluates its own caveat scope ' +
330
+ 'and declares no omissions. A raw payload goes through parseWalletReputation() first.',
331
+ );
332
+ }
333
+ // `Array.isArray`, not a null check: anything that is not a list is not a
334
+ // declaration (the parser already maps it to `null`), and a stored 0.3.0
335
+ // result has no key at all — both are undeclared, both refused as such.
336
+ const declared: unknown = result.caveatsNotComputed;
337
+ if (!Array.isArray(declared)) {
338
+ throw new CaveatsNotComputedError(
339
+ `the answer for ${result.wallet} did not declare which caveat codes it left out (no ` +
340
+ '`caveats_not_computed`): a server older than 2026-09-14, or a payload stored before ' +
341
+ 'then. Undeclared is not `[]`, so this gate does not pass.',
342
+ { wallet: result.wallet, notComputed: null },
343
+ );
344
+ }
345
+ if (declared.length === 0) return result;
346
+ const codes = declared.map(String);
347
+ throw new CaveatsNotComputedError(
348
+ `the answer for ${result.wallet} declares ${codes.length} caveat code(s) it did not ` +
349
+ `compute: ${codes.join(', ')}. Unverified, not passed.`,
350
+ { wallet: result.wallet, notComputed: codes },
351
+ );
352
+ }
353
+
354
+ // ---------------------------------------------------------------------------
355
+ // Author classes — who SIGNED a rating row. Added 2026-09-15 (0.4.0)
356
+ // ---------------------------------------------------------------------------
357
+
358
+ /**
359
+ * The two classes served in `ratings[].author_class` since describe.net
360
+ * 2026-09-14 — the schema's own enum (`describenet/api.py:962`,
361
+ * `Literal["facilitator-authored", "rater-authored"]`), and
362
+ * `types.schema.test.ts` pins this tuple against the snapshot's `enum`. The
363
+ * Python twin calls the same set `KNOWN_AUTHOR_CLASSES`, the way it calls
364
+ * `CAVEAT_CODES` `KNOWN_CAVEAT_CODES`.
365
+ *
366
+ * They live next to the caveat codes because one of them IS one: the agent-scope
367
+ * caveat `facilitator-authored` fires exactly when some row carries that class
368
+ * (`describenet/caveats.py:614`, which reads the field instead of recomputing it,
369
+ * so the two cannot disagree inside one answer).
370
+ */
371
+ export const AUTHOR_CLASSES = ['facilitator-authored', 'rater-authored'] as const;
372
+
373
+ /** The known classes as a union — for `switch`, not for validation. */
374
+ export type KnownAuthorClass = (typeof AUTHOR_CLASSES)[number];
375
+
376
+ /**
377
+ * What `Rating.authorClass` may be: a known class, or any string the server
378
+ * starts sending.
379
+ *
380
+ * Open, not closed, and recording that decision is why this type exists. The
381
+ * server's enum is closed TODAY; a third class there is a new contract on their
382
+ * side and must not become a type error — or worse, a thrown parse — on ours. A
383
+ * parser that rejected it would destroy a PAID read over one advisory field; one
384
+ * that nulled it would read as "no class served". So it arrives verbatim and
385
+ * `isKnownAuthorClass()` says whether this SDK has heard of it: the `CaveatCode`
386
+ * rule, applied one field over.
387
+ */
388
+ export type AuthorClass = KnownAuthorClass | (string & {});
389
+
390
+ /**
391
+ * Is this one of the author classes this SDK knows?
392
+ *
393
+ * NOT a validator, same as `isKnownCaveatCode`: `false` means "newer than this
394
+ * SDK" — or, for `null`, a row served before 2026-09-14 that carries no class at
395
+ * all. Neither is invalid. Before filtering rows on it, decide what an unknown
396
+ * class means for YOUR count; this SDK will not decide that for you.
397
+ */
398
+ export function isKnownAuthorClass(value: string | null | undefined): value is KnownAuthorClass {
399
+ return (AUTHOR_CLASSES as readonly unknown[]).includes(value);
400
+ }
package/src/config.ts CHANGED
@@ -146,7 +146,7 @@ export const PARTNER_KEY_ENV = 'DESCRIBE_PARTNER_PRIVATE_KEY';
146
146
  * time instead of at runtime. Bumping the version without the constant is a
147
147
  * red test, not a silent lie in someone's access log.
148
148
  */
149
- export const SDK_VERSION = '0.3.0';
149
+ export const SDK_VERSION = '0.4.1';
150
150
 
151
151
  /** `uvd-describe-sdk-ts/0.1.0`, plus `(+<product>)` when the caller names itself. */
152
152
  export const SDK_NAME = 'uvd-describe-sdk-ts';
package/src/index.ts CHANGED
@@ -107,14 +107,29 @@ export type { DescribeErrorKind, PaymentAttempt, X402Challenge } from './errors'
107
107
  export { RECOVERY, recoveryFor } from './recovery';
108
108
  export type { RecoveryKey } from './recovery';
109
109
 
110
+ /**
111
+ * The caveat contract. Since 0.4.0 it also carries the two halves describe.net
112
+ * shipped on 2026-09-14: `requireFullCaveats()` — the gate that can fail a free
113
+ * answer which did not evaluate the evidence-quality cuts — and the author
114
+ * classes of `Rating.authorClass`.
115
+ *
116
+ * 🔴 `CaveatsNotComputedError` is exported HERE and not with the errors above,
117
+ * on purpose: it is not a `DescribeError`. A refusal of the gate is a successful
118
+ * read that does not support the decision, and a `catch` that fails open on
119
+ * `DescribeError` must not be able to swallow it.
120
+ */
110
121
  export {
122
+ AUTHOR_CLASSES,
111
123
  CAVEAT_CODES,
112
124
  CAVEAT_SCOPE_FREE,
113
125
  CAVEAT_SCOPE_METERED,
126
+ CaveatsNotComputedError,
114
127
  hasCaveat,
128
+ isKnownAuthorClass,
115
129
  isKnownCaveatCode,
130
+ requireFullCaveats,
116
131
  } from './caveats';
117
- export type { Caveat, CaveatCode, KnownCaveatCode } from './caveats';
132
+ export type { AuthorClass, Caveat, CaveatCode, KnownAuthorClass, KnownCaveatCode } from './caveats';
118
133
 
119
134
  export { formatScore, roundScore } from './format';
120
135
 
package/src/parse.ts CHANGED
@@ -131,6 +131,39 @@ function parseCaveats(v: unknown): Caveat[] {
131
131
  return out;
132
132
  }
133
133
 
134
+ /**
135
+ * `caveats_not_computed` → the declared list, or `null` when nothing readable
136
+ * was declared. Added 2026-09-15 (0.4.0).
137
+ *
138
+ * `null` and `[]` are different facts and this function exists to keep them
139
+ * apart: `[]` is a DECLARATION ("evaluated everything") and the one value that
140
+ * makes `requireFullCaveats()` pass; `null` is a server that did not declare
141
+ * (older than 2026-09-14) or a stored payload from before then. A `?? []` here
142
+ * would turn every undeclared answer into a pass.
143
+ *
144
+ * 🔴 **A declaration that cannot be read WHOLE is not a declaration**, so every
145
+ * shape that is not a list of non-empty strings is `null` — never a filtered
146
+ * list. The asymmetry with `parseCaveats`, which drops a bad entry and keeps the
147
+ * rest, is deliberate: there a dropped entry loses one warning; here it can turn
148
+ * `[null]` into `[]`, the value that opens the gate. Failing closed means reading
149
+ * garbage as "undeclared", which the gate refuses. That covers the bare count
150
+ * floated on 2026-08-31 and rejected upstream for a list, too.
151
+ *
152
+ * It never throws: the field is a footnote to a read that otherwise arrived
153
+ * fine, and on a free route a throw becomes the fail-open `null` — the whole
154
+ * reputation lost over its footnote. Same rule, same shapes, as the Python twin's
155
+ * `models.py::_parse_not_computed`.
156
+ */
157
+ function parseNotComputed(v: unknown): string[] | null {
158
+ if (!Array.isArray(v)) return null;
159
+ const codes: string[] = [];
160
+ for (const item of v) {
161
+ if (typeof item !== 'string' || item === '') return null;
162
+ codes.push(item);
163
+ }
164
+ return codes;
165
+ }
166
+
134
167
  function parseFacets(v: unknown): Record<string, Facet> {
135
168
  if (!isObj(v)) return {};
136
169
  const out: Record<string, Facet> = {};
@@ -267,6 +300,13 @@ function parseRatings(v: unknown): Rating[] {
267
300
  const malformed: string[] = [];
268
301
  return {
269
302
  client: String(r.client ?? ''),
303
+ // Tolerant on purpose, the `isKnownCaveatCode` pattern: a class this SDK
304
+ // has not heard of arrives verbatim, never thrown (one advisory field
305
+ // must not destroy a paid read) and never nulled (dropping it would read
306
+ // as "no class served"). Only a non-string or an empty string is `null`:
307
+ // there is nothing to keep (the Python twin's `_author_class`, same rule).
308
+ authorClass:
309
+ typeof r.author_class === 'string' && r.author_class !== '' ? r.author_class : null,
270
310
  feedbackIndex: num(r.feedback_index),
271
311
  value: num(r.value),
272
312
  valueDecimals: num(r.value_decimals),
@@ -344,6 +384,8 @@ export function parseWalletReputation(payload: unknown): WalletReputation {
344
384
  chainsWithIdentity: num(payload.chains_with_identity),
345
385
  chainsWithReputation: num(payload.chains_with_reputation),
346
386
  totalReviews: num(payload.total_reviews),
387
+ // `null` when absent or unreadable — NEVER `[]`. See `parseNotComputed`.
388
+ caveatsNotComputed: parseNotComputed(payload.caveats_not_computed),
347
389
  policyVersion: optString(payload.policy_version),
348
390
  caveats: parseCaveats(payload.caveats),
349
391
  caveatScope: CAVEAT_SCOPE_FREE,
package/src/types.ts CHANGED
@@ -42,7 +42,7 @@
42
42
  * nothing about which happened.
43
43
  */
44
44
 
45
- import type { Caveat } from './caveats';
45
+ import type { AuthorClass, Caveat, CaveatCode } from './caveats';
46
46
 
47
47
  /** The eleven indexed chains are strings on the wire. Never an enum here: the index adds chains. */
48
48
  export type Network = string;
@@ -196,6 +196,34 @@ export interface WalletReputation extends Sealed {
196
196
  chainsWithIdentity: number;
197
197
  chainsWithReputation: number;
198
198
  totalReviews: number;
199
+ /**
200
+ * The caveat codes that the paid decomposition evaluates and THIS free answer
201
+ * did not — sorted, served since describe.net 2026-09-14
202
+ * (`describenet/caveats.py:525-532`, `not_computed_public`, derived from the
203
+ * same module that builds `caveats`). **Names, never outcomes**: whether any of
204
+ * them fires for this wallet is exactly what stays paid.
205
+ *
206
+ * Seven codes on 2026-09-15, for a wallet with 471 raters and for `0xdead…beef`
207
+ * alike — the declaration depends on what the route evaluates, not on the
208
+ * subject. Read it live; the count is not a constant.
209
+ *
210
+ * 🔴 **Three states, and they stay three:**
211
+ *
212
+ * ```
213
+ * ['few-raters', …] NOT evaluated here — read each one as UNVERIFIED, never as passed
214
+ * [] the answer says it evaluated every wallet-scope cut
215
+ * null nothing readable was declared: a server older than 2026-09-14,
216
+ * a payload stored before then, or a value that is not a list
217
+ * of non-empty strings. NOT `[]` — nothing was promised, and
218
+ * `caveatScope` still says what was evaluated
219
+ * ```
220
+ *
221
+ * The failure this field closes is karma-hello's (2026-08-31): a quality gate
222
+ * built on this route passed every wallet, because `caveats: []` here is the
223
+ * silence of cuts that were never run. Do not gate on it by hand —
224
+ * `requireFullCaveats()` is the gate, and it reads the `null` correctly.
225
+ */
226
+ caveatsNotComputed: CaveatCode[] | null;
199
227
  }
200
228
 
201
229
  // ---------------------------------------------------------------------------
@@ -381,6 +409,27 @@ export interface WalletBreakdown extends Sealed {
381
409
  */
382
410
  export interface Rating {
383
411
  client: string;
412
+ /**
413
+ * Who SIGNED this row, as a class — served since describe.net 2026-09-14
414
+ * (`describenet/api.py:962`, `rating_roles.author_class_of`).
415
+ *
416
+ * - `facilitator-authored` — `client` is a known relayer (today the x402
417
+ * facilitator's EVM wallet) that wrote the rating on behalf of the real
418
+ * rater. **`client` is NOT the counterparty**: every such row shares one
419
+ * `client`, so any per-rater count — `concentration.distinctRaters`,
420
+ * `topClientShare` — merges all of them into one voice. Filter on this
421
+ * before reading `client` as "who rated".
422
+ * - `rater-authored` — `client` is not a relayer the index knows about. 🔴 It
423
+ * does NOT prove who signed; it is the absence of a known relayer.
424
+ * - `null` — no class was served (a server older than 2026-09-14, or a stored
425
+ * payload). Unknown, and deliberately NOT defaulted to `rater-authored`:
426
+ * that would assert the one thing the index says it cannot.
427
+ *
428
+ * An unknown string arrives VERBATIM — the union is open, like `CaveatCode`,
429
+ * and `isKnownAuthorClass()` says whether this SDK has heard of it. Per row
430
+ * only: neither the index nor this SDK computes any score or count by class.
431
+ */
432
+ authorClass: AuthorClass | null;
384
433
  feedbackIndex: number;
385
434
  value: number;
386
435
  valueDecimals: number;