feat(motion): add source-neutral generation foundation

[yuecideng]

Description

Add the source-neutral foundation for high-throughput expert trajectory generation.

This PR defines the shared contracts needed to combine Affordance and trajectory expansion across handwritten experts, MotionGenerator, Atomic Actions, and Task Program adapters. Runtime randomization and observation fan-out profiles are deliberately deferred until their physical and persistence owners exist. It intentionally keeps physical execution, fixed-scene restoration, candidate scheduling, and dataset persistence out of this layer.

Included

• Add source-neutral SourceAdapter boundary with handwritten-template and MotionGenerator PlanResult adapters.
• Add same-grid ActionPlanTemplateAdapter for explicit phase permissions.
• Add source-neutral CandidateSpec:
  • one slot-independent candidate identity;
  • separate Affordance and trajectory provenance;
  • compatibility key and estimated execution cost;
  • post-rollout observation profiles without creating extra physical candidates.
• Extend TrajectoryGenerationJobCfg into a reusable Generation Profile:
  • handwritten, MotionGenerator, Atomic Action, and Task Program source kinds;
  • reference-family budget;
  • Affordance proposal budget;
  • a single reference-family budget owned by scheduling;
  • FIFO or coverage-per-cost scheduling;
  • bounded in-flight execution settings.
• Add world-frame Affordance sampling provenance for selected poses, reference poses, row IDs, and geometric success.
• Add a same-grid ActionPlanTemplateAdapter and Atomic materialization helper.
• Add a call-scoped Atomic plan_transform hook:
  • normal ActionPlan is validated first;
  • collector-owned transform runs once for that planning call;
  • transformed ActionPlan is validated again before execution.
• Keep the API independent of Task Program and environment slot identity.

Deliberately excluded

• Task Program-specific Affordance collection;
• run-env collector routing;
• fixed-scene host and initial-state restoration;
• C>B candidate queues and physical slot scheduling;
• unified EpisodeSink implementation;
• measured rollout coordinator;
• coverage/cost execution policy.

Those belong in the next integration layer and should reuse these contracts instead of adding a second identity or configuration protocol.

Dependencies and relationship to existing PRs

• Add trajectory variants between fixed waypoints #651 and Use manipulability to diversify trajectory augmentation #643 are already merged and provide the trajectory expansion and manipulability algorithms used by these contracts.
• feat(motion): add fixed-scene expert trajectory generation #591 remains the future fixed-scene/physical-host integration.
• Add atomic runtime execution for augmented PickUp collection #594 remains the Atomic runtime execution layer on top of feat(motion): add fixed-scene expert trajectory generation #591.
• Add measured offline Affordance collection #653 contains an earlier Task Program/Gym-specific offline Affordance collector. Its generic world-frame provenance is included here, but its task-specific collector, configs, and measured Pick/Place validator are intentionally not included in this foundation.

Refs #670, #591, #594, #653

Validation

• Focused motion, expansion, Affordance, and Atomic tests: 475 passed.
• python docs/scripts/check_api_docs.py: 2259/2259 exports documented.
• Changed-file Black checks passed.
• git diff --check passed.
• Same-grid ActionPlan/template materialization is covered by focused Atomic tests; no physical/GPU rollout is claimed by this foundation PR.

Type of change

• Bug fix
• Enhancement
• New feature
• Breaking change
• Documentation update

Checklist

• I have run Black on changed files.
• I have added tests for the new contracts and call-scoped transform.
• Public API documentation coverage is aligned.
• Dependencies have been reviewed; no dependency changes are required.
• The design does not add Task Program DSL or task-specific configuration.

Follow-up decision for #591 / #594

The fixed-scene host, LeRobot sink, PickUp contact validator, and Atomic Runtime execution remain deferred. They belong in the Coordinator/PhysicalExecutor layer and should consume this source adapter and CandidateSpec contract rather than be copied into the foundation.

[greptile-apps]

Confidence Score: 4/5

[Medium risk] Adds motion generation foundation and task program integration.

The PR is not yet safe to merge because distinct Affordance branches can still be collapsed into one candidate.

Findings

1.  Affordance branches are collapsed ▶

Fix with agent prompt

### Issue 1
embodichain/lab/sim/motion/expansion/coordinator.py:311-316
When two distinct Affordance branches produce identical trajectory samples, this global trajectory-only fingerprint treats the second branch as a duplicate. Because Affordance provenance and the compatibility key are attached only after this check, the second branch never receives its own candidate identity and cannot be scheduled, losing its lineage.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR adds source-neutral generation contracts, source adapters, candidate coordination, and call-scoped Atomic plan transforms, with Task Program integration and a configured showcase. Physical execution remains behind host-owned interfaces.

• The remaining concern is the previously reported loss of distinct Affordance branches during candidate deduplication.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Source[Source adapter] --> Template[Trajectory template]
  Template --> Coordinator[Candidate coordinator]
  Coordinator --> Session[Generation session]
  Session --> Host[Host-owned execution and persistence]

Loading

_{Reviews (8) · Last reviewed commit: "Merge remote-tracking branch 'origin/mai..."}

[greptile-apps]

Affordance branches are collapsed

When two distinct Affordance branches produce identical trajectory samples, this global trajectory-only fingerprint treats the second branch as a duplicate. Because Affordance provenance and the compatibility key are attached only after this check, the second branch never receives its own candidate identity and cannot be scheduled, losing its lineage.

Prompt To Fix With AI

This is a comment left during a code review.
Path: embodichain/lab/sim/motion/expansion/coordinator.py
Line: 311-316

Comment:
**Affordance branches are collapsed**

When two distinct Affordance branches produce identical trajectory samples, this global trajectory-only fingerprint treats the second branch as a duplicate. Because Affordance provenance and the compatibility key are attached only after this check, the second branch never receives its own candidate identity and cannot be scheduled, losing its lineage.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.