{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://aiwg.io/schemas/flow/graph/v1alpha1/flow-graph.schema.json",
  "title": "FlowGraph",
  "description": "Provider-neutral graph profile for the AIWG Flow metalanguage.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata", "spec"],
  "additionalProperties": false,
  "properties": {
    "apiVersion": { "const": "flow.aiwg.io/v1alpha1" },
    "kind": { "const": "FlowGraph" },
    "metadata": { "$ref": "#/definitions/metadata" },
    "spec": { "$ref": "#/definitions/spec" }
  },
  "definitions": {
    "metadata": {
      "type": "object",
      "required": ["name"],
      "additionalProperties": false,
      "properties": {
        "name": { "$ref": "#/definitions/dnsLabel" },
        "namespace": { "$ref": "#/definitions/dnsLabel" },
        "labels": { "$ref": "#/definitions/stringMap" },
        "annotations": { "$ref": "#/definitions/stringMap" }
      }
    },
    "spec": {
      "type": "object",
      "required": ["entry", "candidates", "state", "permissions", "capabilities", "ceilings", "nodes", "routes", "joins", "failure", "output", "trace"],
      "additionalProperties": false,
      "properties": {
        "description": { "type": "string", "minLength": 1 },
        "entry": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": { "$ref": "#/definitions/id" }
        },
        "candidates": {
          "type": "array",
          "items": { "$ref": "#/definitions/candidate" }
        },
        "state": { "$ref": "#/definitions/state" },
        "permissions": {
          "type": "array",
          "uniqueItems": true,
          "items": { "$ref": "#/definitions/permission" }
        },
        "capabilities": {
          "type": "array",
          "items": { "$ref": "#/definitions/capability" }
        },
        "ceilings": { "$ref": "#/definitions/ceilings" },
        "nodes": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/definitions/node" }
        },
        "routes": {
          "type": "array",
          "items": { "$ref": "#/definitions/route" }
        },
        "joins": {
          "type": "array",
          "items": { "$ref": "#/definitions/join" }
        },
        "failure": { "$ref": "#/definitions/failurePolicy" },
        "output": { "$ref": "#/definitions/outputPolicy" },
        "trace": { "$ref": "#/definitions/tracePolicy" }
      }
    },
    "candidate": {
      "type": "object",
      "required": ["id", "kind"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/definitions/indexRef" },
        "kind": { "$ref": "#/definitions/artifactKind" },
        "schema": { "$ref": "#/definitions/jsonSchema" }
      }
    },
    "state": {
      "type": "object",
      "required": ["fields"],
      "additionalProperties": false,
      "properties": {
        "fields": {
          "type": "array",
          "items": { "$ref": "#/definitions/stateField" }
        }
      }
    },
    "stateField": {
      "type": "object",
      "required": ["name", "schema", "reducer"],
      "additionalProperties": false,
      "properties": {
        "name": { "$ref": "#/definitions/id" },
        "schema": { "$ref": "#/definitions/jsonSchema" },
        "reducer": { "enum": ["replace", "append", "merge", "sum", "min", "max", "set-union"] },
        "initial": {}
      }
    },
    "capability": {
      "type": "object",
      "required": ["id", "permissions", "sideEffectMode"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/definitions/id" },
        "permissions": {
          "type": "array",
          "uniqueItems": true,
          "items": { "$ref": "#/definitions/permission" }
        },
        "sideEffectMode": { "$ref": "#/definitions/sideEffectMode" },
        "idempotencyKey": { "type": "string", "minLength": 1 },
        "approvalGate": { "$ref": "#/definitions/id" }
      }
    },
    "ceilings": {
      "type": "object",
      "required": ["activations", "tokens", "costUsd", "timeMs", "concurrency"],
      "additionalProperties": false,
      "properties": {
        "activations": { "type": "integer", "minimum": 1 },
        "tokens": { "type": "integer", "minimum": 1 },
        "costUsd": { "type": "number", "exclusiveMinimum": 0 },
        "timeMs": { "type": "integer", "minimum": 1 },
        "concurrency": { "type": "integer", "minimum": 1 }
      }
    },
    "node": {
      "type": "object",
      "required": ["id", "kind", "inputs", "outputs", "capabilities", "permissions", "sideEffectMode"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/definitions/id" },
        "kind": { "$ref": "#/definitions/nodeKind" },
        "ref": { "$ref": "#/definitions/indexRef" },
        "deterministic": { "const": true },
        "description": { "type": "string", "minLength": 1 },
        "optional": { "type": "boolean" },
        "phase": { "type": "string", "minLength": 1 },
        "track": { "type": "string", "minLength": 1 },
        "dependsOn": {
          "type": "array",
          "uniqueItems": true,
          "items": { "$ref": "#/definitions/id" }
        },
        "activation": { "$ref": "#/definitions/predicate" },
        "inputs": {
          "type": "array",
          "items": { "$ref": "#/definitions/inputBinding" }
        },
        "outputs": {
          "type": "array",
          "items": { "$ref": "#/definitions/outputBinding" }
        },
        "capabilities": {
          "type": "array",
          "uniqueItems": true,
          "items": { "$ref": "#/definitions/id" }
        },
        "permissions": {
          "type": "array",
          "uniqueItems": true,
          "items": { "$ref": "#/definitions/permission" }
        },
        "sideEffectMode": { "$ref": "#/definitions/sideEffectMode" },
        "idempotencyKey": { "type": "string", "minLength": 1 },
        "approvalGate": { "$ref": "#/definitions/id" },
        "scope": { "$ref": "#/definitions/observationScope" },
        "hitlAction": { "$ref": "#/definitions/hitlAction" },
        "retry": { "$ref": "#/definitions/retryPolicy" },
        "fallback": { "$ref": "#/definitions/fallbackPolicy" },
        "ceilings": { "$ref": "#/definitions/ceilings" }
      },
      "allOf": [
        { "if": { "required": ["hitlAction"] }, "then": { "properties": { "kind": { "const": "gate" } } } }
      ]
    },
    "hitlAction": {
      "description": "Host-authored classification of the exact pending execution plan. Never populate from node inputs, worker output or model text; unknown effects retain human review.",
      "type": "object",
      "required": ["category", "repo", "environment", "resources", "reversible", "impact"],
      "additionalProperties": false,
      "properties": {
        "category": { "type": "string", "minLength": 1 },
        "repo": { "type": "string", "minLength": 1 },
        "target": { "type": "string", "minLength": 1 },
        "environment": { "type": "string", "minLength": 1 },
        "resources": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
        "verb": { "type": "string", "minLength": 1 },
        "reversible": { "type": "boolean" },
        "impact": { "enum": ["low", "medium", "high"] },
        "actor": { "type": "string", "minLength": 1 },
        "inputDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
      }
    },
    "inputBinding": {
      "type": "object",
      "required": ["name", "schema"],
      "additionalProperties": false,
      "properties": {
        "name": { "$ref": "#/definitions/id" },
        "schema": { "$ref": "#/definitions/jsonSchema" },
        "from": { "type": "string", "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9-]*$" },
        "state": { "$ref": "#/definitions/id" },
        "value": {}
      },
      "oneOf": [
        { "required": ["from"] },
        { "required": ["state"] },
        { "required": ["value"] }
      ]
    },
    "outputBinding": {
      "type": "object",
      "required": ["name", "schema"],
      "additionalProperties": false,
      "properties": {
        "name": { "$ref": "#/definitions/id" },
        "schema": { "$ref": "#/definitions/jsonSchema" },
        "state": { "$ref": "#/definitions/id" }
      }
    },
    "route": {
      "type": "object",
      "required": ["from", "to"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/definitions/id" },
        "from": { "$ref": "#/definitions/id" },
        "to": { "$ref": "#/definitions/id" },
        "when": { "$ref": "#/definitions/predicate" },
        "guard": { "$ref": "#/definitions/predicate" },
        "progress": { "$ref": "#/definitions/progressMeasure" },
        "maxIterations": { "type": "integer", "minimum": 1 }
      }
    },
    "progressMeasure": {
      "type": "object",
      "required": ["state", "direction"],
      "additionalProperties": false,
      "properties": {
        "state": { "$ref": "#/definitions/id" },
        "direction": { "const": "decrease" }
      }
    },
    "observationScope": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "files": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
        "resources": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
      }
    },
    "join": {
      "type": "object",
      "required": ["id", "sources", "target", "policy"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/definitions/id" },
        "sources": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": { "$ref": "#/definitions/id" }
        },
        "target": { "$ref": "#/definitions/id" },
        "policy": {
          "type": "object",
          "required": ["mode"],
          "additionalProperties": false,
          "properties": {
            "mode": { "enum": ["all", "quorum", "fixed", "lcm", "converged", "budget"] },
            "quorum": { "type": "integer", "minimum": 1 },
            "count": { "type": "integer", "minimum": 1 },
            "periods": {
              "type": "array",
              "minItems": 2,
              "items": { "type": "integer", "minimum": 1 }
            },
            "predicate": { "$ref": "#/definitions/predicate" },
            "maxIterations": { "type": "integer", "minimum": 1 },
            "maxCostUsd": { "type": "number", "exclusiveMinimum": 0 }
          }
        }
      }
    },
    "failurePolicy": {
      "type": "object",
      "required": ["onNodeFailure", "maxFailures"],
      "additionalProperties": false,
      "properties": {
        "onNodeFailure": { "enum": ["fail", "continue", "skip-optional", "fallback", "partial-synthesis"] },
        "maxFailures": { "type": "integer", "minimum": 0 },
        "terminalSchema": { "$ref": "#/definitions/jsonSchema" }
      }
    },
    "outputPolicy": {
      "type": "object",
      "required": ["mode", "from", "schema"],
      "additionalProperties": false,
      "properties": {
        "mode": { "enum": ["final-only", "progressive", "typed-terminal-failure"] },
        "from": { "type": "string", "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9-]*$" },
        "schema": { "$ref": "#/definitions/jsonSchema" },
        "failureSchema": { "$ref": "#/definitions/jsonSchema" }
      }
    },
    "tracePolicy": {
      "type": "object",
      "required": ["level", "redact"],
      "additionalProperties": false,
      "properties": {
        "level": { "enum": ["metadata", "bindings", "full-io"] },
        "redact": {
          "type": "array",
          "uniqueItems": true,
          "items": { "type": "string", "pattern": "^/" }
        }
      }
    },
    "retryPolicy": {
      "type": "object",
      "required": ["limit", "backoff", "on"],
      "additionalProperties": false,
      "properties": {
        "limit": { "type": "integer", "minimum": 0 },
        "backoff": { "enum": ["none", "linear", "exponential"] },
        "on": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": { "enum": ["failure", "timeout", "rate-limit"] }
        }
      }
    },
    "fallbackPolicy": {
      "type": "object",
      "required": ["node"],
      "additionalProperties": false,
      "properties": {
        "node": { "$ref": "#/definitions/id" },
        "allowPartial": { "type": "boolean" }
      }
    },
    "predicate": {
      "type": "object",
      "required": ["expression"],
      "additionalProperties": false,
      "properties": {
        "language": { "const": "cel" },
        "expression": { "type": "string", "minLength": 1 }
      }
    },
    "jsonSchema": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": true
    },
    "nodeKind": {
      "enum": ["agent", "skill", "prompt", "evaluator", "tool", "function", "gate"]
    },
    "artifactKind": {
      "enum": ["agent", "skill", "prompt", "evaluator", "tool", "function"]
    },
    "sideEffectMode": {
      "enum": ["none", "idempotent", "exactly-once", "approval-required"]
    },
    "permission": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$"
    },
    "indexRef": {
      "type": "string",
      "pattern": "^aiwg:(agent|skill|prompt|evaluator|tool|function):[a-f0-9]{16}$"
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "dnsLabel": {
      "type": "string",
      "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$",
      "maxLength": 63
    },
    "stringMap": {
      "type": "object",
      "additionalProperties": { "type": "string" }
    }
  }
}
