[doubleailes]

Summary

Step S2 of Mantle's scene-index program. Crust's USD import now reads the stage through Moho, a Hydra 2.0-style scene index over openusd. The direct usd::Prim importer is removed: there is one route and no switch. An IPR frame and crust render -i read a scene the same way, and later live updates can work from Moho's dirty locators.

• Reading through Moho. Every schema family reads Hydra prims, schemas and generic attribute data from a Moho index:

  • settings and products;
  • camera;
  • transforms and motion;
  • meshes, implicit shapes and curves;
  • materials;
  • lights and light links;
  • volumes;
  • native and point instancing.

  A small stage uses one standard chain. A streamed stage uses masked chunk inputs merged with a payload-free scene input.

• Gated on parity. Each family moved on its own, gated by baselines recorded from the direct importer before anything moved:

  • for every sample and fixture: a scene digest, the crust check --json report and a 16 spp image hash;
  • for ALab and Moana: the report, the EXR, memory and time.

  Behaviour changes and accepted exceptions are listed in the design record (openspec/specs/usd-scene-import/design.md). They include:

  • undefined prims following USD's rule;
  • material bindings following Hydra's model;
  • inexact shutter offsets (f32, as Hydra);
  • cross-chunk and cross-instancer prototype reuse (D3c), which changes unique-triangle counts only, with images equal.

• openusd comes only through Moho (moho::openusd, moho::openusd_schemas), so Moho's pin is the stack's openusd rev. Moho is pinned at d09cc946.

• Removed: the epoch and EvalTimeScope. Stage listing helpers moved to listing.rs, and authored transform ops to stage_facts.

• hdCrust on hosts with glibc older than 2.38. hydra/hdCrust/test/crust_sysroot.sh and the pixi tasks compare-sysroot and interaction-sysroot run the CLI under the pixi sysroot's glibc. Then both sides of the comparison use the same libm. The underlying package issue is openusd 26.08 (linux-64) needs glibc 2.38 but its metadata allows any glibc anderslanglands/aswf-pixi#57.

Capability

usd-scene-import. The change is openspec/changes/moho-import/ (53/53 tasks, validates with --strict). Also updated:

• docs/architecture.md: Moho in the crate map and render flow, the index/ module, and two invariants (an index reader changes together with its in-place rebuild; one openusd, through Moho);
• the site page docs/architecture/usd-import.md.

Image impact

• Bit-identical: scripts/check_images.sh reports all 48 scenes identical.
  • The cornellbox_guided golden was an outlier of the nondeterministic guided render. It was re-rendered with the direct importer: 4 direct and 6 index renders agree.
  • ALab and Moana: report and EXR equal their baselines. Those baselines were re-recorded for the accepted D3c prototype reuse, and only unique-triangle counts changed.
• Changed intentionally
• Not applicable

Performance

Reported, not gated. These are not bench_ab.sh A/B runs: they come from the parity runs, each alone on the machine.

Scene	Peak memory	Parse USD stage
ALab	21.14 GiB (1.93x)	57.1 s (1.84x)
Moana	24.18 GiB (1.01x)	2171 s (12.5x)

Most of Moana's slowdown is in Moho's read path. The Moho streaming spike shows a similar gap: strategy D (reading through Moho) takes 7.7x as long as strategy B. Part of it is in Crust: materials missing from the top index build a fresh chain, 39 times on isHibiscus alone. With full LTO, cornellbox renders about 2.5% slower than the direct binary, with no render code changed and equal digests; this is unexplained and recorded.

These are follow-ups. Moho is moving to strict Hydra parity next (one loaded stage, no chunk streaming), and update latency will be profiled before first-load time.

Checklist

• cargo fmt --all -- --check (locally)
• cargo clippy --workspace --all-targets -- -D warnings (locally)
• cargo test --workspace --no-fail-fast (locally). The GitHub Rust workflow runs on this PR.
• Both halves of any pair in docs/architecture.md § Invariants changed together (index reader ↔ in-place rebuild, added here)
• No new unsafe, no new RNG outside openqmc, no asset decoding in crust-core
• Logging levels follow the rules
• User documentation in site/ updated (docs/architecture/usd-import.md; zola build OK)
• A new CRUST_* switch: none added

Hydra workflow (hdCrust, OpenUSD 26) passed on this branch at 58b1a25a: https://github.com/doubleailes/Crust/actions/runs/40494072921

🤖 Generated with Claude Code

https://claude.ai/code/session_01PUSvMHN9Akk66u2oG3rUbF

[qodo-code-review]

PR Summary by Qodo

Read USD scenes through Moho's scene index

✨ Enhancement 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Replace direct USD prim import with one Moho scene-index route for CLI and interactive renders.
• Preserve streamed import and in-place rebuilds while migrating geometry, materials, lights,
 settings, and instancing.
• Gate the migration with recorded scene, report, and image parity baselines.

Diagram

graph TD
  A["USD stage"] --> B["Moho inputs"] --> C["Merged index"] --> D["Index walk"] --> E["Schema readers"] --> F["Render world"]
  B --> D
  A --> G["Stage facts"] --> E

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Retain both import routes behind a switch

• ➕ Allows production fallback and direct side-by-side debugging.
• ➖ Duplicates schema behavior and delays establishing one source for future scene-index updates.

Recommendation: Prefer the single Moho route now that the schema families have parity coverage. Keeping the direct importer would reduce short-term migration risk but impose ongoing divergence across CLI, interactive rendering, and eventual dirty-locator handling.

Files changed (45) +8672 / -3005

Enhancement (6) +1331 / -1

live.rsSupport scene-index-backed live edits +42/-1

Support scene-index-backed live edits

• Adjusts live-scene state and edit handling for index-based imports.

crates/crust-core/src/live.rs

mod.rsConstruct single and streamed Moho index chains +233/-0

Construct single and streamed Moho index chains

• Builds the single-stage chain or merges a payload-free input with masked chunks and dependencies.

crates/crust-core/src/scene/usd_import/index/mod.rs

data.rsProvide typed access to Hydra prim data +493/-0

Provide typed access to Hydra prim data

• Wraps index prims, generic attributes, relationships, and prototype path rebasing for schema readers.

crates/crust-core/src/scene/usd_import/index/data.rs

instancers.rsInterpret Moho instancer metadata +58/-0

Interpret Moho instancer metadata

• Provides shared access to propagated native and point-instancer prototype information.

crates/crust-core/src/scene/usd_import/index/instancers.rs

network.rsDecode indexed material networks +384/-0

Decode indexed material networks

• Reads Hydra material contexts, terminals, shader parameters, connections, and forwarded graph values.

crates/crust-core/src/scene/usd_import/index/network.rs

walk.rsTraverse and prune indexed prims +121/-0

Traverse and prune indexed prims

• Preserves visit order and subtree-pruning behavior while walking Moho’s children rather than direct USD prims.

crates/crust-core/src/scene/usd_import/index/walk.rs

Refactor (16) +3796 / -2886

stage_facts.rsIsolate non-imaging USD stage reads +375/-0

Isolate non-imaging USD stage reads

• Keeps layer, composition, and authored-spec facts outside schema readers while obtaining stage metadata from the index.

crates/crust-core/src/scene/usd_import/index/stage_facts.rs

mod.rsRoute scene import through Moho +571/-565

Route scene import through Moho

• Replaces direct prim traversal with index dispatch and coordinates single-stage, streamed, and cached import state.

crates/crust-core/src/scene/usd_import/mod.rs

attrs.rsReuse typed decoders for indexed attributes +4/-222

Reuse typed decoders for indexed attributes

• Removes direct attribute-reading helpers now supplied by indexed generic data.

crates/crust-core/src/scene/usd_import/attrs.rs

camera.rsRead cameras from scene-index schemas +142/-87

Read cameras from scene-index schemas

• Moves camera properties and transforms to indexed data while retaining renderer camera behavior.

crates/crust-core/src/scene/usd_import/camera.rs

implicit.rsRead implicit shapes through Moho +73/-76

Read implicit shapes through Moho

• Migrates cube, plane, cylinder, cone, and capsule inputs from typed USD prims to index data.

crates/crust-core/src/scene/usd_import/implicit.rs

instancing.rsImport propagated and point-instancer prototypes +341/-189

Import propagated and point-instancer prototypes

• Uses Moho instancer data and propagated paths for prototype reuse and placement.

crates/crust-core/src/scene/usd_import/instancing.rs

light_links.rsResolve indexed light and shadow links +227/-72

Resolve indexed light and shadow links

• Uses Moho’s collection results across merged inputs and finalizes linking after streamed chunks.

crates/crust-core/src/scene/usd_import/light_links.rs

lights.rsImport lights from Hydra data +167/-148

Import lights from Hydra data

• Moves light attributes, shaping, and visibility reads to indexed schemas and generic data.

crates/crust-core/src/scene/usd_import/lights.rs

listing.rsSeparate stage listing from scene import +373/-61

Separate stage listing from scene import

• Moves stage inspection and listing helpers out of the importer’s main traversal.

crates/crust-core/src/scene/usd_import/listing.rs

live.rsRebuild live scenes through indexed readers +96/-74

Rebuild live scenes through indexed readers

• Updates masked-stage rebuilds to use Moho prim data and removes direct schema and time-scope reads.

crates/crust-core/src/scene/usd_import/live.rs

materials.rsResolve materials using indexed bindings +614/-639

Resolve materials using indexed bindings

• Migrates material lookup, caching, and shader dispatch to Hydra material bindings and networks.

crates/crust-core/src/scene/usd_import/materials.rs

mesh.rsRead mesh geometry from scene-index data +111/-141

Read mesh geometry from scene-index data

• Moves mesh topology, primvars, and geometry inputs off direct USD mesh schemas.

crates/crust-core/src/scene/usd_import/mesh.rs

mtlx_network.rsConsume indexed MaterialX networks +183/-288

Consume indexed MaterialX networks

• Builds MaterialX documents from indexed shader nodes and connections.

crates/crust-core/src/scene/usd_import/mtlx_network.rs

preview.rsConsume indexed USD Preview networks +259/-118

Consume indexed USD Preview networks

• Migrates preview-surface and texture graph handling to Hydra network data.

crates/crust-core/src/scene/usd_import/preview.rs

xform.rsEvaluate indexed transforms and motion +260/-153

Evaluate indexed transforms and motion

• Uses index transforms and explicit time handling, including shutter samples, instead of direct prim evaluation.

crates/crust-core/src/scene/usd_import/xform.rs

time.rsRemove the importer’s time scope +0/-53

Remove the importer’s time scope

• Deletes EvalTimeScope because indexed reads carry their own evaluation time.

crates/crust-core/src/scene/usd_import/time.rs

Documentation (6) +1554 / -81

architecture.mdDocument Moho’s place in rendering +35/-16

Document Moho’s place in rendering

• Updates the crate map, import flow, index layout, and USD dependency invariants.

docs/architecture.md

usd-import.mdDocument the scene-index importer +75/-0

Document the scene-index importer

• Adds a site architecture page describing Moho-based USD import.

site/content/docs/architecture/usd-import.md

design.mdRecord migration design and parity decisions +619/-0

Record migration design and parity decisions

• Documents index-chain choices, streaming, prototype handling, accepted differences, and validation.

openspec/changes/moho-import/design.md

proposal.mdPropose the Moho import migration +108/-0

Propose the Moho import migration

• States the motivation, scope, and intended outcome of the scene-index step.

openspec/changes/moho-import/proposal.md

tasks.mdTrack the importer migration +375/-0

Track the importer migration

• Records family-by-family implementation and validation tasks.

openspec/changes/moho-import/tasks.md

design.mdUpdate the USD import design record +342/-65

Update the USD import design record

• Replaces direct-import assumptions with scene-index architecture and documented behavioral exceptions.

openspec/specs/usd-scene-import/design.md

Other (17) +1991 / -37

Cargo.tomlPin Moho as the workspace USD dependency +10/-16

Pin Moho as the workspace USD dependency

• Replaces direct openusd workspace dependencies and patches with a pinned Moho dependency and its openusd re-exports.

Cargo.toml

Cargo.lockLock the Moho dependency graph +16/-9

Lock the Moho dependency graph

• Records the Moho pin and corresponding openusd dependency changes.

Cargo.lock

Cargo.tomlWire Moho and parity into crust-core +19/-12

Wire Moho and parity into crust-core

• Moves importer dependencies through Moho and configures test-only parity support.

crates/crust-core/Cargo.toml

lib.rsExpose import parity under its feature +3/-0

Expose import parity under its feature

• Registers the parity module for test-enabled builds.

crates/crust-core/src/lib.rs

parity.rsCompare each test import with direct-import baselines +502/-0

Compare each test import with direct-import baselines

• Adds normalized scene digests and optional 16-spp image hashes, with baseline recording and comparison.

crates/crust-core/src/parity.rs

rt_world.rsExpose stable render-world parity facts +121/-0

Expose stable render-world parity facts

• Adds world and geometry inspection needed to construct deterministic import digests.

crates/crust-core/src/rt_world.rs

import_parity.rsCheck sample-scene import reports +290/-0

Check sample-scene import reports

• Compares normalized 'crust check --json' results against direct-import baselines for committed samples.

crates/crust-render/tests/import_parity.rs

instanced_instancers.rsCover nested instancer combinations +483/-0

Cover nested instancer combinations

• Adds regression tests for prototype and instancer interactions under the Moho import route.

crates/crust-core/tests/instanced_instancers.rs

one_openusd.rsEnforce one openusd dependency +54/-0

Enforce one openusd dependency

• Fails if a crate depends on openusd directly rather than through Moho.

crates/crust-core/tests/one_openusd.rs

streamed_light_links.rsTest linking across streamed chunks +72/-0

Test linking across streamed chunks

• Exercises light-link behavior when linked prims lie outside the current chunk.

crates/crust-core/tests/streamed_light_links.rs

streamed_materials.rsTest materials outside streamed chunks +121/-0

Test materials outside streamed chunks

• Covers bindings and shader dependencies resolved through merged side inputs.

crates/crust-core/tests/streamed_materials.rs

xform_uncomposable.rsCover unusual transform stacks +50/-0

Cover unusual transform stacks

• Adds regression coverage for transforms the indexed representation cannot compose conventionally.

crates/crust-core/tests/xform_uncomposable.rs

import_parity.shCompare large-scene reports and EXRs +132/-0

Compare large-scene reports and EXRs

• Records or checks ALab and Moana parity, reporting import memory and time without gating on performance.

scripts/import_parity.sh

parity_images.shRun sample image-parity checks +57/-0

Run sample image-parity checks

• Automates image comparison against the committed expected parity set.

scripts/parity_images.sh

parity_images.expectedRecord expected image-parity results +28/-0

Record expected image-parity results

• Lists the expected image comparisons used by the parity script.

scripts/parity_images.expected

crust_sysroot.shRun the CLI under pixi’s glibc sysroot +18/-0

Run the CLI under pixi’s glibc sysroot

• Makes the comparison CLI use the same loader and libm as hdCrust on older-glibc hosts.

hydra/hdCrust/test/crust_sysroot.sh

pixi.tomlAdd sysroot comparison tasks +15/-0

Add sysroot comparison tasks

• Provides compare-sysroot and interaction-sysroot tasks for older-glibc Linux hosts.

hydra/pixi.toml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. A sample import mismatch can pass the image gate ✓ Resolved

Description

parity_images.sh excludes every failure and parity diagnostic from tests named in
parity_images.expected, regardless of why the test failed. That list includes
every_sample_imports_as_its_baseline, so a baseline mismatch in the sample-import test can be
suppressed and the gate can report success.

Code

scripts/parity_images.expected[17]

+every_sample_imports_as_its_baseline

Relevance

●●● Strong

Baseline-gate precedents accept fixes preventing missing or failed comparisons from passing
silently.

PR-#174

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The script filters parity diagnostics and failed-test names using the expected list before deciding
its status. The listed sample test performs baseline comparisons, so its actual mismatches fall
under both filters.

scripts/parity_images.sh[32-55]
scripts/parity_images.expected[17-17]
crates/crust-render/tests/import_parity.rs[138-180]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The image runner treats all failures in listed tests as expected, including import-parity failures in the sample baseline test.
## Fix Focus Areas
- scripts/parity_images.expected[17-17]
- scripts/parity_images.sh[34-52]
## Recommended Fix
Make any baseline or parity mismatch fail the runner regardless of test name. Apply the expected-test allowance only to the specific unrelated failure for which each test is listed.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Referenced-layer textures load from the wrong directory ✓ Resolved

Description

asset_value_path anchors an unresolved relative asset path to the root stage directory, replacing
the authoring-layer lookup previously used by asset_path. When a sublayer or reference authors a
path such as a UDIM texture with no resolved path, preview and MaterialX readers can request a
nonexistent or different file.

Code

crates/crust-core/src/scene/usd_import/preview.rs[372]

+    let file = value(tk::FILE).and_then(|v| asset_value_path(&v, caches.stage_path));

Relevance

●●● Strong

Recent importer precedents accept fixes for incorrect asset resolution and unresolved texture
handling.

PR-#194
PR-#333

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new texture reader passes only the value and root stage path to a helper whose fallback joins
that path's parent. The removed helper used the attribute property stack's first authoring layer for
unresolved relative values; the MaterialX reader also uses the new helper.

crates/crust-core/src/scene/usd_import/preview.rs[366-372]
crates/crust-core/src/scene/usd_import/assets.rs[153-175]
crates/crust-core/src/scene/usd_import/mtlx_network.rs[343-344]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Unresolved relative texture assets are now anchored to the root stage rather than the layer that authored their attribute.
## Fix Focus Areas
- crates/crust-core/src/scene/usd_import/preview.rs[366-372]
- crates/crust-core/src/scene/usd_import/mtlx_network.rs[343-344]
- crates/crust-core/src/scene/usd_import/assets.rs[153-175]
## Recommended Fix
Preserve the authoring layer for unresolved asset parameters and resolve relative paths against it. Use the root stage directory only when that layer cannot be determined, and cover a UDIM path authored in a referenced or sublayered file.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Parity image run passes when the build fails ✓ Resolved

Description

scripts/parity_images.sh runs cargo test --release --workspace --no-fail-fast without checking
its exit status, then determines success solely from parity: panics and test … FAILED lines in
the log. If compilation fails, Cargo stops before tests run, or a test binary aborts before printing
results, neither pattern appears, so the script prints “every import renders as its baseline” and
exits 0, making the parity gate look green.

Code

scripts/parity_images.sh[R29-32]

+CARGO_PROFILE_RELEASE_LTO=false CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 \
+    cargo test --release --workspace --no-fail-fast >"$LOG" 2>&1
+
+status=0

Relevance

●●● Strong

This is a deterministic gate bug: ignored Cargo failure status can falsely produce success.

PR-#174

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Line 20 uses set -uo pipefail without -e, and lines 29–30 run Cargo without checking its exit
status. Line 32 initializes status=0; lines 33–53 change it only when parity-panic text or
failed-test lines appear, and lines 54–57 report success otherwise. A failure before test results
are printed produces neither match, so the script exits 0.

scripts/parity_images.sh[20-57]
scripts/parity_images.sh[20-32]
scripts/parity_images.sh[34-57]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`scripts/parity_images.sh` can report parity success when `cargo test` fails before executing tests or before printing test results.

## Fix Focus Areas
- scripts/parity_images.sh[29-57]

## Recommended Fix
Capture the Cargo exit status, for example with `cargo test ... >"$LOG" 2>&1; cargo_status=$?`, and require evidence that the intended test run completed. Preserve the handling of identified test failures, but if Cargo exits nonzero without `test ... FAILED` lines, print the tail of `$LOG` and set `status=1`. Also consider failing when the log contains no `test result:` line.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

❌ Tickets: failed to load — Ticket collection could not establish complete evidence

✅ Cross-repo context — repo relationships

  Explored: repo: doubleailes/OpenSubdiv-rs (sha: 74f2199c) — View relationship

  Explored: repo: doubleailes/Mantle (sha: 4d89ab35) — View relationship

  Explored: repo: doubleailes/Obsidian (sha: 7e84febb) — View relationship

Review mode: Auto: 🧠 Deep: Massive cross-cutting importer rewrite spans many independent logic paths.

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[doubleailes]

Replies to the Qodo review (comment 6444723949). Each finding was verified against the code first.

1. A sample import mismatch can pass the image gate: real, fixed in ab55f84.

• A test listed in parity_images.expected had all of its failures excused, including baseline mismatches.
• Now every parity: diagnostic fails the run, whichever test or crust process raised it. The one exception is an image difference of a stage listed as stage:<file>: only cornellbox_guided.usda, whose guided render is nondeterministic. Its digest is still compared.
• A listed test's own failure is still excused, but never its import differences.
• every_sample_imports_as_its_baseline is no longer listed. In the image run it still runs every sample's check, which compares the digest and image in the crust process, and only skips the report comparison. The second import doubles the texture counts that comparison would see.

2. Referenced-layer textures load from the wrong directory: real for string-typed paths, fixed in b5ee1de. Details are in the reply on the inline comment.

3. The parity image run passes when the build fails: real, fixed in ab55f84.
The run now fails on any of these:

• a build error;
• a test target that reports no test result line, for example a binary that aborted;
• cargo exiting non-zero with no failed test.

I checked the script against synthetic logs:

• listed failures plus a guided image difference: passes;
• a guided digest difference: fails;
• a parity mismatch inside a listed test: fails;
• a compile error: fails;
• an aborted test binary: fails.

The real run (scripts/parity_images.sh) passes on b5ee1de.

Also on this branch, f58c950 fixes the CI test failure. sample_imports_are_deterministic now skips, with a message, a sample whose absolute external references are absent; on CI that is the uncommitted DPEL MaterialX assets. Samples whose assets are present are still compared, the same way import_parity.rs already skips them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PUSvMHN9Akk66u2oG3rUbF