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

[yuecideng]

Description

Stack

• Layer: 1/14
• Base: main
• Depends on: main (including the squash-merged Simplify atomic action planning contracts #517)
• 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.

This branch is rebased onto main after #517 was squash-merged. It preserves #517's simplified engine-local registry and unified HeldObjectState while applying this layer's snapshot, scene-registry, and robot-skill-profile work.

Refs #471
Refs #474

Type of change

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

Screenshots

Not applicable.

Validation

• Full test suite: 1499 passed, 111 skipped, 29 deselected
• Post-rebase affected suites: 403 passed, 5 skipped, 4 deselected
• Black 26.3.1: all 665 Python files unchanged
• Changed Python files: Apache headers 39/39, future annotations 39/39, and public-module exports pass
• Sphinx HTML build: successful (warnings are pre-existing/non-fatal)

Checklist

• Code passes 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, while integrating both foundations with atomic actions and motion planning.

• Adds an authoritative scene registry with canonical identity, immutable registration metadata, snapshot providers, collision geometry derivation, and planner integration validation.
• Adds resource-DAG-based robot skill profiles with typed endpoints, capability matching, deterministic bindings, resource claims, semantic commands, and policy presets.
• Updates atomic actions to use snapshot-grounded object identity, explicit scene dependencies, binding contracts, and stable partial-batch attachment semantics.
• Extends planner interfaces and cuRobo configuration to expose and validate collision-world identities, dynamic subsets, and batching modes.
• Adds focused documentation and test coverage for the new scene, profile, planner, and atomic-action contracts.

Confidence Score: 5/5

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

No blocking failure remains.

Important Files Changed

Filename	Overview
embodichain/lab/sim/skills/scene.py	Introduces canonical scene registration, registry-backed snapshots, collision geometry derivation, and provider/planner contract validation.
embodichain/lab/sim/skills/profiles.py	Implements declarative robot resources, typed endpoint adapters, capability-based skill resolution, immutable claims, commands, defaults, and presets.
embodichain/lab/sim/atomic_actions/core.py	Adds stable object identity, framework-owned scene dependency collection, and declarative skill binding contracts.
embodichain/lab/sim/atomic_actions/engine.py	Integrates robot skill profiles and semantic skill discovery into engine construction and action registration.
embodichain/lab/sim/planners/motion_generator.py	Exposes planner collision-world contracts and supports registry validation through the motion-planning facade.
embodichain/lab/sim/planners/curobo/curobo_planner.py	Connects canonical obstacle identities and dynamic collision-world metadata to the cuRobo backend.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
Registry[SceneRegistry] --> Provider[RegistrySceneProvider]
Registry --> Geometry[Collision geometry by canonical ID]
Provider --> Snapshot[SceneSnapshot]
Geometry --> Planner[MotionGenerator / Planner]
Snapshot --> Actions[AtomicAction planning]
Profile[RobotSkillProfile] --> Binding[Resolved skill and resource binding]
Binding --> Actions
Actions --> Planner

Loading

_{Reviews (3): Last reviewed commit: "style(atomic-actions): format rebased ch..." | 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.