Snippet runtime correctness audit

[truthixify]

Labels: Stellar Wave, audit, test, docs, drips, help-wanted
Tier: M (2–4 days)
Type: audit + test

Context

Every MDX file in the docs has TypeScript snippets. We claim they're "copy-paste runnable." We have not verified that. Some snippets reference function signatures that have changed; some import paths are wrong; some never compiled in the first place.

We want a snippet-correctness CI gate.

Scope

1. Build scripts/check-snippets.ts that:
   • Walks every .mdx file under docs/.
   • Extracts every fenced code block tagged as ts, tsx, typescript, or javascript.
   • For each block, writes it to a temp file and runs tsc --noEmit against it with a tsconfig that has @wraith-protocol/sdk + chain deps installed.
   • Reports per-block compile errors.
2. Allow opt-out via a code-fence attribute: ```ts no-check for snippets that are intentionally illustrative pseudo-code.
3. Run it on every PR via GitHub Actions.
4. Run it once over the current state, fix every error found, and commit those fixes as a separate PR.

Bonus

• For Stellar snippets that include RPC calls, mock the RPC at the fetch layer and verify the code at least runs without throwing on response decode. This catches breakages where the SDK changed return shape.
• Add a separate "Stellar-only" variant that pings actual testnet (allowed to be flaky / non-blocking).

Acceptance criteria

• check-snippets.ts runs locally and in CI.
• Initial audit run produces zero errors (fix anything found).
• At least 5 Stellar snippets have their runtime behavior validated end-to-end against testnet (separate non-blocking job).
• Document the system in docs/CONTRIBUTING.md.

Why this matters

The docs are our most public artifact. A broken snippet in introduction.mdx affects every reader equally. Static type-checking is the cheapest, fastest way to catch this.