{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://haltere.ai/receipt.schema.json",
  "title": "Haltere operation receipt",
  "version": "0.1",
  "description": "One governed operation, as the machine holds it. Fields marked x-proposed are part of the v1 shape and are not emitted today; every other field is on the record now. The published page is https://haltere.ai/receipt-spec.",
  "type": "object",
  "required": [
    "id",
    "ts",
    "actor",
    "operation",
    "context",
    "agent",
    "code",
    "checks",
    "effect"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "the receipt's identity: unique, ordered, never reused"
    },
    "ts": {
      "type": "string",
      "format": "date-time",
      "description": "the moment the operation ran"
    },
    "change": {
      "type": "string",
      "x-proposed": "proposed for v1: part of the shape, not yet emitted",
      "description": "the human-facing change number; today the join is the correlation id"
    },
    "work_order": {
      "type": "object",
      "x-proposed": "proposed for v1: part of the shape, not yet emitted",
      "description": "the governed unit of intent; today intent and scope ride on the command and its authorization decision",
      "properties": {
        "id": {
          "type": "string"
        },
        "scope": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "actor": {
      "type": "object",
      "required": [
        "id",
        "role"
      ],
      "description": "the human or service behind the request, with the role authority was exercised under",
      "properties": {
        "id": {
          "type": "string"
        },
        "role": {
          "type": "string"
        },
        "on_behalf_of": {
          "type": "string",
          "description": "set when the actor is an agent principal"
        },
        "grant": {
          "type": "string",
          "description": "the authorization grant the action ran under"
        }
      }
    },
    "operation": {
      "type": "string",
      "description": "the registered capability that ran, declared on the map before first use"
    },
    "context": {
      "type": "array",
      "description": "every reference the agent worked from, pinned before drafting",
      "items": {
        "type": "object",
        "required": [
          "ref"
        ],
        "properties": {
          "ref": {
            "type": "string"
          },
          "hash": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "band": {
            "type": "array",
            "items": {
              "type": "number"
            }
          }
        }
      }
    },
    "agent": {
      "type": "object",
      "description": "the model that ran and the exact rendered prompt at its own SHA",
      "properties": {
        "model": {
          "type": "string"
        },
        "prompt": {
          "type": "string"
        },
        "rendered_prompt_ref": {
          "type": "string"
        },
        "confidence": {
          "type": "number",
          "x-proposed": "proposed for v1: part of the shape, not yet emitted"
        },
        "alternatives": {
          "type": "array",
          "x-proposed": "proposed for v1: part of the shape, not yet emitted",
          "items": {
            "type": "object"
          }
        }
      }
    },
    "code": {
      "type": "object",
      "description": "a frozen permalink to what executed; resolves after every refactor since",
      "properties": {
        "commit": {
          "type": "string"
        },
        "path": {
          "type": "string"
        }
      }
    },
    "checks": {
      "type": "array",
      "minItems": 1,
      "description": "each policy gate, with the policy revision it ran against. Enforced before effect: a failed check means no effect and no approval requested.",
      "items": {
        "type": "object",
        "required": [
          "name",
          "policy",
          "result"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "policy": {
            "type": "string"
          },
          "result": {
            "enum": [
              "pass",
              "fail"
            ]
          },
          "detail": {
            "type": "string"
          }
        }
      }
    },
    "approval": {
      "description": "name, role, timestamp and the why, verbatim. Durable. Null when a check failed: a failed check never requests one.",
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "required": [
            "name",
            "role",
            "ts"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "role": {
              "type": "string"
            },
            "ts": {
              "type": "string",
              "format": "date-time"
            },
            "why": {
              "type": "string"
            },
            "requested": {
              "type": "boolean"
            }
          }
        }
      ]
    },
    "effect": {
      "type": "object",
      "description": "what changed. Empty on a refusal: the change did not merge.",
      "properties": {
        "writes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "merged": {
          "type": "boolean"
        }
      }
    },
    "seal": {
      "type": "object",
      "x-proposed": "proposed for v1: part of the shape, not yet emitted",
      "description": "content hash chained to the previous receipt. Today the record is append-only, enforced below the application by database trigger and by role; the hash chain is proposed for v1 and is not built. We do not call this tamper-evident.",
      "properties": {
        "hash": {
          "type": "string"
        },
        "prev": {
          "type": "string"
        }
      }
    },
    "pack": {
      "type": "array",
      "x-proposed": "proposed for v1: part of the shape, not yet emitted",
      "items": {
        "type": "string"
      },
      "description": "the exhibits this receipt feeds. Every exhibit is drawn from receipts the system already emits; a person assembles them into exhibits."
    }
  }
}