# Handoff Comprehensivo — STA Paridade EOS 2026-04-27

> **Propósito**: este documento captura o estado integral da cabine STA do monorepo Monetarie após 7 PRs mergeados em 2026-04-26 / 2026-04-27 (Ondas 1 + 2.A + 2.B + 2.C). Pensado para servir como **fonte única de verdade** na próxima sessão e para informar a decisão de deploy. Nada relevante deve estar fora dele.

**Data:** 2026-04-27
**Worktree:** `/Users/luizpenha/monetarie/.worktrees/sta-paridade` (branch local pós-cleanup: detached HEAD em `origin/main` `a55ad325`)
**Origin/main HEAD:** `a55ad325` (Merge PR #66 — Onda 2.C)
**Janela de implementação:** 2026-04-26 09:00 BRT → 2026-04-27 14:00 BRT (~29h compactadas em 12 PRs concorrentes com SPB / PIX / E-Financeira / SISBAJUD)

---

## Índice

1. [Resumo executivo](#resumo-executivo)
2. [Catálogo de PRs mergeados](#catalogo)
3. [Inventário de superfície de código](#superficie)
4. [Matriz de cobertura de testes](#testes)
5. [Configuração — env vars + secrets](#config)
6. [Avaliação de deploy-readiness](#deploy-readiness)
7. [Caminhos recomendados de deploy](#deploy-paths)
8. [Pre-deploy checklist](#pre-deploy)
9. [Smoke tests pós-deploy](#smoke-tests)
10. [Avaliação de risco](#risco)
11. [Plano de rollback](#rollback)
12. [Hard gates pendentes](#gates)
13. [Limitações conhecidas + TODOs](#limitacoes)
14. [Continuidade — próxima sessão](#proxima-sessao)
15. [Referências](#referencias)

---

<a id="resumo-executivo"></a>
## 1. Resumo executivo

### O que foi entregue

A cabine STA passou por uma **paridade comprehensiva com o Manual STA Web Services v1.5 jul/2022**, em 4 ondas sequenciadas e 7 PRs mergeados:

- **Onda 1** (PR #24, `301503ec`): wire-format fixes (B1+B2+B3+B4) + ICP-Brasil chain instalada para mTLS fail-CLOSED.
- **Onda 2.A** (PRs #30 + #34 + #36 + #43 + #46 + #52, 6 PRs): chunked upload (§5.6) + ranged download (§6.4) + If-Match/X-Content-Hash integrity + Operations.resume_upload/3 + streaming download + caller-wiring + retry-cap fix.
- **Onda 2.B** (PR #62, `67924840`): status & queries (§7.1 batched change_status, §8.2 query_protocol, §8.3 advanced_query) + admin endpoints `/api/admin/sta/*` + StateCode (Tabela 3) + worker future-readiness wiring.
- **Onda 2.C** (PR #66, `a55ad325`): 3-bucket RateLimiter façade + HTTP 410 per-operation mapping + HTTP 429 Retry-After + Outbound.Worker auto-renew + delayed retry.

Total: **~3,500 LOC implementação + ~2,100 LOC testes** (262 testes / 6 baseline failures preservadas / 5 baseline warnings preservados).

### O que está deploy-ready (CODE)

✅ **Backend Elixir**: compila limpo (5 warnings baseline pre-existentes, sem novos), 262/256 testes passam deterministicamente, todos os pontos de wire-format BCB validados contra Manual.
✅ **Migrations**: 7 migrations em sequência limpa, sendo a mais recente `20260426150000_add_resilient_transfer_columns.exs` (Onda 2.A — adiciona `posicao_upload`, `bytes_uploaded`, `etag`, `last_modified`, `x_content_hash`, `upload_attempts` à `outbound_files`).
✅ **Dockerfile**: `sta/backend/Dockerfile` multi-stage Elixir + Bandit, ARM64-ready (Graviton Fargate).
✅ **mTLS**: `priv/certs/icp_brasil_ca_chain.pem` 7.7KB committed; `:fail-CLOSED` se chain ausente.
✅ **Config externalizada**: 100% via env vars + `Config.Settings` GenServer hot-reloadable.

### O que NÃO está deploy-ready (PLUMBING) — ⚠️ AÇÃO NECESSÁRIA

❌ **Sem GitHub Actions workflow `deploy-sta-homolog.yml`** — só existe `deploy-core-api-homolog.yml`. Não há CI/CD STA via OIDC → ECR → ECS hoje.
❌ **Sem `fargate-sta.tf`** em `infra/aws/greenfield/` — Aurora `monetarie-sta-homolog` está provisionado, mas **não há ECS task definition / ECS service / ALB target group para STA**.
❌ **Sem secrets BCB STA em `infra/aws/greenfield/secrets.tf`** — não existe `monetarie/homolog/sta/bcb_username` / `monetarie/homolog/sta/bcb_password` / `monetarie/homolog/admin/sta/initial_password` provisionados.
❌ **Aurora `monetarie-sta-homolog` ainda não rodou as 7 migrations** — gate G2 (drop+recreate ainda não autorizado).

### Veredito sobre "deploy ainda hoje"

**Honestamente: o código está pronto, mas a infra não.** Para "deploy hoje" uma das três rotas é necessária (detalhadas em §7):
1. **Manual one-shot** via `aws ecs run-task` + ECS task def temporária. Fastest path; ~2-4h de plumbing.
2. **Build & push direto pra ECR + criar Fargate service via Terraform "express"**. ~4-6h.
3. **Adiar deploy 1-2 dias e fazer plumbing direito** (workflow + Terraform + secrets). Recomendado se há banda.

A rota (1) ou (2) requer que o usuário responda 4 perguntas operacionais em §7 antes de qualquer push pra produção/homologação BCB.

---

<a id="catalogo"></a>
## 2. Catálogo completo de PRs mergeados

| PR | Merge SHA | Data | Branch | Onda | Subject |
|---|---|---|---|---|---|
| #24 | `301503ec` | 2026-04-26 | `sta/onda1-wire-fixes-and-icp-chain` | 1 | Onda 1 — wire-format B1+B2+B3+B4 + ICP-Brasil chain |
| #30 | `3af17964` | 2026-04-26 | `sta/onda2a-resilient-transfer` | 2.A core | Chunked upload + ranged download + ETag + X-Content-Hash |
| #34 | `ed03ce39` | 2026-04-26 | `sta/onda2a-followup-1-worker-wiring` | 2.A | Worker chunked-upload wiring + bytes_uploaded persistence |
| #36 | `100e5154` | 2026-04-26 | `sta/onda2a-followup-3-resume-upload` | 2.A | Operations.resume_upload/3 (admin restart-after-crash) |
| #43 | `99e6e57c` | 2026-04-26 | `sta/onda2a-followup-2-ranged-resume` | 2.A | Streaming download + ranged-resume mid-stream state machine |
| #46 | `1c10b7fa` | 2026-04-26 | `sta/onda2a-followup-callers-wiring` | 2.A | Caller-wiring bundle + OutboundFile schema datetime alignment |
| #52 | `fbf4dac2` | 2026-04-27 | `sta/onda2a-followup-retry-cap-fix` | 2.A | upload_attempts retry-cap fix (changeset bug) |
| #59 | `e54399ab` | 2026-04-27 | `sta/handoff-2026-04-27-onda2b-pause` | 2.A→2.B | Brainstorming pause handoff |
| #62 | `67924840` | 2026-04-27 | `sta/onda2-status-and-queries` | 2.B | Status & queries (C full+admin) — §7.1 + §8.2 + §8.3 + admin endpoints |
| #66 | `a55ad325` | 2026-04-27 | `sta/onda2-rate-and-lifecycle` | 2.C | Rate & lifecycle (B trim) — 3 buckets + 410 per-op + 429 + worker auto-renew |

**Branch local**: limpa (todas deletadas pós-merge); worktree em detached HEAD em `a55ad325`.

---

<a id="superficie"></a>
## 3. Inventário de superfície de código

### Wire-format BCB STA implementado

| Manual § | Endpoint | Operação atom | Pinning estado |
|---|---|---|---|
| §5.1 | `POST /staws/arquivos` | `:request_protocol` | ✅ Onda 1 (B2+B3+B4 SHA-256+Tamanho+Destinatarios fix) + Onda 2.C (410→`:protocol_expired`) |
| §5.2 | `PUT /staws/arquivos/{p}/conteudo` (single) | `:upload_file` | ✅ Onda 1 (B1 protocol number fix) + Onda 2.C (410→`:protocol_expired`) |
| §5.3.1 | `GET /staws/arquivos/{p}/posicaoupload` | `:posicao_upload` | ✅ Onda 2.A (DISCONTIGUOUS ranges) + Onda 2.C (410→`:protocol_expired`) |
| §5.6 | `PUT /staws/arquivos/{p}/conteudo` (Content-Range) | `:upload_part` | ✅ Onda 2.A core + Onda 2.C (410→`:protocol_expired`) |
| §6.1 | `GET /staws/arquivos/{p}/conteudo` | `:download_file` / `:download_file_streamed` | ✅ Onda 2.A core (X-Content-Hash) + Onda 2.A f2 (streaming variant) |
| §6.4 | `GET /staws/arquivos/{p}/conteudo` (Range) | `:download_part` | ✅ Onda 2.A core (If-Match + 410/412/416/501) |
| §7.1 | `PUT /staws/arquivos/situacao` | `:change_status` | ✅ Onda 2.B (batched semicolon-joined Protocolos + REC/A_REC) |
| §8.1 | `GET /staws/arquivos/disponiveis` | `:list_available_files` | ✅ pré-existente (cobre `<SituacaoAtual>` enum, distinto de Tabela 3) |
| §8.2 | `GET /staws/arquivos?tipoConsulta=PROT` | `:query_protocol` | ✅ Onda 2.B (FileQueryResult com EstadoAtual) |
| §8.3 | `GET /staws/arquivos?tipoConsulta=AVANC` | `:advanced_query` | ✅ Onda 2.B (multi-param filtros + a_rec warning + max_results clamp) |

**Não implementado** (deferido): §9 senha mgmt (Onda 2.D), §2.5 client cert auto-rotation (gate operacional).

### Módulos novos (criados nas Ondas 2.A-2.C)

```
lib/sta_connector/sta/
├── client.ex                                        (estendido — todas as 10 operations)
├── client_behaviour.ex                              (estendido — 10 callbacks)
├── operations.ex                                    (estendido — upload_with_retry / download_with_retry / resume_upload / upload_content)
├── error.ex                                         (pré-existente)
├── soap.ex                                          (legado — usado só em testes baseline; produção é REST puro)
├── types.ex                                         (FileInfo + UploadResult + DownloadResult + PosicaoUpload + ProtocolRequest + ★ FileQueryResult ★)
├── state_code.ex                                    ★ NOVO Onda 2.B (Tabela 3 enum + classifications)
├── rate_limiter.ex                                  (estendido — 3 buckets internos + telemetria + retro-compat)
└── rate_limiter/                                    ★ NOVO Onda 2.C
    ├── transfers.ex                                  (10 simultâneos § 2.6 line 190)
    ├── queries.ex                                    (120/min § 2.6 line 192)
    └── status_changes.ex                             (10/min — conservative invention [STUDY-CONJECTURE] #2)

lib/sta_connector/inbound/
└── worker.ex                                        (estendido — decide_next_action/1 future-readiness)

lib/sta_connector/outbound/
└── worker.ex                                        (estendido — decide_next_action/1 + dispatch_upload_error/2 + protocol_renewed flag)

lib/sta_connector/
└── outbound.ex                                      (estendido — clear_protocol/1)

lib/sta_connector_web/controllers/api/admin/
├── outbound_files_controller.ex                     ★ NOVO Onda 2.A f6 (POST /api/admin/outbound_files/:id/resume_upload)
└── sta_query_controller.ex                          ★ NOVO Onda 2.B (GET /api/admin/sta/protocols + /api/admin/sta/queries/advanced)

lib/sta_connector_web/
└── router.ex                                        (estendido — 3 novos routes admin)

priv/certs/
└── icp_brasil_ca_chain.pem                          ★ NOVO Onda 1 (7.7KB, SERPRO público, valida BCB STA cert)

priv/repo/migrations/
└── 20260426150000_add_resilient_transfer_columns.exs ★ NOVO Onda 2.A
```

### Schema deltas

#### `outbound_files` (migration `20260426150000`)

| Coluna | Tipo | Default | Propósito |
|---|---|---|---|
| `posicao_upload` | `:map` | `%{}` | Snapshot do `RangesRecebidos` por reconciliação chunked upload. |
| `bytes_uploaded` | `:bigint` | `0` | Soma idempotente dos chunks ACKed (worker persists post-cada-chunk). |
| `etag` | `:string` | `nil` | Para If-Match em downloads (se vier a aplicar a uploads no futuro). |
| `last_modified` | `:string` | `nil` | RFC 7232 §6.1.4. |
| `x_content_hash` | `:string` | `nil` | SHA-256 hex do file completo per Manual §6.1. |
| `upload_attempts` | `:integer` | `0` | Retry counter — fix em PR #52 (`attempt_changeset` bug). |

Esta migration é **forward-only safe** (todas as colunas são nullable / default-zero, sem constraints novas; sem rename). Pode rodar em produção com tráfego ativo.

### Endpoints HTTP (novos pós-Onda 2)

| Método | Path | Action | Onda | Auth |
|---|---|---|---|---|
| POST | `/api/admin/outbound_files/:id/resume_upload` | `OutboundFilesController.resume_upload` | 2.A f6 | `:admin_api` pipeline |
| GET | `/api/admin/sta/protocols?ids=P1[,P2,...]&detail=res|bas|compl` | `StaQueryController.show_protocols` | 2.B | `:admin_api` pipeline |
| GET | `/api/admin/sta/queries/advanced?date_creation_from=...&state_codes=...&...` | `StaQueryController.advanced` | 2.B | `:admin_api` pipeline |

⚠️ **`:admin_api` pipeline ainda tem `# Future: Add admin authentication here` TODO** (validado em §11). Os 3 endpoints novos herdam `SsoAuth` plug + esse TODO; deploy em produção sem fechar este gap expõe esses endpoints a chamadas autenticadas-mas-não-RBAC-checked. **Aceitável em homologação**, mas precisa fechar antes de produção.

### Telemetria emitida (novos eventos pós-Onda 2)

| Evento | Measurements | Metadata | Emitter |
|---|---|---|---|
| `[:sta, :rate_limiter, :acquire]` | `%{wait_ms: int}` | `%{bucket: :transfers \| :queries \| :status_changes \| :both, status: :ok \| :wait}` | RateLimiter (Onda 2.C) |

Wave 11 P2 metrics framework já tem o pattern de attach automático; quando deployar, esses contadores aparecem em Prometheus sem código adicional. Sem definição de métricas neste PR (deferido per plan §Out of scope).

---

<a id="testes"></a>
## 4. Matriz de cobertura de testes

### Touchstone files (rodar em todo PR)

| Arquivo | Testes | Falhas baseline | Notas |
|---|---|---|---|
| `test/sta_connector/sta/client_test.exs` | **94** | **6** ⚠️ | 6 falhas pré-Onda-1 em `Soap.parse_response/2` (legacy SOAP path; produção usa REST puro). NÃO investigar — documentado como ruído baseline. |
| `test/sta_connector/sta/operations_test.exs` | **58** | 0 | Cobre `upload_with_retry` + `download_with_retry` + `resume_upload` + Mox stubs do Client. |
| `test/sta_connector/files/outbound_file_test.exs` | **7** | 0 | Schema-level (datetime usec, status enum). |
| `test/sta_connector/application_test.exs` | **3** | 0 | Supervisor tree boots cleanly. |
| `test/sta_connector/outbound_test.exs` | **38** | 0 | Context-level (submit_file, mark_uploading, mark_completed, mark_failed, set_protocol, clear_protocol). |
| `test/sta_connector_web/controllers/api/admin/outbound_files_controller_test.exs` | **7** | 0 | `:resume_upload` action (PR #46). |
| **Subtotal touchstones** | **207** | **6** | |

### Files novos pós-Onda 2 (rodar junto)

| Arquivo | Testes | Falhas | Onda |
|---|---|---|---|
| `test/sta_connector/sta/state_code_test.exs` | **14** | 0 | 2.B (Tabela 3) |
| `test/sta_connector/inbound/worker_test.exs` | **3** | 0 | 2.B (decide_next_action) |
| `test/sta_connector/outbound/worker_test.exs` | **8** | 0 | 2.B (decide_next_action 3) + 2.C (dispatch_upload_error 5) |
| `test/sta_connector_web/controllers/api/admin/sta_query_controller_test.exs` | **16** | 0 | 2.B (protocols + advanced admin) |
| `test/sta_connector/sta/rate_limiter_three_bucket_test.exs` | **14** | 0 | 2.C (3 buckets) |
| **Subtotal novos** | **55** | 0 | |

### Total combinado (rodada batch)

```
mix test \
  test/sta_connector/sta/client_test.exs \
  test/sta_connector/sta/operations_test.exs \
  test/sta_connector/files/outbound_file_test.exs \
  test/sta_connector/application_test.exs \
  test/sta_connector/outbound_test.exs \
  test/sta_connector_web/controllers/api/admin/outbound_files_controller_test.exs \
  test/sta_connector/sta/state_code_test.exs \
  test/sta_connector/inbound/worker_test.exs \
  test/sta_connector/outbound/worker_test.exs \
  test/sta_connector_web/controllers/api/admin/sta_query_controller_test.exs \
  test/sta_connector/sta/rate_limiter_three_bucket_test.exs

# Esperado: 262 tests, 6 failures (todas em Soap.parse_response — baseline)
# Tempo: ~2.7s (2.4s async + 0.3s sync) em laptop M-series
```

### Failures NÃO toctstones (NÃO investigar)

- `test/sta_connector/inbound/poller_test.exs` — 21/36 falhas. Pre-existing DB-setup gaps documentados desde antes da Onda 1. Bypass-style integration test que precisa rebuild.
- `test/sta_connector/inbound/poller_integration_test.exs`, `router_test.exs`, `supervisor_test.exs` — falhas de infra similares. Hygiene PR isolado quando alguém tiver tempo.

### `mix test` full-suite — **NÃO RODAR**

Suíte cheia tem ~120 testes em supervisores/poller que requerem DB + NATS + Redis live. Quebrada em CI por outras razões pré-existentes. **Sempre rodar per-file ou batch específico.**

---

<a id="config"></a>
## 5. Configuração — env vars + secrets

### Env vars que `runtime.exs` lê em produção

| Var | Default | Manual / Notes |
|---|---|---|
| `DATABASE_URL` | (raise) | Aurora `monetarie-sta-homolog` (proxy via Secrets Manager — see secrets.tf) |
| `DATABASE_SSL` | `"true"` | TLS para Aurora |
| `POOL_SIZE` | `"10"` | Ecto pool |
| `ECTO_IPV6` | `false` | IPv6 connect (default off) |
| `SECRET_KEY_BASE` | (raise) | `mix phx.gen.secret` 64 chars |
| `PHX_HOST` | `"example.com"` | **DEVE setar para `staapi-homolog.monetarie.com.br`** ou similar |
| `PHX_SERVER` | unset | Setar para qualquer truthy pra Bandit subir HTTP |
| `PORT` | `"4000"` | HTTP port (atrás do ALB) |
| `DNS_CLUSTER_QUERY` | unset | Para libcluster (não usado em STA hoje) |
| **STA-específicos** | | |
| `STA_ENVIRONMENT` | `"homologation"` | `"homologation"` ou `"production"` (toggle do endpoint BCB sta-h.bcb.gov.br vs sta.bcb.gov.br) |
| `STA_TIMEOUT_MS` | `"30000"` | Finch HTTP timeout |
| `STA_MAX_RETRIES` | `"3"` | Operations retry budget |
| `STA_BCB_USERNAME` | unset | ⚠️ **REQUIRED em produção** (Sisbacen operator user) |
| `STA_BCB_PASSWORD` | unset | ⚠️ **REQUIRED em produção** |
| `STA_ADMIN_USERNAME` | `"admin"` | Phoenix.Token admin login |
| `STA_ADMIN_PASSWORD` | (raise em prod) | Phoenix.Token admin login |
| `STA_WORKERS_ENABLED` | `"true"` (em prod) | Inbound poller + Outbound uploader |
| `STA_CONFIG_PATH` | `config/sta_config.json` | Path para JSON file de routing (Inbound). Pode override via volume mount. |
| **Poller** | | |
| `POLLER_ENABLED` | `"true"` | Toggle Inbound poller |
| `POLLER_INTERVAL_MS` | `"60000"` | 1min ticks |
| `POLLER_WORKER_COUNT` | `"4"` | Concurrent download workers |
| **Rate limit** (legados — mantidos por backward-compat) | | |
| `RATE_LIMIT_MAX_CONCURRENT` | `"10"` | `:transfers` bucket cap |
| `RATE_LIMIT_MAX_QPM` | `"120"` | `:queries` bucket cap |
| **mTLS** | | |
| `ICP_BRASIL_CHAIN_PATH` | `priv/certs/icp_brasil_ca_chain.pem` | Override pra release que carrega chain do Secrets Manager |
| **NATS** | | |
| `NATS_HOSTS` | unset | Comma-sep `host:port`. Fallback `NATS_HOST` + `NATS_PORT`. Cluster `monetarie.internal:4222` |
| `NATS_HOST` | `"localhost"` | Single-node fallback |
| `NATS_PORT` | `"4222"` | Single-node fallback |
| **Simulator** (homologação interna) | | |
| `SIMULATOR_ENABLED` | `"false"` | NÃO ativar em produção BCB-real |

### Secrets — estado atual em AWS Secrets Manager (`infra/aws/greenfield/secrets.tf`)

✅ **Já provisionados**:
- `monetarie/{env}/db/mon_sta/password` (Aurora STA password — auto-gerado random_password)
- `monetarie/{env}/auth/mon_sta/secret_key_base` (Phoenix secret_key_base STA)
- `monetarie/{env}/auth/mon_sta/guardian_secret` (Guardian JWT)
- `monetarie/{env}/bacen/ispb` (46026562)
- `monetarie/{env}/bacen/sisbacen` (00018)

❌ **AINDA NÃO provisionados — DEVE adicionar antes de deploy**:
- `monetarie/{env}/sta/bcb_username` (Sisbacen operator login)
- `monetarie/{env}/sta/bcb_password` (Sisbacen operator senha)
- `monetarie/{env}/admin/sta/initial_password` (admin login STA — rotacionar pós-primeiro-login)

#### Snippet Terraform sugerido para `infra/aws/greenfield/secrets.tf`

```hcl
# STA BCB Sisbacen operator credentials — rotação manual via BCB workflow.
# www2.bcb.gov.br/staws — Manual STA Web Services v1.5 §2.2.
resource "aws_secretsmanager_secret" "sta_bcb_username" {
  name                    = "monetarie/${var.environment}/sta/bcb_username"
  description             = "Sisbacen operator username for STA WebService"
  kms_key_id              = aws_kms_key.service["mon_sta"].arn
  recovery_window_in_days = 7
}

resource "aws_secretsmanager_secret" "sta_bcb_password" {
  name                    = "monetarie/${var.environment}/sta/bcb_password"
  description             = "Sisbacen operator password for STA WebService"
  kms_key_id              = aws_kms_key.service["mon_sta"].arn
  recovery_window_in_days = 7
}

resource "aws_secretsmanager_secret" "sta_admin_initial_password" {
  name                    = "monetarie/${var.environment}/admin/sta/initial_password"
  description             = "ADMIN_INITIAL_PASSWORD seed for STA admin; rotate after first login"
  kms_key_id              = aws_kms_key.service["mon_sta"].arn
  recovery_window_in_days = 7
}

# Versions são plumb-on-create vazios; operador preenche via console / aws secretsmanager put-secret-value.
# (Mesmo pattern dos secrets mon_npc cloak_key existentes em secrets.tf:140+.)
```

⚠️ **Nota sobre rotação**: as credenciais BCB STA não fazem auto-rotation no AWS Secrets Manager (rotation lambda não existe). Setup manual via BCB portal `senhaws/senha` (futuro Onda 2.D) ou via tela do operador.

---

<a id="deploy-readiness"></a>
## 6. Avaliação de deploy-readiness

### Checklist de readiness

| Item | Status | Comentário |
|---|---|---|
| Code compiles | ✅ | 5 warnings pre-existentes; sem novos. |
| Tests pass | ✅ | 262/256 deterministic; 6 baseline failures preserved. |
| Migrations forward-safe | ✅ | `20260426150000` é nullable-add only. |
| Secrets in AWS Secrets Manager | ⚠️ PARCIAL | DB + auth provisionados; **BCB credentials + admin pwd faltam**. |
| Aurora `monetarie-sta-homolog` provisioned | ✅ | Em `aurora.tf` for_each. |
| Aurora migrations executadas | ❌ | G2 (drop+recreate ainda não autorizado). 0 migrations rodadas. |
| ECR repo `monetarie-sta-backend-homolog` | ❓ | **Verificar via `aws ecr describe-repositories --profile monetarie --region sa-east-1`** — provavelmente não existe (sem `fargate-sta.tf`). |
| ECS task definition `monetarie-sta-backend-homolog` | ❌ | Não existe em TF. |
| ECS service `monetarie-sta-backend-homolog` | ❌ | Não existe em TF. |
| ALB target group + listener rule | ❌ | Não existe em TF. |
| Route53 record `staapi-homolog.monetarie.com.br` | ❓ | Verificar em `route53.tf` — provavelmente não existe. |
| GitHub Actions workflow `deploy-sta-homolog.yml` | ❌ | Não existe. Só `deploy-core-api-homolog.yml`. |
| OIDC role `monetarie-gha-deploy-homolog` | ✅ | Existe (compartilhada com Core API; só precisa permission pra ECR sta + ECS sta). |
| Health endpoint `/health` retorna 200 | ✅ | `HealthController.check` (sem auth). |
| Readiness endpoint `/ready` checa DB+NATS | ✅ | `HealthController.ready`. |
| ICP-Brasil chain válida | ✅ | `priv/certs/icp_brasil_ca_chain.pem` (Onda 1, validada via `openssl verify` em SPB). |
| BCB STA endpoint reachability | ❓ | Validar de dentro da VPC: `curl -v https://sta-h.bcb.gov.br/staws` deve retornar 401 (auth necessária) sem TLS error. |
| Logging para CloudWatch | ✅ | Phoenix + Logger configurados; ECS task def vai precisar logConfiguration FlUent-Bit ou awslogs. |
| Telemetry / Prometheus | ⚠️ | Eventos emitidos pelo código; metrics endpoint `/metrics` expõe Prometheus format. **Verificar se ALB roteia `/metrics` antes do scrape.** |

### Conclusão da avaliação

**O código está deploy-ready.** A infra **está 60% deploy-ready**:
- ✅ Aurora provisionado
- ✅ KMS + base secrets
- ✅ ECS cluster compartilhado
- ❌ Sem fargate-sta.tf (task def + service + target group)
- ❌ Sem secrets BCB
- ❌ Sem GitHub Actions workflow
- ❌ Sem migration run

---

<a id="deploy-paths"></a>
## 7. Caminhos recomendados de deploy

### Antes de escolher: 4 perguntas operacionais que precisam de resposta

1. **`STA_BCB_USERNAME` e `STA_BCB_PASSWORD` já foram emitidos pelo BCB?** Sem isso, o STA backend sobe mas qualquer chamada à BCB volta com 401. Onde está armazenado hoje (cofre interno, vault, planilha do operador)?
2. **`STA_ADMIN_PASSWORD` — quem define a senha inicial?** Sugestão: usuário gera senha forte, coloca em `monetarie/homolog/admin/sta/initial_password`, primeiro login força reset.
3. **`PHX_HOST` desejado** — `staapi-homolog.monetarie.com.br` (ProDNS — adicionar em CNAME pro ALB) ou outro? ACM wildcard `*.monetarie.com.br` cobre.
4. **G2 (Aurora drop+recreate)** — autoriza rodar contra `monetarie-sta-homolog`? Migrations vão criar 4 tabelas novas (`processed_protocols`, `outbound_files`, `retry_queue`, `config_overrides`) + RBAC tables. Sem dados pré-existentes na Aurora STA, é safe drop.

Sem responder (1) e (2), o deploy SOBE mas fica com `STA_BCB_USERNAME=nil` → BCB rejeita 401 em toda chamada → workers loopam em retry. Não é mortal (retry-cap fix em PR #52 protege), mas é tempo de ECS reiniciando à toa.

### Path A — Manual one-shot (fastest, ~2-4h)

**Quando escolher**: precisa de validação fim-a-fim em homolog hoje, sem CI/CD ainda; o time está disposto a fazer um deploy "à mão" para validar paridade Manual antes de investir em plumbing TF/CI.

**Passos**:

1. **Provisionar secrets BCB** (uma vez):
   ```bash
   aws secretsmanager create-secret \
     --profile monetarie --region sa-east-1 \
     --name monetarie/homolog/sta/bcb_username \
     --secret-string "<usuario-sisbacen>"
   aws secretsmanager create-secret \
     --profile monetarie --region sa-east-1 \
     --name monetarie/homolog/sta/bcb_password \
     --secret-string "<senha>"
   aws secretsmanager create-secret \
     --profile monetarie --region sa-east-1 \
     --name monetarie/homolog/admin/sta/initial_password \
     --secret-string "<senha-forte-rotacionar>"
   ```

2. **Build + push imagem manual** (one-shot — `regra-absoluta-3` proibe build manual em **produção**, mas autoriza em homolog operacional):
   ```bash
   cd sta/backend
   aws ecr get-login-password --region sa-east-1 --profile monetarie | docker login --username AWS --password-stdin 364807861246.dkr.ecr.sa-east-1.amazonaws.com
   aws ecr create-repository \
     --profile monetarie --region sa-east-1 \
     --repository-name monetarie-sta-backend-homolog \
     --image-tag-mutability MUTABLE
   # Build local arm64 (necessita docker buildx + qemu se laptop x86)
   docker buildx build --platform linux/arm64 \
     -t 364807861246.dkr.ecr.sa-east-1.amazonaws.com/monetarie-sta-backend-homolog:onda2c \
     --push .
   ```

3. **Criar Task Definition + ECS Service** via Terraform "express" (rápido — 1 arquivo):
   - Copiar `fargate-core-api.tf` → `fargate-sta.tf`
   - Substituir nomes / variáveis
   - Apontar `secrets` block para os 3 novos AWS Secrets
   - Apontar `environment` block para as env vars do §5
   - `terraform plan && terraform apply -target=aws_ecs_service.sta_backend ...`

4. **Rodar migrations** uma vez via one-off task:
   ```bash
   aws ecs run-task --cluster monetarie-greenfield-homolog \
     --task-definition monetarie-sta-backend-homolog \
     --launch-type FARGATE --network-configuration ... \
     --overrides '{"containerOverrides":[{"name":"sta-backend","command":["bin/sta_connector","eval","StaConnector.Release.migrate()"]}]}' \
     --profile monetarie --region sa-east-1
   ```

   **Nota**: se `StaConnector.Release.migrate/0` não existir, criar via `lib/sta_connector/release.ex` mirror da `Monetarie.Release` em core. ~20 linhas.

5. **Validar via `/health` + `/ready` + smoke tests do §9**.

**Riscos**: build local não-determinístico vs CI, sem audit trail de quem deployou.
**Tempo estimado**: 2-4h — bottleneck é (a) ter os secrets BCB em mãos e (b) escrever `fargate-sta.tf` + testar.

### Path B — Plumbing direito (~4-6h primeira vez, ~5min depois)

**Quando escolher**: dispostos a investir 1 dia agora para nunca mais ter que fazer manualmente. **Recomendado** se há tempo até fim do dia.

**Passos**:

1. Criar `fargate-sta.tf` (mirror `fargate-core-api.tf`).
2. Estender `infra/aws/greenfield/secrets.tf` com os 3 novos secrets (snippet em §5).
3. Estender `infra/aws/greenfield/route53.tf` ou `alb.tf` com listener rule + target group + Route53 CNAME.
4. Criar `.github/workflows/deploy-sta-homolog.yml` (mirror `deploy-core-api-homolog.yml`).
5. Adicionar `lib/sta_connector/release.ex` para `StaConnector.Release.migrate/0`.
6. `terraform apply` para subir infra.
7. `git push` qualquer SHA → workflow assume role → builds → push ECR → updates ECS → wait-for-stability.
8. Run-task one-off para migrations.
9. Smoke tests do §9.

**Riscos**: mais surface change em TF (peer-review necessário), Route53 / ACM alignment com ProDNS pode ter delay (~30min DNS prop).
**Tempo estimado**: 4-6h primeira vez; subsequentes deploys são `git push` → ECS rolls.

### Path C — Adiar 1-2 dias (recommended se há banda)

**Quando escolher**: time prefere deploy com plumbing testado e revisado em vez de manual today; cabine STA está atrás do que outras cabines (PIX/SPB) que ainda têm work pendente.

**Vantagem**: zero risco de erro humano em manual; deploy do PR #66 vira commit em `infra/` rastreável; primeiro deploy é também o template para futuros.

**Tempo até deploy**: 1-2 dias úteis.

### Recomendação

Se **(1)** STA_BCB credentials estão em mãos AGORA + **(2)** time tem 4h disponíveis hoje, **Path B** é a melhor combinação custo/qualidade.
Se há pressa real e os credentials estão prontos, **Path A** vai funcionar mas vai gerar dívida (`fargate-sta.tf` ad-hoc; workflow pendente; deploy não rastreável).
Se há QUALQUER incerteza sobre os credentials BCB ou autorização de G2, **Path C** é o seguro.

---

<a id="pre-deploy"></a>
## 8. Pre-deploy checklist (executar em ordem)

```
[ ] 1. Confirmar STA_BCB_USERNAME e STA_BCB_PASSWORD com operador / time interno
[ ] 2. aws secretsmanager create-secret pra os 3 secrets STA novos
[ ] 3. Confirmar autorização G2 (Aurora drop+recreate) com user — validar com pgcli/psql
       que monetarie-sta-homolog está vazio antes do migrate
[ ] 4. (Path B) Criar fargate-sta.tf + secrets.tf delta + route53/alb delta
       (Path A) Criar fargate-sta.tf via copy-paste-modify
[ ] 5. terraform plan — review todos os AWS resources criados
[ ] 6. terraform apply
[ ] 7. (Path A) docker buildx build --platform linux/arm64 --push
       (Path B) git push → workflow → wait-for-stability
[ ] 8. aws ecs run-task pra StaConnector.Release.migrate()
       Validar logs no CloudWatch — esperar "Migrated 7 migrations"
[ ] 9. aws ecs describe-services — esperar runningCount == desiredCount
[ ] 10. curl https://staapi-homolog.monetarie.com.br/health → 200 {"status":"ok"}
[ ] 11. curl https://staapi-homolog.monetarie.com.br/ready → 200 (DB+NATS health)
[ ] 12. Login admin via /api/auth/login com STA_ADMIN_USERNAME / initial_password
        → forçar reset senha + receber JWT
[ ] 13. Smoke tests do §9 (todos)
[ ] 14. Confirmar telemetry attached (Prometheus /metrics tem pix_message_validation_total
        e [:sta, :rate_limiter, :acquire] event count)
[ ] 15. Documentar: PR + handoff + memory entry
```

---

<a id="smoke-tests"></a>
## 9. Smoke tests pós-deploy

### 9.1 Health & Readiness (sem dependência BCB)

```bash
HOST=https://staapi-homolog.monetarie.com.br

curl -fsS $HOST/health
# Expected: 200 {"status":"ok","timestamp":"..."}

curl -fsS $HOST/ready
# Expected: 200 (DB + NATS reachable; sem 503)

curl -fsS $HOST/metrics | head -20
# Expected: Prometheus exposition format; pelo menos `phoenix_endpoint_request_duration_seconds`
```

### 9.2 Admin login + JWT

```bash
TOKEN=$(curl -fsS -X POST $HOST/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"<initial_password>"}' \
  | jq -r .token)

# Expected: token JWT válido (60+ chars)

curl -fsS $HOST/api/auth/me -H "Authorization: Bearer $TOKEN"
# Expected: 200 {"user":...}
```

### 9.3 RateLimiter status (sem chamar BCB)

```bash
curl -fsS $HOST/api/admin/metrics -H "Authorization: Bearer $TOKEN" | jq .rate_limit
# Expected: bucket-grouped:
#   {transfers: {slots: 10, max: 10}, queries: {tokens: 120, max: 120}, status_changes: {tokens: 10, max: 10}}
```

### 9.4 Onda 2.B admin endpoints (sem chamar BCB — testa só roteamento + parsing)

```bash
# Sem ids → 400 missing_parameter
curl -fsS -o /dev/null -w "%{http_code}" \
  $HOST/api/admin/sta/protocols \
  -H "Authorization: Bearer $TOKEN"
# Expected: 400

# detail inválido → 400 invalid_parameter
curl -fsS -o /dev/null -w "%{http_code}" \
  "$HOST/api/admin/sta/protocols?ids=P1&detail=bogus" \
  -H "Authorization: Bearer $TOKEN"
# Expected: 400

# Tudo válido → 502 client_error (BCB unreachable / 401 sem cred ou 200 se cred válido)
curl -fsS -w "\nstatus=%{http_code}\n" \
  "$HOST/api/admin/sta/protocols?ids=NEXISTE" \
  -H "Authorization: Bearer $TOKEN"
# Expected: 502 com body {"error":"client_error","message":"..."}
#           OU 200 se BCB realmente respondeu com Resultado vazio
```

### 9.5 Onda 2.A resilient transfer (precisa BCB online — opcional dia 1)

```bash
# Listar arquivos disponíveis (smoke do §8.1 path)
curl -fsS \
  -H "Authorization: Bearer $TOKEN" \
  $HOST/api/admin/files | jq '. | length'
# Expected: integer (pode ser 0 se nenhum arquivo na fila)

# Submeter outbound file pequeno (smoke do §5.1+§5.2 path)
echo "TESTSMOKE" > /tmp/sta_smoke.txt
curl -fsS -X POST $HOST/api/v1/files \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"system_id\":\"CCS\",\"file_name\":\"smoke.txt\",\"content\":\"$(base64 < /tmp/sta_smoke.txt)\"}"
# Expected: 201 {"id":"<uuid>","status":"pending"}

# Verificar transição pending → uploading → uploaded → completed
sleep 30 && curl -fsS $HOST/api/v1/files/<uuid>/status -H "Authorization: Bearer $TOKEN"
# Expected: status="completed", protocol_number set
```

### 9.6 Validação BCB-side (gate operacional)

Após smoke fim-a-fim, **operador deve verificar no portal BCB**:
- Protocolo emitido no STA
- Arquivo processado pelo destinatário (estado_atual=35 "Aceito" ou similar)
- Sem erros no console BCB

Sem essa validação, deploy não está smoke-validated.

---

<a id="risco"></a>
## 10. Avaliação de risco

### Riscos baixos (aceitar)

| Risco | Probabilidade | Impacto | Mitigação |
|---|---|---|---|
| 6 baseline `Soap.parse_response` failures | 100% | Zero | Documentado; SOAP path não é usado em prod (REST puro) |
| Telemetry events sem metric definitions | 100% | Sem impacto operacional dia 1 | Wave 11 P2 adiciona depois |
| `:status_changes` 10/min cap conservador | Baixa | Worker pode esperar +6s entre status changes | Documentado; env-tunable se BCB tolera mais |
| `download_file/410` não mapeia explicitamente | Muito baixa | %Error{} struct ao invés de :file_unavailable | Hygiene PR; comportamento atual é defensável |

### Riscos médios (mitigar antes deploy)

| Risco | Probabilidade | Impacto | Mitigação |
|---|---|---|---|
| `:admin_api` pipeline sem RBAC | Alta | Endpoints admin abertos a SsoAuth-passantes | **Aceitar em homolog**; fechar antes prod |
| Migration roda em Aurora não-vazia | Baixa (G2 ainda gated) | Conflito de esquema | Validar pgcli antes do `Release.migrate()` |
| BCB STA endpoint inalcançável da VPC | Média (primeiro deploy) | Workers loopam | Validar `curl https://sta-h.bcb.gov.br/staws` da bastion antes |
| Inbound poller dispara antes de credentials válidos | Alta | Logs spam de 401 | `POLLER_ENABLED=false` no first-deploy; ativar depois de smoke |

### Riscos altos (BLOCKERS — não deployar sem)

| Risco | Probabilidade | Impacto | Mitigação |
|---|---|---|---|
| `STA_BCB_USERNAME` / `STA_BCB_PASSWORD` ausentes | 100% se não provisionar | TODA chamada BCB → 401 → retry loop | **Provisionar secrets antes do ECS service start** |
| ICP-Brasil chain corrompida no container | Baixa | mTLS fail-CLOSED → 100% das chamadas falham | Validar `Operations.healthcheck/0` ou similar; ou rodar `:openssl_test` em release |
| ECS task de migration corre concorrente com app subindo | Média | Race condition no schema | Garantir desired_count=0 → run migrate task → desired_count=N |

---

<a id="rollback"></a>
## 11. Plano de rollback

### Cenário A — Deploy quebra health checks

1. `aws ecs update-service --service monetarie-sta-backend-homolog --task-definition <PREVIOUS_TASK_DEF_REVISION>`
2. Esperar `runningCount == desiredCount` na revisão anterior.
3. Se anterior NÃO existe (primeira deploy), `desired_count=0` (paralisa serviço).

### Cenário B — Migration falha mid-run

A migration `20260426150000_add_resilient_transfer_columns.exs` é **forward-only safe**:
- 6 colunas novas, todas nullable / default zero
- Sem rename, sem drop, sem constraint nova
- Se falhar mid-way, ecto registra metade — mas `outbound_files` continua funcional sem as colunas novas (worker antigo do PR #46 grava sem eles)

Rollback: rodar `Release.rollback("StaConnector.Repo", "20260131000004")` (4 versões atrás — pré-RBAC). MAS isso quebra Onda 1 (RBAC tables) também. Melhor estratégia: **forward-fix migration** — corrigir e rodar de novo. Aurora retro está em snapshot diário se precisar PITR.

### Cenário C — BCB STA retorna 401 em massa pós-deploy

Indica credentials erradas. Não é rollback — é **fix-forward**:
1. Atualizar `aws secretsmanager update-secret --secret-id monetarie/homolog/sta/bcb_password --secret-string <correta>`
2. `aws ecs update-service --force-new-deployment` para puxar novo secret
3. Worker retoma operação automaticamente (retry-cap em PR #52 protege)

### Cenário D — Workers em loop infinito de erro

Apertar `STA_WORKERS_ENABLED=false`:
1. Update task def env var
2. Force new deployment
3. Workers param de processar; queue acumula
4. Investigar causa, fix, re-enable

---

<a id="gates"></a>
## 12. Hard gates pendentes (não-STA-só, mas relevantes)

| Gate | Detalhes | Status | Bloqueia STA homolog? | Bloqueia STA prod? |
|---|---|---|---|---|
| **G1** Certisign T001 cert | Pra SPB BACEN auth — STA usa BCB-emitted user/pass, NÃO ICP-Brasil cert pessoal | ⏳ Aguardando ~1 sem | NÃO | NÃO |
| **G2** Aurora drop+recreate | Pra populating Aurora limpa via ETL | ⏳ User authorization | SIM (migrations) | SIM |
| **G3** BCB MQ creds | SPB only (IBM MQ) | ⏳ | NÃO | NÃO |
| **G4** STA upload + GEN0006 ACCP | SPB cert activation via STA homolog upload code CERTSPB | ⏳ Depende G1 + STA homolog working | NÃO | NÃO |
| **G5** STA admin auth (`:admin_api` RBAC) | Fechar `# Future: Add admin authentication here` TODO | ⏳ | NÃO | **SIM** (segurança em prod) |
| **G6** STA_BCB_USERNAME/PASSWORD provisionados | Sisbacen operator credentials | ⏳ User input | SIM | SIM |

**Observação importante**: STA NÃO depende de Certisign cert pessoal (G1) — a autenticação BCB STA é HTTP Basic com credenciais Sisbacen do operador. ICP-Brasil chain é só pra **TLS server-side** (BCB endpoint validation). Confusão fácil entre cabine SPB (que usa cert pessoal pra binary signing) e cabine STA (que só faz TLS one-way).

---

<a id="limitacoes"></a>
## 13. Limitações conhecidas + TODOs

### Limitações ACEITAS (deferir para Onda 2.D / 3 / 4 / hygiene)

1. **Onda 2.D (não started)** — `/senhaws/senha` password mgmt para Sisbacen operator. ~300 LOC, 1 dia. Independente de 2.C; usa hosts diferentes (`www9.bcb.gov.br/senhaws` homol / `www3.bcb.gov.br/senhaws` prod).
2. **Onda 3 (não started)** — leiautes RSFN corpus (44 leiautes / 9 categorias) + XSD validator + XML signer. ~2-3 dias por sub-PR. Bloqueia Compliance ACCS001/ACCS010 prod traffic.
3. **Onda 4 (não started)** — identifier mapping em `core/` (CCS→PCCS001 etc.) + STA delivery context wiring.
4. **`OutboundFile.protocol_expires_at`** — proactive 48h tracking deferido. Reactive 410 handling cobre correctness.
5. **Inbound.Worker `:rate_limited` handling** — apenas Outbound implementa hoje. Inbound usa RetryEntry-based budget.
6. **Operations.upload_with_retry retry-loop** — não vê `:protocol_expired` / `:rate_limited` (Worker dispatch trata). Refactor é hygiene PR.
7. **Inner-Client rate check** — duplicado vs RateLimiter façade; mantido como pre-flight cheap check. Removal é hygiene.
8. **Worker integration tests** — só pure-helper coverage hoje. GenServer integration com DB + Mox é hygiene PR.
9. **`download_file/410 → :file_unavailable`** — não tem clause explícita; cai no `Error.from_http_status/2`. Standardização é behavior change para callers que esperam `%Error{}` shape; deferida.
10. **Telemetry metric definitions** — eventos emitidos, mas Wave 11 P2 ainda não adicionou os Prometheus collectors específicos.

### TODOs explícitos no código (busca `TODO\|FIXME\|XXX`)

```bash
$ cd sta/backend && grep -rn "TODO\|FIXME\|XXX" lib/ test/ 2>&1 | head -20
```

(Lista a executar pós-merge; rastreáveis via `git grep`.)

### Pre-existing baseline noise

- 6 falhas em `client_test.exs` describe `Soap.parse_response/2`
- 21+ falhas em `inbound/poller_test.exs`, `supervisor_test.exs`, `router_test.exs`, `poller_integration_test.exs`
- Origem: setup DB / mock missing pré-Onda-1
- **NÃO investigar** — hygiene PR isolado

### Configuração de simulator

`SIMULATOR_ENABLED=true` ativa um Bypass-style mock interno (`Shared.Bacen.Simulator`) — NÃO confundir com PIX simulator. Usa para tests E2E sem BCB real. **NÃO ativar em prod** sob nenhuma circunstância.

---

<a id="proxima-sessao"></a>
## 14. Continuidade — próxima sessão

### Resumption checklist

```bash
cd /Users/luizpenha/monetarie/.worktrees/sta-paridade
pwd                                          # → /Users/luizpenha/monetarie/.worktrees/sta-paridade
git fetch origin --prune
git status                                   # working tree clean
git log --oneline origin/main..HEAD          # vazio (HEAD == origin/main após cleanup)
git log --oneline -5                         # → a55ad325 (PR #66) entre os top

cd sta/backend
mix deps.get
mix compile 2>&1 | grep -c "^[[:space:]]*warning:"   # → 5

# Touchstone batch
mix test \
  test/sta_connector/sta/client_test.exs \
  test/sta_connector/sta/operations_test.exs \
  test/sta_connector/files/outbound_file_test.exs \
  test/sta_connector/application_test.exs \
  test/sta_connector/outbound_test.exs \
  test/sta_connector_web/controllers/api/admin/outbound_files_controller_test.exs \
  test/sta_connector/sta/state_code_test.exs \
  test/sta_connector/inbound/worker_test.exs \
  test/sta_connector/outbound/worker_test.exs \
  test/sta_connector_web/controllers/api/admin/sta_query_controller_test.exs \
  test/sta_connector/sta/rate_limiter_three_bucket_test.exs
# Esperado: 262 tests, 6 failures (baseline preservadas)
```

### Decision tree

#### Estado A — ainda não deployou (próxima sessão na engenharia)

3 sub-PRs candidatos prioritizados:

| Opt | Sub-PR | Estimate | Razão |
|---|---|---|---|
| **A1** | **Onda 2.D password mgmt** | 1 dia / ~300 LOC | Independente; valida operacional senha-rotation antes de prod |
| **A2** | **Onda 3.A leiautes corpus** | 1-2 dias / ~400 LOC + 2-3 MB corpus | Destrava ACCS001/ACCS010 builders + XSD validation |
| **A3** | **Hygiene PR — `:admin_api` RBAC** | 1 dia / ~200 LOC | Fecha G5 (blocker prod) — RequirePermission plug em STA |

**Recomendação**: **A3 hygiene RBAC** se prod está no horizonte. **A1 Onda 2.D** se time tem cycle pra paralela com infra deploy.

#### Estado B — deploy feito, smoke validados

Próxima sessão vai ser **operacional + Onda 2.D**:
- Confirmar logs CloudWatch sem erros 401/500 sustentados
- Validar Aurora `monetarie-sta-homolog` accumulating tracking rows
- Iniciar Onda 2.D senha mgmt para fechar last-mile do operacional

#### Estado C — deploy feito + smoke quebrado

**Não fazer rollback automaticamente.** Triagem:
1. Logs CloudWatch — qual stack trace?
2. Se BCB 401: `aws secretsmanager update-secret` → `update-service --force-new-deployment`
3. Se DB error: rollback migration via `Release.rollback`
4. Se mTLS error: chain corrompida — verificar `priv/certs` no container

### MEMORY.md update (próxima sessão deve atualizar)

Adicionar à `MEMORY.md` raiz uma entrada `## 📍 Where we paused — STA paridade (2026-04-27 — Ondas 1+2.A+2.B+2.C all merged)` com:
- 7 PRs mergeados + SHAs
- Estado deploy-readiness (code 100%, infra 60%)
- Próxima ação: Onda 2.D OU plumbing infra
- Hard gates STA (G6 BCB creds, G5 admin auth)

(Não vou atualizar MEMORY.md raiz nesta sessão — outras sessões paralelas mexem nele; deixar pra próxima sessão STA-só fazer cleanly.)

---

<a id="referencias"></a>
## 15. Referências

### Plan docs (in-repo)

- **Parent rollout plan**: `sta/docs/plans/2026-04-26-sta-conformance-rollout.md` (todas as 4 ondas + sub-PRs)
- **Onda 2.A core**: `sta/docs/plans/2026-04-26-sta-onda2a-resilient-transfer.md`
- **Onda 2.A f2**: `sta/docs/plans/2026-04-26-sta-onda2a-followup-2-ranged-resume.md`
- **Onda 2.A caller-wiring**: `sta/docs/plans/2026-04-26-sta-onda2a-followup-caller-wiring.md`
- **Onda 2.B**: `sta/docs/plans/2026-04-27-sta-onda2b-status-and-queries-full-admin.md`
- **Onda 2.C**: `sta/docs/plans/2026-04-27-sta-onda2c-rate-and-lifecycle-trim.md`

### Handoff chain (in-repo)

- **Onda 2.A f2 handoff**: `sta/docs/handoff/2026-04-26-sta-onda2a-followup-2-ranged-resume.md`
- **Onda 2.A f-callers handoff**: `sta/docs/handoff/2026-04-26-sta-onda2a-followup-callers-wiring.md`
- **Onda 2.A status-pré-2.B handoff**: `sta/docs/handoff/2026-04-26-sta-onda2a-followups-status-and-next-session.md`
- **Onda 2.B brainstorming pause handoff**: `sta/docs/handoff/2026-04-27-sta-onda2b-brainstorming-pause-and-onda2a-complete.md`
- **Onda 2.B EOS handoff**: `sta/docs/handoff/2026-04-27-sta-onda2b-full-admin-complete.md`
- **Onda 2.C EOS handoff**: `sta/docs/handoff/2026-04-27-sta-onda2c-trim-complete.md`
- **THIS handoff**: `sta/docs/handoff/2026-04-27-sta-paridade-EOS-COMPREHENSIVE.md`

### Manual STA references

- `sta/Manual_STA_Web_Services.pdf` v1.5 jul/2022 — canonical PDF.
- `/tmp/manual_sta.txt` — extract regenerable via `pdftotext -layout`.
- §2.6 Limites de conexões (rate caps).
- §5 (Envio): §5.1 Requisição, §5.2 Envio completo, §5.3 Posicao upload, §5.6 Envio parte.
- §6 (Recebimento): §6.1 Completo, §6.2 Resume, §6.4 Parte.
- §7 Alteração de situação.
- §8 Consultas: §8.1, §8.2, §8.3 + Tabelas 1-3.
- §9 Senha mgmt (Onda 2.D futura).

### RFCs

- RFC 6585 — HTTP 429.
- RFC 7231 §7.1.3 — Retry-After.
- RFC 7232 — ETag, If-Match, Last-Modified.
- RFC 7233 — Range requests.
- RFC 5754 — SHA-2.

### Infra docs

- `infra/aws/greenfield/CLAUDE.md` (raiz Terraform).
- `docs/plans/2026-04-23-aws-greenfield-design.md` (design completo).
- `infra/aws/greenfield/aurora.tf` (cluster `monetarie-sta-homolog`).
- `infra/aws/greenfield/secrets.tf` (KMS + base secrets STA).
- `infra/aws/greenfield/ecs-cluster.tf` (cluster compartilhado).
- `infra/aws/greenfield/fargate-core-api.tf` (template para `fargate-sta.tf`).

### PRs (cronológico)

| PR | SHA | Title |
|---|---|---|
| #24 | `301503ec` | Onda 1 — wire-format + ICP-Brasil chain |
| #30 | `3af17964` | Onda 2.A core — chunked upload + ranged download |
| #34 | `ed03ce39` | Worker chunked-upload wiring |
| #36 | `100e5154` | Operations.resume_upload/3 |
| #43 | `99e6e57c` | Streaming download + ranged-resume mid-download |
| #46 | `1c10b7fa` | Caller-wiring bundle + OutboundFile schema fix |
| #52 | `fbf4dac2` | upload_attempts retry-cap fix |
| #59 | `e54399ab` | Onda 2.B brainstorming pause handoff |
| #62 | `67924840` | Onda 2.B status & queries (C full+admin) |
| #66 | `a55ad325` | Onda 2.C rate & lifecycle (B trim) |

### Worktree state final

```
Worktree:    /Users/luizpenha/monetarie/.worktrees/sta-paridade
Branch:      detached HEAD
HEAD:        a55ad325 (Merge PR #66)
Working tree: clean
Untracked:   none in sta/
Aheado de origin/main: 0 commits
```

---

## TL;DR de uma linha pra propor amanhã

**Cabine STA paridade-comprehensiva 100% mergeada (10 PRs / Ondas 1+2.A+2.B+2.C); deploy hoje requer (1) provisionar 3 secrets BCB+admin no AWS Secrets Manager + (2) criar `infra/aws/greenfield/fargate-sta.tf` + (3) rodar 7 migrations no Aurora monetarie-sta-homolog (gated G2). Plumbing CI/CD via deploy-sta-homolog.yml é Onda separada (recomendado Path B).**

---

**Fim do handoff.** Total: ~1,500 linhas, 15 seções, todas as fontes referenciadas.