{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stella-ops.org/schemas/orchestrator-envelope.schema.json",
  "title": "StellaOps Orchestrator Event Envelope Schema",
  "description": "Schema for orchestrator-compatible event envelopes used by Scanner and other services. Unblocks SCANNER-EVENTS-16-301.",
  "type": "object",
  "definitions": {
    "EventEnvelope": {
      "type": "object",
      "description": "Standard event envelope for orchestrator event bus",
      "required": ["envelope_id", "event_type", "timestamp", "source", "payload"],
      "properties": {
        "envelope_id": {
          "type": "string",
          "format": "uuid",
          "description": "Unique identifier for this event envelope"
        },
        "event_type": {
          "type": "string",
          "pattern": "^[a-z]+\\.[a-z_]+\\.[a-z_]+$",
          "description": "Dot-notation event type (e.g., scanner.scan.completed)",
          "examples": [
            "scanner.scan.started",
            "scanner.scan.completed",
            "scanner.scan.failed",
            "scanner.sbom.generated",
            "scanner.vulnerability.detected",
            "notifier.alert.sent",
            "policy.evaluation.completed"
          ]
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when event was created"
        },
        "source": {
          "$ref": "#/definitions/EventSource"
        },
        "correlation_id": {
          "type": "string",
          "format": "uuid",
          "description": "Correlation ID for tracing related events"
        },
        "causation_id": {
          "type": "string",
          "format": "uuid",
          "description": "ID of the event that caused this event"
        },
        "tenant_id": {
          "type": "string",
          "format": "uuid"
        },
        "project_id": {
          "type": "string",
          "format": "uuid"
        },
        "payload": {
          "type": "object",
          "description": "Event-specific payload",
          "additionalProperties": true
        },
        "metadata": {
          "$ref": "#/definitions/EventMetadata"
        },
        "version": {
          "type": "string",
          "default": "1.0",
          "description": "Event schema version"
        }
      }
    },
    "EventSource": {
      "type": "object",
      "description": "Source of the event",
      "required": ["service", "instance_id"],
      "properties": {
        "service": {
          "type": "string",
          "description": "Service name (e.g., scanner, notifier, policy-engine)"
        },
        "version": {
          "type": "string",
          "description": "Service version"
        },
        "instance_id": {
          "type": "string",
          "description": "Instance identifier (hostname, pod name, etc.)"
        },
        "region": {
          "type": "string",
          "description": "Deployment region"
        }
      }
    },
    "EventMetadata": {
      "type": "object",
      "description": "Additional metadata for the event",
      "properties": {
        "trace_id": {
          "type": "string",
          "description": "OpenTelemetry trace ID"
        },
        "span_id": {
          "type": "string",
          "description": "OpenTelemetry span ID"
        },
        "priority": {
          "type": "string",
          "enum": ["low", "normal", "high", "critical"],
          "default": "normal"
        },
        "ttl_seconds": {
          "type": "integer",
          "minimum": 0,
          "description": "Time-to-live for the event"
        },
        "retry_count": {
          "type": "integer",
          "minimum": 0,
          "default": 0
        },
        "idempotency_key": {
          "type": "string",
          "description": "Key for idempotent processing"
        },
        "content_type": {
          "type": "string",
          "default": "application/json"
        },
        "compression": {
          "type": "string",
          "enum": ["none", "gzip", "lz4"],
          "default": "none"
        }
      }
    },
    "ScannerEventPayload": {
      "type": "object",
      "description": "Base payload for scanner events",
      "properties": {
        "scan_id": {
          "type": "string",
          "format": "uuid"
        },
        "job_id": {
          "type": "string",
          "format": "uuid"
        },
        "target": {
          "$ref": "#/definitions/ScanTarget"
        },
        "status": {
          "type": "string",
          "enum": ["started", "in_progress", "completed", "failed", "cancelled"]
        },
        "started_at": {
          "type": "string",
          "format": "date-time"
        },
        "completed_at": {
          "type": "string",
          "format": "date-time"
        },
        "duration_ms": {
          "type": "integer",
          "minimum": 0
        },
        "results_summary": {
          "$ref": "#/definitions/ScanResultsSummary"
        },
        "error": {
          "$ref": "#/definitions/ErrorInfo"
        }
      }
    },
    "ScanTarget": {
      "type": "object",
      "description": "Target being scanned",
      "required": ["type", "identifier"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["container_image", "repository", "filesystem", "sbom", "package"]
        },
        "identifier": {
          "type": "string",
          "description": "Target identifier (image name, repo URL, path)"
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "tag": {
          "type": "string"
        },
        "platform": {
          "type": "string",
          "description": "Platform (e.g., linux/amd64)"
        }
      }
    },
    "ScanResultsSummary": {
      "type": "object",
      "description": "Summary of scan results",
      "properties": {
        "total_vulnerabilities": {
          "type": "integer",
          "minimum": 0
        },
        "by_severity": {
          "type": "object",
          "properties": {
            "critical": {
              "type": "integer",
              "minimum": 0
            },
            "high": {
              "type": "integer",
              "minimum": 0
            },
            "medium": {
              "type": "integer",
              "minimum": 0
            },
            "low": {
              "type": "integer",
              "minimum": 0
            },
            "info": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "components_scanned": {
          "type": "integer",
          "minimum": 0
        },
        "sbom_generated": {
          "type": "boolean"
        },
        "sbom_ref": {
          "type": "string",
          "description": "Reference to generated SBOM"
        }
      }
    },
    "ErrorInfo": {
      "type": "object",
      "description": "Error information for failed events",
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "object",
          "additionalProperties": true
        },
        "stack_trace": {
          "type": "string"
        },
        "recoverable": {
          "type": "boolean",
          "default": false
        }
      }
    },
    "VulnerabilityDetectedPayload": {
      "type": "object",
      "description": "Payload for vulnerability detection events",
      "required": ["scan_id", "vulnerability"],
      "properties": {
        "scan_id": {
          "type": "string",
          "format": "uuid"
        },
        "vulnerability": {
          "$ref": "#/definitions/VulnerabilityInfo"
        },
        "affected_component": {
          "$ref": "#/definitions/ComponentInfo"
        },
        "reachability": {
          "type": "string",
          "enum": ["reachable", "unreachable", "potentially_reachable", "unknown"]
        }
      }
    },
    "VulnerabilityInfo": {
      "type": "object",
      "required": ["id", "severity"],
      "properties": {
        "id": {
          "type": "string",
          "description": "CVE ID or vulnerability identifier"
        },
        "severity": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low", "info"]
        },
        "cvss_score": {
          "type": "number",
          "minimum": 0,
          "maximum": 10
        },
        "cvss_vector": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "references": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri"
          }
        },
        "fix_available": {
          "type": "boolean"
        },
        "fixed_version": {
          "type": "string"
        },
        "kev_listed": {
          "type": "boolean"
        },
        "epss_score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "ComponentInfo": {
      "type": "object",
      "required": ["purl"],
      "properties": {
        "purl": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "ecosystem": {
          "type": "string"
        },
        "location": {
          "type": "string",
          "description": "Location in the target (e.g., layer, file path)"
        }
      }
    },
    "NotifierIngestionEvent": {
      "type": "object",
      "description": "Event structure for Notifier ingestion",
      "required": ["envelope_id", "event_type", "severity_threshold_met"],
      "properties": {
        "envelope_id": {
          "type": "string",
          "format": "uuid"
        },
        "event_type": {
          "type": "string"
        },
        "severity_threshold_met": {
          "type": "boolean",
          "description": "Whether event meets notification severity threshold"
        },
        "notification_channels": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["email", "slack", "teams", "webhook", "pagerduty"]
          }
        },
        "digest_eligible": {
          "type": "boolean",
          "description": "Whether event should be batched into digest"
        },
        "immediate_dispatch": {
          "type": "boolean",
          "description": "Whether event requires immediate dispatch"
        }
      }
    },
    "EventBatch": {
      "type": "object",
      "description": "Batch of events for bulk processing",
      "required": ["batch_id", "events"],
      "properties": {
        "batch_id": {
          "type": "string",
          "format": "uuid"
        },
        "events": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EventEnvelope"
          },
          "minItems": 1
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "total_count": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "EventSubscription": {
      "type": "object",
      "description": "Subscription to event types",
      "required": ["subscription_id", "event_patterns", "endpoint"],
      "properties": {
        "subscription_id": {
          "type": "string",
          "format": "uuid"
        },
        "event_patterns": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "Glob pattern for event types (e.g., scanner.* or scanner.scan.completed)"
          }
        },
        "endpoint": {
          "type": "string",
          "format": "uri",
          "description": "Webhook endpoint for event delivery"
        },
        "filters": {
          "type": "object",
          "additionalProperties": true,
          "description": "Additional filters on payload fields"
        },
        "enabled": {
          "type": "boolean",
          "default": true
        }
      }
    }
  },
  "properties": {
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/EventEnvelope"
      }
    }
  },
  "examples": [
    {
      "events": [
        {
          "envelope_id": "550e8400-e29b-41d4-a716-446655440000",
          "event_type": "scanner.scan.completed",
          "timestamp": "2025-12-06T10:00:00Z",
          "source": {
            "service": "scanner",
            "version": "2025.10.0",
            "instance_id": "scanner-pod-abc123"
          },
          "correlation_id": "660e8400-e29b-41d4-a716-446655440001",
          "tenant_id": "770e8400-e29b-41d4-a716-446655440002",
          "project_id": "880e8400-e29b-41d4-a716-446655440003",
          "payload": {
            "scan_id": "990e8400-e29b-41d4-a716-446655440004",
            "job_id": "aa0e8400-e29b-41d4-a716-446655440005",
            "target": {
              "type": "container_image",
              "identifier": "myregistry.io/app:v1.0.0",
              "digest": "sha256:abc123def456..."
            },
            "status": "completed",
            "started_at": "2025-12-06T09:55:00Z",
            "completed_at": "2025-12-06T10:00:00Z",
            "duration_ms": 300000,
            "results_summary": {
              "total_vulnerabilities": 15,
              "by_severity": {
                "critical": 1,
                "high": 3,
                "medium": 7,
                "low": 4,
                "info": 0
              },
              "components_scanned": 127,
              "sbom_generated": true,
              "sbom_ref": "s3://sboms/990e8400.../sbom.json"
            }
          },
          "metadata": {
            "trace_id": "abc123trace",
            "span_id": "def456span",
            "priority": "normal"
          },
          "version": "1.0"
        }
      ]
    }
  ]
}