Timi16 · Timi16 · Jun 2, 2026 · Jun 1, 2026
diff --git a/Readme.md b/Readme.md
@@ -260,9 +260,11 @@ soroban-debug upgrade-check --old current.wasm --new upgraded.wasm
 ```
 
 The debugger runs parallel traces and classifies the upgrade:
-- **Safe:** No breaking changes, stable inputs execution.
-- **Caution:** Non-breaking changes like new map arguments or endpoints.
-- **Breaking:** Removed functions, changed signatures, or execution panic regressions.
+- **Safe:** The exported surface is unchanged, and sampled execution matches.
+- **Caution:** New exported functions were added without changing existing signatures.
+- **Breaking:** Functions were removed, signatures changed, or sampled execution diverged.
+
+See [docs/upgrade-classes.md](docs/upgrade-classes.md) for the full mapping between contract changes and upgrade classes.
 
 ### Completions Command
 

diff --git a/docs/cli-command-groups.md b/docs/cli-command-groups.md
@@ -18,7 +18,7 @@ Commands used for executing contract functions and interactive troubleshooting.
 Commands for static analysis, profiling, and version comparisons.
 
 - **`inspect`**: View contract metadata, exported functions, and DWARF source mappings without executing code.
-- **`upgrade-check`**: Compares two WASM files to identify breaking API changes or storage layout shifts.
+- **`upgrade-check`**: Compares two WASM files and reports upgrade classes based on exported function compatibility and optional execution diffs. See [Upgrade Classes](upgrade-classes.md) for the exact mapping.
 - **`optimize`**: Provides automated suggestions for reducing gas (CPU/memory) consumption.
 - **`profile`**: Identifies performance hotspots and budget-heavy instruction sequences.
 - **`compare`**: Renders a side-by-side diff of two execution traces to catch regressions.

diff --git a/docs/index.md b/docs/index.md
@@ -29,6 +29,7 @@ Welcome to the Soroban Debugger documentation. This index helps you navigate the
 ## 🎓 Tutorials
 - [Debugging Auth Errors](tutorials/debug-auth-errors.md) — Diagnosing `require_auth()` failures.
 - [Scenario Runner Cookbook](tutorials/scenario-runner.md) — Writing automated integration tests.
+- [Upgrade Review](tutorials/upgrade-review.md) — Interpreting `upgrade-check` output and upgrade classes.
 - [Plugin Development Tutorial](tutorials/plugin-development.md) — Build, install, and iterate on a plugin end-to-end.
 - [Symbolic Analysis Budgets](tutorials/symbolic-analysis-budgets.md) — Configuring symbolic exploration.
 - [Understanding Budget Trends](tutorials/understanding-budget.md) — Visualizing resource usage.

diff --git a/docs/issues/backlog-100-issues.md b/docs/issues/backlog-100-issues.md
@@ -83,7 +83,7 @@ Roadmap view: [Section C priorities](roadmap-priorities.md#section-c--feature-re
 - **I-031** `[DOC]` `docs/wasm-artifact-metadata.md` (1716 bytes) documents the metadata fields but doesn't show an example `inspect --format json` output that contains them.
 - **I-032** `[DOC]` `docs/watch-mode.md` (744 bytes) mentions the watch command but doesn't document the polling interval, file-glob support, or debounce behavior.
 - **I-033** `[DOC]` `docs/storage-snapshot.md` (1761 bytes) references `--import-storage` but the feature matrix shows this is `PARTIAL` in the extension (use `snapshotPath` instead) — the doc doesn't mention the distinction.
-- **I-034** `[DOC]` `docs/upgrade-classes.md` (1071 bytes) lists upgrade classes (Safe / Caution / Breaking) but doesn't explain what contract changes map to each class.
+- ~**I-034** `[DOC]` `docs/upgrade-classes.md` (1071 bytes) lists upgrade classes (Safe / Caution / Breaking) but doesn't explain what contract changes map to each class.~
 - **I-035** `[DOC]` `docs/batch-execution.md` references JSON format but doesn't document the full set of batch result fields (e.g., `duration_ms`, `error`) that appear in JSON output mode.
 - **I-036** `[DOC]` `docs/optimization-guide.md` (16 KB) is the longest doc in the set and has no internal TOC.
 - **I-037** `[DOC]` `docs/source-level-debugging.md` (3393 bytes) mentions DWARF but doesn't explain what happens when DWARF info is absent (heuristic fallback) — covered in the FAQ but not here.

diff --git a/docs/issues/roadmap-priorities.md b/docs/issues/roadmap-priorities.md
@@ -91,7 +91,7 @@ useful order instead of re-triaging the whole epic every time.
 | I-031 | Add `inspect --format json` example output to `wasm-artifact-metadata.md` | P2 | S | Docs | — | 2 |
 | I-032 | Expand `docs/watch-mode.md` with polling interval and debounce details | P2 | S | Docs | — | 2 |
 | I-033 | Clarify CLI vs. extension behavior in `docs/storage-snapshot.md` | P1 | S | Docs | — | 2 |
-| I-034 | Map contract change types to upgrade classes in `upgrade-classes.md` | P1 | M | Docs | — | 2 |
+| ~I-034~ | ~Map contract change types to upgrade classes in `upgrade-classes.md`~ | P1 | M | Docs | — | 2 |
 | I-035 | Document full batch result JSON fields in `docs/batch-execution.md` | P2 | S | Docs | — | 2 |
 | I-036 | Add internal TOC to `docs/optimization-guide.md` | P2 | XS | Docs | — | 2 |
 | I-037 | Add DWARF-absent heuristic fallback to `source-level-debugging.md` | P1 | S | Docs | — | 2 |

diff --git a/docs/tutorials/upgrade-review.md b/docs/tutorials/upgrade-review.md
@@ -16,7 +16,8 @@ soroban-debug upgrade-check --old old.wasm --new new.wasm
 ```
 
 ## Step 3: Interpret the results
-The tool classifies the upgrade into one of three categories:
-- **Safe:** No exported functions were removed, and signatures match.
-- **Caution:** Non-breaking additions (like new functions) were found.
-- **Breaking:** Functions were removed, or arguments changed in incompatible ways.
+The tool classifies the upgrade into one of three categories. For the full mapping between contract changes and classes, see [Upgrade Classes](../upgrade-classes.md).
+
+- **Safe:** The exported surface is unchanged, and any sampled `--test-inputs` executions match.
+- **Caution:** New exported functions were added, but existing signatures still match.
+- **Breaking:** Functions were removed, signatures changed, or a sampled execution produced a different result.
diff --git a/docs/upgrade-classes.md b/docs/upgrade-classes.md
@@ -1,15 +1,40 @@
 # Upgrade Compatibility Classes
 
-When using the `soroban-debug upgrade-check` command, the debugger runs deep analysis between the old and new WASM binaries. Instead of a binary valid/invalid report, it classifies the upgrade into three categories to help operators manage release risk.
+When you run `soroban-debug upgrade-check`, the debugger compares the old and new WASM binaries and classifies the result based on exported function compatibility and, when provided, test-input execution diffs.
 
-## 🟢 Safe
-- **Criteria:** No parameter signature changes, no removed functions, and identical behavior in test payloads.
-- **Risk:** Minimal. Can be executed without breaking downstream callers.
+The current analyzer uses a simple decision rule:
 
-## 🟡 Caution
-- **Criteria:** Contains only non-breaking changes, like new functions or increased storage mappings without altering existing contract invariants. 
-- **Risk:** Changes the surface area and expands interface footprint, so downstream indexers or dapps must be aware if they upgrade.
+- Any removed or signature-changed exported function is `Breaking`.
+- Any execution mismatch from `--test-inputs` is `Breaking`.
+- If there are no breaking changes but there is at least one added exported function, the result is `Caution`.
+- If the exported surface and sampled execution are unchanged, the result is `Safe`.
 
-## 🔴 Breaking
-- **Criteria:** Changing function parameters, dropping functions, return type mutation, or execution differences meaning outputs would wildly differ.
-- **Risk:** High. Calling systems will fail if they don't adapt immediately to the API surface change.
+## Safe
+Use `Safe` when the contract change is effectively identical from the debugger's point of view:
+
+- No exported functions were added.
+- No exported functions were removed.
+- No exported function signatures changed.
+- No sampled executions differed when `--test-inputs` was used.
+
+This means downstream callers can keep using the same contract interface without code changes.
+
+## Caution
+Use `Caution` when the upgrade is additive but still worth a review:
+
+- One or more exported functions were added.
+- Existing exported function names, parameter counts, parameter types, and return types stayed the same.
+- No sampled executions differed when `--test-inputs` was used.
+
+This class means the contract grew a new surface area, so callers and indexers may want to notice the new entry points even though the upgrade is still compatible.
+
+## Breaking
+Use `Breaking` when the upgrade changes how existing callers interact with the contract:
+
+- An exported function was removed.
+- An exported function's parameter count changed.
+- An exported function's parameter types changed.
+- An exported function's return types changed.
+- A sampled execution produced a different result with `--test-inputs`.
+
+This class means the old and new contract versions are not safely interchangeable without updating callers or reviewing the changed behavior.