feat(expert-program): add pre-simulation runtime catalog

[yuecideng]

Description

Stack

• Layer: 10/14
• Base: refactor/typed-tracking-contract
• Depends on: refactor(atomic-actions): add typed tracking contracts #501
• Followed by: feat(skills): add physical-effect workflows and recovery #480

Consolidation

Consolidates #502 and #503 into this layer. Scope: pre-simulation catalogs, semantic action presets, and registration-owned runtime extensions.
Add registration-owned standard runtime extension declarations and factories for transports, endpoint adapters, effects, policies, registered calls, and parallel safety. The catalog fingerprints the complete provider surface and creates fresh runtime instances under a serialized lifecycle.

This replaces environment attribute scanning with one explicit integration owner and keeps provider compatibility identical between preflight and live assembly.

Refs #471
Refs #474

Type of change

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

Screenshots

Not applicable.

Validation

• Focused coverage: tests/gym/envs/expert_program/test_extensions.py, catalog, bridge, simulation-environment, and parallel-runtime 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.

[greptile-apps]

Greptile Summary

The PR introduces a registration-owned pre-simulation catalog so provider compatibility, runtime extensions, policy presets, transports, and parallel-safety declarations can be validated consistently before live assembly.

• Adds immutable, fingerprinted integration catalogs and fresh runtime factories.
• Moves action-option ownership into typed schema-v2 policy presets.
• Connects registered transports, endpoint adapters, hold behavior, and parallel-safety validation to Expert Program runtime assembly.
• Updates the reference tasks, tutorials, documentation, and focused tests for the new contracts.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
embodichain/lab/gym/envs/expert_program/catalog.py	Adds the immutable integration catalog, fingerprint validation, live drift checks, and registration-owned runtime factories.
embodichain/lab/gym/envs/expert_program/extensions.py	Defines versioned endpoint, transport, and parallel-safety declarations with recursive immutability validation.
embodichain/lab/gym/envs/expert_program/environment.py	Makes runtime assembly consume registration-owned components and verifies transport and endpoint compatibility before freezing dispatch.
embodichain/lab/gym/envs/expert_program/bridge.py	Integrates registered command transports and hold behavior into sequential and parallel demonstration execution.
embodichain/lab/gym/envs/expert_program/simulation_environment.py	Connects simulation registrations to provider validation, fresh runtime assembly, segment policies, and parallel-safety creation.
embodichain/lab/sim/skills/compiler.py	Makes selected policy presets the authoritative action-option source while retaining compiler-owned dynamic target lowering.
embodichain/lab/sim/skills/integration.py	Validates schema-v2 policy templates against semantic target descriptors and reserves compiler-owned option fields.
embodichain/lab/sim/skills/parallel_runtime.py	Applies safety validation to synchronized merged command frames and preserves cancellation and safe-hold handling.
embodichain_tasks/embodichain_tasks/expert_program/open_drawer.py	Migrates the Open Drawer task to registration-owned declarations and preset-owned Slide options.
embodichain_tasks/embodichain_tasks/expert_program/repeated_pick_place.py	Migrates repeated pick-and-place to the pre-simulation registration and catalog assembly path.

Sequence Diagram

sequenceDiagram
participant Task as Task registration
participant Catalog as Integration catalog
participant Preflight as Provider-free preflight
participant Factory as Runtime factory
participant Runtime as Live Expert Program runtime
Task->>Catalog: Declare scene, profile, presets, adapters, transports, safety factory
Catalog->>Catalog: Validate immutability and compute fingerprint
Catalog->>Preflight: Supply provider-free manifests and extension surface
Preflight-->>Catalog: Confirm semantic and parallel compatibility
Factory->>Catalog: Revalidate fingerprint and live endpoint coverage
Catalog->>Factory: Create fresh providers and safety validator
Factory->>Runtime: Assemble compiler, engine, encoder, bridge, and policies
Runtime->>Runtime: Freeze transport routing before command dispatch

Loading

_{Reviews (6): Last reviewed commit: "wip" | Re-trigger Greptile}

[Copilot]

Pull request overview

Adds a registration-owned “standard runtime extensions” surface for Expert Program simulation integration, replacing ad-hoc environment scanning/overrides with explicit, fingerprinted declarations and factory-created runtime instances.

Changes:

• Introduces provider-free extension declarations (endpoint adapters, runtime transports, parallel safety factory) and validates their immutability + exact coverage.
• Threads ExecutionRunnerCfg/timeouts and preset-controlled coordinator cadence through the parallel runtime and Gym bridge/runtime assembly.
• Expands integration tests to assert fingerprint drift detection, frozen encoder behavior, and parallel-safety factory lifecycle/serialization.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/sim/skills/test_parallel_runtime.py	Adds assertions for runner-config-driven timeouts, completion-hold behavior, and minimum-cycle cadence in parallel runtime.
tests/gym/envs/expert_program/test_simulation_environment.py	Extends simulation environment tests for registration ownership, drift detection, custom endpoint/transport wiring, and safety validator lifecycle.
tests/gym/envs/expert_program/test_extensions.py	New: tests for standard extension declaration building, immutability rules, and fingerprint sensitivity (e.g., transport order).
tests/gym/envs/expert_program/test_catalog.py	Adds catalog validation for standard extension declarations, parallel safety requirements, and registration immutability constraints.
tests/gym/envs/expert_program/test_bridge.py	Tests encoder composition order, declared type enforcement, encoder freezing, and runner-cfg snapshotting into lazy parallel runtime creation.
embodichain/lab/sim/skills/parallel_runtime.py	Plumbs ExecutionRunnerCfg into ParallelSkillRuntime for timeouts, minimum-cycle cadence, and completion-hold policy.
embodichain/lab/gym/envs/expert_program/simulation_environment.py	Removes helper-side extension override seams; makes the factory consume extensions exclusively from SimulationExpertProgramRegistration.
embodichain/lab/gym/envs/expert_program/extensions.py	New: implements typed, provider-free extension declarations and deep immutability validation for fingerprint safety.
embodichain/lab/gym/envs/expert_program/environment.py	Enforces registration-owned extension ownership, freezes transport registration, validates live drift vs catalog, and assembles parallel safety validators from factory capability.
embodichain/lab/gym/envs/expert_program/catalog.py	Extends catalog fingerprinting/validation to include extension declarations and adds validation for “standard” call catalog/effect monitors/tracking metrics.
embodichain/lab/gym/envs/expert_program/bridge.py	Tightens transport encoder contracts via class-level declarations, adds deterministic transport composition order, and supports freezing registrations.
embodichain/lab/gym/envs/expert_program/init.py	Re-exports new extension declaration types as part of the Expert Program Gym API surface.
docs/source/overview/sim/atomic_actions/robot_skill_profiles.md	Updates docs to reflect registration-owned adapters/transports and immutability/declaration requirements.
docs/source/overview/sim/atomic_actions/expert_programs.md	Updates task integration guidance to pass a SimulationExpertProgramRegistration and explains standard-path extension ownership/limits.
docs/design/declarative_expert_program_plan.md	Design doc update describing the registration-owned standard runtime extension model and lifecycle guarantees.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.