[snkmcb]

Implements the first slice of P2 in current priorities: Result<T>, the published diagnostic codes, the runtime_info schema, and open.

P0 (compose the vector capability) is blocked outside this repository — ghcr.io/animu-sphere/usd-vector-plugins is not published, so there is no OCI digest to pin — and P1 is sequenced after it, so this takes P2 instead.

Two lanes

Lane	Target	Needs OpenUSD	Provides
core	usdgeospatial::core	no	Result<T>, Diagnostic, runtime_info
usd	usdgeospatial::sdk	yes	open

The split is not cosmetic. Describing a runtime must not require loading it: an application that finds no runtime, or the wrong one, has to be able to say so. runtime_info therefore reads the materialized prefix's own metadata/composition.lock.json rather than asking OpenUSD, which also lets CI check the diagnostics, result, and introspection contracts on a runner with no composed runtime.

What open adds

It returns an ordinary pxr::UsdStageRefPtr — OpenUSD stays reachable below it. What it replaces is the null pointer plus loose TF_ERROR text, by naming each condition separately:

{
  "code": "UGEO-E031",
  "name": "capability_unavailable",
  "category": "asset",
  "subsystem": "sdk",
  "message": "this composition installs no file format for the extension",
  "details": {
    "uri": "boundaries.geojson",
    "extension": "geojson",
    "capability": "usd-fileformat:geojson"
  }
}

The capability detail uses the same name the manifest and the runtime metadata use, so a consumer can report exactly which capability a composition would have to add. GeoJSON is the honest example: it is P0, so this composition genuinely cannot open one, and the SDK's own test asserts that.

Codes are published in docs/reference/diagnostics.md. There is deliberately no generic unknown.

The runtime-info contract is held from both sides

• sdk/core/tests/test_core.cpp asserts the SDK produces exactly the committed sdk/core/tests/data/runtime-info.json.
• tests/tooling asserts that same document satisfies schemas/runtime-info.v1.json, agrees with the lock it was read from (including the target decomposition, via runtime_metadata.target_identity), and lists the same codes sdk/core/src/diagnostics.cpp defines.

Neither side can move alone. Drift detection was checked by mutation: a changed toolchain, host Python version, bundled flag, USD version, and a renamed or renumbered code all fail.

tools/sdk_env.py

ost runtime exec replaces the environment, which is what makes an acceptance result a claim about the composition alone. A native executable cannot use it: the composed OpenUSD links the host CPython (usd_python against python313.dll) and this composition deliberately bundles no interpreter, so such a process fails to load before it runs a line. tools/sdk_env.py prepends the same paths instead. ost runtime exec stays the runner for anything whose result is a claim about the runtime.

Verification

Run clean, from a fresh compose of the committed lock:

• core lane, no OpenUSD anywhere: 80 checks pass
• USD lane against the composed prefix: ctest 2/2, including opening fixtures/three-points.copc
• tests/native-consumer against the installed headers and exported CMake package: ctest 2/2
• python tools/validate_metadata.py: all checks pass; tests/tooling: 15/15

CI gains a sdk-core job. The OpenUSD lane needs a composed prefix and a matching toolchain, so it belongs with acceptance rather than with the per-commit checks.

Known limits

• inspect and formats are not implemented. formats first needs a decision on whether it reports composed capabilities, OpenUSD's registered extensions, or the intersection — those differ exactly when a plugin fails to load, which is when the answer matters most.
• The SDK was built and tested with MSVC 14.51, not the msvc143 its target names; no msvc143 toolset was available on the development machine. sdk/README.md states that building with the target's toolchain is the supported configuration.
• stage_open_failed and runtime_metadata_unreadable have no test that reaches them through a real malformed asset or an unreadable file. Both are recorded in the roadmap.

🤖 Generated with Claude Code