feat(sim): add authoritative scene registry

[yuecideng]

Description

Stack

• Layer: 2/28
• Base: refactor/atomic-actions-phase0
• Depends on: refactor(atomic-actions): establish snapshot identity bridge #485
• Followed by: feat(sim): add declarative scene and robot skill foundation #487

Add the authoritative SceneRegistry integration boundary with typed entity references, globally unique canonical IDs, normalized aliases, registry-derived snapshots/providers, and explicit parent relations.

Construction validates the complete collision-world contract—including dynamic subsets, geometry, batch mode, and planner capability—before execution. cuRobo receives canonical logical IDs end to end rather than a separately maintained task mapping.

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_scene.py, test_scene_curobo_integration.py, and tests/sim/planners/test_curobo_planner.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 introduces an authoritative scene registry that centralizes typed entity identities, aliases, pose and geometry providers, collision roles, and parent relationships.

• Adds registry-derived immutable snapshots and per-environment collision revision tracking.
• Adds construction-time agreement checks across registry, provider, motion generator, and planner collision contracts.
• Carries canonical obstacle IDs through cuRobo world generation, caching, and dynamic updates.
• Expands focused tests and documentation for identity, batching, collision geometry, and planner integration.

Confidence Score: 5/5

The PR appears safe to merge; no actionable correctness or security defects were identified.

The registry, snapshot provider, motion-generator validation, and cuRobo naming paths consistently preserve canonical identity and reject unsupported collision configurations before execution.

Important Files Changed

Filename	Overview
embodichain/lab/sim/skills/scene.py	Introduces typed scene registration, alias and parent validation, simulation adapters, immutable registry-derived providers, and collision integration checks.
embodichain/lab/sim/atomic_actions/state.py	Makes snapshot entity access defensive by copying entity state and pose tensors at construction and lookup.
embodichain/lab/sim/planners/motion_generator.py	Exposes planner collision contracts and validates configured IDs and bound pose keys before delegating updates.
embodichain/lab/sim/planners/curobo/curobo_planner.py	Adds canonical mapping-based obstacle identities, complete collision-world declarations, and dynamic sphere restrictions.
embodichain/lab/sim/planners/curobo/curobo_yaml.py	Generates cuRobo obstacle entries from explicit logical names while preserving representation-specific physical naming.
tests/sim/skills/test_scene.py	Provides broad coverage of registry identity, aliases, hierarchy, snapshots, revisions, batching, geometry, and simulation construction.
tests/sim/skills/test_scene_curobo_integration.py	Covers canonical registry-to-cuRobo geometry and dynamic collision integration.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    SIM[Simulation entities] --> REG[SceneRegistry]
    REG -->|canonical IDs and pose providers| PROVIDER[RegistrySceneProvider]
    REG -->|canonical IDs and geometry| WORLD[cuRobo world configuration]
    PROVIDER --> SNAPSHOT[SceneSnapshot]
    WORLD --> PLANNER[Motion planner]
    SNAPSHOT --> ACTIONS[Atomic actions]
    ACTIONS --> GENERATOR[MotionGenerator]
    GENERATOR -->|validated dynamic poses| PLANNER
    REG -. validates complete world, dynamic subset, and batch mode .-> GENERATOR

Loading

_{Reviews (1): Last reviewed commit: "docs(sim): document scene registry integ..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Introduces an authoritative semantic scene registry (SceneRegistry) as the integration boundary between semantic entity identity, atomic-action scene snapshots, and planner collision worlds. This establishes canonical typed entity references with alias normalization, registry-derived scene providers/snapshots, and pre-execution validation that planner collision-world configuration matches the registry contract (including batch-mode semantics and dynamic/static subsets).

Changes:

• Add embodichain.lab.sim.skills with SceneRegistry, typed SceneEntityRef variants, SceneEntityRegistration, and a RegistrySceneProvider that publishes canonical-ID SceneSnapshots with per-row collision revisions.
• Extend planner interfaces (BasePlanner, MotionGenerator, cuRobo planner/world/yaml) to expose and validate canonical collision-world IDs end-to-end and to support registry-backed obstacle-ID mappings (vs. UID-derived names).
• Add focused tests and documentation covering registry semantics, cuRobo ID binding, snapshot defensiveness, and collision-world validation.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/sim/skills/test_scene.py	New test suite for registry IDs/aliases, parent/native-name rules, provider revision behavior, and collision-world validation.
tests/sim/skills/test_scene_curobo_integration.py	Cross-layer test ensuring cuRobo binding uses canonical registry IDs (not simulation UIDs).
tests/sim/skills/init.py	Test package init for skill integration tests.
tests/sim/planners/test_motion_generator_batched.py	Adds tests for strict obstacle-ID validation in MotionGenerator.bind_collision_world() and planner metadata plumbing.
tests/sim/planners/test_curobo_planner.py	Adds tests for registry-backed obstacle naming, whitespace/string validation, and cuRobo collision-world metadata exposure.
tests/sim/atomic_actions/test_core.py	Adds coverage that SceneSnapshot owns/copies entity state and returns defensive reads.
embodichain/lab/sim/skills/scene.py	New core implementation: typed refs, registrations, immutable registry, geometry materialization, collision integration validation, and registry-derived scene provider.
embodichain/lab/sim/skills/init.py	Public exports for the new skills/scene registry module.
embodichain/lab/sim/planners/motion_generator.py	Adds canonical collision-world metadata accessors and tighter validation in collision-world binding.
embodichain/lab/sim/planners/curobo/curobo_yaml.py	Extends world-YAML generation to accept registry-backed Mapping[id, RigidObject] inputs and enforce canonical obstacle IDs.
embodichain/lab/sim/planners/curobo/curobo_planner.py	Supports registry-backed rigid-object mappings, exposes collision-world ID contracts, and uses mapping keys for cache identity/YAML generation.
embodichain/lab/sim/planners/base_planner.py	Defines default collision-world metadata properties for planners.
embodichain/lab/sim/atomic_actions/state.py	Hardens SceneSnapshot.entities by owning entity-state storage and returning defensive copies on read.
docs/source/tutorial/atomic_actions.rst	Updates tutorial to use SceneRegistry provider setup and documents canonical collision integration behavior.
docs/source/overview/sim/scene_registry.md	New overview doc describing registry ownership model, provider semantics, and full collision-world validation contract.
docs/source/overview/sim/planners/curobo_planner.md	Updates cuRobo docs to show registry-backed world construction and explains canonical ID semantics vs. physical YAML names.
docs/source/overview/sim/index.rst	Adds “scene registry” to sim overview and navigation.
docs/source/overview/sim/atomic_actions/index.md	Updates atomic-actions overview to reflect SceneRegistry canonical integration and snapshot immutability.
docs/source/api_reference/embodichain/embodichain.lab.sim.skills.rst	New API reference page for embodichain.lab.sim.skills.
docs/source/api_reference/embodichain/embodichain.lab.sim.rst	Adds the new skills submodule to the sim API reference toctree.
docs/design/declarative_expert_program_plan.md	Updates design-plan status and aligns wording with the registry integration work in this PR layer.
agent_context/topics/motion-planning/motion-planning.md	Updates agent context with canonical obstacle ID and registry/planner validation guidance.
agent_context/topics/atomic-actions/atomic-actions.md	Updates agent context to document SceneRegistry integration and snapshot defensiveness.
agent_context/MAP.yaml	Adds topic keywords and source-of-truth paths covering the new registry and collision-ID contracts.

---

💡 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.