Refactor code structure for improved readability and maintainability; optimize performance in key functions.

docs/schemas/predicates/policy-decision.v1.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stella.ops/predicates/policy-decision@v1",
+  "title": "StellaOps Policy Decision Attestation Predicate",
+  "description": "Predicate for policy evaluation decision attestations.",
+  "type": "object",
+  "required": ["finding_id", "cve", "component_purl", "decision", "reasoning", "evidence_refs", "evaluated_at", "policy_version"],
+  "properties": {
+    "finding_id": {
+      "type": "string",
+      "description": "The finding ID (CVE@PURL format)."
+    },
+    "cve": {
+      "type": "string",
+      "description": "The CVE identifier."
+    },
+    "component_purl": {
+      "type": "string",
+      "description": "The component Package URL."
+    },
+    "decision": {
+      "type": "string",
+      "enum": ["Allow", "Review", "Block", "Suppress", "Escalate"],
+      "description": "The policy decision result."
+    },
+    "reasoning": {
+      "type": "object",
+      "required": ["rules_evaluated", "rules_matched", "final_score", "risk_multiplier"],
+      "properties": {
+        "rules_evaluated": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of policy rules evaluated."
+        },
+        "rules_matched": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Names of policy rules that matched."
+        },
+        "final_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Final computed risk score (0-100)."
+        },
+        "risk_multiplier": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Risk multiplier applied (1.0 = no change)."
+        },
+        "reachability_state": {
+          "type": "string",
+          "description": "Reachability state used in decision."
+        },
+        "vex_status": {
+          "type": "string",
+          "description": "VEX status used in decision."
+        },
+        "summary": {
+          "type": "string",
+          "description": "Human-readable summary of decision rationale."
+        }
+      }
+    },
+    "evidence_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^sha256:[a-f0-9]{64}$"
+      },
+      "description": "References to evidence artifacts used in the decision."
+    },
+    "evaluated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the decision was evaluated (UTC ISO 8601)."
+    },
+    "expires_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the decision expires (UTC ISO 8601)."
+    },
+    "policy_version": {
+      "type": "string",
+      "description": "Version of the policy used for evaluation."
+    },
+    "policy_hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "Hash of the policy configuration used."
+    }
+  },
+  "additionalProperties": false
+}