@openvtc/trust-tasks 0.16.8 → 0.16.9

package/src/rooms/records/curate/0.1/payload.ts

@@ -0,0 +1,357 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/rooms/records/curate/0.1/payload.schema.json
+ */
+
+import type { AuthorityPresentation, Ext } from "../../../../_shared/components.js";
+
+
+/**
+ * A member curates a record: demotes it, retracts it, restores it from demotion, or pins it. Distinct from `rooms/records/put`, which replaces content — curation changes a record's standing in the room without a member having to rewrite it, and `curate` is a separate authority action so a community can grant one without the other.
+ */
+export type RoomsRecordsCuratePayload = {
+  [k: string]: unknown | undefined;
+} & {
+  /**
+   * The room's identifier. A host verifies the presentation against credentials issued by this identifier, never against a member list of its own.
+   */
+  roomId: string;
+  /**
+   * The record to curate.
+   */
+  key: string;
+  /**
+   * Must confer the `curate` action at this room's scope. Deliberately not implied by `write`: curation is judgement over what a room's shared knowledge is worth, which is a different grant from the ability to add to it.
+   */
+  presentation: AuthorityPresentation;
+  /**
+   * The standing to move the record to. `deprecated` demotes it — the body is retained and a recalling agent MUST treat it as demoted rather than hidden. `retracted` is a tombstone: the body is dropped and the key, version and epoch remain so incremental sync converges. `active` restores a `deprecated` record; it MUST NOT be accepted for a `retracted` one, whose body is already gone and cannot be restored by a status change.
+   */
+  status?: "active" | "deprecated" | "retracted";
+  /**
+   * Whether the record is pinned. Orthogonal to `status` — a pinned record is still active, deprecated or retracted — because pinning answers 'what matters here' and status answers 'is this still current'. Omit to leave unchanged.
+   */
+  pinned?: boolean;
+  /**
+   * Why, for the room's audit trail. A retraction without a reason is the one a member cannot interpret later.
+   */
+  reason?: string;
+  /**
+   * Optional precondition: the record's current version. Curation assigns a new version — a demotion other members must converge on is a change like any other — so a caller that read a record before deciding to curate it can require that nothing has replaced it since.
+   */
+  expectedVersion?: number;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+};
+
+/**
+ * Success response to rooms/records/curate. Type https://trusttasks.org/spec/rooms/records/curate/0.1#response.
+ */
+export interface RoomsRecordsCurateResponsePayload {
+  /**
+   * The record curated.
+   */
+  key: string;
+  /**
+   * The version the curation assigned. A caller syncing on `sinceVersion` sees the change at this version.
+   */
+  version: number;
+  /**
+   * The record's standing after the operation.
+   */
+  status: "active" | "deprecated" | "retracted";
+  /**
+   * Whether the record is pinned after the operation.
+   */
+  pinned?: boolean;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { AuthorityPresentation, Ext };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/rooms/records/curate/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = RoomsRecordsCuratePayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/records/curate/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = RoomsRecordsCurateResponsePayload;
+
+/**
+ * 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/rooms/records/curate/0.1",
+  "title": "Rooms Records Curate — payload",
+  "description": "A member curates a record: demotes it, retracts it, restores it from demotion, or pins it. Distinct from `rooms/records/put`, which replaces content — curation changes a record's standing in the room without a member having to rewrite it, and `curate` is a separate authority action so a community can grant one without the other.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "roomId",
+    "key",
+    "presentation"
+  ],
+  "properties": {
+    "roomId": {
+      "type": "string",
+      "description": "The room's identifier. A host verifies the presentation against credentials issued by this identifier, never against a member list of its own."
+    },
+    "key": {
+      "type": "string",
+      "maxLength": 512,
+      "description": "The record to curate."
+    },
+    "presentation": {
+      "$ref": "#/$defs/AuthorityPresentation",
+      "description": "Must confer the `curate` action at this room's scope. Deliberately not implied by `write`: curation is judgement over what a room's shared knowledge is worth, which is a different grant from the ability to add to it."
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "active",
+        "deprecated",
+        "retracted"
+      ],
+      "description": "The standing to move the record to. `deprecated` demotes it — the body is retained and a recalling agent MUST treat it as demoted rather than hidden. `retracted` is a tombstone: the body is dropped and the key, version and epoch remain so incremental sync converges. `active` restores a `deprecated` record; it MUST NOT be accepted for a `retracted` one, whose body is already gone and cannot be restored by a status change."
+    },
+    "pinned": {
+      "type": "boolean",
+      "description": "Whether the record is pinned. Orthogonal to `status` — a pinned record is still active, deprecated or retracted — because pinning answers 'what matters here' and status answers 'is this still current'. Omit to leave unchanged."
+    },
+    "reason": {
+      "type": "string",
+      "maxLength": 512,
+      "description": "Why, for the room's audit trail. A retraction without a reason is the one a member cannot interpret later."
+    },
+    "expectedVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional precondition: the record's current version. Curation assigns a new version — a demotion other members must converge on is a change like any other — so a caller that read a record before deciding to curate it can require that nothing has replaced it since."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "anyOf": [
+    {
+      "required": [
+        "status"
+      ]
+    },
+    {
+      "required": [
+        "pinned"
+      ]
+    }
+  ],
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Rooms Records Curate — response payload",
+      "description": "Success response to rooms/records/curate. Type https://trusttasks.org/spec/rooms/records/curate/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "version",
+        "status"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "The record curated."
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The version the curation assigned. A caller syncing on `sinceVersion` sees the change at this version."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "active",
+            "deprecated",
+            "retracted"
+          ],
+          "description": "The record's standing after the operation."
+        },
+        "pinned": {
+          "type": "boolean",
+          "description": "Whether the record is pinned after the operation."
+        },
+        "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-]+)+$"
+      }
+    },
+    "AuthorityPresentation": {
+      "title": "AuthorityPresentation",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "membership",
+        "authority"
+      ],
+      "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier.",
+      "properties": {
+        "membership": {
+          "type": "string",
+          "description": "The presenter's membership credential for this room, or — on a `private` room — a zero-knowledge presentation of it. Serialized per the governing profile."
+        },
+        "authority": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "string"
+          },
+          "description": "The authority chain, LEAF FIRST: the first element is the credential being relied on and the last MUST be one issued by the room itself. Every link the presenter relies on is present, because the host will not fetch one. Capped at 8: verification is linear in chain length and runs on every operation, so an unbounded chain is a denial-of-service surface against the host. The known uses need 2 to 3 — a person attenuating to an agent, and that agent to a sub-agent."
+        },
+        "subjectBinding": {
+          "type": "string",
+          "description": "REQUIRED on a `private` room, where the subject identifier is withheld: a proof that the membership credential and the authority chain's leaf describe the SAME subject. Without it two parties pool credentials — one contributes membership, the other authority — and the combination verifies as a single party holding both. A host MUST refuse a private-room presentation that omits this."
+        }
+      }
+    }
+  }
+} 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": "Rooms Records Curate — response payload",
+      "description": "Success response to rooms/records/curate. Type https://trusttasks.org/spec/rooms/records/curate/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "version",
+        "status"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "The record curated."
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The version the curation assigned. A caller syncing on `sinceVersion` sees the change at this version."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "active",
+            "deprecated",
+            "retracted"
+          ],
+          "description": "The record's standing after the operation."
+        },
+        "pinned": {
+          "type": "boolean",
+          "description": "Whether the record is pinned after the operation."
+        },
+        "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-]+)+$"
+      }
+    },
+    "AuthorityPresentation": {
+      "title": "AuthorityPresentation",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "membership",
+        "authority"
+      ],
+      "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier.",
+      "properties": {
+        "membership": {
+          "type": "string",
+          "description": "The presenter's membership credential for this room, or — on a `private` room — a zero-knowledge presentation of it. Serialized per the governing profile."
+        },
+        "authority": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "string"
+          },
+          "description": "The authority chain, LEAF FIRST: the first element is the credential being relied on and the last MUST be one issued by the room itself. Every link the presenter relies on is present, because the host will not fetch one. Capped at 8: verification is linear in chain length and runs on every operation, so an unbounded chain is a denial-of-service surface against the host. The known uses need 2 to 3 — a person attenuating to an agent, and that agent to a sub-agent."
+        },
+        "subjectBinding": {
+          "type": "string",
+          "description": "REQUIRED on a `private` room, where the subject identifier is withheld: a proof that the membership credential and the authority chain's leaf describe the SAME subject. Without it two parties pool credentials — one contributes membership, the other authority — and the combination verifies as a single party holding both. A host MUST refuse a private-room presentation that omits this."
+        }
+      }
+    }
+  }
+} 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;