feat(atomic-actions): add verified effect-aware runtime

[yuecideng]

Description

Stack

• Layer: 4/14
• Base: feat/semantic-skill-compiler
• Depends on: feat(sim): add semantic skill IR and compiler #492
• Followed by: feat(sim): add semantic runtime effects and parallelism #496

Consolidation

Consolidates #493 and #494 into this layer. Scope: row-local lifecycle, physical-effect monitors, and the verified atomic-action runtime.
Complete the typed verified-action runtime with physical effect requirements, stable held-object and articulation state, effect-aware plans, and the reusable OperateArticulation primitive.

Pick, Place, coordinated manipulation, HandOver, and articulation operations now expose explicit terminal effect boundaries and row-local state deltas. Verification observes real physics; it never creates synthetic attachments or teleports task objects.

Refs #471
Refs #474

Type of change

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

Screenshots

Not applicable.

Validation

• Focused coverage: tests/sim/atomic_actions, including articulation effects and per-environment execution
• 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 adds an effect-aware atomic-action runtime with row-local verification, eligibility, state updates, and recovery behavior.

• Adds correlated effect-verification requests and partial per-environment results.
• Preserves stable held-object and articulation state across execution boundaries.
• Extends Pick, Place, semantic runtime, documentation, and tests for effect-aware execution.
• Replaces the proposed articulation-specific operation with the existing open-loop Slide primitive and application-level verification.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains from the previously reported issues.

No blocking failure remains.

Important Files Changed

Filename	Overview
embodichain/lab/sim/atomic_actions/execution.py	Adds correlated, deadline-aware, row-local effect verification and state commitment to execution sessions.
embodichain/lab/sim/atomic_actions/runner.py	Integrates synchronous and asynchronous effect results with runner scheduling, eligibility changes, and safe-stop behavior.
embodichain/lab/sim/atomic_actions/effects.py	Extends row-local state-delta handling while preserving stable held-object identity and metadata.
embodichain/lab/sim/skills/runtime.py	Carries verified task state and eligible environment cohorts across semantic-call boundaries.
embodichain/lab/sim/atomic_actions/primitives/pick_up.py	Narrows semantic-object dependency monitoring to the reversible approach phase.
embodichain/lab/sim/atomic_actions/primitives/place.py	Declares terminal physical-effect verification and verified release-state updates for placement.
embodichain/lab/sim/objects/articulation.py	Adds stable articulation-state support used by effect-aware execution.
docs/source/api_reference/embodichain/embodichain.lab.sim.atomic_actions.rst	Documents the new effect-verification request, result, requirement, and plan-attempt contracts.

Sequence Diagram

sequenceDiagram
participant App
participant Runner as ExecutionRunner
participant Session as ExecutionSession
participant Physics as Simulation/Physics
participant Verifier as Effect Verifier
App->>Runner: step()
Runner->>Session: tick(fresh observation)
Session->>Physics: dispatch active-row command
Physics-->>Runner: updated observation
Session-->>Runner: EffectVerificationRequest
Runner->>Verifier: verify(context, request)
Verifier-->>Runner: EffectVerificationResult
Runner->>Session: tick(correlated result)
Session->>Session: commit successful row deltas
Session->>Session: retain unresolved rows
Session-->>App: completed, pending, or recovery status

Loading

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

[greptile-apps]

Public runtime APIs lack documentation

The package now publicly exports the articulation operation and related verification, diagnostics, and state APIs without documenting their construction, observation-provider requirements, effect lifecycle, or recovery semantics, contrary to the repository requirement to document public API changes.

Context Used: AGENTS.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: embodichain/lab/sim/atomic_actions/__init__.py
Line: 261-264
Comment:
**Public runtime APIs lack documentation**
The package now publicly exports the articulation operation and related verification, diagnostics, and state APIs without documenting their construction, observation-provider requirements, effect lifecycle, or recovery semantics, contrary to the repository requirement to document public API changes.
**Context Used:** AGENTS.md ([source](https://github.com/dexforce/embodichain/blob/main/AGENTS.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!

[Copilot]

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