{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cloudworldmodel-ai/json-schema/cloudworldmodel-ai-hybrid-decision-schema.json",
  "title": "HybridDecision",
  "description": "One per-step hybrid referee decision.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cloudworldmodel-ai-openapi.yml#/components/schemas/HybridDecision",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "number"
    },
    "ruleBasedMetrics": {
      "type": "object",
      "description": "Metrics produced by the deterministic rule engine for this step. Percentiles are null when workload-specific latency evidence is unavailable.",
      "properties": {
        "latencyP50": {
          "type": [
            "number",
            "null"
          ]
        },
        "latencyP95": {
          "type": [
            "number",
            "null"
          ]
        },
        "latencyP99": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "mlPrediction": {
      "type": "object",
      "description": "Full ML prediction. When latency evidence is unavailable, latency reasoning is replaced with an explicit limitation, latency bottlenecks and latency-jitter quirks are omitted, and latency-bearing event impact text is withheld.",
      "properties": {
        "metrics": {
          "type": "object",
          "properties": {
            "latencyP50": {
              "type": [
                "number",
                "null"
              ],
              "description": "Null when workload-specific latency evidence is unavailable."
            },
            "latencyP95": {
              "type": [
                "number",
                "null"
              ],
              "description": "Null when workload-specific latency evidence is unavailable."
            },
            "latencyP99": {
              "type": [
                "number",
                "null"
              ],
              "description": "Null when workload-specific latency evidence is unavailable."
            }
          }
        },
        "overallConfidence": {
          "type": "number"
        },
        "reasoning": {
          "type": "string",
          "description": "Replaced with the latency-unavailable explanation when workload-specific latency evidence is unavailable."
        },
        "bottlenecks": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "eventLikelihoods": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      }
    },
    "hybridMetrics": {
      "type": "object",
      "description": "Final blended (or fallback) metrics used for this step. Percentiles are null when workload-specific latency evidence is unavailable.",
      "properties": {
        "latencyP50": {
          "type": [
            "number",
            "null"
          ]
        },
        "latencyP95": {
          "type": [
            "number",
            "null"
          ]
        },
        "latencyP99": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "latencyAvailability": {
      "$ref": "#/$defs/PredictionLatencyAvailability"
    },
    "comparisons": {
      "type": "array",
      "description": "Latency percentile comparisons are omitted when workload-specific latency evidence is unavailable.",
      "items": {
        "$ref": "#/$defs/HybridPredictionComparison"
      }
    },
    "agreement": {
      "$ref": "#/$defs/HybridAgreement",
      "description": "Omitted when latency evidence is unavailable because the agreement score includes latency comparisons."
    },
    "blendingApplied": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Null when workload-specific latency evidence is unavailable because blending may depend on withheld percentile comparisons."
    },
    "fallbackUsed": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Null when workload-specific latency evidence is unavailable because fallback may depend on withheld percentile safety checks."
    },
    "safetyBoundsViolated": {
      "type": "array",
      "description": "Latency-derived safety violations are omitted when workload-specific latency evidence is unavailable; unrelated violations remain.",
      "items": {
        "type": "string"
      }
    },
    "explanation": {
      "type": "string",
      "description": "Replaced with an explicit latency-unavailable explanation when workload-specific latency evidence is unavailable."
    },
    "behaviorMismatch": {
      "type": "object",
      "description": "Present when `agreement.level === \"low\"` AND at least one Kubernetes resource in the simulation carries GPU/inference characteristics (`accelerator`, `tokensPerRequest`, `inputTokensPerRequest`) without `inferenceMode: true`. Indicates that the rule engine is using `generic-kubernetes/load-saturation` for a resource that appears to be a GPU inference workload. This is a factual configuration note, not a claim about the ML predictor's internal model — enabling `inferenceMode` switches the rule engine to the `gpu-inference/ttft-decode` latency path AND activates the ML service's own independently calibrated TTFT/decode estimator (`gpu-inference/ttft-decode-ml`), so both models operate on the same workload class and the agreement score may change. Absent when agreement is not \"low\", no such misconfiguration is detected, or workload-specific latency evidence is unavailable.",
      "required": [
        "detected",
        "cause",
        "affectedResources"
      ],
      "properties": {
        "detected": {
          "type": "boolean",
          "description": "True when a rule-engine path mismatch was detected on this step."
        },
        "cause": {
          "type": "string",
          "description": "Human-readable explanation of the detected rule-engine configuration issue. Names the detected GPU characteristics and states what to set to activate the GPU inference latency path in the rule engine."
        },
        "affectedResources": {
          "type": "array",
          "description": "IDs of Kubernetes resources that triggered the mismatch.",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "rulesBehaviorModel": {
      "type": "string",
      "description": "Provenance: the latency path the rules engine used for this step's dominant workload class (e.g. `gpu-inference/ttft-decode` for inferenceMode Kubernetes GPU clusters, `generic-kubernetes/load-saturation` otherwise)."
    },
    "mlBehaviorModel": {
      "type": "string",
      "description": "Provenance: the path/label the ML service used for this prediction (e.g. `gpu-inference/ttft-decode-ml` when the ML service applied its independently calibrated TTFT/decode token-economics estimator, or `generic/nonlinear-heuristics` for the default heuristic path)."
    },
    "behaviorAlignment": {
      "type": "string",
      "enum": [
        "aligned",
        "misaligned"
      ],
      "description": "`aligned` when the rules engine and ML service operated on the same workload class for this step; `misaligned` when they diverged (e.g. rules used the GPU-inference TTFT model but ML fell back to generic compute saturation). Lets a disagreement be diagnosed as \"same model, different numbers\" vs \"different models entirely\"."
    },
    "modelingNote": {
      "type": "string",
      "description": "Optional provenance note. Present on GPU inference steps (`rulesBehaviorModel: gpu-inference/ttft-decode`) to remind API consumers that TTFT and decode-throughput figures reported in this decision are produced by the CWM simulation model and are not externally measured hardware benchmarks. Absent on non-inference steps."
    }
  },
  "$defs": {
    "HybridAgreement": {
      "type": "object",
      "description": "Model agreement — how closely the ML model and rule engine agree with\neach other on a hybrid step (distinct from ML confidence, which is the\nmodel's belief in its own prediction). Derived from the largest\nnormalised deviation among cost, latency P95, latency P99, and error rate, each\nnormalised against its safety-bound threshold (maxCostDeviation,\nmaxLatencyDeviation, maxErrorRateDeviation), so one dimension way off\ncannot be washed out by agreement on the others. Sits alongside the\nper-field `comparisons` array so component signals can be inspected\ndirectly. Absent on decisions persisted before this field existed.\n\n**Safety-fallback participation:** both latencyP95 and latencyP99\ndeviations are checked against `maxLatencyDeviation` in\n`checkSafetyBounds`. A P99 disagreement that exceeds the threshold\ntriggers the rule-based fallback in the same way a P95 violation does.\nConsumers should therefore treat `largestDisagreement: \"latencyP99\"`\nas a first-class fallback signal, not merely an informational label.\n",
      "required": [
        "score",
        "level",
        "largestDisagreement"
      ],
      "properties": {
        "score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "0–1, where 1.0 = strong agreement."
        },
        "level": {
          "type": "string",
          "enum": [
            "high",
            "moderate",
            "low"
          ],
          "description": "score ≥ 0.75 → high, ≥ 0.4 → moderate, else low."
        },
        "largestDisagreement": {
          "type": "string",
          "enum": [
            "cost",
            "latencyP95",
            "latencyP99",
            "errorRate"
          ],
          "description": "The dimension with the largest normalised rule/ML deviation."
        },
        "normalizationBasis": {
          "type": "string",
          "enum": [
            "absolute_safety_bounds"
          ],
          "description": "The agreement score is calibrated against the configured safety-bound\nthresholds, not against relative sensitivity of each metric. Latency\n(P95/P99) and error-rate deviations are absolute differences (ms and\npercentage points) divided by maxLatencyDeviation /\nmaxErrorRateDeviation; cost deviation is relative to the rule-based\ncost, divided by maxCostDeviation. A deviation that is large in\nrelative terms but small against its bound (e.g. error rate\n0.1% → 0.5% against a 5 pp bound) can therefore still score as\nhigh agreement.\n"
        }
      }
    },
    "HybridPredictionComparison": {
      "type": "object",
      "description": "Per-field rule vs ML vs blended comparison for one hybrid step.",
      "properties": {
        "field": {
          "type": "string"
        },
        "ruleValue": {
          "type": "number"
        },
        "mlValue": {
          "type": "number"
        },
        "hybridValue": {
          "type": "number"
        },
        "deviation": {
          "type": "number",
          "description": "Absolute rule/ML difference in the field's native units."
        },
        "source": {
          "type": "string",
          "enum": [
            "rules",
            "ml",
            "hybrid_blend",
            "rules_fallback"
          ]
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "reasoning": {
          "type": "string"
        }
      }
    },
    "PredictionLatencyAvailability": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "status",
        "reason",
        "resourceIds"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "unavailable"
          ]
        },
        "reason": {
          "type": "string",
          "minLength": 1,
          "description": "Names the unresolved Fargate shape, missing workload-specific latency calibration, and applicable per-edge timeout boundary."
        },
        "resourceIds": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    }
  }
}