# Actor Hierarchy and Advanced YAML Extensions

This document covers the advanced actor YAML schema extensions introduced
in **M2.1.actor-yaml**: per-node LSP bindings, tool-source references,
subgraph actor references, and actor-level skill/LSP fields.

## Overview

Actor YAML configurations can define multi-node graph workflows. The
M2.1 extensions add fine-grained control over:

| Feature | Scope | Purpose |
|---------|-------|---------|
| `lsp_binding` | Per-node | Bind specific LSP servers to individual graph nodes |
| `tool_sources` | Per-node | Declare where a node's tools come from (skills, MCP, builtins) |
| `actor_ref` | Per-node (subgraph) | Reference another actor by namespaced name |
| `skills` | Actor-level | List of skill references available to the actor |
| `lsp` | Actor-level | Default LSP server bindings for the actor |
| `lsp_capabilities` | Actor-level | Filter which LSP capabilities are exposed |
| `lsp_context_enrichment` | Actor-level | Control automatic context injection |

## Per-Node LSP Binding

Different nodes in a graph can have different LSP configurations:

```yaml
nodes:
  - id: strategist
    type: agent
    name: Strategy Planner
    description: Plans with read-only LSP
    lsp_binding:
      server: local/pyright
      languages:
        - python
      capabilities:
        - diagnostics
        - hover

  - id: implementer
    type: agent
    name: Implementer
    description: Full LSP auto-binding
    lsp_binding:
      auto: true
```

### `NodeLspBinding` Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `server` | `string` | `null` | Namespaced LSP server name (e.g. `local/pyright`) |
| `languages` | `list[string]` | `[]` | Languages for language-based resolution |
| `auto` | `bool` | `false` | Auto-resolve from project resources |
| `capabilities` | `list[string]` | `null` | Capability filter for this node |

## Tool-Source References

Nodes can declare their tool sources explicitly:

```yaml
nodes:
  - id: executor
    type: agent
    name: Executor
    description: Has multiple tool sources
    tool_sources:
      - type: skill
        name: local/file-ops
      - type: mcp
        name: local/filesystem
      - type: builtin
        group: git_operations
```

### `ToolSourceRef` Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | `string` | Yes | `skill`, `mcp`, `builtin`, or `custom` |
| `name` | `string` | No | Namespaced name (for `skill` and `mcp`) |
| `group` | `string` | No | Group identifier (for `builtin`) |

## Subgraph Actor References

Subgraph nodes can reference other actors by namespaced name:

```yaml
nodes:
  - id: review
    type: subgraph
    name: Code Review
    description: Delegates to code-reviewer
    actor_ref: local/code-reviewer
```

The `actor_ref` field must be in `namespace/name` format.

## Actor-Level Fields

### `skills`

```yaml
skills:
  - local/file-ops
  - local/git-ops
```

### `lsp`

Explicit binding (list of server names):

```yaml
lsp:
  - local/pyright
  - local/clangd
```

Auto binding:

```yaml
lsp:
  auto: true
```

### `lsp_capabilities`

```yaml
lsp_capabilities:
  - diagnostics
  - hover
  - definitions
```

Or expose all:

```yaml
lsp_capabilities: all
```

### `lsp_context_enrichment`

```yaml
lsp_context_enrichment:
  diagnostics: true
  type_annotations: false
  max_diagnostics_per_file: 50
```

## Validation Error Messages

Validation errors now include field-path context:

| Error | Example Message |
|-------|-----------------|
| Bad entry node | `Entry node 'missing' not found in route.entry_node. Valid node IDs: [a, b]` |
| Bad exit node | `Exit node 'missing' not found in route.exit_nodes. Valid node IDs: [a, b]` |
| Bad edge ref | `Edge from_node 'ghost' not found at route.edges[0]. Valid node IDs: [a, b]` |
| Duplicate IDs | `route.nodes: Duplicate node IDs found: ['dup']. Each node ID must be unique.` |
| Cycle | `route: graph contains a cycle involving nodes: [a → b]. Hint: remove or redirect edges.` |

## Complete Example

See `examples/actors/hierarchical_workflow.yaml` for a full working example
combining all these features.