Digital twin, sync and drift

The Digital Twin is the tenant-scoped evidence and planning boundary between observed infrastructure and intended state. It is not a live provider view and cannot authorize a mutation.

Immutable snapshots

There are two canonical snapshot kinds:

Kind	Meaning	Valid producer
observed	Facts collected from a provider adapter, agent or import	server-controlled collection boundary
desired	Validated target state from a template, workspace or approved intent	server-side validation and approval flow

Each snapshot is append-only and contains snapshotId, organization, kind, schema version, scope, UTC capture time, canonical contentDigest, provenance, freshness policy, confidence and payload. A correction creates a new snapshot referencing the superseded one. Secrets, tokens and credential values are redacted before persistence.

Reconciliation flow

collect observed snapshot
          |
          v
resolve desired snapshot + exact scope
          |
          v
compare immutable IDs and digests
          |
          +--> evidence: missing / extra / attribute / relationship / policy
          +--> conflict or insufficient evidence: UNKNOWN, not drift
          |
          v
policy decision -> bounded simulation -> snapshot-bound plan

Freshness is evaluated as fresh, stale, expired or unknown. Stale evidence can be displayed and audited but cannot authorize a new plan. Expired or unknown evidence cannot be a comparison base. Confidence is server-calculated and the model cannot raise it.

Evidence classes

Class	Interpretation	Can it recommend a mutation?
MISSING_DESIRED	Desired item is absent from observed state	Only after normal policy and approval
EXTRA_OBSERVED	Observed item is outside desired scope	Depends on scope and policy
ATTRIBUTE_MISMATCH	Same identity, different compared attribute	Only with fresh evidence
RELATIONSHIP_MISMATCH	Dependency or topology differs	Only with fresh evidence
POLICY_VIOLATION	Observed state violates a policy	Policy determines actionability
CONFLICTING_OBSERVATION	Authoritative sources disagree	No mutation recommendation from conflict alone
UNKNOWN	Collection, identity, permission or freshness prevented comparison	No; obtain better evidence

Comparisons are immutable and keyed by observed snapshot, desired snapshot and comparison version. Re-running produces a new result. Resolving or suppressing a finding is a new audited decision, never an edit to original evidence.

Bounded what-if

Simulation accepts explicit snapshot IDs/digests and a typed allowlisted change set. It never calls a mutation method, changes desired state or claims provider acceptance. Default bounds are 200 affected resources, 100 operations, relationship depth 5, 64 KiB input and 30 seconds of compute. A truncated result identifies omitted work and includes limitations.

Plans carry the exact snapshots, simulation, policy decision, actor, scope, plan digest, generatedAt and expiresAt. The API and worker re-resolve membership, permissions, entitlements, environment, policy and approval, then verify a fresh observation before the first side effect.

In demo mode, observations and simulations are deterministic and explicitly simulated. AI can read this evidence and propose a bounded simulation or plan, but cannot create an authoritative snapshot or execute it.