{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://chorus.services/schemas/backbeat/statusclaim/v1.0.0",
  "title": "BACKBEAT StatusClaim (INT-B)",
  "description": "Status update message sent from agents to Reverb service during beat execution",
  "version": "1.0.0",
  "type": "object",
  "required": [
    "type",
    "agent_id",
    "beat_index", 
    "state",
    "hlc"
  ],
  "additionalProperties": false,
  "properties": {
    "type": {
      "type": "string",
      "const": "backbeat.statusclaim.v1",
      "description": "Message type identifier for StatusClaim v1"
    },
    "agent_id": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_:-]+$",
      "minLength": 1,
      "maxLength": 128,
      "description": "Unique identifier for the reporting agent (format: service:instance or agent:id)"
    },
    "task_id": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_:-]+$",
      "minLength": 1,
      "maxLength": 128,
      "description": "Optional task identifier if agent is working on a specific task"
    },
    "beat_index": {
      "type": "integer", 
      "minimum": 0,
      "maximum": 9223372036854775807,
      "description": "Beat index this status claim refers to (must match current or recent BeatFrame)"
    },
    "state": {
      "type": "string",
      "enum": [
        "idle",
        "planning", 
        "executing",
        "reviewing",
        "completed",
        "failed",
        "blocked",
        "helping"
      ],
      "description": "Current state of the agent"
    },
    "beats_left": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000,
      "description": "Estimated number of beats needed to complete current work (0 = done this beat)"
    },
    "progress": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "Progress percentage for current task/phase (0.0 = not started, 1.0 = complete)"
    },
    "notes": {
      "type": "string",
      "maxLength": 256,
      "description": "Brief human-readable status description or error message"
    },
    "hlc": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{4}:[0-9a-fA-F]{4}:[0-9a-fA-F]{4}$",
      "description": "Hybrid Logical Clock timestamp from the agent"
    },
    "resources": {
      "type": "object",
      "description": "Optional resource utilization information",
      "additionalProperties": false,
      "properties": {
        "cpu_percent": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 100.0,
          "description": "CPU utilization percentage"
        },
        "memory_mb": {
          "type": "integer",
          "minimum": 0,
          "description": "Memory usage in megabytes"
        },
        "disk_io_ops": {
          "type": "integer",
          "minimum": 0,
          "description": "Disk I/O operations since last beat"
        },
        "network_kb": {
          "type": "integer", 
          "minimum": 0,
          "description": "Network traffic in kilobytes since last beat"
        }
      }
    },
    "dependencies": {
      "type": "array",
      "maxItems": 50,
      "description": "List of agent IDs this agent is waiting on or helping",
      "items": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9_:-]+$",
        "maxLength": 128
      }
    },
    "metadata": {
      "type": "object",
      "description": "Optional metadata for extensions and debugging",
      "additionalProperties": true,
      "properties": {
        "agent_version": {
          "type": "string",
          "description": "Version of the agent software"
        },
        "error_code": {
          "type": "string",
          "description": "Structured error code if state is 'failed'"
        },
        "retry_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of retries attempted for current task"
        }
      }
    }
  },
  "examples": [
    {
      "type": "backbeat.statusclaim.v1",
      "agent_id": "search-indexer:worker-03",
      "task_id": "index-batch:20250905-120",
      "beat_index": 1337,
      "state": "executing",
      "beats_left": 3,
      "progress": 0.65,
      "notes": "processing batch 120/200",
      "hlc": "7ffd:0001:beef",
      "resources": {
        "cpu_percent": 85.0,
        "memory_mb": 2048,
        "disk_io_ops": 1250,
        "network_kb": 512
      }
    },
    {
      "type": "backbeat.statusclaim.v1", 
      "agent_id": "agent:backup-runner",
      "beat_index": 1338,
      "state": "failed",
      "beats_left": 0,
      "progress": 0.0,
      "notes": "connection timeout to storage backend",
      "hlc": "7ffe:0002:dead",
      "metadata": {
        "agent_version": "2.1.0",
        "error_code": "STORAGE_TIMEOUT",
        "retry_count": 3
      }
    },
    {
      "type": "backbeat.statusclaim.v1",
      "agent_id": "ml-trainer:gpu-node-1", 
      "beat_index": 1336,
      "state": "helping",
      "progress": 1.0,
      "notes": "completed own work, assisting node-2 with large model",
      "hlc": "7ffc:0005:cafe",
      "dependencies": ["ml-trainer:gpu-node-2"]
    }
  ]
}