tony/BACKBEAT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backbeat: add module sources

Browse Source
This commit is contained in:
anthonyrawlins
2025-10-17 08:56:25 +11:00
parent 627d15b3f7
commit 4b4eb16efb
48 changed files with 11636 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
contracts/schemas/barreport-v1.schema.json Normal file
View File

@@ -0,0 +1,267 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://chorus.services/schemas/backbeat/barreport/v1.0.0",
"title": "BACKBEAT BarReport (INT-C)",
"description": "Periodic report from Reverb service summarizing agent activity over a bar (120 beats)",
"version": "1.0.0",
"type": "object",
"required": [
"type",
"window_id",
"from_beat",
"to_beat",
"agents_reporting",
"on_time_reviews",
"help_promises_fulfilled",
"secret_rotations_ok",
"tempo_drift_ms"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "backbeat.barreport.v1",
"description": "Message type identifier for BarReport v1"
},
"window_id": {
"type": "string",
"pattern": "^[0-9a-fA-F]{32}$",
"description": "Unique identifier for this reporting window"
},
"from_beat": {
"type": "integer",
"minimum": 0,
"maximum": 9223372036854775807,
"description": "Starting beat index for this report (inclusive)"
},
"to_beat": {
"type": "integer",
"minimum": 0,
"maximum": 9223372036854775807,
"description": "Ending beat index for this report (inclusive)"
},
"agents_reporting": {
"type": "integer",
"minimum": 0,
"description": "Total number of unique agents that sent status claims during this window"
},
"on_time_reviews": {
"type": "integer",
"minimum": 0,
"description": "Number of agents that completed review phase within deadline"
},
"help_promises_fulfilled": {
"type": "integer",
"minimum": 0,
"description": "Number of successful help/collaboration completions"
},
"secret_rotations_ok": {
"type": "boolean",
"description": "True if all required credential rotations completed successfully"
},
"tempo_drift_ms": {
"type": "number",
"description": "Average timing drift in milliseconds (positive = running behind, negative = ahead)"
},
"issues": {
"type": "array",
"maxItems": 100,
"description": "List of significant issues or anomalies detected during this window",
"items": {
"type": "object",
"required": ["severity", "category", "count"],
"additionalProperties": false,
"properties": {
"severity": {
"type": "string",
"enum": ["info", "warning", "error", "critical"],
"description": "Issue severity level"
},
"category": {
"type": "string",
"enum": [
"timing",
"failed_tasks",
"missing_agents",
"resource_exhaustion",
"network_partition",
"credential_failure",
"data_corruption",
"unknown"
],
"description": "Issue category for automated handling"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Number of occurrences of this issue type"
},
"description": {
"type": "string",
"maxLength": 512,
"description": "Human-readable description of the issue"
},
"affected_agents": {
"type": "array",
"maxItems": 50,
"description": "List of agent IDs affected by this issue",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:-]+$",
"maxLength": 128
}
},
"first_seen_beat": {
"type": "integer",
"minimum": 0,
"description": "Beat index when this issue was first detected"
},
"last_seen_beat": {
"type": "integer",
"minimum": 0,
"description": "Beat index when this issue was last seen"
}
}
}
},
"performance": {
"type": "object",
"description": "Performance metrics for this reporting window",
"additionalProperties": false,
"properties": {
"avg_response_time_ms": {
"type": "number",
"minimum": 0,
"description": "Average response time for status claims in milliseconds"
},
"p95_response_time_ms": {
"type": "number",
"minimum": 0,
"description": "95th percentile response time for status claims"
},
"total_tasks_completed": {
"type": "integer",
"minimum": 0,
"description": "Total number of tasks completed during this window"
},
"total_tasks_failed": {
"type": "integer",
"minimum": 0,
"description": "Total number of tasks that failed during this window"
},
"peak_concurrent_agents": {
"type": "integer",
"minimum": 0,
"description": "Maximum number of agents active simultaneously"
},
"network_bytes_transferred": {
"type": "integer",
"minimum": 0,
"description": "Total network bytes transferred by all agents"
}
}
},
"health_indicators": {
"type": "object",
"description": "Cluster health indicators",
"additionalProperties": false,
"properties": {
"cluster_sync_score": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"description": "How well synchronized the cluster is (1.0 = perfect sync)"
},
"resource_utilization": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"description": "Average resource utilization across all agents"
},
"collaboration_efficiency": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"description": "How effectively agents are helping each other"
},
"error_rate": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"description": "Proportion of beats that had errors"
}
}
},
"metadata": {
"type": "object",
"description": "Optional metadata for extensions and debugging",
"additionalProperties": true,
"properties": {
"reverb_version": {
"type": "string",
"description": "Version of the Reverb service generating this report"
},
"report_generation_time_ms": {
"type": "number",
"minimum": 0,
"description": "Time taken to generate this report"
},
"next_window_id": {
"type": "string",
"pattern": "^[0-9a-fA-F]{32}$",
"description": "Window ID for the next reporting period"
}
}
}
},
"examples": [
{
"type": "backbeat.barreport.v1",
"window_id": "7e9b0e6c4c9a4e59b7f2d9a3c1b2e4d5",
"from_beat": 240,
"to_beat": 359,
"agents_reporting": 978,
"on_time_reviews": 942,
"help_promises_fulfilled": 87,
"secret_rotations_ok": true,
"tempo_drift_ms": 7.3,
"issues": [
{
"severity": "warning",
"category": "timing",
"count": 12,
"description": "Some agents consistently reporting 50ms+ late",
"affected_agents": ["worker:batch-03", "indexer:shard-7"],
"first_seen_beat": 245,
"last_seen_beat": 358
}
],
"performance": {
"avg_response_time_ms": 45.2,
"p95_response_time_ms": 125.7,
"total_tasks_completed": 15678,
"total_tasks_failed": 23,
"peak_concurrent_agents": 1203,
"network_bytes_transferred": 67890123
},
"health_indicators": {
"cluster_sync_score": 0.94,
"resource_utilization": 0.67,
"collaboration_efficiency": 0.89,
"error_rate": 0.001
}
},
{
"type": "backbeat.barreport.v1",
"window_id": "a1b2c3d4e5f6789012345678901234ab",
"from_beat": 0,
"to_beat": 119,
"agents_reporting": 150,
"on_time_reviews": 147,
"help_promises_fulfilled": 12,
"secret_rotations_ok": true,
"tempo_drift_ms": -2.1,
"issues": []
}
]
}

121
contracts/schemas/beatframe-v1.schema.json Normal file
View File

@@ -0,0 +1,121 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://chorus.services/schemas/backbeat/beatframe/v1.0.0",
"title": "BACKBEAT BeatFrame (INT-A)",
"description": "Beat synchronization message broadcast from Pulse service to all BACKBEAT-enabled services",
"version": "1.0.0",
"type": "object",
"required": [
"type",
"cluster_id",
"beat_index",
"downbeat",
"phase",
"hlc",
"deadline_at",
"tempo_bpm",
"window_id"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "backbeat.beatframe.v1",
"description": "Message type identifier for BeatFrame v1"
},
"cluster_id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"minLength": 1,
"maxLength": 64,
"description": "Unique identifier for the BACKBEAT cluster"
},
"beat_index": {
"type": "integer",
"minimum": 0,
"maximum": 9223372036854775807,
"description": "Monotonically increasing beat counter since cluster start"
},
"downbeat": {
"type": "boolean",
"description": "True if this is the first beat of a new bar (every 120 beats by default)"
},
"phase": {
"type": "string",
"enum": ["plan", "execute", "review"],
"description": "Current phase within the beat cycle"
},
"hlc": {
"type": "string",
"pattern": "^[0-9a-fA-F]{4}:[0-9a-fA-F]{4}:[0-9a-fA-F]{4}$",
"description": "Hybrid Logical Clock timestamp for causal ordering (format: wall:logical:node)"
},
"deadline_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when this beat phase must complete"
},
"tempo_bpm": {
"type": "number",
"minimum": 0.1,
"maximum": 1000,
"multipleOf": 0.1,
"description": "Current tempo in beats per minute (default: 2.0 for 30-second beats)"
},
"window_id": {
"type": "string",
"pattern": "^[0-9a-fA-F]{32}$",
"description": "Unique identifier for the current reporting window (changes every bar)"
},
"metadata": {
"type": "object",
"description": "Optional metadata for extensions and debugging",
"additionalProperties": true,
"properties": {
"pulse_version": {
"type": "string",
"description": "Version of the Pulse service generating this beat"
},
"cluster_health": {
"type": "string",
"enum": ["healthy", "degraded", "critical"],
"description": "Overall cluster health status"
},
"expected_agents": {
"type": "integer",
"minimum": 0,
"description": "Number of agents expected to participate in this beat"
}
}
}
},
"examples": [
{
"type": "backbeat.beatframe.v1",
"cluster_id": "chorus-prod",
"beat_index": 1337,
"downbeat": false,
"phase": "execute",
"hlc": "7ffd:0001:abcd",
"deadline_at": "2025-09-05T12:30:00Z",
"tempo_bpm": 2.0,
"window_id": "7e9b0e6c4c9a4e59b7f2d9a3c1b2e4d5",
"metadata": {
"pulse_version": "1.2.3",
"cluster_health": "healthy",
"expected_agents": 150
}
},
{
"type": "backbeat.beatframe.v1",
"cluster_id": "dev-cluster",
"beat_index": 0,
"downbeat": true,
"phase": "plan",
"hlc": "0001:0000:cafe",
"deadline_at": "2025-09-05T12:00:30Z",
"tempo_bpm": 4.0,
"window_id": "a1b2c3d4e5f6789012345678901234ab"
}
]
}

181
contracts/schemas/statusclaim-v1.schema.json Normal file
View File

@@ -0,0 +1,181 @@
{
"$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"]
}
]
}