{
  "$id": "https://stella.ops/schema/timeline-event.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TimelineEvent",
  "description": "Unified timeline event schema for audit trail, observability, and evidence chain tracking",
  "type": "object",
  "required": [
    "eventId",
    "tenantId",
    "eventType",
    "source",
    "occurredAt"
  ],
  "properties": {
    "eventSeq": {
      "type": "integer",
      "minimum": 0,
      "description": "Monotonically increasing sequence number for ordering"
    },
    "eventId": {
      "type": "string",
      "format": "uuid",
      "description": "Globally unique event identifier"
    },
    "tenantId": {
      "type": "string",
      "description": "Tenant scope for multi-tenant isolation"
    },
    "eventType": {
      "type": "string",
      "description": "Event type identifier following namespace convention",
      "examples": [
        "scan.started",
        "scan.completed",
        "vex.imported",
        "policy.evaluated",
        "attestation.created",
        "mirror.bundle.registered"
      ]
    },
    "source": {
      "type": "string",
      "description": "Service or component that emitted this event",
      "examples": ["scanner-worker", "policy-engine", "excititor", "orchestrator"]
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 timestamp when the event actually occurred"
    },
    "receivedAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 timestamp when the event was received by timeline indexer"
    },
    "correlationId": {
      "type": "string",
      "description": "Correlation ID linking related events across services"
    },
    "traceId": {
      "type": "string",
      "description": "OpenTelemetry trace ID for distributed tracing"
    },
    "spanId": {
      "type": "string",
      "description": "OpenTelemetry span ID within the trace"
    },
    "actor": {
      "type": "string",
      "description": "User, service account, or system that triggered the event"
    },
    "severity": {
      "type": "string",
      "enum": ["debug", "info", "warning", "error", "critical"],
      "default": "info",
      "description": "Event severity level"
    },
    "attributes": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Key-value attributes for filtering and querying"
    },
    "payloadHash": {
      "type": "string",
      "pattern": "^sha256:[a-f0-9]{64}$",
      "description": "SHA-256 hash of the raw payload for integrity"
    },
    "rawPayloadJson": {
      "type": "string",
      "description": "Original event payload as JSON string"
    },
    "normalizedPayloadJson": {
      "type": "string",
      "description": "Canonicalized JSON for deterministic hashing"
    },
    "evidencePointer": {
      "$ref": "#/$defs/EvidencePointer",
      "description": "Reference to associated evidence bundle or attestation"
    }
  },
  "$defs": {
    "EvidencePointer": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["BUNDLE", "ATTESTATION", "MANIFEST", "ARTIFACT"],
          "description": "Type of evidence being referenced"
        },
        "bundleId": {
          "type": "string",
          "format": "uuid",
          "description": "Evidence bundle identifier"
        },
        "bundleDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Content digest of the evidence bundle"
        },
        "attestationSubject": {
          "type": "string",
          "description": "Subject URI for the attestation"
        },
        "attestationDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Digest of the attestation envelope"
        },
        "manifestUri": {
          "type": "string",
          "format": "uri",
          "description": "URI to the evidence manifest"
        },
        "lockerPath": {
          "type": "string",
          "description": "Path within evidence locker storage"
        }
      }
    }
  },
  "examples": [
    {
      "eventSeq": 12345,
      "eventId": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "acme-corp",
      "eventType": "scan.completed",
      "source": "scanner-worker",
      "occurredAt": "2025-11-21T10:15:00Z",
      "receivedAt": "2025-11-21T10:15:01Z",
      "correlationId": "job-abc123",
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "actor": "service:scanner-worker",
      "severity": "info",
      "attributes": {
        "image": "registry.example.com/app:v1.2.3",
        "vulnerabilityCount": "42",
        "criticalCount": "3"
      },
      "payloadHash": "sha256:7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee",
      "evidencePointer": {
        "type": "BUNDLE",
        "bundleId": "660e8400-e29b-41d4-a716-446655440001",
        "bundleDigest": "sha256:8d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aef"
      }
    }
  ]
}