StageTrace
OpenUSD diagnostic provenance

See what won.
Trace why.

StageTrace helps pipeline TDs and USD tools engineers turn a surprising composed result into the value source, losing opinions, causal composition path, and a conservative next action.

See the three diagnosticsShare a real problem
CLI implementedGUI not yet builtPlatform macOS arm64 developmentAssets stay local

01 / The problem

OpenUSD gives the composed answer. Debugging still means correlating several views by hand.

A property stack can contain specs that do not author the winning value. A time query can resolve through samples, clips, splines, fallback, or a block. Visibility can be inherited from an ancestor. The useful answer is not merely “the value is X.”

StageTrace is for people who already know USD and need a faster, reviewable path from a symptom to the actual source evidence.

02 / Three useful questions

Facts first. Correlation second. Recommendations last.

Browse every command
01

$ why

Which opinion produced this value?

Fixture: Tests/Fixtures/diagnostic_local_over_reference.usda

{
  "command": "why",
  "status": "ok",
  "data": {
    "propertyPath": "/World/Referenced.test:size",
    "resolvedValue": "9",
    "sourceKind": "authoredDefault",
    "winner": {
      "path": "/World/Referenced.test:size",
      "value": "9",
      "role": "winner",
      "sourceKind": "authoredDefault",
      "arcType": "root"
    },
    "competingOpinions": [
      { "path": "/Model.test:size", "value": "5", "role": "weaker", "arcType": "reference" }
    ],
    "safeEditRecommendation": {
      "canEdit": true,
      "action": "authorSessionOverride",
      "reason": "supportedAttributeType"
    }
  }
}

Resolve one property and correlate its value source, competing opinions, causal arc, and safe action.

Open JSON Schema
02

$ visibility

What actually made this prim invisible?

Fixture: Tests/Fixtures/diagnostic_visibility_reference_root.usda

{
  "command": "visibility",
  "status": "ok",
  "data": {
    "primPath": "/World/Referenced/Child",
    "computedVisibility": "invisible",
    "blockingOpinion": {
      "path": "/Model.visibility",
      "value": "invisible",
      "sourceKind": "authoredDefault",
      "arcType": "reference"
    },
    "safeEditRecommendation": {
      "canEdit": true,
      "path": "/World/Referenced.visibility",
      "action": "authorSessionOverride"
    }
  }
}

Compute effective visibility and identify the actual invisible ancestor and opinion.

Open JSON Schema
03

$ explain

How do the answers fit together?

Fixture: Tests/Fixtures/diagnostic_default_vs_time_samples.usda

{
  "command": "explain",
  "status": "ok",
  "data": {
    "mode": "property",
    "timeCode": "1.5",
    "probe": { "targetKind": "attribute", "stageRevision": 1 },
    "property": {
      "resolvedValue": "15",
      "sourceKind": "timeSamples",
      "winner": { "value": "15", "timeCode": "1.5", "sourceKind": "timeSamples" }
    },
    "visibility": { "computedVisibility": "inherited" },
    "editability": { "editableByCurrentEdit": true, "propertyKind": "attribute" }
  }
}

Combine property, composition, visibility, layer, and editability context from one stage snapshot.

Open JSON Schema

03 / How it works

StageTrace does not replace OpenUSD’s resolver.

OpenUSD resolves the value and visibility facts. StageTrace reads the same stage snapshot, correlates resolve information with property-stack and composition evidence, classifies what can safely be edited, and formats the result for a human or pipeline.

Resolved through bundled OpenUSD, cross-checked against direct OpenUSD queries, and emitted as schema-validated JSON.

JSON Schema validates output structure. It does not prove semantic truth. Truth confidence comes from deterministic edge-case fixtures, direct OpenUSD differential assertions, and optional real-asset semantic sampling.

  1. 1
    Resolve

    Query the target, time, and load policy through bundled OpenUSD.

  2. 2
    Correlate

    Match the resolved source to real authored sites and the causal composition node.

  3. 3
    Constrain

    Recommend only the non-destructive actions the current edit model supports.

  4. 4
    Emit

    Return readable text or stable, schema-validated JSON.

04 / Current boundary

Done now

Diagnostic CLI foundation

  • CLI commands for inventory, validation, composition, provenance, visibility, explain, edits, export, projects, and watch.
  • Typed JSON contracts and deterministic fixtures for diagnostic edge cases.
  • Direct differential checks against the bundled OpenUSD runtime.
May come next

Evidence-led workflow expansion

  • Folder and batch workflows, file/report output, and validation profiles—only where pipeline demand is clear.
  • Signed private CLI builds after legal, supply-chain, safety, and packaging gates.
  • Linux CLI or a macOS GUI based on qualified user evidence, not assumption.

05 / Asset boundary

Your scene does not become someone else’s dataset.

StageTrace runs against files on your machine. The planned product does not upload USD assets, layers, textures, or paths to a hosted analysis service. The research form below is separate and stores only the answers you choose to submit.

06 / Join the research

Bring the last USD problem that took too long.

This first round is five short conversations about the problem, platform, and workflow—not a sales call and not a claim that an interview validates correctness. A private binary comes later, only after the distribution gates and real interest.

Local-first product. This form stores only what you enter—never your USD files or asset paths.