@openvtc/trust-tasks 0.23.0 → 0.23.1

package/src/vtc/admin/actions/list/0.2/payload.ts

@@ -0,0 +1,825 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/admin/actions/list/0.2/payload.schema.json
+ */
+
+import type { Action_VtcAdminActionsV0_2 as Action, ActionId, DigestMultibase, Ext, Field, Summary } from "../../../../../_shared/components.js";
+
+
+/**
+ * Enumerate the administrative actions a Verifiable Trust Community holds that the caller is entitled to see, one page at a time, from one of four views. The single-record sibling is vtc/admin/actions/show/0.2. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface VTCAdminActionsListPayload {
+  /**
+   * `waitingForMe` — open actions on which the caller is an eligible approver or acknowledger and has not yet decided. `requestedByMe` — open actions the caller requested, including `coolingOff` actions that will land unless the caller cancels them. `history` — closed actions the caller requested, decided, or was the subject of, or (with the audit-read capability) any closed action, newest first. `all` — every action the caller may see, open and closed, including a `coolingOff` action that acts on the caller (`callerRole: subject`). A `coolingOff` action is never in `waitingForMe`: nobody decides it.
+   */
+  view: "waitingForMe" | "requestedByMe" | "history" | "all";
+  /**
+   * Only with `view: history`: return actions closed at or after this instant. Supplied with any other view it is refused with `invalidFilter` rather than ignored, so a caller never reads a silently unfiltered page as a filtered one.
+   */
+  since?: string;
+  /**
+   * Maximum number of actions in the page. The community MAY return fewer.
+   */
+  limit?: number;
+  /**
+   * Opaque continuation token from a previous page's `nextCursor`, valid only with the same `view` and `since` it was issued for.
+   */
+  cursor?: string;
+  ext?: Ext;
+}
+/**
+ * One page of actions and the caller's badge counts. Failures use trust-task-error, not this shape.
+ */
+export interface VTCAdminActionsListResponsePayload {
+  /**
+   * The page, in the view's order: open views by deadline soonest first — `expiresAt`, or `landsAt` for `coolingOff` — (actions with neither last, then by `createdAt`), `history` by `closedAt` newest first, `all` open-before-closed in those orders. An empty array is a successful answer: nothing in this view.
+   *
+   * @maxItems 100
+   */
+  actions: Action[];
+  /**
+   * Present when more actions follow. Pass it back as `cursor` with the same `view` and `since`.
+   */
+  nextCursor?: string;
+  /**
+   * Totals across the whole collection, not the page — what a console badge shows. Computed for the caller regardless of which `view` was requested.
+   */
+  counts: {
+    /**
+     * Open actions awaiting the caller's decision or acknowledgement.
+     */
+    waitingForMe: number;
+    /**
+     * Open actions the caller requested.
+     */
+    requestedByMe: number;
+  };
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Action, ActionId, DigestMultibase, Ext, Field, Summary };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/admin/actions/list/0.2" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCAdminActionsListPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/admin/actions/list/0.2#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCAdminActionsListResponsePayload;
+
+/**
+ * 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/admin/actions/list/0.2",
+  "title": "VTC Admin Actions — List — payload",
+  "description": "Enumerate the administrative actions a Verifiable Trust Community holds that the caller is entitled to see, one page at a time, from one of four views. The single-record sibling is vtc/admin/actions/show/0.2. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "view"
+  ],
+  "properties": {
+    "view": {
+      "type": "string",
+      "enum": [
+        "waitingForMe",
+        "requestedByMe",
+        "history",
+        "all"
+      ],
+      "description": "`waitingForMe` — open actions on which the caller is an eligible approver or acknowledger and has not yet decided. `requestedByMe` — open actions the caller requested, including `coolingOff` actions that will land unless the caller cancels them. `history` — closed actions the caller requested, decided, or was the subject of, or (with the audit-read capability) any closed action, newest first. `all` — every action the caller may see, open and closed, including a `coolingOff` action that acts on the caller (`callerRole: subject`). A `coolingOff` action is never in `waitingForMe`: nobody decides it."
+    },
+    "since": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Only with `view: history`: return actions closed at or after this instant. Supplied with any other view it is refused with `invalidFilter` rather than ignored, so a caller never reads a silently unfiltered page as a filtered one."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "default": 25,
+      "description": "Maximum number of actions in the page. The community MAY return fewer."
+    },
+    "cursor": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "Opaque continuation token from a previous page's `nextCursor`, valid only with the same `view` and `since` it was issued for."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Admin Actions — List — response payload",
+      "description": "One page of actions and the caller's badge counts. Failures use trust-task-error, not this shape.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "actions",
+        "counts"
+      ],
+      "properties": {
+        "actions": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "$ref": "#/$defs/Action"
+          },
+          "description": "The page, in the view's order: open views by deadline soonest first — `expiresAt`, or `landsAt` for `coolingOff` — (actions with neither last, then by `createdAt`), `history` by `closedAt` newest first, `all` open-before-closed in those orders. An empty array is a successful answer: nothing in this view."
+        },
+        "nextCursor": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "Present when more actions follow. Pass it back as `cursor` with the same `view` and `since`."
+        },
+        "counts": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "waitingForMe",
+            "requestedByMe"
+          ],
+          "description": "Totals across the whole collection, not the page — what a console badge shows. Computed for the caller regardless of which `view` was requested.",
+          "properties": {
+            "waitingForMe": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Open actions awaiting the caller's decision or acknowledgement."
+            },
+            "requestedByMe": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Open actions the caller requested."
+            }
+          }
+        },
+        "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-]+)+$"
+      }
+    },
+    "Action": {
+      "title": "Action",
+      "description": "One parked administrative operation, as the caller is entitled to see it. The same action reads differently to different callers only in `challenge` and `callerRole`, which are per-caller.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "actionId",
+        "category",
+        "kind",
+        "typeUri",
+        "requester",
+        "status",
+        "createdAt",
+        "approvals",
+        "summary",
+        "payload",
+        "payloadDigest",
+        "callerRole"
+      ],
+      "properties": {
+        "actionId": {
+          "$ref": "#/$defs/ActionId"
+        },
+        "category": {
+          "type": "string",
+          "enum": [
+            "approval",
+            "acknowledge",
+            "queue",
+            "coolingOff"
+          ],
+          "description": "`approval` — eligible approvers approve or decline, N-of-M; the operation executes when the threshold is met. `acknowledge` — an operation that already happened (an operator's offline or break-glass write) which every remaining administrator must acknowledge; there is nothing to approve or decline. `queue` — an existing human decision (for example a join review) surfaced in the same list, with a threshold of one. `coolingOff` — an operation with no eligible third party to consent, which lands by itself at `landsAt` unless its requester cancels it first; nobody approves, declines or acknowledges it."
+        },
+        "kind": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-z][a-zA-Z0-9.]*$",
+          "description": "The community's name for what kind of operation is parked, dotted and lowerCamelCase (`acl.grant.authority`, `member.join.review`). Selects the summary template. The set is OPEN: a renderer that does not recognise a kind still renders `summary` from its fields."
+        },
+        "typeUri": {
+          "type": "string",
+          "format": "uri",
+          "minLength": 1,
+          "description": "The Type URI of the parked operation — the Trust Task the community will execute when the action completes (for `coolingOff`, when it lands). Together with `payload` it is exactly what will run. For `acknowledge`, the Type URI of the operation that already took effect; an operator's offline write, which is a command on the community's host and has no Trust Task of its own, is named by the record type `https://trusttasks.org/spec/vtc/operator/offline-write/0.1`, and `payload` is then that record."
+        },
+        "requester": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "description": "VID of the party whose operation was parked. For `acknowledge`, the operator whose offline write is being acknowledged, where the community can attribute one. For `coolingOff`, the administrator whose operation will land — the only party who may cancel it."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "open",
+            "completed",
+            "declined",
+            "expired",
+            "cancelled",
+            "failed"
+          ],
+          "description": "`open` — awaiting decisions, or for `coolingOff` awaiting `landsAt`. `completed` — the threshold was met and the operation executed, a `coolingOff` operation landed, or, for `acknowledge`, every administrator acknowledged. `declined` — an eligible approver denied it. `expired` — it lapsed at `expiresAt`. `cancelled` — the requester withdrew it, or the community invalidated it (see `closedReason`). `failed` — the threshold was met or `landsAt` reached but the re-check at execution refused it, or execution itself failed; the operation did not take effect."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the operation was parked."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When an open action lapses. ALWAYS present for `approval`, whose open life is bounded (72 hours by default; the community configures it between 15 minutes and 14 days). Absent for an `acknowledge` or `queue` action that does not expire, and ALWAYS absent for `coolingOff`, which does not lapse but lands — see `landsAt`."
+        },
+        "landsAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When a `coolingOff` action lands: the instant from which the community executes the parked operation, after its execution-time re-check, unless the requester cancelled first. Present exactly when `category` is `coolingOff`. It is a deadline for the requester's cancellation, not for anyone's approval, and it is fixed when the action is parked: neither the requester nor the subject can move it."
+        },
+        "cancellableBy": {
+          "type": "string",
+          "enum": [
+            "requester"
+          ],
+          "description": "Who may withdraw the action with `vtc/admin/actions/cancel` while it is `open`. Present on every open `coolingOff` action, where it is `requester`: the operation lands unless its requester stops it, and nobody else — the subject included — can. A closed set so that a console can offer a cancel control without inferring it; future values would widen who may cancel and need a new version."
+        },
+        "closedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the action left `open`. Present exactly when `status` is not `open`."
+        },
+        "closedReason": {
+          "type": "string",
+          "enum": [
+            "thresholdMet",
+            "declined",
+            "expired",
+            "cancelledByRequester",
+            "invalidated",
+            "failedRecheck",
+            "acknowledged",
+            "landedAfterCoolingOff"
+          ],
+          "description": "Why the action closed. Present exactly when `status` is not `open`. `invalidated` — the community closed it because something it depended on stopped holding before the threshold or `landsAt` (an approver or the requester lost standing, the target state moved); `failedRecheck` — the threshold was met or `landsAt` reached but the execution-time re-check refused; `landedAfterCoolingOff` — a `coolingOff` action reached `landsAt` uncancelled and its operation executed (`status: completed`)."
+        },
+        "threshold": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The number of distinct approvals the operation needs. Present for `approval`; absent otherwise (a `queue` decision is one decision by construction, `acknowledge` needs every remaining administrator, and `coolingOff` needs no approval at all)."
+        },
+        "approvals": {
+          "type": "array",
+          "description": "The decisions in favour recorded so far — approvals for `approval` and `queue`, acknowledgements for `acknowledge` — one entry per distinct subject, in the order recorded. Empty while none has landed, and always empty for `coolingOff`, which takes no decisions.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "subject",
+              "at"
+            ],
+            "properties": {
+              "subject": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 2048,
+                "description": "VID of the approver or acknowledger, as proven by the decision's own proof."
+              },
+              "at": {
+                "type": "string",
+                "format": "date-time",
+                "description": "When the decision was recorded."
+              }
+            }
+          }
+        },
+        "approversRemaining": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many further distinct decisions the action needs while `open` — approvals for `approval`, acknowledgements for `acknowledge`. Lets a console say 'one more' without disclosing the eligible set. Absent for `coolingOff`, which waits on time, not on decisions."
+        },
+        "summary": {
+          "$ref": "#/$defs/Summary"
+        },
+        "payload": {
+          "type": "object",
+          "description": "The exact payload of the parked operation — the object `payloadDigest` is computed over and the one the community will execute. Carried so an approver can recompute the digest and re-derive every summary field from it rather than trusting the rendering (VTI-APV-013). Deliberately an open object: its shape is governed by the specification `typeUri` names, and a digest is checked over members exactly as received."
+        },
+        "payloadDigest": {
+          "$ref": "#/$defs/DigestMultibase",
+          "description": "Digest of `payload`, taken over its RFC 8785 (JCS) canonicalization. The community re-derives it from the payload it is about to execute and refuses on mismatch. The digest an approver signs over is the challenge-salted one of `task-consent/decision`, not this value; this one lets the approver check that `payload` is what was parked."
+        },
+        "challenge": {
+          "type": "string",
+          "minLength": 16,
+          "maxLength": 256,
+          "description": "Present ONLY on an action the CALLER may decide now — an `approval` or `queue` action on which the caller is an eligible approver who has not yet decided. Never present on `acknowledge` or `coolingOff`. Per-approver: two approvers are shown different challenges for the same action. Echoed verbatim in `task-consent/decision`'s `challenge`, which binds that decision to this approver and this action. Absent for everyone else, including the requester."
+        },
+        "callerRole": {
+          "type": "string",
+          "enum": [
+            "approver",
+            "requester",
+            "acknowledger",
+            "subject",
+            "observer"
+          ],
+          "description": "The caller's relation to this action. `approver` — an eligible approver (whether or not already decided). `requester` — the party whose operation was parked. `acknowledger` — an administrator expected to acknowledge it. `subject` — the party a `coolingOff` operation acts on, shown it so that they learn of it before it lands; a subject can neither decide nor cancel it. `observer` — none of these; seen only through the audit-read capability on a `history` or `all` view."
+        },
+        "requesterOpenActions": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many open actions the requester currently has at the community, this one included. For consent-fatigue display: an approver shown the twentieth request from one requester today should be able to see that it is the twentieth."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Summary": {
+      "title": "Summary",
+      "description": "What an approver is shown, rendered from the summary template for the action's `kind`. Title and effect are the template's prose; the fields are the payload values that prose is about, each located by pointer so a renderer can verify it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "title",
+        "fields",
+        "templateDigest"
+      ],
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "One-line heading from the template. Prose only: a renderer MUST NOT present the action from this text without the fields."
+        },
+        "effect": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "One or two sentences from the template saying what executing the operation will do."
+        },
+        "fields": {
+          "type": "object",
+          "description": "Named values the template displays, keyed by a lowerCamelCase field name. Each locates its value in `payload` by JSON Pointer.",
+          "propertyNames": {
+            "pattern": "^[a-z][a-zA-Z0-9]*$",
+            "maxLength": 64
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/Field"
+          }
+        },
+        "templateDigest": {
+          "$ref": "#/$defs/DigestMultibase",
+          "description": "Digest of the summary template this summary was rendered from, over its RFC 8785 (JCS) canonicalization. Pinned per `kind`: a renderer that holds the template for a kind refuses a summary naming a different digest, so the community cannot change what approvers are shown for a kind without that change being visible."
+        }
+      }
+    },
+    "Field": {
+      "title": "Field",
+      "description": "One displayed value, with where it comes from and how to render it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "pointer",
+        "format",
+        "value"
+      ],
+      "properties": {
+        "pointer": {
+          "type": "string",
+          "maxLength": 512,
+          "pattern": "^(/([^~/]|~[01])*)*$",
+          "description": "RFC 6901 JSON Pointer into the action's `payload`. The empty string addresses the whole payload."
+        },
+        "format": {
+          "type": "string",
+          "enum": [
+            "did",
+            "capabilityList",
+            "duration",
+            "datetime",
+            "text"
+          ],
+          "description": "How to render the value. `did` — a DID, shown in full or with a verified display name, never truncated to a prefix that two DIDs share. `capabilityList` — an array of capability names. `duration` — an ISO 8601 duration. `datetime` — an RFC 3339 date-time. `text` — anything else, rendered as literal text."
+        },
+        "value": {
+          "description": "The value found at `pointer` when the community rendered the summary. A renderer re-derives it from `payload` and refuses to render the action on any mismatch; it is carried so that a mismatch is detectable, not so that it can be trusted."
+        }
+      }
+    },
+    "DigestMultibase": {
+      "title": "DigestMultibase",
+      "description": "A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for `digestMultibase`, and the one `did:webvh` uses for its SCID and entry hashes.\n\nMultihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a `sha-256:`-style prefix hard-codes one algorithm into the wire contract and is non-conforming here.\n\nThis definition constrains the *encoding only*. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible.\n\nRestricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — `z` (base58btc) and `u` (base64url-no-pad). CID permits others but states that \"interoperability is not guaranteed between implementations using such values\", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with `did:key` and `did:webvh`.",
+      "type": "string",
+      "minLength": 16,
+      "pattern": "^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$",
+      "examples": [
+        "zQmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR"
+      ]
+    },
+    "ActionId": {
+      "title": "ActionId",
+      "description": "Opaque, community-minted identifier of one action. A consumer MUST NOT parse or order it; it is compared for equality only. Long enough to be unguessable, because a show of an id the caller may not see is answered `notFound` and an enumerable id would turn that answer into an oracle.",
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9._~:-]+$"
+    }
+  }
+} 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 Admin Actions — List — response payload",
+      "description": "One page of actions and the caller's badge counts. Failures use trust-task-error, not this shape.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "actions",
+        "counts"
+      ],
+      "properties": {
+        "actions": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "$ref": "#/$defs/Action"
+          },
+          "description": "The page, in the view's order: open views by deadline soonest first — `expiresAt`, or `landsAt` for `coolingOff` — (actions with neither last, then by `createdAt`), `history` by `closedAt` newest first, `all` open-before-closed in those orders. An empty array is a successful answer: nothing in this view."
+        },
+        "nextCursor": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "Present when more actions follow. Pass it back as `cursor` with the same `view` and `since`."
+        },
+        "counts": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "waitingForMe",
+            "requestedByMe"
+          ],
+          "description": "Totals across the whole collection, not the page — what a console badge shows. Computed for the caller regardless of which `view` was requested.",
+          "properties": {
+            "waitingForMe": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Open actions awaiting the caller's decision or acknowledgement."
+            },
+            "requestedByMe": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Open actions the caller requested."
+            }
+          }
+        },
+        "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-]+)+$"
+      }
+    },
+    "Action": {
+      "title": "Action",
+      "description": "One parked administrative operation, as the caller is entitled to see it. The same action reads differently to different callers only in `challenge` and `callerRole`, which are per-caller.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "actionId",
+        "category",
+        "kind",
+        "typeUri",
+        "requester",
+        "status",
+        "createdAt",
+        "approvals",
+        "summary",
+        "payload",
+        "payloadDigest",
+        "callerRole"
+      ],
+      "properties": {
+        "actionId": {
+          "$ref": "#/$defs/ActionId"
+        },
+        "category": {
+          "type": "string",
+          "enum": [
+            "approval",
+            "acknowledge",
+            "queue",
+            "coolingOff"
+          ],
+          "description": "`approval` — eligible approvers approve or decline, N-of-M; the operation executes when the threshold is met. `acknowledge` — an operation that already happened (an operator's offline or break-glass write) which every remaining administrator must acknowledge; there is nothing to approve or decline. `queue` — an existing human decision (for example a join review) surfaced in the same list, with a threshold of one. `coolingOff` — an operation with no eligible third party to consent, which lands by itself at `landsAt` unless its requester cancels it first; nobody approves, declines or acknowledges it."
+        },
+        "kind": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-z][a-zA-Z0-9.]*$",
+          "description": "The community's name for what kind of operation is parked, dotted and lowerCamelCase (`acl.grant.authority`, `member.join.review`). Selects the summary template. The set is OPEN: a renderer that does not recognise a kind still renders `summary` from its fields."
+        },
+        "typeUri": {
+          "type": "string",
+          "format": "uri",
+          "minLength": 1,
+          "description": "The Type URI of the parked operation — the Trust Task the community will execute when the action completes (for `coolingOff`, when it lands). Together with `payload` it is exactly what will run. For `acknowledge`, the Type URI of the operation that already took effect; an operator's offline write, which is a command on the community's host and has no Trust Task of its own, is named by the record type `https://trusttasks.org/spec/vtc/operator/offline-write/0.1`, and `payload` is then that record."
+        },
+        "requester": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "description": "VID of the party whose operation was parked. For `acknowledge`, the operator whose offline write is being acknowledged, where the community can attribute one. For `coolingOff`, the administrator whose operation will land — the only party who may cancel it."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "open",
+            "completed",
+            "declined",
+            "expired",
+            "cancelled",
+            "failed"
+          ],
+          "description": "`open` — awaiting decisions, or for `coolingOff` awaiting `landsAt`. `completed` — the threshold was met and the operation executed, a `coolingOff` operation landed, or, for `acknowledge`, every administrator acknowledged. `declined` — an eligible approver denied it. `expired` — it lapsed at `expiresAt`. `cancelled` — the requester withdrew it, or the community invalidated it (see `closedReason`). `failed` — the threshold was met or `landsAt` reached but the re-check at execution refused it, or execution itself failed; the operation did not take effect."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the operation was parked."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When an open action lapses. ALWAYS present for `approval`, whose open life is bounded (72 hours by default; the community configures it between 15 minutes and 14 days). Absent for an `acknowledge` or `queue` action that does not expire, and ALWAYS absent for `coolingOff`, which does not lapse but lands — see `landsAt`."
+        },
+        "landsAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When a `coolingOff` action lands: the instant from which the community executes the parked operation, after its execution-time re-check, unless the requester cancelled first. Present exactly when `category` is `coolingOff`. It is a deadline for the requester's cancellation, not for anyone's approval, and it is fixed when the action is parked: neither the requester nor the subject can move it."
+        },
+        "cancellableBy": {
+          "type": "string",
+          "enum": [
+            "requester"
+          ],
+          "description": "Who may withdraw the action with `vtc/admin/actions/cancel` while it is `open`. Present on every open `coolingOff` action, where it is `requester`: the operation lands unless its requester stops it, and nobody else — the subject included — can. A closed set so that a console can offer a cancel control without inferring it; future values would widen who may cancel and need a new version."
+        },
+        "closedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the action left `open`. Present exactly when `status` is not `open`."
+        },
+        "closedReason": {
+          "type": "string",
+          "enum": [
+            "thresholdMet",
+            "declined",
+            "expired",
+            "cancelledByRequester",
+            "invalidated",
+            "failedRecheck",
+            "acknowledged",
+            "landedAfterCoolingOff"
+          ],
+          "description": "Why the action closed. Present exactly when `status` is not `open`. `invalidated` — the community closed it because something it depended on stopped holding before the threshold or `landsAt` (an approver or the requester lost standing, the target state moved); `failedRecheck` — the threshold was met or `landsAt` reached but the execution-time re-check refused; `landedAfterCoolingOff` — a `coolingOff` action reached `landsAt` uncancelled and its operation executed (`status: completed`)."
+        },
+        "threshold": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The number of distinct approvals the operation needs. Present for `approval`; absent otherwise (a `queue` decision is one decision by construction, `acknowledge` needs every remaining administrator, and `coolingOff` needs no approval at all)."
+        },
+        "approvals": {
+          "type": "array",
+          "description": "The decisions in favour recorded so far — approvals for `approval` and `queue`, acknowledgements for `acknowledge` — one entry per distinct subject, in the order recorded. Empty while none has landed, and always empty for `coolingOff`, which takes no decisions.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "subject",
+              "at"
+            ],
+            "properties": {
+              "subject": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 2048,
+                "description": "VID of the approver or acknowledger, as proven by the decision's own proof."
+              },
+              "at": {
+                "type": "string",
+                "format": "date-time",
+                "description": "When the decision was recorded."
+              }
+            }
+          }
+        },
+        "approversRemaining": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many further distinct decisions the action needs while `open` — approvals for `approval`, acknowledgements for `acknowledge`. Lets a console say 'one more' without disclosing the eligible set. Absent for `coolingOff`, which waits on time, not on decisions."
+        },
+        "summary": {
+          "$ref": "#/$defs/Summary"
+        },
+        "payload": {
+          "type": "object",
+          "description": "The exact payload of the parked operation — the object `payloadDigest` is computed over and the one the community will execute. Carried so an approver can recompute the digest and re-derive every summary field from it rather than trusting the rendering (VTI-APV-013). Deliberately an open object: its shape is governed by the specification `typeUri` names, and a digest is checked over members exactly as received."
+        },
+        "payloadDigest": {
+          "$ref": "#/$defs/DigestMultibase",
+          "description": "Digest of `payload`, taken over its RFC 8785 (JCS) canonicalization. The community re-derives it from the payload it is about to execute and refuses on mismatch. The digest an approver signs over is the challenge-salted one of `task-consent/decision`, not this value; this one lets the approver check that `payload` is what was parked."
+        },
+        "challenge": {
+          "type": "string",
+          "minLength": 16,
+          "maxLength": 256,
+          "description": "Present ONLY on an action the CALLER may decide now — an `approval` or `queue` action on which the caller is an eligible approver who has not yet decided. Never present on `acknowledge` or `coolingOff`. Per-approver: two approvers are shown different challenges for the same action. Echoed verbatim in `task-consent/decision`'s `challenge`, which binds that decision to this approver and this action. Absent for everyone else, including the requester."
+        },
+        "callerRole": {
+          "type": "string",
+          "enum": [
+            "approver",
+            "requester",
+            "acknowledger",
+            "subject",
+            "observer"
+          ],
+          "description": "The caller's relation to this action. `approver` — an eligible approver (whether or not already decided). `requester` — the party whose operation was parked. `acknowledger` — an administrator expected to acknowledge it. `subject` — the party a `coolingOff` operation acts on, shown it so that they learn of it before it lands; a subject can neither decide nor cancel it. `observer` — none of these; seen only through the audit-read capability on a `history` or `all` view."
+        },
+        "requesterOpenActions": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many open actions the requester currently has at the community, this one included. For consent-fatigue display: an approver shown the twentieth request from one requester today should be able to see that it is the twentieth."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Summary": {
+      "title": "Summary",
+      "description": "What an approver is shown, rendered from the summary template for the action's `kind`. Title and effect are the template's prose; the fields are the payload values that prose is about, each located by pointer so a renderer can verify it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "title",
+        "fields",
+        "templateDigest"
+      ],
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "One-line heading from the template. Prose only: a renderer MUST NOT present the action from this text without the fields."
+        },
+        "effect": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "One or two sentences from the template saying what executing the operation will do."
+        },
+        "fields": {
+          "type": "object",
+          "description": "Named values the template displays, keyed by a lowerCamelCase field name. Each locates its value in `payload` by JSON Pointer.",
+          "propertyNames": {
+            "pattern": "^[a-z][a-zA-Z0-9]*$",
+            "maxLength": 64
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/Field"
+          }
+        },
+        "templateDigest": {
+          "$ref": "#/$defs/DigestMultibase",
+          "description": "Digest of the summary template this summary was rendered from, over its RFC 8785 (JCS) canonicalization. Pinned per `kind`: a renderer that holds the template for a kind refuses a summary naming a different digest, so the community cannot change what approvers are shown for a kind without that change being visible."
+        }
+      }
+    },
+    "Field": {
+      "title": "Field",
+      "description": "One displayed value, with where it comes from and how to render it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "pointer",
+        "format",
+        "value"
+      ],
+      "properties": {
+        "pointer": {
+          "type": "string",
+          "maxLength": 512,
+          "pattern": "^(/([^~/]|~[01])*)*$",
+          "description": "RFC 6901 JSON Pointer into the action's `payload`. The empty string addresses the whole payload."
+        },
+        "format": {
+          "type": "string",
+          "enum": [
+            "did",
+            "capabilityList",
+            "duration",
+            "datetime",
+            "text"
+          ],
+          "description": "How to render the value. `did` — a DID, shown in full or with a verified display name, never truncated to a prefix that two DIDs share. `capabilityList` — an array of capability names. `duration` — an ISO 8601 duration. `datetime` — an RFC 3339 date-time. `text` — anything else, rendered as literal text."
+        },
+        "value": {
+          "description": "The value found at `pointer` when the community rendered the summary. A renderer re-derives it from `payload` and refuses to render the action on any mismatch; it is carried so that a mismatch is detectable, not so that it can be trusted."
+        }
+      }
+    },
+    "DigestMultibase": {
+      "title": "DigestMultibase",
+      "description": "A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for `digestMultibase`, and the one `did:webvh` uses for its SCID and entry hashes.\n\nMultihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a `sha-256:`-style prefix hard-codes one algorithm into the wire contract and is non-conforming here.\n\nThis definition constrains the *encoding only*. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible.\n\nRestricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — `z` (base58btc) and `u` (base64url-no-pad). CID permits others but states that \"interoperability is not guaranteed between implementations using such values\", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with `did:key` and `did:webvh`.",
+      "type": "string",
+      "minLength": 16,
+      "pattern": "^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$",
+      "examples": [
+        "zQmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR"
+      ]
+    },
+    "ActionId": {
+      "title": "ActionId",
+      "description": "Opaque, community-minted identifier of one action. A consumer MUST NOT parse or order it; it is compared for equality only. Long enough to be unguessable, because a show of an id the caller may not see is answered `notFound` and an enumerable id would turn that answer into an oracle.",
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9._~:-]+$"
+    }
+  }
+} 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: false,
+  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: false,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;