Require explicit timing for atomic action trajectories

[yuecideng]

Description

This PR makes trajectory timing an explicit producer contract across motion planning and atomic actions.

• require every PlanResult containing positions to provide validated per-waypoint dt and matching per-environment duration
• require custom atomic actions to return TimedTrajectory instead of untimed position tensors
• remove fallback_control_dt and redundant planner/cadence/limit fields from MotionPolicy
• carry explicit interpolation cadence through PlanningContext.control_dt and MotionGenOptions.interpolation_dt
• preserve planner timing for direct actions and duration when resampling planner output
• migrate built-in actions, tasks, benchmarks, examples, and tutorials to the strict timing contract
• add a runnable control_dt.py tutorial comparing identical paths at two command periods
• update project context, design documentation, public documentation, and focused tests

The previous fallback behavior could silently assign execution timing to an incomplete planner or action result. The strict contract fails at the producer boundary and keeps planner-owned trajectory timing separate from integration-owned interpolation cadence.

Dependencies: None. The branch is based directly on the current main.

Issue reference: None.

Breaking API changes

• planner results with positions must include dt and duration
• AtomicAction.build_plan() accepts only TimedTrajectory
• fallback_control_dt is removed from the atomic-action engine and planning services
• deterministic interpolation requires an explicit interpolation period

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Enhancement (non-breaking change which improves existing functionality)
• New feature (non-breaking change which adds functionality)
• Breaking change (existing functionality requires caller migration)
• Documentation update

Screenshots

Not applicable. The new control-period tutorial can record fast and slow trajectory videos when run with --auto_play.

Validation

• black . — 667 files unchanged
• Apache headers, from __future__ import annotations, and public-module __all__ checks — passed for 54 changed Python files
• python -m compileall -q embodichain embodichain_tasks scripts examples tests — passed
• changed YAML files parsed with yaml.safe_load — passed
• git diff --check — passed
• focused pytest suite — 461 passed, 3 skipped, 14 deselected
• make -C docs html SPHINXOPTS=-q — passed

Checklist

• I have run the black . command to format the code base.
• I have made corresponding changes to the documentation.
• I have added tests that prove the change is effective.
• Dependencies are unchanged; no dependency update is required.

[greptile-apps]

Greptile Summary

This PR makes trajectory timing an explicit producer-owned contract throughout motion planning and atomic actions.

• Requires timed planner results and TimedTrajectory action outputs.
• Threads interpolation cadence through planning contexts and motion-generation options.
• Removes engine-owned timing fallbacks and migrates built-in actions, profiles, examples, documentation, and tests.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains in the eligible follow-up review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
embodichain/lab/sim/planners/utils.py	Enforces shape, device, finiteness, non-negativity, and duration consistency for explicitly timed planner results.
embodichain/lab/sim/planners/motion_generator.py	Requires interpolation cadence, normalizes explicit planner timing, and preserves per-environment duration during trajectory resampling.
embodichain/lab/sim/atomic_actions/plans.py	Defines and validates the strict TimedTrajectory contract used by atomic-action plans.
embodichain/lab/sim/atomic_actions/core.py	Rejects untimed action outputs at the framework boundary and requires actions to provide complete timed trajectories.
embodichain/lab/sim/atomic_actions/state.py	Adds optional explicit control cadence to planning contexts with a strict accessor for interpolation paths.
embodichain/lab/sim/atomic_actions/sim_adapter.py	Populates planning-context cadence from the simulation integration.
embodichain/lab/sim/skills/profiles.py	Moves optional planner compatibility into versioned skill policy presets and validates it when profiles are bound.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
A[Environment step_dt] --> B[PlanningContext control_dt]
B --> C[Action-owned interpolation]
C --> D[TimedTrajectory]
E[Planner backend] --> F[PlanResult with dt and duration]
F --> G[MotionGenerator normalization]
G --> D
D --> H[ActionPlan]
H --> I[Timed execution]

Loading

_{Reviews (3): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}