{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.connectsoft.ai/reference/schemas/model-invocation.schema.json",
  "title": "Model invocation and receipt (model-invocation-v1, model-receipt-v1)",
  "description": "Contract of the model gateway (GW-04, BC-07): a request names a logical profile and a budget; the receipt records the actual provider, model and deployment, the policy receipt and the usage status.",
  "$defs": {
    "ModelInvocation": {
      "type": "object",
      "required": ["invocationId", "profileId", "scope", "runId", "attemptId", "requestHash", "classification", "budget"],
      "additionalProperties": false,
      "properties": {
        "invocationId": { "type": "string", "format": "uuid" },
        "profileId": { "type": "string" },
        "profileRevision": { "type": "string" },
        "scope": { "$ref": "execution-scope.schema.json" },
        "runId": { "type": "string", "format": "uuid" },
        "stepId": { "type": "string", "format": "uuid" },
        "attemptId": { "type": "string", "format": "uuid" },
        "requestHash": { "type": "string", "description": "Hash of the canonical request (messages, tools, schema); content stays in the artifact store." },
        "idempotencyKey": { "type": "string" },
        "classification": { "enum": ["public", "internal", "confidential", "restricted"] },
        "capabilities": { "type": "array", "items": { "enum": ["tools", "parallel-tools", "structured-output", "vision", "long-context", "embedding", "reranking", "streaming"] } },
        "budget": { "type": "object", "properties": { "maxInputTokens": { "type": "integer" }, "maxOutputTokens": { "type": "integer" }, "maxCostUsd": { "type": "number" }, "deadline": { "type": "string", "format": "date-time" } } },
        "stream": { "type": "boolean", "default": false },
        "outputSchemaRef": { "type": "string", "description": "Descriptor id when structured output is required." }
      }
    },
    "ModelReceipt": {
      "type": "object",
      "required": ["invocationId", "status", "route", "usage", "policyReceipt", "receiptHash"],
      "additionalProperties": false,
      "properties": {
        "invocationId": { "type": "string", "format": "uuid" },
        "status": { "enum": ["Succeeded", "Failed", "Denied", "TimedOut", "Cancelled", "PartialStream"] },
        "route": {
          "type": "object", "required": ["provider", "model"],
          "properties": { "provider": { "enum": ["openai", "azure-openai", "azure-ai-inference", "ollama", "anthropic"] }, "model": { "type": "string" }, "deployment": { "type": "string" }, "region": { "type": "string" }, "fallbackOf": { "type": "string", "description": "Profile or route that failed before this route was used." } }
        },
        "usage": {
          "type": "object", "required": ["status"],
          "properties": { "status": { "enum": ["observed", "estimated", "unknown"] }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "cachedTokens": { "type": "integer" }, "reasoningTokens": { "type": "integer" }, "latencyMs": { "type": "integer" }, "pricingRevision": { "type": "string" }, "estimatedCostUsd": { "type": "number" }, "confirmedCostUsd": { "type": "number" } }
        },
        "policyReceipt": { "$ref": "policy-decision.schema.json" },
        "validation": { "type": "object", "properties": { "structuredOutputValid": { "type": "boolean" }, "repairs": { "type": "integer" }, "retries": { "type": "integer" } } },
        "outputRef": { "type": "string", "description": "Artifact reference of the output; never inlined." },
        "diagnosticsRef": { "type": "string" },
        "receiptHash": { "type": "string" }
      }
    }
  },
  "oneOf": [{ "$ref": "#/$defs/ModelInvocation" }, { "$ref": "#/$defs/ModelReceipt" }]
}