{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://uwmd.org/schemas/calc-result.schema.json",
  "title": "UW Calc Engine Result",
  "description": "Output of a single safe-expression evaluation by a Tier-3 Calc Host. Mirrors the CalcResult interface in @uwmd/verify's protocol.ts. See UW_PROTOCOL.md §VIII for the safe-expression language and the deterministic-evaluation contract.",
  "type": "object",
  "required": ["calc_id", "ok", "value"],
  "additionalProperties": false,
  "properties": {
    "calc_id": {
      "type": "string",
      "minLength": 1,
      "description": "ID from the calculation declaration."
    },
    "ok": {
      "type": "boolean",
      "description": "True if evaluation succeeded. False when `error` is set."
    },
    "value": {
      "type": ["number", "string", "boolean", "null"],
      "description": "Result of the expression. A numeric value is quantized to `round_to` decimal places, half away from zero, per §VIII.5 — it carries no unquantized tail, and it is this value that a receipt digest covers. Null when an input was null (per the null-propagation rule §VIII.2) or when ok=false."
    },
    "unit": {
      "type": "string",
      "description": "Unit string copied from the calc declaration (e.g. '%', '$', 'x', 'units'). Renderers use this to pick a number formatter."
    },
    "round_to": {
      "type": "integer",
      "minimum": 0,
      "maximum": 12,
      "description": "Decimal places `value` was quantized to — the declaration's `round_to` when it stated one, otherwise the §VIII.5 default for `unit`. Echoed so a consumer can see the precision contract it received rather than having to re-derive it."
    },
    "display": {
      "type": "string",
      "description": "Pre-formatted display string per DEFAULT_NUMBER_FORMAT (en-US in v1). Convenience for renderers that don't want to re-format."
    },
    "error": {
      "$ref": "https://uwmd.org/schemas/protocol-error.schema.json",
      "description": "Set when ok=false. Code MUST be one of CALC-PARSE-001, CALC-RESOLVE-001, CALC-TYPE-001, CALC-DIV-ZERO, CALC-IRR-DIVERGE, CALC-LIMIT-001, CALC-SENS-001..005 (sensitivity declarations, protocol §VIII.7.4), CALC-STOCH-001..006 (stochastic declarations, §VIII.8.5), or a module-prefixed code."
    }
  },
  "examples": [
    {
      "calc_id": "revpar",
      "ok": true,
      "value": 104.76,
      "unit": "$",
      "round_to": 2,
      "display": "$104.76"
    },
    {
      "calc_id": "implied_dscr",
      "ok": true,
      "value": 1.3896,
      "unit": "x",
      "round_to": 4,
      "display": "1.390x"
    },
    {
      "calc_id": "broken_calc",
      "ok": false,
      "value": null,
      "error": {
        "category": "calc",
        "code": "CALC-DIV-ZERO",
        "message": "Division by zero in expression 'a / b' (b = 0)."
      }
    }
  ]
}
