{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.connectsoft.ai/reference/schemas/usage-record.schema.json",
  "title": "Usage reservation and record (usage-reservation-v1, usage-record-v1)",
  "description": "Usage Accounting (BC-05): a reservation is taken before dispatch and settled afterwards; a usage record carries the pricing revision it was priced with and a reconciliation state. Unknown usage stays unknown rather than zero.",
  "$defs": {
    "UsageReservation": {
      "type": "object", "required": ["reservationId", "tenantId", "projectId", "runId", "amount", "state", "expiresAt"], "additionalProperties": false,
      "properties": {
        "reservationId": { "type": "string", "format": "uuid" },
        "tenantId": { "type": "string" }, "projectId": { "type": "string" }, "runId": { "type": "string", "format": "uuid" },
        "budgetId": { "type": "string" },
        "amount": { "type": "object", "required": ["estimatedCostUsd"], "properties": { "estimatedCostUsd": { "type": "number" }, "tokens": { "type": "integer" }, "sandboxMinutes": { "type": "integer" } } },
        "state": { "enum": ["Reserved", "Settled", "Released", "Denied", "Expired"] },
        "approvalId": { "type": "string", "format": "uuid", "description": "Present when the estimate exceeded the platform spend threshold (D21)." },
        "expiresAt": { "type": "string", "format": "date-time" }
      }
    },
    "UsageRecord": {
      "type": "object", "required": ["usageId", "tenantId", "projectId", "runId", "meter", "quantity", "status", "pricingRevision", "occurredAt"], "additionalProperties": false,
      "properties": {
        "usageId": { "type": "string", "format": "uuid" },
        "tenantId": { "type": "string" }, "projectId": { "type": "string" }, "runId": { "type": "string", "format": "uuid" }, "stepId": { "type": "string", "format": "uuid" }, "attemptId": { "type": "string", "format": "uuid" },
        "reservationId": { "type": "string", "format": "uuid" },
        "meter": { "enum": ["model.tokens", "runs.accepted", "runs.completed", "tools.invocations", "sandbox.minutes", "storage.gb", "product.capacity"] },
        "dimensions": { "type": "object", "additionalProperties": { "type": "string" }, "description": "profile, provider, model, tool, pool, store, product, sloTier …" },
        "quantity": { "type": "number" },
        "status": { "enum": ["estimated", "reserved", "observed", "reconciled", "uncertain"] },
        "pricingRevision": { "type": "string" },
        "currency": { "type": "string", "default": "USD" },
        "estimatedCost": { "type": "number" },
        "confirmedCost": { "type": "number" },
        "sourceReceipt": { "type": "string", "description": "Model or tool receipt id that produced this record." },
        "occurredAt": { "type": "string", "format": "date-time" },
        "reconciledAt": { "type": "string", "format": "date-time" }
      }
    }
  },
  "oneOf": [{ "$ref": "#/$defs/UsageReservation" }, { "$ref": "#/$defs/UsageRecord" }]
}