[Proposal] Integrate trajectory variant expansion with Task Program execution

[yuecideng]

Proposal

Integrate fixed-waypoint trajectory variant expansion with Task Program planning and execution so a compiled program can produce and collect multiple executable demonstrations while preserving its Semantic Call, Atomic Skill, effect, recovery, and dataset contracts.

The host-independent operators and candidate contracts are introduced in PR #651, but Task Program integration is explicitly deferred there. This proposal covers the missing planning and lifecycle adapter rather than adding a new Task Program language primitive.

Motivation

Task Program currently lowers each Semantic Call to an Atomic Skill and executes the resulting ActionPlan through ExecutionSession and the normal Gym DemoSegment bridge. Replacing only the stored joint trajectory would not update the transport commands, tracking targets, segment indices, effect gates, or recovery metadata that the runtime actually consumes.

A supported integration would make it possible to:

• execute several variants of the same grounded call or complete program from the same verified initial state;
• preserve contact, hold, effect-verification, recovery, and task-success semantics;
• validate candidates using measured rollout evidence rather than planned targets;
• persist variant, seed, program, call, source, and geometry-family provenance with each accepted episode; and
• keep candidate generation independent of environment slots while retaining deterministic replay.

This is related to the trajectory-diversification goal in #634 and the implementation boundary documented in #651.

Proposed scope

1. Planning adapter

   • Add a collector-owned integration at the Atomic Skill planning boundary, after a normal ActionPlan is built and before it is installed in ExecutionSession.
   • Rebuild the complete command sequence, tracking data, timing, named segments, and relevant scene-dependency indices after applying a variant.
   • Reject plans that do not expose an explicit, phase-authorized qpos trajectory or that cannot preserve the skill's endpoint/effect contract.

2. Task Program and Atomic Skill contracts

   • Define trusted metadata for controlled joints, editable segments, operator permissions, Jacobian frame/column order, task rows, contact/hold windows, and validator requirements.
   • Keep variation policy in the collector/integration configuration; do not add executable or provider-specific behavior to program.yaml.
   • Preserve projected versus verified EffectAssurance semantics and all phase effect gates, held-object guards, and recovery boundaries.

3. Execution and batching

   • Start with sequential single-environment collection or candidates sharing one control-grid/phase layout.
   • Define how candidates with different duration or sample counts map to environment rows, phase events, settling, and env.step_dt.
   • Ensure recovery/replanning creates a fresh candidate from the latest context instead of reusing stale Jacobians or scene data.

4. Reset, validation, and persistence

   • Restore and verify the complete initial state before each candidate; include TaskState, object attachments, controller targets, and scene revisions where required.
   • Route accepted/rejected candidates through GenerationSession and the existing Demo/LeRobot persistence path, including idempotent commit receipts and partial-write failures.
   • Store program/call identity, candidate identity, seed, operator factors, source revision, geometry family, validation outcome, and actual rollout timing.

Acceptance criteria

• A supported sequential Task Program demo can generate at least two deterministic variants of one grounded call and execute them through the ordinary TaskProgramDemoBridge/Gym stepping path.
• Every candidate is represented by a complete executable ActionPlan; command payloads, tracking, named segments, effect gates, and recovery metadata remain internally consistent.
• Contact/hold endpoints and declared semantic waypoints remain exact, and candidates that fail motion, collision, effect, or task validation are excluded from persistence.
• Re-running with the same program, scene/initial-state identity, source revision, and seed reproduces candidate identities and factors.
• Accepted episodes contain variant provenance and are committed through the existing recorder/session lifecycle without duplicate commits.
• Focused tests cover planning, phase permissions, reset isolation, row selection, failure cleanup, persistence metadata, and deterministic replay.

Additional context

The first implementation should target one sequential manipulation program and one Atomic Skill family. Parallel calls, runtime-dependent branching, mid-program checkpoint/suffix expansion, and heterogeneous per-row phase schedules can follow after the single-call path has a complete validation and persistence contract.

The algorithm layer should remain under embodichain/lab/sim/motion/expansion/; Task Program integration belongs in the Atomic Skill planning boundary, simulation adapter, Gym demo lifecycle, and dataset persistence adapters.

Checklist

• I have checked that there is no similar issue in the repo (required)