{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/welkaim/ea-codex/schemas/v1/fitness-function.json",
  "title": "FitnessFunction",
  "description": "Typed architectural control that proves whether a decision, principle, standard, or policy remains respected. A FitnessFunction is a named, identifiable check (FF-SAP-001, FF-PV-002) implemented in a policy language (Rego, Cedar, CEL, SQL) and run by a CI pipeline, runtime gate, or scheduled scan. Earns a typed kind because it closes the loop from a DecisionRecord's verification requirement to an actual executable check, and produces EvidenceRecord artifacts. Without typed FitnessFunction, the chain Decision -> Specification -> Control -> Evidence runs through unchecked strings. Introduced in Chapter 14.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata", "spec"],
  "properties": {
    "apiVersion": { "$ref": "_common.json#/$defs/apiVersion" },
    "kind": { "type": "string", "const": "FitnessFunction" },
    "metadata": { "$ref": "_common.json#/$defs/metadata" },
    "spec": {
      "type": "object",
      "required": ["controlType", "evaluates", "implementation", "enforcementMode"],
      "properties": {
        "controlType": {
          "type": "string",
          "enum": ["fitness-function", "runtime-gate", "scheduled-scan", "ci-check"],
          "description": "How the control runs. fitness-function is the default architectural control; runtime-gate enforces at request time; scheduled-scan walks the portfolio periodically; ci-check runs in pull-request validation."
        },
        "evaluates": {
          "type": "array",
          "minItems": 1,
          "description": "What the control checks. Each entry names a typed attribute path on a fact-sheet, an artifact field, or a runtime signal that the control predicates on.",
          "items": { "type": "string" }
        },
        "implementation": {
          "type": "object",
          "required": ["language"],
          "description": "How the control is implemented. The Codex does not embed the implementation; it points at the policy package or scan job that runs it.",
          "properties": {
            "language": {
              "type": "string",
              "enum": ["rego", "cedar", "cel", "sql", "graph-query", "test-harness", "custom"]
            },
            "packageRef": {
              "type": "string",
              "description": "Reference to the implementing artifact. For Rego this is typically a RegoPackage identifier (REGO-...); for CI checks it is a workflow path or job name."
            }
          },
          "additionalProperties": true
        },
        "enforcementMode": {
          "type": "string",
          "enum": ["deny", "warn", "log", "advisory"],
          "description": "What happens when the control fails. deny blocks the action or merge; warn surfaces a warning but allows progress; log records the failure without surfacing it; advisory is informational only."
        },
        "enforces": {
          "type": "object",
          "description": "Which artifacts the control enforces. At least one of decisionRefs, principleRefs, standardRefs, or policyRefs should be populated for an approved control.",
          "properties": {
            "decisionRefs": {
              "type": "array",
              "items": { "$ref": "_common.json#/$defs/identifier" }
            },
            "principleRefs": {
              "type": "array",
              "items": { "$ref": "_common.json#/$defs/identifier" }
            },
            "standardRefs": {
              "type": "array",
              "items": { "$ref": "_common.json#/$defs/identifier" }
            },
            "policyRefs": {
              "type": "array",
              "items": { "$ref": "_common.json#/$defs/identifier" }
            }
          },
          "additionalProperties": true
        },
        "scope": {
          "type": "object",
          "description": "Where the control applies. Restricts the universe of artifacts the check evaluates against.",
          "properties": {
            "factSheetTypes": {
              "type": "array",
              "items": { "type": "string" }
            },
            "capabilityRefs": {
              "type": "array",
              "items": { "type": "string" }
            },
            "jurisdictions": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "additionalProperties": true
        },
        "evidenceProfile": {
          "type": "object",
          "description": "What the control emits as evidence on each run. EvidenceRecord artifacts referencing this FitnessFunction must conform to this profile.",
          "properties": {
            "resultEnum": {
              "type": "array",
              "items": { "type": "string" },
              "default": ["pass", "fail", "pass-with-warnings", "skipped"]
            },
            "retainEvidenceFor": {
              "type": "string",
              "description": "Retention duration (e.g., '7y' for regulated controls, '90d' for advisory)."
            }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}