devagent-physical-engine 0.10.0__py3-none-any.whl

devagent_physical_engine/twin.py

@@ -0,0 +1,939 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import Enum, IntEnum
+from hashlib import sha256
+import json
+from math import isfinite, pi
+from typing import Any, Mapping
+
+from .engineering_request import ValidatedEngineeringRequest
+from .robot_platform import RobotPlatformError, RobotProfileRegistry
+
+
+class TwinError(ValueError):
+    pass
+
+
+class EvidenceOrigin(str, Enum):
+    MEASURED = "measured"
+    IMPORTED = "imported"
+    USER_DECLARED = "user_declared"
+    ROBOT_PROFILE = "robot_profile"
+    ESTIMATED = "estimated"
+    DEFAULT = "default"
+    UNKNOWN = "unknown"
+
+
+class TwinConfidenceLevel(IntEnum):
+    CONCEPTUAL = 1
+    GEOMETRIC = 2
+    PHYSICAL = 3
+    REALITY_CALIBRATED = 4
+
+
+class GeometryKind(str, Enum):
+    BOX = "box"
+    CYLINDER = "cylinder"
+    MESH = "mesh"
+    CAD = "cad"
+    UNKNOWN = "unknown"
+
+
+class IssueSeverity(str, Enum):
+    ERROR = "error"
+    WARNING = "warning"
+
+
+_JSON_MAX_DEPTH = 8
+_JSON_MAX_ITEMS = 256
+_JSON_MAX_TEXT = 8192
+
+
+def _validate_json_like(value: Any, *, path: str = "metadata", depth: int = 0) -> None:
+    """Reject unstable/non-serializable metadata before evidence hashing."""
+
+    if depth > _JSON_MAX_DEPTH:
+        raise TwinError(f"metadata_depth_exceeded:{path}")
+    if value is None or isinstance(value, (bool, int)):
+        return
+    if isinstance(value, float):
+        if not isfinite(value):
+            raise TwinError(f"metadata_non_finite:{path}")
+        return
+    if isinstance(value, str):
+        if len(value) > _JSON_MAX_TEXT:
+            raise TwinError(f"metadata_text_too_long:{path}")
+        return
+    if isinstance(value, (list, tuple)):
+        if len(value) > _JSON_MAX_ITEMS:
+            raise TwinError(f"metadata_array_too_large:{path}")
+        for index, item in enumerate(value):
+            _validate_json_like(item, path=f"{path}[{index}]", depth=depth + 1)
+        return
+    if isinstance(value, Mapping):
+        if len(value) > _JSON_MAX_ITEMS:
+            raise TwinError(f"metadata_object_too_large:{path}")
+        for key, item in value.items():
+            if not isinstance(key, str) or not key:
+                raise TwinError(f"metadata_key_invalid:{path}")
+            _validate_json_like(item, path=f"{path}.{key}", depth=depth + 1)
+        return
+    raise TwinError(f"metadata_type_unsupported:{path}:{type(value).__name__}")
+
+
+def _canonical(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Mapping):
+        return {str(key): _canonical(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_canonical(item) for item in value]
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class EvidenceValue:
+    """A scalar value plus provenance; uncertainty is never erased."""
+
+    value: float | int | str | bool | None
+    origin: EvidenceOrigin
+    source_ref: str | None = None
+    uncertainty: float | None = None
+
+    def __post_init__(self) -> None:
+        if isinstance(self.value, float) and not isfinite(self.value):
+            raise TwinError("evidence_value_non_finite")
+        if self.source_ref is not None and not self.source_ref.strip():
+            raise TwinError("empty_evidence_source_ref")
+        if self.uncertainty is not None and (
+            not isfinite(self.uncertainty) or self.uncertainty < 0
+        ):
+            raise TwinError("evidence_uncertainty_invalid")
+        if self.origin is EvidenceOrigin.UNKNOWN and self.value is not None:
+            raise TwinError("unknown_origin_requires_null_value")
+
+
+@dataclass(frozen=True, slots=True)
+class Pose3D:
+    """Canonical SI pose: translation in metres and RPY in radians."""
+
+    x_m: float
+    y_m: float
+    z_m: float
+    roll_rad: float = 0.0
+    pitch_rad: float = 0.0
+    yaw_rad: float = 0.0
+    frame_id: str = "world"
+    origin: EvidenceOrigin = EvidenceOrigin.USER_DECLARED
+    source_ref: str | None = None
+
+    def __post_init__(self) -> None:
+        values = (
+            self.x_m,
+            self.y_m,
+            self.z_m,
+            self.roll_rad,
+            self.pitch_rad,
+            self.yaw_rad,
+        )
+        if any(not isfinite(value) for value in values):
+            raise TwinError("pose_non_finite")
+        if not self.frame_id.strip():
+            raise TwinError("pose_frame_required")
+        if self.source_ref is not None and not self.source_ref.strip():
+            raise TwinError("empty_pose_source_ref")
+        if any(abs(value) > 2 * pi + 1e-9 for value in self.orientation):
+            raise TwinError("pose_orientation_out_of_canonical_range")
+
+    @property
+    def orientation(self) -> tuple[float, float, float]:
+        return self.roll_rad, self.pitch_rad, self.yaw_rad
+
+
+@dataclass(frozen=True, slots=True)
+class FrameTransform:
+    """A named child frame located relative to an already-defined parent frame."""
+
+    child_frame_id: str
+    parent_frame_id: str
+    transform: Pose3D
+
+    def __post_init__(self) -> None:
+        if not self.child_frame_id.strip() or not self.parent_frame_id.strip():
+            raise TwinError("frame_identity_required")
+        if self.child_frame_id == "world":
+            raise TwinError("world_frame_cannot_have_parent")
+        if self.child_frame_id == self.parent_frame_id:
+            raise TwinError("self_parent_frame")
+        if self.transform.frame_id != self.parent_frame_id:
+            raise TwinError("frame_transform_parent_mismatch")
+
+
+@dataclass(frozen=True, slots=True)
+class GeometrySpec:
+    kind: GeometryKind
+    origin: EvidenceOrigin
+    dimensions_m: tuple[float, ...] = ()
+    asset_ref: str | None = None
+    collision_geometry: bool = True
+    source_ref: str | None = None
+
+    def __post_init__(self) -> None:
+        if any(not isfinite(value) or value <= 0 for value in self.dimensions_m):
+            raise TwinError("geometry_dimension_invalid")
+        if self.kind is GeometryKind.BOX and len(self.dimensions_m) != 3:
+            raise TwinError("box_requires_xyz_dimensions")
+        if self.kind is GeometryKind.CYLINDER and len(self.dimensions_m) != 2:
+            raise TwinError("cylinder_requires_radius_height")
+        if self.kind in {GeometryKind.MESH, GeometryKind.CAD}:
+            if not self.asset_ref or not self.asset_ref.strip():
+                raise TwinError("geometry_asset_required")
+        if self.kind is GeometryKind.UNKNOWN and (self.dimensions_m or self.asset_ref):
+            raise TwinError("unknown_geometry_cannot_have_shape_data")
+        if self.asset_ref is not None and not self.asset_ref.strip():
+            raise TwinError("empty_geometry_asset_ref")
+        if self.source_ref is not None and not self.source_ref.strip():
+            raise TwinError("empty_geometry_source_ref")
+        if self.origin is EvidenceOrigin.UNKNOWN and self.kind is not GeometryKind.UNKNOWN:
+            raise TwinError("unknown_geometry_origin_requires_unknown_kind")
+
+
+@dataclass(frozen=True, slots=True)
+class PhysicsSpec:
+    mass_kg: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+    friction_coefficient: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+    restitution: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+
+    def __post_init__(self) -> None:
+        for name in ("mass_kg", "friction_coefficient", "restitution"):
+            evidence = getattr(self, name)
+            if evidence.value is None:
+                continue
+            if isinstance(evidence.value, bool) or not isinstance(
+                evidence.value, (int, float)
+            ):
+                raise TwinError(f"physics_{name}_must_be_numeric")
+            numeric = float(evidence.value)
+            if name == "mass_kg" and numeric <= 0:
+                raise TwinError("physics_mass_invalid")
+            if name == "friction_coefficient" and numeric < 0:
+                raise TwinError("physics_friction_invalid")
+            if name == "restitution" and not 0 <= numeric <= 1:
+                raise TwinError("physics_restitution_invalid")
+
+    @property
+    def complete_for_contact(self) -> bool:
+        return (
+            self.mass_kg.value is not None
+            and self.friction_coefficient.value is not None
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TwinEntity:
+    entity_id: str
+    entity_type: str
+    pose: Pose3D | None
+    geometry: GeometrySpec
+    physics: PhysicsSpec = field(default_factory=PhysicsSpec)
+    enabled: bool = True
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.entity_id.strip():
+            raise TwinError("entity_id_required")
+        if not self.entity_type.strip():
+            raise TwinError("entity_type_required")
+        if not isinstance(self.metadata, Mapping):
+            raise TwinError("entity_metadata_must_be_mapping")
+        _validate_json_like(self.metadata, path=f"entity.{self.entity_id}.metadata")
+
+    @property
+    def geometric_ready(self) -> bool:
+        return (
+            self.pose is not None
+            and self.geometry.kind is not GeometryKind.UNKNOWN
+            and self.geometry.collision_geometry
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ToolSpec:
+    tool_id: str
+    tcp: Pose3D | None
+    geometry: GeometrySpec
+    max_payload_kg: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+
+    def __post_init__(self) -> None:
+        if not self.tool_id.strip():
+            raise TwinError("tool_id_required")
+        if self.max_payload_kg.value is not None:
+            value = self.max_payload_kg.value
+            if isinstance(value, bool) or not isinstance(value, (int, float)):
+                raise TwinError("tool_payload_limit_must_be_numeric")
+            if float(value) <= 0:
+                raise TwinError("tool_payload_limit_invalid")
+
+
+@dataclass(frozen=True, slots=True)
+class SensorSpec:
+    sensor_id: str
+    sensor_type: str
+    pose: Pose3D | None
+    latency_ms: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+    noise_stddev: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+
+    def __post_init__(self) -> None:
+        if not self.sensor_id.strip() or not self.sensor_type.strip():
+            raise TwinError("sensor_identity_required")
+        for name in ("latency_ms", "noise_stddev"):
+            evidence = getattr(self, name)
+            if evidence.value is None:
+                continue
+            if isinstance(evidence.value, bool) or not isinstance(
+                evidence.value, (int, float)
+            ):
+                raise TwinError(f"sensor_{name}_must_be_numeric")
+            if float(evidence.value) < 0:
+                raise TwinError(f"sensor_{name}_invalid")
+
+
+@dataclass(frozen=True, slots=True)
+class ControllerModel:
+    speed_scale_pct: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+    command_latency_ms: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+    state_latency_ms: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+
+    def __post_init__(self) -> None:
+        if self.speed_scale_pct.value is not None:
+            value = self.speed_scale_pct.value
+            if isinstance(value, bool) or not isinstance(value, (int, float)):
+                raise TwinError("controller_speed_scale_must_be_numeric")
+            if not 0 < float(value) <= 100:
+                raise TwinError("controller_speed_scale_invalid")
+        for name in ("command_latency_ms", "state_latency_ms"):
+            evidence = getattr(self, name)
+            if evidence.value is None:
+                continue
+            if isinstance(evidence.value, bool) or not isinstance(
+                evidence.value, (int, float)
+            ):
+                raise TwinError(f"controller_{name}_must_be_numeric")
+            if float(evidence.value) < 0:
+                raise TwinError(f"controller_{name}_invalid")
+
+    @property
+    def measured_or_declared(self) -> bool:
+        return any(
+            evidence.value is not None
+            for evidence in (
+                self.speed_scale_pct,
+                self.command_latency_ms,
+                self.state_latency_ms,
+            )
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class UncertaintyModel:
+    pose_translation_mm: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+    pose_rotation_deg: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+    payload_kg: EvidenceValue = field(
+        default_factory=lambda: EvidenceValue(None, EvidenceOrigin.UNKNOWN)
+    )
+
+    def __post_init__(self) -> None:
+        for name in ("pose_translation_mm", "pose_rotation_deg", "payload_kg"):
+            evidence = getattr(self, name)
+            if evidence.value is None:
+                continue
+            if isinstance(evidence.value, bool) or not isinstance(
+                evidence.value, (int, float)
+            ):
+                raise TwinError(f"uncertainty_{name}_must_be_numeric")
+            if float(evidence.value) < 0:
+                raise TwinError(f"uncertainty_{name}_invalid")
+
+
+@dataclass(frozen=True, slots=True)
+class RealityCalibrationEvidence:
+    observation_count: int = 0
+    cycle_time_gap_pct_p95: float | None = None
+    tcp_error_mm_p95: float | None = None
+    behavior_agreement: float | None = None
+    origin: EvidenceOrigin = EvidenceOrigin.UNKNOWN
+    dataset_ref: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.observation_count < 0:
+            raise TwinError("reality_observation_count_invalid")
+        for name in ("cycle_time_gap_pct_p95", "tcp_error_mm_p95"):
+            value = getattr(self, name)
+            if value is not None and (not isfinite(value) or value < 0):
+                raise TwinError(f"reality_{name}_invalid")
+        if self.behavior_agreement is not None and (
+            not isfinite(self.behavior_agreement)
+            or not 0 <= self.behavior_agreement <= 1
+        ):
+            raise TwinError("reality_behavior_agreement_invalid")
+        if self.dataset_ref is not None and not self.dataset_ref.strip():
+            raise TwinError("empty_reality_dataset_ref")
+        if self.observation_count > 0 and self.origin is not EvidenceOrigin.MEASURED:
+            raise TwinError("reality_calibration_requires_measured_origin")
+
+    @property
+    def calibrated(self) -> bool:
+        quantitative_gap = (
+            self.cycle_time_gap_pct_p95 is not None
+            or self.tcp_error_mm_p95 is not None
+        )
+        return (
+            self.observation_count > 0
+            and self.origin is EvidenceOrigin.MEASURED
+            and self.behavior_agreement is not None
+            and quantitative_gap
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TwinSpec:
+    twin_id: str
+    robot_profile_key: str
+    robot_base_pose: Pose3D | None
+    entities: tuple[TwinEntity, ...]
+    source_entity_id: str
+    destination_entity_id: str
+    workpiece_entity_id: str | None = None
+    tool: ToolSpec | None = None
+    frames: tuple[FrameTransform, ...] = ()
+    sensors: tuple[SensorSpec, ...] = ()
+    controller: ControllerModel = field(default_factory=ControllerModel)
+    uncertainty: UncertaintyModel = field(default_factory=UncertaintyModel)
+    reality: RealityCalibrationEvidence = field(default_factory=RealityCalibrationEvidence)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for name, value in (
+            ("twin_id", self.twin_id),
+            ("robot_profile_key", self.robot_profile_key),
+            ("source_entity_id", self.source_entity_id),
+            ("destination_entity_id", self.destination_entity_id),
+        ):
+            if not value.strip():
+                raise TwinError(f"{name}_required")
+        if self.workpiece_entity_id is not None and not self.workpiece_entity_id.strip():
+            raise TwinError("workpiece_entity_id_empty")
+        if not isinstance(self.metadata, Mapping):
+            raise TwinError("twin_metadata_must_be_mapping")
+        _validate_json_like(self.metadata)
+
+    def entity_map(self) -> dict[str, TwinEntity]:
+        return {entity.entity_id: entity for entity in self.entities}
+
+    def frame_ids(self) -> frozenset[str]:
+        return frozenset({"world", *(frame.child_frame_id for frame in self.frames)})
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "twin_id": self.twin_id,
+            "robot_profile_key": self.robot_profile_key,
+            "robot_base_pose": asdict(self.robot_base_pose) if self.robot_base_pose else None,
+            "entities": [asdict(entity) for entity in self.entities],
+            "source_entity_id": self.source_entity_id,
+            "destination_entity_id": self.destination_entity_id,
+            "workpiece_entity_id": self.workpiece_entity_id,
+            "tool": asdict(self.tool) if self.tool else None,
+            "frames": [asdict(frame) for frame in self.frames],
+            "sensors": [asdict(sensor) for sensor in self.sensors],
+            "controller": asdict(self.controller),
+            "uncertainty": asdict(self.uncertainty),
+            "reality": asdict(self.reality),
+            "metadata": dict(self.metadata),
+        }
+
+    @property
+    def fingerprint(self) -> str:
+        payload = json.dumps(
+            _canonical(self.to_dict()),
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        )
+        return sha256(payload.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class TwinIssue:
+    severity: IssueSeverity
+    code: str
+    detail: str
+    entity_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.code.strip() or not self.detail.strip():
+            raise TwinError("twin_issue_content_required")
+
+
+@dataclass(frozen=True, slots=True)
+class TwinValidationReport:
+    twin_id: str
+    twin_hash: str
+    confidence_level: TwinConfidenceLevel
+    structurally_valid: bool
+    ready_for_planning: bool
+    ready_for_physics: bool
+    reality_calibrated: bool
+    issues: tuple[TwinIssue, ...]
+
+    @property
+    def errors(self) -> tuple[TwinIssue, ...]:
+        return tuple(
+            issue for issue in self.issues if issue.severity is IssueSeverity.ERROR
+        )
+
+    @property
+    def warnings(self) -> tuple[TwinIssue, ...]:
+        return tuple(
+            issue for issue in self.issues if issue.severity is IssueSeverity.WARNING
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "twin_id": self.twin_id,
+            "twin_hash": self.twin_hash,
+            "confidence_level": int(self.confidence_level),
+            "confidence_name": self.confidence_level.name.lower(),
+            "structurally_valid": self.structurally_valid,
+            "ready_for_planning": self.ready_for_planning,
+            "ready_for_physics": self.ready_for_physics,
+            "reality_calibrated": self.reality_calibrated,
+            "issues": [
+                {
+                    "severity": issue.severity.value,
+                    "code": issue.code,
+                    "detail": issue.detail,
+                    "entity_id": issue.entity_id,
+                }
+                for issue in self.issues
+            ],
+        }
+
+
+class TwinValidator:
+    """Fail-closed validation for a customer simulation twin."""
+
+    def __init__(self, robot_profiles: RobotProfileRegistry) -> None:
+        self.robot_profiles = robot_profiles
+
+    @staticmethod
+    def _validate_frames(twin: TwinSpec, issues: list[TwinIssue]) -> frozenset[str]:
+        children = [frame.child_frame_id for frame in twin.frames]
+        if len(children) != len(set(children)):
+            issues.append(
+                TwinIssue(
+                    IssueSeverity.ERROR,
+                    "duplicate_frame_id",
+                    "Each child frame may be declared only once.",
+                )
+            )
+
+        frame_map = {frame.child_frame_id: frame.parent_frame_id for frame in twin.frames}
+        known = {"world", *frame_map.keys()}
+        for child, parent in frame_map.items():
+            if parent not in known:
+                issues.append(
+                    TwinIssue(
+                        IssueSeverity.ERROR,
+                        "unknown_parent_frame",
+                        f"Frame '{child}' references unknown parent '{parent}'.",
+                    )
+                )
+
+        for child in frame_map:
+            visited: set[str] = set()
+            current = child
+            while current in frame_map:
+                if current in visited:
+                    issues.append(
+                        TwinIssue(
+                            IssueSeverity.ERROR,
+                            "frame_cycle",
+                            f"Frame chain containing '{child}' is cyclic.",
+                        )
+                    )
+                    break
+                visited.add(current)
+                current = frame_map[current]
+
+        return frozenset(known)
+
+    @staticmethod
+    def _check_pose_frame(
+        pose: Pose3D | None,
+        *,
+        known_frames: frozenset[str],
+        owner: str,
+        issues: list[TwinIssue],
+        entity_id: str | None = None,
+    ) -> None:
+        if pose is not None and pose.frame_id not in known_frames:
+            issues.append(
+                TwinIssue(
+                    IssueSeverity.ERROR,
+                    "unknown_pose_frame",
+                    f"{owner} references undeclared frame '{pose.frame_id}'.",
+                    entity_id,
+                )
+            )
+
+    def validate(
+        self,
+        twin: TwinSpec,
+        *,
+        request: ValidatedEngineeringRequest | None = None,
+    ) -> TwinValidationReport:
+        issues: list[TwinIssue] = []
+        try:
+            profile = self.robot_profiles.resolve(twin.robot_profile_key)
+        except RobotPlatformError:
+            profile = None
+            issues.append(
+                TwinIssue(
+                    IssueSeverity.ERROR,
+                    "unknown_robot_profile",
+                    f"Robot profile '{twin.robot_profile_key}' is not registered.",
+                )
+            )
+
+        known_frames = self._validate_frames(twin, issues)
+        self._check_pose_frame(
+            twin.robot_base_pose,
+            known_frames=known_frames,
+            owner="Robot base pose",
+            issues=issues,
+        )
+        if twin.tool is not None:
+            self._check_pose_frame(
+                twin.tool.tcp,
+                known_frames=known_frames,
+                owner="Tool TCP",
+                issues=issues,
+            )
+        for sensor in twin.sensors:
+            self._check_pose_frame(
+                sensor.pose,
+                known_frames=known_frames,
+                owner=f"Sensor '{sensor.sensor_id}'",
+                issues=issues,
+            )
+
+        ids = [entity.entity_id for entity in twin.entities]
+        duplicate_ids = sorted(
+            {entity_id for entity_id in ids if ids.count(entity_id) > 1}
+        )
+        for entity_id in duplicate_ids:
+            issues.append(
+                TwinIssue(
+                    IssueSeverity.ERROR,
+                    "duplicate_entity_id",
+                    "Twin entity ids must be unique.",
+                    entity_id,
+                )
+            )
+
+        entity_map = twin.entity_map()
+        for role, entity_id in (
+            ("source", twin.source_entity_id),
+            ("destination", twin.destination_entity_id),
+        ):
+            if entity_id not in entity_map:
+                issues.append(
+                    TwinIssue(
+                        IssueSeverity.ERROR,
+                        f"missing_{role}_entity",
+                        f"The {role} entity '{entity_id}' is not present in the twin.",
+                        entity_id,
+                    )
+                )
+        if twin.workpiece_entity_id and twin.workpiece_entity_id not in entity_map:
+            issues.append(
+                TwinIssue(
+                    IssueSeverity.ERROR,
+                    "missing_workpiece_entity",
+                    f"The workpiece entity '{twin.workpiece_entity_id}' is not present in the twin.",
+                    twin.workpiece_entity_id,
+                )
+            )
+
+        if twin.robot_base_pose is None:
+            issues.append(
+                TwinIssue(
+                    IssueSeverity.ERROR,
+                    "robot_base_pose_missing",
+                    "Robot base pose is required before geometric planning.",
+                )
+            )
+
+        if twin.tool is None:
+            issues.append(
+                TwinIssue(
+                    IssueSeverity.WARNING,
+                    "tool_not_specified",
+                    "Tool/TCP is not specified; geometric confidence is limited.",
+                )
+            )
+        else:
+            if twin.tool.tcp is None:
+                issues.append(
+                    TwinIssue(
+                        IssueSeverity.ERROR,
+                        "tool_tcp_missing",
+                        "A configured tool requires a TCP pose before planning.",
+                    )
+                )
+            if twin.tool.geometry.kind is GeometryKind.UNKNOWN:
+                issues.append(
+                    TwinIssue(
+                        IssueSeverity.WARNING,
+                        "tool_geometry_unknown",
+                        "Tool collision geometry is unknown.",
+                    )
+                )
+
+        for entity in twin.entities:
+            if not entity.enabled:
+                continue
+            if entity.pose is None:
+                issues.append(
+                    TwinIssue(
+                        IssueSeverity.ERROR,
+                        "entity_pose_missing",
+                        "Enabled entity has no pose.",
+                        entity.entity_id,
+                    )
+                )
+            else:
+                self._check_pose_frame(
+                    entity.pose,
+                    known_frames=known_frames,
+                    owner=f"Entity '{entity.entity_id}'",
+                    issues=issues,
+                    entity_id=entity.entity_id,
+                )
+            if entity.geometry.kind is GeometryKind.UNKNOWN:
+                issues.append(
+                    TwinIssue(
+                        IssueSeverity.ERROR,
+                        "entity_geometry_unknown",
+                        "Enabled entity has no usable geometry.",
+                        entity.entity_id,
+                    )
+                )
+            if not entity.geometry.collision_geometry:
+                issues.append(
+                    TwinIssue(
+                        IssueSeverity.WARNING,
+                        "collision_geometry_disabled",
+                        "Entity is excluded from collision geometry.",
+                        entity.entity_id,
+                    )
+                )
+            for dimension in entity.geometry.dimensions_m:
+                if dimension > 100:
+                    issues.append(
+                        TwinIssue(
+                            IssueSeverity.ERROR,
+                            "possible_unit_mismatch",
+                            f"Geometry dimension {dimension:g} m is unusually large for a robot cell; confirm mm/m conversion before planning.",
+                            entity.entity_id,
+                        )
+                    )
+
+        sensor_ids = [sensor.sensor_id for sensor in twin.sensors]
+        if len(sensor_ids) != len(set(sensor_ids)):
+            issues.append(
+                TwinIssue(
+                    IssueSeverity.ERROR,
+                    "duplicate_sensor_id",
+                    "Sensor ids must be unique.",
+                )
+            )
+
+        if request is not None:
+            try:
+                request_robot = self.robot_profiles.resolve(request.robot_key).key
+            except RobotPlatformError:
+                request_robot = request.robot_key
+            twin_robot = profile.key if profile is not None else twin.robot_profile_key
+            if request_robot != twin_robot:
+                issues.append(
+                    TwinIssue(
+                        IssueSeverity.ERROR,
+                        "request_robot_twin_mismatch",
+                        f"Request robot '{request.robot_key}' differs from twin robot '{twin.robot_profile_key}'.",
+                    )
+                )
+            if request.source != twin.source_entity_id:
+                issues.append(
+                    TwinIssue(
+                        IssueSeverity.ERROR,
+                        "request_source_twin_mismatch",
+                        f"Request source '{request.source}' differs from twin source '{twin.source_entity_id}'.",
+                    )
+                )
+            if request.destination != twin.destination_entity_id:
+                issues.append(
+                    TwinIssue(
+                        IssueSeverity.ERROR,
+                        "request_destination_twin_mismatch",
+                        f"Request destination '{request.destination}' differs from twin destination '{twin.destination_entity_id}'.",
+                    )
+                )
+            if request.payload_kg is not None and profile is not None:
+                if (
+                    profile.limits.payload_kg is not None
+                    and request.payload_kg > profile.limits.payload_kg
+                ):
+                    issues.append(
+                        TwinIssue(
+                            IssueSeverity.ERROR,
+                            "robot_payload_limit_exceeded",
+                            f"Requested payload {request.payload_kg:g} kg exceeds qualified profile limit {profile.limits.payload_kg:g} kg.",
+                        )
+                    )
+                if twin.tool is not None and twin.tool.max_payload_kg.value is not None:
+                    tool_limit = float(twin.tool.max_payload_kg.value)
+                    if request.payload_kg > tool_limit:
+                        issues.append(
+                            TwinIssue(
+                                IssueSeverity.ERROR,
+                                "tool_payload_limit_exceeded",
+                                f"Requested payload {request.payload_kg:g} kg exceeds tool limit {tool_limit:g} kg.",
+                            )
+                        )
+
+        structural_errors = [
+            issue for issue in issues if issue.severity is IssueSeverity.ERROR
+        ]
+        structurally_valid = not structural_errors
+
+        enabled_entities = [entity for entity in twin.entities if entity.enabled]
+        geometry_complete = (
+            twin.robot_base_pose is not None
+            and twin.tool is not None
+            and twin.tool.tcp is not None
+            and twin.tool.geometry.kind is not GeometryKind.UNKNOWN
+            and all(entity.geometric_ready for entity in enabled_entities)
+            and twin.source_entity_id in entity_map
+            and twin.destination_entity_id in entity_map
+        )
+        ready_for_planning = structurally_valid and geometry_complete
+
+        workpiece = (
+            entity_map.get(twin.workpiece_entity_id)
+            if twin.workpiece_entity_id is not None
+            else None
+        )
+        physics_complete = (
+            ready_for_planning
+            and workpiece is not None
+            and workpiece.physics.complete_for_contact
+            and twin.controller.measured_or_declared
+        )
+        if ready_for_planning and not physics_complete:
+            issues.append(
+                TwinIssue(
+                    IssueSeverity.WARNING,
+                    "physics_evidence_incomplete",
+                    "Geometry is planning-ready, but workpiece physics/controller evidence is incomplete.",
+                )
+            )
+
+        reality_calibrated = physics_complete and twin.reality.calibrated
+        if reality_calibrated:
+            confidence = TwinConfidenceLevel.REALITY_CALIBRATED
+        elif physics_complete:
+            confidence = TwinConfidenceLevel.PHYSICAL
+        elif ready_for_planning:
+            confidence = TwinConfidenceLevel.GEOMETRIC
+        else:
+            confidence = TwinConfidenceLevel.CONCEPTUAL
+
+        return TwinValidationReport(
+            twin_id=twin.twin_id,
+            twin_hash=twin.fingerprint,
+            confidence_level=confidence,
+            structurally_valid=structurally_valid,
+            ready_for_planning=ready_for_planning,
+            ready_for_physics=physics_complete,
+            reality_calibrated=reality_calibrated,
+            issues=tuple(issues),
+        )
+
+
+def evidence_summary(twin: TwinSpec) -> dict[str, int]:
+    """Count provenance across important twin values for report/UI use."""
+
+    origins: list[EvidenceOrigin] = []
+    if twin.robot_base_pose is not None:
+        origins.append(twin.robot_base_pose.origin)
+    for frame in twin.frames:
+        origins.append(frame.transform.origin)
+    if twin.tool is not None:
+        if twin.tool.tcp is not None:
+            origins.append(twin.tool.tcp.origin)
+        origins.append(twin.tool.geometry.origin)
+        origins.append(twin.tool.max_payload_kg.origin)
+    for entity in twin.entities:
+        if entity.pose is not None:
+            origins.append(entity.pose.origin)
+        origins.append(entity.geometry.origin)
+        origins.extend(
+            (
+                entity.physics.mass_kg.origin,
+                entity.physics.friction_coefficient.origin,
+                entity.physics.restitution.origin,
+            )
+        )
+    for sensor in twin.sensors:
+        if sensor.pose is not None:
+            origins.append(sensor.pose.origin)
+        origins.extend((sensor.latency_ms.origin, sensor.noise_stddev.origin))
+    origins.extend(
+        (
+            twin.controller.speed_scale_pct.origin,
+            twin.controller.command_latency_ms.origin,
+            twin.controller.state_latency_ms.origin,
+            twin.uncertainty.pose_translation_mm.origin,
+            twin.uncertainty.pose_rotation_deg.origin,
+            twin.uncertainty.payload_kg.origin,
+            twin.reality.origin,
+        )
+    )
+    return {
+        origin.value: sum(1 for value in origins if value is origin)
+        for origin in EvidenceOrigin
+    }