{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stella-ops.org/schemas/signals-integration.schema.json",
  "title": "StellaOps Signals Integration Schema",
  "description": "Schema for runtime signals integration, callgraph formats, and signal weighting. Unblocks DOCS-SIG-26-001 through DOCS-SIG-26-007.",
  "type": "object",
  "definitions": {
    "SignalState": {
      "type": "string",
      "enum": [
        "active",
        "inactive",
        "pending",
        "stale",
        "error",
        "unknown"
      ],
      "description": "Current state of a signal"
    },
    "SignalScore": {
      "type": "object",
      "description": "Computed signal score with confidence",
      "required": ["value", "confidence"],
      "properties": {
        "value": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Normalized score value (0-1)"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Confidence level in the score"
        },
        "raw_value": {
          "type": "number",
          "description": "Original unnormalized value"
        },
        "components": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ScoreComponent"
          }
        }
      }
    },
    "ScoreComponent": {
      "type": "object",
      "description": "Individual component contributing to score",
      "properties": {
        "name": {
          "type": "string"
        },
        "weight": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "contribution": {
          "type": "number"
        },
        "source": {
          "type": "string"
        }
      }
    },
    "RuntimeSignal": {
      "type": "object",
      "description": "Runtime observation signal from instrumented application",
      "required": ["signal_id", "signal_type", "observed_at"],
      "properties": {
        "signal_id": {
          "type": "string",
          "format": "uuid"
        },
        "signal_type": {
          "$ref": "#/definitions/RuntimeSignalType"
        },
        "state": {
          "$ref": "#/definitions/SignalState"
        },
        "score": {
          "$ref": "#/definitions/SignalScore"
        },
        "subject": {
          "$ref": "#/definitions/SignalSubject"
        },
        "observation": {
          "$ref": "#/definitions/RuntimeObservation"
        },
        "environment": {
          "$ref": "#/definitions/RuntimeEnvironment"
        },
        "retention": {
          "$ref": "#/definitions/SignalRetention"
        },
        "observed_at": {
          "type": "string",
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "RuntimeSignalType": {
      "type": "string",
      "enum": [
        "function_invocation",
        "code_path_execution",
        "module_load",
        "dependency_resolution",
        "network_call",
        "file_access",
        "database_query",
        "crypto_operation",
        "serialization",
        "reflection",
        "dynamic_code",
        "process_spawn",
        "memory_allocation",
        "exception_thrown"
      ]
    },
    "SignalSubject": {
      "type": "object",
      "description": "Subject of the signal (what was observed)",
      "properties": {
        "purl": {
          "type": "string",
          "description": "Package URL of component"
        },
        "symbol": {
          "type": "string",
          "description": "Fully qualified symbol name"
        },
        "file": {
          "type": "string"
        },
        "line": {
          "type": "integer"
        },
        "module": {
          "type": "string"
        },
        "class": {
          "type": "string"
        },
        "method": {
          "type": "string"
        },
        "cve_id": {
          "type": "string",
          "pattern": "^CVE-[0-9]{4}-[0-9]+$"
        }
      }
    },
    "RuntimeObservation": {
      "type": "object",
      "description": "Details of the runtime observation",
      "properties": {
        "call_count": {
          "type": "integer",
          "minimum": 0
        },
        "first_seen": {
          "type": "string",
          "format": "date-time"
        },
        "last_seen": {
          "type": "string",
          "format": "date-time"
        },
        "observation_window": {
          "type": "string",
          "description": "Duration of observation (e.g., '7d', '30d')"
        },
        "sample_rate": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Sampling rate if not 100%"
        },
        "call_stack": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/StackFrame"
          }
        },
        "arguments": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ArgumentSummary"
          }
        }
      }
    },
    "StackFrame": {
      "type": "object",
      "description": "Stack frame in call stack",
      "properties": {
        "symbol": {
          "type": "string"
        },
        "file": {
          "type": "string"
        },
        "line": {
          "type": "integer"
        },
        "module": {
          "type": "string"
        }
      }
    },
    "ArgumentSummary": {
      "type": "object",
      "description": "Summary of argument (privacy-preserving)",
      "properties": {
        "position": {
          "type": "integer"
        },
        "type": {
          "type": "string"
        },
        "is_sensitive": {
          "type": "boolean",
          "default": false
        },
        "hash": {
          "type": "string",
          "description": "Hash of value for correlation"
        }
      }
    },
    "RuntimeEnvironment": {
      "type": "object",
      "description": "Runtime environment context",
      "properties": {
        "environment": {
          "type": "string",
          "enum": ["production", "staging", "development", "test"]
        },
        "deployment_id": {
          "type": "string"
        },
        "instance_id": {
          "type": "string"
        },
        "region": {
          "type": "string"
        },
        "runtime": {
          "type": "string",
          "description": "Runtime platform (e.g., 'node-20.10', 'python-3.12')"
        },
        "container_id": {
          "type": "string"
        },
        "pod_name": {
          "type": "string"
        }
      }
    },
    "SignalRetention": {
      "type": "object",
      "description": "Retention policy for signal data",
      "properties": {
        "retention_days": {
          "type": "integer",
          "minimum": 1,
          "default": 30
        },
        "aggregation_after_days": {
          "type": "integer",
          "description": "Days after which to aggregate raw data"
        },
        "privacy_policy": {
          "type": "string",
          "enum": ["full", "anonymized", "aggregated_only"]
        }
      }
    },
    "CallgraphFormat": {
      "type": "object",
      "description": "Callgraph representation format",
      "required": ["format", "version"],
      "properties": {
        "format": {
          "type": "string",
          "enum": ["richgraph-v1", "dot", "json-graph", "sarif", "spdx-lite"],
          "description": "Callgraph serialization format"
        },
        "version": {
          "type": "string"
        },
        "generator": {
          "type": "string"
        },
        "generator_version": {
          "type": "string"
        }
      }
    },
    "Callgraph": {
      "type": "object",
      "description": "Static or dynamic callgraph",
      "required": ["callgraph_id", "format", "nodes"],
      "properties": {
        "callgraph_id": {
          "type": "string",
          "format": "uuid"
        },
        "format": {
          "$ref": "#/definitions/CallgraphFormat"
        },
        "analysis_type": {
          "type": "string",
          "enum": ["static", "dynamic", "hybrid"]
        },
        "nodes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/CallgraphNode"
          }
        },
        "edges": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/CallgraphEdge"
          }
        },
        "entry_points": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Node IDs of entry points"
        },
        "vulnerable_nodes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Node IDs of vulnerable symbols"
        },
        "statistics": {
          "$ref": "#/definitions/CallgraphStatistics"
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "generated_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "CallgraphNode": {
      "type": "object",
      "description": "Node in callgraph",
      "required": ["id", "symbol"],
      "properties": {
        "id": {
          "type": "string"
        },
        "symbol": {
          "type": "string",
          "description": "Fully qualified symbol name"
        },
        "type": {
          "type": "string",
          "enum": ["function", "method", "class", "module", "package", "external"]
        },
        "file": {
          "type": "string"
        },
        "line_start": {
          "type": "integer"
        },
        "line_end": {
          "type": "integer"
        },
        "package": {
          "type": "string"
        },
        "purl": {
          "type": "string"
        },
        "is_entry_point": {
          "type": "boolean",
          "default": false
        },
        "is_vulnerable": {
          "type": "boolean",
          "default": false
        },
        "is_sink": {
          "type": "boolean",
          "default": false
        },
        "vulnerability_ids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "attributes": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "CallgraphEdge": {
      "type": "object",
      "description": "Edge in callgraph",
      "required": ["source", "target"],
      "properties": {
        "source": {
          "type": "string",
          "description": "Source node ID"
        },
        "target": {
          "type": "string",
          "description": "Target node ID"
        },
        "call_type": {
          "type": "string",
          "enum": ["direct", "indirect", "virtual", "reflection", "dynamic", "callback", "async"]
        },
        "weight": {
          "type": "number",
          "minimum": 0,
          "description": "Edge weight for path analysis"
        },
        "call_site": {
          "type": "object",
          "properties": {
            "file": { "type": "string" },
            "line": { "type": "integer" }
          }
        },
        "observed_count": {
          "type": "integer",
          "description": "Call count if from dynamic analysis"
        }
      }
    },
    "CallgraphStatistics": {
      "type": "object",
      "description": "Statistics about callgraph",
      "properties": {
        "total_nodes": {
          "type": "integer"
        },
        "total_edges": {
          "type": "integer"
        },
        "entry_point_count": {
          "type": "integer"
        },
        "vulnerable_node_count": {
          "type": "integer"
        },
        "max_depth": {
          "type": "integer"
        },
        "coverage_percent": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "packages_analyzed": {
          "type": "integer"
        }
      }
    },
    "CallgraphValidationError": {
      "type": "object",
      "description": "Validation error in callgraph",
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "INVALID_FORMAT",
            "MISSING_REQUIRED_FIELD",
            "INVALID_NODE_REFERENCE",
            "CYCLE_DETECTED",
            "ORPHAN_NODE",
            "DUPLICATE_NODE_ID",
            "INVALID_SYMBOL_FORMAT",
            "UNSUPPORTED_VERSION",
            "INCOMPLETE_COVERAGE"
          ]
        },
        "message": {
          "type": "string"
        },
        "path": {
          "type": "string",
          "description": "JSON path to error location"
        },
        "node_id": {
          "type": "string"
        },
        "severity": {
          "type": "string",
          "enum": ["error", "warning", "info"]
        }
      }
    },
    "SignalWeightingConfig": {
      "type": "object",
      "description": "Configuration for signal weighting in policy evaluation",
      "required": ["config_id", "weights"],
      "properties": {
        "config_id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "weights": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SignalWeight"
          }
        },
        "decay_function": {
          "$ref": "#/definitions/DecayFunction"
        },
        "aggregation_method": {
          "type": "string",
          "enum": ["weighted_average", "max", "min", "product", "custom"],
          "default": "weighted_average"
        },
        "thresholds": {
          "$ref": "#/definitions/SignalThresholds"
        },
        "tenant_id": {
          "type": "string",
          "format": "uuid"
        },
        "effective_from": {
          "type": "string",
          "format": "date-time"
        },
        "effective_until": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "SignalWeight": {
      "type": "object",
      "description": "Weight configuration for a signal type",
      "required": ["signal_type", "weight"],
      "properties": {
        "signal_type": {
          "$ref": "#/definitions/RuntimeSignalType"
        },
        "weight": {
          "type": "number",
          "minimum": 0,
          "maximum": 10,
          "description": "Weight multiplier for this signal type"
        },
        "min_observations": {
          "type": "integer",
          "minimum": 1,
          "default": 1,
          "description": "Minimum observations before signal is considered"
        },
        "confidence_boost": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Boost to apply when high confidence"
        },
        "environment_modifiers": {
          "type": "object",
          "additionalProperties": {
            "type": "number"
          },
          "description": "Weight modifiers by environment (e.g., production: 1.5)"
        }
      }
    },
    "DecayFunction": {
      "type": "object",
      "description": "Time decay function for signal freshness",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["linear", "exponential", "step", "none"],
          "default": "exponential"
        },
        "half_life_hours": {
          "type": "integer",
          "minimum": 1,
          "default": 168,
          "description": "Hours for signal to decay to 50% weight"
        },
        "min_weight": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.1,
          "description": "Minimum weight after decay"
        },
        "max_age_hours": {
          "type": "integer",
          "description": "Maximum age before signal is ignored"
        }
      }
    },
    "SignalThresholds": {
      "type": "object",
      "description": "Thresholds for signal-based decisions",
      "properties": {
        "reachable_threshold": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.7,
          "description": "Score above which symbol is considered reachable"
        },
        "unreachable_threshold": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.3,
          "description": "Score below which symbol is considered unreachable"
        },
        "confidence_minimum": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.5,
          "description": "Minimum confidence to use signal"
        }
      }
    },
    "SignalOverlay": {
      "type": "object",
      "description": "UI overlay data for signal visualization",
      "required": ["overlay_id", "component"],
      "properties": {
        "overlay_id": {
          "type": "string",
          "format": "uuid"
        },
        "component": {
          "type": "string",
          "description": "PURL or component identifier"
        },
        "display": {
          "$ref": "#/definitions/OverlayDisplay"
        },
        "badges": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SignalBadge"
          }
        },
        "timeline_events": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TimelineOverlayEvent"
          }
        },
        "shortcuts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/OverlayShortcut"
          }
        }
      }
    },
    "OverlayDisplay": {
      "type": "object",
      "description": "Display properties for overlay",
      "properties": {
        "reachability_state": {
          "type": "string",
          "enum": ["reachable", "unreachable", "potentially_reachable", "unknown"]
        },
        "reachability_icon": {
          "type": "string",
          "enum": ["check", "x", "question", "warning"]
        },
        "reachability_color": {
          "type": "string",
          "enum": ["green", "red", "yellow", "gray"]
        },
        "confidence_display": {
          "type": "string",
          "enum": ["high", "medium", "low"]
        },
        "last_observed_label": {
          "type": "string"
        }
      }
    },
    "SignalBadge": {
      "type": "object",
      "description": "Badge to display on component",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["reachability", "runtime", "coverage", "age", "confidence"]
        },
        "label": {
          "type": "string"
        },
        "value": {
          "type": "string"
        },
        "color": {
          "type": "string"
        },
        "tooltip": {
          "type": "string"
        }
      }
    },
    "TimelineOverlayEvent": {
      "type": "object",
      "description": "Event for timeline visualization",
      "properties": {
        "timestamp": {
          "type": "string",
          "format": "date-time"
        },
        "event_type": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "details": {
          "type": "string"
        }
      }
    },
    "OverlayShortcut": {
      "type": "object",
      "description": "Keyboard/UI shortcut pattern",
      "properties": {
        "key": {
          "type": "string"
        },
        "action": {
          "type": "string"
        },
        "description": {
          "type": "string"
        }
      }
    },
    "SignalAPIEndpoint": {
      "type": "object",
      "description": "API endpoint specification for signals",
      "required": ["path", "method"],
      "properties": {
        "path": {
          "type": "string"
        },
        "method": {
          "type": "string",
          "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
        },
        "description": {
          "type": "string"
        },
        "request_schema": {
          "type": "string",
          "description": "JSON Schema reference"
        },
        "response_schema": {
          "type": "string",
          "description": "JSON Schema reference"
        },
        "error_model": {
          "$ref": "#/definitions/SignalAPIError"
        },
        "etag_support": {
          "type": "boolean",
          "default": true
        }
      }
    },
    "SignalAPIError": {
      "type": "object",
      "description": "API error response",
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "object",
          "additionalProperties": true
        },
        "request_id": {
          "type": "string"
        }
      }
    }
  },
  "properties": {
    "signals": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/RuntimeSignal"
      }
    },
    "callgraphs": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Callgraph"
      }
    },
    "weighting_config": {
      "$ref": "#/definitions/SignalWeightingConfig"
    }
  },
  "examples": [
    {
      "signals": [
        {
          "signal_id": "550e8400-e29b-41d4-a716-446655440001",
          "signal_type": "function_invocation",
          "state": "active",
          "score": {
            "value": 0.85,
            "confidence": 0.92
          },
          "subject": {
            "purl": "pkg:npm/lodash@4.17.21",
            "symbol": "lodash.template",
            "cve_id": "CVE-2021-23337"
          },
          "observation": {
            "call_count": 1247,
            "first_seen": "2025-11-01T00:00:00Z",
            "last_seen": "2025-12-06T10:00:00Z",
            "observation_window": "30d"
          },
          "environment": {
            "environment": "production",
            "runtime": "node-20.10"
          },
          "observed_at": "2025-12-06T10:00:00Z"
        }
      ],
      "weighting_config": {
        "config_id": "660e8400-e29b-41d4-a716-446655440002",
        "name": "default-production",
        "weights": [
          {
            "signal_type": "function_invocation",
            "weight": 2.0,
            "min_observations": 10,
            "environment_modifiers": {
              "production": 1.5,
              "staging": 1.0,
              "development": 0.5
            }
          }
        ],
        "decay_function": {
          "type": "exponential",
          "half_life_hours": 168,
          "min_weight": 0.1
        },
        "thresholds": {
          "reachable_threshold": 0.7,
          "unreachable_threshold": 0.3,
          "confidence_minimum": 0.5
        }
      }
    }
  ]
}