From 9e980e1888636b7b96cde9288e2e7df2c7586508 Mon Sep 17 00:00:00 2001 From: snkmcb Date: Wed, 23 Sep 2026 14:09:54 +0900 Subject: [PATCH 1/2] docs: record hosted Jolt backend completion --- .../cmake/physicsJoltConfig.cmake.in | 1 + docs/README.md | 12 +-- docs/architecture/PACKAGE_CONTRACT.md | 4 +- docs/design/DESIGN_POLICY.md | 4 +- docs/reference/CAPABILITY_MATRIX.md | 11 ++- .../2026-09-23-phase2-hosted-backend.md | 37 ++++++++ docs/reports/README.md | 1 + docs/roadmap/README.md | 5 +- docs/roadmap/current.md | 93 ++++++++++--------- tests/installed_consumer/CMakeLists.txt | 10 ++ tests/run_installed_consumer.cmake | 5 + 11 files changed, 122 insertions(+), 61 deletions(-) create mode 100644 docs/reports/2026-09-23-phase2-hosted-backend.md diff --git a/backends/physicsJolt/cmake/physicsJoltConfig.cmake.in b/backends/physicsJolt/cmake/physicsJoltConfig.cmake.in index 3257cc4..52c9a4b 100644 --- a/backends/physicsJolt/cmake/physicsJoltConfig.cmake.in +++ b/backends/physicsJolt/cmake/physicsJoltConfig.cmake.in @@ -6,6 +6,7 @@ if(NOT TARGET physicsCore::physicsCore) endif() @PHYSICSJOLT_FIND_JOLT_DEPENDENCY@ +set(physicsJolt_BACKEND_AVAILABLE @PHYSICSJOLT_BACKEND_AVAILABLE@) set(_physicsJolt_requires_jolt @PHYSICSJOLT_BACKEND_AVAILABLE@) if(_physicsJolt_requires_jolt) set(_physicsJolt_jolt_target [==[@PHYSICSJOLT_BACKEND_TARGET@]==]) diff --git a/docs/README.md b/docs/README.md index ce97f75..969e252 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,12 +4,12 @@ Documentation is organized by responsibility. The taxonomy follows `usd-mmd-plugins`: design says what is intended, architecture fixes structure, reference reports what exists, and the roadmap contains incomplete work. -**Current tree (2026-09-23): Phase 2 backend extraction in progress.** The root -build, packages, boundary checks, and installed-consumer test exist. Neutral -rigid transform values, typed handles, validated descriptors, the single-owner -world contract, optional segment and ground queries, and the initial Jolt -backend are implemented; its OpenStrata intent passes locally. Hosted backend -evidence, an OpenUSD bridge, and a release are not. The +**Current tree (2026-09-23): Phase 2 complete; Phase 3 migration in progress.** +The root build, packages, boundary checks, and installed-consumer test exist. +Neutral rigid transform values, typed handles, validated descriptors, the +single-owner world contract, optional segment and ground queries, and the Jolt +backend are implemented and pass local and hosted Windows/Linux evidence. +Stage Runner migration, an OpenUSD bridge, and a release are not complete. The [capability matrix](reference/CAPABILITY_MATRIX.md) is the only page that may claim implementation status. diff --git a/docs/architecture/PACKAGE_CONTRACT.md b/docs/architecture/PACKAGE_CONTRACT.md index de7baf7..e42f238 100644 --- a/docs/architecture/PACKAGE_CONTRACT.md +++ b/docs/architecture/PACKAGE_CONTRACT.md @@ -1,6 +1,6 @@ # Installed package contract -> **Status: accepted, revised 2026-09-22.** `physicsCore` and `physicsJolt` +> **Status: accepted, revised 2026-09-23.** `physicsCore` and `physicsJolt` > install and pass a clean-prefix consumer test. `physicsCore` now includes > neutral values, typed handles, validated descriptors, typed errors, and the > single-owner world plus optional segment and ground query interfaces and @@ -18,7 +18,7 @@ not need this repository's source tree. | Package | Imported target | Provides | Planned phase | | --- | --- | --- | --- | | `physicsCore` | `physicsCore::physicsCore` | Version surface plus neutral vector, quaternion, transform, typed handles, validated box/body/fixed-constraint descriptors, semantic collision filters, typed errors, world lifecycle/state, and optional segment and ground query interfaces | Phase 1 surface present | -| `physicsJolt` | `physicsJolt::physicsJolt` | `backendAvailable()` plus `createWorld()`; a Jolt-enabled build provides shapes, bodies, fixed constraints, commands, stepping, changed state, segment queries, and ground queries, while a no-Jolt build reports typed unavailability | Phase 2 implementation present; hosted evidence pending | +| `physicsJolt` | `physicsJolt::physicsJolt` | `physicsJolt_BACKEND_AVAILABLE` package metadata, `backendAvailable()`, and `createWorld()`; a Jolt-enabled build provides shapes, bodies, fixed constraints, commands, stepping, changed state, segment queries, and ground queries, while a no-Jolt build reports typed unavailability | Phase 2 complete | | `physicsUsd` | `physicsUsd::physicsUsd` | USD translation, mappings, and synchronization records | 4 | | `secondaryMotion` | `secondaryMotion::secondaryMotion` | generic secondary-motion contracts | 6, if admitted | | `secondaryMotionVerlet` | `secondaryMotionVerlet::secondaryMotionVerlet` | first CPU solver | 6, if admitted | diff --git a/docs/design/DESIGN_POLICY.md b/docs/design/DESIGN_POLICY.md index b4fb715..6fc8bec 100644 --- a/docs/design/DESIGN_POLICY.md +++ b/docs/design/DESIGN_POLICY.md @@ -1,7 +1,7 @@ # usd-physics-plugins design policy -> **Status: proposed, revised 2026-09-22.** This policy defines intended -> behavior while Phase 1 extracts the neutral runtime contract. The +> **Status: proposed, revised 2026-09-23.** This policy defines intended +> behavior while Phase 3 migrates Stage Runner to the extracted packages. The > [capability matrix](../reference/CAPABILITY_MATRIX.md) is the only source for > implementation claims. > diff --git a/docs/reference/CAPABILITY_MATRIX.md b/docs/reference/CAPABILITY_MATRIX.md index 03b8650..1a37837 100644 --- a/docs/reference/CAPABILITY_MATRIX.md +++ b/docs/reference/CAPABILITY_MATRIX.md @@ -4,7 +4,7 @@ This page is the only source of truth for what the current repository tree implements. Design documents describe intended behavior; they do not upgrade a capability on this page. -> **Tree status (2026-09-23): Phase 2 backend extraction in progress.** +> **Tree status (2026-09-23): Phase 2 complete; Phase 3 migration in progress.** > Buildable and installable `physicsCore` and `physicsJolt` package boundaries > exist. > `physicsCore` provides neutral rigid-transform values, typed handles, and @@ -12,8 +12,9 @@ capability on this page. > filters, a single-owner world contract, and optional segment and ground > query interfaces. `physicsJolt` implements those contracts when a compatible > Jolt package is present and retains a typed unavailable fallback otherwise. -> The Jolt-required OpenStrata intent passes locally; hosted backend evidence -> and an OpenUSD plugin do not exist yet. +> The Jolt-required OpenStrata intent passes locally and in hosted Windows and +> Linux CI. Stage Runner has not migrated to the installed packages, and an +> OpenUSD plugin does not exist yet. ## 1. Status vocabulary @@ -62,8 +63,8 @@ capability on this page. | Capability | Status | Evidence / note | | --- | --- | --- | -| `physicsJolt` package | partial | Installable `physicsJolt::physicsJolt` exposes `backendAvailable()` and `createWorld()`; Jolt-enabled and typed unavailable clean-prefix consumers pass on Windows and Linux, and the Jolt-required OpenStrata intent passes locally; hosted evidence remains open | -| Jolt initialization and lifetime | partial | Reference-counted factory/type registration, per-world temporary allocator and job system, explicit resource cleanup, and typed errors are covered by Windows/Linux plain-CMake and local Windows OpenStrata evidence; hosted evidence remains open | +| `physicsJolt` package | supported | Installable `physicsJolt::physicsJolt` exposes `backendAvailable()` and `createWorld()`; Jolt-enabled and typed unavailable clean-prefix consumers pass on Windows and Linux, and the Jolt-required OpenStrata intent passes locally and in the [hosted backend report](../reports/2026-09-23-phase2-hosted-backend.md) | +| Jolt initialization and lifetime | supported | Reference-counted factory/type registration, per-world temporary allocator and job system, explicit resource cleanup, and typed errors are covered by Windows/Linux plain-CMake, local Windows OpenStrata, and [hosted Windows/Linux](../reports/2026-09-23-phase2-hosted-backend.md) evidence | | Jolt body/shape/constraint conversion | supported | Box shapes, static/dynamic bodies, normalized rotations, mass, semantic filters, fixed constraints, force/velocity commands, stepping, state, and cleanup pass focused Windows and Linux tests | | Jolt collision and support queries | supported | Closest segment hit, ignored body, support identity, upward normal, distance, validation, and cross-world rejection pass focused Windows and Linux tests | | Alternative rigid-body backend | unsupported | No implementation phase committed | diff --git a/docs/reports/2026-09-23-phase2-hosted-backend.md b/docs/reports/2026-09-23-phase2-hosted-backend.md new file mode 100644 index 0000000..5d47047 --- /dev/null +++ b/docs/reports/2026-09-23-phase2-hosted-backend.md @@ -0,0 +1,37 @@ +# 2026-09-23 Phase 2 hosted backend verification + +## Scope + +This report records the hosted Windows and Linux verification of the extracted +`physicsJolt` implementation at commit +`0851d9e3717e11401e1ee1d3ef442a2f29e88781`. GitHub Actions run +[`35754385903`](https://github.com/animu-sphere/usd-physics-plugins/actions/runs/35754385903) +was triggered for the `codex/physics-jolt-backend` pull request and completed +successfully on 2026-09-22 UTC. + +The run used the generated OpenStrata source-CI workflow, the `jolt` intent, +OpenStrata 0.23.2, and Jolt Physics 5.5.0 at commit +`23dadd0e603f1b321142d4c74df07fce85064989`. + +## Result + +All three hosted jobs completed successfully: + +- `workspace-graph-pr` validated the CI manifest and workspace dependency + graph on `ubuntu-24.04`; +- `workspace-pr-linux` built the pinned Jolt dependency, materialized and + validated the pinned runtime, built the workspace, and passed the workspace + test suite on `ubuntu-24.04`; and +- `workspace-pr-windows` performed the equivalent Jolt-required build and test + path on `windows-2022`. + +Both platform cells passed the `ost build --intent jolt` and +`ost test --intent jolt` steps. This exercises the focused backend behavior and +clean-prefix installed-consumer path described by the local Windows and Linux +Phase 2 reports through the hosted OpenStrata composition. + +## Conclusion + +The hosted evidence closes the remaining Phase 2 roadmap item. The extracted +`physicsJolt` package has passing local and hosted Windows/Linux evidence, and +Stage Runner package migration can begin as Phase 3. diff --git a/docs/reports/README.md b/docs/reports/README.md index 4713b5f..a00332f 100644 --- a/docs/reports/README.md +++ b/docs/reports/README.md @@ -8,3 +8,4 @@ remain in the [capability matrix](../reference/CAPABILITY_MATRIX.md). - [2026-09-22 Phase 0 hosted CI verification](2026-09-22-phase0-hosted-ci.md) - [2026-09-22 Phase 2 Windows backend verification](2026-09-22-phase2-windows-backend.md) - [2026-09-22 Phase 2 Linux backend verification](2026-09-22-phase2-linux-backend.md) +- [2026-09-23 Phase 2 hosted backend verification](2026-09-23-phase2-hosted-backend.md) diff --git a/docs/roadmap/README.md b/docs/roadmap/README.md index bdce125..2a4d284 100644 --- a/docs/roadmap/README.md +++ b/docs/roadmap/README.md @@ -9,8 +9,7 @@ status and ordering. | Phase | Status | Current outcome | | --- | --- | --- | -| 2 — extract `physicsJolt` | not started | The complete installed Phase 1 contract and selected Jolt 5.5.0 dependency are ready for backend extraction. | -| 3 — Stage Runner migration | not started | Waits for installable Phase 1–2 packages. | +| 3 — Stage Runner migration | in progress | Consume the installed Phase 1–2 packages without changing Stage Runner orchestration or compatibility behavior. | | 4 — `physicsUsd` foundation | not started | Waits for the neutral rigid-body contract. | | 5 — MMD validation | not started | Waits for the USD bridge and a generated vertical-slice fixture. | | 6 — secondary-motion core | not started | Deferred until rigid-body extraction is stable and a VRM slice validates the descriptor. | @@ -22,7 +21,7 @@ version plan exists; release numbers do not belong in the phase definitions. ## Current plan -[current.md](current.md) contains the ordered Phase 2 extraction work. +[current.md](current.md) contains the ordered Phase 3 migration work. Completed items leave that page and are reflected in the [capability matrix](../reference/CAPABILITY_MATRIX.md). diff --git a/docs/roadmap/current.md b/docs/roadmap/current.md index fa7ebc8..e95e619 100644 --- a/docs/roadmap/current.md +++ b/docs/roadmap/current.md @@ -1,53 +1,60 @@ -# Current roadmap — Phase 2 `physicsJolt` extraction +# Current roadmap — Phase 3 Stage Runner migration -> **Status: in progress, 2026-09-23.** The Jolt-backed runtime and Windows/Linux -> plain-CMake/installed-consumer slices are implemented, and the Jolt-required -> OpenStrata intent passes locally on Windows. Hosted evidence remains before -> Phase 2 is complete. +> **Status: in progress, 2026-09-23.** Phase 2 is complete: the installed +> `physicsCore` and `physicsJolt` packages pass local and hosted Windows/Linux +> verification. The next slice migrates Stage Runner to those packages while +> preserving its orchestration and authored compatibility behavior. ## 1. Outcome -Phase 2 produces an installed `physicsJolt` package that constructs a -solver-backed world while keeping every Jolt type, identifier, allocator, job -system, layer, and query implementation private. +Phase 3 makes `usd-stage-runner` a consumer of the installed packages instead +of an owner of the neutral physics and Jolt backend implementations. ```text -installed physicsCore contract - -> physicsJolt world factory - -> Jolt resource lifecycle and fixed stepping - -> changed state, segment queries, and ground queries +installed physicsCore + physicsJolt + -> Stage Runner composition boundary + -> fixed-step orchestration and gameplay capabilities + -> incremental runtime-layer synchronization ``` ## 2. Available prerequisites -- Phase 1 provides installed neutral values, typed handles, validated - descriptors, typed errors, world lifecycle/state, and optional `SegmentQuery` - and `GroundQuery` interfaces. -- Jolt Physics 5.5.0 at commit - `23dadd0e603f1b321142d4c74df07fce85064989` is selected in the - [dependency contract](../architecture/DEPENDENCIES.md). -- The Stage Runner extraction baseline records the proven initialization, - lifecycle, stepping, changed-state, ignored-body segment, and support-contact - behavior to preserve. -- The package scaffold, exported target, boundary checks, and clean-prefix - installed-consumer path already exist. - -## 3. Remaining Phase 2 work - -- Run the configured Jolt-enabled hosted Windows/Linux Phase 2 cells and - record dated evidence. -- Reconcile any platform-specific Jolt compile options discovered by those - cells with the dependency contract before changing the capability claim to - fully supported. - -## 4. Phase 2 completion criteria - -- Falling-body, cleanup, changed-state, segment-query, and ground-query tests - pass through the installed `physicsCore` contract. -- Public `physicsCore` and `physicsJolt` headers expose no Jolt type or native - resource identifier. -- The backend preserves Phase 1 stale, cross-world, validation, error, and - changed-state ordering behavior. -- Package metadata and the `jolt` OpenStrata intent describe the same private - Jolt dependency edge. -- The capability matrix claims only the backend behavior exercised by tests. +- Phase 1 provides the installed neutral values, handles, descriptors, errors, + world contract, and optional segment and ground query capabilities. +- Phase 2 provides the installed Jolt-backed world factory with passing local + and hosted Windows/Linux evidence. +- The Stage Runner extraction inventory fixes the current public surface, + consumers, compatibility importer, fixed-step order, and deterministic parity + evidence at its recorded source revision. +- `StageSession::PhysicsWorldFactory` already gives the standalone and usdview + hosts one backend-selection seam. + +## 3. Remaining Phase 3 work + +- Replace Stage Runner's repository-local `physicsCore` and `physicsJolt` + source edges with installed-package discovery and equivalent OpenStrata + requirements. +- Adapt Stage Runner includes, namespace usage, and math values explicitly at + the composition boundary. +- Move prim/body mapping, dirty synchronization, and fixed-step delegation from + the local `PhysicsRuntime` into `stageRuntime`; do not move `PrimId` or + `RuntimeWorld` into the external package. +- Keep the Runner physics schema importer in Stage Runner as a temporary + compatibility path that produces neutral external descriptors. +- Preserve `StageSession::PhysicsWorldFactory` and use the same external Jolt + factory in standalone and usdview hosts. +- Remove the repository-local physics libraries only after the installed + package path passes the existing parity suite. + +## 4. Phase 3 completion criteria + +- Existing falling-body, character grounding, jump-support, and camera + collision scenarios pass against installed `physicsCore` and `physicsJolt`. +- Stage Runner no longer owns the reusable neutral physics implementation or + the Jolt backend, and no Jolt type crosses a public Stage Runner boundary. +- Prim/body mapping, fixed-step ordering, changed-state synchronization, and + discardable runtime-layer behavior remain owned and tested by Stage Runner. +- Runner physics schema fixtures continue to work through the local + compatibility importer; no new `runner:physics:*` property is added. +- Plain CMake, OpenStrata, standalone, and usdview resolve the same package and + world-factory graph. diff --git a/tests/installed_consumer/CMakeLists.txt b/tests/installed_consumer/CMakeLists.txt index 2ca6103..3b25640 100644 --- a/tests/installed_consumer/CMakeLists.txt +++ b/tests/installed_consumer/CMakeLists.txt @@ -3,10 +3,20 @@ project(UsdPhysicsInstalledConsumer LANGUAGES CXX) if(TEST_FAKE_INCOMPATIBLE_JOLT) add_library(Jolt::Jolt INTERFACE IMPORTED) + set_property(TARGET Jolt::Jolt PROPERTY INTERFACE_COMPILE_DEFINITIONS + USD_PHYSICS_TEST_INCOMPATIBLE_JOLT_ABI=1) endif() find_package(physicsCore CONFIG REQUIRED) find_package(physicsJolt CONFIG REQUIRED) +if(NOT DEFINED physicsJolt_BACKEND_AVAILABLE) + message(FATAL_ERROR "physicsJolt package must report backend availability") +endif() +if(NOT "${physicsJolt_BACKEND_AVAILABLE}" STREQUAL + "${EXPECT_PHYSICSJOLT_BACKEND_AVAILABLE}") + message(FATAL_ERROR + "physicsJolt backend metadata does not match the installed package") +endif() add_executable(usd_physics_installed_consumer main.cpp) target_compile_features(usd_physics_installed_consumer PRIVATE cxx_std_17) diff --git a/tests/run_installed_consumer.cmake b/tests/run_installed_consumer.cmake index 3ab7183..d87586e 100644 --- a/tests/run_installed_consumer.cmake +++ b/tests/run_installed_consumer.cmake @@ -5,6 +5,10 @@ endif() set(_prefix "${PROJECT_BUILD_DIR}/installed-consumer-prefix") set(_build "${PROJECT_BUILD_DIR}/installed-consumer-build") set(_mismatch_build "${PROJECT_BUILD_DIR}/incompatible-jolt-consumer-build") +set(_expected_backend_available OFF) +if(TEST_JOLT_DIR) + set(_expected_backend_available ON) +endif() file(REMOVE_RECURSE "${_prefix}" "${_build}" "${_mismatch_build}") execute_process( @@ -38,6 +42,7 @@ set(_configure_args -B "${_build}" -G "${TEST_GENERATOR}" "-DCMAKE_BUILD_TYPE=${TEST_CONFIG}" + "-DEXPECT_PHYSICSJOLT_BACKEND_AVAILABLE=${_expected_backend_available}" "-DCMAKE_PREFIX_PATH=${_prefix}") if(TEST_GENERATOR_PLATFORM) list(APPEND _configure_args -A "${TEST_GENERATOR_PLATFORM}") From 55ee1f373edb9a31a8929fcc34834ac23a6e03e0 Mon Sep 17 00:00:00 2001 From: snkmcb Date: Wed, 23 Sep 2026 14:18:54 +0900 Subject: [PATCH 2/2] docs: update Stage Runner migration progress --- docs/roadmap/current.md | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/roadmap/current.md b/docs/roadmap/current.md index e95e619..26615f5 100644 --- a/docs/roadmap/current.md +++ b/docs/roadmap/current.md @@ -29,24 +29,31 @@ installed physicsCore + physicsJolt - `StageSession::PhysicsWorldFactory` already gives the standalone and usdview hosts one backend-selection seam. -## 3. Remaining Phase 3 work +## 3. Completed locally -- Replace Stage Runner's repository-local `physicsCore` and `physicsJolt` +- Replaced Stage Runner's repository-local `physicsCore` and `physicsJolt` source edges with installed-package discovery and equivalent OpenStrata requirements. -- Adapt Stage Runner includes, namespace usage, and math values explicitly at +- Adapted Stage Runner includes, namespace usage, and math values explicitly at the composition boundary. -- Move prim/body mapping, dirty synchronization, and fixed-step delegation from - the local `PhysicsRuntime` into `stageRuntime`; do not move `PrimId` or +- Moved prim/body mapping, dirty synchronization, and fixed-step delegation from + the local `PhysicsRuntime` into `stageRuntime` without moving `PrimId` or `RuntimeWorld` into the external package. -- Keep the Runner physics schema importer in Stage Runner as a temporary +- Kept the Runner physics schema importer in Stage Runner as a temporary compatibility path that produces neutral external descriptors. -- Preserve `StageSession::PhysicsWorldFactory` and use the same external Jolt +- Preserved `StageSession::PhysicsWorldFactory` and used the same external Jolt factory in standalone and usdview hosts. -- Remove the repository-local physics libraries only after the installed - package path passes the existing parity suite. +- Removed the repository-local physics libraries after the installed package + path passed all 48 local Windows parity tests. -## 4. Phase 3 completion criteria +## 4. Remaining Phase 3 work + +- Publish immutable OCI sources for the pinned Windows package artifacts. +- Produce and publish equivalent Linux package artifacts. +- Run the Stage Runner hosted Windows and Linux suites from fresh artifact + caches and record the evidence. + +## 5. Phase 3 completion criteria - Existing falling-body, character grounding, jump-support, and camera collision scenarios pass against installed `physicsCore` and `physicsJolt`.