UsdStage::OpenMasked populates active stage caches despite its documented contract

Description of Issue

The OpenMasked documentation says these methods do not automatically consult or populate UsdStageCache instances. In USD 25.02, OpenMasked creates a fresh stage but inserts it into an active writable stage cache. A subsequent ordinary Open can then return that same stage.

This matters for callers that use OpenMasked to create temporary stages: the caller's cache retains the stage, and subsequent Open calls can observe its session-layer edits.

The same implementation path is present in dev commit c280060fd937c1d30debb5c918a13200684b4edb (September 18, 2026):

• Documented contract in stage.h.
• OpenMasked calls _InstantiateStage.
• _InstantiateStage inserts into writable caches.

Could you clarify whether OpenMasked should avoid cache insertion as documented, or whether cache insertion is intentional and the documentation should change?

AI assistance: this report was researched and drafted with AI assistance. The reproducer was executed against USD 25.02; the dev comparison is source inspection only.

Steps to Reproduce

1. Run the following Python script. No external asset is needed.

from pxr import Sdf, Usd

root = Sdf.Layer.CreateAnonymous("cache-repro.usda")
cache = Usd.StageCache()
with Usd.StageCacheContext(cache):
    masked = Usd.Stage.OpenMasked(root, Usd.StagePopulationMask.All())
    print("Cache size after OpenMasked:", cache.Size())
    ordinary = Usd.Stage.Open(root)
    print("Open returns masked stage:", ordinary == masked)

Expected from the documented contract:

Cache size after OpenMasked: 0
Open returns masked stage: False

Observed on USD 25.02:

Cache size after OpenMasked: 1
Open returns masked stage: True

The local execution used the downstream package's falcor2.pxr import namespace; the script above uses the standard upstream pxr spelling. The API calls are otherwise identical.

System Information (OS, Hardware)

Windows 11, build 26200, x86-64. The reproduction uses CPU-only USD APIs and does not create a renderer or GPU device.

Package Versions

• OpenUSD 25.02 (Usd.GetVersion() returns (0, 25, 2)): runtime reproduction.
• Python 3.12.13.
• OpenUSD dev c280060fd937c1d30debb5c918a13200684b4edb: source inspection only; not built or executed for this report.

Build Flags

Downstream packaged Windows build with Python bindings, consumed from a Release application build. A separate stock upstream build was not tested; the original USD configure command is not included in this report.