feat(pi05): complete the native C++ runtime interface

.github/pull_request_template.md

@@ -0,0 +1,31 @@
+## Summary
+
+<!-- Describe the behavior and ownership boundary changed by this PR. -->
+
+## Design boundaries
+
+<!-- State what remains model-, backend-, policy-, or mechanism-owned. -->
+
+## Compatibility
+
+<!-- Public API, payload, fingerprint, capsule, packaging, and migration impact. -->
+
+## Validation
+
+<!-- Use sanitized commands/results. Do not include private paths or environments. -->
+
+- [ ] Focused tests cover success and rejection paths
+- [ ] Affected CUDA-off/hardware configurations were checked or disclosed
+- [ ] Numerical claims use a fixed, justified gate
+- [ ] Low-precision claims include identity, artifact, and kernel-dispatch evidence
+- [ ] Compared producer binaries were built from the same source revision
+- [ ] Calibration artifacts and cache invalidation are identity-complete
+- [ ] Single/multi-sample calibration and named-input rejection are covered
+- [ ] STAGED ports have real matching verbs
+- [ ] Identity uses observed runtime facts and changes with contract changes
+- [ ] Hot-path allocation/capture/rebind claims are measured at the right scope
+- [ ] Documentation and migration notes are updated
+- [ ] Diff contains no private paths, hosts, containers, credentials, or logs
+- [ ] Shared kernel/CMake ownership and packaging were reviewed
+- [ ] Model semantics remain model-local; frozen runtime/exec stay generic
+- [ ] External test migration preserves core contract/result coverage

CMakeLists.txt

@@ -767,8 +767,8 @@ if(ENABLE_NVFP4)
 endif()
 
 # ── Flash-Attention 2 vendored kernels (fp16 + bf16 fwd SM80) ──
-# Built as an object library and linked into a SEPARATE pybind module
-# flash_rt_fa2.so — same isolation pattern as flash_rt_fp4.so. The
+# Built as an object library and linked into a Python-free raw library;
+# flash_rt_fa2.so is a thin pybind adapter over that library. The
 # main flash_rt_kernels.so stays small (~3.6 MB) and its rebuild no
 # longer waits on FA2's heavy CUTLASS 3.x template codegen (~8 min).
 #
@@ -831,9 +831,9 @@ if(ENABLE_FA2)
       csrc/attention/fa2_causal_inst/flash_fwd_split_hdim256_bf16_sm80_causal.cu
     )
   endif()
-  if("bf16" IN_LIST FA2_DTYPES AND ("128" IN_LIST FA2_HDIMS OR "256" IN_LIST FA2_HDIMS))
-    list(APPEND FA2_SRCS csrc/attention/fa2_wrapper_causal.cu)
-  endif()
+  # Always emit the causal C entry. Builds without a causal hdim retain a
+  # stable raw-library symbol that fails clearly instead of an unresolved ABI.
+  list(APPEND FA2_SRCS csrc/attention/fa2_wrapper_causal.cu)
 
   add_library(fa2_vendor_obj OBJECT ${FA2_SRCS})
   set_target_properties(fa2_vendor_obj PROPERTIES
@@ -954,19 +954,38 @@ if(ENABLE_FA2)
   math(EXPR _FA2_NKERN "${_FA2_NSRC} - 1")
   message(STATUS "FA2 vendor instantiations: hdim={${_FA2_H}} x dtype={${_FA2_D}} x {split,no-split} = ${_FA2_NKERN} kernel .cu files")
 
+  # Keep the raw C entries in a Python-free library. The native C++ runtime
+  # links this target directly; the pybind module below is only an adapter.
+  add_library(flashrt_fa2_raw SHARED)
+  target_sources(flashrt_fa2_raw PRIVATE $<TARGET_OBJECTS:fa2_vendor_obj>)
+  target_link_libraries(flashrt_fa2_raw PRIVATE CUDA::cudart)
+  if(NOT MSVC)
+    target_link_options(flashrt_fa2_raw PRIVATE
+      "LINKER:--no-undefined" -static-libstdc++ -static-libgcc)
+  endif()
+  set_target_properties(flashrt_fa2_raw PROPERTIES
+    LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/flash_rt
+    RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/flash_rt
+    BUILD_RPATH "$ORIGIN"
+    INSTALL_RPATH "$ORIGIN")
+
   # Independent pybind module. Caller side:
   #     from flash_rt import flash_rt_fa2 as fa2
   #     fa2.fwd_fp16(...)  /  fa2.fwd_bf16(...)
   pybind11_add_module(flash_rt_fa2 csrc/fa2_bindings.cpp)
   set_target_properties(flash_rt_fa2 PROPERTIES
     LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/flash_rt
     RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/flash_rt)
-  target_sources(flash_rt_fa2 PRIVATE $<TARGET_OBJECTS:fa2_vendor_obj>)
   target_include_directories(flash_rt_fa2 PRIVATE
     ${CMAKE_CURRENT_SOURCE_DIR}/csrc
   )
-  target_link_libraries(flash_rt_fa2 PRIVATE CUDA::cudart)
-  install(TARGETS flash_rt_fa2 DESTINATION ${CMAKE_CURRENT_SOURCE_DIR}/flash_rt)
+  target_link_libraries(flash_rt_fa2 PRIVATE flashrt_fa2_raw CUDA::cudart)
+  set_target_properties(flash_rt_fa2 PROPERTIES
+    BUILD_RPATH "$ORIGIN"
+    INSTALL_RPATH "$ORIGIN"
+    BUILD_WITH_INSTALL_RPATH ON)
+  install(TARGETS flash_rt_fa2 flashrt_fa2_raw
+    DESTINATION ${CMAKE_CURRENT_SOURCE_DIR}/flash_rt)
   message(STATUS "FA2 pybind module: flash_rt_fa2 (separate .so)")
 endif()
 
@@ -1440,8 +1459,8 @@ if(FLASHRT_ENABLE_MOTUS AND GPU_ARCH STREQUAL "120")
     ENABLE_TINYFP8_KERNELS=1)
 endif()
 
-# (ENABLE_FA2 object-lib is linked into flash_rt_fa2.so only — see
-# the dedicated pybind11_add_module(flash_rt_fa2 ...) above. The main
+# (ENABLE_FA2 object-lib is linked into libflashrt_fa2_raw.so only; the
+# dedicated pybind module and native C++ runtime both consume it. The main
 # flash_rt_kernels.so deliberately does NOT pull FA2 in, so rebuilds
 # of our hand-written kernels don't re-trigger the FA2 codegen tax.)
 

CONTRIBUTING.md

@@ -18,10 +18,15 @@ Before opening a PR:
    - New model integration: [`docs/adding_new_model.md`](docs/adding_new_model.md)
    - Kernel catalog: [`docs/kernel_catalog.md`](docs/kernel_catalog.md)
    - Calibration contract: [`docs/calibration.md`](docs/calibration.md)
+   - Native model producers:
+     [`docs/native_model_runtime_producer.md`](docs/native_model_runtime_producer.md)
+   - PR review standard: [`docs/pr_review_checklist.md`](docs/pr_review_checklist.md)
 2. Build the extension modules locally.
 3. Run the smallest test set that covers your change.
-4. Include the exact GPU, CUDA, command lines, and latency/precision numbers
-   in the PR description when the change touches runtime behavior.
+4. Include sanitized, reproducible build/test commands and the relevant public
+   hardware capability and latency/precision results when runtime behavior
+   changes. Never include private paths, host names, container names, tokens,
+   checkpoint locations, or internal dataset identifiers.
 
 ## Development Setup
 
@@ -224,6 +229,28 @@ reviewers hold every PR to:
   [`docs/subgraph_stage_plans.md`](docs/subgraph_stage_plans.md). A structural
   cut is a re-ordering, not an approximation — split-vs-full replay must stay
   bit-exact (`cpp/tests/gate_pi05_model_runtime_export.py` is the gate).
+- All three C construction paths mechanically reject a STAGED input without
+  `set_input` or a STAGED output without `get_output`. Do not bypass this with
+  a published declaration-only object.
+- Derive hardware identity from the active runtime device. A requested build
+  target or configuration string is not proof of the executing architecture.
+- Schema shared by multiple producers needs checked-in canonical records;
+  every producer compares independently against that golden face.
+
+### Native C++ Model Ownership
+
+Keep a native model producer split by ownership: model semantics, model-private
+support, a coarse backend session seam, hardware backend implementations, and
+the public service/plugin face. Do not expose those private classes as installed
+headers or move model topology into generic runtime/exec code.
+
+Each hardware backend target must compile only its own implementation and link
+the explicitly shared mechanisms it needs. An aggregate compatibility target
+may forward link dependencies, but it must not become a source bucket that
+injects every hardware implementation and architecture flag into every build.
+Validation targets must be registered from actual backend capabilities; do not
+compile one backend's private classes for another device just to preserve a test
+count.
 
 ### Calibration And Precision
 
@@ -235,6 +262,46 @@ calibration, or graph capture behavior, include a precision comparison:
 - action sanity check for quickstart-only paths
 - latency before/after for performance-sensitive changes
 
+Native calibration APIs and artifacts have additional producer-boundary rules:
+
+- Keep model calibration sites, dimensions, camera names, prompt/state
+  semantics, and artifact schema under `cpp/models/<model>/`; do not add them
+  to the frozen runtime ABI or generic `exec/` mechanism.
+- Keep dataset discovery, decoding, synchronization, and sampling policy in the
+  host. A calibration session accepts complete observations; it does not own a
+  dataset loader.
+- Bind reusable artifacts to observed hardware, model/tokenizer content,
+  precision, fixed shapes, reducer/schema version, and any other input that can
+  change scale meaning. Include the artifact digest in producer identity when
+  changing it changes inference math.
+- Test single-observation and repeated-observation reduction. Named multi-input
+  samples must reject missing/duplicate/unknown names and prove that caller
+  array order does not change semantic order.
+- Use explicit fixed stochastic inputs for reference comparison. A generated
+  fallback must be deterministic, documented, and separately exercised.
+- Do not infer compute precision from a public staging dtype. Native low-
+  precision evidence must agree across producer identity, calibration artifact
+  metadata, and captured kernel dispatch; mixed-precision boundary kernels are
+  documented separately from the main GEMM route.
+- Build every producer used in a parity comparison from the same source
+  revision. A stale pybind extension or shared library is an invalid numerical
+  oracle even when its Python sources match the checkout.
+
+### Native Producer Test Ownership
+
+Keep frozen ABI/schema, lifecycle/ownership, artifact validation, final-result,
+subgraph-equivalence, and hot-path invariant tests in FlashRT. Large-checkpoint
+official-framework oracles, layer-by-layer diagnostics, profiler reports,
+deployment shadow comparisons, and soak workloads may live in an integration
+validation repository. Detailed native probes must be opt-in, non-installed
+targets; do not expose intermediate model state through the production ABI to
+make an external test convenient.
+
+Moving a test requires a checked-in coverage map, byte-for-byte migration (or
+an explicitly reviewed rewrite), and one overlapping successful run before the
+old path is removed. Default builds must still exercise failure paths and final
+observable behavior without private checkpoints.
+
 ### Performance Measurement
 
 Use the right metric for the claim:
@@ -354,6 +421,8 @@ Before requesting review:
 - Mention unsupported hardware or missing local fixtures explicitly.
 - Avoid committing generated build outputs, local checkpoints, logs, or
   `third_party/cutlass`.
+- Search the diff for private absolute paths, user/host/container names,
+  credentials, internal URLs, and environment dumps before pushing.
 
 ## Reporting Hardware Results
 

README.md

@@ -578,9 +578,9 @@ NVFP4 weights directly from the Orbax checkpoint (no torch dependency at
 runtime) and uses the same two-phase multi-sample calibration flow as the
 torch FP4 path. Treat the table as Thor correctness / availability evidence,
 not a broad performance claim across every view count or host.
-Reproduce with
-[`tests/bench_pi05_thor_views.py`](tests/bench_pi05_thor_views.py)
-(defaults now include `jax_fp4`).
+The view-count benchmark is maintained in the
+[MindOn PI0.5 validation suite](https://github.com/LiangSu8899/MindOn-dev/tree/main/validation/pi05_cpp/perf)
+(`bench_pi05_thor_views.py`; defaults include `jax_fp4`).
 
 **What's next**:
 - Decoder FP4 (S2 precision-validated set — 72 weight tensors, ~-6 ms estimated)

USAGE.md

@@ -169,6 +169,38 @@ out the exact command.
 do I need to migrate?**
 A: No. The legacy path is still in the search list.
 
+### Pi0.5 Native C++ Runtime
+
+Pi0.5 can also be loaded without a resident Python producer through
+`frt_model_runtime_open_v1`. This is a separate deployment face from
+`flash_rt.load_model()` and returns the backend-neutral
+`frt_model_runtime_v1` contract.
+
+| Hardware | Native precision | Required backend | Calibration artifact |
+|---|---|---|---|
+| SM120 | BF16 | native FA2 + SentencePiece | no |
+| SM120 | static FP8 E4M3 | native FA2 + SentencePiece | yes (schema v2) |
+| Thor SM110 | FP8 E4M3 | Thor FP8/CUTLASS + SentencePiece | yes |
+
+The native producer includes model-specific C APIs for single-view,
+multi-view, and repeated dataset-observation calibration on SM110 and SM120.
+SM110 artifacts contain encoder and decoder scales (schema v1); SM120 also
+contains vision scales (schema v2). Every artifact is bound to hardware,
+checkpoint, tokenizer, fixed shapes, sample count, and reducer policy; runtime
+identity also includes its SHA-256. With `precision="auto"`, SM120 selects
+static FP8 when `calibration_path` is present and BF16 otherwise; SM110 selects
+FP8 and therefore still requires an artifact. Native C++ NVFP4 is not currently
+supported. Python FP8 and NVFP4 routes keep their existing behavior.
+
+Native safetensors setup uses one direct mmap -> transform/quantize -> device
+upload path and does not create an implicit weight-cache format. This is
+independent of the Python JAX Orbax weight cache documented below.
+
+See [Pi0.5 Native C++ FP8](docs/pi05_thor_native_fp8.md) for build
+flags, configuration JSON, C calibration usage, camera-name rules, artifact
+invalidation, runtime ports, and validation commands. The complete portable IO
+contract is [Pi0.5 Native Model Runtime IO](docs/pi05_io_contract.md).
+
 ---
 
 ## Quick Start
@@ -212,7 +244,7 @@ model = flash_rt.load_model(
 | `num_views` | `int` | `2` | Number of camera views. LIBERO uses 2 (base + wrist). |
 | `autotune` | `int\|bool` | `3` | CUDA Graph autotune intensity. See [Autotune](#autotune). |
 | `recalibrate` | `bool` | `False` | Force fresh FP8 calibration (and weight cache for JAX), ignoring cache. See [Calibration](#calibration). |
-| `weight_cache` | `bool` | `True` | Cache FP8-quantized weights to disk. **JAX only** — reduces cold start from ~42s to ~6s. Torch loads in ~3s and ignores this. See [Weight Cache](#weight-cache-jax-only). |
+| `weight_cache` | `bool` | `True` | Cache FP8-quantized weights to disk. **JAX only** — reduces cold start from ~42s to ~6s. Torch loads in ~3s and ignores this. See [Python JAX Weight Cache](#python-jax-weight-cache). |
 | `config` | `str` | `"pi05"` | Model architecture config: `"pi05"`, `"pi0"`, `"groot"`, `"groot_n17"`, `"pi0fast"`, `"motus"`, `"wan22_ti2v_5b"`, `"cosmos3_video"`. `"cosmos3_video"` is a non-VLA text2video denoise model — drive it with `set_prompt(ref=...)` + `infer(...)`, not `predict()`. |
 | `decode_cuda_graph` | `bool` | `False` | **Pi0-FAST only.** Capture action-phase decode as CUDA Graph. Trades startup time for per-token speed. See [Pi0-FAST](#pi0-fast). |
 | `decode_graph_steps` | `int` | `80` | **Pi0-FAST only.** Number of action tokens to capture in the decode graph. Should cover your longest expected action sequence. |
@@ -1155,18 +1187,26 @@ actions = model.predict(images=[img3, img4], prompt="task B")  # fresh calibrati
 
 ---
 
-## Weight Cache (JAX only)
+## Python JAX Weight Cache
 
 JAX (Orbax) checkpoint loading takes ~42s due to OCDBT deserialization + weight transform + FP8 quantization. The weight cache saves the final FP8-quantized engine weights to disk after first load, so subsequent loads skip all three steps.
 
 ### Why JAX only?
 
 | Framework | Cold start | Bottleneck |
 |-----------|-----------|------------|
-| **Torch** (safetensors) | ~3s | mmap load — already fast |
+| **Python Torch** (safetensors) | ~3s | mmap-backed conversion and GPU upload |
 | **JAX** (Orbax) | ~42s → **~6s with cache** | OCDBT deserialize + transform + FP8 quant |
 
-Torch uses safetensors which is essentially a flat binary mmap — there's nothing to cache. JAX's Orbax format requires complex deserialization that the weight cache eliminates.
+This cache belongs to the Python JAX producer. Python Torch uses a flat,
+mmap-backed safetensors source and does not write this cache. That does not mean
+that mmap alone completes model startup: layout transforms, dtype conversion,
+GPU upload, identity construction, workspace setup, and graph capture still
+belong to the selected producer. The native C++ producer fuses its safetensors
+conversion and layout transforms and reports complete setup phases with
+`FLASHRT_PROFILE_NATIVE_SETUP=1`; it does not consume the JAX cache format.
+JAX's Orbax format requires the additional deserialization work that this cache
+eliminates.
 
 ### How it works