docs(dx): add unified error code catalog with CI validation

.github/workflows/ci.yml

@@ -95,6 +95,60 @@ jobs:
           components: rustfmt
 
       - run: cargo fmt --all --check
+      - name: Check Stellar error catalog
+        run: |
+          python3 - <<'PY'
+          from pathlib import Path
+          import re
+          import sys
+
+          root = Path('.')
+          doc = Path('ERRORS.md').read_text(encoding='utf-8')
+          missing = []
+
+          for path in sorted(root.glob('**/*.rs')):
+              parts = set(path.parts)
+              if {'bench', 'bench-crossover', 'fuzz', 'integration-tests'} & parts:
+                  continue
+
+              lines = path.read_text(encoding='utf-8').splitlines()
+              i = 0
+              while i < len(lines):
+                  if 'contracterror' not in lines[i]:
+                      i += 1
+                      continue
+
+                  j = i + 1
+                  while j < len(lines) and 'pub enum ' not in lines[j]:
+                      j += 1
+                  if j == len(lines):
+                      i += 1
+                      continue
+
+                  match = re.search(r'pub enum\s+([A-Za-z0-9_]+)', lines[j])
+                  if not match:
+                      i = j + 1
+                      continue
+                  enum_name = match.group(1)
+
+                  brace_depth = lines[j].count('{') - lines[j].count('}')
+                  k = j + 1
+                  while k < len(lines) and brace_depth > 0:
+                      line = lines[k]
+                      variant = re.match(r'\s*([A-Za-z][A-Za-z0-9_]*)\s*=\s*\d+\s*,', line)
+                      if variant:
+                          token = f'{enum_name}::{variant.group(1)}'
+                          if token not in doc:
+                              missing.append(f'{path}:{k + 1}: {token}')
+                      brace_depth += line.count('{') - line.count('}')
+                      k += 1
+                  i = k
+
+          if missing:
+              print('ERRORS.md is missing contracterror variants:')
+              print('\n'.join(missing))
+              sys.exit(1)
+          PY
       - run: cargo test --workspace
       - name: Run stellar resource benches
         run: |

stellar/README.md

@@ -15,6 +15,8 @@ This directory contains the Soroban smart contracts for the Wraith multichain st
 - `wraith-names`: Privacy-preserving name registry for `.wraith` names. [README](./wraith-names/README.md)
 - `contracts/governance`: Token-weighted governance (PoC, not production ready). [README](./contracts/governance/README.md)
 
+See [`ERRORS.md`](./ERRORS.md) for the Stellar contract error-code catalog and allocation policy.
+
 ## Prerequisites
 
 - [Rust](https://rustup.rs/) and `wasm32-unknown-unknown` target.

stellar/contracts/governance/README.md

@@ -295,3 +295,5 @@ Tests cover:
 - Timelock enforcement
 - Config retrieval
 - Double-init rejection
+
+Error codes are tracked in the [Stellar error catalog](../../ERRORS.md#governance).

stellar/stealth-announcer/README.md

@@ -83,3 +83,5 @@ Tests cover:
 - View tag bucket derivation from first metadata byte
 - Rejection of v1 scheme ID
 - Rejection of missing view tag (empty metadata)
+
+Error codes and panic-only coverage status are tracked in the [Stellar error catalog](../ERRORS.md#stealth-announcer).

stellar/stealth-batch-sender/README.md

@@ -112,3 +112,5 @@ Tests cover:
 - Positive amount validation
 - Non-empty ephemeral_pub_key validation
 - Metric event emission
+
+Error codes and panic-only coverage status are tracked in the [Stellar error catalog](../ERRORS.md#stealth-batch-sender).

stellar/stealth-registry/README.md

@@ -2,6 +2,8 @@
 
 The `stealth-registry` contract manages the storage and resolution of stealth meta-addresses (`spending_pubkey || viewing_pubkey`) on Soroban.
 
+Error codes are tracked in the [Stellar error catalog](../ERRORS.md#stealth-registry).
+
 ## Formal Verification with Kani
 
 Formal verification harnesses are located in `src/proofs/mod.rs` and can be verified using [Kani](https://model-checking.github.io/kani/).

stellar/stealth-sender/README.md

@@ -7,6 +7,8 @@ stealth address and emits one announcement; `batch_send` does the same for a
 variable-length batch of parallel vectors (`stealth_addresses`,
 `ephemeral_pub_keys`, `metadatas`, `amounts`), rejecting mismatched lengths.
 
+Error codes are tracked in the [Stellar error catalog](../ERRORS.md#stealth-sender).
+
 ```bash
 cargo test          # unit tests (from stellar/)
 ```

stellar/stealth-splitter/README.md

@@ -2,10 +2,12 @@
 
 ## 🎯 Assignment Completed
 
-**Issue #15: 1-to-N Stealth Payment Splitter on Stellar**
-**Tier: L (1–2 weeks)** | **Type: Feature** | **Status: ✅ COMPLETE**
-
----
+**Issue #15: 1-to-N Stealth Payment Splitter on Stellar**
+**Tier: L (1–2 weeks)** | **Type: Feature** | **Status: ✅ COMPLETE**
+
+Error codes are tracked in the [Stellar error catalog](../ERRORS.md#stealth-splitter).
+
+---
 
 ## 📦 What Was Delivered
 
@@ -426,4 +428,4 @@ This enables:
 **Developer Notes:** Assignment completed with a focus on immutability, atomicity, privacy, and comprehensive documentation.
 // new feature work
 // new feature work
-
+

stellar/stealth-vault/README.md

@@ -261,3 +261,5 @@ The proofs live in `src/proofs/mod.rs` and run against the real `claim` /
 `refund` / `refund_permissionless` bodies, compiled against `src/mock_sdk.rs` in
 place of `soroban-sdk`. See [AUDIT_SUMMARY.md](./AUDIT_SUMMARY.md) for what the
 model assumes.
+
+Error codes are tracked in the [Stellar error catalog](../ERRORS.md#stealth-vault).

stellar/wraith-asset-policy/README.md

@@ -133,3 +133,5 @@ Tests cover:
 - Policy allowlist flow (add, check, remove)
 - Initialize with default assets
 - Double initialization rejection
+
+Error codes and panic-only coverage status are tracked in the [Stellar error catalog](../ERRORS.md#wraith-asset-policy).

stellar/wraith-names/README.md

@@ -2,6 +2,8 @@
 
 Soroban contract mapping `.wraith` names to 64-byte stealth meta-addresses.
 
+Error codes are tracked in the [Stellar error catalog](../ERRORS.md#wraith-names), including the [auction subsystem](../ERRORS.md#wraith-names-auctions).
+
 Core features:
 
 - **Register / update / release** — names are 3-32 chars, lowercase