feat: add FreeSWITCH service (SignalWire packages, not compiled from source)

- infrastructure/freeswitch/Dockerfile: debian:trixie-slim + SignalWire
  packaged freeswitch-meta-vanilla, avoiding a C/C++ build on a 1.9GB RAM VM
- FREESWITCH_PAT used only via Docker BuildKit secret, apt credentials file
  created and deleted within the same RUN — verified absent from the final
  image with docker history
- minimal module set (agente.md secao 15): sofia, event_socket, commands,
  dptools, callcenter, avmd, curl, local_stream, etc. mod_xml_curl installed
  but disabled — it refuses to load without a configured gateway-url, which
  will exist once b2bcall-fs-config is built
- entrypoint.sh rotates the Event Socket password away from the 'ClueCon'
  default at container runtime (never baked into the image); fails loudly if
  ESL_PASSWORD is unset
- port 8021 not published to the host; only reachable from other containers
  on the compose network
- found and fixed: freeswitch-conf-vanilla is a Recommends (not a Depends)
  of freeswitch-meta-vanilla, so --no-install-recommends silently produced
  an empty /etc/freeswitch and a crash loop
- verified end-to-end: fs_cli status via ESL with the custom password,
  default password rejected, expected modules loaded, healthcheck green,
  ~44MB RAM usage
- docs/FREESWITCH.md, docs/NETWORK_ARCHITECTURE.md (network_mode decision
  deferred until a real SIP trunk exists)

docs/FREESWITCH.md

@@ -0,0 +1,95 @@
+# FreeSWITCH
+
+Imagem própria em `infrastructure/freeswitch/` (agente.md secao 19), rodando como
+serviço Docker `freeswitch` (container `b2bcall-freeswitch`).
+
+## Por que pacotes prontos, e não compilar da fonte
+
+O servidor de desenvolvimento tem só ~1.9GB de RAM. Compilar FreeSWITCH (C/C++,
+dezenas de módulos) arriscaria OOM e levaria muito tempo. Em vez disso, a imagem
+usa os pacotes `.deb` pré-compilados do repositório oficial do SignalWire
+(`freeswitch.signalwire.com`), autenticado com `FREESWITCH_PAT` — exatamente o
+uso previsto para essa credencial (agente.md secao 11). O repositório do
+SignalWire tem pacotes para o codename `trixie`, então a imagem usa
+`debian:trixie-slim` como base (mesma versão do host, mas isso é coincidência —
+o container é isolado e poderia usar qualquer Debian suportado pelo repo).
+
+## Manuseio do PAT (agente.md secao 11)
+
+`FREESWITCH_PAT` entra no build via **Docker BuildKit secret**
+(`--mount=type=secret,id=freeswitch_pat`), nunca como `ARG`/`ENV`. O arquivo de
+credenciais do apt (`/etc/apt/auth.conf.d/freeswitch.conf`, que contém o PAT em
+texto puro) é criado e apagado dentro do **mesmo** `RUN`, então nunca aparece em
+nenhuma camada da imagem final — verificado com `docker history --no-trunc`.
+
+`docker-compose.yml` declara o secret assim:
+
+```yaml
+secrets:
+  freeswitch_pat:
+    environment: FREESWITCH_PAT
+```
+
+e o serviço `freeswitch` referencia `secrets: [freeswitch_pat]` em `build:`.
+
+## Pacotes instalados
+
+```
+freeswitch-meta-vanilla       # core + config de referência (a mesma usada em
+                               # praticamente todo tutorial/livro de FreeSWITCH)
+freeswitch-conf-vanilla       # ⚠ Recommends de meta-vanilla, não Depends —
+                               # precisa ser listado explicitamente com
+                               # --no-install-recommends (foi um bug real
+                               # durante o setup: sem isso /etc/freeswitch
+                               # fica vazio e o container entra em crash loop)
+freeswitch-mod-callcenter     # ACD (agente.md secao 37)
+freeswitch-mod-avmd           # detecção de caixa postal/beep (secao 87)
+freeswitch-mod-curl           # chamadas HTTP a partir do dialplan
+```
+
+`mod_xml_curl` está **instalado mas desativado** em
+`overrides/autoload_configs/modules.conf.xml` — o módulo se recusa a carregar
+sem pelo menos um binding com `gateway-url` configurada ("Binding has no
+url!"), e essa URL só existirá quando o `b2bcall-fs-config` for criado (fase
+"XML Curl", logo em seguida). Reativar lá.
+
+`mod_signalwire` foi removido da lista de módulos: é específico da nuvem do
+SignalWire, que não usamos (só o repositório de pacotes).
+
+## Event Socket (agente.md secao 22)
+
+Senha alterada da padrão (`ClueCon`) para `${ESL_PASSWORD}` (gerado com
+`openssl rand`, vive só em `.env`) via `entrypoint.sh`, que faz um `sed` no
+`event_socket.conf.xml` **em runtime** — a senha real nunca é copiada para a
+imagem, só injetada via variável de ambiente do container. O entrypoint falha
+alto (`set -eu` + `${ESL_PASSWORD:?...}`) se a variável não estiver definida —
+nunca sobe com a senha padrão por engano.
+
+Porta 8021 **não é publicada no host** (`ports:` ausente no compose) — só
+alcançável por outros containers na rede interna do Docker Compose
+(`b2bcall_default`), pelo nome de serviço `freeswitch`. Isso satisfaz
+"NÃO pública... acesso somente pela aplicação autorizada" sem precisar de ACL
+adicional por enquanto (ACL fica como hardening futuro, ver TODO).
+
+## O que NÃO foi feito nesta fase (fica para as próximas, por design)
+
+Seguindo a ordem do próprio `agente.md` (secao 232): esta fase só cobre "ter o
+FreeSWITCH rodando e alcançável". As próximas fases constroem em cima:
+
+- **Event Socket**: `b2bcall-fs-events`, conexão ESL permanente (secao 21).
+- **XML Curl**: `b2bcall-fs-config`, reativa `mod_xml_curl` apontando pra esse
+  serviço (secao 26).
+- **Extensions/Trunks/Dialplan**: hoje o directory/dialplan estático da config
+  vanilla continua com os 20 ramais de teste (1000-1019, senhas fracas — README
+  do próprio pacote avisa isso). Como as portas SIP não estão publicadas no
+  host, isso fica contido, mas precisa ser substituído por `mod_xml_curl`
+  dinâmico antes de qualquer tronco/ramal real existir.
+- **mod_odbc_cdr**: não instalado ainda — só faz sentido junto da fase de CDR.
+
+## Verificação manual
+
+```bash
+source <(grep '^ESL_PASSWORD=' .env)
+docker exec b2bcall-freeswitch fs_cli -p "$ESL_PASSWORD" -x "status"
+docker exec b2bcall-freeswitch fs_cli -p "$ESL_PASSWORD" -x "module_exists mod_sofia"
+```

docs/NETWORK_ARCHITECTURE.md

@@ -0,0 +1,36 @@
+# Arquitetura de Rede
+
+## Estado atual (fase FreeSWITCH inicial)
+
+`freeswitch` roda na rede padrão do Docker Compose (bridge, `b2bcall_default`),
+igual a `postgres` e `redis`. Nenhuma porta é publicada no host — nem 8021
+(ESL), nem SIP (5060/5080), nem RTP. Isso é intencional: ainda não existe
+nenhum tronco SIP real nem ramal externo, então não há motivo pra expor nada.
+
+`apps/api` roda hoje **direto no host** (fora do Docker), então usa
+`APP_DATABASE_URL`/`REDIS_URL` apontando pra `localhost` nas portas publicadas
+pelo Postgres/Redis. Ela não consegue (nem precisa, ainda) alcançar o
+FreeSWITCH.
+
+## Decisão pendente: `network_mode` do FreeSWITCH (agente.md secao 19)
+
+Quando existir um tronco SIP real (fase Trunks), será preciso decidir entre:
+
+- **`network_mode: host`**: mais simples pra SIP/RTP (sem NAT entre o
+  container e a rede), mas perde isolamento de rede do Docker.
+- **macvlan/ipvlan**: dá ao FreeSWITCH um IP próprio na rede física, sem expor
+  outros serviços do host: mais trabalho de configurar, melhor isolamento.
+
+Não decidido ainda — só vira relevante quando houver um carrier/SBC real pra
+conectar (secao 17: "FreeSWITCH não deverá depender de IP SIP público" — a
+topologia esperada é `Internet → OpenSIPS → rede SIP privada → FreeSWITCH`,
+então o FreeSWITCH em si tende a ficar em rede privada mesmo, o que favorece
+manter bridge/macvlan em vez de host).
+
+## Quando `apps/api` virar container
+
+Hoje ela roda no host por conveniência de desenvolvimento. Quando virar o
+serviço Docker `b2bcall-api` (agente.md secao 14), as connection strings
+precisam trocar de `localhost` pros hostnames internos do compose
+(`postgres`, `redis`, `freeswitch`) — ver nota em docs/AUTHENTICATION.md sobre
+essa pegadinha.