feat(expert-program): add strict pre-simulation catalogs

[yuecideng]

Description

Stack

• Layer: 18/28
• Base: refactor/typed-tracking-contract
• Depends on: refactor(atomic-actions): add typed tracking contracts #501
• Followed by: feat(expert-program): configure semantic action options #503

Move Expert Program linking to task-owned, provider-free pre-simulation catalogs and reject opaque integration values. Gym registration, CLI startup, and environment construction now validate the exact declared scene/profile/call surface before live simulator assembly.

This removes global or introspective discovery paths and makes catalog fingerprints stable across registration and runtime creation.

Refs #471
Refs #474

Type of change

• Enhancement (non-breaking change which improves existing functionality)

Screenshots

Not applicable.

Validation

• Focused coverage: tests/gym/envs/expert_program/test_catalog.py, simulation-environment tests, Gym registration tests, and task configuration tests
• 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.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[greptile-apps]

Greptile Summary

The PR introduces immutable, task-owned Expert Program integration catalogs and validates their fingerprints during configuration loading and simulator assembly.

• Adds deterministic catalog fingerprinting and pre-simulation semantic-call linking.
• Propagates registrations through Gym configuration, CLI startup, and simulation factories.
• Converts the cube-pick-place and open-drawer tasks to explicit scene/profile/provider declarations.
• Adds focused coverage for catalog validation, registration, task configuration, and runtime assembly.

Confidence Score: 4/5

The PR appears safe to merge, with only a non-blocking type-annotation gap in the extended registration APIs.

The catalog and runtime wiring expose no established behavioral failure in the reviewed paths; the remaining issue is incomplete typing on public APIs changed to carry Expert Program registrations.

Files Needing Attention: embodichain/lab/gym/utils/registration.py

Important Files Changed

Filename	Overview
embodichain/lab/gym/envs/expert_program/catalog.py	Adds immutable integration declarations, canonical fingerprints, static preflight linking, and live-component consistency checks.
embodichain/lab/gym/envs/expert_program/simulation_environment.py	Replaces separately supplied simulation bindings and providers with one validated task-owned registration.
embodichain/lab/gym/utils/gym_utils.py	Loads Expert Programs against the registered catalog and performs preflight validation before environment construction.
embodichain/lab/gym/utils/registration.py	Stores Expert Program registrations on environment specifications, but the changed public registration APIs remain incompletely annotated.
embodichain_tasks/embodichain_tasks/multi_segments/cube_pick_place.py	Declares the cube-pick-place scene and robot integration through the new strict registration surface.
embodichain_tasks/embodichain_tasks/tableware/open_drawer.py	Declares the open-drawer articulation, target, and robot integration through the new catalog.

Sequence Diagram

sequenceDiagram
    participant Task as Task registration
    participant Gym as Gym config/CLI
    participant Catalog as Integration catalog
    participant Factory as Simulation factory
    participant Runtime as Expert Program runtime
    Task->>Catalog: Declare scene, profile, calls, providers
    Catalog->>Catalog: Snapshot and fingerprint
    Gym->>Catalog: Load and preflight program
    Catalog->>Catalog: Validate references and semantic calls
    Gym->>Factory: Construct with exact registration
    Factory->>Catalog: Assert declaration unchanged
    Factory->>Runtime: Build scene, profile, engine, policies
    Runtime->>Catalog: Validate live components

Loading

Prompt To Fix All With AI

### Issue 1
embodichain/lab/gym/utils/registration.py:99-102
**Incomplete registration API annotations**

The changed public registration APIs add the Expert Program registration contract while leaving several parameters and return types unannotated, preventing callers and static analysis from determining the complete accepted interface; annotate `register`, `register_env`, and `register_env_function` consistently.

---

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

_{Reviews (1): Last reviewed commit: "fix(expert-program): reject opaque catal..." | Re-trigger Greptile}

[greptile-apps]

Incomplete registration API annotations

The changed public registration APIs add the Expert Program registration contract while leaving several parameters and return types unannotated, preventing callers and static analysis from determining the complete accepted interface; annotate register, register_env, and register_env_function consistently.

Context Used: CLAUDE.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: embodichain/lab/gym/utils/registration.py
Line: 99-102

Comment:
**Incomplete registration API annotations**

The changed public registration APIs add the Expert Program registration contract while leaving several parameters and return types unannotated, preventing callers and static analysis from determining the complete accepted interface; annotate `register`, `register_env`, and `register_env_function` consistently.

**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!

[yuecideng]

Folded into #504 during stacked-PR consolidation. Its commits remain included in #504; the remote branch is retained for traceability.