Add scene candidates and measured Task Program execution

[yuecideng]

Description

Add immutable scene pose candidates and an opt-in Task Program entry point that prepares one candidate, executes the canonical Task Program path, and requires separate measured acceptance. Acceptance requires normal completion of the selected canonical bridge and its final acceptance mask, independently of early Gym success. Recording rejection remains attached to the buffers until reset discards them; retries and replaced episode metadata cannot make rejected data saveable. Preparation, execution, and measurement share an attempt guard that blocks automatic resets and premature persistence.

lab.sim.scene_expansion owns bounded fixed candidates, permissions, rigid-transform validation, and reproducible proposal identity. Task Program integrations reuse the existing demo executor and persistence boundary. The executor accepts an explicit trusted segment iterable so an environment subclass cannot silently redirect this entry point into a handwritten expert action list.

Includes the design from #748, API documentation, a routed project-context topic, and architecture nodes with source evidence for the scene core and Task Program entry point. The concrete workspace and physical-state host are the next layer.

Refs #748. Dependencies: existing Task Program and motion-expansion infrastructure; no new package dependency. This layer does not depend on PR #729.

Stack

• Layer: 1/2
• Base: main
• Depends on: none
• Followed by: Integrate scene workspace checks and add a UR5 showcase #750

Type of change

• New feature
• Documentation update

Validation

• 290 focused tests passed: scene contracts/source, Task Program scene integration, real bridge lifecycle, existing demo/environment regressions, API-doc tooling, and context tooling. The 31 added cases cover early termination during runtime/post-policies, final-mask rejection through wrappers, retries without reset, preparation/measurement resets, empty reset, discard errors, and interruption.
• Black 26.3.1: black . completed; staged whitespace/header/annotation/export checks passed.
• Public API gate on an isolated snapshot of this layer: 2464/2464 exports documented.
• Standard Sphinx dummy build in a clean checkout: succeeded, with 824 existing/optional-dependency and cross-reference warnings; no warning identifies the new scene-expansion pages or symbols.
• Context check and representative English/Chinese routes passed. Added the scene-expansion owner and linked existing Task Program/workspace/motion context.
• Architecture coverage: 46 Python checks, 17 frontend tests, 8 browser tests, and 10 Sphinx embedding tests passed; the generated graph represents all 19 registered topics and 10 production packages.
• Independent architecture, engine, and agentic reviews completed. Three confirmed acceptance/persistence defects are fixed. Behavioral tests against the original reviewed head exposed 14 failures with two valid reset controls; the fixed suite passes.

This layer's integration tests use CPU physics/runtime ports and exercise the production demo and delayed persistence boundaries. Native scene preparation and workspace qualification belong to layer 2.

Screenshots

No UI change.

Checklist

• I have run black . with Black 26.3.1.
• I reviewed and updated affected project context.
• Public API changes are reflected in the API docs.
• Focused tests prove the new contracts, execution routing, and failure persistence behavior.
• Dependency declarations were reviewed; no new dependency is required.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; both previous recording and completion issues are fixed.

Summary

Adds immutable scene pose proposals, a bounded candidate source, and a Task Program entry point with separate measured acceptance.

• Scene candidates are bounded, immutable, and tied to their proposal inputs.
• Scene attempts run a canonical Task Program and need measured evidence to be accepted.
• The docs explain how scene proposals connect to Task Program execution.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[SceneVariant] --> B[Prepare scene]
  B --> C{Initial checks pass?}
  C -->|No| R[Reject recording]
  C -->|Yes| D[Run canonical Task Program]
  D --> E[Read bridge completion]
  E --> F[Measure task outcome]
  F --> G{All checks pass?}
  G -->|No| R
  G -->|Yes| H[Accept attempt]
  R --> I[Reset discards buffers]
  H --> J[Caller requests reset-time save]
  J --> K{Earlier recording rejected?}
  K -->|Yes| I
  K -->|No| L[Existing recording writers]

Loading

_{Reviews (4) · Last reviewed commit: "fix(scene): require bridge completion an..." · Reviewed by Greptile}