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

devagent_physical_engine/engineering_request.py

@@ -0,0 +1,630 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from hashlib import sha256
+import json
+from math import isfinite
+import re
+from typing import Any, Mapping, Sequence
+
+from .models import Goal, Resource
+from .planning import SUPPORTED_GOAL_ACTIONS
+from .robots import CATALOG
+
+
+MAX_REQUEST_TEXT = 4096
+MAX_LIST_ITEMS = 32
+MAX_RUNS = 10_000
+
+
+class EngineeringRequestError(ValueError):
+    pass
+
+
+class RequestState(str, Enum):
+    DRAFT = "draft"
+    NEEDS_INFORMATION = "needs_information"
+    READY_FOR_VALIDATION = "ready_for_validation"
+    VALIDATED = "validated"
+    REJECTED = "rejected"
+
+
+class RequestPurpose(str, Enum):
+    PLAN = "plan"
+    SIMULATE = "simulate"
+    QUALIFY = "qualify"
+    COMMISSIONING = "commissioning"
+
+
+class Objective(str, Enum):
+    BALANCED = "balanced"
+    CYCLE_TIME = "cycle_time"
+    ROBUSTNESS = "robustness"
+    CLEARANCE = "clearance"
+    ENERGY = "energy"
+
+
+class TestPreset(str, Enum):
+    QUICK = "quick"
+    ENGINEERING = "engineering"
+    ROBUSTNESS = "robustness"
+    STRESS = "stress"
+    CUSTOM = "custom"
+
+
+class FaultIntent(str, Enum):
+    MISSING_OBJECT = "missing_object"
+    DESTINATION_OCCUPIED = "destination_occupied"
+    ROBOT_UNAVAILABLE = "robot_unavailable"
+    CONTROLLER_TIMEOUT = "controller_timeout"
+    COLLISION_OBSTACLE = "collision_obstacle"
+    SENSOR_LATENCY = "sensor_latency"
+    POSE_UNCERTAINTY = "pose_uncertainty"
+
+
+_OPERATION_ALIASES = {
+    "load": "load",
+    "machine_load": "load",
+    "machine_loading": "load",
+    "machine loading": "load",
+    "pick_and_place": "pick_place",
+    "pick-place": "pick_place",
+    "pick place": "pick_place",
+    "pick_place": "pick_place",
+    "palletize": "palletize",
+    "palletizing": "palletize",
+    "inspect": "inspect",
+    "inspection": "inspect",
+    "transfer": "transfer",
+}
+
+_ROBOT_ALIASES = {
+    "ur5e": "ur5e",
+    "ur 5e": "ur5e",
+    "universal robots ur5e": "ur5e",
+    "universal robot ur5e": "ur5e",
+    "fanuc crx": "fanuc_crx",
+    "fanuc_crx": "fanuc_crx",
+    "crx": "fanuc_crx",
+    "kuka kr": "kuka_kr",
+    "kuka_kr": "kuka_kr",
+    "abb irb": "abb_irb",
+    "abb_irb": "abb_irb",
+}
+
+_CORE_REQUIRED_FIELDS = ("robot", "operation", "object_id", "source", "destination")
+_CRITICAL_FIELDS = frozenset(_CORE_REQUIRED_FIELDS + ("payload_kg",))
+_SAFE_SYSTEM_CONSTRAINTS = ("collision_free", "joint_limits")
+
+
+def _clean_text(value: object, *, field_name: str, required: bool = False) -> str | None:
+    if value is None:
+        if required:
+            raise EngineeringRequestError(f"{field_name}_required")
+        return None
+    if not isinstance(value, str):
+        raise EngineeringRequestError(f"{field_name}_must_be_string")
+    text = value.strip()
+    if not text:
+        if required:
+            raise EngineeringRequestError(f"{field_name}_required")
+        return None
+    if len(text) > MAX_REQUEST_TEXT:
+        raise EngineeringRequestError(f"{field_name}_too_long")
+    return text
+
+
+def _optional_number(value: object, *, field_name: str, minimum: float | None = None, maximum: float | None = None) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise EngineeringRequestError(f"{field_name}_must_be_number")
+    result = float(value)
+    if not isfinite(result):
+        raise EngineeringRequestError(f"{field_name}_non_finite")
+    if minimum is not None and result < minimum:
+        raise EngineeringRequestError(f"{field_name}_below_minimum")
+    if maximum is not None and result > maximum:
+        raise EngineeringRequestError(f"{field_name}_above_maximum")
+    return result
+
+
+def _optional_int(value: object, *, field_name: str, minimum: int, maximum: int) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise EngineeringRequestError(f"{field_name}_must_be_integer")
+    if not minimum <= value <= maximum:
+        raise EngineeringRequestError(f"{field_name}_out_of_range")
+    return value
+
+
+def _string_tuple(value: object, *, field_name: str, allowed: set[str] | None = None) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes, bytearray)):
+        raise EngineeringRequestError(f"{field_name}_must_be_array")
+    if len(value) > MAX_LIST_ITEMS:
+        raise EngineeringRequestError(f"{field_name}_too_many_items")
+    output: list[str] = []
+    for item in value:
+        text = _clean_text(item, field_name=field_name, required=True)
+        assert text is not None
+        normalized = text.strip().lower()
+        if allowed is not None and normalized not in allowed:
+            raise EngineeringRequestError(f"unknown_{field_name}:{normalized}")
+        if normalized not in output:
+            output.append(normalized)
+    return tuple(output)
+
+
+def normalize_robot(value: str | None) -> str | None:
+    if value is None:
+        return None
+    key = re.sub(r"\s+", " ", value.strip().lower())
+    key = _ROBOT_ALIASES.get(key, key.replace("-", "_").replace(" ", "_"))
+    return key
+
+
+def normalize_operation(value: str | None) -> str | None:
+    if value is None:
+        return None
+    key = re.sub(r"\s+", " ", value.strip().lower())
+    return _OPERATION_ALIASES.get(key, key.replace("-", "_").replace(" ", "_"))
+
+
+@dataclass(frozen=True, slots=True)
+class PhysicalVariation:
+    object_x_mm: float | None = None
+    object_y_mm: float | None = None
+    object_z_mm: float | None = None
+    yaw_deg: float | None = None
+    payload_min_kg: float | None = None
+    payload_max_kg: float | None = None
+    speed_min_pct: float | None = None
+    speed_max_pct: float | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("object_x_mm", "object_y_mm", "object_z_mm", "yaw_deg"):
+            value = getattr(self, name)
+            if value is not None and (not isfinite(value) or value < 0):
+                raise EngineeringRequestError(f"{name}_invalid")
+        for name in ("payload_min_kg", "payload_max_kg"):
+            value = getattr(self, name)
+            if value is not None and (not isfinite(value) or value < 0):
+                raise EngineeringRequestError(f"{name}_invalid")
+        if self.payload_min_kg is not None and self.payload_max_kg is not None and self.payload_min_kg > self.payload_max_kg:
+            raise EngineeringRequestError("payload_variation_range_invalid")
+        for name in ("speed_min_pct", "speed_max_pct"):
+            value = getattr(self, name)
+            if value is not None and (not isfinite(value) or not 0 < value <= 100):
+                raise EngineeringRequestError(f"{name}_invalid")
+        if self.speed_min_pct is not None and self.speed_max_pct is not None and self.speed_min_pct > self.speed_max_pct:
+            raise EngineeringRequestError("speed_variation_range_invalid")
+
+    @property
+    def configured(self) -> bool:
+        return any(value is not None for value in asdict(self).values())
+
+
+@dataclass(frozen=True, slots=True)
+class EngineeringRequestDraft:
+    robot: str | None = None
+    operation: str | None = None
+    object_id: str | None = None
+    source: str | None = None
+    destination: str | None = None
+    tool: str | None = None
+    payload_kg: float | None = None
+    purpose: RequestPurpose = RequestPurpose.SIMULATE
+    objective: Objective = Objective.BALANCED
+    test_preset: TestPreset = TestPreset.ENGINEERING
+    runs: int | None = None
+    variation: PhysicalVariation = field(default_factory=PhysicalVariation)
+    faults: tuple[str, ...] = ()
+    minimum_clearance_mm: float | None = None
+    max_cycle_time_s: float | None = None
+    uncertain_fields: tuple[str, ...] = ()
+    notes: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.robot is not None:
+            object.__setattr__(self, "robot", normalize_robot(self.robot))
+        if self.operation is not None:
+            object.__setattr__(self, "operation", normalize_operation(self.operation))
+        if self.payload_kg is not None and (not isfinite(self.payload_kg) or self.payload_kg < 0):
+            raise EngineeringRequestError("payload_kg_invalid")
+        if self.minimum_clearance_mm is not None and (not isfinite(self.minimum_clearance_mm) or self.minimum_clearance_mm <= 0):
+            raise EngineeringRequestError("minimum_clearance_mm_invalid")
+        if self.max_cycle_time_s is not None and (not isfinite(self.max_cycle_time_s) or self.max_cycle_time_s <= 0):
+            raise EngineeringRequestError("max_cycle_time_s_invalid")
+        if self.runs is not None and not 1 <= self.runs <= MAX_RUNS:
+            raise EngineeringRequestError("runs_out_of_range")
+        unknown_uncertain = set(self.uncertain_fields) - {
+            "robot", "operation", "object_id", "source", "destination", "tool", "payload_kg",
+            "objective", "test_preset", "runs", "variation", "faults",
+        }
+        if unknown_uncertain:
+            raise EngineeringRequestError("unknown_uncertain_fields:" + ",".join(sorted(unknown_uncertain)))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "robot": self.robot,
+            "operation": self.operation,
+            "object_id": self.object_id,
+            "source": self.source,
+            "destination": self.destination,
+            "tool": self.tool,
+            "payload_kg": self.payload_kg,
+            "purpose": self.purpose.value,
+            "objective": self.objective.value,
+            "test_preset": self.test_preset.value,
+            "runs": self.runs,
+            "variation": asdict(self.variation),
+            "faults": list(self.faults),
+            "minimum_clearance_mm": self.minimum_clearance_mm,
+            "max_cycle_time_s": self.max_cycle_time_s,
+            "uncertain_fields": list(self.uncertain_fields),
+            "notes": list(self.notes),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class InformationRequest:
+    field: str
+    question: str
+    reason: str
+
+    def to_dict(self) -> dict[str, str]:
+        return asdict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class RequestAssessment:
+    state: RequestState
+    missing: tuple[InformationRequest, ...] = ()
+    rejection_codes: tuple[str, ...] = ()
+    open_items: tuple[str, ...] = ()
+
+    @property
+    def ready(self) -> bool:
+        return self.state is RequestState.READY_FOR_VALIDATION
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "state": self.state.value,
+            "missing": [item.to_dict() for item in self.missing],
+            "rejection_codes": list(self.rejection_codes),
+            "open_items": list(self.open_items),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ValidatedEngineeringRequest:
+    request_id: str
+    robot_key: str
+    operation: str
+    object_id: str
+    source: str
+    destination: str
+    tool: str | None
+    payload_kg: float | None
+    purpose: RequestPurpose
+    objective: Objective
+    test_preset: TestPreset
+    runs: int
+    variation: PhysicalVariation
+    faults: tuple[str, ...]
+    hard_constraints: tuple[str, ...]
+    minimum_clearance_mm: float | None
+    max_cycle_time_s: float | None
+    open_items: tuple[str, ...]
+
+    def goal(self) -> Goal:
+        return Goal(
+            goal_id=f"{self.request_id}-goal",
+            action=self.operation,
+            object_id=self.object_id,
+            source=self.source,
+            destination=self.destination,
+        )
+
+    def resource(self) -> Resource:
+        return CATALOG[self.robot_key]()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "request_id": self.request_id,
+            "state": RequestState.VALIDATED.value,
+            "robot": self.robot_key,
+            "operation": self.operation,
+            "object_id": self.object_id,
+            "source": self.source,
+            "destination": self.destination,
+            "tool": self.tool,
+            "payload_kg": self.payload_kg,
+            "purpose": self.purpose.value,
+            "objective": self.objective.value,
+            "test_preset": self.test_preset.value,
+            "runs": self.runs,
+            "variation": asdict(self.variation),
+            "faults": list(self.faults),
+            "hard_constraints": list(self.hard_constraints),
+            "minimum_clearance_mm": self.minimum_clearance_mm,
+            "max_cycle_time_s": self.max_cycle_time_s,
+            "open_items": list(self.open_items),
+        }
+
+
+_QUESTIONS = {
+    "robot": ("Which robot or robot model should perform this task?", "A robot must be selected before capability validation."),
+    "operation": ("What operation should the robot perform?", "The requested task must be known before planning."),
+    "object_id": ("What object or part should the robot move or process?", "The workpiece is required to create a deterministic goal."),
+    "source": ("Where should the robot pick up or start with the object?", "The source location is required to create the task goal."),
+    "destination": ("Where should the robot place or deliver the object?", "The destination is required to create the task goal."),
+    "payload_kg": ("What is the expected payload or part weight in kilograms?", "Commissioning qualification needs the payload instead of silently assuming one."),
+}
+
+
+class RequestCompletenessValidator:
+    """Deterministically decide whether enough information exists to proceed.
+
+    Critical fields marked uncertain by the model are treated as missing even if
+    the model emitted a guessed value. Commissioning requests additionally
+    require payload because payload materially affects physical qualification.
+    """
+
+    def assess(self, draft: EngineeringRequestDraft) -> RequestAssessment:
+        uncertain = set(draft.uncertain_fields)
+        required = list(_CORE_REQUIRED_FIELDS)
+        if draft.purpose is RequestPurpose.COMMISSIONING:
+            required.append("payload_kg")
+
+        missing_fields: list[str] = []
+        for field_name in required:
+            value = getattr(draft, field_name)
+            if value is None or field_name in uncertain:
+                missing_fields.append(field_name)
+
+        if missing_fields:
+            return RequestAssessment(
+                state=RequestState.NEEDS_INFORMATION,
+                missing=tuple(
+                    InformationRequest(field_name, *_QUESTIONS[field_name])
+                    for field_name in missing_fields
+                ),
+                open_items=self._open_items(draft),
+            )
+
+        return RequestAssessment(
+            state=RequestState.READY_FOR_VALIDATION,
+            open_items=self._open_items(draft),
+        )
+
+    @staticmethod
+    def _open_items(draft: EngineeringRequestDraft) -> tuple[str, ...]:
+        output: list[str] = []
+        if draft.tool is None:
+            output.append("tool_not_specified")
+        if draft.payload_kg is None:
+            output.append("payload_not_specified")
+        if draft.purpose in {RequestPurpose.SIMULATE, RequestPurpose.QUALIFY, RequestPurpose.COMMISSIONING} and not draft.variation.configured:
+            output.append("physical_variation_not_specified")
+        return tuple(output)
+
+
+def _default_runs(preset: TestPreset) -> int:
+    return {
+        TestPreset.QUICK: 25,
+        TestPreset.ENGINEERING: 250,
+        TestPreset.ROBUSTNESS: 1_000,
+        TestPreset.STRESS: 10_000,
+        TestPreset.CUSTOM: 250,
+    }[preset]
+
+
+class EngineeringRequestCompiler:
+    """Compile a complete AI draft into bounded deterministic engine input."""
+
+    def __init__(self, completeness: RequestCompletenessValidator | None = None) -> None:
+        self.completeness = completeness or RequestCompletenessValidator()
+
+    def compile(self, draft: EngineeringRequestDraft) -> ValidatedEngineeringRequest:
+        assessment = self.completeness.assess(draft)
+        if not assessment.ready:
+            if assessment.state is RequestState.NEEDS_INFORMATION:
+                raise EngineeringRequestError(
+                    "request_needs_information:" + ",".join(item.field for item in assessment.missing)
+                )
+            raise EngineeringRequestError("request_not_ready")
+
+        assert draft.robot is not None
+        assert draft.operation is not None
+        assert draft.object_id is not None
+        assert draft.source is not None
+        assert draft.destination is not None
+
+        rejection_codes: list[str] = []
+        if draft.robot not in CATALOG:
+            rejection_codes.append(f"unsupported_robot:{draft.robot}")
+        if draft.operation not in SUPPORTED_GOAL_ACTIONS:
+            rejection_codes.append(f"unsupported_operation:{draft.operation}")
+        if draft.runs is not None and draft.test_preset is not TestPreset.CUSTOM:
+            rejection_codes.append("runs_require_custom_test_preset")
+        if draft.test_preset is TestPreset.CUSTOM and draft.runs is None:
+            rejection_codes.append("custom_test_preset_requires_runs")
+        if rejection_codes:
+            raise EngineeringRequestError("request_rejected:" + ";".join(rejection_codes))
+
+        runs = draft.runs if draft.runs is not None else _default_runs(draft.test_preset)
+        hard_constraints = list(_SAFE_SYSTEM_CONSTRAINTS)
+        if draft.minimum_clearance_mm is not None:
+            hard_constraints.append("minimum_clearance")
+        if draft.max_cycle_time_s is not None:
+            hard_constraints.append("max_cycle_time")
+
+        canonical = {
+            "robot": draft.robot,
+            "operation": draft.operation,
+            "object_id": draft.object_id,
+            "source": draft.source,
+            "destination": draft.destination,
+            "tool": draft.tool,
+            "payload_kg": draft.payload_kg,
+            "purpose": draft.purpose.value,
+            "objective": draft.objective.value,
+            "test_preset": draft.test_preset.value,
+            "runs": runs,
+            "variation": asdict(draft.variation),
+            "faults": list(draft.faults),
+            "minimum_clearance_mm": draft.minimum_clearance_mm,
+            "max_cycle_time_s": draft.max_cycle_time_s,
+        }
+        digest = sha256(
+            json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        ).hexdigest()[:12]
+
+        return ValidatedEngineeringRequest(
+            request_id=f"REQ-{digest}",
+            robot_key=draft.robot,
+            operation=draft.operation,
+            object_id=draft.object_id,
+            source=draft.source,
+            destination=draft.destination,
+            tool=draft.tool,
+            payload_kg=draft.payload_kg,
+            purpose=draft.purpose,
+            objective=draft.objective,
+            test_preset=draft.test_preset,
+            runs=runs,
+            variation=draft.variation,
+            faults=draft.faults,
+            hard_constraints=tuple(hard_constraints),
+            minimum_clearance_mm=draft.minimum_clearance_mm,
+            max_cycle_time_s=draft.max_cycle_time_s,
+            open_items=assessment.open_items,
+        )
+
+
+def _reject_unknown(obj: Mapping[str, Any], allowed: set[str], name: str) -> None:
+    extra = set(obj) - allowed
+    if extra:
+        raise EngineeringRequestError(f"{name}_unknown_fields:" + ",".join(sorted(extra)))
+
+
+def parse_engineering_request_draft(payload: Mapping[str, Any]) -> EngineeringRequestDraft:
+    if not isinstance(payload, Mapping):
+        raise EngineeringRequestError("engineering_request_must_be_object")
+    allowed = {
+        "robot", "operation", "object_id", "source", "destination", "tool",
+        "payload_kg", "purpose", "objective", "test_preset", "runs",
+        "variation", "faults", "minimum_clearance_mm", "max_cycle_time_s",
+        "uncertain_fields", "notes",
+    }
+    _reject_unknown(payload, allowed, "engineering_request")
+
+    variation_raw = payload.get("variation") or {}
+    if not isinstance(variation_raw, Mapping):
+        raise EngineeringRequestError("variation_must_be_object")
+    _reject_unknown(
+        variation_raw,
+        {
+            "object_x_mm", "object_y_mm", "object_z_mm", "yaw_deg",
+            "payload_min_kg", "payload_max_kg", "speed_min_pct", "speed_max_pct",
+        },
+        "variation",
+    )
+    variation = PhysicalVariation(
+        object_x_mm=_optional_number(variation_raw.get("object_x_mm"), field_name="object_x_mm", minimum=0),
+        object_y_mm=_optional_number(variation_raw.get("object_y_mm"), field_name="object_y_mm", minimum=0),
+        object_z_mm=_optional_number(variation_raw.get("object_z_mm"), field_name="object_z_mm", minimum=0),
+        yaw_deg=_optional_number(variation_raw.get("yaw_deg"), field_name="yaw_deg", minimum=0),
+        payload_min_kg=_optional_number(variation_raw.get("payload_min_kg"), field_name="payload_min_kg", minimum=0),
+        payload_max_kg=_optional_number(variation_raw.get("payload_max_kg"), field_name="payload_max_kg", minimum=0),
+        speed_min_pct=_optional_number(variation_raw.get("speed_min_pct"), field_name="speed_min_pct", minimum=0.001, maximum=100),
+        speed_max_pct=_optional_number(variation_raw.get("speed_max_pct"), field_name="speed_max_pct", minimum=0.001, maximum=100),
+    )
+
+    try:
+        purpose = RequestPurpose(str(payload.get("purpose", RequestPurpose.SIMULATE.value)).strip().lower())
+        objective = Objective(str(payload.get("objective", Objective.BALANCED.value)).strip().lower())
+        test_preset = TestPreset(str(payload.get("test_preset", TestPreset.ENGINEERING.value)).strip().lower())
+    except ValueError as exc:
+        raise EngineeringRequestError("request_enum_invalid") from exc
+
+    faults = _string_tuple(
+        payload.get("faults"),
+        field_name="faults",
+        allowed={item.value for item in FaultIntent},
+    )
+    uncertain_fields = _string_tuple(payload.get("uncertain_fields"), field_name="uncertain_fields")
+    notes = _string_tuple(payload.get("notes"), field_name="notes")
+
+    return EngineeringRequestDraft(
+        robot=_clean_text(payload.get("robot"), field_name="robot"),
+        operation=_clean_text(payload.get("operation"), field_name="operation"),
+        object_id=_clean_text(payload.get("object_id"), field_name="object_id"),
+        source=_clean_text(payload.get("source"), field_name="source"),
+        destination=_clean_text(payload.get("destination"), field_name="destination"),
+        tool=_clean_text(payload.get("tool"), field_name="tool"),
+        payload_kg=_optional_number(payload.get("payload_kg"), field_name="payload_kg", minimum=0),
+        purpose=purpose,
+        objective=objective,
+        test_preset=test_preset,
+        runs=_optional_int(payload.get("runs"), field_name="runs", minimum=1, maximum=MAX_RUNS),
+        variation=variation,
+        faults=faults,
+        minimum_clearance_mm=_optional_number(payload.get("minimum_clearance_mm"), field_name="minimum_clearance_mm", minimum=0.001),
+        max_cycle_time_s=_optional_number(payload.get("max_cycle_time_s"), field_name="max_cycle_time_s", minimum=0.001),
+        uncertain_fields=uncertain_fields,
+        notes=notes,
+    )
+
+
+ENGINEERING_REQUEST_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": [
+        "robot", "operation", "object_id", "source", "destination", "tool",
+        "payload_kg", "purpose", "objective", "test_preset", "runs",
+        "variation", "faults", "minimum_clearance_mm", "max_cycle_time_s",
+        "uncertain_fields", "notes",
+    ],
+    "properties": {
+        "robot": {"type": ["string", "null"], "maxLength": 512},
+        "operation": {"type": ["string", "null"], "maxLength": 512},
+        "object_id": {"type": ["string", "null"], "maxLength": 512},
+        "source": {"type": ["string", "null"], "maxLength": 512},
+        "destination": {"type": ["string", "null"], "maxLength": 512},
+        "tool": {"type": ["string", "null"], "maxLength": 512},
+        "payload_kg": {"type": ["number", "null"], "minimum": 0},
+        "purpose": {"enum": [item.value for item in RequestPurpose]},
+        "objective": {"enum": [item.value for item in Objective]},
+        "test_preset": {"enum": [item.value for item in TestPreset]},
+        "runs": {"type": ["integer", "null"], "minimum": 1, "maximum": MAX_RUNS},
+        "variation": {
+            "type": "object",
+            "additionalProperties": False,
+            "required": [
+                "object_x_mm", "object_y_mm", "object_z_mm", "yaw_deg",
+                "payload_min_kg", "payload_max_kg", "speed_min_pct", "speed_max_pct",
+            ],
+            "properties": {
+                "object_x_mm": {"type": ["number", "null"], "minimum": 0},
+                "object_y_mm": {"type": ["number", "null"], "minimum": 0},
+                "object_z_mm": {"type": ["number", "null"], "minimum": 0},
+                "yaw_deg": {"type": ["number", "null"], "minimum": 0},
+                "payload_min_kg": {"type": ["number", "null"], "minimum": 0},
+                "payload_max_kg": {"type": ["number", "null"], "minimum": 0},
+                "speed_min_pct": {"type": ["number", "null"], "exclusiveMinimum": 0, "maximum": 100},
+                "speed_max_pct": {"type": ["number", "null"], "exclusiveMinimum": 0, "maximum": 100},
+            },
+        },
+        "faults": {"type": "array", "maxItems": MAX_LIST_ITEMS, "uniqueItems": True, "items": {"enum": [item.value for item in FaultIntent]}},
+        "minimum_clearance_mm": {"type": ["number", "null"], "exclusiveMinimum": 0},
+        "max_cycle_time_s": {"type": ["number", "null"], "exclusiveMinimum": 0},
+        "uncertain_fields": {"type": "array", "maxItems": MAX_LIST_ITEMS, "uniqueItems": True, "items": {"type": "string", "maxLength": 128}},
+        "notes": {"type": "array", "maxItems": MAX_LIST_ITEMS, "uniqueItems": True, "items": {"type": "string", "maxLength": 512}},
+    },
+}