Regras Compartilhadas Obrigatórias¶
Decisões arquiteturais¶
- Linguagem de implementação: Java.
- O reator Maven atual exige Java 25 (
maven.compiler.source/targetempom.xml). A aplicação Android possui um build Gradle separado e requisitos próprios; vejamodules/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 mesmoMqttGateway/PahoMqttGateway(Eclipse Paho, módulofederated-containers) sobre broker real, em todo composition root — JVM/Docker e Android. Docker Compose e.env.exampleconfiguram 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ódulofederated-digital-twin-broker) em todo composition root JVM/Docker, lado servidor emfederated-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.RestSseGatewayeEmbeddedRestSseBrokerforam incorporados afederated-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/AggregationStatusPayloadnunca saíram de MQTT. Verdocs/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ó oClientUpdateRelaydo 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 queMqttClientUpdateCollectorassina. Verdocs/components/04-orchestrator.md. - APIs administrativas: REST/JSON com OpenAPI.
- Persistência local implementada: SQLite (
timeseries.db) viaDataComponent, com registros separados porclientIdeexperimentId; 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_djlpara 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 quandoMQTT_ARCHIVE_MONGODB_URIestá 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.csvdiretamente; useDataComponent. - Todo
TrainingLocalModeldeve declararMlAlgorithmSpec. - O cliente deve validar
ClientMlRuntimeSupportantes 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.shdeve encerrar o processo que escuta em8088. - 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õeContainerRunSummary. - 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—LedgerModenão tem maisHYBRIDnemmemorypuro (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.EXPCEPTEDexiste apenas por compatibilidade com ledger antigo. Código novo deve usarisAccepted().- Paths com entrada externa devem ser normalizados e verificados contra a raiz permitida.
LocalArtifactExperimentServicedeve 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.*(). MqttEnvelopedeve ser criado viaMqttEnvelope.signed().- Receptores de envelope devem chamar
envelope.verify(signatureService)eenvelope.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
MqttEnvelopedevem implementarbr.ufma.lsdi.common.model.EvidenceProducing(evidenceString()determinístico, mapas/listas ordenados) para queverifyPayloadIntegrity()funcione. InMemoryMqttGatewaynão é uma opção de implementação de produção — vive emfederated-common/src/test/java(fixture de teste, test-jarclassifier=tests). Código de produção deve usarPahoMqttGateway(módulofederated-containers, construído viaMqttBrokerConfig.fromEnvironment()) paraiot//mhub/e para o protocolo de rodadafl/— um únicoMqttGatewaycobre os dois desde o revert do BL-259.RestSseGateway(módulofederated-digital-twin-broker) não é usado parafl/; é usado só internamente pelo salto do microbroker do gêmeo digital local (BL-243, verdocs/components/17-local-digital-twin-broker.md).- Consumidores de
ClientUpdateMessageque dependem de coletar updates antes de agregar devem usarMqttClientUpdateCollector.awaitUpdates(...)(bloqueia até quórum ou deadline) — nuncaupdatesFor(...)isolado, que não espera entrega assíncrona do broker real. - O cliente nunca publica
ClientUpdateMessagediretamente para o agregador — a entrega passa sempre peloClientUpdateRelaydo orquestrador (BL-242). Todo composition root que constróiMqttClientUpdateCollectordeve também construir e iniciar seu próprioClientUpdateRelay.forExperiment(experimentId, gateway)sobre o mesmoMqttGateway, logo em seguida — republicação duplicada é inofensiva (MqttClientUpdateCollectordeduplica 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 --harde nunca reverter mudanças do usuário sem autorização explícita.
Invariantes de conformidade LGPD (Lei nº 13.709/2018)¶
clientIdreal nunca deve ser gravado no ledger Fabric. UseClientPseudonymService.pseudonym(clientId, experimentId)viaFabricCliLedgerMirror. Em produção,LGPD_PSEUDONYM_SALTdeve estar definido.- Todo experimento com dados pessoais identificáveis deve definir
consentTermsUrinoExperimentContract. - 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 > 0ePrivacyPolicy(true, clipNorm, noiseMultiplier, ...). A classeDifferentialPrivacy.clipAndNoise()só é invocada quandodpNoiseMultiplier > 0. - O monitor web deve ser executado com TLS ativo (
ADMIN_TLS_KEYSTORE) em ambientes que processem dados pessoais reais. ArtifactRetentionPolicydeve ser aplicada ao encerrar experimentos —AdminMonitoringService.enforceExpiredContracts()é chamado automaticamente no bootstrap do monitor.AggregationReport.clientWeightseclientEvaluationMetricsnã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.mde os documentos de Fabric e cliente antes de modificar fluxos declientId, 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:
- 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).
- Green — Escreva o mínimo de código necessário para o teste passar. Não antecipe abstrações.
- 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
ArchitectureComponentTestSuiteou arquivo de teste dedicado. - Testes novos devem ser adicionados ao passo
setUp()daArchitectureComponentTestSuite(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:
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.