refactor(atomic-actions): establish snapshot identity bridge

[yuecideng]

Description

Stack

• Layer: 1/28
• Base: main
• Depends on: none
• Followed by: feat(sim): add authoritative scene registry #486

Establish the Phase 0 snapshot/identity bridge used by every later declarative layer. Stable semantic entity IDs become authoritative for object grounding, action scene dependencies are explicit, object motion is derived from captured snapshots, and partial-batch state merges preserve verified identity deterministically.

The change deliberately fails closed for missing explicit IDs and keeps only the documented legacy no-ID fallback. It does not add a second planner, runtime, or scene source of truth.

Refs #471
Refs #474

Type of change

• Breaking change (explicit semantic identities now fail closed instead of falling back to live state)

Screenshots

Not applicable.

Validation

• Focused coverage: tests/sim/atomic_actions/test_actions.py, test_core.py, and test_engine_per_env.py
• Final affected-suite regression on the stack tip: 1215 passed, 2 skipped, 8 deselected
• Changed Python files pass Black 26.3.1; the Sphinx build and rollout-report drift check pass at the stack tip

Checklist

• Changed Python files pass Black 26.3.1.
• Corresponding public/design documentation is included in this stack.
• Tests cover the affected behavior.
• No dependency update is required.

[greptile-apps]

Greptile Summary

The PR establishes stable semantic object identity and snapshot-backed pose grounding across atomic actions while preserving narrowly documented legacy fallbacks.

• Adds frozen ObjectSemantics.entity_id values and deterministic identity-aware partial state merging.
• Makes action scene dependencies explicit and derives held-object motion from verified attachment transforms.
• Adds snapshot-backed assembly anchors, planner configuration validation, focused tests, and supporting documentation.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete changed-code defect remaining after review.

Snapshot grounding, identity-aware state merging, transform composition, recovery dependencies, and obstacle naming remain internally consistent across the changed paths and their callers.

Important Files Changed

Filename	Overview
embodichain/lab/sim/atomic_actions/core.py	Introduces frozen semantic identities, stable identity comparison, and action-owned scene dependency collection without an accepted defect.
embodichain/lab/sim/atomic_actions/effects.py	Makes partial attachment merges identity-aware and deterministically preserves scalar semantics while previous rows remain active.
embodichain/lab/sim/atomic_actions/goals.py	Adds strict snapshot pose grounding with a documented deprecated live-entity fallback.
embodichain/lab/sim/atomic_actions/primitives/pick_up.py	Grounds the object pose once per planning attempt and consistently reuses it for grasping and attachment transforms.
embodichain/lab/sim/atomic_actions/primitives/hand_over.py	Verifies held-object identity and derives current object pose from measured FK plus the verified attachment transform.
embodichain/lab/sim/atomic_actions/primitives/place.py	Adds snapshot-backed assembly base poses and dependency tracking while retaining the documented legacy fallback.
embodichain/lab/sim/planners/curobo/curobo_planner.py	Validates dynamic obstacle names against the same rigid-object naming scheme used by world generation and caching.
embodichain/lab/sim/atomic_actions/trajectory_ops.py	Corrects three-segment allocation to round the complete weighted expression as documented.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    S[ObjectSemantics entity_id] --> G[PlanningContext SceneSnapshot]
    G --> P[Snapshot-grounded action planning]
    P --> D[Explicit scene dependencies]
    D --> R[Movement-triggered recovery]
    P --> E[Expected StateDelta]
    E --> M[Identity-aware partial merge]
    M --> H[Verified held-object state]
    H --> A[Attachment-derived object motion]

Loading

_{Reviews (1): Last reviewed commit: "docs(atomic-actions): define snapshot br..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Establishes the “Phase 0” snapshot/identity bridge for atomic actions by making stable semantic entity IDs (ObjectSemantics.entity_id) the authoritative grounding key, ensuring scene-motion dependencies reflect the exact snapshot poses consumed during planning, and hardening partial-batch state merges to preserve identity deterministically.

Changes:

• Add explicit semantic identity (entity_id) and strict snapshot-only grounding (with a deprecated live-entity fallback only when no explicit ID is provided).
• Introduce an action-owned scene dependency hook (AtomicAction._scene_dependencies) and update built-in primitives to declare dependencies consistent with the snapshot poses they consume.
• Tighten planner/trajectory utilities: validate cuRobo dynamic obstacle naming registration, improve CUDA device erroring in mask normalization, and fix trajectory segment split rounding.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/sim/planners/test_curobo_planner.py	Adds regression coverage for cuRobo dynamic-obstacle registration/name validation.
tests/sim/atomic_actions/test_trajectory_ops.py	Adds tests for CUDA-unavailable “cuda” device requests and corrected segment split rounding.
tests/sim/atomic_actions/test_core.py	Adds tests for semantic identity immutability, strict snapshot grounding, dependency collection, and deterministic partial merges.
tests/sim/atomic_actions/test_affordance.py	Adds coverage for AssembleAffordance pose shape/batch validation.
tests/sim/atomic_actions/test_actions.py	Updates primitive tests to use snapshot grounding (IDs + scene) and verify no live-pose reads.
scripts/tutorials/atomic_action/moving_target_recovery.py	Updates tutorial to set ObjectSemantics.entity_id for snapshot-grounded recovery.
embodichain/lab/sim/planners/utils.py	Makes CUDA-device requests fail closed when CUDA is unavailable (before querying current device).
embodichain/lab/sim/planners/curobo/curobo_planner.py	Validates dynamic obstacle names: uniqueness and membership in rigid_objects-derived names.
embodichain/lab/sim/atomic_actions/trajectory_ops.py	Fixes split_three_segments() rounding to round after multiplication (and drops numpy dependency).
embodichain/lab/sim/atomic_actions/primitives/place.py	Adds AssembleGoal.base_pose snapshot reference + dependency tracking; deprecates live base-entity fallback with warning.
embodichain/lab/sim/atomic_actions/primitives/pick_up.py	Grounds object pose via snapshot identity and records the semantic ID as a scene dependency; removes live-pose coupling.
embodichain/lab/sim/atomic_actions/primitives/move_held_object.py	Derives current object pose from observed EEF pose + verified object_to_eef, avoiding live entity reads.
embodichain/lab/sim/atomic_actions/primitives/hand_over.py	Verifies target identity matches held attachment and derives orientation from observed EEF + attachment transform; avoids misleading dependencies.
embodichain/lab/sim/atomic_actions/primitives/coordinated_pickment.py	Uses snapshot grounding for implicit initial pose and declares semantic dependency only when that path is used.
embodichain/lab/sim/atomic_actions/goals.py	Introduces _resolve_object_pose() and prevents dependency collection from descending into ObjectSemantics.
embodichain/lab/sim/atomic_actions/effects.py	Uses stable identity comparison for partial merges and preserves previous scalar semantics when any prior rows remain active.
embodichain/lab/sim/atomic_actions/core.py	Adds frozen ObjectSemantics.entity_id, identity comparison rules, and the _scene_dependencies hook used by build_plan().
embodichain/lab/sim/atomic_actions/affordance.py	Hardens AssembleAffordance.get_assemble_object_pose() input shape/type and batch compatibility checks.
docs/source/tutorial/atomic_actions.rst	Documents strict _plan() extension boundary and new snapshot/identity dependency semantics.
docs/source/overview/sim/planners/curobo_planner.md	Documents planner-local validation for dynamic obstacle names vs registered rigid objects.
docs/source/overview/sim/atomic_actions/index.md	Documents the hard extension boundary and identity-driven dependency semantics.
docs/source/overview/sim/atomic_actions/builtin_actions.md	Updates built-in action docs for identity grounding, dependency behavior, and deprecated live fallback paths.
docs/design/declarative_expert_program_plan.md	Updates design plan baseline and aligns Phase 0/PR1 bridge details with implemented identity + snapshot semantics.
agent_context/topics/motion-planning/motion-planning.md	Updates internal context doc to reflect new cuRobo config validation behavior.
agent_context/topics/atomic-actions/atomic-actions.md	Updates internal atomic-actions context with identity/grounding rules and dependency guidance.
agent_context/MAP.yaml	Extends topic indexing keywords and sources for the updated identity/grounding docs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[yuecideng]

Folded into #487 during stacked-PR consolidation. Its commits remain included in #487; the remote branch is retained for traceability.