Keep schema fallbacks source-owned

Let source-neutral adapters supply registered schema metadata at resolution time while keeping the PXR registry authoritative for USD imports. Remove the copied fallback catalog so unregistered schemas retain only their compatibility behavior.

Author: adenzler-nvidia

CHANGELOG.md

@@ -24,8 +24,7 @@
 - Add opt-in filtering of static-static, static-kinematic, and kinematic-kinematic contacts during broad-phase collision detection. Set `CollisionPipeline(include_static_kinematic_pairs=False)` to enable filtering; the default preserves existing contact generation. `Model.shape_contact_pairs` remains an unfiltered superset for direct consumers such as `SolverKamino` and hydroelastic SDF setup.
 - Add opt-in `body_frame_origin="com"` to `ModelBuilder.add_rod()` and `ModelBuilder.add_rod_graph()` for COM-centered cable capsule body frames.
 - Add `sign_method` argument to `Mesh.build_sdf` and `SDF.create_from_mesh` support for a `"normal"` (angle-weighted pseudo-normal) sign strategy, for selecting the inside/outside sign of the baked SDF (`"auto"`, `"parity"`, `"winding"`, or `"normal"`).
-- Add opt-in source-neutral USD schema resolution through `newton.usd.create_schema_resolution()` and `ModelBuilder.add_usd(schema_resolution=...)`, allowing populated scene sources to reuse Newton's schema precedence, conversions, and built-in fallbacks.
-- Add source-neutral USD schema resolution through `newton.usd.SchemaResolution` and `ModelBuilder.add_usd(schema_resolution=...)`, allowing populated scene sources to reuse Newton's schema precedence, conversions, and built-in fallbacks.
+- Add source-neutral USD schema resolution through `newton.usd.SchemaResolution` and `ModelBuilder.add_usd(schema_resolution=...)`, allowing populated scene adapters to reuse Newton's precedence and conversions with adapter-supplied registered schema fallbacks.
 - Add `forward_depth_image` output support to `SensorTiledCamera.update()` and `SensorTiledCamera.utils.create_forward_depth_image_output()` for native forward-depth rendering without post-processing `depth_image`.
 - Add optional `shear_stiffness`/`shear_damping` and `twist_stiffness`/`twist_damping` controls to `ModelBuilder.add_joint_cable()`, `ModelBuilder.add_rod()`, and `ModelBuilder.add_rod_graph()`; omitted shear defaults to stretch and omitted twist defaults to bend for compatibility.
 - Add `newton.utils.CableStiffness` and extend `newton.utils.create_cable_stiffness_from_elastic_moduli()` with `poissons_ratio`/`shear_modulus` inputs that include torsional `GJ/L` stiffness.

docs/design/schema-resolution.md

@@ -19,19 +19,20 @@ the current `ModelBuilder.add_usd()` construction path and behavior. One typed
 existing `schema_resolvers=` argument constructs that object internally.
 Applied schema identity is part of the input: an applied schema owns the
 properties it defines, including its USD fallbacks. Resolver definitions
-identify ownership and conversion. A private catalog supplies built-in Newton,
-PhysX, and MuJoCo fallbacks when their schema plugins are unavailable. Batched
-resolution, Warp functions, and direct ModelBuilder buffer population are
-deliberately deferred.
+identify ownership and conversion. The source adapter supplies registered
+schema fallbacks: the PXR adapter reads them from `Usd.SchemaRegistry`, while a
+PXR-free adapter provides the equivalent versioned schema metadata explicitly.
+Batched resolution, Warp functions, and direct ModelBuilder buffer population
+are deliberately deferred.
 
 ## Goals
 
 - Keep core Newton as the single owner of schema precedence and conversion.
 - Preserve the behavior of `add_usd()` and `schema_resolvers=` by default.
 - Resolve values and applied schemas supplied without a `Usd.Prim`.
 - Read fallbacks from registered USD schemas on the PXR path.
-- Share built-in fallbacks with schema-neutral sources.
-- Let callers override or extend the fallback catalog for other schema versions.
+- Accept registered schema fallbacks from schema-neutral source adapters.
+- Keep schema metadata versioning in the adapter that owns the scene source.
 - Keep the external mechanism small and hide candidates, provenance, and storage.
 - Make the scalar contract suitable for later columnar and Warp execution.
 - Let non-PXR scene consumers reuse the resolver without changing their
@@ -86,13 +87,14 @@ fallback(schema_name, attribute_name) -> raw USD value or missing
 
 The PXR adapter reads authored values and applied/type metadata, then asks
 `Usd.SchemaRegistry` for the composed prim definition and its attribute
-fallbacks. A non-PXR source provides already-composed values and recorded
-schema identity; the resolver uses Newton's private fallback catalog. Resolver
-priority, transformations, and selected-source provenance are shared. Once the
-composed policy is active, an applied schema that owns a requested property but
-has no fallback in either the registry or catalog fails instead of silently
-using a builder default. During the audit period, that future error does not
-break the legacy result.
+fallbacks. A non-PXR source provides already-composed values, recorded schema
+identity, and the fallbacks for schemas it treats as registered. Resolver
+priority, transformations, and selected-source provenance are shared.
+
+Schemas without authoritative metadata remain a second-class compatibility
+path. Their authored values still participate in resolver priority, while
+importer defaults precede resolver compatibility defaults. They do not claim
+registered-schema fallback ownership.
 
 Canonical USDPhysics descriptors remain importer inputs. Resolvers only supply
 extension-schema properties such as armature, friction, contact parameters,
@@ -131,17 +133,17 @@ The same object resolves mapping inputs directly:
 ```python
 resolution = newton.usd.SchemaResolution(
     resolvers,
-    # Only needed for custom schemas or version-specific overrides.
-    schema_fallbacks={
-        "ExampleJointAPI": {"example:armature": 0.0},
-    },
 )
 requirements = resolution.requirements(PrimType.JOINT)
 schemas = resolution.schemas(PrimType.JOINT)
 properties = resolution.resolve(
     PrimType.JOINT,
     values,
     schemas=applied_schemas,
+    # Registered schema metadata supplied by this source adapter.
+    schema_fallbacks={
+        "ExampleJointAPI": {"example:armature": 0.0},
+    },
     defaults={"armature": builder.default_joint_cfg.armature},
 )
 ```
@@ -165,9 +167,10 @@ path, not the future hot path.
 `SchemaResolution` through the PXR adapter. It constructs a default Newton
 resolution when neither argument is supplied and wraps `schema_resolvers=` when
 that shorthand is used. The adapter caches composed schema fallbacks by prim
-type and schema. An explicitly supplied fallback table is used only when the
-registered schema cannot provide the property. Attribute collection for the
-returned `schema_attrs` dictionary remains separate and unchanged.
+type and schema. `Usd.SchemaRegistry` remains authoritative on this path;
+`schema_fallbacks` is input for source-neutral `resolve()` calls. Attribute
+collection for the returned `schema_attrs` dictionary remains separate and
+unchanged.
 
 The first implementation does not move every higher-level rule out of
 `import_usd.py`. Source-specific branches such as MuJoCo raw-limit provenance,
@@ -178,8 +181,8 @@ small behavior-preserving changes after the common scalar engine is established.
 
 A schema-aware scene source supplies attribute values plus typed and applied
 schema identities to the same `SchemaResolution` inside its existing body,
-shape, and joint loops. It uses Newton's built-in fallback catalog, so it owns
-no schema-default table. Topology discovery, ordering, and
+shape, and joint loops. It also supplies the registered fallbacks for the
+schema versions its transport exposes. Topology discovery, ordering, and
 `ModelBuilder.add_*()` calls remain source concerns. Equivalent local
 precedence and conversion code can be removed as each entity family moves to
 the shared engine.
@@ -217,8 +220,9 @@ host to report after execution. Diagnostic representation is not public.
   authored nonzero, resolver ordering, transformations, and missing values.
 - The same values and schema identity resolve equally through PXR and mapping
   sources.
-- Every built-in owned mapping has an entry in the private fallback catalog.
-- Registered Newton schema fallbacks match the catalog exactly.
+- Adapter-supplied fallbacks establish registered ownership without importing
+  PXR.
+- Registered Newton schema fallbacks are read directly from the PXR registry.
 - Legacy PXR-only callbacks continue to work and fail explicitly through the
   source-neutral facade.
 - Later cross-source tests compare final builder/model fields against

newton/_src/sim/builder.py

@@ -3395,6 +3395,7 @@ def add_usd(
         parse_mujoco_options: bool = True,
         mesh_maxhullvert: int | None = None,
         schema_resolvers: list[SchemaResolver] | None = None,
+        schema_resolution: SchemaResolution | None = None,
         use_applied_schema_fallbacks: bool = False,
         force_position_velocity_actuation: bool = False,
         convert_mjc_equality_constraints: bool = True,
@@ -3520,8 +3521,12 @@ def add_usd(
 
                 .. experimental::
 
-                    The ``schema_resolvers`` and ``use_applied_schema_fallbacks``
-                    arguments may change without prior notice.
+                    The ``schema_resolvers``, ``schema_resolution``, and
+                    ``use_applied_schema_fallbacks`` arguments may change without
+                    prior notice.
+            schema_resolution: Reusable source-neutral schema resolution. It is
+                mutually exclusive with ``schema_resolvers`` and owns the applied
+                schema fallback policy when provided.
             use_applied_schema_fallbacks: True uses an applied schema's registered
                 USD fallback before importer defaults and lower-priority resolvers,
                 opting into the future behavior without migration warnings. The
@@ -3648,6 +3653,7 @@ def add_usd(
             parse_mujoco_options=parse_mujoco_options,
             mesh_maxhullvert=mesh_maxhullvert,
             schema_resolvers=schema_resolvers,
+            schema_resolution=schema_resolution,
             use_applied_schema_fallbacks=use_applied_schema_fallbacks,
             force_position_velocity_actuation=force_position_velocity_actuation,
             convert_mjc_equality_constraints=convert_mjc_equality_constraints,