Add simulation-level Affordance sampling

[yuecideng]

Description

This PR adds reproducible, Affordance-owned pose sampling to simulation Atomic Actions. It uses PR #637 only as a design reference and delivers the implementation on a fresh branch based on main.

Key changes:

• add AffordanceSamplingContext, AffordancePoseCandidates, and the unified, owned AffordanceSample result;
• route PickUp, AxisAlign, HandOver, Slide, OpenDoor, Press, Twist, interaction points, and Assemble placement through Affordance sampling while keeping IK and complete trajectory feasibility in each Atomic Action;
• retain row-local success and publish sampling provenance in plan diagnostics;
• share branch argument validation, sampling-context construction, and per-row diagnostics across the parallel PickUp, AxisAlign, HandOver, OpenDoor, Press, Slide, and Twist simulation tutorials;
• keep Task Program, Gym lifecycle, retry/commit, and dataset integration explicitly deferred; and
• document the ownership boundary, supported geometric freedom, reproducibility limits, and direct-simulation host contract.

The review follow-up also deep-copies nested sampling metadata, updates the PickUp replan integration test to the AffordanceSample contract, and removes tutorial-focused sampling tests in favor of production-contract tests plus static tutorial validation.

Dependencies: none.

Refs #637

Type of change

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

Screenshots

Not applicable.

Validation

• black . — 1050 files left unchanged with Black 26.3.1
• black --check --diff --color ./ — passed
• pytest -q tests/sim/atomic_actions --tb=short — 834 passed, 1 skipped, 3 deselected
• pytest -q tests/lab/task_program/test_semantic_compiler.py --tb=short — 31 passed
• python docs/scripts/check_api_docs.py — 2081/2081 exports documented
• python .agents/skills/project-dev-context/scripts/context.py check — passed
• pytest -q -c /dev/null --noconftest tests/test_agent_context_map.py tests/test_agent_context_tools.py — 23 passed
• python -m py_compile for the seven sampling tutorials and shared tutorial_utils.py — passed

The interactive GPU simulation tutorials were not launched in this non-interactive validation environment.

Checklist

• I have run the black . command to format the code base.
• I have made corresponding changes to the documentation.
• Public API changes are reflected in the API docs (python docs/scripts/check_api_docs.py).
• I have added production-contract tests that prove the feature works.
• Dependencies have been updated, if applicable (no dependency changes required).

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no outstanding previous finding or actionable new regression remains.

Summary

This PR adds simulation-level, Affordance-owned pose sampling while leaving IK and trajectory feasibility with individual Atomic Actions.

• Introduces immutable sampling context, candidate, and result contracts with deterministic branch streams and owned provenance metadata.
• Integrates grasp, contact-roll, interaction-point, and assembly-symmetry sampling across supported Atomic Actions.
• Propagates sampling through planning contexts and publishes row-local diagnostics.
• Adds parallel direct-simulation tutorial wiring and documents the boundary excluding Task Program, Gym lifecycle, retries, and datasets.
• The changes since the previous review deep-copy nested metadata and remove tutorial-focused tests, fully addressing both previous findings.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Host[Direct simulation host] --> Context[AffordanceSamplingContext]
    Context --> Planning[PlanningContext]
    Planning --> Action[Atomic Action]
    Geometry[Affordance geometry] --> Candidates[Pose candidates]
    Candidates --> Affordance[Affordance sampling]
    Context --> Affordance
    Affordance --> Sample[AffordanceSample]
    Sample --> Action
    Action --> Feasibility[IK and trajectory feasibility]
    Feasibility --> Plan[Row-local ActionPlan]
    Sample --> Diagnostics[Sampling provenance]
    Diagnostics --> Plan

Loading

_{Reviews (3) · Last reviewed commit: "fix(atomic-actions): address affordance ..."}