feat(atomic-actions): reconcile terminal effect failures

[yuecideng]

Description

Stack

• Layer: 23/28
• Base: feat/semantic-effect-outcome-matrix
• Depends on: feat(skills): expose per-expectation effect outcomes #477
• Followed by: feat(skills): gate motion on physical effects #479

Make terminal physical-effect failures a core-owned, fail-closed state transition. Verification requests carry removal-only invalidation deltas; results classify failed rows into invalidation, same-invocation retry, or external recovery, and preserve per-expectation evidence for tracing.

The execution session now applies invalidation before recovery, rejects unsafe replay, and handles unresolved deadlines consistently. The semantic runtime translates monitor decisions into this single atomic-action contract instead of maintaining a second recovery/state path.

This intentionally tightens the typed effect-result API without a compatibility shim.

Refs #471
Refs #474

Type of change

• Breaking change (existing typed effect-result callers must provide the new reconciliation fields)
• Enhancement (non-breaking behavior improvement for migrated callers)

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_runtime.py — 142 passed
• Black 26.3.1 check on changed Python files

Checklist

• Changed Python files pass Black 26.3.1.
• Corresponding API, tutorial, design, and agent-context documentation is updated.
• Tests cover row-local invalidation, retry, timeout, and recovery hand-off.
• No dependency update is required.

[greptile-apps]

Greptile Summary

The PR adds core-owned reconciliation for terminal physical-effect failures and makes retry, invalidation, and external recovery explicit per environment.

• Extends verification requests and results with removal-only invalidation, retry masks, and per-expectation outcomes.
• Applies failure invalidation before retry or recovery and reconciles unresolved deadlines fail-closed.
• Maps semantic Pick, Place, and HandOver outcomes onto the unified execution-session contract.
• Updates tests, tutorials, design documentation, exports, and trace metadata for the expanded API.

Confidence Score: 5/5

The PR appears safe to merge; no concrete changed-code failure remains after reviewing row-local retry, invalidation, recovery, and timeout paths.

The execution session preserves retryable rows when other rows enter external recovery, scopes invalidation to selected environment masks, rebuilds requests after partial progress, and validates semantic expectation outcomes before policy selection.

Important Files Changed

Filename	Overview
embodichain/lab/sim/atomic_actions/execution.py	Adds typed per-expectation results, request-owned removal deltas, row-local failure reconciliation, and fail-closed timeout handling without an identified correctness defect.
embodichain/lab/sim/skills/runtime.py	Converts monitor decisions into explicit invalidation and retry policies for Pick, Place, and HandOver while preserving expectation evidence in traces.
embodichain/lab/sim/atomic_actions/init.py	Exports the new EffectExpectationResult public API.
tests/sim/atomic_actions/test_engine_per_env.py	Expands coverage for request-owned invalidation, retained state, external recovery, and unresolved timeout behavior.
tests/sim/skills/test_runtime.py	Covers per-expectation trace preservation and Place/HandOver terminal failure policy selection.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Terminal effect verification] --> B{Result received before deadline?}
    B -->|No| C{Covered verified state active?}
    C -->|Yes| D[Apply removal-only invalidation]
    D --> E[External recovery]
    C -->|No| F[Retry eligible rows]
    B -->|Yes| G{Row outcome}
    G -->|Success| H[Commit expected effect]
    G -->|Failed and retryable| I[Apply selected invalidation]
    I --> F
    G -->|Failed and not retryable| J[Apply selected invalidation]
    J --> E
    G -->|Unresolved| K[Keep pending request]

Loading

_{Reviews (1): Last reviewed commit: "feat(atomic-actions): reconcile terminal..." | Re-trigger Greptile}

[yuecideng]

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