{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://valkyrlabs.com/schemas/graymatter-swarm-v0.1.schema.json",
  "title": "GrayMatter SWARM Protocol v0.1 Event",
  "description": "Canonical event envelope for GrayMatter-backed SWARM coordination across ValkyrAI, ValorIDE, OpenClaw, Codex, Claude adapters, services, workflows, and human operators.",
  "type": "object",
  "required": [
    "protocol",
    "version",
    "eventId",
    "type",
    "timestamp",
    "source",
    "payload",
    "correlationId"
  ],
  "properties": {
    "protocol": {
      "const": "graymatter.swarm"
    },
    "version": {
      "const": "0.1"
    },
    "eventId": {
      "type": "string",
      "minLength": 8,
      "description": "Globally unique event identifier. UUID/ULID values are recommended."
    },
    "type": {
      "type": "string",
      "pattern": "^swarm\\.[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$",
      "description": "Dot-delimited event type such as swarm.task.assigned or swarm.command.ack."
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "source": {
      "$ref": "#/$defs/Endpoint"
    },
    "target": {
      "anyOf": [
        {
          "$ref": "#/$defs/Endpoint"
        },
        {
          "type": "null"
        }
      ]
    },
    "workspace": {
      "$ref": "#/$defs/Workspace"
    },
    "payload": {
      "$ref": "#/$defs/Payload"
    },
    "requiresAck": {
      "type": "boolean",
      "default": false
    },
    "correlationId": {
      "type": "string",
      "minLength": 1
    },
    "parentEventId": {
      "type": [
        "string",
        "null"
      ]
    },
    "ttlMs": {
      "type": "integer",
      "minimum": 0,
      "default": 300000
    },
    "priority": {
      "type": "string",
      "enum": [
        "low",
        "normal",
        "high",
        "urgent"
      ],
      "default": "normal"
    },
    "capability": {
      "$ref": "#/$defs/Capability"
    },
    "durability": {
      "$ref": "#/$defs/Durability"
    },
    "security": {
      "$ref": "#/$defs/Security"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "Endpoint": {
      "type": "object",
      "required": [
        "agentId",
        "agentType"
      ],
      "properties": {
        "agentId": {
          "type": "string",
          "minLength": 1,
          "description": "Stable SWARM identifier used in events, graph nodes, and task assignment."
        },
        "agentRecordId": {
          "type": "string",
          "minLength": 1,
          "description": "Durable ValkyrAI/GrayMatter Agent object id. Required for compliant registered agents; omitted only for human/system compatibility events."
        },
        "agentType": {
          "type": "string",
          "enum": [
            "agent",
            "codex",
            "openclaw",
            "valor",
            "valklaw",
            "valoride",
            "claude",
            "human",
            "native",
            "service",
            "valkyrai-native",
            "workflow"
          ]
        },
        "instanceId": {
          "type": "string"
        },
        "principalId": {
          "type": "string"
        },
        "displayName": {
          "type": "string"
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "Workspace": {
      "type": "object",
      "properties": {
        "organizationId": {
          "type": "string"
        },
        "repo": {
          "type": "string"
        },
        "project": {
          "type": "string"
        },
        "branch": {
          "type": "string"
        },
        "commit": {
          "type": "string"
        },
        "workflowId": {
          "type": "string"
        },
        "taskId": {
          "type": "string"
        },
        "environment": {
          "type": "string",
          "enum": [
            "local",
            "loki",
            "staging",
            "production",
            "offline",
            "unknown"
          ]
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "Payload": {
      "type": "object",
      "required": [
        "action",
        "data"
      ],
      "properties": {
        "action": {
          "type": "string",
          "minLength": 1
        },
        "data": {
          "type": "object",
          "additionalProperties": true
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    },
    "Capability": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "scope": {
          "type": "string"
        },
        "risk": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high",
            "critical"
          ]
        },
        "requiresHumanApproval": {
          "type": "boolean",
          "default": false
        },
        "allowedTargets": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "Durability": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "transient",
            "memory-entry",
            "swarm-task",
            "swarm-audit"
          ],
          "default": "transient"
        },
        "grayMatterObjectType": {
          "type": "string",
          "enum": [
            "SwarmAgent",
            "SwarmSession",
            "SwarmTask",
            "SwarmEvent",
            "SwarmCapability",
            "SwarmDeployment",
            "SwarmCrmAction",
            "SwarmCmsAction",
            "SwarmAuditRecord",
            "MemoryEntry",
            "GrayMatter",
            "SwarmOps"
          ]
        },
        "memoryEntryType": {
          "type": "string",
          "enum": [
            "decision",
            "todo",
            "context",
            "artifact",
            "preference"
          ]
        },
        "retention": {
          "type": "string"
        },
        "replayable": {
          "type": "boolean",
          "default": true
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "Security": {
      "type": "object",
      "properties": {
        "authContext": {
          "type": "string",
          "enum": [
            "jwt",
            "github",
            "local",
            "service-account",
            "human-approved",
            "unknown"
          ]
        },
        "rbac": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "deploymentTarget": {
          "type": "string",
          "enum": [
            "none",
            "loki",
            "production"
          ],
          "default": "none"
        },
        "productionAllowed": {
          "type": "boolean",
          "default": false
        },
        "containsSecrets": {
          "type": "boolean",
          "default": false
        },
        "signature": {
          "type": "string"
        },
        "encrypted": {
          "type": "boolean",
          "default": false
        },
        "policy": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    }
  }
}