Plan pure Swift shell over SwiftUsd/OpenUSD

[elkraneo]

Summary

Create a pure Swift shell over SwiftUsd so application and feature targets can use OpenUSD functionality without importing raw Swift/C++ interop types or enabling C++ interop themselves.

The goal is not to replace SwiftUsd. SwiftUsd remains the runtime binding and engine layer over OpenUSD. SwiftUsdShell becomes the stable pure Swift SDK surface: handles, values, DTOs, protocols, semantic requests, and results.

Productization Goal

The main goal is to productize OpenUSD as an SDK capability that is painless for host applications:

• Hosts should not import OpenUSD, raw SwiftUsd/OpenUSD C++ interop modules, or USDInteropCxx.
• Hosts should not need Swift/C++ interop enabled just to inspect, validate, or edit USD assets.
• Hosts should avoid paying large build-time and invalidation costs from raw OpenUSD headers in app and feature targets.
• Common workflows should be driven through pure Swift APIs and stable DTOs.

Architectural Clarification

The intended final layering is:

OpenUSD
  Native USD engine and C++ implementation.

SwiftUsd
  Swift runtime/binding layer over OpenUSD.
  Owns direct OpenUSD interaction wherever possible.
  Generic missing authoring/inspection primitives should be added here first.

SwiftUsdShell
  Pure Swift public SDK surface.
  No OpenUSD import.
  No Swift/C++ interop.
  Defines handles, paths, tokens, values, DTOs, protocols, semantic requests, and results.

First-party USD packages, such as USDTools
  Product/domain workflows over SwiftUsdShell APIs.
  Keep raw runtime details private and transitional.
  Public APIs must stay pure Swift and shell-facing.

Application and external consumers
  Import SwiftUsdShell and pure Swift domain APIs.
  Do not import OpenUSD, USDInteropCxx, or raw SwiftUsd/OpenUSD interop surfaces.

SwiftUsdShellRuntime should not become a renamed USDInterop. If a runtime implementation target exists, it should prefer SwiftUsd as its implementation dependency and only drop to raw OpenUSD for explicitly documented gaps that cannot yet be expressed through SwiftUsd. Those gaps should be candidates for moving down into SwiftUsd.

USDInterop Policy

USDInterop is transitional scaffolding, not the final SDK boundary.

• Do not grow USDInterop as the long-term productized runtime layer.
• Generic OpenUSD-safe operations currently in USDInterop should be classified and migrated:
  • runtime/binding primitives belong in SwiftUsd where possible;
  • pure Swift API contracts belong in SwiftUsdShell;
  • product workflow logic belongs in USDTools or another domain package.
• New work should avoid adding broad new public concepts to USDInterop unless needed to unblock an immediate migration or bug.
• Consumers must never be required to depend on USDInterop or USDInteropCxx for common workflows.

Problem

SwiftUsd already ships native OpenUSD libraries as binaries, but consumers still pay large compile-time and invalidation costs when they import the raw OpenUSD C++ API surface through Swift/C++ interop.

The cost leaks whenever public APIs expose imported C++ types such as:

• UsdStage
• UsdStageRefPtr
• UsdPrim
• UsdAttribute
• UsdShadeShader
• UsdShadeMaterial
• SdfPath
• TfToken
• VtValue
• Gf*
• OpenUSD.*
• pxrInternal_*

This prevents clean productization because downstream consumers must still understand the heavy C++ interop surface.

Non-Goals

• Do not hand-write a .usda parser.
• Do not replace SwiftUsd/OpenUSD.
• Do not expose raw OpenUSD escape hatches in public APIs.
• Do not make USDInterop the permanent SDK runtime layer.
• Do not attempt to complete every OpenUSD schema before proving the boundary.
• Do not binary-package the runtime before the public API is pure Swift.

Hard Rules

1. SwiftUsdShell must never import OpenUSD, SwiftUsd raw interop modules, USDInterop, USDInteropCxx, or any C++ interop target.
2. Public shell APIs must not mention raw SwiftUsd/OpenUSD types.
3. Runtime implementation should use SwiftUsd first. Direct OpenUSD use is allowed only as private implementation debt for missing SwiftUsd capabilities.
4. Any public API that exposes Usd*, Sdf*, Tf*, Vt*, Gf*, OpenUSD.*, or pxrInternal_* is a shelling failure unless the type is a pure Swift shell type.
5. Migration must be measurable by removing raw USD imports or C++ interop requirements from at least one downstream consumer.
6. USDInterop dependencies in first-party packages must be treated as migration debt, not final architecture.

Phase 0: Package Bootstrap

• Establish SwiftUsdShell as a standalone package.
• Add pure Swift core types:
  • USDStageHandle
  • USDPrimHandle
  • USDPath
  • USDToken
  • USDAssetPath
  • USDLoadPolicy
  • SwiftUsdShellError
• Add tests proving core types are Hashable, Sendable, and Codable where appropriate.
• Confirm SwiftUsdShell builds without Swift/C++ interop.

Exit criteria:

• SwiftUsdShell has zero OpenUSD imports.
• SwiftUsdShell has zero USDInterop or USDInteropCxx imports.
• SwiftUsdShell has zero .interoperabilityMode(.Cxx).
• A trivial consumer can import SwiftUsdShell without C++ interop.

Phase 1: Runtime Capability Inventory

Before creating a runtime target, inventory the real missing capabilities.

• List shell workflows that require runtime implementation:
  • open stage from URL
  • register/resolve stage handles
  • validate prim existence
  • inspect prim and attribute summaries
  • inspect material sources
  • author material values and texture connections
  • save/export edit layers
• For each runtime operation, decide the correct home:
  • SwiftUsd if it is a generic runtime/binding primitive;
  • SwiftUsdShell if it is a pure Swift API contract or DTO;
  • USDTools if it is domain workflow logic;
  • temporary USDInterop only when needed to bridge an existing gap.
• Avoid creating a parallel runtime target that simply duplicates USDInterop.

Exit criteria:

• Runtime gaps are explicitly classified.
• Any direct OpenUSD or USDInterop dependency has a documented migration target.

Phase 2: Mid-Weight Pilot In USDToolsMaterials

Use USDToolsMaterials as the first serious proof. It is large enough to be meaningful and small enough to complete.

Initial focus: read-only material inspection and detection, not mutation.

• Add SwiftUsdShell dependency to USDToolsMaterials.
• Add shell-facing APIs for:
  • detectShaderSystems(in: USDStageHandle)
  • detectOrigin(in: USDStageHandle)
  • detectMaterialOutputs(in: USDStageHandle, materialPath:)
  • detectMaterialMode(in: USDStageHandle, materialPath:)
  • editableMaterialContract(in: USDStageHandle, materialPath:)
  • inspectMaterialSources(in: USDStageHandle, materialPath:)
• Keep old raw APIs temporarily for compatibility.
• Make raw OpenUSD typealiases internal where possible.
• If immediate internalization breaks callers, deprecate public raw APIs and record blockers.
• Add tests around shell-facing material detection.

Exit criteria:

• USDToolsMaterials has a complete read-only material inspection API that does not expose raw USD types.
• At least one downstream consumer can call material inspection through shell handles.
• Remaining raw public APIs are documented as migration debt.

Phase 3: Migrate One Real Consumer

Use Preflight as the internal proving ground, but do not make this package Preflight-specific.

• Pick one consumer path, likely material inspection in PreflightUSDInterop.
• Replace raw UsdStageRefPtr material calls with shell handle calls.
• Confirm behavior remains equivalent.
• Check whether the migrated consumer can remove direct OpenUSD, USDInterop, or C++ interop dependency for that path.

Exit criteria:

• One real product path uses SwiftUsdShell APIs instead of raw SwiftUsd/OpenUSD APIs.
• The migration reveals concrete remaining raw USD dependencies instead of hiding them.

Phase 4: Expand Shell Core Types

Add pure Swift representations as needed by real APIs:

• USDValue
• numeric/vector/matrix values
• USDTimeCode
• USDAttributeSummary
• USDRelationshipSummary
• USDPrimSummary
• USDMaterialSummary
• USDConnection
• diagnostics and warnings

Exit criteria:

• Common read-only inspection results can be represented without VtValue, TfToken, or SdfPath leaking.

Phase 5: Material Mutation Shell

After read-only material inspection works, migrate material edits.

• Shell-facing semantic edit requests.
• Shell-facing prepared edit results.
• Shell-facing mutation results.
• Authoring APIs must not expose UsdShade*, Sdf*, Tf*, VtValue, or raw OpenUSD types.
• Generic authoring primitives needed by mutation should be proposed for SwiftUsd first, not permanently added to USDInterop.
• Existing USDInterop-backed mutation helpers are transitional and should have a migration path.

Exit criteria:

• Material inspection and material edit planning/mutation can be driven through pure Swift public APIs.
• Preflight can perform common material edits without importing raw OpenUSD or USDInterop in app/feature targets.
• Remaining USDInterop use is private, documented, and targeted for removal or movement into SwiftUsd.

Phase 6: Broader USDTools Shelling

Apply the pattern to other first-party packages in priority order:

1. USDToolsMaterials
2. USDToolsInspection
3. USDToolsTransformSupport
4. USDAnalysis
5. USDToolsSession
6. USDToolsSurgery
7. AppleUSDSchemasUSD

For each package:

• Inventory public raw USD signatures.
• Add shell equivalents.
• Migrate one consumer.
• Make raw APIs internal or deprecated.
• Record remaining USDInterop dependencies as migration debt.
• Add tests.

Exit criteria:

• First-party public APIs no longer require downstream consumers to import raw OpenUSD, USDInterop, or C++ interop targets for common workflows.

Phase 7: Code Generation

Once the manual shell shape is validated, introduce code generation.

Potential inputs:

• SwiftUsd symbols and APIs
• OpenUSD schema information, where needed
• Apple SwiftUsd-ast-answerer ideas
• symbol graphs where useful

Generate:

• pure Swift shell wrappers
• SwiftUsd-backed bridge methods where appropriate
• schema wrappers
• token sets
• enum/value mappings

Exit criteria:

• Repetitive schema/value wrapper work is generated, not hand-maintained.
• Generated public APIs remain pure Swift.

Phase 8: Binary Or Service Productization

Only after public APIs are pure Swift:

• Evaluate binary XCFramework runtime packaging.
• Evaluate XPC/helper service runtime packaging.
• Measure consumer build impact.
• Document local development override strategy.

Exit criteria:

• Consumers can use meaningful USD functionality without rebuilding/reimporting SwiftUsd in most app/feature targets.

Phase 9: External Consumer Proof With Bismuth

Use Bismuth as an external proof after internal shelling works.

• Create BismuthUSD optional module.
• Consume SwiftUsdShell APIs.
• Convert shell mesh/material output to Bismuth Entity, MeshResource, and material types.
• Avoid raw SwiftUsd/OpenUSD dependency in Bismuth core.

Exit criteria:

• Bismuth can import static USD scene data through shell APIs without taking a direct raw SwiftUsd/OpenUSD dependency in its core renderer/DSL.

Completion Definition

The whole SwiftUsd shelling effort is complete when:

• SwiftUsdShell is a standalone pure Swift package.
• SwiftUsd remains the preferred runtime binding layer over OpenUSD.
• Public shell APIs cover the main read/write workflows needed by first-party packages.
• First-party packages expose pure Swift APIs for common workflows.
• Raw SwiftUsd/OpenUSD and USDInterop types are no longer part of app-facing public APIs.
• At least one real app/feature consumer uses shell APIs without direct raw OpenUSD, USDInterop, or C++ interop imports.
• Build impact has been measured before and after.
• Binary or service packaging has been evaluated after the API boundary is clean.
• Bismuth or another external consumer can use the shell without becoming tied to raw SwiftUsd/OpenUSD.

Initial Implementation Note

The first concrete pilot should be USDToolsMaterials, specifically the read-only material inspection surface. This is intentionally more meaningful than a trivial stage-cache handle proof, but still smaller than shelling all of USDTools at once.

For mutation work, prefer adding missing generic runtime primitives to SwiftUsd, then representing them through SwiftUsdShell pure Swift contracts. Use USDInterop only as temporary compatibility scaffolding while migrating existing USDTools behavior.

[elkraneo]

SwiftUsdShell Boundary Audit - 2026-04-17

Branch: elkraneo/swiftusd-shell-issue-1

What changed in this pass

• Preflight material list mapping now opens a MaterialStageRegistry handle once per staged URL.
• USDClient+Live.mapMaterialInfo now calls shell-handle overloads:
  • ShaderDetector.editableMaterialContract(in:materialPath:registry:)
  • ShaderDetector.inspectMaterialSources(in:materialPath:registry:)
• The runtime/OpenUSD work remains inside PreflightUSDInterop.
• Preflight app load presentation was fixed so the workspace mounts after document preparation while viewport handoff continues.

Current boundary state

Expected interop-bearing modules:

• PreflightUSDInterop
• ViewportUSDPreparation

Current direct raw USD imports are confined to those modules:

• PreflightUSDInterop: OpenUSD, USDInterop, OpenUSD plugin runtime/artifacts.
• ViewportUSDPreparation: OpenUSD, USDInterop.

Current runtime installer imports:

• Preflight/PreflightRuntime.swift imports PreflightUSDInterop.
• GantryApp/GantryRuntime.swift imports PreflightUSDInterop.

No direct ViewportUSDPreparation imports were found in Preflight or Gantry app-facing sources.

C++ interop settings

Remaining .interoperabilityMode(.Cxx) targets:

• PreflightUSDInterop
• ViewportUSDPreparation
• ViewportModule
• RealityKitModule
• PreflightUI
• GantryApp
• PreflightApp

Do not remove these speculatively. PreflightUSDInterop and ViewportUSDPreparation genuinely need C++ interop. The app/UI target settings may be historical or due to downstream imported products, but removing them should wait for explicit compile validation.

No clean next read-only shell candidate found in Preflight

The remaining ShaderDetector calls in PreflightUSDInterop/USDSurgeryClient+Live.swift are semantic edit validation/preparation and mutation-adjacent. That belongs to the later material mutation shell phase, not this read-only material inspection pass.

Recommendation

• Keep ViewportUSDPreparation as a separate implementation target for now.
• Do not physically move it under PreflightUSDInterop unless there is a concrete build/package simplification to validate.
• Treat the current Preflight material inspection path as the real consumer proof for SwiftUsdShell issue Plan pure Swift shell over SwiftUsd/OpenUSD #1 Phase 3.

[elkraneo]

Phase 3 follow-up update - 2026-04-17

Preflight compile/run was validated by local app testing after the material-stage-handle changes. To reduce full-build churn, the next batch focused on package-level exposure instead of another tiny call-site refactor.

Changes in this batch

• Removed stale .interoperabilityMode(.Cxx) settings from app/UI targets that do not import or reference C++/OpenUSD symbols:
  • ViewportModule
  • RealityKitModule
  • PreflightUI
  • GantryApp
  • PreflightApp
• Kept C++ interop enabled only on the current implementation targets that directly import OpenUSD/USDInterop:
  • PreflightUSDInterop
  • ViewportUSDPreparation
• Kept runtime installation in PreflightUSDInterop and runtime bootstrap imports in the app runtime files.
• Confirmed app feature code still consumes PreflightUSDCore contracts for viewport reload preparation.

Static validation

• swift package dump-package succeeds after the manifest cleanup.
• git diff --check passes.
• rg shows raw OpenUSD / USDInterop imports remain confined to PreflightUSDInterop and ViewportUSDPreparation, plus runtime installer imports of PreflightUSDInterop.
• smith validate only reports the existing broad TCA missing-error-action heuristics in unrelated feature files.

No full build was run for this batch because Preflight full compilation is currently about 20 minutes; this change is intended to be validated with the next meaningful compile batch rather than a small-step build.

[elkraneo]

Correction: app/UI C++ interop settings must stay

Compile evidence disproved the package cleanup in ec2eb54e:

Module 'HydraStageView' was built with C++ interoperability enabled, but current compilation does not enable C++ interoperability

This is not a DerivedData/cache issue. It is Swift module compatibility: targets importing modules built with C++ interoperability must also enable C++ interoperability.

Restored .interoperabilityMode(.Cxx) for the consumer targets that import HydraStageView, RealityKitStageView, or StageViewOverlay:

• ViewportModule
• RealityKitModule
• PreflightUI
• GantryApp
• PreflightApp

The architectural boundary note is unchanged in the important sense: these targets do not directly import OpenUSD/USDInterop; they need C++ interop because of dependency ABI from stage-view products. Direct raw USD imports remain confined to PreflightUSDInterop and ViewportUSDPreparation.

Correction commit: e15ffa7d Restore Cxx interop for stage view consumers.

[elkraneo]

Phase 3 follow-up update from Preflight:

• Moved Preflight normal-map texture normalization to the USDTools API: USDAdvancedClient.normalizeNormalMapTexture(source:shaderPath:output:).
• Removed the duplicate Preflight-side raw USD implementation and local USDA override string writer from PreflightUSDInterop/USDSurgeryClient+Live.swift.
• Follow-up: batch fix mapping now forwards FixAction.normalizeNormalMapTexture to USDTools USDFixAction.normalizeNormalMapTexture, matching ValidationModule batchability.
• Commits in the Preflight workspace: 5de79f26 Delegate normal map normalization to USDTools, bdf1d51d Batch normal map normalization through USDTools.

This keeps the app-facing surgery client API stable while shifting another real material repair operation behind the USDTools/SwiftUsdShell-facing boundary. I did not trigger a full Preflight build for this pass; validation was limited to static reference checks and git diff --check to avoid another expensive SwiftUSD compile.

[elkraneo]

Phase 3 follow-up from Preflight retest on 2026-04-17:

• Retest confirmed the Preflight repair flow is functionally correct: Fix All applies the available repair and leaves the real missing-source-USDZ texture members as manual source-archive blockers.
• Remaining console noise was traced past Preflight's validation dependency scan. The source was USDTools session flatten/rebase export rewriting every missing relative image reference to @./source.usdz[...]@ whenever a source.usdz existed, without checking whether the member was actually present.
• For broken USDZ inputs, that manufactured package-member references for assets absent from the archive. OpenUSD later emitted assetLocalization.cpp failures and Ill-formed SdfPath warnings while inspecting the rebase layer.
• Added USDTools commit 33e540d Avoid missing USDZ package rewrites: session export now verifies the member exists in source.usdz before rewriting to package-member syntax. Missing members remain as authored unresolved relative paths, preserving the user-facing diagnosis without creating invalid rebase references.

Preflight workspace remains clean at fe2504be Avoid noisy USDZ dependency scan. USDTools has one unrelated pre-existing dirty file left untouched: Sources/USDToolsEditing/USDAdvancedEditing.swift.

[elkraneo]

Architecture clarification: shell vs product tools

The long-term model has two consumer levels, and the shell work should preserve that distinction.

Preflight / Gantry / internal apps / white-label products
        |
        v
USDTools
workflow APIs, validators, repairs, import/export flows, product DTOs
        |
        v
SwiftUsdShell / USDInterop
general Swift-native USD primitives and operations
        |
        v
SwiftUsd / OpenUSD
raw C++ interop

For open-source/general consumers such as renderer or engine libraries, the dependency should stop one layer lower:

Bismuth or other renderer/library consumers
        |
        v
SwiftUsdShell / USDInterop
canonical USD import, mesh/material/texture extraction, stage traversal
        |
        v
SwiftUsd / OpenUSD

So the migration should not treat USDTools as the final public replacement for USDInterop. Moving raw OpenUSD code from Preflight into USDTools is useful as an intermediate step because it removes app/feature interop leakage, but each extracted capability should be classified first:

• General USD primitive or reusable query -> SwiftUsdShell / USDInterop.
• Product policy or workflow orchestration -> USDTools.

General shell candidates include stage handles/lifetime, prim traversal, hierarchy summaries, safe attribute reads, typed USD values, mesh/material/texture extraction, asset path resolution, transforms, bounds, variants, and dependency summaries.

USDTools should own product/workflow policy: RealityKit compatibility validation, Preflight health scoring, fix planning, Reality Composer Pro preparation, texture conversion policy, session export, and packaging workflows.

Preferred end state: SwiftUsdShell is the public product/package identity for the general shell. USDInterop can remain as implementation plumbing or a compatibility bridge, but consumers should not need to choose between two conceptual public shells.

[elkraneo]

Phase 4 shell-core update - 2026-04-18

Added the first reusable pure Swift value/summary types directly to SwiftUsdShell rather than routing them through Preflight or USDTools:

• USDValue
• USDVector2, USDVector3, USDVector4
• USDMatrix4x4
• USDTimeCode
• USDAttributeSummary
• USDRelationshipSummary
• USDPrimSummary

This targets the general/open-source shell layer: safe attribute reads and prim summaries should be representable without exposing VtValue, TfToken, SdfPath, or other OpenUSD/C++ interop types to consumers.

Validation: swift test passes in the standalone SwiftUsdShell package. No Preflight build was run.

Commit: 99cb0e8 Add pure Swift USD value summaries in the local SwiftUsdShell repo.

[elkraneo]

Phase 4 integration update - 2026-04-18

Added the first OpenUSD-backed adapter that returns the new shell DTOs from USDTools inspection:

• USDAdvancedClient.primSummary(url:path:) -> SwiftUsdShell.USDPrimSummary?
• Converts prim path/name/type, authored attributes, and relationships into pure Swift shell types.
• Attribute values are currently conservative: raw VtValue payloads are represented as .unsupported(typeName:description:) until typed value conversion is implemented deliberately.

This keeps raw UsdPrim, UsdAttribute, UsdRelationship, SdfPath, and VtValue inside USDToolsInspection, while exposing a shell-facing summary API for consumers.

Validation:

• swift package dump-package passes in USDTools after adding the SwiftUsdShell dependency to USDToolsInspection.
• Preflight boundary guard passes.
• No full Preflight build was run.

Commit: d3db4ba Expose shell prim summaries from inspection in the local USDTools repo.

[elkraneo]

Phase 4 real consumer wiring - 2026-04-18

Preflight now exercises the new shell prim summary API in the selected-prim inspection path:

• USDClient.interopLive.getPrimAttributes calls USDAdvancedClient.primSummary(url:path:) first.
• USDClient.interopLive.getSelectedPrimInspection also uses primSummary for the basic selected-prim attributes shown by the inspector.
• Existing primAttributes remains as a fallback and metadata source for active/visibility/purpose/kind until those fields are shell-backed.
• PreflightUSDInterop now declares a direct SwiftUsdShell dependency in Package.swift instead of relying on transitive imports.

This makes the shell path real functionality rather than an unused adapter: selecting a prim in Preflight now validates the shell-facing inspection surface once the app is built/run.

Validation:

• swift package dump-package passes for PreflightPackage.
• Preflight USD boundary audit passes.
• No full Preflight build was run in this step.

Commit: ecec36e3 Use shell prim summaries for inspection in the Preflight workspace.

[elkraneo]

Phase 4 metadata follow-up - 2026-04-18

Extended the real selected-prim shell path so the shell summary owns more of the inspector metadata:

• SwiftUsdShell.USDPrimSummary now includes isActive, visibility, purpose, and kind.
• USDToolsInspection populates those fields from OpenUSD.
• Preflight inspector mapping now reads those fields from the shell summary first, with legacy primAttributes retained only as fallback/compatibility while the remaining path is migrated.

Commits:

• SwiftUsdShell: 6feaaa9 Add prim metadata to shell summaries
• USDTools: 210a6c6 Populate shell prim metadata
• Preflight: f1713b30 Read inspector metadata from shell summaries

Validation:

• swift test passes in SwiftUsdShell.
• swift package dump-package passes in USDTools and PreflightPackage.
• Preflight USD boundary audit passes.
• No full Preflight build was run for this follow-up.

[elkraneo]

Phase 4 checkpoint from Preflight branch elkraneo/merge-develop-stageview:

• Preflight is now pinned to USDTools 0.2.61.
• USDTools v0.2.60 added USDAdvancedClient.createPreviewSurfaceMaterial(...); Preflight now uses that instead of local raw OpenUSD preview-material creation.
• USDTools v0.2.61 added USDAdvancedClient.createVerbatimUSDZPackage(currentDirectory:inputs:outputURL:); Preflight still owns typed session/export policy, but no longer owns SdfZipFileWriter usage. This preserves authored layers/variants and does not flatten.
• Boundary scripts now guard shell-native inspection use: PreflightUSDInterop has shell inspection calls = 4, compatibility inspection calls = 0.
• Current low-level import audit remains PreflightUSDInterop: 3, all validation/runtime oriented: OpenUSD type aliases, attribute reader shim, and canonical OpenUSD validation registry execution.

Recommendation for the next chunk: do not pull OpenUSDValidationRegistryExecution apart piecemeal. It mixes registry execution, Preflight validation mapping, fix enrichment, and ownership classification. The better Phase 5-ish move is a deliberate URL-based USDTools validation API with neutral DTOs, then a thin Preflight mapper.

[elkraneo]

Phase 6 Complete — Broader USDTools Shelling

All 7 first-party packages now have pure Swift public APIs. Raw OpenUSD types (UsdStage, UsdPrim, etc.) no longer appear in any public API signature.

SwiftUsdShell changes (tag: 0.2.0)

• 28 new pure-Swift DTOs: material inspection/binding, transform chain (8 types), statistics/model info, RealityKit extension inventory (9 types)
• Added import simd for SIMD3 support

USDTools changes (tag: v0.2.64)

Package	What Changed
USDToolsInspection	14 new shell* methods on USDAdvancedClient (21 total): material enumeration, binding, transforms, statistics, RK extensions
USDToolsTransformSupport	3 shell methods wrapping transform inspection via Inspection
USDToolsMaterials	Shell edit readiness detection + bidirectional type converters (pre-existing)
USDAnalysis	Already pure Swift via USDAnalysisCore
USDToolsSession	Already pure Swift (1 struct, no raw USD)
USDToolsSurgery	Already pure Swift (URL/String API)
AppleUSDSchemasUSD	13 shellDefine/shellApply methods + SwiftUsdShell dependency

Name collision fix

Mirrored DTOs use identical names to legacy USDInterfaces/USDToolsCore types. The transitional interop layer qualifies legacy references with module prefix (USDInterfaces.XXX) while shell consumers use bare names. This resolves when legacy types are deprecated.

Preflight consumer

Preflight's PreflightUSDInterop layer qualified legacy type references for compatibility. No runtime behavior change.

[elkraneo]

Checkpoint: SwiftUsdShell boundary cleanup and first consumer proof completed.

Published tags/commits:

• SwiftUsdShell 0.3.0 (517a32f): pruned product/workflow material planning DTOs from the public shell API and removed RealityKit material graph cases from shell enums.
• USDTools v0.2.66 (392204c): moved material workflow/readiness concepts to USDTools, stopped re-exporting USDToolsMaterialsOpenUSD through the umbrella product, removed the USDAnalysis -> USDOperations -> USDInteropCxx dependency path, and raised the SwiftUsdShell floor to 0.3.0.
• Preflight preflight-v1.12.1-swiftusd-shell-pins (496ed1f2): migrated the app-facing USD interop paths to shell/USDTools APIs, removed direct old USDInterop/USDOperations/OpenUSDPluginUSDInterop dependencies from PreflightUSDInterop, and raised dependency floors to SwiftUsdShell 0.3.0 and USDTools 0.2.66.

Runtime check:

• Preflight compiled and ran locally after the cleanup.
• Extended log showed repeated successful USDAnalysis runs (analysis completed successfully, 94 nodes for the tested asset).
• No runtime log references to USDOperations, USDInteropCxx, OpenUSDPluginUSDInterop, duplicate symbols, dyld failures, or undefined symbols.

Architecture status:

• SwiftUsdShell is cleaner and remains pure Swift for this API surface.
• Product material planning/readiness logic now lives above the shell in USDTools.
• USDToolsMaterialsOpenUSD is no longer re-exported by the main USDTools product.
• The old duplicate-symbol bridge path through USDAnalysis -> USDOperations -> USDInteropCxx is removed.
• Preflight now proves a real downstream consumer path can use the shell/USDTools boundary without linking that old bridge path.

Remaining debt:

• USDInterfaces is still present for DTOs that were not deliberately migrated yet. Continue migrating only when the shell/product shape is equivalent or an explicit converter exists.
• Strongest-opinion provenance was intentionally not preserved through the old USDOperations dependency. Add a USDTools-owned provenance API over the new bridge/SwiftUsd path before reintroducing richer provenance observations.
• Some implementation targets still require C++ interop privately. Keep those private and continue moving generic runtime primitives toward SwiftUsd when practical.
• CI/release validation should run the constrained Preflight build/archive path rather than broad local swift build.

[elkraneo]

Follow-up release hardening checkpoint published as SwiftUsdShell 0.3.1 (a000543).

Changes:

• Expanded README into a public boundary document with rules, current surface, non-goals, and release checklist.
• Added shell-only tests for material inspection DTOs, binding DTOs, transform inspection DTOs, geometry/statistics DTOs, model info, material shell enum contents, and Sendable coverage for the main public contracts.
• Confirmed the SwiftUsdShell source imports only Foundation and simd; tests import only Foundation, simd, Testing, and SwiftUsdShell.
• Confirmed no product material workflow names (realityKitGraph, material edit policy/readiness/prepared edit/branch planning) appear in source or tests.

Validation:

• swift package dump-package
• git diff --check
• swift test passed with 12 Swift Testing tests.

This does not change API beyond docs/tests, so downstream floors at 0.3.0 remain valid. Use 0.3.1 as the preferred launch-readiness tag for new consumers.