[yuecideng]

Description

ODS consumers currently duplicate refill, quota-wait and pacing loops. Add an optional owner-side ODSFlowController so applications can coordinate manual engines with bounded waits and protected delivery while retaining ownership of engine startup/shutdown and model updates.

The foundation also removes redundant sampling copies/padding and fixes concurrent forkserver exit-status reads between the monitor and owner. Sampling still copies under the publication lock, returns independent storage, and preserves immediate source errors and quota accounting.

Refs #788. Extracted from #828; the visual showcase depends on this change.

Scope

• Public controller/configuration, READY-only health/status methods, and lazy package export.
• Engine/source copy optimization and worker-status synchronization, with focused production regressions and a reproducible CPU component benchmark.
• Existing simple BC caller migration, replacing duplicated scheduling loops; preserve current main's installed-package metadata handling.
• Public API/operation documentation and the owning data-pipeline context.

This is a standalone 21-file foundation. Visual encoder dependencies, visual training/recording/report modules, generated evidence and VLA/WAM integrations belong to the upper change.

Stack

• Layer: 1/2
• Base: main
• Depends on: none
• Followed by: Add ODS visual BC learning and data-stream comparisons #828

Review and merge this layer independently. #828 will use this branch as its base so that its review contains only the remaining visual work.

Validation

• Fixed the repository-wide pytest module collision by naming the new file test_ods_runtime.py. Both runtime modules now collect together (88 cases) and pass jointly under pytest-xdist --dist loadgroup, including the real forkserver publication/backpressure case. The existing scenarios are unchanged; no duplicate regression framework is added.
• Clarified the reviewed live-source boundary in API/operation docs: controller sampling accepts only its own live engine source; resident sources call their own sampling method directly. No resident-source behavior was added.
• 352 focused tests passed across runtime, online engine, protected quotas, sources, configuration/regimes and import boundaries; includes real forkserver numeric publication, worker failure, timeout and shutdown cases.
• 42 project-context tests passed; map checks and English/Chinese controller routes pass.
• Black 26.3.1 (black .), Python 3.10 parsing/header checks, public API coverage 3036/3036, simple BC CLI help and git diff --check pass.
• Independent dependency review confirms the public runtime imports without the upper example, torchvision, simulator imports or CUDA initialization. Tests exercise ownership/padding, copy-failure accounting, deadlines, pacing, refill coalescing, bounded supply and error propagation.
• Validation used conda py311. The final test command uses the installed DexSim and exposes one idle device for Open3D's CUDA-only native import; no physical simulation or GPU performance experiment was run. Earlier attempts using an obsolete temporary DexSim overlay / a CPU-hidden Open3D import failed during environment setup and were corrected without changing production code.
• Test-necessity review: retain the existing focused production regressions and independent oracles; no additional example test framework. Context is revised for the new public owner and lock/copy contract. No end-to-end speedup or learning-performance claim is made here.

Type of change

• Enhancement (non-breaking)
• Bug fix (non-breaking)

Checklist

• Run black . and focused behavioral validation.
• Review affected context and operational documentation.
• Document public API additions.
• Review test necessity and preserve meaningful regression coverage.
• Keep the layer independently usable without visual dependencies.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge, with the previous documentation issue addressed and no new actionable findings.

Summary

Adds optional ODSFlowController for caller-owned refill, bounded waits and pacing.

• Applications can coordinate manual data refills and training waits through one controller.
• Sampling avoids copying each gathered batch a second time.
• Worker monitoring and shutdown share one lock for process-status reads.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    App["Application owns startup and shutdown"] --> Flow["ODSFlowController"]
    Flow --> Checks["Check health and drain events"]
    Checks --> Prepare["Request refill and pace batches"]
    Prepare --> Source["OnlineDataSource"]
    Source --> Engine["Copy under publication lock"]
    Engine --> Train["Application trains"]

Loading

_{Reviews (2) · Last reviewed commit: "fix(ods): isolate runtime test imports a..." · Reviewed by Greptile}