---
name: stamp-results
description: Use after a simready-benchmark run when you need an OEM-deliverable USD with embedded benchmark metadata. Stamps the run outcome into the mirror-copy USDs and merges a runtime_tests array into the per-asset validation.json. The original asset directory is never written to.
license: Apache-2.0
compatibility: Requires simready-benchmark (pip install simready-benchmark) and usd-core. Operates on a `_testing/` directory that has both a plan.json and per-test result.json files.
metadata:
  author: NVIDIA
  library: simready_benchmark
  version: "2026.05"
---

## Confirm the Installed Version

This skill ships inside the `simready-benchmark` wheel, so the copy installed with the framework matches the installed code. If you are working from a cached copy or from memory rather than the installed package, confirm the framework version with `simready-benchmark --version`, and treat `simready-benchmark --help` and `simready-benchmark --show-config` as the authoritative source for flags and configuration. A flag documented here might have changed in a different version.

## Stamping Happens Automatically by Default

A successful `simready-benchmark` run stamps as its final phase. No action needed.
The mirror-copy USDs at `_testing/results/<asset-dir>/<asset>.usd` carry the
new `runtime_testing` metadata; the original asset directory is untouched.

## Stamp Explicitly After a Run

```bash
simready-benchmark stamp --output-dir _testing
```

Reads `_testing/plan.json` plus the per-test result.json files at
`_testing/results/<asset-dir>/.simready/runtime/<test_name>/result.json`,
aggregates per-feature pass info per asset, and produces two per-asset artifacts:

1. **The mirror USD** at `_testing/results/<asset-dir>/<asset>.usd` gets
   `customLayerData.SimReady_Metadata.runtime_testing.tested_features.<ISO_TIMESTAMP>`
   written into its layer metadata.

2. **The validation JSON** at
   `_testing/results/<asset-dir>/.simready/validation.json` gets a
   `runtime_tests[]` array merged in, alongside any pre-existing SDK validation fields.

## Skip Stamping During a Run

```bash
simready-benchmark --project-config ... --no-stamp
```

Use this when iterating on tests and you do not want every run to mutate the
mirror USDs.

## What the USD Stamp Looks Like

```
customLayerData = {
    dictionary SimReady_Metadata = {
        dictionary runtime_testing = {
            dictionary tested_features = {
                dictionary "<ISO-timestamp>" = {
                    dictionary "<FEATURE_ID>" = {
                        bool   passed   = true
                        string version  = "1.0.0"
                        dictionary tests = {
                            dictionary "<test_script_path>" = { bool passed = true }
                        }
                    }
                }
            }
        }
    }
}
```

Re-stamping the same USD adds a **sibling** entry under `tested_features.<ISO>`;
older runs stay. The framework never deletes or rewrites prior timestamp
entries.

## What the validation.json Merge Looks Like

The framework rewrites the file's `runtime_tests` array on each stamp (read,
replace this one key, write atomically). Other top-level keys, including
`schema_version`, `asset_name`, `profile`, `passed`, `issues`, and any SDK
validator fields, are preserved verbatim.

```json
{
  "schema_version": "...",
  "profile": { /* SDK validator fields preserved as-is */ },
  "runtime_tests": [
    {
      "test_name": "ground_drop",
      "passed": true,
      "timestamp": "2026-05-22T10:15:30Z",
      "metrics": { /* per-test metric dict */ }
    }
  ]
}
```

## Per-Asset Failure Mode

If stamping fails for one asset (for example, a USD lock or a permission
error), the framework emits an `asset_stamp_failed` event but does not abort
the rest of the fleet. Subsequent runs can re-stamp the same asset.

## Key Rules

- Stamping NEVER writes to the original asset directory. Only the mirror copies under `_testing/results/<asset-dir>/`.
- USD-side stamps are keyed by ISO timestamp; re-stamping adds a sibling entry, never overwrites a prior one.
- The `runtime_tests` array in `validation.json` is REPLACED on each stamp (it represents "the current per-test record"). Other top-level keys in `validation.json` are preserved.
- `simready.test` owns the `runtime_testing` sub-tree (USD-side) and the `runtime_tests` array (JSON-side). It never reads or writes the SDK-owned `validation` sub-key or the top-level `profile` field.
- Prior stamper versions' opaque `customLayerData["simready_benchmark"]` key (legacy pre-D63) is preserved untouched.
- The `stamp` subcommand can be run multiple times against the same `_testing/`.
- Stamping reads the original asset and its sibling `validation.json` through the file-access layer, so a Nucleus (`omniverse://`) original requires `omni.client`, which ships with Kit and Isaac Sim and not the standalone wheel. Stamp Nucleus assets from inside Kit or Isaac Sim. The mirror copies the stamper writes are always local.

For the CLI flag set and the full schema definition, refer to [references/stamp-command.md](references/stamp-command.md).
