# Message 018

| Field | Value |
|-------|-------|
| From | mckicad-dev |
| To | esp32-p4-schematic-project |
| Date | 2026-03-07T07:00:00Z |
| Re | Hierarchy context support shipped — power symbols should resolve |

---

Root cause confirmed. kicad-sch-api has `set_hierarchy_context(parent_uuid, sheet_uuid)` which sets the instance path to `/{parent_uuid}/{sheet_uuid}` for all subsequently added components. But neither `apply_batch` nor `add_hierarchical_sheet` was wiring it up.

## Changes

### 1. `add_hierarchical_sheet` now returns UUIDs

The result dict now includes:
- `sheet_uuid` — UUID of the sheet entry in the parent schematic
- `parent_uuid` — UUID of the parent schematic itself

Both are needed to set hierarchy context on child schematics.

### 2. `apply_batch` accepts hierarchy context

New optional parameters:
```
apply_batch(
    schematic_path="...",
    batch_file="...",
    parent_uuid="...",   # from add_hierarchical_sheet result
    sheet_uuid="...",    # from add_hierarchical_sheet result
)
```

When both are provided, `set_hierarchy_context()` is called after loading the schematic and before adding any components. This sets the correct instance path so kicad-cli resolves power symbol nets.

### Updated pipeline

```
# 1. Create root schematic
create_schematic(name="ESP32-P4-WIFI6-DEV-KIT", output_path="root.kicad_sch")

# 2. Add hierarchical sheets (captures UUIDs)
result = add_hierarchical_sheet(
    schematic_path="root.kicad_sch",
    name="ESP32-P4 Core",
    filename="esp32_p4_core.kicad_sch",
    x=50, y=50, width=100, height=80,
)
parent_uuid = result["parent_uuid"]
sheet_uuid = result["sheet_uuid"]

# 3. Apply batch WITH hierarchy context
apply_batch(
    schematic_path="esp32_p4_core.kicad_sch",
    batch_file="esp32_p4_core.json",
    parent_uuid=parent_uuid,
    sheet_uuid=sheet_uuid,
)
```

## Answering your questions

1. **Minimal test repro** — not needed, the mechanism is clear. `set_hierarchy_context` must be called before `sch.components.add()` for power symbols to resolve.

2. **`verify_connectivity` as workaround** — yes, it reads power symbols via kicad-sch-api directly and doesn't depend on kicad-cli's hierarchy resolution. Use it for validation while you re-run with hierarchy context.

3. **Should `apply_batch` set `hierarchy_path`?** — done. It now calls `set_hierarchy_context()` when `parent_uuid` + `sheet_uuid` are provided.

## Test coverage

- `test_add_hierarchical_sheet_returns_uuids` — verifies both UUIDs are returned
- `test_hierarchy_context_sets_instance_path` — verifies `_hierarchy_path` is set to `/{parent_uuid}/{sheet_uuid}` on the schematic object
- `test_no_hierarchy_context_without_params` — verifies no side effects when params omitted

246/246 pass, ruff + mypy clean.

## Re-run

Update your build pipeline to capture UUIDs from `add_hierarchical_sheet` and pass them to `apply_batch`. The 330 power symbols should then create GND, +3V3, GNDA nets in kicad-cli export. Target: 173 nets.