atlas-iac/services/hermes/contracts/hux/permission.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hermes.bstein.dev/contracts/hux/v1/permission.schema.json",
  "title": "HUX autonomy, grants, approvals, cancellation",
  "description": "Policy engine records (HUX-05). A policy fixes the autonomy level and explicit capability grants for a scope; approvals are queued items answered with the existing gateway choices (once|session|always|deny); a cancellation receipt proves what a stop actually did.",
  "$defs": {
    "capability": {
      "type": "string",
      "enum": ["read_files", "write_files", "shell", "network", "web_search", "send_message", "memory_write", "artifact_write", "spend_tokens", "delegate", "deploy"]
    },
    "decision": {"type": "string", "enum": ["allow", "ask", "deny"]},
    "policy": {
      "type": "object",
      "additionalProperties": false,
      "required": ["schema", "id", "owner", "scope", "autonomy", "grants", "budgets", "provenance", "updated_at"],
      "properties": {
        "schema": {"const": "hux.policy.v1"},
        "id": {"$ref": "common.schema.json#/$defs/id"},
        "owner": {"$ref": "common.schema.json#/$defs/user_ref"},
        "scope": {
          "type": "object",
          "additionalProperties": false,
          "required": ["level"],
          "properties": {
            "level": {"type": "string", "enum": ["global", "project", "conversation"]},
            "scope_id": {"$ref": "common.schema.json#/$defs/id"}
          }
        },
        "autonomy": {"type": "string", "enum": ["ask_first", "safe", "autonomous"]},
        "grants": {
          "type": "array",
          "maxItems": 64,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["capability", "decision"],
            "properties": {
              "capability": {"$ref": "#/$defs/capability"},
              "decision": {"$ref": "#/$defs/decision"},
              "expires_at": {"$ref": "common.schema.json#/$defs/timestamp"},
              "granted_by": {"$ref": "common.schema.json#/$defs/actor"}
            }
          }
        },
        "budgets": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "tokens_per_run": {"type": "integer", "minimum": 0},
            "tool_calls_per_run": {"type": "integer", "minimum": 0},
            "wall_clock_seconds": {"type": "integer", "minimum": 0},
            "delegations_per_run": {"type": "integer", "minimum": 0}
          }
        },
        "provenance": {"$ref": "common.schema.json#/$defs/provenance"},
        "updated_at": {"$ref": "common.schema.json#/$defs/timestamp"}
      }
    },
    "approval": {
      "type": "object",
      "additionalProperties": false,
      "required": ["schema", "id", "run_id", "conversation_id", "capability", "request", "status", "requested_at", "expires_at"],
      "properties": {
        "schema": {"const": "hux.approval.v1"},
        "id": {"$ref": "common.schema.json#/$defs/id"},
        "run_id": {"type": "string", "minLength": 1, "maxLength": 120},
        "conversation_id": {"$ref": "common.schema.json#/$defs/id"},
        "capability": {"$ref": "#/$defs/capability"},
        "request": {
          "type": "object",
          "additionalProperties": false,
          "required": ["summary", "risk"],
          "properties": {
            "summary": {"type": "string", "minLength": 1, "maxLength": 280},
            "detail": {"type": "string", "maxLength": 4000},
            "risk": {"type": "string", "enum": ["low", "medium", "high"]},
            "evidence": {"type": "array", "maxItems": 16, "items": {"$ref": "common.schema.json#/$defs/evidence_ref"}}
          }
        },
        "status": {"type": "string", "enum": ["pending", "approved", "denied", "expired", "cancelled"]},
        "decision": {
          "type": "object",
          "additionalProperties": false,
          "required": ["choice", "by", "at"],
          "properties": {
            "choice": {"type": "string", "enum": ["once", "session", "always", "deny"]},
            "by": {"$ref": "common.schema.json#/$defs/actor"},
            "at": {"$ref": "common.schema.json#/$defs/timestamp"}
          }
        },
        "requested_at": {"$ref": "common.schema.json#/$defs/timestamp"},
        "expires_at": {"$ref": "common.schema.json#/$defs/timestamp"}
      }
    },
    "cancellation_receipt": {
      "type": "object",
      "additionalProperties": false,
      "required": ["schema", "id", "run_id", "requested_by", "requested_at", "outcome", "side_effects"],
      "properties": {
        "schema": {"const": "hux.cancel_receipt.v1"},
        "id": {"$ref": "common.schema.json#/$defs/id"},
        "run_id": {"type": "string", "minLength": 1, "maxLength": 120},
        "requested_by": {"$ref": "common.schema.json#/$defs/actor"},
        "requested_at": {"$ref": "common.schema.json#/$defs/timestamp"},
        "acknowledged_at": {"$ref": "common.schema.json#/$defs/timestamp"},
        "completed_at": {"$ref": "common.schema.json#/$defs/timestamp"},
        "outcome": {"type": "string", "enum": ["cancelled", "already_complete", "failed_to_cancel"]},
        "side_effects": {
          "type": "array",
          "maxItems": 64,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["description", "reverted"],
            "properties": {
              "description": {"type": "string", "minLength": 1, "maxLength": 280},
              "reverted": {"type": "boolean"},
              "evidence": {"$ref": "common.schema.json#/$defs/evidence_ref"}
            }
          }
        }
      }
    }
  },
  "oneOf": [
    {"$ref": "#/$defs/policy"},
    {"$ref": "#/$defs/approval"},
    {"$ref": "#/$defs/cancellation_receipt"}
  ]
}