Feature: Actor compiler translates hierarchical actor configs to LangGraph
  As a CleverAgents developer
  I want to compile GRAPH actor configs into LangGraph node/edge structures
  So that actor YAML definitions can be executed as LangGraph StateGraphs

  # ────────────────────────────────────────────────────────────
  # Successful compilation scenarios
  # ────────────────────────────────────────────────────────────

  Scenario: Compile a simple two-node graph actor
    Given a GRAPH actor config with a linear two-node topology
    When I compile the actor config
    Then the compilation should succeed
    And the compiled actor should have 2 nodes
    And the compiled actor entry point should be "planner"
    And the compilation metadata should list node IDs "executor" and "planner"

  Scenario: Compile a graph with a tool node
    Given a GRAPH actor config with an agent and a tool node
    When I compile the actor config
    Then the compilation should succeed
    And the compilation metadata should have 1 tool node

  Scenario: Compile a graph with LSP bindings on a node
    Given a GRAPH actor config with LSP bindings on the agent node
    When I compile the actor config
    Then the compilation should succeed
    And the compilation metadata should have 1 LSP binding
    And the LSP binding should reference server "local/pyright"

  Scenario: Compile a graph with a conditional node
    Given a GRAPH actor config with a conditional routing node
    When I compile the actor config
    Then the compilation should succeed
    And the compiled actor should have 3 nodes

  Scenario: Compile a graph with a subgraph reference
    Given a GRAPH actor config with a subgraph node referencing "workflows/inner"
    When I compile the actor config with a resolver
    Then the compilation should succeed
    And the compilation metadata subgraph refs should map "sub" to "workflows/inner"

  Scenario: Compile a single-node graph actor
    Given a GRAPH actor config with a single node
    When I compile the actor config
    Then the compilation should succeed
    And the compiled actor should have 1 nodes

  # ────────────────────────────────────────────────────────────
  # Subgraph resolution and cycle detection
  # ────────────────────────────────────────────────────────────

  Scenario: Detect cross-actor subgraph cycle
    Given a GRAPH actor config "workflows/outer" referencing "workflows/inner"
    And a resolver where "workflows/inner" references "workflows/outer"
    When I compile the actor config with a resolver
    Then the compilation should fail with SubgraphCycleError
    And the compiler error message should contain "cycle"

  Scenario: Accept acyclic subgraph chain
    Given a GRAPH actor config "workflows/top" referencing "workflows/mid"
    And a resolver where "workflows/mid" has no subgraph nodes
    When I compile the actor config with a resolver
    Then the compilation should succeed

  # ────────────────────────────────────────────────────────────
  # Missing node and invalid entry/exit errors
  # ────────────────────────────────────────────────────────────

  Scenario: Reject non-GRAPH actor type
    Given an LLM actor config
    When I attempt to compile the non-graph actor
    Then the compilation should fail with ActorCompilationError
    And the compiler error message should contain "GRAPH"

  Scenario: Reject GRAPH actor without route
    Given a GRAPH actor config with route set to None
    When I attempt to compile the routeless actor
    Then the compilation should fail with ActorCompilationError
    And the compiler error message should contain "no route"

  # ────────────────────────────────────────────────────────────
  # Metadata inspection
  # ────────────────────────────────────────────────────────────

  Scenario: Metadata lists all node IDs sorted
    Given a GRAPH actor config with nodes "alpha", "beta", and "gamma"
    When I compile the actor config
    Then the compilation should succeed
    And the metadata node IDs should be sorted alphabetically

  Scenario: Metadata records entry and exit nodes
    Given a GRAPH actor config with entry "start_node" and exit "end_node"
    When I compile the actor config
    Then the compilation should succeed
    And the metadata entry node should be "start_node"
    And the metadata exit nodes should contain "end_node"

  Scenario: Compilation metadata is JSON-serializable
    Given a GRAPH actor config with LSP bindings on the agent node
    When I compile the actor config
    Then the compilation metadata should be JSON-serializable