{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://go-sip.local/contracts/proposals/task-discovery-v0.2-proposal.schema.json",
  "title": "Project-local single-response Dispatcher task discovery; external compatibility unverified",
  "oneOf": [
    {"$ref": "#/$defs/snapshot_response"},
    {"$ref": "#/$defs/changes_response"},
    {"$ref": "#/$defs/error_response"}
  ],
  "$defs": {
    "dispatcher_id": {
      "type": "string", "format": "uuid",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "cursor": {
      "type": "string", "minLength": 1, "maxLength": 512,
      "$comment": "Opaque SaaS change watermark; never compare numerically or derive from task_id."
    },
    "task": {
      "type": "object", "additionalProperties": false,
      "required": ["task_id", "tenant_id", "tenant_key", "status", "task_revision"],
      "properties": {
        "task_id": {"type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$"},
        "tenant_id": {"type": "string", "minLength": 1, "maxLength": 128},
        "tenant_key": {"type": "string", "minLength": 1, "maxLength": 196,
          "$comment": "Also enforce the UTF-8 byte limit and tenant_id mapping in business logic."},
        "status": {"enum": ["running", "paused", "stopped", "finished"]},
        "task_revision": {"type": "integer", "minimum": 1}
      }
    },
    "change": {
      "oneOf": [
        {
          "type": "object", "additionalProperties": false,
          "required": ["cursor", "operation", "task_id", "tenant_id", "tenant_key", "status", "task_revision"],
          "properties": {
            "cursor": {"$ref": "#/$defs/cursor"},
            "operation": {"enum": ["assigned", "updated"]},
            "task_id": {"type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$"},
            "tenant_id": {"type": "string", "minLength": 1, "maxLength": 128},
            "tenant_key": {"type": "string", "minLength": 1, "maxLength": 196},
            "status": {"enum": ["running", "paused", "stopped", "finished"]},
            "task_revision": {"type": "integer", "minimum": 1}
          }
        },
        {
          "type": "object", "additionalProperties": false,
          "required": ["cursor", "operation", "task_id", "tenant_id", "tenant_key"],
          "properties": {
            "cursor": {"$ref": "#/$defs/cursor"},
            "operation": {"const": "removed"},
            "task_id": {"type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$"},
            "tenant_id": {"type": "string", "minLength": 1, "maxLength": 128},
            "tenant_key": {"type": "string", "minLength": 1, "maxLength": 196}
          }
        }
      ]
    },
    "snapshot_response": {
      "type": "object", "additionalProperties": false,
      "required": ["schema_version", "dispatcher_id", "cursor", "tasks"],
      "properties": {
        "schema_version": {"const": "task-discovery.v0.2-proposal"},
        "dispatcher_id": {"$ref": "#/$defs/dispatcher_id"},
        "cursor": {"$ref": "#/$defs/cursor"},
        "tasks": {"type": "array", "maxItems": 256, "items": {"$ref": "#/$defs/task"}}
      },
      "$comment": "No pagination or queue address in the body. Persist the entire consistent response before advancing the cursor."
    },
    "changes_response": {
      "type": "object", "additionalProperties": false,
      "required": ["schema_version", "dispatcher_id", "next_cursor", "changes"],
      "properties": {
        "schema_version": {"const": "task-discovery.v0.2-proposal"},
        "dispatcher_id": {"$ref": "#/$defs/dispatcher_id"},
        "next_cursor": {"$ref": "#/$defs/cursor"},
        "changes": {"type": "array", "maxItems": 256, "items": {"$ref": "#/$defs/change"}}
      },
      "$comment": "No change: changes=[] and next_cursor=request after. An unrepresentable complete change set requires HTTP 410 cursor_expired, never a partial 200."
    },
    "error_response": {
      "type": "object", "additionalProperties": false,
      "required": ["schema_version", "resource", "error"],
      "properties": {
        "schema_version": {"const": "task-discovery.v0.2-proposal"},
        "resource": {"const": "error"},
        "error": {
          "type": "object", "additionalProperties": false,
          "required": ["code", "message"],
          "properties": {
            "code": {"enum": ["invalid_cursor", "cursor_expired", "unauthorized", "dispatcher_not_authorized", "service_unavailable"]},
            "message": {"type": "string", "minLength": 1, "maxLength": 256}
          }
        }
      }
    }
  }
}