up

tests/reachability/fixtures/patch-oracles/schema/patch-oracle-v1.json

@@ -0,0 +1,179 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "stellaops:patch-oracle/v1",
+  "title": "Patch Oracle Schema v1",
+  "description": "Defines expected functions/edges for reachability graph validation. CI fails when expected elements are missing.",
+  "type": "object",
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "patch-oracle/v1",
+      "description": "Schema version identifier"
+    },
+    "id": {
+      "type": "string",
+      "description": "Unique oracle identifier (e.g., 'curl-CVE-2023-38545-socks5-heap-reachable')"
+    },
+    "case_ref": {
+      "type": "string",
+      "description": "Reference to parent reachbench case (e.g., 'curl-CVE-2023-38545-socks5-heap')"
+    },
+    "variant": {
+      "type": "string",
+      "enum": ["reachable", "unreachable"],
+      "description": "Which variant this oracle applies to"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of what this oracle validates"
+    },
+    "expected_functions": {
+      "type": "array",
+      "description": "Functions that MUST be present in the generated graph",
+      "items": {
+        "$ref": "#/definitions/expected_function"
+      }
+    },
+    "expected_edges": {
+      "type": "array",
+      "description": "Edges that MUST be present in the generated graph",
+      "items": {
+        "$ref": "#/definitions/expected_edge"
+      }
+    },
+    "expected_roots": {
+      "type": "array",
+      "description": "Root nodes that MUST be present in the generated graph",
+      "items": {
+        "$ref": "#/definitions/expected_root"
+      }
+    },
+    "forbidden_functions": {
+      "type": "array",
+      "description": "Functions that MUST NOT be present (for unreachable variants)",
+      "items": {
+        "$ref": "#/definitions/expected_function"
+      }
+    },
+    "forbidden_edges": {
+      "type": "array",
+      "description": "Edges that MUST NOT be present (for unreachable variants)",
+      "items": {
+        "$ref": "#/definitions/expected_edge"
+      }
+    },
+    "min_confidence": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0,
+      "default": 0.5,
+      "description": "Minimum confidence threshold for edge matching"
+    },
+    "strict_mode": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true, extra functions/edges not in oracle cause failure"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When this oracle was created"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When this oracle was last updated"
+    }
+  },
+  "required": ["schema_version", "id", "case_ref", "variant"],
+  "definitions": {
+    "expected_function": {
+      "type": "object",
+      "properties": {
+        "symbol_id": {
+          "type": "string",
+          "description": "Expected symbol ID (exact match or pattern with '*' wildcards)"
+        },
+        "lang": {
+          "type": "string",
+          "description": "Expected language (optional, for filtering)"
+        },
+        "kind": {
+          "type": "string",
+          "description": "Expected node kind (e.g., 'function', 'method', 'entrypoint')"
+        },
+        "purl_pattern": {
+          "type": "string",
+          "description": "Expected purl pattern (optional, supports wildcards)"
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "If true, missing this function fails CI"
+        },
+        "reason": {
+          "type": "string",
+          "description": "Why this function is expected (for documentation)"
+        }
+      },
+      "required": ["symbol_id"]
+    },
+    "expected_edge": {
+      "type": "object",
+      "properties": {
+        "from": {
+          "type": "string",
+          "description": "Source node symbol ID (exact match or pattern)"
+        },
+        "to": {
+          "type": "string",
+          "description": "Target node symbol ID (exact match or pattern)"
+        },
+        "kind": {
+          "type": "string",
+          "description": "Expected edge kind (e.g., 'call', 'plt', 'indirect')"
+        },
+        "min_confidence": {
+          "type": "number",
+          "minimum": 0.0,
+          "maximum": 1.0,
+          "description": "Minimum confidence for this specific edge"
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "If true, missing this edge fails CI"
+        },
+        "reason": {
+          "type": "string",
+          "description": "Why this edge is expected (for documentation)"
+        }
+      },
+      "required": ["from", "to"]
+    },
+    "expected_root": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Root node ID (exact match or pattern)"
+        },
+        "phase": {
+          "type": "string",
+          "enum": ["load", "init", "main", "runtime", "fini"],
+          "description": "Expected execution phase"
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "If true, missing this root fails CI"
+        },
+        "reason": {
+          "type": "string",
+          "description": "Why this root is expected"
+        }
+      },
+      "required": ["id"]
+    }
+  }
+}