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 makes task registration the owner of standard Expert Program runtime extensions and verifies that preflight declarations match live assembly.

• Adds immutable declarations and catalog fingerprints for endpoint adapters, ordered command transports, and parallel-safety factories.
• Builds fresh runtime assemblies with registered timing, transport, provider, and safety components.
• Extends parallel safety validation, documentation, and focused tests for registration integrity and lifecycle behavior.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete changed-code defect identified.

Registration declarations, fingerprint checks, live transport-order validation, immutable extension requirements, and fresh safety-validator creation consistently preserve the preflight-to-runtime contract.

Important Files Changed

Filename	Overview
embodichain/lab/gym/envs/expert_program/extensions.py	Adds strict immutable declarations and cross-validation for endpoint adapters, command transports, and parallel-safety coverage.
embodichain/lab/gym/envs/expert_program/catalog.py	Incorporates the complete extension surface into registration fingerprints and creates fresh registration-owned safety validators.
embodichain/lab/gym/envs/expert_program/environment.py	Assembles runtime components from registration-owned declarations and checks live transport order against the catalog.
embodichain/lab/gym/envs/expert_program/bridge.py	Expands transport contracts with static target and payload declarations and freezes registered command encoders.
embodichain/lab/gym/envs/expert_program/simulation_environment.py	Routes standard simulation assembly through the registration and creates live safety validators bound to the factory robot and simulation.
embodichain/lab/sim/skills/parallel_runtime.py	Strengthens parallel command validation and dispatch behavior around the authoritative safety gate.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    R[SimulationExpertProgramRegistration] --> D[Provider-free extension declarations]
    D --> C[Integration catalog and fingerprint]
    C --> P[Program preflight]
    R --> F[Simulation runtime factory]
    F --> A[Fresh runtime assembly]
    A --> E[Ordered command encoder]
    A --> S[Fresh parallel safety validator]
    P --> B[AtomicDemoBridge]
    E --> B
    S --> B
    B --> G[Gym environment step boundary]

Loading

_{Reviews (1): Last reviewed commit: "feat(expert-program): own standard runti..." | 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.