{
  "$id": "https://stella.ops/schema/graph-platform.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "GraphPlatform",
  "description": "CAGR0101 Graph platform contract for dependency visualization, SBOM graph analysis, and overlay queries",
  "type": "object",
  "oneOf": [
    { "$ref": "#/$defs/GraphNode" },
    { "$ref": "#/$defs/GraphEdge" },
    { "$ref": "#/$defs/GraphQuery" },
    { "$ref": "#/$defs/GraphQueryResult" },
    { "$ref": "#/$defs/GraphOverlay" },
    { "$ref": "#/$defs/GraphSnapshot" },
    { "$ref": "#/$defs/GraphMetrics" }
  ],
  "$defs": {
    "GraphNode": {
      "type": "object",
      "required": ["nodeType", "nodeId", "label"],
      "description": "Node in the dependency/relationship graph",
      "properties": {
        "nodeType": {
          "type": "string",
          "const": "GRAPH_NODE"
        },
        "nodeId": {
          "type": "string",
          "description": "Unique node identifier (usually PURL or digest)"
        },
        "nodeKind": {
          "type": "string",
          "enum": [
            "PACKAGE",
            "IMAGE",
            "VULNERABILITY",
            "ADVISORY",
            "LICENSE",
            "FILE",
            "SERVICE",
            "NAMESPACE",
            "TENANT"
          ],
          "description": "Kind of graph node"
        },
        "label": {
          "type": "string",
          "description": "Human-readable node label"
        },
        "purl": {
          "type": "string",
          "description": "Package URL if applicable"
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Content digest if applicable"
        },
        "version": {
          "type": "string",
          "description": "Version string if applicable"
        },
        "ecosystem": {
          "type": "string",
          "description": "Package ecosystem (npm, maven, pypi, etc.)"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true,
          "description": "Additional node metadata"
        },
        "position": {
          "$ref": "#/$defs/NodePosition",
          "description": "Layout position for visualization"
        },
        "style": {
          "$ref": "#/$defs/NodeStyle",
          "description": "Visual styling hints"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "When node was created"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When node was last updated"
        }
      }
    },
    "NodePosition": {
      "type": "object",
      "properties": {
        "x": {
          "type": "number",
          "description": "X coordinate"
        },
        "y": {
          "type": "number",
          "description": "Y coordinate"
        },
        "z": {
          "type": "number",
          "description": "Z coordinate (for 3D layouts)"
        },
        "layer": {
          "type": "integer",
          "description": "Layer/depth in hierarchical layout"
        }
      }
    },
    "NodeStyle": {
      "type": "object",
      "properties": {
        "color": {
          "type": "string",
          "description": "Node color (hex or named)"
        },
        "size": {
          "type": "number",
          "description": "Node size multiplier"
        },
        "shape": {
          "type": "string",
          "enum": ["circle", "rectangle", "diamond", "hexagon", "triangle"],
          "description": "Node shape"
        },
        "icon": {
          "type": "string",
          "description": "Icon identifier"
        },
        "highlighted": {
          "type": "boolean",
          "description": "Whether node should be highlighted"
        }
      }
    },
    "GraphEdge": {
      "type": "object",
      "required": ["edgeType", "edgeId", "sourceId", "targetId", "relationship"],
      "description": "Edge connecting two nodes in the graph",
      "properties": {
        "edgeType": {
          "type": "string",
          "const": "GRAPH_EDGE"
        },
        "edgeId": {
          "type": "string",
          "description": "Unique edge identifier"
        },
        "sourceId": {
          "type": "string",
          "description": "Source node ID"
        },
        "targetId": {
          "type": "string",
          "description": "Target node ID"
        },
        "relationship": {
          "type": "string",
          "enum": [
            "DEPENDS_ON",
            "DEV_DEPENDS_ON",
            "OPTIONAL_DEPENDS_ON",
            "CONTAINS",
            "AFFECTS",
            "FIXES",
            "LICENSES",
            "DESCRIBES",
            "BUILDS_FROM",
            "DEPLOYED_TO"
          ],
          "description": "Type of relationship"
        },
        "weight": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Edge weight for algorithms"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true,
          "description": "Additional edge metadata"
        },
        "style": {
          "$ref": "#/$defs/EdgeStyle",
          "description": "Visual styling hints"
        }
      }
    },
    "EdgeStyle": {
      "type": "object",
      "properties": {
        "color": {
          "type": "string",
          "description": "Edge color"
        },
        "width": {
          "type": "number",
          "description": "Edge width"
        },
        "style": {
          "type": "string",
          "enum": ["solid", "dashed", "dotted"],
          "description": "Line style"
        },
        "animated": {
          "type": "boolean",
          "description": "Whether edge should animate"
        }
      }
    },
    "GraphQuery": {
      "type": "object",
      "required": ["queryType", "queryId"],
      "description": "Query against the graph",
      "properties": {
        "queryType": {
          "type": "string",
          "const": "GRAPH_QUERY"
        },
        "queryId": {
          "type": "string",
          "format": "uuid",
          "description": "Unique query identifier"
        },
        "tenantId": {
          "type": "string",
          "description": "Tenant scope"
        },
        "operation": {
          "type": "string",
          "enum": [
            "SUBGRAPH",
            "SHORTEST_PATH",
            "NEIGHBORS",
            "IMPACT_ANALYSIS",
            "DEPENDENCY_TREE",
            "VULNERABILITY_REACH",
            "LICENSE_PROPAGATION"
          ],
          "description": "Query operation type"
        },
        "rootNodes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Starting node IDs for traversal"
        },
        "filters": {
          "$ref": "#/$defs/QueryFilters",
          "description": "Filtering criteria"
        },
        "traversal": {
          "$ref": "#/$defs/TraversalOptions",
          "description": "Traversal options"
        },
        "pagination": {
          "$ref": "#/$defs/Pagination",
          "description": "Pagination options"
        },
        "timeout": {
          "type": "integer",
          "minimum": 100,
          "maximum": 60000,
          "description": "Query timeout in milliseconds"
        }
      }
    },
    "QueryFilters": {
      "type": "object",
      "properties": {
        "nodeKinds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Include only these node kinds"
        },
        "relationships": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Include only these relationship types"
        },
        "ecosystems": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by ecosystems"
        },
        "severityMin": {
          "type": "string",
          "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN"],
          "description": "Minimum severity for vulnerability nodes"
        },
        "dateRange": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "format": "date-time"
            },
            "to": {
              "type": "string",
              "format": "date-time"
            }
          },
          "description": "Date range filter"
        }
      }
    },
    "TraversalOptions": {
      "type": "object",
      "properties": {
        "direction": {
          "type": "string",
          "enum": ["OUTBOUND", "INBOUND", "BOTH"],
          "default": "OUTBOUND",
          "description": "Traversal direction"
        },
        "maxDepth": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10,
          "description": "Maximum traversal depth"
        },
        "maxNodes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100000,
          "default": 10000,
          "description": "Maximum nodes to return"
        },
        "algorithm": {
          "type": "string",
          "enum": ["BFS", "DFS", "DIJKSTRA"],
          "default": "BFS",
          "description": "Traversal algorithm"
        }
      }
    },
    "Pagination": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000,
          "default": 100,
          "description": "Results per page"
        },
        "cursor": {
          "type": "string",
          "description": "Pagination cursor"
        },
        "sortBy": {
          "type": "string",
          "description": "Sort field"
        },
        "sortOrder": {
          "type": "string",
          "enum": ["asc", "desc"],
          "default": "asc"
        }
      }
    },
    "GraphQueryResult": {
      "type": "object",
      "required": ["resultType", "queryId", "completedAt"],
      "description": "Result of a graph query",
      "properties": {
        "resultType": {
          "type": "string",
          "const": "GRAPH_QUERY_RESULT"
        },
        "queryId": {
          "type": "string",
          "format": "uuid",
          "description": "Query identifier"
        },
        "completedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When query completed"
        },
        "durationMs": {
          "type": "integer",
          "minimum": 0,
          "description": "Query duration in milliseconds"
        },
        "nodes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/GraphNode"
          },
          "description": "Nodes in result"
        },
        "edges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/GraphEdge"
          },
          "description": "Edges in result"
        },
        "statistics": {
          "$ref": "#/$defs/QueryStatistics",
          "description": "Query execution statistics"
        },
        "pagination": {
          "type": "object",
          "properties": {
            "nextCursor": {
              "type": "string"
            },
            "hasMore": {
              "type": "boolean"
            },
            "totalCount": {
              "type": "integer"
            }
          }
        },
        "truncated": {
          "type": "boolean",
          "description": "Whether results were truncated"
        }
      }
    },
    "QueryStatistics": {
      "type": "object",
      "properties": {
        "nodesScanned": {
          "type": "integer",
          "description": "Total nodes scanned"
        },
        "nodesReturned": {
          "type": "integer",
          "description": "Nodes returned in result"
        },
        "edgesScanned": {
          "type": "integer",
          "description": "Total edges scanned"
        },
        "edgesReturned": {
          "type": "integer",
          "description": "Edges returned in result"
        },
        "maxDepthReached": {
          "type": "integer",
          "description": "Maximum depth reached in traversal"
        },
        "cacheHit": {
          "type": "boolean",
          "description": "Whether result was served from cache"
        }
      }
    },
    "GraphOverlay": {
      "type": "object",
      "required": ["overlayType", "overlayId", "name"],
      "description": "Overlay layer for graph visualization",
      "properties": {
        "overlayType": {
          "type": "string",
          "const": "GRAPH_OVERLAY"
        },
        "overlayId": {
          "type": "string",
          "format": "uuid",
          "description": "Unique overlay identifier"
        },
        "name": {
          "type": "string",
          "description": "Overlay name"
        },
        "description": {
          "type": "string",
          "description": "Overlay description"
        },
        "overlayKind": {
          "type": "string",
          "enum": [
            "VULNERABILITY_HEATMAP",
            "LICENSE_COMPLIANCE",
            "DEPENDENCY_AGE",
            "REACHABILITY",
            "SEVERITY_GRADIENT",
            "CUSTOM"
          ],
          "description": "Type of overlay"
        },
        "nodeStyles": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/NodeStyle"
          },
          "description": "Node ID to style mapping"
        },
        "edgeStyles": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/EdgeStyle"
          },
          "description": "Edge ID to style mapping"
        },
        "legend": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/LegendItem"
          },
          "description": "Legend items for overlay"
        },
        "cachedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When overlay was cached"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time",
          "description": "When cache expires"
        }
      }
    },
    "LegendItem": {
      "type": "object",
      "required": ["label"],
      "properties": {
        "label": {
          "type": "string",
          "description": "Legend label"
        },
        "color": {
          "type": "string",
          "description": "Color for this legend item"
        },
        "description": {
          "type": "string",
          "description": "Description of what this represents"
        }
      }
    },
    "GraphSnapshot": {
      "type": "object",
      "required": ["snapshotType", "snapshotId", "createdAt"],
      "description": "Point-in-time snapshot of graph state",
      "properties": {
        "snapshotType": {
          "type": "string",
          "const": "GRAPH_SNAPSHOT"
        },
        "snapshotId": {
          "type": "string",
          "format": "uuid",
          "description": "Unique snapshot identifier"
        },
        "tenantId": {
          "type": "string",
          "description": "Tenant scope"
        },
        "name": {
          "type": "string",
          "description": "Snapshot name"
        },
        "description": {
          "type": "string",
          "description": "Snapshot description"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "When snapshot was created"
        },
        "createdBy": {
          "type": "string",
          "description": "User/service that created snapshot"
        },
        "nodeCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of nodes in snapshot"
        },
        "edgeCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of edges in snapshot"
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Content digest of snapshot"
        },
        "storageLocation": {
          "type": "string",
          "format": "uri",
          "description": "Where snapshot data is stored"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true,
          "description": "Additional snapshot metadata"
        }
      }
    },
    "GraphMetrics": {
      "type": "object",
      "required": ["metricsType", "collectedAt"],
      "description": "Graph platform metrics for monitoring",
      "properties": {
        "metricsType": {
          "type": "string",
          "const": "GRAPH_METRICS"
        },
        "collectedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When metrics were collected"
        },
        "ingestLagSeconds": {
          "type": "number",
          "minimum": 0,
          "description": "Lag between event and graph update (graph_ingest_lag_seconds)"
        },
        "tileLatencySeconds": {
          "type": "number",
          "minimum": 0,
          "description": "Tile rendering latency (graph_tile_latency_seconds)"
        },
        "queryBudgetDeniedTotal": {
          "type": "integer",
          "minimum": 0,
          "description": "Queries denied due to budget (graph_query_budget_denied_total)"
        },
        "overlayCacheHitRatio": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Overlay cache hit ratio (graph_overlay_cache_hit_ratio)"
        },
        "nodeCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Total nodes in graph"
        },
        "edgeCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Total edges in graph"
        },
        "queryRate": {
          "type": "number",
          "minimum": 0,
          "description": "Queries per second"
        },
        "avgQueryDurationMs": {
          "type": "number",
          "minimum": 0,
          "description": "Average query duration"
        }
      }
    },
    "BenchmarkConfig": {
      "type": "object",
      "required": ["benchmarkType", "targetNodeCount"],
      "description": "Configuration for graph benchmarking (BENCH-GRAPH-21-001/002)",
      "properties": {
        "benchmarkType": {
          "type": "string",
          "const": "BENCHMARK_CONFIG"
        },
        "targetNodeCount": {
          "type": "integer",
          "minimum": 1000,
          "maximum": 1000000,
          "description": "Target node count for benchmark",
          "examples": [50000, 100000]
        },
        "targetEdgeRatio": {
          "type": "number",
          "minimum": 1,
          "maximum": 100,
          "default": 3,
          "description": "Target edges per node ratio"
        },
        "queryPatterns": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["SUBGRAPH", "SHORTEST_PATH", "IMPACT_ANALYSIS", "DEPENDENCY_TREE"]
          },
          "description": "Query patterns to benchmark"
        },
        "iterations": {
          "type": "integer",
          "minimum": 1,
          "default": 100,
          "description": "Number of iterations per pattern"
        },
        "warmupIterations": {
          "type": "integer",
          "minimum": 0,
          "default": 10,
          "description": "Warmup iterations"
        },
        "memoryThresholdMb": {
          "type": "integer",
          "minimum": 100,
          "description": "Memory threshold in MB"
        },
        "latencyThresholdMs": {
          "type": "integer",
          "minimum": 10,
          "description": "P99 latency threshold in ms"
        }
      }
    },
    "BenchmarkResult": {
      "type": "object",
      "required": ["resultType", "benchmarkId", "completedAt", "passed"],
      "description": "Result of graph benchmark run",
      "properties": {
        "resultType": {
          "type": "string",
          "const": "BENCHMARK_RESULT"
        },
        "benchmarkId": {
          "type": "string",
          "format": "uuid",
          "description": "Benchmark run identifier"
        },
        "completedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When benchmark completed"
        },
        "passed": {
          "type": "boolean",
          "description": "Whether benchmark passed thresholds"
        },
        "nodeCount": {
          "type": "integer",
          "description": "Actual node count"
        },
        "edgeCount": {
          "type": "integer",
          "description": "Actual edge count"
        },
        "patternResults": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PatternResult"
          },
          "description": "Results per query pattern"
        },
        "memoryPeakMb": {
          "type": "number",
          "description": "Peak memory usage in MB"
        },
        "totalDurationSeconds": {
          "type": "number",
          "description": "Total benchmark duration"
        }
      }
    },
    "PatternResult": {
      "type": "object",
      "required": ["pattern", "iterations"],
      "properties": {
        "pattern": {
          "type": "string",
          "description": "Query pattern"
        },
        "iterations": {
          "type": "integer",
          "description": "Completed iterations"
        },
        "p50LatencyMs": {
          "type": "number",
          "description": "P50 latency"
        },
        "p95LatencyMs": {
          "type": "number",
          "description": "P95 latency"
        },
        "p99LatencyMs": {
          "type": "number",
          "description": "P99 latency"
        },
        "throughputQps": {
          "type": "number",
          "description": "Queries per second"
        },
        "passed": {
          "type": "boolean",
          "description": "Whether pattern passed threshold"
        }
      }
    }
  },
  "examples": [
    {
      "queryType": "GRAPH_QUERY",
      "queryId": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "acme-corp",
      "operation": "VULNERABILITY_REACH",
      "rootNodes": ["pkg:npm/lodash@4.17.21"],
      "filters": {
        "nodeKinds": ["PACKAGE", "VULNERABILITY"],
        "severityMin": "HIGH"
      },
      "traversal": {
        "direction": "INBOUND",
        "maxDepth": 5,
        "maxNodes": 1000
      },
      "timeout": 10000
    },
    {
      "metricsType": "GRAPH_METRICS",
      "collectedAt": "2025-11-21T10:00:00Z",
      "ingestLagSeconds": 0.5,
      "tileLatencySeconds": 0.12,
      "queryBudgetDeniedTotal": 42,
      "overlayCacheHitRatio": 0.85,
      "nodeCount": 150000,
      "edgeCount": 450000,
      "queryRate": 125.5,
      "avgQueryDurationMs": 45.2
    },
    {
      "benchmarkType": "BENCHMARK_CONFIG",
      "targetNodeCount": 100000,
      "targetEdgeRatio": 3,
      "queryPatterns": ["SUBGRAPH", "IMPACT_ANALYSIS", "DEPENDENCY_TREE"],
      "iterations": 100,
      "warmupIterations": 10,
      "memoryThresholdMb": 2048,
      "latencyThresholdMs": 500
    }
  ]
}