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, registers their typed scene affordances, and automatically installs matching relation grounders.

• Adds capability-scoped placement defaults for object, articulation, and link parents.
• Resolves placement targets from current scene snapshots while enforcing configured confidence thresholds.
• Adds package exports and tests for declaration, registration, grounding, and default selection.

Confidence Score: 4/5

The PR appears safe to merge from a runtime perspective, with the non-blocking requirement that its newly exported placement APIs be documented.

The placement declaration, registry, and grounding paths maintain explicit parent typing, capability-scoped defaults, and late-bound pose resolution; the remaining accepted concern is missing documentation for the new public interfaces.

Files Needing Attention: embodichain/lab/gym/envs/expert_program/simulation.py

Important Files Changed

Filename	Overview
embodichain/lab/gym/envs/expert_program/simulation.py	Adds validated placement bindings and projects them into provider-free manifests and live scene registries; the public API lacks an in-PR documentation update.
embodichain/lab/gym/envs/expert_program/catalog.py	Automatically installs exact-version support and container relation grounders when corresponding scene declarations are present.
embodichain/lab/sim/skills/compiler.py	Adds typed relation grounders that preserve late pose resolution and affordance confidence thresholds.
embodichain/lab/sim/skills/scene.py	Defines the versioned support-surface and container affordance payload contracts.
tests/gym/envs/expert_program/test_simulation.py	Exercises placement declarations, capability-scoped defaults, live parent-relative poses, and confidence payloads.
tests/gym/envs/expert_program/test_catalog.py	Verifies automatic grounder installation and relation preflight integration.
tests/sim/skills/test_compiler.py	Verifies both built-in grounders produce late-bound targets with preserved confidence thresholds.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    B[Placement binding] --> M[SimulationSceneBinding]
    M --> R[SceneRegistry affordance]
    M --> D[Capability-scoped default]
    M --> G[Automatic relation grounder]
    D --> S[Semantic relation selection]
    S --> G
    G --> P[Late-bound SceneEntityPose]
    R --> P
    P --> A[Placement action planning]

Loading

Prompt To Fix All With AI

### Issue 1
embodichain/lab/gym/envs/expert_program/simulation.py:363
**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.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(skills): add declarative 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!