# IT live collectors — contract

**Canonical machine-readable contract:** [`config/it-operations/live-collectors-contract.json`](../../config/it-operations/live-collectors-contract.json)  
**Spec:** [SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md](./SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md) (section 5.1)

## Per-collector rules

| Collector | Refresh target | On failure |
|-----------|----------------|------------|
| Proxmox guest IPAM | Hourly on LAN (timer or CI dispatch) | `drift.json` notes + `seed_unreachable`; UI stale banner |
| Optional `ip neigh` | 15 min when `IT_COLLECT_IP_NEIGH=1` | Omitted from JSON; no fail |
| Hardware poll | Weekly | Keep last `reports/status/hardware_and_connected_inventory_*.md`; banner if older than policy |
| NPM / UniFi | Phase 2 | Stub endpoint returns `stale: true` until wired |

## Live-only vs declared-only

- **Live-only:** guest `status`, observed `ip`, `mac` (from `net0` / `hwaddr=` when present), `node`, `collected_at` from `pvesh` + guest config.
- **Declared-only:** `ip-addresses.conf` keys not present on any guest (reported in drift as `ip_addresses_conf_ips_not_on_guests` where applicable).
- **Merged:** `drift.json` compares live guests to declared literals and ALL_VMIDS markdown table.

## API exposure

- **GET** `/v1/collector-contract` on the read API serves the JSON above (no auth beyond existing `/v1` API key rule).

## Change process

1. Edit `live-collectors-contract.json` and this doc together.  
2. Run `bash scripts/validation/validate-config-files.sh` (py_compile includes IT scripts).  
3. If portal or BFF caches intervals, bump `version` in JSON.