{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://qzx.yumbale.com/schemas/result-contract-v1.schema.json",
  "title": "QZX Result Contract v1",
  "description": "Open result envelope for QZX commands and compatible agent-facing command tools. Producers may add command-specific fields without changing the stable core.",
  "type": "object",
  "required": [
    "success",
    "message"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "description": "True only when the requested operation completed successfully."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "description": "A complete human-readable summary of the outcome."
    },
    "error": {
      "type": "string",
      "minLength": 1,
      "description": "A human-readable failure description when success is false."
    },
    "error_code": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]*$",
      "description": "A stable machine-oriented failure identifier when available."
    },
    "details": {
      "type": "object",
      "description": "Structured diagnostic, remediation, or domain-specific details."
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Non-fatal conditions that deserve explicit attention."
    },
    "meta": {
      "type": "object",
      "properties": {
        "schema_version": {
          "const": 1,
          "description": "Version of the shared QZX result metadata envelope."
        },
        "command": {
          "type": "string",
          "minLength": 1
        },
        "duration_ms": {
          "type": "number",
          "minimum": 0
        },
        "command_maturity": {
          "type": "object"
        }
      },
      "additionalProperties": true,
      "description": "Shared invocation metadata. Command-specific metadata may use additional fields."
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "success": {
            "const": false
          }
        },
        "required": [
          "success"
        ]
      },
      "then": {
        "anyOf": [
          {
            "required": [
              "error"
            ]
          },
          {
            "required": [
              "error_code"
            ]
          }
        ]
      }
    }
  ],
  "additionalProperties": true,
  "examples": [
    {
      "success": true,
      "message": "Current local date and time returned in ISO 8601 format.",
      "output": "2026-08-07T21:45:00-05:00",
      "meta": {
        "command": "getCurrentDateTime",
        "duration_ms": 2.4,
        "schema_version": 1
      }
    },
    {
      "success": false,
      "message": "The requested path was not found.",
      "error": "Path not found: missing.txt",
      "error_code": "path_not_found",
      "details": {
        "path": "missing.txt"
      },
      "meta": {
        "command": "readFile",
        "duration_ms": 1.1,
        "schema_version": 1
      }
    }
  ]
}