{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://datainsight.at/tools/ahil/schema/v1.0.json",
  "title": "AHIL Exchange File",
  "description": "Agent Human Interface Language v1.0 — typed, append-only exchange log between AI agents and humans.",
  "type": "object",
  "required": ["schema_version", "entries"],
  "additionalProperties": false,
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "1.0",
      "description": "AHIL schema version. Must be \"1.0\"."
    },
    "description": {
      "type": "string",
      "description": "Optional human-readable description of this exchange layer instance."
    },
    "entries": {
      "type": "array",
      "description": "Append-only log of all exchange entries. Never remove or modify existing items.",
      "items": { "$ref": "#/definitions/Entry" }
    }
  },
  "definitions": {
    "Entry": {
      "type": "object",
      "required": ["id", "type", "from", "to", "date", "status", "content"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9_]+-[0-9]{8}-[0-9]{3}$",
          "description": "Unique entry ID. Format: <sender>-<YYYYMMDD>-<NNN>. E.g. scout-20260317-001.",
          "examples": ["scout-20260317-001", "human-20260317-001", "project_architect-20260317-002"]
        },
        "type": {
          "type": "string",
          "enum": [
            "observation",
            "recommendation",
            "alert",
            "order",
            "approval",
            "override",
            "acknowledgement"
          ],
          "description": "Entry type. Determines direction, semantics, and expected status lifecycle."
        },
        "from": {
          "type": "string",
          "minLength": 1,
          "description": "Sender identifier. Agent slug (e.g. \"scout\", \"de_setup_agent\") or \"human\".",
          "examples": ["scout", "project_architect", "de_setup_agent", "data_freshness_monitor", "human", "harlie"]
        },
        "to": {
          "type": "string",
          "minLength": 1,
          "description": "Recipient. Agent slug, \"human\", or \"all\" for broadcast.",
          "examples": ["project_architect", "scout", "human", "all", "publisher"]
        },
        "date": {
          "type": "string",
          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
          "description": "ISO 8601 date the entry was written. E.g. \"2026-03-17\"."
        },
        "status": {
          "type": "string",
          "enum": ["pending", "noted", "acknowledged", "acted", "rejected"],
          "description": "Lifecycle status. See status transition rules in README."
        },
        "content": {
          "type": "string",
          "minLength": 1,
          "description": "The message body in plain English. Must be specific enough to act on without additional context."
        },
        "context": {
          "type": "object",
          "description": "Optional structured metadata. Free-form key-value pairs relevant to this entry.",
          "examples": [
            { "priority": "high", "trigger_tool": "duckdb", "suggested_slug": "duckdb-lakehouse" },
            { "ref": "scout-20260317-001", "slug": "local-llm-inference-pipeline", "case_number": "020" }
          ]
        }
      },
      "if": {
        "properties": { "type": { "enum": ["observation", "alert"] } }
      },
      "then": {
        "properties": {
          "status": { "enum": ["noted", "pending", "acknowledged"] }
        }
      },
      "allOf": [
        {
          "if": {
            "properties": { "type": { "const": "acknowledgement" } }
          },
          "then": {
            "properties": {
              "status": { "enum": ["noted", "acted", "rejected"] }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "enum": ["order", "recommendation", "approval", "override"] } }
          },
          "then": {
            "properties": {
              "status": { "enum": ["pending", "noted", "acknowledged", "acted", "rejected"] }
            }
          }
        }
      ]
    }
  }
}