feat(atomic-actions): reconcile terminal effect failures

agent_context/topics/atomic-actions/atomic-actions.md

@@ -442,15 +442,27 @@ asynchronous integrations instead pass `effect_result` explicitly on a due
 `step()` call.
 
 ```python
+import torch
+
 request = tick.pending_effect
 effect_result = EffectVerificationResult(
     verification_id=request.verification_id,
     success_mask=observed_success,
     failure_mask=observed_failure,
+    invalidation_mask=observed_failure,
+    retry_mask=torch.zeros_like(observed_failure),
 )
 result = runner.step(effect_result=effect_result)
 ```
 
+Both failure-policy masks must be subsets of `failure_mask`.
+`invalidation_mask` selects rows on which the core applies the request-owned,
+removal-only `failure_invalidation` delta; it does not let the verifier inject
+state. `retry_mask` is reserved for rows whose physical preconditions still
+make replay of the same invocation valid. Other failed rows require external
+recovery. Unresolved evidence at the action deadline is reconciled fail-closed
+when the pending effect covers active verified state.
+
 The semantic layer keeps physical observation separate from symbolic effect
 commit. `SkillPolicyPreset.effect_monitors` maps exact semantic call IDs to
 versioned, bounded-declarative `EffectMonitorRef` values. Omitting the mapping

docs/design/declarative_expert_program_plan.md

@@ -603,16 +603,22 @@ the affected row's assumed relation, and enter bounded recovery instead of
 repairing the scene. The runtime now exposes the active named motion phase,
 observes phase-scoped held-object invariants from fresh physical evidence, and
 applies removal-only ``StateDelta`` reconciliation to failed rows before any
-retry or recovery hand-off. ``Pick`` can use the existing bounded action retry;
-``Place`` and ``HandOver`` currently emit a typed ``RECOVERY_REQUIRED`` boundary
-because replaying the same invocation after its required relation was removed
-would be invalid. A workflow-level re-acquisition policy, blocking acquisition
-gates, per-expectation terminal failure reconciliation, and fail-closed
-reconciliation for evidence that remains unresolved at the action deadline
-remain explicit design decisions rather than implicit scene repair. For
-handover, success transfers the verified relation from source to destination
-while the destination remains physically closed. Releasing the destination is
-a separate ``Place`` or ``Release`` semantic call.
+retry or recovery hand-off. The monitor publishes one current-observation
+outcome per physical expectation, including the stronger proof that every
+clause reached its inverse band. ``Pick`` can use the existing bounded action
+retry. ``Place`` retries only when that complete inverse proof shows the source
+is still attached; otherwise it invalidates the relation and emits a typed
+``RECOVERY_REQUIRED`` boundary. ``HandOver`` always hands terminal failure to
+workflow recovery, retaining the source relation only when complete inverse
+evidence proves it is still attached. A verifier selects row-local retry versus
+external recovery, but the core owns the removal-only invalidation delta and
+applies it before either path. Evidence that remains unresolved at the action
+deadline is reconciled fail-closed: any active verified state covered by the
+pending effect is removed before external recovery. Workflow-level
+re-acquisition and blocking acquisition gates remain open; neither may repair
+the scene implicitly. For handover, success transfers the verified relation
+from source to destination while the destination remains physically closed.
+Releasing the destination is a separate ``Place`` or ``Release`` semantic call.
 
 The first pure-dynamics rollout uses the staged **B** continuation policy. The
 standard simulation factory lowers both trajectory ``control_dt`` and runner
@@ -1226,9 +1232,11 @@ implemented. Physical simulation acceptance is partial: Open Drawer and one
 cube Pick/Place/settle/validator cycle have completed. The embodiment-owned
 dual-UR5/PGI HandOver slice now completes Pick, transfer, terminal
 physical-effect verification, settling, and target validation through real
-contact dynamics; blocking acquisition gates, workflow-level re-acquisition,
-per-expectation terminal reconciliation, fault-injection coverage, and the full
-repeated-cube run remain validation or design work.
+contact dynamics. Per-expectation terminal outcomes, core-owned failure
+invalidation, row-local retry/recovery decisions, and fail-closed deadline
+reconciliation are implemented. Blocking acquisition gates, workflow-level
+re-acquisition, fault-injection coverage, and the full repeated-cube run remain
+validation or design work.
 
 Deliverables:
 
@@ -1485,10 +1493,11 @@ The design is complete when all of the following hold:
 - [ ] Physical held-object loss is observed as effect failure, invalidates the
       affected symbolic relation, and exercises bounded recovery rather than
       being hidden by a simulator-side attachment. The phase-aware observation,
-      row-local invalidation, bounded Pick retry, and typed recovery boundary
-      are implemented; blocking acquisition, per-expectation terminal
-      reconciliation, workflow-level re-acquisition, and real-simulation fault
-      injection remain open.
+      row-local core-owned invalidation, per-expectation terminal
+      reconciliation, fail-closed deadline handling, bounded Pick/retained-Place
+      retry, and typed recovery boundary are implemented; blocking acquisition,
+      workflow-level re-acquisition, and real-simulation fault injection remain
+      open.
 - [x] Repeated sub-threshold motion eventually publishes the correct scene
       revision.
 - [x] Custom actions have a documented and tested intentional hard-break

docs/source/overview/sim/atomic_actions/index.md

@@ -775,6 +775,8 @@ At the terminal waypoint, an `ExecutionSession` requests an external,
 correlated per-environment result before committing a non-empty effect:
 
 ```python
+import torch
+
 from embodichain.lab.sim.atomic_actions import EffectVerificationResult
 
 tick = session.tick(latest_context)
@@ -785,6 +787,8 @@ if tick.pending_effect is not None:
         verification_id=request.verification_id,
         success_mask=success_mask,
         failure_mask=failure_mask,
+        invalidation_mask=failure_mask,
+        retry_mask=torch.zeros_like(failure_mask),
     )
     tick = session.tick(latest_context, effect_result=effect_result)
 ```
@@ -797,6 +801,14 @@ and failure masks are disjoint subsets of the request mask; omitted request rows
 remain unresolved. Request IDs change after mask shrinkage or whole-action
 retry, so a delayed result cannot commit a newer attempt.
 
+Every result also classifies failed rows with `invalidation_mask` and
+`retry_mask`, both subsets of `failure_mask`. Invalidation applies the
+request's core-owned removal-only `failure_invalidation`; the verifier cannot
+inject replacement state. Retry is valid only when the same invocation's
+physical preconditions remain satisfied. Failed rows outside `retry_mask`
+enter external recovery, and unresolved evidence at the action deadline removes
+covered active verified state before recovery.
+
 `request.deadline` is expressed in the robot-observation timestamp domain.
 `RecoveryPolicy.action_timeout` covers both trajectory execution and the
 terminal effect wait; a retry invalidates the old request ID. With

docs/source/tutorial/atomic_actions.rst

@@ -489,6 +489,8 @@ correlated per-environment verification result:
 
 .. code-block:: python
 
+   import torch
+
    from embodichain.lab.sim.atomic_actions import EffectVerificationResult
 
    def verify_effect(context, request):
@@ -497,6 +499,8 @@ correlated per-environment verification result:
            verification_id=request.verification_id,
            success_mask=success_mask,
            failure_mask=failure_mask,
+           invalidation_mask=failure_mask,
+           retry_mask=torch.zeros_like(failure_mask),
        )
 
    result = runner.run_until_blocked(effect_verifier=verify_effect)
@@ -518,6 +522,8 @@ can later resume from the *current* pending request:
        verification_id=request.verification_id,
        success_mask=success_mask,
        failure_mask=failure_mask,
+       invalidation_mask=failure_mask,
+       retry_mask=torch.zeros_like(failure_mask),
    )
    resumed = runner.step(effect_result=verified)
    if resumed.is_waiting:
@@ -536,7 +542,13 @@ terminal effect wait. A result submitted after timeout cannot satisfy the new
 retry attempt because its old ID is invalid. The runner remembers the pending
 boundary even though the session emits its event only once. The durable state is
 ``tick.pending_effect`` (an ``EffectVerificationRequest``), not the presence of
-that one-time event.
+that one-time event. ``invalidation_mask`` and ``retry_mask`` must both be
+subsets of ``failure_mask``. Invalidation selects rows for the request's
+core-owned, removal-only ``failure_invalidation`` delta; a verifier cannot
+publish arbitrary replacement state. Set a retry row only when replaying the
+same invocation remains physically valid. Other failed rows enter external
+recovery after selected invalidation. Unresolved evidence at the action
+deadline is reconciled fail-closed when covered verified state is still active.
 
 Adding an action
 ----------------

embodichain/lab/sim/atomic_actions/__init__.py

@@ -59,6 +59,7 @@
     unregister_action,
 )
 from .execution import (
+    EffectExpectationResult,
     EffectVerificationRequest,
     EffectVerificationResult,
     ExecutionEvent,
@@ -262,6 +263,7 @@
     "EndpointCommandRouter",
     "EndpointCommandTransport",
     "EntityState",
+    "EffectExpectationResult",
     "EffectVerificationRequest",
     "EffectVerificationRequirement",
     "EffectVerificationResult",