@openvtc/trust-tasks 0.28.17 → 0.28.19

package/src/vtc/badges/kudos/list/0.1/payload.ts

@@ -0,0 +1,1080 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/badges/kudos/list/0.1/payload.schema.json
+ */
+
+import type { Award, AwardId, AwardNote, AwardState, Badge, BadgeCriteria, BadgeDescription, BadgeId, BadgeKind, BadgeName, BadgeState, CardBlobRef, EntryFields, EntryId, Ext, FieldValue, GroupCredentialId, GroupId, VerifiedValue } from "../../../../../_shared/components.js";
+
+
+/**
+ * List the kudos the signer received or gave, a page at a time, each with its badge and the other party as the directory projects them; or, for a badge administrator, every giving of one kudos badge. The outer document members are owned by the framework — SPEC §6.3.
+ */
+export interface VTCBadgesKudosListPayload {
+  /**
+   * `received`: awards to the signer, with the giver as `counterpart`. `given`: awards by the signer, with the recipient as `counterpart`. Absent: `received`. Ignored with `all`.
+   */
+  direction?: "received" | "given";
+  /**
+   * Only givings of this kudos badge. REQUIRED with `all`.
+   */
+  badgeId?: BadgeId;
+  /**
+   * Only awards in this state.
+   */
+  state?: AwardState;
+  /**
+   * Every giving of `badgeId`, giver and recipient both, to a holder of `vtc.badges.admin` (VTI-BDG-042). Sent only as `true`, with `badgeId`.
+   */
+  all?: true;
+  /**
+   * An opaque continuation token from a previous response's `nextCursor`, bound to the caller and the filters; a responder MUST NOT accept a cursor it did not issue.
+   */
+  cursor?: string;
+  /**
+   * The most items to return, at most 200; the responder chooses a default (50) and MAY return fewer.
+   */
+  limit?: number;
+  ext?: Ext;
+}
+/**
+ * The success response to a vtc/badges/kudos/list/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/badges/kudos/list/0.1#response.
+ */
+export interface VTCBadgesKudosListResponsePayload {
+  /**
+   * Newest first by `offeredAt`.
+   *
+   * @maxItems 200
+   */
+  items: KudosItem[];
+  /**
+   * Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`.
+   */
+  nextCursor?: string;
+  ext?: Ext;
+}
+/**
+ * One giving of a kudos badge: the award, its badge, and the other party as the directory projects them to the caller — `counterpart` for a member's own list, `giver` and `recipient` for an administrator's `all`.
+ */
+export interface KudosItem {
+  award: Award;
+  badge: Badge;
+  /**
+   * The other party's directory fields the caller may see — the giver for `received`, the recipient for `given` — projected exactly as vtc/directory/entries/show would project them. Absent when the caller may see none, the party has departed, or the list is an administrator's `all`.
+   */
+  counterpart?: EntryFields;
+  /**
+   * With `all` only: the giver's fields projected for the caller. Absent when the caller may see none or the giver has departed.
+   */
+  giver?: EntryFields;
+  /**
+   * With `all` only: the recipient's fields projected for the caller. Absent when the caller may see none or the recipient has departed.
+   */
+  recipient?: EntryFields;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Award, AwardId, AwardNote, AwardState, Badge, BadgeCriteria, BadgeDescription, BadgeId, BadgeKind, BadgeName, BadgeState, CardBlobRef, EntryFields, EntryId, Ext, FieldValue, GroupCredentialId, GroupId, VerifiedValue };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/badges/kudos/list/0.1" as const;
+
+/**
+ * The earlier version of this specification that this one declares it
+ * extends (front matter `extends`, SPEC §5.2 "Declared extension"), or
+ * `null`. Only the direct declaration — follow the chain with
+ * `extendsChain` / `readForSpec`.
+ */
+export const EXTENDS: string | null = null;
+
+/**
+ * Why this version is deprecated, or `null` while it is current. A
+ * superseded or retired version is still supported, and is withdrawn from
+ * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
+ * Versions").
+ */
+export const DEPRECATION: string | null = null;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCBadgesKudosListPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/badges/kudos/list/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCBadgesKudosListResponsePayload;
+
+/**
+ * This specification's payload schema, as a value.
+ *
+ * SPEC.md §7.2 item 2 is performed against this. It is shipped as data
+ * rather than only as a `.json` file because TypeScript types are erased
+ * at runtime: without a schema a consumer has nothing to validate, and
+ * every REQUIRED payload member is optional in practice. Cross-file
+ * `$ref`s are already inlined, so it needs no resolver.
+ */
+export const PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trusttasks.org/spec/vtc/badges/kudos/list/0.1",
+  "title": "VTC Badges — Kudos — List — payload",
+  "description": "List the kudos the signer received or gave, a page at a time, each with its badge and the other party as the directory projects them; or, for a badge administrator, every giving of one kudos badge. The outer document members are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "dependentRequired": {
+    "all": [
+      "badgeId"
+    ]
+  },
+  "properties": {
+    "direction": {
+      "type": "string",
+      "enum": [
+        "received",
+        "given"
+      ],
+      "description": "`received`: awards to the signer, with the giver as `counterpart`. `given`: awards by the signer, with the recipient as `counterpart`. Absent: `received`. Ignored with `all`."
+    },
+    "badgeId": {
+      "$ref": "#/$defs/BadgeId",
+      "description": "Only givings of this kudos badge. REQUIRED with `all`."
+    },
+    "state": {
+      "$ref": "#/$defs/AwardState",
+      "description": "Only awards in this state."
+    },
+    "all": {
+      "type": "boolean",
+      "const": true,
+      "description": "Every giving of `badgeId`, giver and recipient both, to a holder of `vtc.badges.admin` (VTI-BDG-042). Sent only as `true`, with `badgeId`."
+    },
+    "cursor": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "An opaque continuation token from a previous response's `nextCursor`, bound to the caller and the filters; a responder MUST NOT accept a cursor it did not issue."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 200,
+      "description": "The most items to return, at most 200; the responder chooses a default (50) and MAY return fewer."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Item": {
+      "title": "KudosItem",
+      "description": "One giving of a kudos badge: the award, its badge, and the other party as the directory projects them to the caller — `counterpart` for a member's own list, `giver` and `recipient` for an administrator's `all`.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "award",
+        "badge"
+      ],
+      "properties": {
+        "award": {
+          "$ref": "#/$defs/Award"
+        },
+        "badge": {
+          "$ref": "#/$defs/Badge"
+        },
+        "counterpart": {
+          "$ref": "#/$defs/EntryFields",
+          "description": "The other party's directory fields the caller may see — the giver for `received`, the recipient for `given` — projected exactly as vtc/directory/entries/show would project them. Absent when the caller may see none, the party has departed, or the list is an administrator's `all`."
+        },
+        "giver": {
+          "$ref": "#/$defs/EntryFields",
+          "description": "With `all` only: the giver's fields projected for the caller. Absent when the caller may see none or the giver has departed."
+        },
+        "recipient": {
+          "$ref": "#/$defs/EntryFields",
+          "description": "With `all` only: the recipient's fields projected for the caller. Absent when the caller may see none or the recipient has departed."
+        }
+      }
+    },
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Badges — Kudos — List — response payload",
+      "description": "The success response to a vtc/badges/kudos/list/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/badges/kudos/list/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "maxItems": 200,
+          "items": {
+            "$ref": "#/$defs/Item"
+          },
+          "description": "Newest first by `offeredAt`."
+        },
+        "nextCursor": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "EntryFields": {
+      "title": "EntryFields",
+      "description": "The fields of one entry that a particular viewer may see, keyed by field: the intersection of the member's visibility, the community's ceiling and policy, plus any derived fields that intersection admits. A withheld field is ABSENT, never null.",
+      "type": "object",
+      "maxProperties": 64,
+      "propertyNames": {
+        "$ref": "#/$defs/FieldKey"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/FieldValue"
+      }
+    },
+    "FieldValue": {
+      "title": "FieldValue",
+      "description": "The value of one field. Which shape a field takes is fixed by its definition's `type`: text-like types (`text`, `longText`, `url`, `email`, `phone`, `enum`, `date` as YYYY-MM-DD, `country` as ISO 3166-1 alpha-2, `did`) are strings; `multiEnum` and the base field `links` are arrays of strings; `image` and the base field `avatar` are a `CardBlobRef`; `claim` is a `VerifiedValue`; the derived base field `personhood` is a boolean.",
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 2000
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "type": "string",
+            "maxLength": 500
+          }
+        },
+        {
+          "$ref": "#/$defs/CardBlobRef"
+        },
+        {
+          "$ref": "#/$defs/VerifiedValue"
+        }
+      ]
+    },
+    "VerifiedValue": {
+      "title": "VerifiedValue",
+      "description": "The value of a `credential`-sourced field: a claim the member disclosed from a credential they presented, with the issuer that attests it. A verified value always names its issuer, and a self-asserted value is never shaped as one. The community keeps only the disclosed claim and these facts about it — never the presentation.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "value",
+        "issuer",
+        "verifiedAt"
+      ],
+      "properties": {
+        "value": {
+          "anyOf": [
+            {
+              "type": "string",
+              "maxLength": 2000
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "number"
+            }
+          ],
+          "description": "The disclosed claim value."
+        },
+        "issuer": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 2048,
+          "description": "DID of the credential's issuer, shown as the field's verification badge."
+        },
+        "credentialType": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The most specific `type` of the credential the claim came from."
+        },
+        "verifiedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the community verified the presentation."
+        },
+        "validUntil": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the credential expires, where it does. The community withdraws the value once it passes."
+        }
+      }
+    },
+    "CardBlobRef": {
+      "title": "CardBlobRef",
+      "description": "A content-addressed image held in the community's blob store — an avatar or an `image` field. At most 256 KiB, images only, re-encoded by the community on upload (vtc/directory/images/upload: metadata stripped, dimensions capped) so its digest does not link the member across communities. A viewer reads the bytes with vtc/directory/images/get, which answers only where the same projection shows the value. `url` and `urlExpiresAt` MAY appear in a projection: a short-lived URL the community checks against the same projection, so a member-only image is never a public URL. A community that does not offer one leaves both out.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sha256",
+        "mediaType"
+      ],
+      "properties": {
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Lowercase hex SHA-256 of the stored, re-encoded bytes."
+        },
+        "mediaType": {
+          "type": "string",
+          "enum": [
+            "image/png",
+            "image/jpeg",
+            "image/webp",
+            "image/avif"
+          ],
+          "description": "Media type of the stored bytes."
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 262144,
+          "description": "Size in bytes of the stored bytes."
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "maxLength": 2048,
+          "description": "Projection only: a URL the viewer can fetch the image from until `urlExpiresAt`."
+        },
+        "urlExpiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Projection only: when `url` stops working."
+        }
+      }
+    },
+    "FieldKey": {
+      "title": "FieldKey",
+      "description": "Identifier of a directory field. A key with no `.` is a BASE field, the same in every community: `displayName`, `nickname`, `avatar`, `pronouns`, `bio`, `links` (written by the member) and `role`, `joinedAt`, `did`, `personhood` (derived from the community's own records, never stored on a card). A community-defined field MUST use a reverse-DNS key (`org.example.employer`), so a base key never collides with one, and a key is never reused with a different meaning once defined.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^([a-z][a-z0-9-]*\\.)*[a-z][a-zA-Z0-9]{0,63}$"
+    },
+    "Badge": {
+      "title": "Badge",
+      "description": "A badge as a caller who may see it sees it. `groupId` is present exactly when `kind` is `community`. `holderCount` only to callers who may see the badge's holders, counted over holders who have not hidden it (VTI-BDG-030, VTI-BDG-033). `createdBy` is the directory entry of the administrator or member who made it, where they have one.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "badgeId",
+        "kind",
+        "name",
+        "description",
+        "image",
+        "repeatable",
+        "listed",
+        "state",
+        "createdAt"
+      ],
+      "properties": {
+        "badgeId": {
+          "$ref": "#/$defs/BadgeId"
+        },
+        "kind": {
+          "$ref": "#/$defs/BadgeKind"
+        },
+        "name": {
+          "$ref": "#/$defs/BadgeName"
+        },
+        "description": {
+          "$ref": "#/$defs/BadgeDescription"
+        },
+        "criteria": {
+          "$ref": "#/$defs/BadgeCriteria"
+        },
+        "image": {
+          "$ref": "#/$defs/CardBlobRef",
+          "description": "The badge's picture, re-encoded and stored by the community (vtc/badges/images/upload), read with vtc/badges/images/get. `url` and `urlExpiresAt` MAY appear in a projection as for a card picture; for a badge whose holders may show it outside, `url` MAY be the picture's stable public location."
+        },
+        "repeatable": {
+          "type": "boolean",
+          "description": "Whether one member may hold the badge more than once, each giving an award of its own (VTI-BDG-022). Always true for a kudos badge."
+        },
+        "requestable": {
+          "type": "boolean",
+          "description": "Community badges only. Whether a member may ask for it: a request to join its badge group, decided by its owners (VTI-BDG-014). Absent reads as false."
+        },
+        "listed": {
+          "type": "boolean",
+          "description": "Whether members who do not hold the badge see it in the community's badge list. An unlisted badge is seen by its holders, its owners and administrators."
+        },
+        "shareableOutside": {
+          "type": "boolean",
+          "description": "Community badges only. Whether its holders may show it outside the community, which decides the credential's regime: short-lived and renewed with no status when false, long-lived with a status in the community's own status set when true (VTI-BDG-061, VTI-BDG-062). Absent reads as false."
+        },
+        "groupId": {
+          "$ref": "#/$defs/GroupId",
+          "description": "The badge group that backs a community badge: its managers are the badge's owners, its members the holders, its DID the credential's issuer."
+        },
+        "state": {
+          "$ref": "#/$defs/BadgeState"
+        },
+        "holderCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Holders who show the badge. Only to callers who may see the holders."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "createdBy": {
+          "$ref": "#/$defs/EntryId"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "retiredAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1. An extension member MUST NOT carry authority."
+        }
+      }
+    },
+    "BadgeState": {
+      "title": "BadgeState",
+      "description": "`active`: may be given and shown. `retired`: kept for its holders' own history, never given, never shown to members who do not hold it (VTI-BDG-005).",
+      "type": "string",
+      "enum": [
+        "active",
+        "retired"
+      ]
+    },
+    "BadgeCriteria": {
+      "title": "BadgeCriteria",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "description": "How the badge is earned, shown to members and written into the credential's Achievement as its criteria narrative. Plain text."
+    },
+    "BadgeDescription": {
+      "title": "BadgeDescription",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "description": "What the badge is for. Plain text; a reader MUST NOT treat it as instructions."
+    },
+    "BadgeName": {
+      "title": "BadgeName",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "The badge's name, shown on the wall and written into the credential's Achievement. Plain text; a reader MUST NOT treat it as instructions."
+    },
+    "BadgeKind": {
+      "title": "BadgeKind",
+      "description": "`community`: defined by holders of `vtc.badges.admin`, given by its owners (its badge group's managers), may carry a credential. `kudos`: made by a member the community's badge settings admit, given by any active member to any other, never a credential. Fixed for the badge's life; a kudos badge becomes a community badge only by promotion (vtc/badges/promote).",
+      "type": "string",
+      "enum": [
+        "community",
+        "kudos"
+      ]
+    },
+    "BadgeId": {
+      "title": "BadgeId",
+      "description": "Opaque identifier of a badge: `bdg_` followed by 16 to 64 base64url characters. Random, community-scoped, never reused (VTI-BDG-001).",
+      "type": "string",
+      "pattern": "^bdg_[A-Za-z0-9_-]{16,64}$"
+    },
+    "EntryId": {
+      "title": "EntryId",
+      "description": "Opaque identifier of one directory entry: `dir_` followed by 16 to 64 base64url characters. Random, scoped to one community, and stable for the life of the membership — it survives a rotation of the member's DID, which is why groups, notes and cards are keyed by it. It MUST NOT be derived from, and MUST NOT reveal, any DID of the member, and the same person's entries in two communities MUST NOT share one. Compared by exact string equality.",
+      "type": "string",
+      "pattern": "^dir_[A-Za-z0-9_-]{16,64}$"
+    },
+    "GroupId": {
+      "title": "GroupId",
+      "description": "Opaque identifier of a community group: `grp_` followed by 16 to 64 base64url characters. Random and community-scoped; not the group's DID.",
+      "type": "string",
+      "pattern": "^grp_[A-Za-z0-9_-]{16,64}$"
+    },
+    "Award": {
+      "title": "Award",
+      "description": "One giving of a badge to one member. `givenBy` is the giver's directory entry, absent for an award a dynamic badge group's rule made. `note` is shown to the recipient, the giver, the badge's owners and administrators, never to other members. `credentialId` is present on an accepted award of a community badge: the badge credential that evidences it, renewed or re-issued as the badge's regime requires.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "awardId",
+        "badgeId",
+        "entryId",
+        "state",
+        "offeredAt"
+      ],
+      "properties": {
+        "awardId": {
+          "$ref": "#/$defs/AwardId"
+        },
+        "badgeId": {
+          "$ref": "#/$defs/BadgeId"
+        },
+        "entryId": {
+          "$ref": "#/$defs/EntryId",
+          "description": "The recipient."
+        },
+        "givenBy": {
+          "$ref": "#/$defs/EntryId"
+        },
+        "note": {
+          "$ref": "#/$defs/AwardNote"
+        },
+        "state": {
+          "$ref": "#/$defs/AwardState"
+        },
+        "offeredAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "decidedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the recipient accepted or declined, the giver withdrew, the offer expired, or the award was revoked."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When an unanswered offer lapses, where the community expires offers."
+        },
+        "credentialId": {
+          "$ref": "#/$defs/GroupCredentialId"
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "AwardState": {
+      "title": "AwardState",
+      "description": "`offered`: waiting for the recipient. `accepted`: the recipient took it; for a community badge the credential was issued and the membership recorded. `declined`: the recipient declined; nothing was recorded in the group and nothing issued. `withdrawn`: the giver withdrew the offer before a decision. `expired`: the offer lapsed unanswered. `revoked`: taken back after acceptance (VTI-BDG-023).",
+      "type": "string",
+      "enum": [
+        "offered",
+        "accepted",
+        "declined",
+        "withdrawn",
+        "expired",
+        "revoked"
+      ]
+    },
+    "AwardNote": {
+      "title": "AwardNote",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500,
+      "description": "What the award is for, from the giver, shown to the recipient and written as the award's evidence narrative where the badge carries a credential. Plain text; erased with its author (VTI-BDG-090)."
+    },
+    "AwardId": {
+      "title": "AwardId",
+      "description": "Opaque identifier of one giving of a badge to one member: `awd_` followed by 16 to 64 base64url characters. Random and unique within the community.",
+      "type": "string",
+      "pattern": "^awd_[A-Za-z0-9_-]{16,64}$"
+    },
+    "GroupCredentialId": {
+      "title": "GroupCredentialId",
+      "description": "Identifier (`id`) of a group membership credential issued to a member. Each renewal issues a new credential with a new identifier. Validity is the community's setting; a community SHOULD default to 30 days, renewed when 10 days remain.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512
+    }
+  }
+} as const;
+
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export const RESPONSE_PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Response",
+  "$defs": {
+    "Item": {
+      "title": "KudosItem",
+      "description": "One giving of a kudos badge: the award, its badge, and the other party as the directory projects them to the caller — `counterpart` for a member's own list, `giver` and `recipient` for an administrator's `all`.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "award",
+        "badge"
+      ],
+      "properties": {
+        "award": {
+          "$ref": "#/$defs/Award"
+        },
+        "badge": {
+          "$ref": "#/$defs/Badge"
+        },
+        "counterpart": {
+          "$ref": "#/$defs/EntryFields",
+          "description": "The other party's directory fields the caller may see — the giver for `received`, the recipient for `given` — projected exactly as vtc/directory/entries/show would project them. Absent when the caller may see none, the party has departed, or the list is an administrator's `all`."
+        },
+        "giver": {
+          "$ref": "#/$defs/EntryFields",
+          "description": "With `all` only: the giver's fields projected for the caller. Absent when the caller may see none or the giver has departed."
+        },
+        "recipient": {
+          "$ref": "#/$defs/EntryFields",
+          "description": "With `all` only: the recipient's fields projected for the caller. Absent when the caller may see none or the recipient has departed."
+        }
+      }
+    },
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Badges — Kudos — List — response payload",
+      "description": "The success response to a vtc/badges/kudos/list/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/badges/kudos/list/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "maxItems": 200,
+          "items": {
+            "$ref": "#/$defs/Item"
+          },
+          "description": "Newest first by `offeredAt`."
+        },
+        "nextCursor": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "EntryFields": {
+      "title": "EntryFields",
+      "description": "The fields of one entry that a particular viewer may see, keyed by field: the intersection of the member's visibility, the community's ceiling and policy, plus any derived fields that intersection admits. A withheld field is ABSENT, never null.",
+      "type": "object",
+      "maxProperties": 64,
+      "propertyNames": {
+        "$ref": "#/$defs/FieldKey"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/FieldValue"
+      }
+    },
+    "FieldValue": {
+      "title": "FieldValue",
+      "description": "The value of one field. Which shape a field takes is fixed by its definition's `type`: text-like types (`text`, `longText`, `url`, `email`, `phone`, `enum`, `date` as YYYY-MM-DD, `country` as ISO 3166-1 alpha-2, `did`) are strings; `multiEnum` and the base field `links` are arrays of strings; `image` and the base field `avatar` are a `CardBlobRef`; `claim` is a `VerifiedValue`; the derived base field `personhood` is a boolean.",
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 2000
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "type": "string",
+            "maxLength": 500
+          }
+        },
+        {
+          "$ref": "#/$defs/CardBlobRef"
+        },
+        {
+          "$ref": "#/$defs/VerifiedValue"
+        }
+      ]
+    },
+    "VerifiedValue": {
+      "title": "VerifiedValue",
+      "description": "The value of a `credential`-sourced field: a claim the member disclosed from a credential they presented, with the issuer that attests it. A verified value always names its issuer, and a self-asserted value is never shaped as one. The community keeps only the disclosed claim and these facts about it — never the presentation.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "value",
+        "issuer",
+        "verifiedAt"
+      ],
+      "properties": {
+        "value": {
+          "anyOf": [
+            {
+              "type": "string",
+              "maxLength": 2000
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "number"
+            }
+          ],
+          "description": "The disclosed claim value."
+        },
+        "issuer": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 2048,
+          "description": "DID of the credential's issuer, shown as the field's verification badge."
+        },
+        "credentialType": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The most specific `type` of the credential the claim came from."
+        },
+        "verifiedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the community verified the presentation."
+        },
+        "validUntil": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the credential expires, where it does. The community withdraws the value once it passes."
+        }
+      }
+    },
+    "CardBlobRef": {
+      "title": "CardBlobRef",
+      "description": "A content-addressed image held in the community's blob store — an avatar or an `image` field. At most 256 KiB, images only, re-encoded by the community on upload (vtc/directory/images/upload: metadata stripped, dimensions capped) so its digest does not link the member across communities. A viewer reads the bytes with vtc/directory/images/get, which answers only where the same projection shows the value. `url` and `urlExpiresAt` MAY appear in a projection: a short-lived URL the community checks against the same projection, so a member-only image is never a public URL. A community that does not offer one leaves both out.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sha256",
+        "mediaType"
+      ],
+      "properties": {
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Lowercase hex SHA-256 of the stored, re-encoded bytes."
+        },
+        "mediaType": {
+          "type": "string",
+          "enum": [
+            "image/png",
+            "image/jpeg",
+            "image/webp",
+            "image/avif"
+          ],
+          "description": "Media type of the stored bytes."
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 262144,
+          "description": "Size in bytes of the stored bytes."
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "maxLength": 2048,
+          "description": "Projection only: a URL the viewer can fetch the image from until `urlExpiresAt`."
+        },
+        "urlExpiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Projection only: when `url` stops working."
+        }
+      }
+    },
+    "FieldKey": {
+      "title": "FieldKey",
+      "description": "Identifier of a directory field. A key with no `.` is a BASE field, the same in every community: `displayName`, `nickname`, `avatar`, `pronouns`, `bio`, `links` (written by the member) and `role`, `joinedAt`, `did`, `personhood` (derived from the community's own records, never stored on a card). A community-defined field MUST use a reverse-DNS key (`org.example.employer`), so a base key never collides with one, and a key is never reused with a different meaning once defined.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^([a-z][a-z0-9-]*\\.)*[a-z][a-zA-Z0-9]{0,63}$"
+    },
+    "Badge": {
+      "title": "Badge",
+      "description": "A badge as a caller who may see it sees it. `groupId` is present exactly when `kind` is `community`. `holderCount` only to callers who may see the badge's holders, counted over holders who have not hidden it (VTI-BDG-030, VTI-BDG-033). `createdBy` is the directory entry of the administrator or member who made it, where they have one.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "badgeId",
+        "kind",
+        "name",
+        "description",
+        "image",
+        "repeatable",
+        "listed",
+        "state",
+        "createdAt"
+      ],
+      "properties": {
+        "badgeId": {
+          "$ref": "#/$defs/BadgeId"
+        },
+        "kind": {
+          "$ref": "#/$defs/BadgeKind"
+        },
+        "name": {
+          "$ref": "#/$defs/BadgeName"
+        },
+        "description": {
+          "$ref": "#/$defs/BadgeDescription"
+        },
+        "criteria": {
+          "$ref": "#/$defs/BadgeCriteria"
+        },
+        "image": {
+          "$ref": "#/$defs/CardBlobRef",
+          "description": "The badge's picture, re-encoded and stored by the community (vtc/badges/images/upload), read with vtc/badges/images/get. `url` and `urlExpiresAt` MAY appear in a projection as for a card picture; for a badge whose holders may show it outside, `url` MAY be the picture's stable public location."
+        },
+        "repeatable": {
+          "type": "boolean",
+          "description": "Whether one member may hold the badge more than once, each giving an award of its own (VTI-BDG-022). Always true for a kudos badge."
+        },
+        "requestable": {
+          "type": "boolean",
+          "description": "Community badges only. Whether a member may ask for it: a request to join its badge group, decided by its owners (VTI-BDG-014). Absent reads as false."
+        },
+        "listed": {
+          "type": "boolean",
+          "description": "Whether members who do not hold the badge see it in the community's badge list. An unlisted badge is seen by its holders, its owners and administrators."
+        },
+        "shareableOutside": {
+          "type": "boolean",
+          "description": "Community badges only. Whether its holders may show it outside the community, which decides the credential's regime: short-lived and renewed with no status when false, long-lived with a status in the community's own status set when true (VTI-BDG-061, VTI-BDG-062). Absent reads as false."
+        },
+        "groupId": {
+          "$ref": "#/$defs/GroupId",
+          "description": "The badge group that backs a community badge: its managers are the badge's owners, its members the holders, its DID the credential's issuer."
+        },
+        "state": {
+          "$ref": "#/$defs/BadgeState"
+        },
+        "holderCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Holders who show the badge. Only to callers who may see the holders."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "createdBy": {
+          "$ref": "#/$defs/EntryId"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "retiredAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1. An extension member MUST NOT carry authority."
+        }
+      }
+    },
+    "BadgeState": {
+      "title": "BadgeState",
+      "description": "`active`: may be given and shown. `retired`: kept for its holders' own history, never given, never shown to members who do not hold it (VTI-BDG-005).",
+      "type": "string",
+      "enum": [
+        "active",
+        "retired"
+      ]
+    },
+    "BadgeCriteria": {
+      "title": "BadgeCriteria",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "description": "How the badge is earned, shown to members and written into the credential's Achievement as its criteria narrative. Plain text."
+    },
+    "BadgeDescription": {
+      "title": "BadgeDescription",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "description": "What the badge is for. Plain text; a reader MUST NOT treat it as instructions."
+    },
+    "BadgeName": {
+      "title": "BadgeName",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "The badge's name, shown on the wall and written into the credential's Achievement. Plain text; a reader MUST NOT treat it as instructions."
+    },
+    "BadgeKind": {
+      "title": "BadgeKind",
+      "description": "`community`: defined by holders of `vtc.badges.admin`, given by its owners (its badge group's managers), may carry a credential. `kudos`: made by a member the community's badge settings admit, given by any active member to any other, never a credential. Fixed for the badge's life; a kudos badge becomes a community badge only by promotion (vtc/badges/promote).",
+      "type": "string",
+      "enum": [
+        "community",
+        "kudos"
+      ]
+    },
+    "BadgeId": {
+      "title": "BadgeId",
+      "description": "Opaque identifier of a badge: `bdg_` followed by 16 to 64 base64url characters. Random, community-scoped, never reused (VTI-BDG-001).",
+      "type": "string",
+      "pattern": "^bdg_[A-Za-z0-9_-]{16,64}$"
+    },
+    "EntryId": {
+      "title": "EntryId",
+      "description": "Opaque identifier of one directory entry: `dir_` followed by 16 to 64 base64url characters. Random, scoped to one community, and stable for the life of the membership — it survives a rotation of the member's DID, which is why groups, notes and cards are keyed by it. It MUST NOT be derived from, and MUST NOT reveal, any DID of the member, and the same person's entries in two communities MUST NOT share one. Compared by exact string equality.",
+      "type": "string",
+      "pattern": "^dir_[A-Za-z0-9_-]{16,64}$"
+    },
+    "GroupId": {
+      "title": "GroupId",
+      "description": "Opaque identifier of a community group: `grp_` followed by 16 to 64 base64url characters. Random and community-scoped; not the group's DID.",
+      "type": "string",
+      "pattern": "^grp_[A-Za-z0-9_-]{16,64}$"
+    },
+    "Award": {
+      "title": "Award",
+      "description": "One giving of a badge to one member. `givenBy` is the giver's directory entry, absent for an award a dynamic badge group's rule made. `note` is shown to the recipient, the giver, the badge's owners and administrators, never to other members. `credentialId` is present on an accepted award of a community badge: the badge credential that evidences it, renewed or re-issued as the badge's regime requires.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "awardId",
+        "badgeId",
+        "entryId",
+        "state",
+        "offeredAt"
+      ],
+      "properties": {
+        "awardId": {
+          "$ref": "#/$defs/AwardId"
+        },
+        "badgeId": {
+          "$ref": "#/$defs/BadgeId"
+        },
+        "entryId": {
+          "$ref": "#/$defs/EntryId",
+          "description": "The recipient."
+        },
+        "givenBy": {
+          "$ref": "#/$defs/EntryId"
+        },
+        "note": {
+          "$ref": "#/$defs/AwardNote"
+        },
+        "state": {
+          "$ref": "#/$defs/AwardState"
+        },
+        "offeredAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "decidedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the recipient accepted or declined, the giver withdrew, the offer expired, or the award was revoked."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When an unanswered offer lapses, where the community expires offers."
+        },
+        "credentialId": {
+          "$ref": "#/$defs/GroupCredentialId"
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "AwardState": {
+      "title": "AwardState",
+      "description": "`offered`: waiting for the recipient. `accepted`: the recipient took it; for a community badge the credential was issued and the membership recorded. `declined`: the recipient declined; nothing was recorded in the group and nothing issued. `withdrawn`: the giver withdrew the offer before a decision. `expired`: the offer lapsed unanswered. `revoked`: taken back after acceptance (VTI-BDG-023).",
+      "type": "string",
+      "enum": [
+        "offered",
+        "accepted",
+        "declined",
+        "withdrawn",
+        "expired",
+        "revoked"
+      ]
+    },
+    "AwardNote": {
+      "title": "AwardNote",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500,
+      "description": "What the award is for, from the giver, shown to the recipient and written as the award's evidence narrative where the badge carries a credential. Plain text; erased with its author (VTI-BDG-090)."
+    },
+    "AwardId": {
+      "title": "AwardId",
+      "description": "Opaque identifier of one giving of a badge to one member: `awd_` followed by 16 to 64 base64url characters. Random and unique within the community.",
+      "type": "string",
+      "pattern": "^awd_[A-Za-z0-9_-]{16,64}$"
+    },
+    "GroupCredentialId": {
+      "title": "GroupCredentialId",
+      "description": "Identifier (`id`) of a group membership credential issued to a member. Each renewal issues a new credential with a new identifier. Validity is the community's setting; a community SHOULD default to 30 days, renewed when 10 days remain.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512
+    }
+  }
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the request variant, from this specification's
+ * front matter. Pass to `consumeInbound` — items 5b, 7 and 8 are
+ * per-specification and cannot be derived from the document alone, and
+ * item 2 needs the schema this carries.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: PAYLOAD_SCHEMA,
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
+ * tracks the *issuer* party's requirement because a response swaps the
+ * parties (§7.3 item 5).
+ */
+export const RESPONSE_SPEC = {
+  typeUri: RESPONSE_TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;