feat(motion): add fixed-scene expert trajectory generation

.agents/skills/add-solver/SKILL.md

@@ -37,6 +37,10 @@ Plus two registration edits:
 - Add the docs page to the toctree in
   `docs/source/overview/sim/motion/solvers/index.rst`.
 
+Keep solver exports in the solver subpackage. The `motion` parent resolves
+subpackages lazily; do not add eager planner or workspace analyzer imports to
+the Robot initialization path.
+
 ## Steps
 
 ### 1. Gather Solver Requirements

.agents/skills/review-pr/references/review-matrix.md

@@ -127,11 +127,14 @@ and the `$add-task-program` read-only deployment inspector.
 
 ## Atomic actions, motion planning, and IK
 
-**Paths:** `embodichain/lab/sim/atomic_actions/**`, `planners/**`,
-`solvers/**`, and grasp/workspace utilities that feed plans.
+**Paths:** `embodichain/lab/sim/atomic_actions/**`,
+`embodichain/lab/sim/motion/{planners,solvers,workspace,expansion}/**`,
+and grasp utilities that feed plans.
 
 Check:
 
+- The `motion` parent and workspace analyzer exports retain lazy loading;
+  Robot initialization must not eagerly load planners or offline analyzers.
 - Goal, options, affordance, requirement, binding, plan, command, effect, and
   evidence types remain coherent across registration, planning, compilation,
   execution, tracking, and verification.

AGENTS.md

@@ -29,6 +29,7 @@ bundles official tasks as the **`embodichain_tasks`** import package.
 | Simulation world, objects, sensors, solvers, planning | `embodichain/lab/sim/` |
 | Gym environments and manager functors | `embodichain/lab/gym/` |
 | Task Program language, semantics, compiler, runtime and integrations | `embodichain/lab/task_program/` |
+| Fixed-scene trajectory host, rollout and persistence | `embodichain/lab/trajectory_generation/` |
 | Browser visualization | `embodichain/lab/visualization/` |
 | RL algorithms, policies, collectors and trainers | `embodichain/learning/rl/` |
 | Real-device controllers / standalone tools | `embodichain/lab/devices/`, `embodichain/toolkits/` |

agent_context/MAP.yaml

@@ -21,16 +21,47 @@ topics:
   - embodichain/lab/sim/objects/articulation.py
   - embodichain/lab/sim/objects/gizmo.py
   - embodichain/lab/gym/envs/base_env.py
+  - embodichain/lab/sim/motion/solvers/__init__.py
+  - embodichain/lab/sim/motion/planners/__init__.py
+  - embodichain/lab/sim/motion/workspace/__init__.py
+  - embodichain/lab/sim/motion/expansion/__init__.py
+  - embodichain/lab/trajectory_generation/initial_state.py
+  - embodichain/lab/trajectory_generation/integrations/sim.py
   watch_paths: [embodichain/lab/sim/sim_manager.py, embodichain/lab/sim/cfg.py, embodichain/lab/sim/objects/,
     tests/sim/]
   related_topics: [env-framework, robot-system, sensor-system, sim-visualization, ik-solvers, motion-planning,
     atomic-actions, rl-learning, configclass-pattern, robot-workspace]
   status: active
 - id: env-framework
   title: Environment Framework
-  aliases: [env framework, environment framework, task registration, list task, 环境框架, 任务环境]
-  keywords: [BaseEnv, EmbodiedEnv, EnvCfg, register_env, list-task, run-env, target_control_frequency,
-    sim_steps_per_control, step_dt, environment.component, embodiment.component, ControllerAction, EnvProfiler]
+  aliases:
+  - env framework
+  - environment framework
+  - task registration
+  - list task
+  - 环境框架
+  - 任务环境
+  - generation lease
+  - controlled episode preparation
+  - 受控初态准备
+  keywords:
+  - BaseEnv
+  - EmbodiedEnv
+  - EnvCfg
+  - register_env
+  - list-task
+  - run-env
+  - target_control_frequency
+  - sim_steps_per_control
+  - step_dt
+  - environment.component
+  - embodiment.component
+  - ControllerAction
+  - EnvProfiler
+  - acquire_generation_lease
+  - prepare_generation_episode
+  - generation_epoch
+  - FixedSceneHost
   paths: [topics/env-framework/env-framework.md]
   source_of_truth:
   - embodichain/cli/main.py
@@ -43,6 +74,7 @@ topics:
   - embodichain/lab/gym/envs/embodied_env.py
   - embodichain/lab/gym/envs/demo.py
   - embodichain/lab/gym/utils/profiler.py
+  - embodichain/lab/trajectory_generation/initial_state.py
   watch_paths: [embodichain/lab/gym/envs/base_env.py, embodichain/lab/gym/envs/embodied_env.py, embodichain/lab/gym/envs/demo.py,
     embodichain/lab/gym/utils/, embodichain/lab/gym/envs/task_program/, embodichain/cli/, embodichain/lab/scripts/run_env.py,
     embodichain_tasks/, tests/gym/envs/]
@@ -83,20 +115,51 @@ topics:
   - embodichain/lab/sim/motion/solvers/null_space_posture_task.py
   - embodichain/lab/sim/utility/solver_utils.py
   - embodichain/compute/kinematics/
+  - embodichain/lab/sim/cfg.py
+  - embodichain/lab/sim/motion/__init__.py
+  - embodichain/lab/sim/motion/solvers/srs_solver.py
+  - embodichain/lab/sim/motion/solvers/opw_solver.py
+  - embodichain/lab/sim/motion/solvers/pinocchio_solver.py
+  - embodichain/lab/sim/motion/solvers/differential_solver.py
   watch_paths: [embodichain/lab/sim/motion/solvers/, embodichain/lab/sim/utility/solver_utils.py, embodichain/compute/kinematics/,
     tests/sim/motion/solvers/, tests/compute/]
   related_topics: [simulation-system, robot-system, motion-planning]
   status: active
 - id: robot-system
   title: Robot System
-  aliases: [robot system, robot config, 机器人配置, 机器人系统]
-  keywords: [RobotCfg, control_parts, build_pk_serial_chain, DexforceW1Cfg, CobotMagicCfg, FrankaPandaCfg,
-    URRobotCfg, DualArmRobotCfg, merge_robot_cfg, JointDrivePropertiesCfg]
+  aliases:
+  - robot system
+  - robot config
+  - 机器人配置
+  - 机器人系统
+  - robot workspace
+  - workspace analysis
+  - 机器人工作空间
+  keywords:
+  - RobotCfg
+  - control_parts
+  - build_pk_serial_chain
+  - DexforceW1Cfg
+  - CobotMagicCfg
+  - FrankaPandaCfg
+  - URRobotCfg
+  - DualArmRobotCfg
+  - merge_robot_cfg
+  - JointDrivePropertiesCfg
+  - workspace
+  - RobotWorkspaceCfg
+  - RobotWorkspace
+  - WorkspaceAnalyzer
+  - reachability
   paths: [topics/robot-system/robot-system.md]
   source_of_truth:
   - embodichain/lab/sim/objects/robot.py
   - embodichain/lab/sim/robots/
   - embodichain/lab/sim/cfg.py
+  - embodichain/lab/sim/motion/workspace/__init__.py
+  - embodichain/lab/sim/motion/workspace/cfg.py
+  - embodichain/lab/sim/motion/workspace/runtime.py
+  - embodichain/lab/sim/motion/workspace/analyzer.py
   watch_paths: [embodichain/lab/sim/robots/, embodichain/lab/sim/objects/robot.py, embodichain/lab/sim/cfg.py]
   related_topics: [simulation-system, ik-solvers, motion-planning, sensor-system, sim-visualization, robot-workspace]
   status: active
@@ -137,9 +200,26 @@ topics:
 - id: motion-planning
   title: Motion Planning
   aliases: [motion planning, trajectory planning, motion expansion, trajectory expansion, trajectory augmentation, fixed scene trajectory augmentation, 轨迹扩增, 运动规划, 轨迹规划]
-  keywords: [BasePlanner, PlanState, PlanResult, MotionGenerator, ToppraPlanner, CuroboPlanner, NeuralPlanner,
-    expansion, GenerationSession, TrajectoryAugmentationCfg, CandidateTrajectoryBatch,
-    collision world, compute trajectory, trajectory resampling, trajectory warping]
+  keywords:
+  - BasePlanner
+  - PlanState
+  - PlanResult
+  - MotionGenerator
+  - ToppraPlanner
+  - CuroboPlanner
+  - NeuralPlanner
+  - expansion
+  - GenerationSession
+  - TrajectoryAugmentationCfg
+  - CandidateTrajectoryBatch
+  - collision world
+  - compute trajectory
+  - trajectory resampling
+  - trajectory warping
+  - GenerationRunner
+  - FixedSceneHost
+  - QposRolloutExecutor
+  - trajectory_generation
   paths: [topics/motion-planning/motion-planning.md]
   source_of_truth:
   - embodichain/lab/sim/motion/planners/base_planner.py
@@ -152,6 +232,25 @@ topics:
   - embodichain/lab/sim/motion/expansion/
   - embodichain/compute/trajectory/
   - embodichain/lab/sim/utility/action_utils.py
+  - embodichain/lab/sim/motion/__init__.py
+  - embodichain/lab/sim/motion/planners/neural_planner.py
+  - embodichain/lab/sim/motion/expansion/__init__.py
+  - embodichain/lab/sim/motion/expansion/contracts.py
+  - embodichain/lab/sim/motion/expansion/cfg.py
+  - embodichain/lab/sim/motion/expansion/operators.py
+  - embodichain/lab/sim/motion/expansion/coverage.py
+  - embodichain/lab/sim/motion/expansion/session.py
+  - embodichain/lab/trajectory_generation/runner.py
+  - embodichain/lab/trajectory_generation/execution.py
+  - embodichain/lab/trajectory_generation/initial_state.py
+  - embodichain/lab/trajectory_generation/integrations/sim.py
+  - embodichain/lab/trajectory_generation/integrations/planning.py
+  - embodichain/lab/trajectory_generation/sinks.py
+  - examples/sim/motion/trajectory_generation/free_motion.py
+  - examples/sim/motion/trajectory_generation/cube_grasp_parallel.py
+  - examples/sim/motion/trajectory_generation/cube_pickup_collection.py
+  - embodichain/lab/trajectory_generation/integrations/atomic.py
+  - embodichain/lab/trajectory_generation/integrations/contact.py
   watch_paths: [embodichain/lab/sim/motion/motion_generator.py, tests/sim/motion/test_motion_generator.py,
     tests/sim/motion/test_motion_generator_batched.py, embodichain/lab/sim/motion/planners/, embodichain/lab/sim/motion/expansion/,
     tests/sim/motion/expansion/, embodichain/lab/sim/utility/action_utils.py, embodichain/compute/trajectory/,

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

@@ -124,3 +124,18 @@ python docs/scripts/check_api_docs.py
 For public API changes also run the docs checker tests and Sphinx dummy build.
 For simulator adapters add an environment-level test that exercises normal
 `env.step()` consumption and safe cancellation.
+
+## Offline PickUp export for fixed-scene collection
+
+`lab/trajectory_generation/integrations/atomic.py::export_pickup_templates`
+exports a successful MoveEndEffector → PickUp compilation into protected phase
+qpos templates. It retains approach/close/lift boundaries, expands passive
+mimic geometry and appends real hold commands. Only transit permits residuals.
+`cube_pickup_collection.py` uses this source with full-state/contact validation
+and confirmed LeRobot persistence across repeated full-batch restoration.
+
+This is an offline atomic source: the qpos executor owns physical validation;
+no projected `HeldObjectState` is committed as observed evidence. It does not
+consume `initial_plan_provider` or run AtomicActionRuntime tracking/recovery.
+The runtime adapter and contact-aware Gym source/host matrix remain separate
+acceptance work. Keep the existing runtime and task-state contracts intact.

agent_context/topics/atomic-actions/execution.md

@@ -47,6 +47,16 @@ implementation `_plan(request, context)` hook.
 - `ExecutionRunner` drives that session against observation, command, and clock
   ports without blocking `step()`.
 
+For selected trajectory candidates, `engine.start(...,
+initial_plan_provider=provider)` materializes the first invocation's initial
+`ActionPlan` from the newly resolved request and current `PlanningContext`.
+The framework still binds collision options, authorizes command destinations,
+checks plan identities and scene revisions, and installs tracking and phase
+gates. The provider is consumed only during session construction; subsequent
+invocations and recovery use the registered skill planner. Rebuild the plan,
+binding-dependent effects, and session after reset instead of retaining runtime
+state from a previous rollout.
+
 ## PlanningContext invariants
 
 `PlanningContext` carries robot observation, scene snapshot, symbolic
@@ -90,6 +100,11 @@ Held-object guards and phase-effect gates are observational:
 Pick gates attachment before lift. Place gates detachment before retract.
 HandOver owns independent source/destination transfer boundaries.
 
+PickUp's ragged grasp sampling uses an explicit candidate mask. Empty rows and
+padding carry a safe current FK pose and cannot win selection; an entirely
+empty batch fails without candidate IK. Failed or non-finite IK outputs retain
+the preceding valid seed before later pickup stages are screened.
+
 ## Row-local state
 
 Vector environments share a synchronized call and command cursor, but success,

agent_context/topics/env-framework/env-framework.md

@@ -27,6 +27,8 @@ component ownership, path resolution, config-owned IDs, and task listing.
 Read [execution](execution.md) for hooks, bridge acceptance, reset ordering,
 wrappers, and replay. Read [profiling](profiling.md) only for instrumentation.
 
+For fixed-scene collection, see [generation preparation and explicit demo candidates](execution.md#fixed-scene-generation-preparation-base_envpy-embodied_envpy). The host owns a full-batch generation lease and validated preparation epochs.
+
 ## Timing contract
 
 `BaseEnv._configure_timing()` resolves `EnvCfg` before constructing the scene:

agent_context/topics/env-framework/execution.md

@@ -49,6 +49,68 @@ Read this when the request needs these details. [Topic overview](env-framework.m
 - A structured controller `TensorDict` may carry auxiliary fields such as
   `ik_success`, but it must contain at least one supported control key.
 
+### Explicit demonstration candidates (`demo.py`)
+
+- `execute_demo_episode(env, segments=...)` accepts one `DemoSegment` or a lazy
+  iterable of segments. Explicit segments bypass both task planning factories;
+  combining them with planning keyword arguments raises `ValueError` before
+  recording begins. An empty iterable executes no candidate and does not fall
+  back to task planning.
+- `segments=None` preserves `resolve_demo_segments()` and its legacy
+  `create_demo_action_list()` fallback. Both paths validate segment types lazily
+  and fill missing instructions from dataset metadata without changing the
+  supplied segment.
+- Explicit candidates use the same normal action processing, per-row masks,
+  validators, cancellation/abort handshake, and recording lifecycle as task
+  plans. Auto-reset remains suspended during execution; the caller owns the
+  later commit or discard boundary. Supplying a candidate does not restore its
+  initial state.
+- Focused coverage: `tests/gym/envs/test_demo.py` and the Task Program bridge
+  and completion tests under `tests/gym/envs/task_program/`.
+
+### Fixed-scene generation preparation (`base_env.py`, `embodied_env.py`)
+
+- `BaseEnv.acquire_generation_lease(owner)` reserves the complete environment
+  batch by owner identity. Same-owner acquisition is idempotent; other owners
+  are rejected. The generation flag disables auto-reset independently of demo
+  and replay flags. Ordinary `reset()` fails before seeding or state mutation
+  while the lease is held.
+- `EmbodiedEnv.prepare_generation_episode(owner, *, prepare, restore, settle,
+  verify)` is the full-batch discard-and-prepare boundary. Freeze prior episode
+  evidence first: this method clears camera buffers, expert/trajectory counts,
+  demo annotations, success state, and the active Task Program bridge without
+  saving pending episodes.
+- Preparation runs deterministic task/controller initialization, physical
+  restoration, settling, standard manager reset, and nonempty all-passed
+  `ValidationResult` verification
+  through trusted callbacks. It does not run startup/reset/interval events or
+  rewind environment/event RNGs. The host profile owns required initialization
+  and certifies any interval events that remain active during later rollouts.
+- Observation/history, reward, and dataset managers reset before verification;
+  `get_obs()` and `get_info()` then refresh the initial observation/task state,
+  and recording seeds from that settled state. Preparation does not use Gym
+  `step()` or write a training transition. Failure leaves stepping disabled.
+- `generation_epoch` advances on lease acquisition/release, every preparation
+  attempt, and normal resets. Failed preparation invalidates previous epochs.
+  `FixedSceneHost` in `embodichain/lab/trajectory_generation/initial_state.py`
+  matches candidate bindings against this epoch and verifies physical/task
+  initial state before publishing a `PreparedBatch` or Gym first frame.
+- `BaseEnv.observe_generation_commands(owner, callback)` observes a successfully
+  submitted `_step_action` command before physics. The observer requires the
+  same generation lease and does not issue a second command or step.
+  `execute_demo_episode` exposes `step_observer(result, active_before_step)` and
+  `row_step_limits` so the qpos executor records real returned observations and
+  stops each short row's recording before batch padding/holds.
+- `FixedSceneHost.initial_observation(binding)` copies the prepared Gym first
+  frame without a second `get_obs()` or history update.
+- `release_generation_lease(owner)` restores normal reset behavior without
+  saving, resetting, or modifying demo/replay flags. Callers serialize access;
+  the host remains the sole simulation stepper while the lease is active.
+- Focused coverage: `tests/gym/envs/test_fixed_scene_preparation.py`, including
+  real Gym lifecycle methods wired to `FixedSceneHost` through fake physical
+  ports; physical adapters have separate tests under
+  `tests/lab/trajectory_generation/`.
+
 ### Task Program completion (`embodied_env.py`, `task_program/bridge.py`)
 
 - `EmbodiedEnvCfg.task_program` remains opt-in. A registered task may attach

agent_context/topics/motion-planning/motion-planning.md

@@ -60,6 +60,8 @@ the object nor certifies the grasp.
 
 Focused augmentation tests live under `tests/sim/motion/expansion/`.
 
+Read [fixed-scene trajectory generation](trajectory-generation.md) for host restoration, qpos rollout, offline PickUp sources, contact validation, and confirmed dataset persistence.
+
 ## Choose the owning layer
 
 - `BasePlanner` and `PlanState` / `PlanResult` define planning interfaces.