magnus919_agent-skills/digital-twin/references/architecture.md

Digital Twin: architecture and federation

Design stance

Design from a decision and its risk boundary outward. A twin universe should be a federation of purpose-bounded component twins, not a monolithic graph or universal database. Each component owns reconciliation with its original and publishes scoped claims, capabilities, freshness, validity, and authority.

Reference architecture

flowchart TB
  O[Originals: code, CI/CD, runtime, infrastructure, people, agents]
  E[Connectors and evidence plane]
  L[(Immutable event log and artifact store)]
  S[(Temporal state projections)]
  G[(Relationship and provenance graph)]
  M[Models, replicas, simulators, scenarios]
  Q[Versioned evidence/query API]
  A[Analytics, planners, agents]
  P[Policy, approval, capability gateway]
  X[PR, ticket, canary, deploy, rollback, stop]
  H[Independent health and evaluation]
  O --> E --> L
  L --> S
  L --> G
  S --> Q
  G --> Q
  Q --> A --> P --> X --> O
  S --> M
  G --> M
  M --> A
  H --> M
  H --> A
  H --> P

Layer contracts

1. Identity and definitions: Stable identifiers for originals, types, instances, revisions, artifacts, models, agents, policies, scenarios, decisions, and actions. Definitions are versioned separately from instance state.
2. Evidence and synchronization: Source-specific connectors emit immutable envelopes with source identity, event time, ingestion time, sequence/revision, schema version, producer, sensitivity, integrity, and raw-evidence reference. Support snapshots and reconciliation in addition to streams.
3. Temporal state and thread: Keep immutable history and materialized views. Support as-of queries and deterministic replay. Every decision-critical field and edge carries provenance, transformation, freshness, validity interval, confidence, and authority.
4. Topology and composition: Model typed relationships among product, code, build, deployment, runtime, infrastructure, people, agents, policies, incidents, and outcomes. A graph is a projection over evidence, not the sole source of truth.
5. Models and scenarios: Register mechanistic, statistical, causal, queueing, policy, executable, and learned models independently. Composition requires explicit adapters and uncertainty propagation.
6. Decision and action: Queries return snapshot watermark, versions, freshness, validity domain, provenance, uncertainty, and explicit unknown. Agents usually emit proposals and evidence packets. Actions require deterministic policy evaluation and reconciliation.
7. Independent assurance: Health, evaluation, and audit paths must be able to disagree with the twin and must not be graded by the same model/action loop.

Component-twin manifest

Each federated twin should publish:

id: twin:example/service
definition: service-twin@2
original: service:example
owner: team@example
purpose: change-impact and rollback recommendation
source_authority:
  - id: runtime-feed
    contract: runtime-feed@4
    freshness: 30s
  - id: deploy-feed
    contract: deploy-feed@2
    freshness: 5m
time_basis: UTC
sync_contract:
  mode: event-driven
  decision_critical_max_age: 30s
  reconciliation: hourly
validity_domain:
  environments: [production]
  regions: [us-east]
  versions: [service@current]
  excluded_conditions: []
queries: [state, dependencies, change-impact]
models: [impact-model@7]
scenarios: [rollback-replay@1]
actions: [recommend-rollback]
authority: shadow
sensitivity: confidential
retention: operational-evidence-90d
stop_authority: team@example
retirement_endpoint: registry://twins/example/service/retire
notes: recommendation only; no direct rollback authority

Treat this as a contract pattern, not a universal standard schema.

Federation rules

• Local owners retain authority over source reconciliation and model validity.
• A catalog resolves identities, capabilities, versions, and compatibility without centralizing all sensitive payloads.
• Scenario composition freezes snapshots, model versions, seeds/configuration, policy context, and uncertainty.
• Cross-twin edges are signed or otherwise attributable and have validity intervals.
• Conflicting claims remain visible; do not silently collapse them into a “current” value.
• A downstream twin may consume a claim only within the producer’s declared validity and authority scope.

Architectural tradeoffs

Choice	Default	Why
Event log plus projections vs graph-only	Event log plus projections	Replay, audit, temporal state, and correction remain possible
Federation vs central universe	Federation with a minimal catalog	Limits coupling, privacy concentration, and cascading failure
Standard ontology vs adapters	Standardize identity/provenance core; adapt domain detail	Prevents lowest-common-denominator semantics
High-fidelity replica vs cheap emulator	Fidelity proportional to decision risk	Calibration is expensive and incomplete external behavior is common
Continuous synchronization vs declared frequency	Declared frequency per field/use case	“Real time” is not one universal requirement
Bidirectional control vs recommendation	Earn authority gradually	A return path turns the twin into a control system

Failure modes to design against

Stale state presented as current; duplicate or reordered events; untracked manual changes; hidden schema changes; name-based identity collisions; graph contamination; false causal inference; simulator exploitation; correlated agent/verifier failures; centralized compromise; and irreversible action without current preconditions.

Sources

• NISTIR 8356: https://csrc.nist.gov/pubs/ir/8356/final
• NIST Digital Twins for Advanced Manufacturing: https://www.nist.gov/programs-projects/digital-twins-advanced-manufacturing
• Digital Twins for Software Engineering Processes: https://arxiv.org/html/2510.05768v1
• Digital Twin Consortium digital thread: https://www.digitaltwinconsortium.org/initiatives/the-definition-of-digital-thread/
• FMI 3.0: https://www.fmi-standard.org/docs/3.0/
• OPC UA reference: https://reference.opcfoundation.org/
• Istio traffic mirroring: https://istio.io/latest/docs/tasks/traffic-management/mirroring/