@openvtc/trust-tasks 0.28.17 → 0.28.19

package/src/vtc/badges/create/0.1/payload.ts

@@ -0,0 +1,1137 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/badges/create/0.1/payload.schema.json
+ */
+
+import type { Badge, BadgeCriteria, BadgeDescription, BadgeId, BadgeKind, BadgeName, BadgeState, CardBlobRef, DynamicRule, EntryId, Ext, FieldKey, Group, GroupAudience, GroupDescription, GroupId, GroupKind, GroupName, JoinPolicy, RuleCondition } from "../../../../_shared/components.js";
+
+
+/**
+ * Define a badge: a community badge, which creates the badge group that backs it, or a kudos badge a member makes. The outer document members are owned by the framework — SPEC §6.3.
+ */
+export interface VTCBadgesCreatePayload {
+  kind: BadgeKind;
+  name: BadgeName;
+  description: BadgeDescription;
+  criteria?: BadgeCriteria;
+  /**
+   * The picture, as the signer uploaded it with vtc/badges/images/upload.
+   */
+  image: {
+    /**
+     * The digest vtc/badges/images/upload answered to this signer.
+     */
+    sha256: string;
+  };
+  /**
+   * Whether one member may hold the badge more than once. Absent: false for a community badge; a kudos badge is always repeatable and refuses `false`.
+   */
+  repeatable?: boolean;
+  /**
+   * Community badges only. Whether members may ask for it (a request to join the badge group). Absent: false.
+   */
+  requestable?: boolean;
+  /**
+   * Whether members who do not hold it see it in the badge list. Absent: true.
+   */
+  listed?: boolean;
+  /**
+   * Community badges only. Whether holders may show it outside the community, which fixes the credential's regime. Absent: false.
+   */
+  shareableOutside?: boolean;
+  /**
+   * Community badges only. Who may see the badge's holders: the badge group's `showMembers`. Absent: `members`.
+   */
+  holdersVisibleTo?: GroupAudience;
+  /**
+   * Community badges only. Present: the badge is automatic, backed by a dynamic badge group computed from `rule`; nobody gives it by hand and `requestable` is refused.
+   */
+  automatic?: {
+    rule: DynamicRule;
+  };
+  /**
+   * Community badges only. Members to appoint as the badge's owners — the badge group's managers — as vtc/groups/managers/add appoints them, bounded by the signer's own holding.
+   *
+   * @maxItems 32
+   */
+  owners?: EntryId[];
+  /**
+   * Why, recorded with the change.
+   */
+  reason: string;
+  ext?: Ext;
+}
+/**
+ * The success response to a vtc/badges/create/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/badges/create/0.1#response.
+ */
+export interface VTCBadgesCreateResponsePayload {
+  badge: Badge;
+  /**
+   * The badge group, as vtc/groups/create answers it. Present exactly for a community badge.
+   */
+  group?: Group;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Badge, BadgeCriteria, BadgeDescription, BadgeId, BadgeKind, BadgeName, BadgeState, CardBlobRef, DynamicRule, EntryId, Ext, FieldKey, Group, GroupAudience, GroupDescription, GroupId, GroupKind, GroupName, JoinPolicy, RuleCondition };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/badges/create/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 = VTCBadgesCreatePayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/badges/create/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCBadgesCreateResponsePayload;
+
+/**
+ * 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/create/0.1",
+  "title": "VTC Badges — Create — payload",
+  "description": "Define a badge: a community badge, which creates the badge group that backs it, or a kudos badge a member makes. The outer document members are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "name",
+    "description",
+    "image",
+    "reason"
+  ],
+  "properties": {
+    "kind": {
+      "$ref": "#/$defs/BadgeKind"
+    },
+    "name": {
+      "$ref": "#/$defs/BadgeName"
+    },
+    "description": {
+      "$ref": "#/$defs/BadgeDescription"
+    },
+    "criteria": {
+      "$ref": "#/$defs/BadgeCriteria"
+    },
+    "image": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sha256"
+      ],
+      "properties": {
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "The digest vtc/badges/images/upload answered to this signer."
+        }
+      },
+      "description": "The picture, as the signer uploaded it with vtc/badges/images/upload."
+    },
+    "repeatable": {
+      "type": "boolean",
+      "description": "Whether one member may hold the badge more than once. Absent: false for a community badge; a kudos badge is always repeatable and refuses `false`."
+    },
+    "requestable": {
+      "type": "boolean",
+      "description": "Community badges only. Whether members may ask for it (a request to join the badge group). Absent: false."
+    },
+    "listed": {
+      "type": "boolean",
+      "description": "Whether members who do not hold it see it in the badge list. Absent: true."
+    },
+    "shareableOutside": {
+      "type": "boolean",
+      "description": "Community badges only. Whether holders may show it outside the community, which fixes the credential's regime. Absent: false."
+    },
+    "holdersVisibleTo": {
+      "$ref": "#/$defs/GroupAudience",
+      "description": "Community badges only. Who may see the badge's holders: the badge group's `showMembers`. Absent: `members`."
+    },
+    "automatic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rule"
+      ],
+      "properties": {
+        "rule": {
+          "$ref": "#/$defs/DynamicRule"
+        }
+      },
+      "description": "Community badges only. Present: the badge is automatic, backed by a dynamic badge group computed from `rule`; nobody gives it by hand and `requestable` is refused."
+    },
+    "owners": {
+      "type": "array",
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/EntryId"
+      },
+      "description": "Community badges only. Members to appoint as the badge's owners — the badge group's managers — as vtc/groups/managers/add appoints them, bounded by the signer's own holding."
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "Why, recorded with the change."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Badges — Create — response payload",
+      "description": "The success response to a vtc/badges/create/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/badges/create/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "badge"
+      ],
+      "properties": {
+        "badge": {
+          "$ref": "#/$defs/Badge"
+        },
+        "group": {
+          "$ref": "#/$defs/Group",
+          "description": "The badge group, as vtc/groups/create answers it. Present exactly for a community badge."
+        },
+        "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-]+)+$"
+      }
+    },
+    "Group": {
+      "title": "Group",
+      "description": "A community group, as a caller who may see it sees it. Members a caller may not see are absent: `memberCount` only to those who may see the group's members, `managers` and `credentialAuthorityValidUntil` only to its managers.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "groupId",
+        "groupDid",
+        "name",
+        "kind",
+        "visibility",
+        "showMembers",
+        "issuesCredentials",
+        "carriesAuthority",
+        "createdAt"
+      ],
+      "properties": {
+        "groupId": {
+          "$ref": "#/$defs/GroupId"
+        },
+        "groupDid": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 2048,
+          "description": "The group's own DID, minted by the community's VTA for this group alone. It issues the group's membership credentials. Its DID document carries no name or description."
+        },
+        "name": {
+          "$ref": "#/$defs/GroupName"
+        },
+        "description": {
+          "$ref": "#/$defs/GroupDescription"
+        },
+        "kind": {
+          "$ref": "#/$defs/GroupKind"
+        },
+        "rule": {
+          "$ref": "#/$defs/DynamicRule",
+          "description": "Present exactly when `kind` is `dynamic`."
+        },
+        "joinPolicy": {
+          "$ref": "#/$defs/JoinPolicy",
+          "description": "Present exactly when `kind` is `static`."
+        },
+        "visibility": {
+          "$ref": "#/$defs/GroupAudience",
+          "description": "Who may see that the group exists, and its name and description."
+        },
+        "showMembers": {
+          "$ref": "#/$defs/GroupAudience",
+          "description": "Who may see the group's member list. Separate from `visibility`: a group everyone sees may show its members only to administrators. Never wider than `visibility`."
+        },
+        "issuesCredentials": {
+          "type": "boolean",
+          "description": "Whether the group's DID issues its members a membership credential. Default true."
+        },
+        "carriesAuthority": {
+          "type": "boolean",
+          "description": "`true` while the group has a `grants` or `role` binding. Such a group is `static` and `closed` for as long as it does."
+        },
+        "badgeId": {
+          "$ref": "#/$defs/BadgeId",
+          "description": "Present exactly when the group backs a community badge (vtc/badges/*): its managers are the badge's owners, its members the badge's holders, and its DID issues the badge credential in place of a membership credential. A badge group never carries authority, is not counted among the groups two members share, and is listed among the community's groups only to a caller who asks for badge groups (VTI-BDG-010 – VTI-BDG-012)."
+        },
+        "memberCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Active members. Only to callers who may see the member list."
+        },
+        "managers": {
+          "type": "array",
+          "maxItems": 256,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/EntryId"
+          },
+          "description": "Entries holding `vtc.groups.manage` qualified to this group, read from the access-control list. Informational: managers are appointed by an access-control grant (vtc/groups/managers/add), never by this record."
+        },
+        "credentialAuthorityValidUntil": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the community's authorization credential to the group expires. The community renews it well before."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "createdBy": {
+          "$ref": "#/$defs/EntryId",
+          "description": "The creating administrator's directory entry, where they have one."
+        },
+        "updatedAt": {
+          "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."
+        }
+      }
+    },
+    "GroupAudience": {
+      "title": "GroupAudience",
+      "description": "Who may see something about a group, narrowest first. `admins`: holders of `vtc.groups.manage` for the group (unqualified, or qualified `group:<groupId>`). `groupMembers`: the group's own members, and its managers. `members`: every active member of the community.",
+      "type": "string",
+      "enum": [
+        "admins",
+        "groupMembers",
+        "members"
+      ]
+    },
+    "JoinPolicy": {
+      "title": "JoinPolicy",
+      "description": "How a member enters a static group by themselves. `closed`: only a manager adds them. `request`: a member asks and a manager decides. `open`: a member joins at once, subject to the community's `groups` policy. A group carrying authority is always `closed`.",
+      "type": "string",
+      "enum": [
+        "closed",
+        "request",
+        "open"
+      ]
+    },
+    "DynamicRule": {
+      "title": "DynamicRule",
+      "description": "A dynamic group's membership rule: a member belongs when every condition holds and they have not opted out. The community evaluates it under its `groups` policy and recomputes membership whenever a fact it reads changes, always excluding opted-out entries.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "all"
+      ],
+      "properties": {
+        "all": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": {
+            "$ref": "#/$defs/RuleCondition"
+          }
+        }
+      }
+    },
+    "RuleCondition": {
+      "title": "RuleCondition",
+      "description": "One test over a verified fact about a member. `fact: role` tests the member's community role; `fact: field` tests an `admin`- or `credential`-sourced directory field named by `field`; `fact: personhood` tests whether a personhood assertion is on file; `fact: joinedAt` tests when they joined. A rule never reads a self-asserted (`member`-sourced) field: a member must not be able to join a group by editing their card.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "fact",
+        "op"
+      ],
+      "properties": {
+        "fact": {
+          "type": "string",
+          "enum": [
+            "role",
+            "field",
+            "personhood",
+            "joinedAt"
+          ]
+        },
+        "field": {
+          "$ref": "#/$defs/FieldKey",
+          "description": "Present exactly when `fact` is `field`."
+        },
+        "op": {
+          "type": "string",
+          "enum": [
+            "equals",
+            "oneOf",
+            "exists",
+            "before",
+            "after"
+          ],
+          "description": "`equals` compares with `value`; `oneOf` with any of `values`; `exists` needs neither; `before` and `after` compare a date fact with `value`."
+        },
+        "value": {
+          "anyOf": [
+            {
+              "type": "string",
+              "maxLength": 256
+            },
+            {
+              "type": "boolean"
+            }
+          ]
+        },
+        "values": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "type": "string",
+            "maxLength": 256
+          }
+        }
+      }
+    },
+    "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}$"
+    },
+    "GroupKind": {
+      "title": "GroupKind",
+      "description": "`static`: membership is explicit — added, joined, or granted on request. `dynamic`: membership is computed from `rule` over verified facts only; nobody is added by hand, but a member may opt out (vtc/groups/leave), an exclusion the rule cannot override, and undo it (vtc/groups/join). A dynamic group never confers authority. Fixed for the group's life.",
+      "type": "string",
+      "enum": [
+        "static",
+        "dynamic"
+      ]
+    },
+    "GroupDescription": {
+      "title": "GroupDescription",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "description": "What the group is for. Plain text; a reader MUST NOT treat it as instructions. Same placement rules as `GroupName`."
+    },
+    "GroupName": {
+      "title": "GroupName",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "The group's name, shown to those who may see the group. The community's own record: never in the group's DID document or its credentials' subject beyond the group's DID. Plain text."
+    },
+    "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}$"
+    },
+    "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}$"
+    },
+    "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}$"
+    },
+    "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"
+      ]
+    },
+    "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."
+        }
+      }
+    }
+  }
+} 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": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Badges — Create — response payload",
+      "description": "The success response to a vtc/badges/create/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/badges/create/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "badge"
+      ],
+      "properties": {
+        "badge": {
+          "$ref": "#/$defs/Badge"
+        },
+        "group": {
+          "$ref": "#/$defs/Group",
+          "description": "The badge group, as vtc/groups/create answers it. Present exactly for a community badge."
+        },
+        "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-]+)+$"
+      }
+    },
+    "Group": {
+      "title": "Group",
+      "description": "A community group, as a caller who may see it sees it. Members a caller may not see are absent: `memberCount` only to those who may see the group's members, `managers` and `credentialAuthorityValidUntil` only to its managers.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "groupId",
+        "groupDid",
+        "name",
+        "kind",
+        "visibility",
+        "showMembers",
+        "issuesCredentials",
+        "carriesAuthority",
+        "createdAt"
+      ],
+      "properties": {
+        "groupId": {
+          "$ref": "#/$defs/GroupId"
+        },
+        "groupDid": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 2048,
+          "description": "The group's own DID, minted by the community's VTA for this group alone. It issues the group's membership credentials. Its DID document carries no name or description."
+        },
+        "name": {
+          "$ref": "#/$defs/GroupName"
+        },
+        "description": {
+          "$ref": "#/$defs/GroupDescription"
+        },
+        "kind": {
+          "$ref": "#/$defs/GroupKind"
+        },
+        "rule": {
+          "$ref": "#/$defs/DynamicRule",
+          "description": "Present exactly when `kind` is `dynamic`."
+        },
+        "joinPolicy": {
+          "$ref": "#/$defs/JoinPolicy",
+          "description": "Present exactly when `kind` is `static`."
+        },
+        "visibility": {
+          "$ref": "#/$defs/GroupAudience",
+          "description": "Who may see that the group exists, and its name and description."
+        },
+        "showMembers": {
+          "$ref": "#/$defs/GroupAudience",
+          "description": "Who may see the group's member list. Separate from `visibility`: a group everyone sees may show its members only to administrators. Never wider than `visibility`."
+        },
+        "issuesCredentials": {
+          "type": "boolean",
+          "description": "Whether the group's DID issues its members a membership credential. Default true."
+        },
+        "carriesAuthority": {
+          "type": "boolean",
+          "description": "`true` while the group has a `grants` or `role` binding. Such a group is `static` and `closed` for as long as it does."
+        },
+        "badgeId": {
+          "$ref": "#/$defs/BadgeId",
+          "description": "Present exactly when the group backs a community badge (vtc/badges/*): its managers are the badge's owners, its members the badge's holders, and its DID issues the badge credential in place of a membership credential. A badge group never carries authority, is not counted among the groups two members share, and is listed among the community's groups only to a caller who asks for badge groups (VTI-BDG-010 – VTI-BDG-012)."
+        },
+        "memberCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Active members. Only to callers who may see the member list."
+        },
+        "managers": {
+          "type": "array",
+          "maxItems": 256,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/EntryId"
+          },
+          "description": "Entries holding `vtc.groups.manage` qualified to this group, read from the access-control list. Informational: managers are appointed by an access-control grant (vtc/groups/managers/add), never by this record."
+        },
+        "credentialAuthorityValidUntil": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the community's authorization credential to the group expires. The community renews it well before."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "createdBy": {
+          "$ref": "#/$defs/EntryId",
+          "description": "The creating administrator's directory entry, where they have one."
+        },
+        "updatedAt": {
+          "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."
+        }
+      }
+    },
+    "GroupAudience": {
+      "title": "GroupAudience",
+      "description": "Who may see something about a group, narrowest first. `admins`: holders of `vtc.groups.manage` for the group (unqualified, or qualified `group:<groupId>`). `groupMembers`: the group's own members, and its managers. `members`: every active member of the community.",
+      "type": "string",
+      "enum": [
+        "admins",
+        "groupMembers",
+        "members"
+      ]
+    },
+    "JoinPolicy": {
+      "title": "JoinPolicy",
+      "description": "How a member enters a static group by themselves. `closed`: only a manager adds them. `request`: a member asks and a manager decides. `open`: a member joins at once, subject to the community's `groups` policy. A group carrying authority is always `closed`.",
+      "type": "string",
+      "enum": [
+        "closed",
+        "request",
+        "open"
+      ]
+    },
+    "DynamicRule": {
+      "title": "DynamicRule",
+      "description": "A dynamic group's membership rule: a member belongs when every condition holds and they have not opted out. The community evaluates it under its `groups` policy and recomputes membership whenever a fact it reads changes, always excluding opted-out entries.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "all"
+      ],
+      "properties": {
+        "all": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": {
+            "$ref": "#/$defs/RuleCondition"
+          }
+        }
+      }
+    },
+    "RuleCondition": {
+      "title": "RuleCondition",
+      "description": "One test over a verified fact about a member. `fact: role` tests the member's community role; `fact: field` tests an `admin`- or `credential`-sourced directory field named by `field`; `fact: personhood` tests whether a personhood assertion is on file; `fact: joinedAt` tests when they joined. A rule never reads a self-asserted (`member`-sourced) field: a member must not be able to join a group by editing their card.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "fact",
+        "op"
+      ],
+      "properties": {
+        "fact": {
+          "type": "string",
+          "enum": [
+            "role",
+            "field",
+            "personhood",
+            "joinedAt"
+          ]
+        },
+        "field": {
+          "$ref": "#/$defs/FieldKey",
+          "description": "Present exactly when `fact` is `field`."
+        },
+        "op": {
+          "type": "string",
+          "enum": [
+            "equals",
+            "oneOf",
+            "exists",
+            "before",
+            "after"
+          ],
+          "description": "`equals` compares with `value`; `oneOf` with any of `values`; `exists` needs neither; `before` and `after` compare a date fact with `value`."
+        },
+        "value": {
+          "anyOf": [
+            {
+              "type": "string",
+              "maxLength": 256
+            },
+            {
+              "type": "boolean"
+            }
+          ]
+        },
+        "values": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "type": "string",
+            "maxLength": 256
+          }
+        }
+      }
+    },
+    "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}$"
+    },
+    "GroupKind": {
+      "title": "GroupKind",
+      "description": "`static`: membership is explicit — added, joined, or granted on request. `dynamic`: membership is computed from `rule` over verified facts only; nobody is added by hand, but a member may opt out (vtc/groups/leave), an exclusion the rule cannot override, and undo it (vtc/groups/join). A dynamic group never confers authority. Fixed for the group's life.",
+      "type": "string",
+      "enum": [
+        "static",
+        "dynamic"
+      ]
+    },
+    "GroupDescription": {
+      "title": "GroupDescription",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "description": "What the group is for. Plain text; a reader MUST NOT treat it as instructions. Same placement rules as `GroupName`."
+    },
+    "GroupName": {
+      "title": "GroupName",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "The group's name, shown to those who may see the group. The community's own record: never in the group's DID document or its credentials' subject beyond the group's DID. Plain text."
+    },
+    "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}$"
+    },
+    "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}$"
+    },
+    "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}$"
+    },
+    "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"
+      ]
+    },
+    "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."
+        }
+      }
+    }
+  }
+} 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;