HDT-AF¶
Aprendizagem Federada Confiável para Gêmeos Digitais¶
Doutorado — DCCMAPI - UFMA / LSDi José Daniel Pereira Ribeiro Filho josedaniel@lsdi.ufma.br
Contextualização¶
- Gêmeos Digitais (pacientes, dispositivos, processos, organizações) dependem de modelos de aprendizado de máquina treinados sobre dados contínuos, sensíveis e heterogêneos — sinais fisiológicos, comportamentais ou de processo, atrelados à instância física que representam.
- Cada gêmeo pertence a um dono distinto — não há um único detentor dos dados capaz de simplesmente reuni-los para treinar um modelo único.
- A Aprendizagem Federada (FL) surge como resposta natural: treina modelos colaborativos sem centralizar dados brutos.
- Mas frameworks de FL consolidados (Flower, NVIDIA FLARE, IBM FL, Substra, Fed-BioMed) tratam governança, proveniência e auditabilidade como preocupações extrínsecas — resolvidas fora do protocolo, por configuração de aplicação, não por invariante estrutural.
Problemática (na perspectiva dos Gêmeos Digitais)¶
- Cada Gêmeo Digital (dispositivo, paciente, processo ou organização) gera continuamente dados locais sensíveis e heterogêneos, atrelados à instância física que representa.
- Evoluir os modelos que sustentam esses gêmeos exige aprendizado colaborativo entre vários deles — mas centralizar os dados brutos de cada gêmeo fere a soberania de quem os gerou e pode violar LGPD e governança.
- Como cada gêmeo tem um "dono" distinto, a colaboração exige, ao mesmo tempo:
- soberania local dos dados de cada gêmeo;
- rastreabilidade técnica de como cada gêmeo contribuiu para o modelo compartilhado;
- validade científica dos resultados, apesar da heterogeneidade entre gêmeos.
- Lacuna central: nenhum framework de FL existente une contrato pré-rodada verificável, auditoria blockchain imutável e isolamento real de código não confiável num único protocolo coeso.
Justificativa¶
- Gêmeos digitais de saúde e comportamento humano operam sobre dados pessoais e sensíveis (Art. 5º, II da LGPD) — a ausência de governança estrutural não é só um risco técnico, é um risco de conformidade legal.
- Depender de configuração correta (e não de invariante de protocolo) para proteger dados brutos, autenticar participantes e auditar decisões deixa a segurança do sistema tão forte quanto a disciplina operacional de quem o opera — um ponto único de falha humana.
- A falta de confiança verificável entre participantes é uma barreira real de adoção de FL em domínios regulados (saúde, indústria), onde auditabilidade e responsabilização não são opcionais.
- Contribuição pretendida: uma metodologia — não apenas um algoritmo — que eleva contrato, soberania de dados, transporte autenticado, auditoria imutável e isolamento de processo a invariantes estruturais do protocolo, com uma implementação de referência aberta e reprodutível.
A proposta¶
O HDT-AF é uma arquitetura de aprendizagem federada confiável para gêmeos digitais.
Permite treinar modelos colaborativos sem centralizar dados brutos, combinando:
- Contrato de experimento formal e obrigatório
- Execução local verificável no cliente
- Agregação robusta com quórum
- Auditoria em Hyperledger Fabric
- Comunicação federada — MQTT 5 ponta a ponta, para ingestão de dados e para o protocolo de rodada (cliente↔orquestrador); o cliente nunca fala com o agregador — o orquestrador relaya os updates e chama o agregador (função pura, sem I/O) diretamente
Uma metodologia inovadora para FL em Gêmeos Digitais¶
O HDT-AF trata confiança, governança e soberania de dados como requisitos de primeira classe do processo federado — não só novos algoritmos de agregação:
- Contrato formal e obrigatório rege dados, código, agregação e auditoria antes de cada rodada
- Governança nativa em blockchain: contrato, consentimento, evidência e modelo global viram ativos imutáveis
- Soberania de dados por construção:
DataComponentcomo único acesso local é invariante de código — e só devolve o que o contrato autoriza, de um catálogo fechado de tipos (DataTypeCatalog, BL-245) - Transporte federado real e seguro (mTLS + assinatura) — sensores e dispositivos físicos como participantes de fato
Papéis do sistema (C4 Context)¶
| Papel | Responsabilidade |
|---|---|
| Pesquisador | Define o experimento e monitora rodadas (Monitor Web) |
| Cliente | Consentimento + dataset local do nó (DataComponent) |
| Auditor | Verifica evidências e hashes no ledger Fabric |
Separação por desenho: quem autoriza o dado ≠ quem quer o resultado ≠ quem audita — soberania local + governança independente.
⚠️ Hoje é conceitual (C4 Context) — o Monitor Web ainda não tem RBAC por papel.
Fluxo de um experimento¶

Componentes principais¶
| Componente | Papel |
|---|---|
| Pesquisador | Define objetivo, desenho experimental, métricas, código de treino e contrato |
| Contrato de experimento | Formaliza dados permitidos, código, aceite, políticas, métricas, agregação e auditoria |
| Cliente federado | Aceita contrato, resolve dados via DataComponent, roda preflight e treina localmente |
| DataComponent | Único caminho de acesso a data/{client_id}/{experiment_id}; authorizedTrainingView(...) filtra pelo contrato (BL-245) |
Componentes principais (cont.)¶
| Componente | Papel |
|---|---|
| Orquestrador | Coordena contrato, seleção de clientes, rodadas e configuração federada; único caminho do update local até o agregador (ClientUpdateRelay, BL-242); chama o agregador diretamente e publica/registra o resultado (BL-244) |
| Agregador | Valida updates, aplica quórum, rejeita outliers, gera modelo global candidato — função pura, sem I/O (BL-244) |
| Artifact Experiment Service | Deve ser apenas staging temporário de artefatos durante a rodada, com remoção após confirmação do commit no ledger; a implementação ainda mantém cópias |
| Hyperledger Fabric | Armazenamento permanente único desejado para o núcleo federado: contratos, consentimentos, eventos, updates/modelos e metadados de auditoria |
Componentes principais (cont. 2)¶
| Componente | Papel |
|---|---|
| MQTT (Eclipse Paho) | Barramento real para ingestão de dados (iot//mhub/) e para o protocolo de rodada (config/updates/modelo), em todo composition root JVM/Docker e Android (BL-259 reverteu a migração para REST+SSE do BL-240/BL-241/BL-242/BL-254) |
| ClientUpdateRelay (BL-242) | Único caminho do update local ao agregador — o cliente publica só no orquestrador, que relaya (mesmo envelope assinado, sem re-assinar) e, a partir daí, chama o agregador direto em Java (BL-244) |
| Monitor Web | Contratos, consentimentos, rodadas, métricas, assets, tarefas e containers; deploy dinâmico de experimentos |
| Empacotador de Experimentos | Formato ExperimentPackage v1 (.zip) para implantar experimentos sem recompilar |
| Gêmeo Digital Local (broker embarcado) | Interface local de acesso ao gêmeo digital (ADR-002) — broker HTTP+SSE embarcado (BL-243) que aciona o cliente e decide PROMOTE/REJECT/DEFER do modelo candidato |
Assets da Blockchain (Hyperledger Fabric)¶
Registrados imutavelmente no World State via chaincode federated-governance:
| Asset | Descrição / Papel no Sistema |
|---|---|
| ExperimentContractAsset | Contrato formal do experimento (status, validade, política, URI e hash SHA-256) |
| TrainingCodeAsset | Código de treino autorizado (hash do JAR, entrypoint, manifesto e assinatura) |
| ClientConsentAsset | Decisão de consentimento do cliente federado (ACCEPTED, REJECTED, REVOKED) |
Assets da Blockchain (cont.)¶
| Asset | Descrição / Papel no Sistema |
|---|---|
| DatasetEvidenceAsset | Evidência de integridade do dataset local (hashes de dataset.csv e metadata.json; sem dados brutos) |
| AuditEventAsset | Registros auditáveis append-only de eventos de rodada, preflight e submissão de updates |
| GlobalModelAsset | Versão do modelo global candidato, pesos e métricas registrados no Fabric |
Arquitetura em camadas¶
Núcleo Federado — detalhe interno¶

Cliente Federado — detalhe interno¶

Pipeline de simulação de coleta de dados¶

Técnicas de segurança empregadas¶
- Cifragem & Autenticação Mútua: TLS 1.3 + mTLS (certificados X.509) no barramento MQTT.
- Integridade de Payload (HMAC-SHA256): Assinatura criptográfica com chave secreta que valida a autenticidade da origem e garante que as observações não foram adulteradas ou injetadas por terceiros.
- Providência Estrutural (BL-091):
MqttTimeSeriesIngestoré o único escritor de produção detimeseries.db— presença de dados na store já comprova proveniência MQTT, sem checagem de runtime nem bypass possível. - Auditoria On-Chain: Registro imutável dos hashes SHA-256 dos updates no Hyperledger Fabric.
Ciclo de vida (status) do experimento¶

Status do cliente por rodada¶

Consentimento do usuário (LGPD)¶

Diagrama de componentes simplificado¶

Diagrama de containers (Docker)¶

Fluxo de simulação — MQTT + Docker + Fabric¶

Invariantes obrigatórias¶
- Java-only. Ingestão de dados (
iot//mhub/) e protocolo de rodada (fl/, cliente↔orquestrador): MQTT 5 (TLS/mTLS), em todo composition root — JVM/Docker e Android. (BL-241/BL-242/BL-240/BL-254 haviam migrado o protocolo de rodada para REST+SSE; revertido pelo BL-259 a pedido explícito do usuário.) - O cliente nunca fala diretamente com o agregador (BL-242) — só publica no orquestrador; o
ClientUpdateRelayé o único caminho até o agregador, sem re-assinar o envelope. - O agregador não acessa MQTT, Artifact Service nem Fabric (BL-244) — é uma função pura chamada diretamente pelo orquestrador, que também publica o resultado e registra os hashes.
- Hyperledger Fabric como armazenamento permanente único do núcleo federado e camada de auditoria/governança. Artefatos externos são apenas staging temporário e devem ser removidos após confirmação do commit no ledger.
DataComponenté o único caminho de acesso aos dados locais do experimento, e só devolve o que o contrato autoriza (authorizedTrainingView(...), BL-245).- Os tipos de dado do contrato pertencem a um vocabulário fechado (
DataTypeCatalog,federated-common) — não são texto livre;prohibitedFieldstem precedência sobreallowedObservationCodes(BL-245). - Nenhum dado bruto sai do cliente federado.
- Nenhum treinamento ocorre sem:
- contrato aceito;
- preflight válido;
- compatibilidade de runtime verificada.
- O gêmeo digital só é acessado via o broker HTTP+SSE embarcado (loopback, ADR-002, BL-243) — nunca exposto fora do processo/container do cliente.
Estratégias de seleção de clientes¶
Implementadas em federated-orchestrator, escolhidas por rodada via RoundCoordinator (hiperparâmetro participation_strategy):
| Estratégia | Resumo |
|---|---|
AllAccepted (padrão)all_accepted |
Todos os aceitos participam a cada rodada — ideal para poucos clientes (< 100) |
RandomSampledrandom_sampled:fraction=F |
Amostra uma fração por rodada; seed reprodutível baseSeed·31 + roundId |
RoundRobinround_robin:window=N |
Rotaciona janelas de clientes; janela (roundId-1) % numWindows — participação equitativa |
Todas garantem o quórum mínimo do contrato na seleção (SelectionStrategyCatalog).
Estratégias de agregação¶
Implementadas em Java puro no federated-aggregator:
- FedAvg
- FedProx
- FedMedian
- TrimmedMean
- Krum
- FedAdam
Todas com validação de quorum e rejeição de outliers antes de gerar o modelo global candidato.
Quórum: duas checagens distintas¶
"Aplicar quórum" não é responsabilidade de um componente só — são duas checagens diferentes, sobre populações diferentes, em estágios diferentes:
-
Quórum de participação — Orquestrador (
RoundClientSelector), antes de iniciar a rodadaclientes aceitos ≥ minimumClients— se falhar, lançaQUORUM_NOT_REACHEDe a rodada nem começa -
Quórum do resultado — Agregador (
FedAvgAggregationService), depois de coletar os updatesupdates recebidos ≥ minimumClients— se falhar, o modelo ficaREJECTED(não é promovido)
Ambas usam o mesmo AggregationPolicy.minimumClients(), mas quem aceitou ≠ quem enviou update.
Privacidade e conformidade (LGPD)¶
Conformidade LGPD parcialmente implementada:
- Pseudonimização on-chain (
LGPD_PSEUDONYM_SALT) - TLS no monitor web (
ADMIN_TLS_KEYSTORE) - TLS 1.3/mTLS no broker MQTT (mosquitto só expõe
8883,require_certificate true) - Política de retenção de artefatos (
validTo) consentTermsMarkdownlegível no contrato de experimento- Privacidade diferencial aplicada no experimento de ECG (dado sensível de saúde)
Experimentos de pesquisa disponíveis¶
| ID | Dataset | Tipo | LGPD |
|---|---|---|---|
exp-har-smartphones-001 |
UCI HAR Smartphones (21 sujeitos) | Classificação multi-classe (6 atividades) — MLP | Dado pessoal |
exp-ecg5000-anomaly-001 |
ECG5000 (UCR Archive) | Detecção de anomalias — MLP Autoencoder | Dado sensível de saúde |
Especificação de Empacotamento (Código & Datasets)¶
Permite implantar novos experimentos e dados de simulação sem recompilar a plataforma:
- Pacote de Experimento (
{id}.hdtpkg.zip): package-descriptor.json: Formato v1,experimentId,contractVersion,sessionFactoryClass.code/{id}.jar: Bytecode compilado do modelo de treinamento local.manifest.yaml/specification.md: Metadados e especificação científica do experimento.-
SHA256SUMS: Hash de integridade SHA-256 de todos os arquivos contidos. -
Pacote de Dados de Simulação (
{id}-simdata.hdtpkg.zip): simulation-descriptor.json:packageFormatVersion: 1,experimentId,csvEntry.-
dataset/data.csv: Séries temporais de observações para replay via MQTT. -
Validação & Segurança no Desempacotamento:
- Proteção contra Zip Slip (
../), limite de descompressão (Zip Bomb) e checagem determinística de hashes.
Monitor Web¶
Aplicação web na porta 8088 (HTTP/HTTPS), com:
- Contratos, consentimentos e evidências por cliente
- Rodadas, gráficos de desempenho e configuração de hiperparâmetros
- Explorer de blockchain por tipo de asset e eventos de auditoria
- Deploy dinâmico de novos experimentos via upload de pacote (
.hdtpkg.zip) - Modo de ledger:
blockchain( Fabric sempre obrigatório) - Execução de clientes em modo Docker, com logs e artefatos expostos em
logs/<nome>/
Stack tecnológica¶
- Java 25 + Maven
- Hyperledger Fabric 2.5+ (chaincode
federated-governance) - MQTT 5 — Eclipse Paho (
federated-containers), ingestão de dados e protocolo de rodada (BL-259 reverteu a migração para REST+SSE do BL-240/BL-241/BL-242/BL-254) - HTTP+SSE embarcado — broker do gêmeo digital local (
federated-digital-twin-broker, ADR-002, BL-243; substituiu o Moquette/MQTT interno) —federated-digital-twin-broker/java.net.http.HttpClientsobrevive só para este salto interno - HMAC-SHA256 para integridade de payloads e evidências
- ML federado em Java puro (FedAvg, FedProx, FedMedian, TrimmedMean, Krum, FedAdam)
sh scripts/compile.sh # build (Maven obrigatório)
sh scripts/run-admin-web.sh # monitor web :8088
sh scripts/run-tests.sh # suíte de testes
Estado atual (MVP funcional)¶
- ✅ Compila e executa os dois experimentos reais (HAR, ECG5000)
- ✅ Ingestão de dados via broker MQTT real (Eclipse Paho)
- ✅ Chaincode
federated-governancedeployado (Org1 + Org2,federated-channel) - ✅ Monitor web com TLS opcional e deploy dinâmico de experimentos
Estado atual (cont.)¶
- ✅ Modo de ledger:
blockchain(único suportado — Fabric sempre obrigatório) - ✅ TLS 1.3/mTLS no broker MQTT (BL-016)
- ✅ Interface local de acesso ao gêmeo digital — broker HTTP+SSE embarcado (ADR-002, BL-238; migrado de MQTT/Moquette para HTTP+SSE interno no BL-243)
- ✅ Protocolo de rodada é MQTT-only em toda composition root — JVM/Docker e Android (BL-259
reverteu a migração para REST+SSE do BL-240/BL-241/BL-242/BL-254, a pedido explícito do
usuário);
federated-digital-twin-brokersobrevive só para o salto interno do BL-243 - ✅ Cliente nunca fala diretamente com o agregador —
ClientUpdateRelayno orquestrador é o único caminho do update local até o agregador (BL-242) - ✅ Agregador é função pura — não acessa MQTT, Artifact Service nem Fabric; o orquestrador chama
aggregate(...)diretamente e publica/registra o resultado (AggregationResultPublisher, BL-244);DockerAggregatorDaemonApp(exp-ergonomic-risk-001) segue com transporte próprio, redesenho previsto numa entrega futura separada - ✅ Catálogo fechado de tipos de dados (
DataTypeCatalog,federated-common) — o contrato só aceita tipos da tabela;DataComponent.authorizedTrainingView(...)é o único método que devolve dados aoFederatedClientService;prohibitedFieldsagora é de fato aplicado (BL-245) - ⚠️ Deploy dinâmico de pacotes: risco de execução de código arbitrário aceito e documentado
Obrigado¶
HDT-AF — Aprendizagem Federada Confiável para Gêmeos Digitais Doutorado UFMA/LSDi — José Daniel
Documentação completa: docs/README.md
Base de conhecimento: .agent-config/rag/