feat: add asset, account, and Horizon diagnostics examples (#229-#232) - #262

Closes #229, closes #230, closes #231, closes #232.

Adds four runnable, read-only examples. Each one ships with helper-level tests, runner registration, a validation exclusion, and a README catalog entry.

Examples

169-asset-holder-distribution (ISSUE-169) — Pages every trustline Horizon reports for an issued asset and produces a holder-distribution report: total/average/median/largest balance, holders ranked by balance, and configurable top-N concentration. Authorized and unauthorized balances are tallied separately, zero-balance trustlines are counted apart so they don't distort circulation figures, and a mid-stream pagination failure is reported rather than letting a partial set look complete.

170-account-balance-liability-analysis (ISSUE-170) — Analyses balances, trustline limits, and buying/selling liabilities, deriving available amounts (balance - sellingLiabilities, minus the minimum reserve for native XLM) and limit headroom. Ledger-reported and derived values are kept visually separate throughout, so a computed figure is never mistaken for ledger state. Flags near-limit trustlines (a leading indicator of op_line_full) and unauthorized lines.

171-account-activity-profile (ISSUE-171) — Combines account metadata, transaction history, operation history, and payment history into one descriptive profile: success/failure counts, fee aggregation in stroops and XLM, operations grouped by type, incoming/outgoing payment split, and recent activity. The profile is assembled from four independent Horizon requests, so each records its own status and the report names which sections are incomplete — a failed request never turns into a silent zero that reads like an inactive account. Scope is explicitly descriptive: it does not score, rank, or classify accounts.

172-horizon-request-tracing (ISSUE-172) — A reusable tracing wrapper recording start/end time, duration, resource, HTTP status, success, and attempt count per request, aggregated into min/max/average/median latency. Supports a configurable timeout and slow-request threshold, tracks retries, and sanitizes diagnostics (Stellar secret seeds, JWTs, and token/secret/api_key/authorization query params) before logging — public keys are deliberately preserved so traces stay debuggable. The example traces several live resources plus a deliberate 404 and a deliberate network failure.

All four support --json (also OUTPUT_FORMAT=json) for machine-readable output, accept parameters through the interactive runner or environment variables, and perform no ledger mutations.

Incidental fix

The merge in #253 left three files syntactically broken, so npm run typecheck failed on main before this branch. This PR repairs them, since nothing builds otherwise:

• src/runner/catalog.ts — restored the missing closing brace on the 192-soroban-contract-code-inspection entry, and un-swapped the params blocks of entries 67 and 192, which the merge had crossed over (entry 67 had picked up 192's contract-hash prompts while its own ledger-range prompts were left orphaned mid-object). Original values recovered from the pre-merge history.
• src/validation/validation.config.json — restored the object boundary between the 192 and 66 exclusions; without it the file was not valid JSON.

Note: tests/soroban-contract-code-inspection.test.ts still fails on main (an unrelated pre-existing xdr.*.v0() typing issue from the same PR). Left alone as out of scope.

Verification

• All four examples run successfully against Horizon Testnet in both text and JSON mode.
• 103 new tests pass; full suite is 611 passing (was 508).
• No new typecheck or lint errors — the 36 remaining tsc errors are pre-existing and confined to unrelated examples referencing a missing stellar-sdk-v16 package.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VtubmgtuY97zQVrDu3PSKb