Simplify atomic action planning contracts

[yuecideng]

Description

This PR simplifies the Atomic Action planning and runtime contracts, removes duplicated primitive logic, and establishes one authoritative path for validation, registration, and attachment state.

The previous design combined repeated per-primitive validation, a disconnected process-wide extension registry, a marker-only goal protocol, and parallel individual/coordinated attachment representations. This made extensions harder to reason about and allowed equivalent state to drift between abstractions.

Dependencies: none.

Issue: no issue is linked.

What changed

• Centralize goal, option, binding, and planning validation at the framework boundary.
• Share batched pose resolution, qpos repetition, trajectory assembly, and named-arm planning helpers across primitives.
• Keep action registration engine-local and remove the global extension catalog and unregistered planning escape hatch.
• Remove the marker-only ActionGoal protocol and goal_kind; each action declares and validates its concrete GoalType.
• Consolidate attachment state into TaskState.held_objects, including coordinated grasps represented by one HeldObjectState per manipulator.
• Derive trajectory duration from dt and share simulator command writing logic.
• Rename n_envs to num_envs across public APIs, implementations, tests, examples, and documentation.
• Update Atomic Action documentation and project agent context for the new contracts.

Breaking API migrations

• n_envs and n_envs= become num_envs and num_envs=.
• ActionGoal and goal_kind are removed; define an action-owned goal dataclass and set AtomicAction.GoalType.
• register_action, unregister_action, and get_registered_actions are removed; instantiate the action and call engine.register(action).
• engine.plan_action is removed; register the action and use engine.plan.
• Public request-resolution helpers are internalized; application code should use plan, compile, or start.
• CoordinatedHeldObjectState and the coordinated attachment map are removed; use per-manipulator HeldObjectState entries.

Type of change

• Breaking change (existing functionality requires migration)

Screenshots

Not applicable.

Validation

• conda run -n open black . — 905 files unchanged with Black 26.3.1.
• Targeted pytest suite — 244 passed, 7 skipped, 5 deselected.
• Python compilation of all 50 changed Python files.
• Apache header, future annotations, public __all__, and git diff --check checks.
• Repository-wide searches confirm no remaining n_envs or removed Atomic Action API symbols.
• conda run -n open make -C docs html — succeeded; the repository still emits pre-existing Sphinx warnings unrelated to this change.

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 refactor and migration work.
• No dependency updates are required.

[greptile-apps]

Greptile Summary

This follow-up adds exclusivity-aware attachment handling so single-arm actions cannot mutate one side of a shared multi-manipulator grasp.

• Consolidates attachment state into per-manipulator HeldObjectState entries.
• Adds shared-object detection and exclusive-hold masks.
• Applies exclusivity checks to movement, placement, handover, and coordinated placement.
• Simplifies action registration, goal validation, planning helpers, and public environment-count naming.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
embodichain/lab/sim/atomic_actions/state.py	Adds shared-physical-object detection and per-environment exclusive attachment masks.
embodichain/lab/sim/atomic_actions/primitives/coordinated_pickment.py	Represents a coordinated grasp using two attachment entries sharing the same semantic object.
embodichain/lab/sim/atomic_actions/primitives/move_held_object.py	Rejects transport rows where another manipulator holds the same object.
embodichain/lab/sim/atomic_actions/primitives/place.py	Prevents release of one side of a shared attachment while retaining empty-gripper placement behavior.
embodichain/lab/sim/atomic_actions/primitives/hand_over.py	Requires the source attachment to be exclusive before transferring ownership.
embodichain/lab/sim/atomic_actions/effects.py	Consolidates verified attachment updates into the sole per-manipulator held-object map.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Coordinated pick succeeds] --> B[Store one HeldObjectState per manipulator]
B --> C[Entries share object semantics]
C --> D[exclusive_held_object_mask]
D -->|Shared object detected| E[Reject single-arm move, release, or handover]
D -->|Exclusive object| F[Allow single-arm operation]

Loading

_{Reviews (2): Last reviewed commit: "fix(atomic-actions): guard shared held o..." | Re-trigger Greptile}