# HideMyName / AmneziaWG provider adapter

## Current legacy state

The old HMN layer on VM101 is a provider-specific discovery and validation layer.
It must not be treated as the final traffic balancer.

Current useful provider outputs are TSV cache files under `/root/hmn/cache`, not
the empty `/root/hmn/configs/awg1/latest` directory.

Observed on VM101 during STEP_030B:

- `/root/hmn/cache/selected-awg1-latest.tsv`
  - current legacy selected slots
- `/root/hmn/cache/ok-awg1-strict-foreign-latest.tsv`
  - preferred candidate pool for new egress slots
  - already filtered to working foreign endpoints
- `/root/hmn/cache/ok-awg1-strict-all-latest.tsv`
  - broader candidate pool
- `/root/hmn/cache/working-awg1-latest.tsv`
  - raw working pool from validation/download
- `/root/hmn/cache/quarantine-awg1-latest.tsv`
  - endpoints/configs to avoid

## Adapter input priority

1. Primary candidate source:
   `/root/hmn/cache/ok-awg1-strict-foreign-latest.tsv`

2. Legacy currently selected source:
   `/root/hmn/cache/selected-awg1-latest.tsv`

3. Fallback candidate source:
   `/root/hmn/cache/ok-awg1-strict-all-latest.tsv`

4. Avoid/quarantine source:
   `/root/hmn/cache/quarantine-awg1-latest.tsv`

## Generic slot model

The upper egress system should see provider-independent slots:

- slot id: `hmn_slot_1` ... `hmn_slot_5`
- interface: `vpn1` ... `vpn5`
- routing table: `201` ... `205`
- fwmark: `0x201` ... `0x205`
- provider: `hidemyname`
- endpoint: from provider adapter
- config path: provider-private detail, never publish raw config

## Safety rules

- Do not print private keys.
- Do not publish raw configs.
- Do not publish HMN access code.
- Do not mutate VM101 during status/model steps.
- Do not use `/root/hmn/configs/awg1/latest` as the primary source unless it is verified to contain `.conf` files.