Ir para o conteúdo

Regras Compartilhadas Obrigatórias

Decisões arquiteturais

  • Linguagem de implementação: Java.
  • O reator Maven atual exige Java 25 (maven.compiler.source/target em pom.xml). A aplicação Android possui um build Gradle separado e requisitos próprios; veja modules/federated-android-client/README.md.
  • Blockchain: Hyperledger Fabric.
  • Chaincodes: Java.
  • Comunicação federada — um único transporte MQTT, ponta a ponta (BL-259 reverteu BL-241/BL-242/BL-240/BL-254):
  • Ingestão de dados de treinamento (iot//mhub/) e protocolo de rodada (fl/ — RoundConfig, RoundFinalizationSignal, ClientUpdateMessage, ClientAnnouncePayload, ContractPublishedPayload, GlobalModelPublication) usam o mesmo MqttGateway/PahoMqttGateway (Eclipse Paho, módulo federated-containers) sobre broker real, em todo composition root — JVM/Docker e Android. Docker Compose e .env.example configuram MQTT sobre TLS/mTLS na porta 8883; tcp:// só deve ser usado quando explicitamente necessário em testes ou desenvolvimento local.
  • Histórico revertido: BL-241/BL-242 haviam migrado o protocolo de rodada para REST+SSE via RestSseGateway (módulo federated-digital-twin-broker) em todo composition root JVM/Docker, lado servidor em federated-rest-api (endpoints /api/rounds/publish//api/rounds/events); BL-240/BL-254 estenderam isso ao Android. A pedido explícito do usuário essa migração foi revertida por completo (BL-259): os dois endpoints e a config mTLS que os protegia (ADMIN_TLS_CLIENT_TRUSTSTORE) foram removidos. RestSseGateway e EmbeddedRestSseBroker foram incorporados a federated-digital-twin-broker, mas só para o salto interno do microbroker do gêmeo digital local (BL-243) — sem relação com o protocolo cliente↔servidor. TwinValidationDecisionMessage/ConsentStatusPayload/ClientRoundStatusPayload/AggregationStatusPayload nunca saíram de MQTT. Ver docs/components/18-rest-sse-gateway.md (registro histórico da transição e do revert).
  • O cliente nunca fala diretamente com o agregador (BL-242). ClientUpdateMessage é publicado pelo cliente no tópico "client-facing" (MqttTopics.clientUpdate(...)); só o ClientUpdateRelay do orquestrador (federated-orchestrator) assina esse tópico, e só ele republica o MESMO envelope assinado (sem re-assinar) no tópico "aggregator-facing" (MqttTopics.aggregatorClientUpdate(...)) — o único que MqttClientUpdateCollector assina. Ver docs/components/04-orchestrator.md.
  • APIs administrativas: REST/JSON com OpenAPI.
  • Persistência local implementada: SQLite (timeseries.db) via DataComponent, com registros separados por clientId e experimentId; PostgreSQL é uma opção futura, não o backend atual.
  • Dados de experimento: data/{client_id}/{experiment_id}.
  • Acesso a dados locais: sempre por DataComponent.
  • Caminhos de runtime de experimentos devem ser resolvidos por ExperimentRuntimePaths, permitindo execução local e Docker.
  • ML em Java: Tribuo, Smile, Spark MLlib, DJL, Deeplearning4j e ONNX Runtime Java, conforme compatibilidade do caso.
  • Android: Java puro para algoritmos leves ou LiteRT/TensorFlow Lite para modelos treináveis; ONNX Runtime Android apenas para inferência/validação.
  • MacBook Pro M4: Java puro em JDK macOS AArch64 ou DJL com target macos_apple_silicon_djl para execução/validação compatível.

Invariantes federados

  • Dados brutos nunca saem do cliente por padrão. A exceção opt-in do arquivo MQTT BL-306 persiste envelopes completos — inclusive observações iot//mhub/ — no MongoDB central somente quando MQTT_ARCHIVE_MONGODB_URI está configurada; esse modo exige autorização de tratamento, controle de acesso e política de retenção/exclusão documentados.
  • Todo treinamento exige contrato ativo e aceite válido.
  • O cliente só participa da agregação se passar no preflight estatístico.
  • Experimentos não devem ler dataset.csv diretamente; use DataComponent.
  • Todo TrainingLocalModel deve declarar MlAlgorithmSpec.
  • O cliente deve validar ClientMlRuntimeSupport antes de acessar a visão autorizada dos dados.
  • Updates locais devem ser representados por ClientUpdateMessage, com URI, hash, assinatura, métricas e perfil de dados.
  • Modelos globais candidatos devem ser representados por GlobalModelPublication, com URI/hash do modelo e URI/hash do relatório de agregação.
  • Modelos completos, updates locais e relatórios extensos ficam off-chain no Artifact Experiment Service; o ledger registra hash, URI, versão e decisão.
  • Quando o contrato definir EvaluationDatasetSpec, o dataset de teste pertence ao pesquisador/agregador, nunca é enviado aos clientes e deve avaliar modelos locais e modelo global candidato conforme flags do contrato.
  • O modelo global é candidato; ele deve ser validado localmente antes de atualizar o gêmeo digital.

Monitoramento

  • O monitor web executa na porta fixa 8088.
  • Se a porta estiver ocupada, scripts/run-admin-web.sh deve encerrar o processo que escuta em 8088.
  • O monitor expõe métricas federadas por rodada por RoundLearningMetrics, sem dados brutos.
  • O monitor expõe plano de tarefas por ComputePlanTaskMonitor.
  • O monitor expõe performances por PerformanceMonitorPoint.
  • No modo FEDERATED_CLIENT_EXECUTION_MODE=docker, clientes DT rodam em containers Docker e o monitor expõe ContainerRunSummary.
  • Containers de clientes devem montar somente o dataset do cliente/experimento necessário, nunca a raiz completa de data.
  • O monitor mantém um único modo de ledger, blockchain — LedgerMode não tem mais HYBRID nem memory puro (removidos; decisão explícita do usuário, ver histórico do backlog). Qualquer falha do Fabric agora bloqueia a operação; não há mais tolerância silenciosa.

Invariantes de segurança e integridade

  • ConsentStatus.ACCEPTED é o valor canônico. EXPCEPTED existe apenas por compatibilidade com ledger antigo. Código novo deve usar isAccepted().
  • Paths com entrada externa devem ser normalizados e verificados contra a raiz permitida.
  • LocalArtifactExperimentService deve impedir path traversal.
  • Hash SHA-256 de arquivos grandes deve usar streaming, não carregar arquivos grandes inteiros em memória.
  • Evidências auditáveis devem ser serializadas de forma determinística, com mapas e listas ordenadas quando afetam hash.
  • Seeds de seleção de clientes devem ser derivadas de SHA-256 de experimentId|contractHash|roundId.
  • Prazos de rodada devem vir de configuração, como ROUND_DEADLINE_SECONDS, com fallback documentado.
  • Strings de tópicos MQTT devem ser geradas por MqttTopics.*().
  • MqttEnvelope deve ser criado via MqttEnvelope.signed().
  • Receptores de envelope devem chamar envelope.verify(signatureService) e envelope.verifyPayloadIntegrity() antes de processar payload — verify() sozinho só prova que o hash foi assinado, nunca que o hash corresponde ao payload real transportado.
  • Novos tipos de payload de MqttEnvelope devem implementar br.ufma.lsdi.common.model.EvidenceProducing (evidenceString() determinístico, mapas/listas ordenados) para que verifyPayloadIntegrity() funcione.
  • InMemoryMqttGateway não é uma opção de implementação de produção — vive em federated-common/src/test/java (fixture de teste, test-jar classifier=tests). Código de produção deve usar PahoMqttGateway (módulo federated-containers, construído via MqttBrokerConfig.fromEnvironment()) para iot//mhub/ e para o protocolo de rodada fl/ — um único MqttGateway cobre os dois desde o revert do BL-259. RestSseGateway (módulo federated-digital-twin-broker) não é usado para fl/; é usado só internamente pelo salto do microbroker do gêmeo digital local (BL-243, ver docs/components/17-local-digital-twin-broker.md).
  • Consumidores de ClientUpdateMessage que dependem de coletar updates antes de agregar devem usar MqttClientUpdateCollector.awaitUpdates(...) (bloqueia até quórum ou deadline) — nunca updatesFor(...) isolado, que não espera entrega assíncrona do broker real.
  • O cliente nunca publica ClientUpdateMessage diretamente para o agregador — a entrega passa sempre pelo ClientUpdateRelay do orquestrador (BL-242). Todo composition root que constrói MqttClientUpdateCollector deve também construir e iniciar seu próprio ClientUpdateRelay.forExperiment(experimentId, gateway) sobre o mesmo MqttGateway, logo em seguida — republicação duplicada é inofensiva (MqttClientUpdateCollector deduplica por (experimentId, contractVersion, roundId, clientId)), depender de outro processo estar de pé para relayar não é aceitável.
  • Logs, diagnósticos e telas não devem exibir dados brutos ou identificadores sensíveis fora do permitido pelo contrato.

Git e versionamento

  • Este projeto deve permanecer em um repositório Git local configurado.
  • O agente deve usar a configuração Git local do repositório, nunca depender de configuração implícita ausente.
  • Ao concluir uma mudança não trivial, o agente deve criar um commit Git antes de encerrar a tarefa, a menos que o usuário peça explicitamente para não commitar ainda.
  • O commit deve representar um estado validado da mudança, com mensagem curta e descritiva.
  • Antes de commitar, o agente deve evitar incluir artefatos gerados, caches locais, datasets locais ou arquivos temporários.
  • Regras de segurança existentes continuam valendo: nunca usar comandos destrutivos como git reset --hard e nunca reverter mudanças do usuário sem autorização explícita.

Invariantes de conformidade LGPD (Lei nº 13.709/2018)

  • clientId real nunca deve ser gravado no ledger Fabric. Use ClientPseudonymService.pseudonym(clientId, experimentId) via FabricCliLedgerMirror. Em produção, LGPD_PSEUDONYM_SALT deve estar definido.
  • Todo experimento com dados pessoais identificáveis deve definir consentTermsUri no ExperimentContract.
  • Privacidade Diferencial é opcional como capacidade geral do framework, mas experimentos específicos podem torná-la obrigatória por requisito científico ou regulatório. No ECG5000 (dado sensível de saúde), o contrato e os hiperparâmetros padrão devem manter dp_noise_multiplier > 0 e PrivacyPolicy(true, clipNorm, noiseMultiplier, ...). A classe DifferentialPrivacy.clipAndNoise() só é invocada quando dpNoiseMultiplier > 0.
  • O monitor web deve ser executado com TLS ativo (ADMIN_TLS_KEYSTORE) em ambientes que processem dados pessoais reais.
  • ArtifactRetentionPolicy deve ser aplicada ao encerrar experimentos — AdminMonitoringService.enforceExpiredContracts() é chamado automaticamente no bootstrap do monitor.
  • AggregationReport.clientWeights e clientEvaluationMetrics não devem ser incluídos em saídas públicas sem pseudonimização prévia das chaves.
  • Consulte .agent-config/rag/chunks/chunk-012-lgpd.md e os documentos de Fabric e cliente antes de modificar fluxos de clientId, artefatos, ledger ou consentimento.

TDD — Test-Driven Development (obrigatório)

Todo desenvolvimento de código executável no projeto segue o ciclo TDD:

Ciclo Red → Green → Refactor:

  1. Red — Escreva o teste que descreve o comportamento desejado antes de escrever a implementação. O teste deve falhar por razão legítima (lógica ausente, não por erro de compilação).
  2. Green — Escreva o mínimo de código necessário para o teste passar. Não antecipe abstrações.
  3. Refactor — Melhore o código (elimine duplicações, melhore nomes, extraia métodos) sem quebrar os testes existentes.

Regras TDD obrigatórias:

  • Nenhuma classe ou método de produção novo sem pelo menos um caso de teste correspondente em ArchitectureComponentTestSuite ou arquivo de teste dedicado.
  • Testes novos devem ser adicionados ao passo setUp() da ArchitectureComponentTestSuite (ou arquivo equivalente) antes da implementação.
  • O teste deve descrever o comportamento esperado, não os detalhes internos da implementação (teste de caixa preta).
  • Cada private void test*() cobre um comportamento coeso e independente — não um "super teste" com múltiplos cenários misturados.
  • Asserts devem ter mensagem descritiva: assertEquals(expected, actual, "motivo da falha").
  • Casos de borda obrigatórios: entrada vazia/nula, valores-limite, falhas esperadas (exceções), comportamento idempotente.
  • Para código de segurança (assinaturas, hashes, path traversal, pseudonimização): teste do caminho feliz e do caminho de falha.
  • Não escrever testes que dependem de ordem de execução ou de estado global entre casos.

Onde ficam os testes:

Tipo Localização
Testes de componente e integração modules/federated-system-tests/src/main/java/br/ufma/lsdi/tests/ArchitectureComponentTestSuite.java
Testes de experimento ponta a ponta Mesma suíte, método testHarExperimentEndToEnd, testEcgExperimentEndToEnd etc.
Testes unitários isolados (futuro) src/test/java/ no módulo correspondente (JUnit 5)

Execução:

sh scripts/run-tests.sh
# Deve mostrar PASS para todos os 24+ casos antes de qualquer commit

O agente não deve criar ou alterar código de produção sem: 1. Mostrar o teste que será adicionado/modificado 2. Confirmar que o teste falha sem a implementação (Red) 3. Implementar o mínimo para passar (Green) 4. Refatorar se necessário (Refactor) 5. Confirmar sh scripts/run-tests.sh passa ao final

Não reintroduzir

Não reintroduza como implementação principal:

  • Python;
  • PyTorch como API de treinamento;
  • scikit-learn;
  • Flower;
  • NVIDIA FLARE;
  • gRPC como comunicação federada;
  • chaincode em Go, Node.js, TypeScript ou JavaScript;
  • Great Expectations, Pandera, Evidently, Alibi Detect ou DVC como dependências centrais.

Essas tecnologias podem aparecer apenas em seções históricas, comparativas ou de justificativa de substituição.