# Swarm test inventory extension

`extend_inventory.py` expands a provisioned swarm-test inventory so the static
validator and the deploy see every group the run will use. It reads `APP_ID`,
`INV_PATH` and `SWARM_NAME` from the environment, merges the computed groups
into `INV_PATH`, and writes a sibling `backup.yml` for the second (backup-host)
play.

## Flow

```mermaid
flowchart TD
    ENV["env: SWARM_NAME, APP_ID, INV_PATH"] --> MAIN["main()"]

    MAIN --> TOPO["_host_topology(app_id)"]
    MAIN --> DEP["_placement_dep_groups(app_id)"]
    MAIN --> BKP{"backup_repos.repo_placements:\nvolume / secrets role in derive_includes(app_id)?"}
    MAIN --> NBKP{"backup_repos.repo_placements:\nsvc-bkp-nfs-2-local in derive_includes(svc-storage-nfs-server)?"}

    TOPO --> T1["app_id → manager (+ workers unless manager-placed)"]
    TOPO --> T2["svc-swarm-node → manager + workers"]
    TOPO --> T3["svc-swarm-manager → manager"]
    TOPO --> T4["svc-storage-nfs-client → manager + workers"]
    TOPO --> T5["svc-storage-nfs-server → nfs-server"]

    DEP --> D1["derive_includes(app_id)\nrole with placement=manager → manager"]

    BKP -- yes --> B1["svc-bkp-volume-2-local,\nsvc-bkp-secrets-2-local → manager"]
    BKP -- no --> SKIP["skip app-induced backup legs"]
    NBKP -- yes --> NFS["svc-bkp-nfs-2-local → nfs-server"]
    NBKP -- no --> NSKIP["skip nfs-backup leg"]

    T1 & T2 & T3 & T4 & T5 & D1 & B1 & NFS --> MERGE["merge groups into all.children"]

    MERGE --> OUT1["write INV_PATH (devices.yml)"]
    MAIN --> OUT2["write backup.yml:\nsvc-bkp-remote-2-local,\nsvc-bkp-local-2-device → backup host"]
```

## Groups

| Group | Host | Condition |
| --- | --- | --- |
| `APP_ID` | manager, workers | workers dropped when the role is `placement: manager` |
| `svc-swarm-node` | manager, workers | always |
| `svc-swarm-manager` | manager | always |
| `svc-storage-nfs-client` | manager, workers | always |
| `svc-storage-nfs-server` | nfs-server | always |
| dep roles from `derive_includes` | manager | role declares `placement: manager` |
| `svc-bkp-volume-2-local` | manager | `derive_includes(APP_ID)` pulls it in via the `container_backup` consumer |
| `svc-bkp-secrets-2-local` | manager | `derive_includes(APP_ID)` pulls it in |
| `svc-bkp-nfs-2-local` | nfs-server | `derive_includes(svc-storage-nfs-server)` pulls it in via the `nfs_backup` consumer |
| `svc-bkp-remote-2-local`, `svc-bkp-local-2-device` | backup host | always, written to `backup.yml` |

Node names come from `default.env` (`INFINITO_SWARM_*_NAME`) with the
`SWARM_NAME` prefix. `INFINITO_APP_VARIANTS` feeds `derive_includes` to select
the active variant; in-process callers pass the map as
`derive_includes(app_id, variants=...)`.

The three `svc-bkp-*` repository rows come from `backup_repos.repo_placements`.
`utils/tests/swarm/matrix.py` calls `backup_repos.backup_provider_ips`, which
resolves the same two closures and returns the nodes as IPs, to build
`svc-bkp-remote-2-local.services.remote-2-local.backup_providers`.