{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://heartcortex.ai/schemas/1.0/reason-response.schema.json",
  "title": "Reason response",
  "description": "Also the response to /ask. Models propose; they never execute.",
  "type": "object",
  "required": [
    "id",
    "status",
    "model",
    "usage"
  ],
  "properties": {
    "id": {
      "$ref": "common.schema.json#/$defs/uuid"
    },
    "status": {
      "enum": [
        "completed",
        "refused",
        "truncated"
      ]
    },
    "text": {
      "type": "string"
    },
    "json": {},
    "proposedActions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "capability",
          "arguments"
        ],
        "properties": {
          "capability": {
            "$ref": "common.schema.json#/$defs/capabilityName"
          },
          "arguments": {
            "type": "object"
          },
          "rationale": {
            "type": "string"
          },
          "expect": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "items": {
              "$ref": "common.schema.json#/$defs/check"
            }
          },
          "undoIf": {
            "$ref": "proposal.schema.json#/properties/undoIf"
          }
        }
      },
      "description": "Suggestions, not actions. One that changes state MUST be handled as a Proposal (Core Standard, Section 7.3): without expect and undoIf it is refused. For task 'propose', put Proposals in 'json' instead."
    },
    "groundedIn": {
      "description": "Rhythm sequence numbers the answer relied on.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0
      }
    },
    "model": {
      "type": "object",
      "required": [
        "reasoning"
      ],
      "properties": {
        "reasoning": {
          "enum": [
            "cloud",
            "local",
            "rules-only"
          ]
        },
        "provider": {
          "type": "string"
        },
        "model": {
          "type": "string"
        },
        "fallbackUsed": {
          "type": "boolean"
        }
      }
    },
    "usage": {
      "type": "object",
      "properties": {
        "inputTokens": {
          "type": "integer",
          "minimum": 0
        },
        "outputTokens": {
          "type": "integer",
          "minimum": 0
        },
        "costUsd": {
          "type": "number",
          "minimum": 0
        },
        "latencyMs": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "receiptId": {
      "$ref": "common.schema.json#/$defs/uuid"
    },
    "signed": {
      "$ref": "common.schema.json#/$defs/brainSignature",
      "description": "Set by a Command Center (API Standard 7.4 rule 5). A system with the brain module rejects an answer without it."
    }
  }
}