# AIM inventory hierarchy discovery

**AIM 3.3.0rc8 / service API 1.0.** `inventory_hierarchy_v1` is a read-only,
additive discovery capability. It exists so interfaces can present AIM's actual
inventory group/subgroup structure without duplicating Ansible-inventory parsing.

## Public operation

Python:

```python
result = AimService().inventory_hierarchy('CUSTOMER')
```

Machine interface:

```bash
printf '%s\n' '{"api_version":"1.0","operation":"inventory_hierarchy","customer":"CUSTOMER"}' | aimctl request
```

Query `capabilities.inventory_hierarchy` before relying on this operation.

The result has this shape:

```json
{
  "api_version": "1.0",
  "schema": "inventory_hierarchy_v1",
  "customer": "CUSTOMER",
  "hosts": ["direct-customer-host.example"],
  "groups": [
    {
      "name": "windows",
      "path": ["windows"],
      "hosts": ["win01.example"],
      "children": [
        {
          "name": "servers",
          "path": ["windows", "servers"],
          "hosts": ["win02.example"],
          "children": []
        }
      ]
    }
  ]
}
```

`hosts` on each node means **direct membership in that node**, not recursively
expanded membership. A client can render descendants without guessing whether a
host came from the parent or a subgroup. Group nesting is preserved to a bounded
64 levels / 10,000 group nodes; malformed mappings, aliases/cycles or larger
structures fail as invalid source rather than being silently flattened.

## Safety and execution boundary

Only customer/group names, group paths and inventory host names are returned.
Variables, addresses, credentials, Vault values, connection settings and group
vars are not part of this tree. `list_hosts` remains the flat host/address/platform
metadata operation.

The hierarchy is presentation/discovery metadata only. It does **not** add group
patterns to `RunRequest`, change `--limit`, authorize targets, or skip preparation
and review. Execution still accepts explicit host names and Core revalidates them
against current inventory/catalog compatibility.

Interfaces should not persist a competing hierarchy or derive execution authority
from a previously fetched tree. Fetch current hierarchy when presenting inventory,
then prepare the final explicit host request through Core.