feat(stage): track unresolved assets during composition

[yohawing]

Adds the ability to inspect a stage even when some referenced / payloaded assets cannot be resolved.

pub fn unresolved_assets(&self) -> &[String]

When Stage::open recursively walks references and payloads, any asset path the resolver cannot map to a physical file is recorded rather than causing the whole open to fail. The stage is partially constructed, and callers (e.g. asset-health linters, viewers) can read unresolved_assets() to see what's missing.

Implementation

• Adds compose::collect_layers_recording() next to the existing collect_layers(). The original collect_layers() keeps its current signature, so no callers break.
• Stage::open now uses collect_layers_recording and stores the resulting Vec<String> on the stage.
• The recorded paths are the canonical identifiers from Resolver::create_identifier.

Design judgment that may want discussion

The root layer is treated asymmetrically: if the file passed to Stage::open itself cannot be found, Stage::open still returns Err exactly like before. Only the transitive dependencies discovered during composition are recorded as unresolved.

The reasoning: from a caller's perspective, "the file you asked me to open does not exist" is almost always a hard error worth surfacing immediately, while "one of its references is missing" is usually something the caller wants to inspect rather than abort on. But I can see an argument for symmetry — happy to switch to "always Ok, record everything" if you'd prefer that contract. Wanted to flag it explicitly.

Tests

Two new fixtures + tests covering: missing transitive reference, and the existing root-not-found path still returning Err.

[yohawing]

Hi @mxpv,

Apologies — this PR (and the other four in this batch: #41 #42 #43 #44 #45) was opened by an AI agent on my behalf without enough human review of upstream etiquette. I should have filed an issue first to discuss before dropping a stack of code on you. Sorry for the noise.

For context: I'm building yw-look, a Windows quick-look style asset inspector for CG workflows, and I need a few small accessors on top of openusd to surface stage metadata (upAxis, metersPerUnit) and detect broken references in user assets. These five PRs are the minimal set of additions I needed.

If the API and approach look reasonable to you, I'd be grateful if you could merge them. If not — totally fine to close, I'd just maintain them on my fork instead. Happy to revise based on any feedback.

Thanks for the great crate!

[Copilot]

Pull request overview

This PR introduces “partial stage open” support by recording unresolved transitive asset dependencies (references/payloads) during composition instead of failing the entire Stage::open, enabling callers to inspect what’s missing.

Changes:

• Added unresolved-asset tracking to Stage plus a new Stage::unresolved_assets() accessor.
• Introduced compose::collect_layers_recording() to return both collected layers and unresolved asset identifiers, and updated Stage::open to use it.
• Added new fixture layers + tests covering both “no unresolved assets” and “missing transitive assets are recorded”.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
src/stage.rs	Stores unresolved identifiers on the stage and exposes them via unresolved_assets(); open() now uses the recording collector.
src/compose/mod.rs	Adds collect_layers_recording() and updates recursive layer collection to record missing transitive assets instead of erroring.
fixtures/unresolved_assets.usda	New fixture with missing reference + payload to validate unresolved recording.
fixtures/unresolved_assets_none.usda	New fixture with no external dependencies to validate the empty unresolved list case.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Stage::open's doc comment still says it "recursively resolves and loads all referenced layers". With the new behavior (missing transitive assets are recorded and skipped), this description is no longer accurate and may mislead callers about when open returns Ok. Update the doc here to explicitly mention partial construction / unresolved recording (and ideally point to unresolved_assets()).

Suggested change

	/// Recursively resolves and loads all referenced layers, then builds a
	/// composed stage ready for queries.
	/// Recursively resolves and loads referenced layers to build a composed
	/// stage ready for queries.
	///
	/// If some transitive assets cannot be resolved, this may still return
	/// `Ok` with a partially constructed stage; unresolved asset paths are
	/// recorded and can be inspected with [`Stage::unresolved_assets`].

[Copilot]

collect_layers previously errored when any referenced/payloaded asset couldn't be resolved; after this change it silently drops unresolved transitive layers (and discards the list). This is a semantic change to a public API, and the current doc comment above still claims that "each discovered asset path is resolved ... loaded" and that it loads the full dependency stack. Consider either (a) keeping collect_layers strict by returning an error when the unresolved list is non-empty, or (b) updating the collect_layers docs to clearly state that unresolved transitive assets are skipped and no longer reported via Err.

[Copilot]

unresolved.contains(&identifier) is redundant because visited is checked before resolution and the missing-asset branch inserts the identifier into visited before returning—so you should never reach this branch twice for the same identifier. You can drop the contains check and always push, or (if you also want to protect against future refactors) maintain membership via a HashSet<String> alongside the Vec<String> to avoid O(n) scans while preserving encounter order.

Suggested change

	if !unresolved.contains(&identifier) {
	unresolved.push(identifier.clone());
	}
	unresolved.push(identifier.clone());

[mxpv]

I went with a slightly different approach in #46. Instead of storing unresolved paths on the Stage, composition errors are surfaced through a callback that the caller controls:

// Default behavior — hard error on any failure (unchanged)
let stage = Stage::open("scene.usda")?;

// Permissive — caller decides per-error
let stage = Stage::builder()
    .on_error(|err| {
        eprintln!("warning: {err}");
        Ok(()) // skip and continue
    })
    .open("scene.usda")?;

The callback receives a CompositionError with full context (asset path, referencing layer, dependency kind, prim path), and returns Result<()> — Ok(()) to continue, Err to abort. This way callers can log, collect, filter, or bail as needed without the Stage carrying extra state.

I'm going to close this one. Let me know if anything is missing.