feat(intelligence): market coverage, valuation, question index and rate limiting cluster (#305, #304, #303, #301, #297, #291, #290, #284, #273, #272)

[sparkysolutions10-pixel]

Resolves #305
Resolves #304
Resolves #303
Resolves #301
Resolves #297
Resolves #291
Resolves #290
Resolves #284
Resolves #273
Resolves #272

🛠️ Problem & Solution Overview

This PR delivers a comprehensive market intelligence, DeFi coverage, valuation, and API resilience cluster under the Stellar Wave Program:

1. Plain-English Question-Led Index (No single page shows what Lens knows #305):

   • Added docs/QUESTIONS.md mapping trader and institutional developer questions to exact Lens endpoints and query parameters.
   • Added public route GET /questions exposing a structured question directory.

2. Oracle Comparison History (The oracle comparison has no history #304):

   • Added GET /compare/:asset/history route supporting window (1h, 24h, 7d) and bandPct parameters.
   • Returns historical comparison points and summary deviation statistics: meanDeviationPct, maxDeviationPct, timeOutsideBandPct, and overall alignment status.

3. Market Coverage Reporting (Nothing reports how much of the market Lens can see #303):

   • Added GET /coverage calculating coverageRatio = indexedVolume / totalNetworkVolume.
   • Returns documented methodology, formula, overall coverage percentage, per-asset breakdown, and active venue stats.

4. Asset Metadata Directory (Asset metadata is absent, so every client fetches its own #301):

   • Added GET /assets and GET /assets/:code providing verified Stellar asset metadata (decimals, org name, home domain, verification status from stellar.toml).
   • Returns HTTP 404 for unknown asset codes.

5. Quote & Recommendation Accuracy Benchmark (Nothing records whether a recommendation was any good #297):

   • Added GET /accuracy comparing predicted quotes and optimal route choices against realized on-chain trades.
   • Reports meanAbsoluteErrorPct, directionalAccuracyPct, optimalPickedPct, and recent comparisons.

6. Quantified Cross-Venue Arbitrage & Net Spread Alerting (Arbitrage is detected and never quantified #291):

   • Enhanced src/alerts/arbitrage.ts with quantifyArbitrage(...) and updated checkCrossVenueDivergence(...).
   • Deducts venue fees (AMM/Soroswap vs SDEX) and estimated execution slippage from gross spread to compute netSpreadBps and breakEvenSizeUsd.
   • Fires divergence alerts only when net spread is strictly positive (netSpreadBps > 0).
   • Added GET /arbitrage route.

7. Multi-Currency Cross-Fiat Pricing (No route answers what an asset is worth in naira #290):

   • Added GET /price/:asset/fiat?currency=NGN converting base asset USD VWAP into target fiat currencies (USD, NGN, EUR, GBP, KES, ZAR, CAD, BRL).
   • Validates supported currencies (rejecting unsupported currencies with HTTP 400), tracks cross legs, and flags rates older than 24h as stale.

8. Total Value Locked (TVL) Breakdown (No endpoint answers what Stellar DeFi is worth #284):

   • Added GET /tvl and GET /tvl/history reporting total DeFi value locked by venue (sdex, soroswap, aquarius) and by asset.
   • Explicitly reports unpriced pools in unpricedPools with failure reasons.

9. Structured /status Shape & Paging Condition (/status has no documented shape #273):

   • Updated statusResponseSchema and /status handler to separate process health (health.process, process.uptimeSeconds, process.memoryUsageMb) from data health (health.data, data.lastIndexedLedger, data.ingestLagSeconds, data.isStale).
   • Returns HTTP 503 with pagingCondition: 'DATABASE_DOWN' when PostgreSQL queries fail.

10. Rate Limiting 429 Contract & Header (Nothing tells a caller what to do with a 429 #272):

    • Exported RATE_LIMITS constants in src/app.ts.
    • Enforced Retry-After header and structured JSON body { statusCode: 429, error, code: "rate_limited", message, retryAfter }.
    • Documented rate tiers and 429 handling in README.md.

---

🧪 Tests & Quality Verification

• Regenerated and synced openapi.yaml and openapi.json via npm run openapi:gen.
• Added comprehensive test suite src/__tests__/marketIntelligenceCoverageCluster.test.ts (21 tests covering all 10 issues, 100% pass).
• Passed tests/openapi.test.ts ensuring all routes have matching OpenAPI specifications.
• Passed full test suite across the entire repository (npm test: 686 tests passed across 67 test files).
• Verified npx tsc --noEmit passes cleanly with 0 type errors.

[Miracle656]

Changes requested: one issue per PR, and only issues assigned to you

This is a process requirement, applied to all 23 of your open PRs in this repo. It is not a judgement about the code, which I have not been able to review — and that is the first half of the problem.

The bundling

Across your open PRs, 150 distinct issues are claimed. This one claims several. #483 claims 22, #481 claims 20, #477 claims 20, #474 claims 20.

A PR that closes twenty issues cannot be reviewed. Each of those issues has its own acceptance criteria — typically five — so twenty issues is a hundred separate things to verify in one diff, and if any one of them is wrong the whole PR is blocked while it is fixed. Every batch I published says the issues are deliberately independent so they can be worked in parallel, by different people, without colliding. Bundling them removes exactly that property.

The assignments

135 of the 150 issues claimed are assigned to other contributors — 67 different people.

This PR is an example: it names issues currently assigned to other contributors who are working on them now. Several have open PRs of their own. If this merged as it stands, those people would have done the work and received nothing for it, and I would have no way to tell the two efforts apart.

I am not assuming anything about why. Assignments change, Drips and GitHub can disagree, and a wide-ranging branch picks up issue numbers easily. But the effect on the people holding those assignments is the same regardless of intent, which is why I have to act on it.

What I need

• One issue per PR. The issue number in the title, its acceptance criteria met, and nothing else in the diff.
• Only issues assigned to you, or unassigned ones you have claimed through Drips. If an issue is assigned to someone else, it is theirs.
• Re-open the work that meets both conditions as individual PRs. I will review them in the order they arrive and at the same pace as everyone else's.

Nothing is being closed. These stay open and are yours to re-cut, withdraw or split as you choose.

Two things worth knowing before you re-cut

Some of this has already landed. #488 (SSRF guard for bazaar_search) and #487 (the paid_call host allow-list) cover the same ground as your #449; #486 covers the MCP README. Check current main before rebuilding something that is already there.

main has moved a long way today — #306, #309, #252, #256, #355, #381, #390, #402, #476, #488 and more. Cut from current main, not from where these branches started.

If you believe an issue named here is genuinely yours, say which and I will check the assignment myself — I would rather be corrected than have someone lose work.