feat(gym): add declarative expert program runtime

[yuecideng]

Description

Stack

• Layer: 6/14
• Base: feat/semantic-skill-runtime
• Depends on: feat(sim): add semantic runtime effects and parallelism #496
• Followed by: feat(agents): add strict expert program frontend #498
  Add the strict, versioned Expert Program configuration, decoder, loader, preflight compiler, lazy segment runtime, Gym demo bridge, simulation factory, settling policies, validators, and completion metadata.

The environment retains its normal env.step() cadence and dataset lifecycle. Expert Programs compile into the existing semantic/atomic runtime instead of creating a third workflow engine.

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, demo, settling, registration, and run-env integration 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 wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[greptile-apps]

Greptile Summary

The PR adds a strict, versioned Expert Program configuration and compilation pipeline that lazily lowers declarative semantic programs into the existing Gym action lifecycle.

• Adds schema decoding, loading, preflight compilation, sequential and parallel execution, simulation bindings, settling policies, validators, and completion metadata.
• Extends demonstration execution with processed actions, row-independent vector-environment failure handling, and an explicit emergency cancellation handshake.
• Integrates Expert Programs with EmbodiedEnv, run_env, configuration-path resolution, public APIs, documentation, and focused tests.

Confidence Score: 5/5

The PR appears safe to merge based on the reviewed changes, with no concrete actionable defects remaining.

The new compilation, lazy execution, cancellation, vector-row masking, and configuration paths preserve the existing environment-step lifecycle, and investigated failure paths were either explicitly handled or contradicted by repository behavior and tests.

Important Files Changed

Filename	Overview
embodichain/lab/gym/envs/demo.py	Extends segment execution with owned processed actions, per-row failure policies, emergency cancellation, stricter metadata, and preserved exception propagation.
embodichain/lab/gym/envs/expert_program/compiler.py	Introduces bounded preflight compilation and deterministic lazy expansion for sequential, repeated, segmented, and parallel programs.
embodichain/lab/gym/envs/expert_program/bridge.py	Bridges compiled segments into the existing env.step() cadence with buffered commands, lifecycle tracking, cancellation, and row eligibility.
embodichain/lab/gym/envs/expert_program/environment.py	Defines the adapter and factory boundaries used to compile programs, assemble semantic components, preflight execution, and create bridges.
embodichain/lab/gym/envs/expert_program/simulation_environment.py	Adds simulation observation, command-state evidence, scene snapshots, and runtime integration for Expert Programs.
embodichain/lab/gym/envs/expert_program/simulation_policies.py	Implements bounded simulation post-policies and settling behavior using ordinary environment steps.
embodichain/lab/gym/envs/embodied_env.py	Integrates Expert Program configuration and processed demo actions into environment execution and rollout recording.
embodichain/lab/scripts/run_env.py	Adds CLI/configuration loading for Expert Programs while preserving normal episode commit and abort handling.

Sequence Diagram

sequenceDiagram
    participant Config as Expert Program Config
    participant Loader as Decoder / Loader
    participant Compiler as Preflight Compiler
    participant Bridge as Lazy Demo Bridge
    participant Runtime as Semantic / Atomic Runtime
    participant Env as EmbodiedEnv
    Config->>Loader: Load strict versioned document
    Loader->>Compiler: Decode typed program
    Compiler->>Compiler: Validate resources, calls, and policies
    Compiler-->>Bridge: Compiled lazy segment stream
    loop Each segment and command
        Bridge->>Runtime: Observe and ground semantic call
        Runtime-->>Bridge: Controller-ready action
        Bridge->>Env: env.step(processed action)
        Env-->>Bridge: termination, failure, and metadata
    end
    Bridge-->>Env: Segment validation and completion metadata

Loading

_{Reviews (1): Last reviewed commit: "feat(gym): add declarative expert progra..." | Re-trigger Greptile}