usd_import: read USD through Moho (scene-index S2)

CLAUDE.md

@@ -14,9 +14,25 @@ beside the behavioural `spec.md` for the same capability.
 Crust Render is a toy, physically-based path tracer written in safe Rust (edition 2024),
 inspired by PBRT, *Ray Tracing in One Weekend*, and Autodesk Standard Surface / OpenPBR.
 Scenes are loaded exclusively from **USD** (`.usda` / `.usdc` / `.usdz`) via the pure-Rust
-[`openusd`](https://github.com/mxpv/openusd) crate (its GitHub `main`, patched over 0.8 in
-the workspace `Cargo.toml`; typed schemas in `openusd-schemas`, which every stage must be
-opened with — `usd_import::stage_builder()`). Do not add loaders for any other scene or mesh format.
+[`openusd`](https://github.com/mxpv/openusd) crate (typed schemas in `openusd-schemas`,
+which every stage must be opened with — `usd_import::stage_builder()`). The importer is
+moving onto [Moho](https://github.com/doubleailes/Moho), a Hydra-2.0-style scene index over
+openusd that Mantle's IPR and Obsidian also consume (`openspec/changes/moho-import`). Do not add loaders for any other scene or mesh format.
+
+**openusd only through Moho.** No crate depends on `openusd` or `openusd-schemas`
+itself: every crate names them as `moho::openusd` and `moho::openusd_schemas` (a file
+adds `use moho::openusd;`), so Moho's pin is the stack's and the build carries one
+openusd by construction; `crust-core/tests/one_openusd.rs` fails if a manifest names
+openusd directly. openusd's features are Moho's: `moho/mmap`, `moho/serde`, and the
+schema families (`skel`, `proc`, `media`, …; `geom`, `lux`, `render`, `shade`, `vol` are
+always on). `moho` is pinned by `rev` in `[workspace.dependencies]`; bump in order:
+**Moho, then crust-render, then Mantle**. To co-develop with a local Moho checkout, pass a Cargo config
+file with a path patch rather than editing `.cargo/config.toml` (it is tracked):
+
+```bash
+printf '[patch."https://github.com/doubleailes/Moho"]\nmoho = { path = "../Moho/crates/moho" }\n' > /tmp/moho.toml
+cargo --config /tmp/moho.toml test -p crust-core   # rewrites Cargo.lock's moho entry: restore it before committing
+```
 
 ## Where things are documented
 
@@ -144,8 +160,9 @@ with CMake against OpenUSD 26 from `hydra/pixi.toml`, outside `cargo build`. Imp
   it — a wrapper adds a vtable hop per texel fetch that LTO cannot remove.
 - `scene/usd_import/` siblings share through `pub(super)` and import each other
   explicitly — no `use super::*`, so a file's `use` block is its real dependency list.
-- The USD import is single-threaded and reads the time code from a thread-local
-  (`EvalTimeScope`); parallelising it means threading the time explicitly.
+- The USD import reads USD through Moho's scene index, which owns the time: a reader
+  takes the index's time, or a time code passed to it explicitly (`crust ls`, the
+  stage facts). No reader keeps the time in a thread-local.
 - No RNG outside `openqmc`: stratified draws through keyed sub-domains (`K_*` in
   `tracer/path.rs`), incidental ones through `draw_rnd` / `domain.rng()`.
 
@@ -176,8 +193,9 @@ without the other (full list: `docs/architecture.md` § Invariants):
   an MCP edit applied in place ↔ a full re-import of the same layer (`crust_core::live`
   rebuilds through the import's own functions; a material property the import bakes
   into geometry or a world flag belongs in `Signature`, in `rt_world.rs`).
-- Anything keyed on a prototype path is scoped by the stage epoch
-  (`ImportCaches::epoch`): `/__Prototype_N` is renumbered per masked stage.
+- Anything keyed on a prototype is keyed by Moho's propagated prototype path (or a
+  point instancer's copy), which is stable across a streamed import's stages, never
+  by openusd's `/__Prototype_N`, which is renumbered per masked stage.
 - `Material::resolve` must return exactly what per-query shading would (pinned for every
   material by `crust-core/tests/resolve.rs`); build it with `Resolution::new`, which takes
   the emission from the parameters *before* `into_resolved` — the type allows no other order.

Cargo.toml

@@ -80,14 +80,16 @@ half = "2.7"
 # converts them into the working space (`crust_core::color`). From crates.io
 # (doubleailes/ocio-rs#2); the committed `Cargo.lock` pins the exact version.
 ocio = "0.2.0"
-# The USD reader and its typed schema views, versioned in lockstep. Declared
-# once so crust-core (the import) and crust-render (the MCP session's override
-# layer, the probe examples) can never name different versions of the stage
-# they share; `[patch.crates-io]` below swaps both for GitHub `main`. No
-# default features (openusd has none since 0.8): each member adds the ones it
-# needs — crust-core's `mmap` and schema families, crust-render's `serde`.
-openusd = { version = "0.8", default-features = false }
-openusd-schemas = { version = "0.8", default-features = false }
+# Moho, the Hydra-2.0-style scene index over openusd that the import reads the
+# stage through, pinned by rev. It is also the only way crust reaches openusd:
+# every crate names `moho::openusd` and `moho::openusd_schemas`, so Moho's pin
+# is the stack's and there is one openusd in the build by construction
+# (`crust-core/tests/one_openusd.rs` fails if a crate depends on openusd
+# directly). openusd's features are Moho's: `mmap`, `serde`, and the schema
+# families `media`, `physics`, `proc`, `semantics`, `skel`, `ui` (`geom`, `lux`,
+# `render`, `shade`, `vol` are always on). Bump order: Moho, then crust-render,
+# then Mantle.
+moho = { git = "https://github.com/doubleailes/Moho", rev = "d09cc946def933d3f0b3aa66c3b5249aff7c91d4" }
 
 # The hot loops are spread across crates: the integrator in `crust-core`
 # calls the kernel in `crust-rt`, which calls `glam`'s SIMD vector ops.
@@ -142,11 +144,3 @@ codegen-units = 1
 inherits = "release"
 panic = "unwind"
 
-# openusd tracks its GitHub `main` rather than the 0.8.0 release, to take its
-# fixes as they land. A patch rather than a `git =` in `[workspace.dependencies]`,
-# so the requirement stays the release's `0.8` and dropping this section is the
-# whole revert to it. Cargo.lock pins the commit; `cargo update -p
-# openusd -p openusd-schemas` moves it.
-[patch.crates-io]
-openusd = { git = "https://github.com/mxpv/openusd", branch = "main" }
-openusd-schemas = { git = "https://github.com/mxpv/openusd", branch = "main" }

crates/crust-core/Cargo.toml

@@ -25,8 +25,13 @@ jit = ["dep:crust-jit"]
 # `unsafe`, which this feature alone compiles. Off here and on in the
 # renderer, like `jit`; `CRUST_USD_MMAP=0` turns it off at run time.
 # openusd's own `mmap`, and with it `memmap2`, is compiled in only with this
-# feature: openusd has no default features since 0.8.
-mmap = ["openusd/mmap"]
+# feature, forwarded through Moho: openusd has no default features since 0.8.
+mmap = ["moho/mmap"]
+# Test-only: every import is compared with the baseline recorded from the
+# direct importer (`src/parity.rs`, the `moho-import` change). Turned on for
+# this crate's tests by the dev-dependency on itself below, and for
+# crust-render's by its own; never by a build that ships.
+parity = []
 
 [dependencies]
 utils = { path = "../utils" }
@@ -35,16 +40,16 @@ crust-rt = { path = "../crust-rt" }
 rayon.workspace = true
 glam.workspace = true
 tracing.workspace = true
-openusd.workspace = true
-# The typed schema views (UsdGeom / UsdLux / UsdShade / UsdRender) left the
-# core crate in openusd 0.7 and ship separately, versioned in lockstep. UsdSkel,
-# UsdVol, UsdProc and UsdMedia are compiled in for their types alone: the import
-# composes a prim's xformOps only when the schema registry knows it is
-# Xformable, and a SkelRoot, Volume, GenerativeProcedural or SpatialAudio from a
-# family left out is unknown, so its transform would be dropped. With them,
-# every Xformable type C++ USD defines is known (the remaining families,
-# UsdPhysics, UsdUI and UsdSemantics, define none).
-openusd-schemas = { workspace = true, features = ["geom", "lux", "shade", "render", "skel", "vol", "proc", "media"] }
+# The scene index the import reads the stage through (`scene/usd_import/`), and
+# crust's one way to openusd and its typed schema views (`moho::openusd`,
+# `moho::openusd_schemas`). UsdGeom, UsdLux, UsdShade, UsdRender and UsdVol are
+# always on in Moho; UsdSkel, UsdProc and UsdMedia are compiled in for their
+# types alone: the import composes a prim's xformOps only when the schema
+# registry knows it is Xformable, and a SkelRoot, GenerativeProcedural or
+# SpatialAudio from a family left out is unknown, so its transform would be
+# dropped. With them, every Xformable type C++ USD defines is known (UsdPhysics,
+# UsdUI and UsdSemantics define none).
+moho = { workspace = true, features = ["skel", "proc", "media"] }
 # Pure-Rust OpenSubdiv port (Far topology refinement + Sdc rules) driving
 # Catmull-Clark subdivision at USD import: zero dependencies,
 # `forbid(unsafe_code)`. Pinned to a release tag; the committed `Cargo.lock`
@@ -68,6 +73,8 @@ serde = { version = "1.0.229", features = ["derive"] }
 serde_json = "1.0.151"
 
 [dev-dependencies]
+# The import-parity check (`parity` feature) on for every test of this crate.
+crust-core = { path = ".", features = ["parity"] }
 criterion = "0.8"
 # `std` for `tracing::subscriber::with_default`, which the import tests use
 # to check which warnings a stage's render settings produce.

crates/crust-core/src/lib.rs

@@ -41,6 +41,9 @@ mod lux;
 mod material;
 mod medium;
 pub mod names;
+/// Import parity against the direct importer's baselines; test-only.
+#[cfg(feature = "parity")]
+pub mod parity;
 mod pdf;
 pub mod place;
 pub mod precomp;

crates/crust-core/src/live.rs

@@ -85,11 +85,52 @@ pub struct Provenance {
     pub(crate) stage: StageFacts,
 }
 
+#[cfg(feature = "parity")]
+impl Provenance {
+    /// Writes the provenance into an import-parity digest
+    /// ([`crate::parity`]), maps sorted by key so it is stable text.
+    pub(crate) fn parity_digest(&self, out: &mut String) {
+        use std::fmt::Write as _;
+        let mut materials: Vec<_> = self.materials.iter().collect();
+        materials.sort_by(|a, b| a.0.cmp(b.0));
+        for (path, origin) in materials {
+            let _ = writeln!(out, "provenance material {path}: {origin:?}");
+        }
+        for read in &self.material_reads {
+            let _ = writeln!(out, "provenance material read: {read:?}");
+        }
+        for source in &self.arc_sources {
+            let _ = writeln!(out, "provenance arc source: {source}");
+        }
+        let mut lights: Vec<_> = self.lights.iter().collect();
+        lights.sort_by(|a, b| a.0.cmp(b.0));
+        for (path, origin) in lights {
+            let _ = writeln!(out, "provenance light {path}: {origin:?}");
+        }
+        for (ids, path) in &self.geometry {
+            let _ = writeln!(out, "provenance geometry {ids:?}: {path}");
+        }
+        for mesh in &self.meshes {
+            let _ = writeln!(out, "provenance mesh: {mesh:?}");
+        }
+        for (i, slot) in self.mesh_slots.iter().enumerate() {
+            let _ = writeln!(out, "provenance mesh slot {i}: {slot:?}");
+        }
+        let _ = writeln!(out, "provenance spheres: {:?}", self.spheres);
+        let _ = writeln!(out, "provenance volumes: {:?}", self.volumes);
+        // The working space by name: `Space` is an id interned per process,
+        // in whatever order the process met the spaces.
+        let mut stage = self.stage.clone();
+        let working = stage.working.take().map(|w| w.name().to_owned());
+        let _ = writeln!(out, "provenance stage: {stage:?} working {working:?}");
+    }
+}
+
 /// The slots one material fills.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct MaterialOrigin {
     /// Every `World` slot whose material is this prim's: by `Arc` identity,
-    /// every streamed epoch's `Arc` of it included.
+    /// every streamed chunk's `Arc` of it included.
     pub slots: Vec<u32>,
     /// Whether a mesh displaced by it: its geometry depends on its inputs.
     pub displaced: bool,