Component: Local Digital Twin¶
Responsibility¶
The local digital twin is the primary asset of each federated participant. It represents the physical, clinical, industrial, or urban system operated by the client — and is the end consumer of the global model produced by the framework.
The trained federated model is not promoted automatically. The local digital twin decides, based on institutional policy, whether to accept or reject the candidate model published by the aggregator.
Implementation status¶
| Aspect | Status |
|---|---|
| Publication of the candidate model via MQTT | ✅ Implemented (GlobalModelPublication) |
| Local access interface to the digital twin (microbroker) | ✅ Implemented (ADR-002) — federated-digital-twin-broker, see 17-local-digital-twin-broker.md |
| Receipt of the model by the digital twin | ✅ Implemented — DigitalTwinValidatorAdapter |
| Local validation before promotion | ✅ Implemented — BaselineComparisonModelValidator (baseline comparison; the holdout evaluator itself is a placeholder, see 17) |
| Operational promotion of the model | 🔲 Planned — baseline is fixed per instance in this MVP; automatically updating it after a PROMOTE is a follow-up |
Current flow¶
AggregationResultPublisher (federated-orchestrator, BL-244)
│
│ publish GlobalModelPublication (signed MQTT)
│ - experimentId, modelVersion
│ - modelUri → "file://target/artifacts/.../model.bin"
│ - modelHash → "sha256:abc123..."
│ - aggregationReportUri + hash
▼
MqttGateway (external broker) → topic fl/experiments/{expId}/models/{version}/published
│
│ DigitalTwinBridge — verified and relayed onto the embedded HTTP+SSE broker (ADR-002 / BL-243)
▼
DigitalTwinValidatorAdapter (federated-digital-twin-broker)
├── LocalModelValidator.validate(publication, baseline, holdout)
│ ├── Download model.bin via LocalArtifactExperimentService, verify SHA-256
│ │ (and write candidate-v{version}.bin locally — pending TwinArtifactChannel migration)
│ ├── Evaluate against the private holdout (HoldoutEvaluator)
│ └── Compare with the production baseline → PROMOTE | REJECT | DEFER
├── Publish TwinValidationDecisionMessage (signed) back through the microbroker
└── Record locally + TwinValidationDecisionIngestor registers on Fabric (when wired)
See 17-local-digital-twin-broker.md for the full architecture of the microbroker/bridge/adapters.
Inputs expected by the digital twin¶
| Data | Source | Description |
|---|---|---|
GlobalModelPublication |
MQTT fl/.../models/{v}/published |
Hash, URI, and version of the candidate model |
AggregationReport |
Off-chain URI in GlobalModelPublication |
Global metrics, quorum, participating clients |
Candidate model (model.bin) |
LocalArtifactExperimentService via URI |
Weight vector of the candidate global model |
| Local baseline | digital twin repository | Model currently in production for comparison |
| Private holdout dataset | institutional storage | Local test data never sent to the framework |
Architectural invariants¶
- The global model is a candidate. Never automatically updates the digital twin without explicit local validation.
- Validation is local. The client's validation holdout never leaves the local domain — it is not sent to the orchestrator, aggregator, or Fabric.
- The digital twin never sends raw data. The only authorized output to the framework is the local update vector via MQTT (after the training round).
- Promotion respects institutional policy. The decision to promote a globally trained model must be mediated by the local operator — not by the remote researcher.
Integration with the experiments¶
| Experiment | Digital twin type | Model produced |
|---|---|---|
exp-har-smartphones-001 |
Person / mobile device | Human activity classifier (6 classes) |
exp-ecg5000-anomaly-001 |
Patient / cardiac sensor | Autoencoder for ECG anomaly detection |
Implemented — LocalModelValidator (ADR-002, BL-238)¶
The 7 steps originally sketched here are implemented in federated-digital-twin-broker
(package br.ufma.lsdi.digitaltwin.validator):
- Subscribe to
fl/experiments/{expId}/models/+/published— done byDigitalTwinBridge(external broker) relaying onto the embedded microbroker, consumed byDigitalTwinValidatorAdapter. - Download
model.binfromGlobalModelPublication.modelUri()viaLocalArtifactExperimentService—BaselineComparisonModelValidator. - Verify the SHA-256 hash against
GlobalModelPublication.modelHash()— mismatch is fail-closedREJECT, even with an otherwise-good metric. - Evaluate the candidate model against the private local holdout — via the pluggable
HoldoutEvaluatorinterface. Not production-ready as shipped: the only implementation provided,ReferenceMetricHoldoutEvaluator, is an explicit placeholder that returnsPrivateHoldout.precomputedMetric()without running real inference — training/evaluating HAR/ECG models is out of scope for this component (see 17). - Compare the evaluated metric with the baseline (production model) —
promoteMargin/rejectMarginonLocalModelBaseline. - Emit a decision:
ValidationDecision.PROMOTE | REJECT | DEFER, wrapped inTwinValidationOutcome(a superset of the original sketch's return type — see 17 for why). - Record the decision — locally in
DigitalTwinValidatorAdapter's unbridged chaincode and on the orchestrator's Fabric-bridgedFederatedExperimentChaincodeviaTwinValidationDecisionIngestor(registerTwinValidationDecision, implemented in theFederatedExperimentSmartContractchaincode source in BL-259, pending live Fabric test-network redeploy; wired inErgonomicRiskFederatedSession). (Note:BaselineComparisonModelValidatorcurrently still readsmodel.binand writescandidate-v{version}.bindirectly viaLocalArtifactExperimentServicerather than consuming in-memoryGlobalModelPayloadbytes.)
The interface itself matches the original sketch almost exactly, except the return type: