@cloudhal/core-contracts 0.3.3 → 0.3.5

package/schemas/.bundled/comment.schema.json

@@ -1,425 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cloudhal.dev/schemas/v1/comment.schema.json",
-  "title": "Comment",
-  "description": "A reader comment on a published content entry, as stored in D1 (outside the site graph), returned to people and agents, and exported (RFC-0007). It is not a graph node: it never enters a snapshot, a diff or a site bundle, and a content rollback never changes it. The record carries no personal data beyond the display name the commenter chose: an email address, an IP address or its hash, a user agent and a proof-of-work challenge live in separate columns and tables that this contract cannot express (additionalProperties: false), so no reader of the contract — Studio lists, MCP tools, exports — can leak them. Text is plain text; renderers escape it and turn only https links into anchors with rel=\"ugc nofollow noopener noreferrer\".",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "schemaVersion",
-    "id",
-    "siteId",
-    "nodeId",
-    "source",
-    "author",
-    "status",
-    "createdAt",
-    "rev"
-  ],
-  "properties": {
-    "schemaVersion": {
-      "$ref": "#/$defs/SchemaVersion"
-    },
-    "id": {
-      "$ref": "#/$defs/CommentId"
-    },
-    "siteId": {
-      "$ref": "#/$defs/Id"
-    },
-    "nodeId": {
-      "$ref": "#/$defs/Id",
-      "description": "The content entry the comment belongs to, by id, so threads survive slug changes (RFC-0002)."
-    },
-    "parentId": {
-      "$ref": "#/$defs/CommentId",
-      "description": "The comment this one is nested under for display. Absent for a top-level comment. In v1 the tree is two levels deep: a parent is always top-level, and a reply to a reply is nested under the same top-level comment with `inReplyToId` pointing at the comment it answers."
-    },
-    "inReplyToId": {
-      "$ref": "#/$defs/CommentId",
-      "description": "The comment this one answers when that is not `parentId` itself (a reply to a reply). Only with `parentId`, in the same thread."
-    },
-    "source": {
-      "type": "string",
-      "description": "Where the comment came from: `native` (the site's own form or Studio), `import` (an importer; see `origin`). `webmention` and `activitypub` are reserved for later RFCs and are refused by v1 writers.",
-      "enum": [
-        "native",
-        "import",
-        "webmention",
-        "activitypub"
-      ]
-    },
-    "origin": {
-      "$ref": "#/$defs/CommentOrigin"
-    },
-    "author": {
-      "$ref": "#/$defs/CommentAuthor"
-    },
-    "body": {
-      "$ref": "#/$defs/CommentBody"
-    },
-    "status": {
-      "$ref": "#/$defs/CommentStatus"
-    },
-    "labels": {
-      "type": "array",
-      "description": "Advisory labels from rules, classifiers, agents and people. Labels never change what readers see; only a status change does.",
-      "items": {
-        "$ref": "#/$defs/CommentLabel"
-      },
-      "maxItems": 32
-    },
-    "moderation": {
-      "$ref": "#/$defs/CommentModeration"
-    },
-    "createdAt": {
-      "$ref": "#/$defs/Timestamp"
-    },
-    "editedAt": {
-      "$ref": "#/$defs/Timestamp",
-      "description": "Set when the text changed after it was first stored (v1.1 edit window; staff replies edited in Studio)."
-    },
-    "rev": {
-      "$ref": "#/$defs/Revision"
-    }
-  },
-  "$defs": {
-    "Actor": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "kind",
-        "id"
-      ],
-      "properties": {
-        "kind": {
-          "$ref": "#/$defs/ActorKind"
-        },
-        "id": {
-          "$ref": "#/$defs/Id"
-        },
-        "name": {
-          "type": "string",
-          "maxLength": 200
-        }
-      }
-    },
-    "ActorKind": {
-      "type": "string",
-      "description": "Who performed an action. Humans and agents share one actor model so the policy engine treats them uniformly.",
-      "enum": [
-        "human",
-        "agent",
-        "system"
-      ]
-    },
-    "CommentAuthor": {
-      "description": "Who wrote the comment, discriminated by `kind`. There is deliberately no email, address or account handle here.",
-      "oneOf": [
-        {
-          "type": "object",
-          "title": "GuestCommentAuthor",
-          "description": "A guest: only the display name they typed. Guest comments are always held for moderation in v1.",
-          "additionalProperties": false,
-          "required": [
-            "kind",
-            "name"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "guest"
-              ]
-            },
-            "name": {
-              "$ref": "#/$defs/CommentDisplayName"
-            }
-          }
-        },
-        {
-          "type": "object",
-          "title": "ReaderCommentAuthor",
-          "description": "A verified reader (v1.1: email code or magic link on the site's own host). `readerId` is the site's reader account id, never the email.",
-          "additionalProperties": false,
-          "required": [
-            "kind",
-            "readerId",
-            "name"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "reader"
-              ]
-            },
-            "readerId": {
-              "$ref": "#/$defs/Id"
-            },
-            "name": {
-              "$ref": "#/$defs/CommentDisplayName"
-            }
-          }
-        },
-        {
-          "type": "object",
-          "title": "StaffCommentAuthor",
-          "description": "A reply on the site's behalf. It is always attributed to a person (`personId` is a staff actor id, `user_…`): an agent may draft the text (`draftedBy`), but a person approved it. `draftedBy` names the agent that drafted the text, when one did (shown in Studio and the audit, not on the public page).",
-          "additionalProperties": false,
-          "required": [
-            "kind",
-            "personId",
-            "name",
-            "badge"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "staff"
-              ]
-            },
-            "personId": {
-              "type": "string",
-              "description": "The person who wrote or approved the reply.",
-              "pattern": "^user_[A-Za-z0-9]{6,32}$"
-            },
-            "name": {
-              "$ref": "#/$defs/CommentDisplayName"
-            },
-            "badge": {
-              "type": "string",
-              "description": "What the public page shows next to the name: `author` when the person wrote the entry, otherwise `team`.",
-              "enum": [
-                "author",
-                "team"
-              ]
-            },
-            "draftedBy": {
-              "$ref": "#/$defs/Actor"
-            }
-          }
-        },
-        {
-          "type": "object",
-          "title": "ErasedCommentAuthor",
-          "description": "The commenter's identity was erased on request (RFC-0007 privacy model). Pages show a localised \"Anonymous\".",
-          "additionalProperties": false,
-          "required": [
-            "kind"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "erased"
-              ]
-            }
-          }
-        }
-      ]
-    },
-    "CommentBody": {
-      "type": "object",
-      "description": "The comment text. v1 has only `text`: plain text with line breaks, no markup. A later RFC may add a restricted Markdown format. Absent only when the text was deleted (status `deleted`, or an erasure that removed the text); the record then stays as a tombstone while approved replies hang under it.",
-      "additionalProperties": false,
-      "required": [
-        "format",
-        "text"
-      ],
-      "properties": {
-        "format": {
-          "type": "string",
-          "enum": [
-            "text"
-          ]
-        },
-        "text": {
-          "type": "string",
-          "description": "NFC-normalised, CRLF turned into LF, trimmed: 1 to 5,000 characters. Tabs and line feeds are the only control characters allowed; bidirectional overrides are refused so a comment cannot disguise itself in Studio.",
-          "minLength": 1,
-          "maxLength": 5000,
-          "pattern": "^[^\\x00-\\x08\\x0B-\\x1F\\x7F\\u202A-\\u202E\\u2066-\\u2069]+$"
-        }
-      }
-    },
-    "CommentDisplayName": {
-      "type": "string",
-      "description": "Plain text chosen by the commenter (or the staff member's name), NFC-normalised and trimmed by the server: 1 to 80 characters, no control characters, no bidirectional overrides, no surrounding whitespace.",
-      "minLength": 1,
-      "maxLength": 80,
-      "pattern": "^[^\\s\\x00-\\x1F\\x7F\\u202A-\\u202E\\u2066-\\u2069](?:[^\\x00-\\x1F\\x7F\\u202A-\\u202E\\u2066-\\u2069]*[^\\s\\x00-\\x1F\\x7F\\u202A-\\u202E\\u2066-\\u2069])?$"
-    },
-    "CommentId": {
-      "type": "string",
-      "description": "A comment id: `cmt_` and 6 to 32 letters or digits.",
-      "pattern": "^cmt_[A-Za-z0-9]{6,32}$"
-    },
-    "CommentLabel": {
-      "type": "object",
-      "description": "An advisory label. `rule` labels come from the submission pipeline (word lists, link count, instruction-like text); `classifier` from an opt-in classifier (Workers AI, Akismet); `agent` from `label_comments`; `person` from Studio. `by` is the agent or person that set it (absent for rules and classifiers).",
-      "additionalProperties": false,
-      "required": [
-        "label",
-        "source",
-        "at"
-      ],
-      "properties": {
-        "label": {
-          "type": "string",
-          "enum": [
-            "spam-suspect",
-            "toxic",
-            "off-topic",
-            "question",
-            "needs-reply",
-            "praise",
-            "personal-data",
-            "links",
-            "watch-word",
-            "instruction-like"
-          ]
-        },
-        "source": {
-          "type": "string",
-          "enum": [
-            "rule",
-            "classifier",
-            "agent",
-            "person"
-          ]
-        },
-        "by": {
-          "$ref": "#/$defs/Actor"
-        },
-        "confidence": {
-          "type": "integer",
-          "description": "0 to 100, when the source reports one.",
-          "minimum": 0,
-          "maximum": 100
-        },
-        "at": {
-          "$ref": "#/$defs/Timestamp"
-        }
-      }
-    },
-    "CommentModeration": {
-      "type": "object",
-      "description": "The latest moderation decision, kept as a statement of reasons (EU DSA Art. 17). The full history is in `comment_events`. Approvals are always a person's decision; agents may only hide, mark as spam or hold.",
-      "additionalProperties": false,
-      "required": [
-        "action",
-        "actor",
-        "at",
-        "automated"
-      ],
-      "properties": {
-        "action": {
-          "type": "string",
-          "enum": [
-            "approve",
-            "hide",
-            "spam",
-            "hold",
-            "restore",
-            "delete",
-            "erase"
-          ]
-        },
-        "actor": {
-          "$ref": "#/$defs/Actor"
-        },
-        "at": {
-          "$ref": "#/$defs/Timestamp"
-        },
-        "reasonCode": {
-          "type": "string",
-          "description": "Required by writers for hide, spam, delete and erase.",
-          "enum": [
-            "spam",
-            "abuse",
-            "off-topic",
-            "personal-data",
-            "illegal-content",
-            "legal-order",
-            "author-request",
-            "erasure-request",
-            "duplicate",
-            "other"
-          ]
-        },
-        "note": {
-          "type": "string",
-          "description": "Free text from the moderator, plain text, at most 500 characters.",
-          "maxLength": 500,
-          "pattern": "^[^\\x00-\\x08\\x0B-\\x1F\\x7F\\u202A-\\u202E\\u2066-\\u2069]*$"
-        },
-        "automated": {
-          "type": "boolean",
-          "description": "True when the decision was taken without a person (an agent, a rule or a ban), as a statement of reasons must say."
-        }
-      }
-    },
-    "CommentOrigin": {
-      "type": "object",
-      "description": "For imported comments: the system and its id, so importers are idempotent.",
-      "additionalProperties": false,
-      "required": [
-        "system",
-        "id"
-      ],
-      "properties": {
-        "system": {
-          "type": "string",
-          "enum": [
-            "cloudhal",
-            "disqus",
-            "wordpress"
-          ]
-        },
-        "id": {
-          "type": "string",
-          "description": "The comment's id in that system: printable ASCII, at most 200 characters.",
-          "minLength": 1,
-          "maxLength": 200,
-          "pattern": "^[!-~]+$"
-        }
-      }
-    },
-    "CommentStatus": {
-      "type": "string",
-      "description": "Lifecycle. `pending` waits for a person (every guest comment starts here); `approved` is public; `hidden` is withdrawn and reversible; `spam` is never shown and is deleted after the retention period; `deleted` is a soft delete, hard-deleted after the retention period unless approved replies keep it as a tombstone.",
-      "enum": [
-        "pending",
-        "approved",
-        "hidden",
-        "spam",
-        "deleted"
-      ]
-    },
-    "Id": {
-      "type": "string",
-      "description": "Prefixed, URL-safe identifier, e.g. site_01HZX8K3Q9. The prefix names the entity kind; agents and the MCP server pass these as opaque handles.",
-      "pattern": "^[a-z]+_[A-Za-z0-9]{6,32}$",
-      "minLength": 8,
-      "maxLength": 48
-    },
-    "Revision": {
-      "type": "integer",
-      "description": "Monotonic per-node revision used for optimistic locking (compare-and-swap on write).",
-      "minimum": 0
-    },
-    "SchemaVersion": {
-      "type": "integer",
-      "description": "Version of this contract. Readers reject unknown versions; migrations move documents forward one version at a time.",
-      "enum": [
-        1
-      ]
-    },
-    "Timestamp": {
-      "type": "string",
-      "description": "RFC 3339 / ISO 8601 instant in UTC.",
-      "format": "date-time"
-    }
-  }
-}