@cloudhal/core-contracts 0.3.4 → 0.3.5

package/schemas/.bundled/automation.schema.json

@@ -1,334 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cloudhal.dev/schemas/v1/automation.schema.json",
-  "title": "Automation",
-  "description": "A recurring job on a site (RFC-0008), created by a person in Studio: either a built-in deterministic job that Cloudhal runs itself (reports, findings and notifications; it never publishes), or a scheduled agent task that an external agent picks up over MCP with the automation's own key, inside a run window, under a mode cap and budgets. No language model runs inside Cloudhal. Scheduling never grants rights: every call of a task runs with the key's scopes narrowed to its owner's current role. Automations live in D1 next to the graph; they are not graph nodes and are not part of site bundles.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "schemaVersion",
-    "id",
-    "siteId",
-    "name",
-    "job",
-    "recurrence",
-    "state",
-    "consecutiveFailures",
-    "owner",
-    "createdAt",
-    "updatedAt",
-    "rev"
-  ],
-  "properties": {
-    "schemaVersion": {
-      "$ref": "#/$defs/SchemaVersion"
-    },
-    "id": {
-      "$ref": "#/$defs/AutomationId"
-    },
-    "siteId": {
-      "$ref": "#/$defs/Id"
-    },
-    "name": {
-      "type": "string",
-      "minLength": 1,
-      "maxLength": 120,
-      "pattern": "^[^\\x00-\\x1F\\x7F\\u202A-\\u202E\\u2066-\\u2069]+$"
-    },
-    "job": {
-      "$ref": "#/$defs/AutomationJob"
-    },
-    "recurrence": {
-      "$ref": "#/$defs/AutomationRecurrence"
-    },
-    "state": {
-      "$ref": "#/$defs/AutomationState"
-    },
-    "pausedReason": {
-      "type": "string",
-      "description": "Why the automation is not `active`: a person paused it; its agent paused it; three consecutive failures; a run exceeded its budget; the site's kill switch; its key was revoked; its owner left or no longer holds the scopes it needs.",
-      "enum": [
-        "person",
-        "agent",
-        "failures",
-        "budget",
-        "kill-switch",
-        "key-revoked",
-        "owner-removed",
-        "role-changed"
-      ]
-    },
-    "consecutiveFailures": {
-      "type": "integer",
-      "minimum": 0
-    },
-    "owner": {
-      "$ref": "#/$defs/AutomationOwner"
-    },
-    "nextRunAt": {
-      "$ref": "#/$defs/Timestamp"
-    },
-    "createdAt": {
-      "$ref": "#/$defs/Timestamp"
-    },
-    "updatedAt": {
-      "$ref": "#/$defs/Timestamp"
-    },
-    "rev": {
-      "$ref": "#/$defs/Revision"
-    },
-    "metadata": {
-      "$ref": "#/$defs/Metadata"
-    }
-  },
-  "$defs": {
-    "AutomationBudget": {
-      "type": "object",
-      "description": "Per-run limits Cloudhal counts and enforces for an agent task: tool calls, mutations, approval requests filed and minutes since the run began. Exceeding one ends the run (`budget-exceeded`) and pauses the automation.",
-      "additionalProperties": false,
-      "required": [
-        "maxToolCalls",
-        "maxWrites",
-        "maxApprovalRequests",
-        "maxMinutes"
-      ],
-      "properties": {
-        "maxToolCalls": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 500
-        },
-        "maxWrites": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 200
-        },
-        "maxApprovalRequests": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 20
-        },
-        "maxMinutes": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 240
-        }
-      }
-    },
-    "AutomationId": {
-      "type": "string",
-      "description": "An automation id: `aut_` and 6 to 32 letters or digits.",
-      "pattern": "^aut_[A-Za-z0-9]{6,32}$"
-    },
-    "AutomationJob": {
-      "description": "What runs, discriminated by `kind`.",
-      "oneOf": [
-        {
-          "type": "object",
-          "title": "BuiltinAutomationJob",
-          "description": "A deterministic job Cloudhal runs itself, in bounded steps. Its outputs are findings, reports and Studio notifications; it never changes or publishes content.",
-          "additionalProperties": false,
-          "required": [
-            "kind",
-            "builtin"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "builtin"
-              ]
-            },
-            "builtin": {
-              "type": "string",
-              "enum": [
-                "broken-links",
-                "stale-content",
-                "feed-check",
-                "weekly-digest",
-                "cleanup"
-              ]
-            },
-            "staleAfterDays": {
-              "type": "integer",
-              "description": "`stale-content` only: entries not updated for this many days are listed for review.",
-              "minimum": 30,
-              "maximum": 1095
-            }
-          }
-        },
-        {
-          "type": "object",
-          "title": "AgentTaskAutomationJob",
-          "description": "A task an external agent performs over MCP. At each occurrence a run window opens for `windowMinutes`; the automation's key (`keyId`, owned by the automation's owner) is valid only inside an open run, which the agent starts with `begin_run` and ends with `end_run`. The run's mode is the key's effective mode capped by `modeCap`; it never waits for a person: calls that need one leave an approval request and the run ends. `readsUntrustedText` declares that the task reads visitor-supplied text (comments, 404 paths, fetched pages); such an automation's key cannot hold write scopes, and any run that reads such text is limited to reading, labelling and hiding from then on.",
-          "additionalProperties": false,
-          "required": [
-            "kind",
-            "keyId",
-            "instructions",
-            "modeCap",
-            "readsUntrustedText",
-            "windowMinutes",
-            "budget"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "agent-task"
-              ]
-            },
-            "keyId": {
-              "type": "string",
-              "pattern": "^[A-Za-z0-9_-]{6,64}$"
-            },
-            "instructions": {
-              "type": "string",
-              "description": "What the owner asks the agent to do, shown to the agent by `begin_run`. Plain text.",
-              "minLength": 1,
-              "maxLength": 2000,
-              "pattern": "^[^\\x00-\\x08\\x0B-\\x1F\\x7F\\u202A-\\u202E\\u2066-\\u2069]+$"
-            },
-            "skill": {
-              "type": "string",
-              "description": "A skill the run declares (its scopes and approval list narrow the run further).",
-              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
-              "maxLength": 64
-            },
-            "modeCap": {
-              "type": "string",
-              "description": "The most autonomous mode a run may use; never `bypass`.",
-              "enum": [
-                "plan",
-                "manual",
-                "edits",
-                "auto"
-              ]
-            },
-            "readsUntrustedText": {
-              "type": "boolean"
-            },
-            "windowMinutes": {
-              "type": "integer",
-              "minimum": 5,
-              "maximum": 240
-            },
-            "budget": {
-              "$ref": "#/$defs/AutomationBudget"
-            }
-          }
-        }
-      ]
-    },
-    "AutomationOwner": {
-      "type": "object",
-      "description": "The person who created the automation and owns its key (`user_…`). Agents never own automations.",
-      "additionalProperties": false,
-      "required": [
-        "id"
-      ],
-      "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^user_[A-Za-z0-9]{6,32}$"
-        },
-        "name": {
-          "type": "string",
-          "maxLength": 200
-        }
-      }
-    },
-    "AutomationRecurrence": {
-      "type": "object",
-      "description": "When the automation runs: the first occurrence as a wall-clock time in `timeZone`, repeated by `rule` (absent: once). Occurrences are computed in the zone, so \"Mondays 09:07\" stays 09:07 across daylight-saving changes; a time that does not exist on a given day (a spring-forward gap) runs at the next valid minute, and a time that occurs twice runs once, at the first (a documented deviation from RFC 5545 §3.3.10, which drops such occurrences). `preset` records which Studio choice produced the rule.",
-      "additionalProperties": false,
-      "required": [
-        "start",
-        "timeZone",
-        "preset"
-      ],
-      "properties": {
-        "start": {
-          "$ref": "#/$defs/LocalDateTime"
-        },
-        "timeZone": {
-          "$ref": "#/$defs/TimeZone"
-        },
-        "rule": {
-          "$ref": "#/$defs/AutomationRule"
-        },
-        "preset": {
-          "type": "string",
-          "enum": [
-            "once",
-            "hourly",
-            "daily",
-            "weekdays",
-            "weekly",
-            "monthly",
-            "custom"
-          ]
-        }
-      }
-    },
-    "AutomationRule": {
-      "type": "string",
-      "description": "The recurrence as an RFC 5545 RRULE value in Cloudhal's subset, without the `RRULE:` prefix: FREQ DAILY, WEEKLY or MONTHLY; INTERVAL; BYDAY (ordinals such as 2TU or -1FR only with MONTHLY); BYMONTHDAY (1–31 or -1); BYHOUR; BYMINUTE; COUNT or UNTIL. The pattern bounds the vocabulary; the parser refuses repeated parts, COUNT with UNTIL, ordinals outside MONTHLY and runs closer than the job's minimum interval.",
-      "maxLength": 300,
-      "pattern": "^FREQ=(?:DAILY|WEEKLY|MONTHLY)(?:;(?:INTERVAL=[1-9][0-9]{0,2}|BYDAY=(?:[+-]?[1-5])?(?:MO|TU|WE|TH|FR|SA|SU)(?:,(?:[+-]?[1-5])?(?:MO|TU|WE|TH|FR|SA|SU)){0,6}|BYMONTHDAY=(?:-1|[1-9]|[12][0-9]|3[01])(?:,(?:-1|[1-9]|[12][0-9]|3[01])){0,30}|BYHOUR=(?:[01]?[0-9]|2[0-3])(?:,(?:[01]?[0-9]|2[0-3])){0,23}|BYMINUTE=[0-5]?[0-9](?:,[0-5]?[0-9]){0,3}|COUNT=[1-9][0-9]{0,3}|UNTIL=[0-9]{8}T[0-9]{6}Z))*$"
-    },
-    "AutomationState": {
-      "type": "string",
-      "description": "`active` runs on its recurrence; `paused` and `auto-paused` (by failures or a budget) wait for a person to resume; `broken` needs a person to repair it (key revoked, owner gone); `ended` reached its COUNT or UNTIL.",
-      "enum": [
-        "active",
-        "paused",
-        "auto-paused",
-        "broken",
-        "ended"
-      ]
-    },
-    "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
-    },
-    "LocalDateTime": {
-      "type": "string",
-      "description": "A wall-clock date and time without an offset, to the minute (YYYY-MM-DDTHH:mm), as a person entered it; always paired with a TimeZone (RFC-0008).",
-      "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])T(?:[01][0-9]|2[0-3]):[0-5][0-9]$"
-    },
-    "Metadata": {
-      "type": "object",
-      "description": "Free-form string-to-string map for extensions. Keys should be namespaced (e.g. cloudhal.source).",
-      "additionalProperties": {
-        "type": "string"
-      }
-    },
-    "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"
-    },
-    "TimeZone": {
-      "type": "string",
-      "description": "IANA time zone name from the tz database (RFC-0008), e.g. Europe/Istanbul, America/Argentina/Buenos_Aires, Etc/GMT+3 or UTC. Wall-clock times a person enters are kept with their zone, so the instant is recomputed when governments change the rules. The pattern bounds the shape only; writers also check the name against the runtime's Intl zone list.",
-      "pattern": "^(?:UTC|[A-Z][A-Za-z_-]+(?:/[A-Za-z0-9_+-]+){1,2})$",
-      "maxLength": 64
-    }
-  }
-}

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

@@ -1,172 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cloudhal.dev/schemas/v1/comment-submission.schema.json",
-  "title": "CommentSubmission",
-  "description": "What a browser may send to the site Worker's comment endpoints (RFC-0007): `POST /__cloudhal/comments` (a comment) and `POST /__cloudhal/comments/report` (a report). Forms post application/x-www-form-urlencoded and the comments module posts JSON; the server builds this object from either (the endpoint sets `kind`, the server sets `schemaVersion`) and checks it with the precompiled validator before anything else reads it. Everything in it is untrusted. It is loose where the server normalises (it trims, NFC-normalises and re-checks text against the stored Comment contract) and strict where a browser has no business sending something: there is no field for a status, a site, an author kind, a label, an IP address or anything the server derives itself.",
-  "oneOf": [
-    {
-      "type": "object",
-      "title": "CommentPostSubmission",
-      "description": "A new comment or a reply.",
-      "additionalProperties": false,
-      "required": [
-        "schemaVersion",
-        "kind",
-        "nodeId",
-        "name",
-        "body"
-      ],
-      "properties": {
-        "schemaVersion": {
-          "$ref": "#/$defs/SchemaVersion"
-        },
-        "kind": {
-          "type": "string",
-          "enum": [
-            "comment"
-          ]
-        },
-        "nodeId": {
-          "$ref": "#/$defs/Id",
-          "description": "The entry commented on. The server accepts it only for a published entry with an open thread, and works out the page to return to itself."
-        },
-        "parentId": {
-          "$ref": "#/$defs/SubmissionCommentId",
-          "description": "The comment replied to; it must be approved and in the same thread. The server decides `parentId`/`inReplyToId` of the stored comment."
-        },
-        "name": {
-          "type": "string",
-          "description": "The display name as typed (the form says it is shown publicly).",
-          "minLength": 1,
-          "maxLength": 200
-        },
-        "email": {
-          "type": "string",
-          "description": "Optional and never shown. Kept only for moderation, erasure and export requests (v1.1: reply notifications after double opt-in).",
-          "maxLength": 254,
-          "pattern": "^[^\\s@\\x00-\\x1F\\x7F]{1,64}@[^\\s@\\x00-\\x1F\\x7F]{1,189}$"
-        },
-        "body": {
-          "type": "string",
-          "description": "The comment as typed; the server trims and normalises it, then requires 2 to 5,000 characters.",
-          "minLength": 1,
-          "maxLength": 20000
-        },
-        "challenge": {
-          "$ref": "#/$defs/SubmissionChallenge"
-        },
-        "solution": {
-          "$ref": "#/$defs/SubmissionSolution"
-        },
-        "turnstileToken": {
-          "$ref": "#/$defs/SubmissionTurnstileToken"
-        },
-        "website": {
-          "$ref": "#/$defs/SubmissionHoneypot"
-        }
-      }
-    },
-    {
-      "type": "object",
-      "title": "CommentReportSubmission",
-      "description": "A reader's notice that a comment breaks the site's rules or the law (EU DSA Art. 16). A report never hides anything by itself: it puts the comment in front of a person.",
-      "additionalProperties": false,
-      "required": [
-        "schemaVersion",
-        "kind",
-        "commentId",
-        "reason"
-      ],
-      "properties": {
-        "schemaVersion": {
-          "$ref": "#/$defs/SchemaVersion"
-        },
-        "kind": {
-          "type": "string",
-          "enum": [
-            "report"
-          ]
-        },
-        "commentId": {
-          "$ref": "#/$defs/SubmissionCommentId"
-        },
-        "reason": {
-          "type": "string",
-          "enum": [
-            "spam",
-            "abuse",
-            "personal-data",
-            "illegal-content",
-            "other"
-          ]
-        },
-        "details": {
-          "type": "string",
-          "description": "Why, as typed; at most 1,000 characters after normalising.",
-          "maxLength": 4000
-        },
-        "email": {
-          "type": "string",
-          "description": "Optional, never shown: where the site may answer the notice.",
-          "maxLength": 254,
-          "pattern": "^[^\\s@\\x00-\\x1F\\x7F]{1,64}@[^\\s@\\x00-\\x1F\\x7F]{1,189}$"
-        },
-        "challenge": {
-          "$ref": "#/$defs/SubmissionChallenge"
-        },
-        "solution": {
-          "$ref": "#/$defs/SubmissionSolution"
-        },
-        "turnstileToken": {
-          "$ref": "#/$defs/SubmissionTurnstileToken"
-        },
-        "website": {
-          "$ref": "#/$defs/SubmissionHoneypot"
-        }
-      }
-    }
-  ],
-  "$defs": {
-    "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
-    },
-    "SchemaVersion": {
-      "type": "integer",
-      "description": "Version of this contract. Readers reject unknown versions; migrations move documents forward one version at a time.",
-      "enum": [
-        1
-      ]
-    },
-    "SubmissionChallenge": {
-      "type": "string",
-      "description": "The signed proof-of-work challenge from `GET /__cloudhal/comments/challenge`, as issued (base64url segments joined by dots).",
-      "minLength": 16,
-      "maxLength": 512,
-      "pattern": "^[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*$"
-    },
-    "SubmissionCommentId": {
-      "type": "string",
-      "pattern": "^cmt_[A-Za-z0-9]{6,32}$"
-    },
-    "SubmissionHoneypot": {
-      "type": "string",
-      "description": "A field people never see. The schema accepts any short value so that a filled honeypot gets the same answer as a real submission (\"held for moderation\") and nothing is stored.",
-      "maxLength": 2048
-    },
-    "SubmissionSolution": {
-      "type": "string",
-      "description": "The counter that solves the challenge, in decimal.",
-      "pattern": "^(?:0|[1-9][0-9]{0,15})$"
-    },
-    "SubmissionTurnstileToken": {
-      "type": "string",
-      "description": "Cloudflare Turnstile's response token, when the site turned Turnstile on.",
-      "minLength": 1,
-      "maxLength": 2048
-    }
-  }
-}