{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://coulomb.social/resource-control/optimization-case.schema.json",
  "title": "Resource optimization case",
  "description": "An evidence-backed comparison between a baseline resource arrangement and one or more alternatives. Every option must present the same decision fields; unknown values are null and are reported as blocking evidence gaps rather than assumed.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "record_scope",
    "case_id",
    "case_type",
    "trigger",
    "review_period",
    "created_at",
    "resource_ids",
    "baseline",
    "alternatives",
    "decision",
    "evidence"
  ],
  "properties": {
    "schema_version": {
      "const": "0.1"
    },
    "record_scope": {
      "description": "operational cases assert real facts; illustrative cases exist only to exercise the mechanism.",
      "enum": [
        "operational",
        "illustrative"
      ]
    },
    "case_id": {
      "type": "string",
      "pattern": "^opt:[a-z0-9][a-z0-9:._-]+$"
    },
    "case_type": {
      "enum": [
        "rightsizing",
        "consolidation",
        "commitment",
        "renewal",
        "migration",
        "retirement",
        "provider_switch"
      ]
    },
    "trigger": {
      "enum": [
        "cadence",
        "renewal",
        "variance",
        "incident",
        "request",
        "procurement"
      ]
    },
    "review_period": {
      "type": "string",
      "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "resource_ids": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "pattern": "^resource:"
      }
    },
    "baseline": {
      "$ref": "#/$defs/option"
    },
    "alternatives": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/option"
      }
    },
    "decision": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "state",
        "recommended_option_id",
        "rationale",
        "approver",
        "approved_on",
        "delegated_to"
      ],
      "properties": {
        "state": {
          "description": "blocked_on_evidence until every decision field of the compared options is known; proposed once the case computes; then approved or rejected by the named authority.",
          "enum": [
            "blocked_on_evidence",
            "proposed",
            "approved",
            "rejected",
            "superseded"
          ]
        },
        "recommended_option_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "rationale": {
          "type": "string",
          "minLength": 1
        },
        "approver": {
          "description": "Named human or repository authority. Null while the case is not yet decided.",
          "type": [
            "string",
            "null"
          ]
        },
        "approved_on": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "delegated_to": {
          "description": "Repositories that own any approved implementation. resource-control never implements.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        }
      }
    },
    "financial_handoff": {
      "description": "What is sent to fin-hub when the case is approved.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "cost_attribution_key",
        "sent"
      ],
      "properties": {
        "cost_attribution_key": {
          "type": [
            "string",
            "null"
          ]
        },
        "sent": {
          "type": "boolean"
        },
        "reference": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "outcome": {
      "description": "Closes the loop: which control-cycle records will show whether the case was right.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "feeds_forecast",
        "actual_refs"
      ],
      "properties": {
        "feeds_forecast": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "actual_refs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        }
      }
    },
    "evidence": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/evidence_ref"
      }
    }
  },
  "$defs": {
    "measurement": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "value",
        "unit"
      ],
      "properties": {
        "value": {
          "type": [
            "number",
            "null"
          ]
        },
        "unit": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "utilization": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "provisioned",
        "used"
      ],
      "properties": {
        "provisioned": {
          "$ref": "#/$defs/measurement"
        },
        "used": {
          "$ref": "#/$defs/measurement"
        }
      }
    },
    "evidence_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "kind",
        "ref",
        "authority"
      ],
      "properties": {
        "kind": {
          "enum": [
            "telemetry",
            "quote",
            "contract",
            "invoice",
            "forecast",
            "workplan",
            "document",
            "decision"
          ]
        },
        "ref": {
          "type": "string",
          "minLength": 1
        },
        "authority": {
          "type": "string",
          "minLength": 1
        },
        "observed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        }
      }
    },
    "option": {
      "description": "Baseline and alternatives carry identical decision fields so they compare on equal terms. A null cost or utilization value means unknown, never zero.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "option_id",
        "label",
        "one_time_eur",
        "recurring_infrastructure_eur_month",
        "recurring_internal_labor_eur_month",
        "recurring_external_labor_eur_month",
        "utilization",
        "uncertainty",
        "service_constraints",
        "failure_domains",
        "exit_path",
        "unknowns"
      ],
      "properties": {
        "option_id": {
          "type": "string",
          "minLength": 1
        },
        "label": {
          "type": "string",
          "minLength": 1
        },
        "one_time_eur": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0
        },
        "recurring_infrastructure_eur_month": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0
        },
        "recurring_internal_labor_eur_month": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0
        },
        "recurring_external_labor_eur_month": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0
        },
        "utilization": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/utilization"
          }
        },
        "uncertainty": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "level",
            "notes"
          ],
          "properties": {
            "level": {
              "enum": [
                "low",
                "medium",
                "high"
              ]
            },
            "notes": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "service_constraints": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/measurement"
          }
        },
        "failure_domains": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "exit_path": {
          "type": [
            "string",
            "null"
          ]
        },
        "unknowns": {
          "description": "Named blocking evidence gaps, each attributable to an owning repository or authority.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "excluded": {
          "type": "boolean",
          "default": false,
          "description": "True when an alternative could not be evaluated and the deciding authority chose to exclude it rather than wait. An excluded option does not block the case, and its exclusion_reason becomes part of the decision record."
        },
        "exclusion_reason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Required when excluded is true: why the option was set aside, and what would bring it back."
        }
      }
    }
  }
}