feat(skills): gate motion on physical effects

[yuecideng]

Description

Stack

• Layer: 24/28
• Base: feat/effect-failure-reconciliation
• Depends on: feat(atomic-actions): reconcile terminal effect failures #478
• Followed by: feat(skills): add physical-effect workflows and recovery #480

Add blocking physical-effect gates at named trajectory-segment entries. Pick verifies attachment before lift, Place verifies detachment before retract, and HandOver verifies destination attachment before source release.

Each gate has a fresh monitor, correlated request/result identity, row-local retry or recovery behavior, and holds the preceding real controller command while evidence is unresolved. Gates observe physics only; they do not commit symbolic state or mutate simulator object state.

Refs #471
Refs #474

Type of change

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

Screenshots

Not applicable.

Validation

• pytest -q tests/sim/atomic_actions/test_engine_per_env.py tests/sim/atomic_actions/test_runner.py tests/sim/skills/test_compiler.py tests/sim/skills/test_runtime.py tests/gym/envs/expert_program/test_simulation_environment.py — 225 passed
• Black 26.3.1 check on changed Python files

Checklist

• Changed Python files pass Black 26.3.1.
• Corresponding API, tutorial, and design documentation is updated.
• Tests cover segment binding, stale identities, row-local gates, retries, and recovery.
• No dependency update is required.

[greptile-apps]

Greptile Summary

The PR adds blocking, correlated physical-effect gates at named trajectory-segment boundaries so Pick, Place, and HandOver cannot begin safety-critical motion until fresh attachment or detachment evidence is available.

• Adds gate requirement, request, result, event, and verifier contracts to the atomic-action execution API.
• Integrates gate polling, deadline handling, retry behavior, stale-result rejection, and preceding-command replay into ExecutionSession and ExecutionRunner.
• Grounds independent gate monitors for Pick, Place, and HandOver and routes physical evidence through SkillRuntime.
• Adds focused compiler, runtime, runner, per-environment engine, and simulation-factory coverage plus API and design documentation.

Confidence Score: 5/5

The PR appears safe to merge; no concrete blocking or independently actionable non-blocking defect was identified.

The new gate lifecycle remains correlated across requests and attempts, blocks waypoint advancement while evidence is unresolved, replays the preceding synchronized command, and routes contradiction through bounded retry or recovery with focused test coverage.

Important Files Changed

Filename	Overview
embodichain/lab/sim/atomic_actions/execution.py	Adds the correlated segment-gate state machine, validation, command replay, deadlines, retries, events, and lifecycle cleanup without an identified actionable defect.
embodichain/lab/sim/atomic_actions/runner.py	Integrates synchronous gate verification into due-cycle observation and dispatch ordering while preserving external blocked-boundary behavior.
embodichain/lab/sim/skills/compiler.py	Grounds independent Pick, Place, and HandOver gate monitors against the intended named segments and physical expectations.
embodichain/lab/sim/skills/runtime.py	Correlates gate requests with fresh row-local evidence and converts monitor decisions into retry-aware gate results.
embodichain/lab/sim/atomic_actions/invocation.py	Adds validated invocation-local phase-effect gate requirements and preserves them through invocation construction.
tests/sim/atomic_actions/test_engine_per_env.py	Covers gate blocking, predecessor-command replay, stale identities, retries, deadlines, and row-local outcomes.
tests/sim/skills/test_runtime.py	Covers semantic runtime evidence collection, independent monitor behavior, and gate-result routing.

Sequence Diagram

sequenceDiagram
    participant C as SemanticSkillCompiler
    participant R as SkillRuntime
    participant E as ExecutionRunner
    participant S as ExecutionSession
    participant M as Gate EffectMonitor
    C->>R: Ground invocation and independent gate monitor
    R->>E: Step with gate verifier
    E->>S: Tick with fresh observation
    S-->>E: PhaseEffectGateRequest at segment entry
    E->>R: Verify correlated gate request
    R->>M: Observe current physical evidence
    M-->>R: Success, failure, or unresolved masks
    R-->>E: PhaseEffectGateResult
    E->>S: Apply correlated result
    alt unresolved
        S-->>E: Replay preceding cohort command
    else success
        S-->>E: Unlock next trajectory segment
    else contradiction
        S-->>E: Retry action or require recovery
    end

Loading

_{Reviews (1): Last reviewed commit: "feat(skills): gate motion on physical ef..." | Re-trigger Greptile}

[yuecideng]

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