Dados Locais dos Clientes¶
Esta pasta contém os dados ingeridos via MQTT de cada cliente federado, usados para execução local
e em Docker dos experimentos. Nada aqui é escrito manualmente pelo pesquisador — todo o
conteúdo é gerado por DataComponent/MqttTimeSeriesIngestor a partir de dados recebidos via MQTT
(ver docs/componentes/07-data-component.md para a API
completa e docs/componentes/16-simulacao-dataset-generico.md
para como os dados chegam até o MQTT a partir de um dataset).
BL-091: a partir desta versão,
timeseries.dbé a única fonte de leitura deDataComponent.loadLocalCdmRepository(...)(o caminho de treino). A estrutura antigadata/{client_id}/{experiment_id}/dataset.csvnão é mais necessária nem lida por esse caminho — deixou de existir a obrigação de materializar um snapshot por cliente antes de treinar.
Estrutura atual¶
data/
timeseries.db # SQLite único, compartilhado por todos os clientes/experimentos
# (tabelas mqtt_observations, mqtt_events, mqtt_entities;
# store padrão — TIMESERIES_STORE=sqlite)
{client_id}/
{experiment_id}/
dataset.csv # OPCIONAL — snapshot legado, só existe se alguém chamar
metadata.json # DataComponent.materializeDatasetFromStore(...)/dataset(...)
# diretamente (loaders legados fora do pipeline MQTT genérico;
# loadLocalCdmRepository() nunca lê esses dois arquivos)
observations_ts.csv # somente se TIMESERIES_STORE=csv (store legado por arquivo)
events_ts.csv # idem
entities_ts.csv # idem
timeseries.db é a fonte de verdade e o único caminho de leitura para treino. dataset.csv/
metadata.json continuam existindo como um recurso opcional de depuração/exportação manual (via
DataComponent.dataset(...)/materializeDatasetFromStore(...), preservados para os loaders
legados Ecg5000DatasetLoader/HarDatasetLoader) — mas loadLocalCdmRepository(), usado por todo
o pipeline de treino, nunca consulta esses dois arquivos.
Isolamento físico em Docker (BL-091)¶
FederatedDockerClientExecutor não monta mais data/{client_id}/{experiment_id} no container.
Em vez disso, a cada lançamento de container ele exporta — via ClientTimeSeriesExporter, a partir
do timeseries.db compartilhado desta pasta — um timeseries.db filtrado, contendo só as
linhas do cliente/experimento daquele container, e monta esse arquivo filtrado (não o diretório) em
/app/data/timeseries.db:ro. O container nunca tem acesso ao timeseries.db compartilhado
inteiro, preservando a invariante "não permitir dados brutos fora do cliente" mesmo sem a estrutura
de diretório por cliente.
metadata.json — exemplo real (quando gerado manualmente)¶
{
"client_id": "1",
"experiment_id": "exp-mnist-digits-001",
"dataset_file": "dataset.csv",
"records": 7860,
"created_at": "2026-07-14T18:38:16.402797Z",
"notes": ["source=mqtt", "observations=7850", "events=10"]
}
dataset.csv — cabeçalho fixo¶
Uma linha por observação (record_type=observation) ou evento (record_type=event) do CDM local
do cliente — nunca o formato bruto do dataset de origem (ex.: não são as colunas pixel_0..pixel_783
do MNIST; essas viram uma linha cada, identificadas por property_or_event).
Como os dados chegam até aqui (pipeline obrigatório)¶
Fonte do dataset (CSV real ou fallback sintético)
│
│ CsvDatasetSimulationSource / {Dataset}MqttSimulationAdapter
│ (ver docs/componentes/16-simulacao-dataset-generico.md)
▼
MqttDatasetReplaySimulator.replayRepository(...) → publica MqttEnvelope assinado via MQTT
▼
DataComponent.subscribeToMqttSource(...) → assina ANTES da publicação
│
▼
MqttTimeSeriesIngestor → verifica assinatura → grava em timeseries.db
│
│ DataComponent.loadLocalCdmRepository(...) ← lê direto daqui (BL-091)
▼
InMemoryLocalCdmRepository
Proveniência MQTT é garantida estruturalmente, não por arquivo (BL-091): o único escritor de
produção de timeseries.db (appendObservation/appendEvent) é MqttTimeSeriesIngestor, que só
grava depois de envelope.verify(signatureService) ter sucesso — logo, a simples presença de dados
na store para (clientId, experimentId) já comprova que passaram pela verificação de assinatura
MQTT. DataComponent.loadLocalCdmRepository(...) lança IllegalStateException apenas quando não
há dado nenhum na store para o par consultado; não existe mais checagem de metadata.json. Não
existe caminho de "carregar CSV bruto do dataset diretamente" — todo experimento novo deve seguir o
pipeline acima.
Regras¶
client_iddeve ser um inteiro positivo (validado porClientExperimentDataStore, ainda usado pelo caminho legado dedataset()/materializeDatasetFromStore()).- Todo dado de treino trafega por
timeseries.db—loadLocalCdmRepository()lançaIllegalStateExceptionse não houver observações/eventos/entidades na store para o par(clientId, experimentId). - Código de treinamento (
TrainingLocalModel) nunca acessa esta pasta diretamente — recebecontext.authorizedDataView(), filtrado porAuthorizedTrainingViewBuildera partir do repositório carregado porDataComponent. - Nenhum loader de dataset deve escrever diretamente em
timeseries.db— sempre passar pelo pipeline MQTT ({Dataset}MqttSimulationAdapter+MqttDatasetReplaySimulatorou o motor genéricoCsvDatasetSimulationSource, nunca escrita direta em disco). - Datasets de teste definidos no contrato não devem ser colocados nesta árvore, pois não pertencem a nenhum cliente (ver seção abaixo).
Dataset de teste contratual¶
Se o pesquisador definir um dataset de teste em EvaluationDatasetSpec, ele deve ficar sob
controle do pesquisador/agregador, por exemplo em research/datasets/{dataset_id} ou em um
Artifact Experiment Service com URI e hash registrados no contrato.
Esse dataset:
- nunca é enviado aos clientes;
- nunca é montado nos containers dos clientes;
- nunca é usado para construir a visão autorizada de treinamento;
- pode ser usado para avaliar modelos locais submetidos e modelo global candidato.
Não confundir com a segmentação train/test/validation do motor genérico de simulação (BL-088, ver
docs/componentes/16-simulacao-dataset-generico.md): aquela decide quais linhas de um dataset simulado são publicadas aos clientes via MQTT (train+test) versus retidas como holdout central (validation) — ainda assim, tudo o que é publicado aos clientes passa pelo pipeline acima e termina materializado nesta pasta.
Variáveis de ambiente¶
| Variável | Padrão | Descrição |
|---|---|---|
HDT_AF_DATA_ROOT (alias DATA_ROOT) |
data |
Raiz desta árvore de dados |
TIMESERIES_STORE |
sqlite |
sqlite (padrão, timeseries.db) ou csv (legado, *_ts.csv por cliente/experimento) |
Execução Docker (BL-091)¶
Em containers, HDT_AF_DATA_ROOT=/app/data continua sendo a variável usada por
ExperimentRuntimePaths.dataRoot()/DataComponent. O que muda é o que é montado nesse caminho:
FederatedDockerClientExecutor gera esse arquivo automaticamente a cada lançamento de container —
não é este data/timeseries.db compartilhado que é montado diretamente. O fluxo, por cliente:
ClientTimeSeriesExporter.export(sourceDataRoot=data/, destinationDataRoot=target/docker-client-data/{experimentId}/round-{roundId}/{clientId}, clientId, experimentId)lê otimeseries.dbcompartilhado desta pasta e grava umtimeseries.dbnovo contendo só as linhas demqtt_observations/mqtt_events/mqtt_entitiesdaquele(clientId, experimentId).- O arquivo exportado é montado somente-leitura em
/app/data/timeseries.db:ro. - Dentro do container,
DataComponent(ExperimentRuntimePaths.dataRoot())resolve/app/data/timeseries.dbnormalmente — o código do cliente (DockerEcgClientApp,DockerHarClientApp) não muda nada, só passa a enxergar um banco pré-filtrado.
Assim o container de um cliente continua sem receber dados de outros clientes, sem depender da
estrutura data/{client_id}/{experiment_id} — que deixou de ser criada/exigida para este fluxo.