Ir para o conteúdo

Auditoria Detalhada de Funcionalidades e Documentação — HDT-AF

Data: 2026-11-18
Escopo: Inspeção estática integral de código-fonte, build/POM/Gradle/npm, infraestrutura Docker/Fabric/scripts e especificações OpenAPI em todo o workspace (modules/, research/experiments/, deploy/, docker/, pom.xml, docs/), com identificação de funcionalidades implementadas, divergências entre código e documentação e achados de engenharia.

Limite de verificação: Auditoria estática conduzida sobre os arquivos reais do workspace em 2026-11-18 (incluindo alterações locais não commitadas referentes ao BL-334). A suíte Java/Maven não foi executada por ausência de mvn e JDK 25 no ambiente local.


1. Inventário Quantitativo Real do Workspace

Camada Localização Composição real observada
Reator Maven (Java 25) pom.xml 15 módulos de plataforma + 5 módulos de experimento + 2 módulos de benchmark = 22 módulos (exp-har-smartphones-001 entra via build-helper-maven-plugin, sem pom.xml próprio)
Aplicação Android (Gradle) modules/federated-android-client 3 subprojetos (:core, :app, :client-engine-plugin) + includeBuild("../../../hdt-mobile-apps") (br.ufma.lsdi:mdpl)
Frontend Web (npm/Vite) modules/federated-admin-web 10 arquivos JS/JSX em src/ (SPA desativada no roteamento principal do AdminWebServer desde BL-135)
Portal de Documentação modules/federated-docs Repositório independente MkDocs Material + Read the Docs (.readthedocs.yaml, mkdocs.yml, scripts/sync_docs.py, tests/)
Scripts Operacionais modules/scripts (scripts/) 21 scripts .sh
Chaincodes Fabric deploy/fabric/chaincode/federated-governance-java/ 19 arquivos Java (fabric-chaincode-shim:2.5.4, Gradle Shadow 9.0.0, Java 25), 3 @Contracts e 9 assets
Experimentos de Pesquisa research/experiments/* 6 diretórios (exp-ecg5000-anomaly-001, exp-ergonomic-risk-001, exp-har-smartphones-001, exp-mimic-v31-icu-mortality-001, exp-mnist-digits-001, exp-synthetic-smoke-001); exp-dt-federated-001 existe apenas como contrato bootstrap em AdminApplicationBootstrap

2. Mapa Detalhado de Funcionalidades Implementadas por Subsistema

2.1 Núcleo Compartilhado e Segurança (federated-common)

  • Tratamento de erros (br.ufma.lsdi.common): ErrorCode (17 códigos padronizados) e FederatedException.
  • Criptografia, assinatura e integridade (br.ufma.lsdi.common.crypto):
  • HmacSignatureService (identidades registradas e assinatura/verificação HMAC-SHA256);
  • X509SignatureService ("x509:{id}:{base64}", suporte a chaves RSA e EC) e X509SignatureServiceLoader (load, registerOwnIdentity, fromTrustAnchor, fromEnvironment via SIGNING_*);
  • CompositeSignatureService (roteamento por identidade entre X.509 e HMAC);
  • Hashing (sha256 para String, Path via stream e byte[]).
  • Compactação e ZIP seguro (br.ufma.lsdi.common.io.PackageZipSupport): leitura/escrita determinística com SHA256SUMS e proteção contra Zip Slip e Zip Bomb.
  • Serialização (br.ufma.lsdi.common.util): JsonCodec (Jackson ObjectMapper + JavaTimeModule) e VectorCodec.
  • Barramento MQTT (br.ufma.lsdi.common.mqtt):
  • MqttEnvelope<T> (signed, verify, verifyPayloadIntegrity), MqttPayloadCodec (Jackson ObjectMapper serializando os records em camelCase), MqttTopicMatcher, ClientSenderScope e DockerMqttEnvironment (injeção de env vars MQTT, mTLS e SIGNING_*, além de reescrita localhost/127.0.0.1 → host.docker.internal).
  • MqttTopics (tópicos fl/experiments/{id}/..., constantes wildcard *_WILDCARD / ALL_EXPERIMENT_*, tópicos locais MDPL mdpl/... e canais de artefato do gêmeo digital clientArtifact/globalModelPayload).
  • IotTopics (entityObservation, entityEvent, cddlService, cddlEventObjectDiscovered/Disconnected e wildcards por cliente).
  • Modelo de domínio (br.ufma.lsdi.common.model — 46 tipos): contratos (ExperimentContract, ExperimentSchedule, ParticipationPolicy, AggregationPolicy, PrivacyPolicy, EvaluationDatasetSpec, DataSchemaSpec), vocabulário fechado de tipos (DataTypeCatalog com 21 DataTypeSpec, DataFieldSpec), rodadas e atualizações (RoundConfig com 13 campos incluindo AlgorithmSelection, RoundFinalizationSignal, ClientUpdateMessage, GlobalModelPublication, RemoteAggregationRequest, TwinValidationDecisionMessage) e 11 implementações de EvidenceProducing.

2.2 SDK de Experimentos e Empacotamento (federated-experiment-sdk, federated-experiment-packager, federated-package-experiment-service)

  • federated-experiment-sdk (12 arquivos):
  • Contratos de extensão TrainingLocalModel (algorithmSpec(), execute(TrainingContext) throws TrainingException), TrainingContext (11 campos), TrainingResult (12 campos + construtor legado de 8 args), TrainingStatus (5 constantes: SUCCESS, FAILED, PREFLIGHT_FAILED, COMPLETED_NOT_SUBMITTED, UPDATE_SUBMITTED), ExperimentSession e ExperimentSessionFactory (com forExperiment(String) para clonagem dinâmica).
  • Catálogo de algoritmos e runtimes: MlAlgorithmSpec (10 campos), MlRuntimeTarget (7 alvos, incluindo ANDROID_ONNX_RUNTIME e MACOS_APPLE_SILICON_DJL) e MlAlgorithmCatalog (8 especificações prontas).
  • Resolução portável de diretórios (ExperimentRuntimePaths) com precedência System.getProperty > System.getenv > padrão (var/deployed-experiments, var/deployed-datasets, var/deployed-client-packages, etc.), leitura de termos (ConsentTermsMarkdownReader) e diagnóstico de rodada (RoundEvaluationReport).
  • federated-experiment-packager (15 arquivos):
  • Pacotes de experimento .hdtpkg.zip (ExperimentPackageDescriptor via Jackson, ExperimentPackageWriter validando codeJarEntry via JarFile, ExperimentPackageReader, ExperimentPackagerCli).
  • Pacotes de cliente Android .hdtclient.zip (ClientPackageDescriptor via Jackson exigindo code/*.dex, assinatura Ed25519 via ClientPackageSignature, ClientPackageWriter, ClientPackageReader exigindo SHA256SUMS e cabeçalho dex\n, ClientPackagePackagerCli gravando code/client-engine.dex).
  • Pacotes de simulação .hdtsim.zip (CsvTabularDatasetSchema, DatasetPartitioner com estratégias sequential_chunk e random_shuffle_seed + roundSlice, SimulationDataPackageDescriptor/Writer/Reader/Cli).
  • federated-package-experiment-service (3 arquivos):
  • ArtifactReference(uri, hash, sizeBytes), LocalArtifactExperimentService (store, read(ArtifactReference) com resolução cross-mount resolveAcrossForeignRoot do BL-117, readIfPresent(namespace, filename), sanitização por substituição _ em caracteres fora da whitelist e private resolveSecure) e ArtifactRetentionPolicy (expurgo pós-validTo).

2.3 Dados Locais, Ingestão MQTT e Privacidade (federated-local-cdm — 27 arquivos)

  • DataComponent & SqliteTimeSeriesStore (atualizados no BL-334):
  • DataComponent mantém cache thread-safe de defaultStore via double-checked locking; expõe subscribeToMqttSource, awaitIngestion, awaitMqttDataAndMaterialize, materializeDatasetFromStore, loadLocalCdmRepository, authorizedTrainingView (estático), consultas de séries temporais e helpers centralizados de Privacidade Diferencial (differentialPrivacyConfig*, applyDifferentialPrivacyIfConfigured*).
  • SqliteTimeSeriesStore implementa TimeSeriesStore e AutoCloseable, utilizando WriterResources (conexão JDBC persistente + 3 PreparedStatements em cache, transações explícitas com autoCommit=false, SQLiteConfig com BUSY_TIMEOUT_MS=5000, SynchronousMode.NORMAL e TempStore.MEMORY), limpeza via java.lang.ref.Cleaner, recuperação após SQLException e reabertura transparente em novas escritas.
  • Persistência de artefatos de modelo local/global em {dataRoot}/model_artifacts.db via ModelArtifactStore (SQLite WAL).
  • Ingestão, Perfilamento e Preflight:
  • MqttTimeSeriesIngestor assina 4 filtros de tópico (allObservationsForClient, allEventsForClient, cddlServicesForClient, cddlAllEvents) e registra IngestionDiagnostics / IngestionAudit.
  • DataProfileService produz LocalDataProfile e DefaultPreflightValidator avalia 5 checagens (minimum_examples_per_client, minimum_positive_examples_per_client, minimum_entities_per_client, expected_positive_rate_range, missingness_threshold:{code}), gerando PreflightResult (eligibleForTraining()).
  • Privacidade Diferencial (BL-081): DifferentialPrivacyConfig, DifferentialPrivacyConfigReader (leitura XML segura contra XXE) e DifferentialPrivacyMath (clip L2 + ruído gaussiano + alerta [DP-UTILIDADE] quando ruído domina o sinal).

2.4 Ciclo Federado, Gêmeo Digital Local e Inferência

  • Cliente Federado (federated-client — 39 + 5 arquivos):
  • FederatedClientService: valida contrato ativo, consentimento, seleção em selected_clients, compatibilidade de AlgorithmSelection e ClientMlRuntimeSupport, preflight (registrando hash), visão autorizada em authorized_view.csv, modelo global FedProx, execução do TrainingLocalModel, consistência de métricas/OutputPolicy, verificação de hash pré-DP, aplicação de DP, upload via ClientArtifactChannel (LocalDiskArtifactChannel ou TwinArtifactChannel) e registro de hashes de update e métricas no ledger.
  • FederatedDockerClientExecutor: exporta timeseries.db isolado por cliente/experimento (ClientTimeSeriesExporter), monta /app/lib:ro e ambiente MQTT/mTLS, executa container efêmero, lê result.properties e cria symlinks em logs/<containerName>/{data,model}.
  • Núcleo portável Android (br.ufma.lsdi.fedandroid.core): ConsentManager, ContractPublishedGate, ObservationStore/TabularAssembler, MultiExperimentRoundCoordinator, RoundLifecycle, LocalTrainer (MlpNetwork), ClientPackageVerifier, MdplTrainingPluginResolver e ponte Android br.ufma.lsdi.fedandroid.net (5 classes compiladas pelo :app).
  • Orquestrador (federated-orchestrator — 20 arquivos):
  • RoundCoordinator, AllAcceptedClientsStrategy, RandomSampledClientsStrategy, RoundRobinStrategy, FederatedRoundStrategyFactory, SelectionStrategyCatalog, ExternalParticipantRoundTrigger.
  • ClientUpdateRelay (relay obrigatório clientUpdate → aggregatorClientUpdate), ClientArtifactIngestor, MqttClientUpdateCollector, ClientUpdateResolver, AggregationResultPublisher, RemoteAggregatorClient (HTTP POST /aggregate), TwinValidationDecisionIngestor e RoundFlowPublisher (atualmente não conectado aos fluxos principais).
  • Agregador (federated-aggregator — 12 arquivos):
  • 6 algoritmos configuráveis via AggregationStrategyFactory: fedavg, fedmedian, trimmed_mean (poda por norma L2), krum/multikrum, fedadam e fedyogi (via FedAdamAggregationStrategy.fedYogi()).
  • FedAvgAggregationService realiza validação de escopo, duplicidade, assinatura, finitude, dimensão, norma, SHA-256 e quórum (AggregationQuorumException). Ainda preserva métodos/campos legados (aggregateFromMessages) e cópia antiga de MqttClientUpdateCollector.
  • Containers MQTT (federated-containers — 3 arquivos):
  • MqttBrokerConfig (sufixo UUID obrigatório), MqttTlsConfig (TLSv1.3, PKCS12) e PahoMqttGateway (MQTTv5 QoS 1, automaticReconnect, fallback host.docker.internal ↔ 127.0.0.1, re-assinatura em connectComplete).
  • Gêmeo Digital Local (federated-digital-twin-broker — 18 arquivos):
  • EmbeddedRestSseBroker / EmbeddedTwinBroker + RestSseGateway (BL-243: HTTP+SSE interno com backoff 500ms → 15s), DigitalTwinBridge (borda externa MQTT 5 com EnvelopeBoundaryGuard ↔ barramento interno HTTP+SSE abrindo 7 assinaturas internas totais quando TwinArtifactChannel é conectado), DigitalTwinClientCommandAdapter, DigitalTwinValidatorAdapter, BaselineComparisonModelValidator, ReferenceMetricHoldoutEvaluator e LocalDigitalTwinRuntime.
  • Serviço de Inferência (federated-model-inference — 14 arquivos):
  • Empacotamento .hdtmodel.zip (ModelPackageManifest/Writer/Reader, limite 2 MiB), persistência on-chain (FabricInferencePackageLedger chamando FederatedExperimentChaincode), LinearModelInference (linear-regression-v1, logistic-regression-v1) e servidor HTTP :8092 (GET /models, GET /models/{id}/package, POST /models, POST /infer, POST /infer/{id}, POST /infer/stream NDJSON, POST /infer/{id}/stream).

2.5 Governança Blockchain & Cliente Android

  • Hyperledger Fabric (deploy/fabric/chaincode/federated-governance-java/ + federated-chaincode):
  • Chaincode real em Java 25 (fabric-chaincode-shim:2.5.4, Gradle Shadow 9.0.0):
    • ExperimentContractSmartContract (9 transações);
    • ClientConsentSmartContract (6 transações, grava ACCEPTED e aceita legado EXPCEPTED);
    • FederatedExperimentSmartContract (18 transações, incluindo pacotes de inferência e assinaturas canônicas de 10 argumentos em registerLocalUpdateHash e registerGlobalModelVersion);
    • 9 tipos de asset (ExperimentContractAsset, TrainingCodeAsset, ClientConsentAsset, AuditEventAsset, DatasetEvidenceAsset, GlobalModelAsset, ClientUpdateAsset, InferencePackageAsset, InferencePackageMetadataAsset), 9 object types em LedgerConstants/StateKeys e 4 validadores em Validation.
  • Simuladores em memória (modules/federated-chaincode) e FabricGatewayLedgerMirror (SubmitOutcome: SUBMITTED, ALREADY_REGISTERED, FAILED) + FabricCliLedgerMirror legado.
  • Cliente Android (modules/federated-android-client):
  • 5 Activities (MainActivity, ConsentActivity, ExperimentDetailActivity, CollectedDataActivity, ExperimentMonitorActivity), 2 Foreground Services (FederatedMqttService, FederatedMdplInferenceEngineService), coleta CDDL/CDAL (gravada após consentimento ativo), EncryptedSharedPreferences, upload de artefatos por HTTP REST (RestRoundArtifactGateway), sincronização síncrona de consentimento (RestConsentSyncClient), carregamento dinâmico DEX Ed25519 via MdplClientPackageManager e fallback LocalTrainer (MlpNetwork).

2.6 Monitor Web, API REST, Simulador e Experimentos

  • Monitor & API REST (federated-rest-api — 71 arquivos):
  • AdminWebServer (7.714 linhas, JDK HttpServer/HttpsServer na porta 8088), AdminHtmlLayout (abas em PT-BR), AdminMonitoringService (2.389 linhas), AdminExperimentExecutor, IsolatedExperimentRunnerApp (BL-236 isolamento em subprocesso), DockerParticipantLaunchService, DockerParticipantDaemonRegistry, ClientDiscoveryService, AnonymousClientInstallationRegistry, CddlStatusRegistry, MqttTrafficMonitorService + MongoMqttMessageStore (BL-306), SimulationSession / SimulationRoundEngine / MqttClientDataFlowInjector (BL-246) e endurecimento de concorrência/SSE/locks (BL-334).
  • Simulador (federated-simulator — 8 arquivos): MqttDatasetReplaySimulator, HarMqttReplayAdapter, EcgMqttReplayAdapter, IotDatasetReplayApp e pacote br.ufma.lsdi.simulator.data (CsvDatasetSimulationSource, DatasetPartitioner, SimulationDataPackagePlayer).
  • Experimentos (research/experiments/*): 6 projetos ativos (exp-ecg5000-anomaly-001, exp-har-smartphones-001, exp-mimic-v31-icu-mortality-001, exp-mnist-digits-001, exp-ergonomic-risk-001, exp-synthetic-smoke-001) com sessões, modelos locais e adaptadores de simulação.

3. Achados de Engenharia Identificados (Código × Infraestrutura)

Estes achados permanecem no código/infraestrutura atual (não modificados por esta entrega documental) e passam a ser explicitados com transparência na documentação:

  1. FedAdam silencioso para HAR e ECG: HarFederatedSession e EcgFederatedSession invocam aggregator.aggregate(contract, roundConfig, updates) sem passar o vetor global anterior (currentGlobal = null), fazendo FedAdamAggregationStrategy.combine recair no fallback ponderado (FedAvg).
  2. Clamping ausente em HarMqttReplayAdapter e EcgMqttReplayAdapter: Apenas CsvDatasetSimulationSource utiliza DatasetPartitioner.roundSlice; os adaptadores HAR e ECG calculam (roundNumber - 1) * chunkSize sem clamp.
  3. RoundFlowPublisher não integrado: Criado em federated-orchestrator, mas RoundCoordinator e AggregationResultPublisher ainda publicam diretamente via MqttGateway.
  4. BaselineComparisonModelValidator acoplado ao LocalArtifactExperimentService: Lê e grava arquivos de modelo diretamente no serviço de artefatos em vez de operar apenas sobre payloads em memória do broker local.
  5. Divergências entre simuladores in-memory e chaincode Fabric real: ExperimentContractChaincode permite DRAFT -> REVOKED e rejeita PUBLISHED -> CLOSED (inverso de ExperimentContractSmartContract); FederatedExperimentChaincode aceita reescritas idênticas e não implementa as 4 transações de pacotes de inferência, enquanto FederatedExperimentSmartContract usa requireMissing (*_ALREADY_EXISTS).
  6. Inconsistências em AdminWebServer e OpenAPI:
  7. POST /api/experiments/{id}/simulation-config é interceptado pelo roteamento genérico /{command} antes da rota dedicada e devolve CommandResult;
  8. POST /experiments/{id}/clients/{clientId}/register está sombreado pela rota genérica de 5 segmentos clients;
  9. GET /datasets/deploy e GET /datasets não estão conectados no doHandle;
  10. POST /api/experiments/{id}/run-with-dataset e POST /experiments/{id}/run-with-dataset executam de forma síncrona sem runBoundedRoundAction;
  11. GET /api/experiments/{id}/containers/{name}/logs ignora ?tail= (fixo em 200 linhas);
  12. GET /openapi.json retorna resumo estático desatualizado (12 rotas);
  13. AdminWebServer.stop() não fecha MongoMqttMessageStore nem ClientUpdateRelay.
  14. Infraestrutura Docker & Build:
  15. docker/mosquitto/mosquitto.conf configura apenas listener 8883 (TLS 1.3 + mTLS); portas 1883 e 9001 no Compose/VM não possuem listeners ativos no broker;
  16. Serviço postgres nos arquivos Compose (5432/15432) não possui consumidor Java (Local CDM usa SQLite);
  17. docker-compose.yml raiz não injeta FABRIC_GATEWAY_*, não monta credenciais Fabric nem entra em fabric_test, e referencia DockerClientSimulationApp/FederatedSimulationApp inexistentes;
  18. docker/docker-compose.vm.yml define HDT_AF_RESEARCH_ROOT=/app/research, mas não monta ./research:/app/research:ro;
  19. modules/federated-common/src/main/resources/logback.xml não existe no checkout;
  20. pom.xml dos consumidores federated-rest-api e federated-system-tests ainda lista o diretório inexistente exp-dt-federated-001/src/main/java, e o pom.xml raiz declara dependências vestigiais de Moquette/Paho v3;
  21. FEDERATED_CLIENT_EXECUTION_MODE e MIMIC_V31_DATASET são variáveis obsoletas não lidas pelo código Java;
  22. exp-mimic, exp-mnist e exp-ergonomic-risk possuem research.xml incompatível com research-experiment.xsd, e EcgFederatedSession/MimicV31FederatedSession divergem entre PrivacyPolicy Java e <privacy> em research.xml.
  23. Testes & Scripts:
  24. ArchitectureComponentTestSuite mantém asserções legadas (2 experimentos em vez de 3; "OK" em /health em vez de JSON);
  25. HarSessionFactory não existe (sem suporte a clone dinâmico no HAR);
  26. run-coverage.sh omite federated-model-inference e exp-synthetic-smoke-001; run-iot-simulator.sh omite o modo dt; package-experiment.sh envia para /experiments/deploy em vez de /api/experiments/deploy.

4. Melhorias Documentais Aplicadas (BL-335)

  1. Novos documentos estruturantes:
  2. docs/ARCHITECTURE.md e docs/INSTALL.md (alinhados ao padrão canônico do projeto, com diagramas PlantUML inline e guia completo de instalação/execução).
  3. Este relatório técnico de auditoria integral (docs/analysis/auditoria-funcionalidades-e-documentacao-2026-11-18.md).
  4. Correção de todos os documentos de componente (docs/components/01 a 20) e README.md dos módulos: alinhamento de assinaturas Java 25, modelos de dados, estratégias, BL-334 (DataComponent, SqliteTimeSeriesStore, AdminWebServer, SseEventBus), BL-244, BL-259, BL-234/235, BL-236, BL-237, BL-243, BL-306, BL-308/309, Android e experimentos reais.
  5. Atualização das especificações OpenAPI (openapi-admin-monitor.yaml e openapi-hdt-client.yaml) preservando identidade byte a byte entre docs/components/ e modules/federated-rest-api/src/main/resources/.
  6. Atualização da camada Blockchain (docs/blockchain/* e 03-hyperledger-fabric.md) para 9 assets, 18 transações de FederatedExperimentSmartContract, Shadow 9.0.0, LedgerMode.failOnFabricError(), SubmitOutcome e estado real das sessões.
  7. Atualização da camada MQTT (docs/mqtt/* e 05-mqtt.md) para formato camelCase de MqttPayloadCodec, 13 campos de RoundConfig, 11 implementações de EvidenceProducing, X.509/Composite, TLS 8883 e tópicos mhub//fl/.
  8. Atualização dos guias (execution-guide.md, experiments-guide.md, tutorial-create-experiment.md, simulation-deployment-guide.md, vm-deployment-guide.md, modules.md, docker/README.md, research/README.md), diagramas (docs/diagrams/*), RAG e portal Read the Docs (modules/federated-docs).