animu-sphere · snkmcb · Sep 27, 2026 · Sep 27, 2026
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -27,8 +27,18 @@ endif()
 
 add_subdirectory(libs/physicsCore)
 add_subdirectory(backends/physicsJolt)
+option(USDPHYSICS_BUILD_USD "Build the optional standard OpenUSD declaration adapter" OFF)
+if(USDPHYSICS_BUILD_USD)
+  add_subdirectory(libs/physicsUsd)
+endif()
 
 include("${CMAKE_CURRENT_SOURCE_DIR}/cmake/UsdPhysicsBoundaryChecks.cmake")
+if(TARGET physicsUsd)
+  usdphysics_assert_target_dependencies(
+    TARGET physicsUsd
+    ALLOWED_PUBLIC physicsCore::physicsCore usd usdGeom usdPhysics pxr::usd pxr::usdGeom pxr::usdPhysics
+    ALLOWED_PRIVATE physicsCore::physicsCore usd usdGeom usdPhysics pxr::usd pxr::usdGeom pxr::usdPhysics)
+endif()
 usdphysics_assert_target_dependencies(
   TARGET physicsCore
   ALLOWED_PUBLIC)

diff --git a/README.md b/README.md
@@ -2,12 +2,13 @@
 
 Backend-neutral physics runtime components for OpenUSD-based applications.
 
-> **Status (2026-09-23): Phase 2 backend extraction in progress.** The
+> **Status (2026-09-27): core/backend extraction complete; Box USD foundation in progress.** The
 > repository builds and installs `physicsCore` and `physicsJolt`; the neutral
 > core contract and a Jolt-backed world with fixed stepping, changed state,
 > segment queries, and ground queries are implemented. The Jolt-required
 > OpenStrata intent passes
-> locally; hosted Phase 2 evidence and an OpenUSD bridge remain. The
+> locally and in hosted CI. An optional `physicsUsd` package now reads standard
+> Box declarations; wider bridge support and artifact rollout remain. The
 > [capability matrix](docs/reference/CAPABILITY_MATRIX.md) is the only page
 > that states what exists, and the [current roadmap](docs/roadmap/current.md)
 > states what comes next.
@@ -20,6 +21,12 @@ validate it with
 
 ## The central rule
 
+The optional Box adapter builds with `-DUSDPHYSICS_BUILD_USD=ON` and an OpenUSD
+26.08 install on `CMAKE_PREFIX_PATH`. It installs `physicsUsd::physicsUsd` and
+`usd_physics/usd/box_scene.h`. The core/backend-only root build remains the
+default. See the [bounded Box contract](docs/design/USD_BRIDGE_CONTRACT.md)
+for supported declarations and explicit rejection behavior.
+
 > **OpenUSD describes the physical world; `usd-physics-plugins` makes that
 > world executable without exposing a backend SDK to its consumers.**
 

diff --git a/docs/architecture/DEPENDENCIES.md b/docs/architecture/DEPENDENCIES.md
@@ -15,7 +15,7 @@ claims.
 | C++ | C++17 | all C++ targets | verified with GCC 15.2.0 and MSVC 19.51 |
 | OpenStrata | 0.23.2 | workspace composition and CI generation | Windows root build/test, isolated library tests, consumer verification, and packaging pass |
 | OpenStrata platform | `cy2026`, `usd` profile | workspace composition | digest-pinned Windows runtime materialized and validated; scaffold code does not link OpenUSD |
-| OpenUSD | 26.08 exact for the first ecosystem integration | future `physicsUsd`, `physicsSchema`, USD tests | aligned and CI runtime pinned; no target currently links it |
+| OpenUSD | 26.08 exact for the first ecosystem integration | `physicsUsd` and USD tests; future `physicsSchema` | Box adapter and clean-prefix consumer verified locally on Windows; hosted bridge evidence remains open |
 | Jolt Physics | 5.5.0, tag `v5.5.0`, commit `23dadd0e603f1b321142d4c74df07fce85064989` | private `physicsJolt` implementation | Jolt-backed plain-CMake tests pass locally on Windows and Linux and the `jolt` OpenStrata intent passes on Windows; hosted Phase 2 evidence remains open |
 | CTest | version shipped with CMake | tests | 11 Jolt-enabled root tests pass on Windows and Linux and through OpenStrata on Windows |
 

diff --git a/docs/architecture/PACKAGE_CONTRACT.md b/docs/architecture/PACKAGE_CONTRACT.md
@@ -19,7 +19,7 @@ not need this repository's source tree.
 | --- | --- | --- | --- |
 | `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` | `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 |
+| `physicsUsd` | `physicsUsd::physicsUsd` | Validated standard Box snapshots; mappings and synchronization records remain planned | Phase 4 subset implemented |
 | `secondaryMotion` | `secondaryMotion::secondaryMotion` | generic secondary-motion contracts | 6, if admitted |
 | `secondaryMotionVerlet` | `secondaryMotionVerlet::secondaryMotionVerlet` | first CPU solver | 6, if admitted |
 | `physicsSchema` | bundle contract to be defined at admission | generated schema library and resources | only if admitted |
@@ -29,6 +29,14 @@ The public include root and namespace are fixed by
 
 ## 3. Install-interface rules
 
+The optional `physicsUsd` target builds with `USDPHYSICS_BUILD_USD=ON` in the
+root or as a standalone `libs/physicsUsd` project. It exports public headers
+under `usd_physics/usd/`, links only `physicsCore` and OpenUSD `usd`, `usdGeom`,
+and `usdPhysics` targets (also accepting `pxr::` names), and resolves those
+dependencies from its installed config. The clean-prefix consumer includes a
+standard Cube import when this option is enabled. Its OpenStrata member is
+declared but has not entered the published release/artifact set.
+
 Every library package must:
 
 - install public headers under one repository-owned include root;

diff --git a/docs/architecture/WORKSPACE.md b/docs/architecture/WORKSPACE.md
@@ -18,7 +18,7 @@ that contradicts it updates this document first, in a focused change.
 | --- | --- | --- | --- | --- | --- | --- |
 | `physicsCore` | plain static CMake library | `libs/physicsCore/` | `openstrata.library.yaml` | Solver-neutral value types, handles, descriptors, world lifecycle, state, validation, and optional query contracts. No OpenUSD or backend SDK. | Phase 0 scaffold; Phase 1 runtime | Phase 1 values, handles, descriptors, world contract, and segment/ground queries implemented |
 | `physicsJolt` | plain static CMake library | `backends/physicsJolt/` | `openstrata.library.yaml` | Jolt implementation of `physicsCore`; owns Jolt initialization, filters, jobs, resources, stepping, and queries. | Phase 0 scaffold; Phase 2 backend | backend implemented; Windows and Linux plain-CMake and installed-consumer evidence present |
-| `physicsUsd` | plain static CMake library | `libs/physicsUsd/` | `openstrata.library.yaml` | Standard `UsdPhysics` to core descriptors, transform conversion, transient scene/resource mapping, and synchronization records. | Phase 4 | reserved |
+| `physicsUsd` | plain static CMake library | `libs/physicsUsd/` | `openstrata.library.yaml` | Standard Box declarations to neutral snapshots; resource mapping and synchronization records remain planned. | Phase 4 | optional installable Box reader implemented |
 
 The Phase 0 targets established package and dependency boundaries.
 `physicsCore` has supported value, handle, descriptor, and world-contract

diff --git a/docs/design/USD_BRIDGE_CONTRACT.md b/docs/design/USD_BRIDGE_CONTRACT.md
@@ -1,7 +1,30 @@
 # OpenUSD physics bridge contract
 
-> **Status: proposed, 2026-09-21.** `physicsUsd` is planned for Phase 4 and is
-> not present. See the [capability matrix](../reference/CAPABILITY_MATRIX.md).
+> **Status: proposed, updated 2026-09-27.** A bounded Box snapshot reader is
+> implemented; the wider bridge remains planned. See the
+> [capability matrix](../reference/CAPABILITY_MATRIX.md).
+
+The initial implementation exposes `usd_physics::usd::readBoxScene()` and
+`BoxBody` in `usd_physics/usd/box_scene.h`. It returns validated neutral shape,
+motion, transform, and mass values sorted by absolute prim path. It owns no
+world, handles, persistent mapping, or USD edits. Callers must keep the result
+associated with its source Stage and discard it at reload; stage-generation
+identities and synchronization records remain future work.
+
+The Box subset requires collision and body on the same Cube, Y-up meters/kg,
+explicit positive mass for dynamic bodies, one translate op then scale ops,
+and identity ancestors or resetXformStack. Static collision-only Cubes and
+disabled rigid bodies are static; disabled collision-only Cubes are skipped.
+A rigid body with disabled collision is rejected until collider-free bodies
+are supported. Kinematic bodies, animated declarations, scenes, joints,
+instances, nested bodies, inherited/density-based mass, materials, and all
+other authored `physics:*` properties are rejected. No default mass is
+substituted for unsupported USD mass inference.
+
+For this surface, `USD-O2` uses typed `ImportErrorCode` plus the offending path
+on `ImportError`: `invalidStage`, `unsupportedUnits`, `unsupportedDeclaration`,
+`unsupportedTransform`, and `invalidValue`. Consumers assert code/path, not
+diagnostic prose. Validation completes before a snapshot is returned.
 
 ## 1. Purpose
 

diff --git 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 complete; Phase 3 migration in progress.**
+> **Tree status (2026-09-27): Phase 2 complete; Phase 3 release follow-up and Phase 4 Box foundation in progress.**
 > Buildable and installable `physicsCore` and `physicsJolt` package boundaries
 > exist.
 > `physicsCore` provides neutral rigid-transform values, typed handles, and
@@ -13,8 +13,9 @@ capability on this page.
 > 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 and in hosted Windows and
-> Linux CI. Stage Runner has not migrated to the installed packages, and an
-> OpenUSD plugin does not exist yet.
+> Linux CI. Stage Runner has migrated to installed core/backend packages. An
+> optional installable `physicsUsd` Box reader now exists; an OpenUSD plugin
+> does not. Bridge artifact publication and hosted parity remain open.
 
 ## 1. Status vocabulary
 
@@ -73,18 +74,27 @@ capability on this page.
 
 | Capability | Status | Evidence / note |
 | --- | --- | --- |
-| `physicsUsd` package | not present | Planned Phase 4 |
+| `physicsUsd` package | partial | Optional installed `physicsUsd::physicsUsd`; `physicsUsd.box_scene` and clean-prefix USD consumer test |
 | `UsdPhysicsScene` gravity | planned | No implementation |
-| Box/sphere/capsule collision | planned | No implementation |
-| `UsdPhysicsRigidBodyAPI` | planned | No implementation |
-| `UsdPhysicsMassAPI` | planned | No implementation |
+| Box collision | partial | Cube size and ordered scales; `physicsUsd.box_scene` covers conversion, disabled static colliders, and invalid dimensions |
+| Sphere/capsule collision | planned | No implementation |
+| `UsdPhysicsRigidBodyAPI` | partial | Enabled dynamic or disabled static body on the collision Cube; kinematic, collider-free, nested, and compound bodies rejected |
+| `UsdPhysicsMassAPI` | partial | Explicit positive dynamic mass in kg; density inference, inherited mass, inertia and center-of-mass overrides rejected |
 | Fixed joints | planned | No implementation |
 | Other standard joints, limits, and drives | planned | Phase 5 expands from consumer fixtures |
 | Prim/resource mappings | planned | No implementation |
 | Stage reset/rebuild | planned | No implementation |
 | Incremental USD change processing | unsupported | Rebuild-first policy; no implementation |
 | USD state synchronization records | planned | `USD-O3` unresolved |
 
+The [Box contract](../design/USD_BRIDGE_CONTRACT.md) documents the bounded
+subset. It requires Y-up meters/kg, translate then scale, and identity
+ancestors or resetXformStack. Animated values, instances, other standard
+physics APIs/properties, scenes, and joints fail with typed code/path diagnostics.
+Tests live in [box_scene_test.cpp](../../libs/physicsUsd/tests/box_scene_test.cpp).
+The parser never edits USD or creates resources; returned paths are snapshot
+identities belonging to the caller's Stage, not persistent runtime mappings.
+
 ## 6. Secondary motion
 
 | Capability | Status | Evidence / note |
@@ -106,8 +116,8 @@ capability on this page.
 
 | Scenario | Status | Evidence / note |
 | --- | --- | --- |
-| Stage Runner falling body | planned | Phase 3 |
-| Stage Runner character grounding and camera collision | planned | Phase 3 |
+| Stage Runner falling body | supported | Installed core/backend migration verified in the [Phase 3 artifact report](../reports/2026-09-23-phase3-linux-artifacts.md); standard Box consumer remains opt-in |
+| Stage Runner character grounding and camera collision | supported | Same installed-package consumer evidence; standard/compatibility parity is covered in Stage Runner's optional `stage_runtime.standard_physics_parity` test |
 | MMD rigid bodies and joints through standard USD | planned | Phase 5 |
 | VRM-derived secondary motion | planned | Phase 7 |
 | Vehicle primitives | planned | Phase 8 |
diff --git a/docs/roadmap/README.md b/docs/roadmap/README.md
@@ -9,8 +9,8 @@ status and ordering.
 
 | Phase | Status | Current outcome |
 | --- | --- | --- |
-| 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. |
+| 3 — Stage Runner migration | in progress | Consumer migration verified; versioned release workflow remains. |
+| 4 — `physicsUsd` foundation | in progress | Box snapshot parser exists; artifact rollout and wider declarations remain. |
 | 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. |
 | 7 — VRM validation | not started | Waits for Phase 6 and a format-owned adapter. |
@@ -21,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 3 migration work.
+[current.md](current.md) contains release follow-up and the next Phase 4 slice.
 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
@@ -1,76 +1,32 @@
-# Current roadmap — Phase 3 Stage Runner migration
-
-> **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 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 + physicsJolt
-        -> Stage Runner composition boundary
-        -> fixed-step orchestration and gameplay capabilities
-        -> incremental runtime-layer synchronization
-```
-
-## 2. Available prerequisites
-
-- 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. Completed locally
-
-- Replaced Stage Runner's repository-local `physicsCore` and `physicsJolt`
-  source edges with installed-package discovery and equivalent OpenStrata
-  requirements.
-- Adapted Stage Runner includes, namespace usage, and math values explicitly at
-  the composition boundary.
-- 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.
-- Kept the Runner physics schema importer in Stage Runner as a temporary
-  compatibility path that produces neutral external descriptors.
-- Preserved `StageSession::PhysicsWorldFactory` and used the same external Jolt
-  factory in standalone and usdview hosts.
-- Removed the repository-local physics libraries after the installed package
-  path passed all 48 local Windows parity tests.
-- Published the pinned Windows packages as public, immutable OCI artifacts and
-  verified both OCI and content digests from a fresh cache.
-- Published equivalent Linux packages and verified their content and OCI
-  digests from a fresh cache; see the
-  [Linux artifact report](../reports/2026-09-23-phase3-linux-artifacts.md).
-- Stage Runner passed hosted Windows and Linux OpenStrata consumer builds and
-  tests with artifact caches disabled, plus the plain-CMake hosted jobs;
-  [the consumer run](https://github.com/animu-sphere/usd-stage-runner/actions/runs/35853380748)
-  records both platform cells.
-
-## 4. Remaining Phase 3 work
-
-- Implement and dry-run the versioned release workflow against the
-  [release schema](../architecture/RELEASE_SCHEMA.md) before creating a tag;
-  the currently published Windows and Linux artifacts are Phase 3 inputs, not
-  a full release.
-
-## 5. 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.
+# Current roadmap — release follow-up and Phase 4
+
+Status: in progress, 2026-09-27. The installed core/backend consumer migration
+has passed hosted Windows/Linux verification. An optional standard Box reader
+is implemented; the [capability matrix](../reference/CAPABILITY_MATRIX.md)
+records the supported subset and tests.
+
+## 1. Release follow-up
+
+Implement and dry-run the versioned release workflow against the
+[release schema](../architecture/RELEASE_SCHEMA.md) before creating a tag.
+Existing Windows/Linux core/backend artifacts remain migration inputs rather
+than a full release.
+
+## 2. Next Box delivery slice
+
+- Validate and publish Windows/Linux `physicsUsd` artifacts and pin them in
+  Stage Runner's OpenStrata requirements before enabling standard import by default.
+- Run hosted standard/compatibility parity including standalone and usdview.
+- Extend through working fixtures for scene gravity, additional shapes,
+  mass inference, fixed joints, and composed transforms.
+- Resolve stage-generation identity and synchronization contracts before
+  introducing retained resource mappings in the package.
+
+## 3. Completion criteria
+
+Standard declarations become the primary authored representation in Stage
+Runner while core/backend packages remain reusable and contain no gameplay
+policy. The same package graph must work in plain CMake and OpenStrata, on
+Windows and Linux. Keep Runner compatibility fixtures until all host and
+runtime-layer parity gates pass. The wider intended bridge is defined in
+[USD_BRIDGE_CONTRACT.md](../design/USD_BRIDGE_CONTRACT.md).