feat(skills): add declarative placement relations

[yuecideng]

Description

Stack

• Layer: 12/14
• Base: feat/workflow-reacquisition
• Depends on: feat(skills): add physical-effect workflows and recovery #480
• Followed by: feat(expert-program): validate parallel joint segments #482
  Add reusable declarative placement relations for standard simulation scenes. SupportSurfaceAffordanceBinding and ContainerAffordanceBinding declare the desired object target frame relative to an explicit object, articulation, or link parent; registration installs the exact versioned relation grounder automatically.

Defaults remain capability-scoped and all target poses are resolved from fresh registry snapshots. The implementation never guesses a frame from an entity name, mesh, or bounding box, so new tasks using an existing placement capability need scene configuration rather than task-local motion code.

Refs #471
Refs #474

Type of change

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

Screenshots

Not applicable.

Validation

• pytest -q tests/gym/envs/expert_program/test_simulation.py tests/sim/skills/test_compiler.py tests/gym/envs/expert_program/test_catalog.py -k 'support or container or relation or placement' — 12 passed, 58 deselected
• Black 26.3.1 check on changed Python files

Checklist

• Changed Python files pass Black 26.3.1.
• Public API and usage documentation is completed by follow-up layer test(tasks): gate cube physical recovery #483.
• Tests cover declarations, defaults, live grounding, and automatic registration.
• No dependency update is required.

[greptile-apps]

Greptile Summary

The PR adds declarative support-surface and container placement relations, including validated scene bindings, capability-scoped defaults, live target grounding, and automatic grounder registration.

• Exposes and documents the new placement bindings, affordance payloads, and relation grounders.
• Projects placement declarations into scene manifests and live registries using explicit object, articulation, or link parents.
• Adds tests for defaults, live poses, confidence thresholds, and automatic registration.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
embodichain/lab/gym/envs/expert_program/simulation.py	Adds validated declarative placement bindings and projects their parent-relative target frames and defaults into manifests and registries.
embodichain/lab/gym/envs/expert_program/catalog.py	Automatically installs exact built-in relation grounders when the scene declares support-surface or container bindings.
embodichain/lab/sim/skills/compiler.py	Adds typed support-surface and container grounders that preserve late pose resolution and configured confidence thresholds.
embodichain/lab/sim/skills/scene.py	Defines the versioned placement affordance payloads and validates their confidence thresholds.
docs/source/api_reference/embodichain/embodichain.lab.gym.envs.expert_program.rst	Documents the newly exported declarative placement binding classes and their public members.
docs/source/api_reference/embodichain/embodichain.lab.sim.skills.rst	Adds API references for the built-in support-surface and container relation grounders.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
A[Placement binding] --> B[SimulationSceneBinding]
B --> C[Scene manifest and registry]
C --> D[Typed placement affordance]
B --> E[Automatic grounder registration]
D --> F[Semantic placement relation]
E --> F
F --> G[Late-bound SceneEntityPose]

Loading

_{Reviews (5): Last reviewed commit: "Merge branch 'main' into feat/placement-..." | Re-trigger Greptile}

[greptile-apps]

Document the public placement API

The newly exported placement bindings, affordance payloads, and relation grounders have no corresponding public documentation in this changeset, leaving users without guidance on declaration fields, registration behavior, or usage.

Context Used: CLAUDE.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: embodichain/lab/gym/envs/expert_program/simulation.py
Line: 363
Comment:
**Document the public placement API**
The newly exported placement bindings, affordance payloads, and relation grounders have no corresponding public documentation in this changeset, leaving users without guidance on declaration fields, registration behavior, or usage.
**Context Used:** CLAUDE.md ([source](https://github.com/dexforce/embodichain/blob/main/CLAUDE.md))
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!