{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.ai4energy.cn/schema/esml-result-v1.json",
  "title": "ESML one-shot result and error envelopes (v1)",
  "description": "Solve and simulate successes plus the machine-readable failure envelope. Fields may be added in future v1 releases; clients must ignore unknown fields.",
  "oneOf": [
    { "$ref": "#/$defs/solve" },
    { "$ref": "#/$defs/simulate" },
    { "$ref": "#/$defs/error" }
  ],
  "$defs": {
    "unit": {
      "type": ["string", "null"],
      "description": "SI dimension expression; \"1\" = dimensionless; null = the model declared no unit."
    },
    "unitCoverage": {
      "type": "object",
      "required": ["known", "total", "complete"],
      "properties": {
        "known": { "type": "integer", "minimum": 0 },
        "total": { "type": "integer", "minimum": 0 },
        "complete": { "type": "boolean" }
      },
      "additionalProperties": true
    },
    "solveValue": {
      "type": "object",
      "required": ["path", "value", "unit"],
      "properties": {
        "path": { "type": "string", "minLength": 1 },
        "value": { "type": "number" },
        "unit": { "$ref": "#/$defs/unit" }
      },
      "additionalProperties": true
    },
    "solve": {
      "type": "object",
      "required": ["apiVersion", "system", "unknowns", "values", "meta"],
      "properties": {
        "apiVersion": { "const": "esml.solve/v1" },
        "system": { "type": "string" },
        "unknowns": { "type": "integer", "minimum": 0 },
        "values": {
          "type": "array",
          "items": { "$ref": "#/$defs/solveValue" }
        },
        "meta": {
          "type": "object",
          "required": ["engineVersion", "docHash", "durationMs", "converged", "unitCoverage"],
          "properties": {
            "engineVersion": { "type": "string", "minLength": 1 },
            "docHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
            "durationMs": { "type": "number", "minimum": 0 },
            "converged": { "const": true },
            "iterations": { "type": ["integer", "null"], "minimum": 0 },
            "residual": { "type": ["number", "null"] },
            "residualTolerance": { "type": ["number", "null"] },
            "unitCoverage": { "$ref": "#/$defs/unitCoverage" }
          },
          "additionalProperties": true
        },
        "ddm": {
          "type": "object",
          "description": "Present only for `solve --ddm`; adds the coordinator's zone/cut counters."
        }
      },
      "additionalProperties": true
    },
    "simulate": {
      "type": "object",
      "required": ["apiVersion", "system", "steps", "points", "columns", "units", "t", "rows", "meta"],
      "properties": {
        "apiVersion": { "const": "esml.simulate/v1" },
        "system": { "type": "string" },
        "steps": { "type": "integer", "minimum": 0 },
        "points": { "type": "integer", "minimum": 1 },
        "columns": { "type": "array", "items": { "type": "string" } },
        "units": {
          "type": "object",
          "additionalProperties": { "type": "string" }
        },
        "t": { "type": "array", "items": { "type": "number" } },
        "rows": {
          "type": "array",
          "items": { "type": "array", "items": { "type": ["number", "null"] } }
        },
        "meta": {
          "type": "object",
          "required": ["engineVersion", "docHash", "durationMs", "unitCoverage"],
          "properties": {
            "engineVersion": { "type": "string", "minLength": 1 },
            "docHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
            "durationMs": { "type": "number", "minimum": 0 },
            "unitCoverage": { "$ref": "#/$defs/unitCoverage" }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "required": ["apiVersion", "code", "message", "hint", "docHash", "engineVersion"],
      "properties": {
        "apiVersion": { "const": "esml.error/v1" },
        "code": {
          "type": "string",
          "minLength": 1,
          "examples": [
            "license.size",
            "license.dtil",
            "io.read",
            "solve.failed",
            "model.parse",
            "model.structure",
            "usage",
            "engine.error"
          ]
        },
        "message": { "type": "string", "minLength": 1 },
        "hint": { "type": ["string", "null"] },
        "docHash": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$" },
        "engineVersion": { "type": "string", "minLength": 1 }
      },
      "additionalProperties": true
    }
  }
}