feat(sim): add declarative scene and robot skill foundation

[yuecideng]

Description

Stack

• Layer: 1/14
• Base: main
• Depends on: main
• Followed by: refactor(atomic-actions): generalize runtime endpoints #488

Consolidation

Consolidates #485 and #486 into this layer. Scope: snapshot identity, authoritative scene registration, and declarative robot skill profiles.
Add embodiment-owned RobotSkillProfile declarations: a generic resource DAG, typed endpoints, capability matching, deterministic defaults, immutable resource claims, semantic commands, and versioned policy presets.

Profile validation checks installed skills, robot control parts, joint ownership, endpoint overlap, configured solvers, commands, and presets. The resource model remains generic enough for future mobile and whole-body integrations without adding task-shaped fields.

Refs #471
Refs #474

Type of change

• New feature (non-breaking change which adds functionality)

Screenshots

Not applicable.

Validation

• Focused coverage: tests/sim/skills/test_profiles.py and test_integration.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 declarative scene registration and embodiment-owned robot skill profiles for the simulation action stack.

• Adds canonical scene identities, registry-backed snapshots, collision-world validation, and cuRobo integration.
• Adds resource DAGs, typed endpoint adapters, capability matching, immutable claims, command profiles, and policy presets.
• Grounds atomic-action object semantics in versioned scene snapshots and updates batched attachment identity handling.
• Extends tests and documentation for the new scene and skill-profile contracts.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
embodichain/lab/sim/skills/scene.py	Adds canonical scene registration, registry-backed observation, collision geometry mapping, and planner/provider consistency validation.
embodichain/lab/sim/skills/profiles.py	Introduces declarative resource graphs, endpoint adapters, capability resolution, claims, defaults, commands, and policy presets.
embodichain/lab/sim/atomic_actions/engine.py	Integrates bound robot skill profiles with action discovery, registration invalidation, and control-profile construction.
embodichain/lab/sim/atomic_actions/core.py	Adds explicit semantic identity handling, binding contracts, and scene-dependency hooks to the atomic-action core.
embodichain/lab/sim/atomic_actions/effects.py	Updates partial-batch held-object merges to preserve scalar semantics for retained rows.
embodichain/lab/sim/planners/curobo/curobo_planner.py	Exposes collision-world identity and batch contracts while validating dynamic obstacle update compatibility.
embodichain/lab/sim/planners/motion_generator.py	Adds planner collision-world metadata and validates dynamic scene bindings before planning.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Registry[SceneRegistry] --> Provider[RegistrySceneProvider]
  Registry --> Geometry[Collision geometry by canonical ID]
  Geometry --> Planner[MotionGenerator / cuRobo]
  Provider --> Snapshot[Versioned SceneSnapshot]
  Snapshot --> Engine[AtomicActionEngine]
  Profile[RobotSkillProfile] --> Binder[Resource and endpoint resolution]
  Binder --> Claims[Immutable ResourceClaim]
  Binder --> Commands[Lowered command profiles]
  Claims --> Engine
  Commands --> Engine
  Engine --> Action[Resolved atomic action]
  Action --> Planner

Loading

_{Reviews (2): Last reviewed commit: "feat(sim): add declarative robot skill p..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR introduces a declarative “robot skill profile” layer that lets atomic skills publish robot-independent resource/endpoint requirements, while embodiments provide a generic resource DAG (endpoints, capabilities, commands, defaults, and versioned policy presets) that can be validated and deterministically resolved against an AtomicActionEngine.

Changes:

• Add RobotSkillProfile / resource-graph binding, endpoint adapters, immutable claims, deterministic resolution, and versioned policy presets in embodichain.lab.sim.skills.
• Add a new atomic-skill-side contract model (SkillBindingContract, slots/endpoints/routes/capabilities/constraints) and wire it into SkillDescriptor + AtomicActionEngine.skills.
• Update built-in atomic action primitives to declare explicit binding contracts; add focused unit tests and documentation describing the new semantic binding path.

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/skills/test_profiles.py	New comprehensive tests for profile ownership, validation, endpoint adapters, claims, defaults, ambiguity handling, and preset snapshotting.
tests/sim/atomic_actions/test_control.py	Adds validation tests for command snapshot typing and command-name whitespace constraints.
embodichain/lab/sim/skills/profiles.py	Implements declarative robot resources/endpoints, endpoint adapters, binding/validation logic, claims, defaults, and policy presets.
embodichain/lab/sim/skills/init.py	Exposes the new profile/binding API from the skills package.
embodichain/lab/sim/atomic_actions/requirements.py	Adds robot-independent skill binding contracts, standard capability IDs, and disjointness constraints.
embodichain/lab/sim/atomic_actions/primitives/press.py	Declares the skill binding contract (endpoints/capabilities/commands/routes/constraints) for Press.
embodichain/lab/sim/atomic_actions/primitives/place.py	Declares the skill binding contract for Place.
embodichain/lab/sim/atomic_actions/primitives/pick_up.py	Declares the skill binding contract for PickUp.
embodichain/lab/sim/atomic_actions/primitives/move_joints.py	Declares the skill binding contract for MoveJoints (kept non-agent-visible).
embodichain/lab/sim/atomic_actions/primitives/move_held_object.py	Declares the skill binding contract for MoveHeldObject.
embodichain/lab/sim/atomic_actions/primitives/move_end_effector.py	Declares the skill binding contract for MoveEndEffector.
embodichain/lab/sim/atomic_actions/primitives/hand_over.py	Declares the skill binding contract for HandOver, including disjoint slot/resource constraints.
embodichain/lab/sim/atomic_actions/primitives/coordinated_placement.py	Declares the skill binding contract for CoordinatedPlacement.
embodichain/lab/sim/atomic_actions/primitives/coordinated_pickment.py	Declares the skill binding contract for CoordinatedPickment.
embodichain/lab/sim/atomic_actions/engine.py	Adds engine.skills, optional skill_profile binding at construction, and bind_skill_profile(); invalidates bound profiles on registration changes.
embodichain/lab/sim/atomic_actions/core.py	Extends SkillDescriptor with binding_contract and enforces route coverage for declared core roles; adds AtomicAction.binding_contract.
embodichain/lab/sim/atomic_actions/control.py	Adds ControlCommand.equivalent_to and strengthens snapshot/name validation in command profiles.
embodichain/lab/sim/atomic_actions/init.py	Re-exports the new requirements/contracts and capability constants.
docs/source/overview/sim/index.rst	Updates simulation stack overview to include robot skill profiles.
docs/source/overview/sim/atomic_actions/robot_skill_profiles.md	New conceptual/user documentation for robot skill profiles, endpoints/adapters, binding semantics, and constraints.
docs/source/overview/sim/atomic_actions/index.md	Integrates robot skill profiles into the atomic-actions overview and clarifies semantic vs direct-core binding boundaries.
docs/source/api_reference/embodichain/embodichain.lab.sim.skills.rst	Adds API reference sections for the new skill profile classes/errors.
docs/source/api_reference/embodichain/embodichain.lab.sim.atomic_actions.rst	Adds API reference sections for semantic resource contracts and capability constants.
docs/design/declarative_expert_program_plan.md	Updates the design plan to reflect PR2B (robot skill profiles) being implemented on the stacked branch.
agent_context/topics/atomic-actions/atomic-actions.md	Updates internal project context docs with the new profile/contract model and discovery boundaries.
agent_context/MAP.yaml	Extends topic index keywords/paths to include skill profiles and semantic resource contract docs.

---

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

[yuecideng]

Temporarily closing and reopening to trigger the full CI workflow after retargeting this consolidated root PR to main.