Implementação do RoomOperator com Gestão Declarativa de Estado para Salas

[invictvs-k]

Contexto

Implementar o RoomOperator como um serviço externo, responsável por aplicar o estado desejado de uma Sala (RoomSpec), reconciliando continuamente até que o estado atual corresponda ao desejado. O Operator deve atuar de forma idempotente, auditável e tolerante a falhas, sem alterar as capacidades do host da Sala, que permanece neutro.

---

Principais Melhorias Incorporadas

• Versionamento do RoomSpec: Adicionar campos de versionamento e metadados ao spec para rastreabilidade e rollback.
• Fases transacionais de reconcile: Planejamento, pré-validação, execução, verificação e rollback.
• Circuit Breaker para dependências externas: Estratégia para tolerar falhas e evitar storms de retry.
• Idempotência robusta para artefatos: Fingerprint combinando nome, tipo, conteúdo, workspace e tags.
• Modo Dry-Run/Preview: Simulação das ações antes de aplicá-las.
• Observabilidade avançada: CorrelationId por reconciliação, logs estruturados, histórico de execuções, health checks.
• Validação contratual do RoomSpec: Schema enforcement e validação customizada.
• Suporte a múltiplas salas: Multi-tenancy configurável.
• Perfis de configuração (dev, staging, prod): Gerenciamento de ambientes.
• Auditoria/event sourcing: Registro imutável das ações do operador.
• Tratamento de erros parciais: Reconciliação continua mesmo com falhas em parte das ações.
• Controle de concorrência e rate limiting: Sem conflitos entre reconciliações e apply requests.

---

Entregáveis

1. Projeto RoomOperator (.NET 8 Console App)

   • Estrutura de pastas sugerida:
     • /operator/RoomOperator.csproj
     • /operator/appsettings.{env}.json
     • /operator/specs/<roomId>.room.yaml
     • /operator/src/: RoomSpec.cs, RoomState.cs, RoomOperatorService.cs, SignalRClient.cs, ArtifactsClient.cs, McpClient.cs, PoliciesClient.cs, DiffEngine.cs, OperatorHttpApi.cs, RoomSpecValidator.cs, AuditTrail.cs
   • Clients: SignalR, Artifacts, MCP, Policies, com injeção de token e circuit breaker.
   • DiffEngine: Cálculo de diffs determinísticos e geração de fingerprints para artefatos.
   • Loop de reconcile: Fases transacionais; periodicidade configurável; dry-run; tratamento de erros parciais; logs estruturados e correlationId.
   • API HTTP: POST /apply (dry-run ou efetivo), GET /status, GET /health, GET /audit.
   • Multi-room: Suporte via configuração.
   • Feature flags e perfis de ambiente.
   • Graceful shutdown e health checks.
   • Documentação: docs/room-operator.md com exemplos, variáveis, fluxo E2E, schema do RoomSpec.

2. Contratos e Schemas

   • RoomSpec versionado, schemas JSON/YAML e exemplos.
   • Mensagens de comando/evento do Operator com correlationId, phases e status.

3. Testes Automatizados (xUnit)

   • Cobertura: entidades, artefatos (seed/promote/update), policies, recursos/multi-room, dry-run, erros parciais, idempotência, retry/backoff, circuit breaker.
   • Casos realistas de resiliência e concorrência.

---

Plano de Implementação

Veja detalhes no prompt refinado incorporando as sugestões.

---

Labels

• enhancement

Observações Importantes

• O Operator deve ser desacoplado, tolerante a falhas, auditável, e nunca assumir comportamento "mágico" do host da sala.
• Priorizar fases MVP (reconcile core, validação, dry-run), depois versionamento, multi-room e observabilidade avançada.