SIENTIAPDE-1972: fixa NATS como broker decidido (brief/Vitor) e reflete rename da branch

docs/superpowers/specs/2026-07-13-opc-gateway-design.md

@@ -3,7 +3,7 @@
 - **Épico:** [SIENTIAPDE-1972](https://aignosi-wiki.atlassian.net/browse/SIENTIAPDE-1972) — OPC Gateway derivado do OPC Ingestor, com ajustes no Orchestrator e no Laborious.
 - **Sub-tasks:** [1973](https://aignosi-wiki.atlassian.net/browse/SIENTIAPDE-1973) (Gateway), [1974](https://aignosi-wiki.atlassian.net/browse/SIENTIAPDE-1974) (Orchestrator), [1975](https://aignosi-wiki.atlassian.net/browse/SIENTIAPDE-1975) (Laborious).
 - **Referências:** [1879](https://aignosi-wiki.atlassian.net/browse/SIENTIAPDE-1879) (boas práticas OPC), [1569](https://aignosi-wiki.atlassian.net/browse/SIENTIAPDE-1569) (banco de tags / CRUD conectores).
-- **Branch:** `SIENTIAPDE-1972-opc-gateway-...` (repo `sientia-dataops-opc-ingestor`). ⚠️ ver §11 (convenção de nomes de branch × CI).
+- **Branch:** `feature/SIENTIAPDE-1972-opc-gateway-...` (repo `sientia-dataops-opc-ingestor`).
 - **Data:** 2026-07-13.
 
 ---
@@ -141,11 +141,14 @@ Lê agora, persiste no pipeline e devolve.
 ## 7. Gestão de certificados
 Reaproveita o 1569: `platform_certificates` (metadados) + MinIO (`streamlit-connectors`, `platform/certificates/`). O `OpcConnectionPool` baixa `client_cert`/`private_key` para **`emptyDir`/tmpfs** (root FS é read-only, §12) e passa ao `asyncua` com `Basic256Sha256`, espelhando `_create_opc_ua_client`. Cert de plataforma é único/compartilhado. **Questão de fronteira:** o bucket `streamlit-connectors` pertence ao app Streamlit; padrão de plataforma é bucket/secret scoped por serviço (§10/§12) — decidir se o Gateway lê desse bucket ou se ganha bucket `opc-gateway` próprio (ver §17).
 
-## 8. NATS como nova dependência de plataforma ⚠️
-Os cards e o brief exigem **NATS**. Porém os docs de plataforma dizem explicitamente: *"Do not include RabbitMQ/NATS unless a clear requirement arises from a new component"* (`helm-chart-air-gapped/03-database-storage/other-data-stores.md`; `requirements-checklist.md:106`), e o **Kafka** já é o streaming adotado (o próprio opc-ingestor usa Kafka). Um revisor vai questionar **NATS vs Kafka**.
+## 8. NATS como nova dependência de plataforma
+**Decisão: NATS** (definido pelo brief oficial `opc-gateway/topics.md` e confirmado pelo dono da feature, Vitor Pimentel — fonte mais atualizada). O padrão de subjects/queue groups do NATS casa com o comando de escrita ponto-a-ponto de baixa latência.
 
-- **Justificativa a registrar:** o padrão request/response leve, subjects e queue groups do NATS casam com comando de escrita ponto-a-ponto de baixa latência; é o que o brief define. (Alternativa Kafka: possível, mas o card fixa NATS.)
-- **Ônus de onboarding (o Gateway é o "novo componente" que justifica o NATS):** subchart Helm + versão pinada (sem `latest`), imagem no bundle air-gapped (Trivy/Cosign), entrada nos perfis de sizing, `NetworkPolicy` de egress no `sientia-core`, secrets de credencial via `sientia-secrets-chart`, e decisão de HA/persistência (Core agora; JetStream depois exige storage).
+Nota de plataforma: os docs air-gapped diziam *"do not include RabbitMQ/NATS unless a clear requirement arises from a new component"* (`helm-chart-air-gapped/03-database-storage/other-data-stores.md`; `requirements-checklist.md:106`). O **OPC Gateway é exatamente esse novo componente** que cria o requisito — logo o NATS entra na plataforma como dependência de primeira classe. Ônus de onboarding a cumprir:
+- Subchart Helm + versão pinada (sem `latest`); imagem no bundle air-gapped (Trivy/Cosign).
+- Entrada nos perfis de sizing; `NetworkPolicy` de egress no `sientia-core`.
+- Credencial via `sientia-secrets-chart`.
+- HA/persistência: **Core NATS** agora (fire-and-forget, sem storage); JetStream depois exige storage/persistência.
 
 ## 9. Métricas e observabilidade
 - **Métricas (1973+1879):** `app_up`; sucesso/erro de escrita e leitura ativa; latência (histograma) de escrita e leitura ativa; tags na subscription; slots possuídos; conexões/desconexões; **status de escrita por modelo**; **valor por tag/modelo**; ciclos sem dado em subscription; **tipos de erro OPC**; **lag de leitura**. Prefixo sugerido `opc_gateway_*`; manter `app_up`.
@@ -166,7 +169,7 @@ Os cards e o brief exigem **NATS**. Porém os docs de plataforma dizem explicita
 - **MinIO:** padrão é bucket + user scoped por serviço; existe bucket `opc-ingestor`. Ver fronteira de certs em §7/§17.
 
 ## 11. Convenções de desenvolvimento
-- **Nome de branch dirige versionamento e é checado no CI:** `feature/`→minor, `fix/|hotfix/|bugfix/`→patch, `release/`→major, `rc/`, etc.; descrição em kebab-case; **branch fora do padrão falha o CI**. ⚠️ **A branch atual não tem prefixo `feature/`** → renomear para `feature/SIENTIAPDE-1972-...` antes de abrir PR (ver §17).
+- **Nome de branch dirige versionamento e é checado no CI:** `feature/`→minor, `fix/|hotfix/|bugfix/`→patch, `release/`→major, `rc/`, etc.; descrição em kebab-case; **branch fora do padrão falha o CI**. ✅ Branch já renomeada para `feature/SIENTIAPDE-1972-...`.
 - **Ticket-first:** referência do Jira no branch e no commit (ex.: `feat(gateway): ... (SIENTIAPDE-1973)`).
 - **Qualidade:** SonarQube (quality gate bloqueia merge — coverage, smells, security hotspots, duplicação, complexidade). Sem config numérica de tamanho de arquivo/função documentada além do 1879; qualidade delegada ao Sonar. Dockerfiles via `.hadolint.yaml`, centralizados em `sientia-container-images`, sem `latest`.
 - **Testes:** unit + integration (pytest) + E2E (Playwright quando aplicável).
@@ -211,17 +214,22 @@ Os cards e o brief exigem **NATS**. Porém os docs de plataforma dizem explicita
 - Funcional single-node contra o `opc_simulator`.
 
 ## 17. Questões em aberto
-1. **Nome da branch:** renomear para `feature/SIENTIAPDE-1972-...` (o padrão atual falha o CI de versionamento) — decidir antes do 1º PR.
-2. **Bucket de certs:** Gateway lê do bucket `streamlit-connectors` (do app 1569) ou ganha bucket `opc-gateway` scoped? (§7/§10)
+
+**Decididas:**
+- **Broker = NATS** (Core NATS agora; §8). Definido pelo brief/Vitor.
+- **Nome da branch:** renomeada para `feature/SIENTIAPDE-1972-...` ✅.
+
+**Em aberto:**
+1. **Bucket de certs:** Gateway lê do bucket `streamlit-connectors` (do app 1569) ou ganha bucket `opc-gateway` scoped? Default do spec: reutilizar o cert de plataforma do 1569 (MinIO+Mongo, conforme brief); confirmar scoping com plataforma. (§7/§10)
+2. **Provisionamento do NATS no air-gapped:** alinhar com plataforma o subchart/versão/sizing (a *escolha* já é NATS; falta o provisionamento). (§8)
 3. **Stack de migração de banco:** Flyway (docs helm) vs Alembic+SQLAlchemy (onboarding) para a coluna de write_status — confirmar.
-4. **NATS vs Kafka:** registrar justificativa formal (§8); confirmar com plataforma o provisionamento do broker no air-gapped.
-5. **Campo `metadata` em `connector_tags`** (subtask 1600): formalizar; tags de teste criadas com `metadata: {}` (pedido do Vitor).
-6. **Durabilidade da escrita:** Core NATS agora; reavaliar JetStream (TTL curto p/ descartar comando obsoleto) se perda em restart for problema.
-7. **Origem de `collection`/`frequency`/`active_read`** no JOIN do 1974: confirmar (pipeline vs config de modelo) ao detalhar o spec do Orchestrator.
-8. **Chamador do GRPC on-demand:** confirmar quem chama (Laborious/Orchestrator/UI-API) p/ dimensionar auth/limites.
+4. **Campo `metadata` em `connector_tags`** (subtask 1600): formalizar; tags de teste criadas com `metadata: {}` (pedido do Vitor).
+5. **Durabilidade da escrita:** Core NATS agora; reavaliar JetStream (TTL curto p/ descartar comando obsoleto) se perda em restart for problema.
+6. **Origem de `collection`/`frequency`/`active_read`** no JOIN do 1974: confirmar (pipeline vs config de modelo) ao detalhar o spec do Orchestrator.
+7. **Chamador do GRPC on-demand:** confirmar quem chama (Laborious/Orchestrator/UI-API) p/ dimensionar auth/limites.
 
 ## 18. Riscos
-- **Introdução de NATS** contraria a diretriz "não adicionar NATS sem requisito" — mitigado registrando o Gateway como o requisito e cumprindo o onboarding de plataforma (§8/§10).
+- **Introdução de NATS** (decidida): a diretriz antiga "não adicionar NATS sem requisito" é atendida — o Gateway é o requisito; resta cumprir o onboarding de plataforma (§8/§10).
 - **Escrita OPC não idempotente:** se migrar p/ JetStream (at-least-once), dedupe por `msg_id`.
 - **Relógio/OPC:** timestamps/NTP são fonte recorrente de bug (1879) — priorizar `monotonic` e flags de quality.
 - **Restrições reais do servidor OPC (Samarco):** block size 512/255, chars especiais em endereços, degradação de sessão, timeouts (publishing 2000ms, write 30000ms) — o pool/WriteEngine devem tolerar e medir.