{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agentic.advalorem.io/schemas/capabilities.schema.json",
  "title": "AdValorem Capability Registry",
  "description": "Machine-readable catalog of capabilities across the AdValorem three-domain network (agentic / builder / mev). Each capability describes an agent-consumable surface. LIVE status requires evidence.checked_at and evidence.source.",
  "type": "object",
  "required": ["registry_version", "generated_at", "network", "capabilities"],
  "additionalProperties": false,
  "properties": {
    "registry_version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "SemVer of the registry file itself (not of any capability)."
    },
    "generated_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 UTC timestamp when this file was generated or last refreshed."
    },
    "network": {
      "type": "object",
      "additionalProperties": false,
      "required": ["organization", "domains", "operational_status", "operational_status_source"],
      "properties": {
        "organization": {"type": "string", "minLength": 1},
        "domains": {
          "type": "object",
          "additionalProperties": false,
          "required": ["discover", "execute", "intelligence"],
          "properties": {
            "discover":     {"type": "string", "format": "uri"},
            "execute":      {"type": "string", "format": "uri"},
            "intelligence": {"type": "string", "format": "uri"}
          }
        },
        "operational_status": {
          "type": "string",
          "enum": ["ok", "degraded", "outage"],
          "description": "Rollup status derived from capability statuses. See linter."
        },
        "operational_status_source": {
          "type": "string",
          "minLength": 1,
          "description": "How this rollup was decided (e.g. path to inventory or linter run)."
        }
      }
    },
    "capabilities": {
      "type": "array",
      "minItems": 1,
      "items": {"$ref": "#/$defs/capability"},
      "description": "Ordered list of capabilities. Ordering is by product then by id."
    },
    "metric_definitions": {
      "type": "object",
      "description": "Optional. Names for metrics referenced by capabilities, so agent-side dashboards can render them consistently.",
      "additionalProperties": {
        "type": "object",
        "required": ["description"],
        "properties": {
          "description": {"type": "string", "minLength": 1},
          "unit":        {"type": "string"}
        }
      }
    }
  },
  "$defs": {
    "capability": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "product", "name", "status", "surface", "endpoint", "auth", "provider", "evidence"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$",
          "description": "Stable identifier product.name (e.g. agentnet.echo, mev.liquidations)."
        },
        "product": {
          "type": "string",
          "enum": ["agentnet", "builder", "mev", "phoenix"],
          "description": "Which AdValorem product this capability belongs to."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable label."
        },
        "description": {
          "type": "string",
          "description": "One or two sentences an agent LLM can quote."
        },
        "status": {
          "type": "string",
          "enum": ["LIVE", "PARTIAL", "STALE", "PLANNED", "PILOT"],
          "description": "Evidence-backed status. LIVE requires a successful probe (see linter)."
        },
        "surface": {
          "type": "string",
          "enum": ["MCP", "JSON-RPC", "REST", "SSE", "WEBHOOK", "WEB"],
          "description": "How the capability is consumed."
        },
        "endpoint": {
          "type": "string",
          "format": "uri",
          "description": "Canonical URL. For MCP surfaces this is the RPC URL; for WEB it is a discoverable landing/doc URL."
        },
        "auth": {
          "type": "string",
          "enum": ["none", "bearer", "flashbots_signature", "x402", "custom"],
          "description": "Primary auth expected by an agent client."
        },
        "provider": {
          "type": "string",
          "minLength": 1,
          "description": "Party responsible for the capability (usually 'AdValorem'; may be 'partner' or a partner name for pilots)."
        },
        "proof": {
          "type": ["string", "null"],
          "description": "How execution is proven back to the caller (e.g. agentnet-receipt-v1). Null means no cryptographic proof channel yet."
        },
        "jwks_url": {
          "type": ["string", "null"],
          "format": "uri",
          "description": "JWKS URL for verifying proofs from this capability, if any."
        },
        "x402": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "advertised":   {"type": "boolean"},
            "descriptor":   {"type": "string", "format": "uri"},
            "resource":     {"type": "string", "format": "uri"},
            "pay_to":       {"type": "string"},
            "asset":        {"type": "string"},
            "network":      {"type": "string"}
          }
        },
        "docs_url": {
          "type": ["string", "null"],
          "format": "uri"
        },
        "related_capabilities": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$"
          },
          "description": "Other capabilities in this registry this one depends on or coexists with."
        },
        "evidence": {"$ref": "#/$defs/evidence"},
        "notes": {"type": "string"}
      },
      "allOf": [
        {
          "description": "LIVE requires a probe timestamp.",
          "if": {"properties": {"status": {"const": "LIVE"}}, "required": ["status"]},
          "then": {"required": ["evidence"], "properties": {"evidence": {"required": ["checked_at", "source", "probe"]}}}
        },
        {
          "description": "STALE requires an advertised_by field so we know which surface is lying.",
          "if": {"properties": {"status": {"const": "STALE"}}, "required": ["status"]},
          "then": {"required": ["evidence"], "properties": {"evidence": {"required": ["source", "advertised_by"]}}}
        }
      ]
    },
    "evidence": {
      "type": "object",
      "additionalProperties": false,
      "required": ["source"],
      "properties": {
        "source": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable pointer to how we know (e.g. 'A5.2 ratification packet' or 'a5.3-inventory/evidence/builder_mcp_initialize.body')."
        },
        "checked_at": {
          "type": "string",
          "format": "date-time",
          "description": "RFC3339 UTC timestamp of the last successful probe. Required for LIVE."
        },
        "probe": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "url":         {"type": "string", "format": "uri"},
            "method":      {"type": "string", "enum": ["GET", "POST", "OPTIONS"]},
            "status":      {"type": "integer"},
            "body_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
            "artifact":    {"type": "string", "description": "Relative path (from this file) to the raw evidence file."}
          },
          "description": "Structured probe metadata. Required for LIVE capabilities."
        },
        "advertised_by": {
          "type": "string",
          "description": "For STALE only: where the broken claim is published (e.g. https://mev.advalorem.io/sitemap.xml)."
        },
        "next_action": {
          "type": "string",
          "description": "Optional short note on what unblocks a status upgrade."
        }
      }
    }
  }
}