Ir para o conteúdo

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):

  1. Subscribe to fl/experiments/{expId}/models/+/published — done by DigitalTwinBridge (external broker) relaying onto the embedded microbroker, consumed by DigitalTwinValidatorAdapter.
  2. Download model.bin from GlobalModelPublication.modelUri() via LocalArtifactExperimentService — BaselineComparisonModelValidator.
  3. Verify the SHA-256 hash against GlobalModelPublication.modelHash() — mismatch is fail-closed REJECT, even with an otherwise-good metric.
  4. Evaluate the candidate model against the private local holdout — via the pluggable HoldoutEvaluator interface. Not production-ready as shipped: the only implementation provided, ReferenceMetricHoldoutEvaluator, is an explicit placeholder that returns PrivateHoldout.precomputedMetric() without running real inference — training/evaluating HAR/ECG models is out of scope for this component (see 17).
  5. Compare the evaluated metric with the baseline (production model) — promoteMargin/rejectMargin on LocalModelBaseline.
  6. Emit a decision: ValidationDecision.PROMOTE | REJECT | DEFER, wrapped in TwinValidationOutcome (a superset of the original sketch's return type — see 17 for why).
  7. Record the decision — locally in DigitalTwinValidatorAdapter's unbridged chaincode and on the orchestrator's Fabric-bridged FederatedExperimentChaincode via TwinValidationDecisionIngestor (registerTwinValidationDecision, implemented in the FederatedExperimentSmartContract chaincode source in BL-259, pending live Fabric test-network redeploy; wired in ErgonomicRiskFederatedSession). (Note: BaselineComparisonModelValidator currently still reads model.bin and writes candidate-v{version}.bin directly via LocalArtifactExperimentService rather than consuming in-memory GlobalModelPayload bytes.)

The interface itself matches the original sketch almost exactly, except the return type:

public interface LocalModelValidator {
    TwinValidationOutcome validate(
        GlobalModelPublication publication,
        LocalModelBaseline     baseline,
        PrivateHoldout         holdout
    );
}

public enum ValidationDecision { PROMOTE, REJECT, DEFER } // in br.ufma.lsdi.common.model — travels over MQTT