embodichain.lab.sim.motion.expansion

The embodichain.lab.sim.motion.expansion package provides qpos contracts, constrained trajectory operators, measured coverage, and a generation session for simulation expert trajectories. The core algorithms do not directly import Gym or own simulation stepping. Public imports pass through embodichain.lab and embodichain.lab.sim initialization and therefore require the normal simulation dependencies.

This is the motion core for fixed-scene expert generation. Physical initial-state restoration, planning, rollout execution, task validation, and episode persistence must be supplied by separate host integrations. Those integrations provide actual observations and commands, validation evidence, and persistence confirmations; this package does not instantiate them.

CandidateIdentity	Candidate lineage independent of execution slots and their epochs.
CandidateTrajectoryBatch	Logical candidate rows with safe padding and no physical batch assumption.
CommitReceipt	Sink confirmation tied to stable episode/candidate IDs, never a slot.
ExpertEpisode	Frozen rollout evidence with causal obs[t], action[t], obs[t+1] pairs.
MotionSnapshot	One copied complete robot state; poses map local frames into the world.
SceneCase	A fixed scene and allowed initial state, with no live environment references.
TrajectoryAugmentationCfg	Local random seed, explicitly enabled factors, and geometry coverage limits.
TrajectoryGenerationJobCfg	Standalone generation job configuration; control periods remain host-owned.
TrajectoryPhase	An explicitly annotated half-open sample interval [start, stop).
TrajectoryTemplate	A full-joint qpos reference with arrival intervals and explicit permissions.
ValidationCheck	One mandatory check; unavailable and not-run checks cannot accept data.
ValidationResult	A fail-closed collection of required validation checks.
TrajectoryDescriptor	Measured joint geometry and elapsed times at uniform phase progress.
describe_trajectory	Describe an actual rollout without rewarding additional time samples.
CoverageIndex	Reserve near-distinct measured trajectories and count confirmed geometry.
rotate_grasp_about_object_axis	Rotate a reference grasp about an axis through a fixed object's origin.
joint_residual	Add one smooth, endpoint-preserving residual per allowed free phase.
retime	Retime permitted free phases and resample onto the host control clock.
validate_motion_limits	Check sampled finite-difference motion limits without asserting task success.
GenerationSession	Own one job's bounded candidates, budgets, evidence, and commit history.

Values and Evidence

SceneCase separates scene and initial-state identity from physical execution slots. MotionSnapshot copies robot positions and velocities, the robot root pose, entity poses, and dependency revisions. Pose validation checks finite proper SE(3) transforms, including rotation orthogonality and handedness. Tensor inputs are detached and cloned at construction; consumers must still treat the resulting owned tensors as read-only.

Templates declare the complete joint order and use explicit qpos values. dt[0] is zero and each subsequent dt is the positive arrival interval from the preceding sample. Phase ranges are half-open sample intervals [start_index, stop_index). Unannotated paths permit replay only; operators also require explicit template, phase, and controlled-joint permissions.

Candidate batches have shape (C, N, D_full), where the logical candidate count C does not prescribe the host’s physical batch size. valid_length selects actual samples. Padding holds the final valid position and uses zero time intervals; it is excluded from execution and recording. Extracting a row copies its tensor payload and retains aligned identity, phase, factor, and source-row metadata.

An ExpertEpisode contains T commands actually sent and T+1 observations and timestamps, including the terminal observation. Episode metadata accepts finite JSON values rather than live host objects. A validation result accepts only a nonempty collection of passing checks; not_run, failed, and unavailable remain distinct rejection states. This structural check does not generate physical evidence or certify the supplied checker.

Persistence uses stable episode, candidate, scene, and commit IDs. The commit ID remains fixed across write retries, while submission_id distinguishes each submission and its delayed receipt. A persistence receipt is an input contract; the package itself does not write or verify storage.

class embodichain.lab.sim.motion.expansion.SceneCase

A fixed scene and allowed initial state, with no live environment references.

Methods:

__init__(scene_case_id, initial_state_id, ...)

__init__(scene_case_id, initial_state_id, scene_signature, task_id, robot_profile_id, calibration_id='default')

class embodichain.lab.sim.motion.expansion.MotionSnapshot

One copied complete robot state; poses map local frames into the world.

Methods:

__init__(scene_case, joint_names, ...[, ...])

__init__(scene_case, joint_names, joint_positions, joint_velocities, root_pose, entity_poses=<factory>, dependency_revisions=<factory>)

class embodichain.lab.sim.motion.expansion.TrajectoryPhase

An explicitly annotated half-open sample interval [start, stop).

Phase endpoints are samples start_index and stop_index - 1. Unannotated samples remain unchanged by augmentation operators.

Methods:

__init__(phase_id, start_index, stop_index)

__init__(phase_id, start_index, stop_index, kind='free', allowed_operators=())

class embodichain.lab.sim.motion.expansion.TrajectoryTemplate

A full-joint qpos reference with arrival intervals and explicit permissions.

dt[0] is zero; every later interval is strictly positive. Empty phases and operator permissions permit replay only. EEF conversion is owned by an injected planning adapter before constructing this qpos contract.

Methods:

__init__(source_id, source_revision, ...[, ...])

__init__(source_id, source_revision, template_id, joint_names, positions, dt, phases=(), allowed_operators=(), validator_id='default', controlled_joint_indices=(), representation='qpos')

class embodichain.lab.sim.motion.expansion.CandidateIdentity

Candidate lineage independent of execution slots and their epochs.

Methods:

__init__(scene_case_id, initial_state_id, ...)

__init__(scene_case_id, initial_state_id, candidate_id, geometry_family_id, source_id, source_revision, template_id, attempt_id=0, parent_id=None)

class embodichain.lab.sim.motion.expansion.CandidateTrajectoryBatch

Logical candidate rows with safe padding and no physical batch assumption.

positions is (C,N,D_full), dt is (C,N), and each valid_length is in [1,N]. An empty candidate set uses C=0. Padded positions hold the final valid sample and padded intervals are zero. They must never be executed or recorded; use valid_mask.

Methods:

__init__(positions, dt, valid_length, ...[, ...])
row(index)	Copy one candidate and its aligned metadata, retaining padded shape.

Attributes:

valid_mask

Return a fresh boolean mask selecting actual samples in each row.

__init__(positions, dt, valid_length, identities, joint_names, phases=(), factors=(), source_row_indices=None)

row(index)

Copy one candidate and its aligned metadata, retaining padded shape.

Parameters:

index (int) – Nonnegative candidate row index.

Return type:

CandidateTrajectoryBatch

Returns:

An owned single-row batch with shape (1, N, D_full) and aligned metadata.

property valid_mask: Tensor

Return a fresh boolean mask selecting actual samples in each row.

Returns:

A boolean tensor of shape (C, N) that excludes padded samples.

class embodichain.lab.sim.motion.expansion.ValidationCheck

One mandatory check; unavailable and not-run checks cannot accept data.

Methods:

__init__(check_id, status[, detail, metrics])

__init__(check_id, status, detail='', metrics=<factory>)

class embodichain.lab.sim.motion.expansion.ValidationResult

A fail-closed collection of required validation checks.

Methods:

__init__(checks)

Attributes:

accepted

Return whether every required check was run and passed.

__init__(checks)

property accepted: bool

Return whether every required check was run and passed.

Returns:

True only for a nonempty result whose checks all have passing status.

class embodichain.lab.sim.motion.expansion.ExpertEpisode

Frozen rollout evidence with causal obs[t], action[t], obs[t+1] pairs.

Observations and timestamps contain T+1 samples, including the terminal observation. Actions contain the T commands actually submitted. This contract checks structure; hosts remain responsible for measuring evidence.

Methods:

__init__(identity, observations, actions, ...)

__init__(identity, observations, actions, timestamps, action_representation, validation, episode_id, commit_id, phases=(), metadata=<factory>)

class embodichain.lab.sim.motion.expansion.CommitReceipt

Sink confirmation tied to stable episode/candidate IDs, never a slot.

The idempotent commit_id remains fixed across persistence retries. submission_id identifies an individual write attempt so a delayed failure cannot invalidate a newer retry of the same episode.

Methods:

__init__(episode_id, candidate_id, ...[, ...])

__init__(episode_id, candidate_id, attempt_id, storage_id, commit_id, scene_case_id, confirmed=True, error='', submission_id=0)

Configuration and Preflight

TrajectoryAugmentationCfg owns the local seed, provided-start declaration, spatial and timing factors, and joint-geometry coverage limits. TrajectoryGenerationJobCfg adds the nested source, planning, execution, reset, validation, collection, and persistence sections used by a standalone generation job. Both from_mapping methods reject unknown fields and invalid types or ranges. validate_semantics rechecks mutable configuration objects.

The initial schema requires planning.batch_mode: env_rows, execution.pool_mode: per_env_case, execution.scheduler: full_batch, provided initial states, and synchronous persistence. It limits each candidate to one rollout attempt. Write retries reuse the same episode and commit ID. Other scheduling modes, overlapping planning and physics, and unsupported enabled factors are rejected. Control periods remain owned by the host.

Configuration IDs, including the default lerobot sink name, do not create services. validate_capabilities requires explicit trusted source, validator, profile, sink, and operator registries; configuration values are not imported or evaluated. In particular, accepting a restoration profile ID or a supplied via_points capability does not implement physical restoration or an EEF planner in this package. Deployment preflight must still verify those services.

class embodichain.lab.sim.motion.expansion.TrajectoryAugmentationCfg

Local random seed, explicitly enabled factors, and geometry coverage limits.

Methods:

from_mapping(data)	Decode closed nested fields without executing configuration values.
validate_semantics()	Recheck typed nested values, including mutations made after decoding.

classmethod from_mapping(data)

Decode closed nested fields without executing configuration values.

Parameters:

data (Mapping[str, Any]) – Nested augmentation settings using the declared configuration fields.

Return type:

TrajectoryAugmentationCfg

Returns:

A decoded configuration with semantic constraints validated.

validate_semantics()

Recheck typed nested values, including mutations made after decoding.

Return type:

None

class embodichain.lab.sim.motion.expansion.TrajectoryGenerationJobCfg

Standalone generation job configuration; control periods remain host-owned.

Methods:

from_mapping(data)	Decode the supported nested YAML schema and reject unknown fields.
validate_capabilities(*, source_ids, ...[, ...])	Require IDs and enabled operators in explicitly supplied registries.
validate_semantics()	Validate configuration without loading hosts, profiles, or sources.

classmethod from_mapping(data)

Decode the supported nested YAML schema and reject unknown fields.

Parameters:

data (Mapping[str, Any]) – Nested job settings for source, augmentation, execution, and collection.

Return type:

TrajectoryGenerationJobCfg

Returns:

A decoded job configuration with semantic constraints validated.

validate_capabilities(*, source_ids, validator_ids, profile_ids, sink_ids, operators=())

Require IDs and enabled operators in explicitly supplied registries.

This is a preflight step in addition to semantic decoding. Registry membership asserts that the caller has already resolved trusted implementations; it does not itself certify physical validation.

Parameters:

• source_ids (Collection[str]) – Available trusted trajectory source identifiers.

• validator_ids (Collection[str]) – Available trusted validator identifiers.

• profile_ids (Collection[str]) – Available preparation, state, validation, and motion-limit profiles.

• sink_ids (Collection[str]) – Available episode sink identifiers.

• operators (Collection[str]) – Implemented spatial and timing operator names.

Return type:

None

validate_semantics()

Validate configuration without loading hosts, profiles, or sources.

Return type:

None

Operators, Coverage, and Session

rotate_grasp_about_object_axis derives TCP pose candidates from a reference grasp, rotating its position and orientation about an object-local axis through the fixed object origin. The caller selects rotations appropriate to the object’s geometry, such as quarter turns for a cube, and replans each candidate. The operator does not move the object or establish contact/IK validity.

joint_residual samples one smooth residual per explicitly permitted free phase and preserves its endpoints and uncontrolled joints. retime rescales permitted free phases and resamples on the supplied host control period, remapping phase indices. Contact and hold durations are preserved. Generated paths still need dynamic, collision, and task checks. validate_motion_limits supplies a sampled finite-difference speed and acceleration check; it does not assert collision freedom or task success.

describe_trajectory computes phase-aligned normalized joint geometry and elapsed-time descriptors from actual observations. CoverageIndex reserves capacity before persistence and counts geometry only after confirmation. Timing variants share geometry-family membership. This first descriptor uses joint geometry; it does not provide EEF workspace coverage.

GenerationSession owns scene-case registration, stable candidate identity, local random streams, bounded candidate and pending-episode payloads, collection budgets, coverage reservations, and commit accounting. Its lifecycle accepts planning results and measured episode evidence without stepping or resetting a host. Duplicate receipts do not increment committed counts, and failed writes release collection and coverage reservations before an explicit write retry.

embodichain.lab.sim.motion.expansion.rotate_grasp_about_object_axis(object_pose, grasp_pose, *, axis, angles)

Rotate a reference grasp about an axis through a fixed object’s origin.

The axis is expressed in the object’s local frame. Both the grasp position and orientation rotate about that axis; the object itself is unchanged. For example, a cube permits quarter-turn variants of a centered top grasp. The caller owns object symmetry and grasp validity: arbitrary rotations need not preserve contacts. Every candidate requires fresh IK/path planning and physical grasp validation. This function does not modify a qpos template.

Parameters:

• object_pose (Tensor) – Object transform in the scene frame, shape (4, 4).

• grasp_pose (Tensor) – Reference TCP transform in that same frame, shape (4, 4).

• axis (Tensor) – Finite nonzero object-local rotation axis, shape (3,).

• angles (Tensor) – Finite rotation angles in radians, shape (C,), with C > 0.

Return type:

Tensor

Returns:

Owned candidate TCP transforms with shape (C, 4, 4), using the object pose’s device and dtype, in the original scene frame.

Raises:

ValueError – If transforms, axis, or angles are malformed or nonfinite.

embodichain.lab.sim.motion.expansion.joint_residual(template, *, joint_limits, normalized_scale, generator)

Add one smooth, endpoint-preserving residual per allowed free phase.

This operator applies only to explicitly permitted joint-space motion. Cartesian contact constraints require a planning adapter and cannot be inferred from qpos. It changes only the declared controlled joints.

Parameters:

• template (TrajectoryTemplate) – Annotated full-joint reference.

• joint_limits (Tensor) – Finite lower/upper limits with shape (D, 2).

• normalized_scale (float) – Maximum offset as a fraction of each joint range.

• generator (Generator) – Explicit local generator; global RNG is never consumed.

Return type:

TrajectoryTemplate

Returns:

A new template requiring path and physical validation.

Raises:

ValueError – If permissions, limits or resulting positions are invalid.

embodichain.lab.sim.motion.expansion.retime(template, *, duration_scale, control_dt, max_samples=1000000)

Retime permitted free phases and resample onto the host control clock.

Contact and wait durations, phase endpoints, and inter-phase intervals are preserved. Phase boundaries must already align with the host clock. Scaled phase durations round up to whole control steps; sample counts therefore change. The function does not claim dynamic or collision validity.

Parameters:

• template (TrajectoryTemplate) – Reference containing explicitly permitted retime phases.

• duration_scale (float) – Positive factor; greater than one slows free motion.

• control_dt (float) – Authoritative host control period in seconds.

• max_samples (int) – Allocation bound for the resulting trajectory.

Return type:

TrajectoryTemplate

Returns:

A new uniformly timed template with remapped phase indices.

Raises:

ValueError – If permissions, timing or allocation constraints fail.

embodichain.lab.sim.motion.expansion.validate_motion_limits(template, *, velocity_limits, acceleration_limits)

Check sampled finite-difference motion limits without asserting task success.

Parameters:

• template (TrajectoryTemplate) – Timed full-joint path to check.

• velocity_limits (Tensor) – Positive per-joint speed bounds, shape (D,).

• acceleration_limits (Tensor) – Positive per-joint acceleration bounds, shape (D,).

Return type:

ValidationResult

Returns:

A single motion_limits check with maximum normalized ratios.

class embodichain.lab.sim.motion.expansion.TrajectoryDescriptor

Measured joint geometry and elapsed times at uniform phase progress.

Parameters:

• phase_ids (tuple[tuple[str, str], ...]) – Ordered phase identities, including contact/free mode.

• geometry (Tensor) – Normalized joint samples, with shape (P, S, D).

• timing (Tensor) – Elapsed seconds within each phase, with shape (P, S).

Methods:

__init__(phase_ids, geometry, timing)

__init__(phase_ids, geometry, timing)

embodichain.lab.sim.motion.expansion.describe_trajectory(positions, timestamps, joint_limits, *, phases=(), samples_per_phase=32)

Describe an actual rollout without rewarding additional time samples.

Geometry is sampled by normalized joint arc length within each phase. Timing includes the phase duration, including stationary waits. Unlabelled gaps are included as separate phases so no measured movement is silently discarded.

Parameters:

• positions (Tensor) – Actual joint positions with shape (T, D).

• timestamps (Tensor) – Strictly increasing observation timestamps, shape (T,).

• joint_limits (Tensor) – Finite lower/upper joint limits, shape (D, 2).

• phases (tuple[TrajectoryPhase, ...]) – Optional half-open ranges in the actual observation sequence.

• samples_per_phase (int) – Number of progress samples, at least two.

Return type:

TrajectoryDescriptor

Returns:

Owned CPU descriptor separating geometry from timing.

Raises:

ValueError – If samples, limits, times or phase ranges are invalid.

class embodichain.lab.sim.motion.expansion.CoverageIndex

Reserve near-distinct measured trajectories and count confirmed geometry.

One instance belongs to one scene case. Pending writes occupy capacity but do not contribute to formal coverage. A timing variant cannot increase the geometry count even if small physical tracking differences are measured.

Parameters:

• geometry_tolerance (float) – Maximum normalized joint difference for near copies.

• target_per_geometry (int) – Maximum distinct timing variants per geometry.

• timing_tolerance_s (float) – Maximum timing difference for duplicate episodes.

Methods:

__init__(*[, geometry_tolerance, ...])
confirm(commit_id)	Confirm a reserved commit; repeated confirmations are idempotent.
release(commit_id)	Release an uncommitted reservation after write failure.
reserve(commit_id, geometry_family_id, ...)	Reserve a distinct measured rollout before submitting its payload.

Attributes:

geometry_count

Number of distinct geometries with a confirmed persistence receipt.

__init__(*, geometry_tolerance=0.01, target_per_geometry=4, timing_tolerance_s=1e-06)

confirm(commit_id)

Confirm a reserved commit; repeated confirmations are idempotent.

Parameters:

commit_id (str) – Previously reserved persistence identity.

Return type:

None

property geometry_count: int

Number of distinct geometries with a confirmed persistence receipt.

Returns:

The number of geometry groups containing at least one confirmed commit.

release(commit_id)

Release an uncommitted reservation after write failure.

Parameters:

commit_id (str) – Previously reserved persistence identity.

Raises:

ValueError – If persistence has already been confirmed.

Return type:

None

reserve(commit_id, geometry_family_id, descriptor)

Reserve a distinct measured rollout before submitting its payload.

Parameters:

• commit_id (str) – Stable, unique persistence identity.

• geometry_family_id (str) – Family shared by proposed timing variants.

• descriptor (TrajectoryDescriptor) – Descriptor calculated from the actual execution.

Return type:

bool

Returns:

False for a near duplicate or a geometry whose quota is full.

class embodichain.lab.sim.motion.expansion.GenerationSession

Own one job’s bounded candidates, budgets, evidence, and commit history.

This value-only session never reads an environment or steps a simulator. Call mark_rollout_started only after the first actual command. A sink must provide one final outcome per submission and persist commit_id idempotently across retries. Contradictory final receipts are rejected. The caller serializes operations. Cancellation means stopping new work and releasing individual candidates; pending writes still require final receipts. Byte limits include tensor data and serialized value metadata, excluding Python object allocation overhead. The runner separately bounds host buffers and any copies it allocates outside this session.

Parameters:

• cfg (TrajectoryGenerationJobCfg) – Semantically valid job settings, copied on construction.

• clock (Callable[[], float]) – Monotonic seconds, injectable for deterministic budget tests.

Methods:

__init__(cfg, *[, clock])
accept_episode(episode)	Reserve passed measured evidence for writing; rejected evidence releases its slot.
add_planned(batch, validation)	Atomically admit validated candidate rows within ready count and byte limits.
apply_receipt(receipt)	Apply a final submission result to its original identity, idempotently.
episode_ids(identity)	Return the deterministic episode and idempotent commit IDs for an attempt.
mark_rollout_started(identity)	Count an assigned candidate once its first command actually ran.
propose(case_id, initial_state_id, *, ...[, ...])	Allocate stable lineage and a local CPU RNG independent of execution slots.
register_case(case, joint_limits, *, joint_names)	Register immutable case conditions and complete joint normalization limits.
release(identity, *[, reason])	Discard uncommitted work while preserving its failure reason and checks.
retry_write(commit_id)	Re-reserve a failed payload and return a copy plus its next submission ID.
snapshot()	Return read-only counters, case coverage, and lightweight lifecycle audit.
take_ready(case_id, initial_state_id, *[, ...])	Reserve a row, rollout attempt, and pending payload capacity before execution.

Attributes:

stop_reason

Report exhausted collection budgets while allowing outstanding results to finish.

__init__(cfg, *, clock=<built-in function monotonic>)

accept_episode(episode)

Reserve passed measured evidence for writing; rejected evidence releases its slot.

Joint positions, observation timestamps, and actual phase intervals supply coverage. Planned targets are never used as measured evidence.

Parameters:

episode (ExpertEpisode) – Actual commands, observations, and validation for a running candidate.

Return type:

bool

Returns:

True when the episode is reserved for persistence; False when validation or coverage rejects it. No storage write occurs here.

add_planned(batch, validation)

Atomically admit validated candidate rows within ready count and byte limits.

The caller owns physical planning checks. Nonempty, passing checks must include path_collision when required by this job.

Parameters:

• batch (CandidateTrajectoryBatch) – Planned rows matching candidates previously proposed by this session.

• validation (ValidationResult) – One planning result per row, including required collision checks.

Return type:

None

apply_receipt(receipt)

Apply a final submission result to its original identity, idempotently.

A repeated receipt is ignored. Different outcomes for one submission are invalid even after retry; the sink must resolve ambiguous writes before reporting a final failure and releasing its reservation.

Parameters:

receipt (CommitReceipt) – Final outcome for an outstanding episode write submission.

Return type:

bool

Returns:

True when a new success or failure receipt is applied, or False for an identical previously applied receipt.

episode_ids(identity)

Return the deterministic episode and idempotent commit IDs for an attempt.

Parameters:

identity (CandidateIdentity) – Candidate identity registered in this session.

Return type:

tuple[str, str]

Returns:

The episode ID and commit ID, stable across persistence retries.

mark_rollout_started(identity)

Count an assigned candidate once its first command actually ran.

Parameters:

identity (CandidateIdentity) – Assigned candidate whose first command has been executed.

Return type:

None

propose(case_id, initial_state_id, *, source_id, source_revision, template_id, operator_id, geometry_family_id=None, parent_id=None)

Allocate stable lineage and a local CPU RNG independent of execution slots.

Parameters:

• case_id (str) – Registered scene-case identifier.

• initial_state_id (str) – Registered initial state within that case.

• source_id (str) – Identifier of the reference trajectory source.

• source_revision (str) – Revision of the source used for this proposal.

• template_id (str) – Identifier of the reference template.

• operator_id (str) – Operator name selecting the deterministic proposal stream.

• geometry_family_id (str | None) – Shared geometry lineage, or None for a new family.

• parent_id (str | None) – Existing candidate in the same case and initial state, if any.

Return type:

tuple[CandidateIdentity, Generator]

Returns:

The new candidate identity and its seeded local CPU generator.

register_case(case, joint_limits, *, joint_names)

Register immutable case conditions and complete joint normalization limits.

Parameters:

• case (SceneCase) – Scene and initial-state identity with fixed robot conditions.

• joint_limits (Tensor) – Finite increasing joint intervals, shape (D_full, 2).

• joint_names (tuple[str, ...]) – Complete unique joint order matching the limit rows.

Return type:

None

release(identity, *, reason='discarded')

Discard uncommitted work while preserving its failure reason and checks.

Parameters:

• identity (CandidateIdentity) – Candidate to release before a write is pending or confirmed.

• reason (str) – Nonempty rejection or cancellation reason retained in diagnostics.

Return type:

None

retry_write(commit_id)

Re-reserve a failed payload and return a copy plus its next submission ID.

A failed write frees collection and coverage quota. Retry therefore fails if another candidate has occupied either quota in the meantime. It never adds a proposal, rollout attempt, or accepted-episode count.

Parameters:

commit_id (str) – Stable commit identifier of an episode whose last write failed.

Return type:

tuple[ExpertEpisode, int]

Returns:

An owned episode copy and the incremented submission ID for the retry.

snapshot()

Return read-only counters, case coverage, and lightweight lifecycle audit.

Diagnostics retain each check’s status, first 256 detail characters, and first 16 numeric metrics. Results support at most 64 checks. Pending reservations cover assigned/running upper bounds and retained payload bytes, including failed writes that remain available for retry.

Return type:

Mapping[str, object]

Returns:

Immutable mappings of counters, reservations, coverage, candidate audit entries, diagnostics, and the current stop reason.

property stop_reason: str | None

Report exhausted collection budgets while allowing outstanding results to finish.

Returns:

An exhausted budget identifier, or None while new work is permitted.

take_ready(case_id, initial_state_id, *, episode_byte_budget=None)

Reserve a row, rollout attempt, and pending payload capacity before execution.

episode_byte_budget is a trusted upper bound on serialized metadata plus tensor data in the eventual episode. None reserves the entire pending byte limit, conservatively allowing only one outstanding episode. Smaller explicit bounds permit concurrent rows; exceeding a bound rejects the episode. The runner owns separate limits on host-side allocations.

Parameters:

• case_id (str) – Registered scene-case identifier to execute next.

• initial_state_id (str) – Registered initial state whose ready rows may be selected.

• episode_byte_budget (int | None) – Maximum episode payload bytes to reserve for this row.

Return type:

CandidateTrajectoryBatch | None

Returns:

One assigned candidate row, or None when no matching row or capacity is available or the session has stopped.

Implementation Modules

The following module paths expose the same contracts and implementations. The package import path above is convenient for callers combining them.

SceneCase	A fixed scene and allowed initial state, with no live environment references.
MotionSnapshot	One copied complete robot state; poses map local frames into the world.
TrajectoryPhase	An explicitly annotated half-open sample interval [start, stop).
TrajectoryTemplate	A full-joint qpos reference with arrival intervals and explicit permissions.
CandidateIdentity	Candidate lineage independent of execution slots and their epochs.
CandidateTrajectoryBatch	Logical candidate rows with safe padding and no physical batch assumption.
ValidationCheck	One mandatory check; unavailable and not-run checks cannot accept data.
ValidationResult	A fail-closed collection of required validation checks.
ExpertEpisode	Frozen rollout evidence with causal obs[t], action[t], obs[t+1] pairs.
CommitReceipt	Sink confirmation tied to stable episode/candidate IDs, never a slot.

TrajectoryAugmentationCfg	Local random seed, explicitly enabled factors, and geometry coverage limits.
TrajectoryGenerationJobCfg	Standalone generation job configuration; control periods remain host-owned.

TrajectoryDescriptor	Measured joint geometry and elapsed times at uniform phase progress.
describe_trajectory	Describe an actual rollout without rewarding additional time samples.
CoverageIndex	Reserve near-distinct measured trajectories and count confirmed geometry.

rotate_grasp_about_object_axis	Rotate a reference grasp about an axis through a fixed object's origin.
joint_residual	Add one smooth, endpoint-preserving residual per allowed free phase.
retime	Retime permitted free phases and resample onto the host control clock.
validate_motion_limits	Check sampled finite-difference motion limits without asserting task success.

GenerationSession

Own one job's bounded candidates, budgets, evidence, and commit history.