feat: strategy what-if simulation endpoint (#344)

[BernardOnuh]

Closes #344

Summary

Adds POST /api/v1/strategies/simulate (#344) — a dry-run what-if preview for a hypothetical strategy change before the user commits to it.

The endpoint resolves the caller's effective strategy config (follow → inline → own, risk ceiling tighten-only), then returns:

• immediate — what the agent would do right now on the caller's live positions (rebalance/hold/blocked) plus a trace that is shape-parity with the persisted DecisionTrace.
• historical — a non-compounding daily replay over retained ProtocolRate history, side-by-side with a counterfactual "held in the starting protocol" leg. Each rebalance subtracts the same estimateRebalanceCost the live agent uses.

All accrual math uses Prisma.Decimal (never a plain float).

Zero side effects

The endpoint is a pure read — it never writes an OutboxOp, AgentLog, Transaction, RebalanceDecision, User, PublishedStrategy, or Position row. Enforced structurally in the core (src/agent/simulate.ts has no stellar/db/event imports — verified by a source-reading test) and by acceptance tests at the DB-glue layer.

Deliberate decisions (callouts)

• Amount encoding: the historical/decision legs pass move amounts as value × 10^18 (the src/agent/backtest.ts convention) so the shared estimateRebalanceCost divides back to human units and yields realistic fees. We deliberately do not mirror the latent plain-integer encoding in src/agent/tools/actionTools.ts:265, which would drive network-fee percent toward ~1e15 and block every move. Documented in ASSUMPTIONS.md / STRATEGY_MARKETPLACE.md.
• No apply path: per scope, this is core-only (no confirmSimulationToken / PUT /api/v1/strategy apply step — that endpoint does not exist yet; strategy changes go through adjustStrategyTool).

Files

New

• src/agent/simulate.ts — pure simulation core
• src/strategy/simulation-service.ts — owner-scoped DB glue (reads only caller positions + public rates/risk scores)
• tests/unit/agent/simulate.test.ts (12 tests)
• tests/integration/strategies-simulate.integration.test.ts (7 tests)

Changed

• src/routes/strategies.ts, src/controllers/strategy-controller.ts — the route
• src/validators/strategy-validators.ts — strategySimulateSchema (180-day cap, follow/inline mutual exclusion)
• src/config/env.ts, src/middleware/rateLimiter.ts — simulateRateLimit (6 req/min)
• tests/integration/rateLimiter.integration.test.ts — mock block for the new limiter
• Docs: docs/openapi.yaml, docs/STRATEGY_MARKETPLACE.md, ASSUMPTIONS.md

Verification

• npm run typecheck ✅
• npm run lint ✅
• npm test ✅ (123 suites / 1665 tests pass)

Note: package-lock.json was left out of this PR — it only picked up a dev: true metadata tweak from a local npm install and is unrelated to the feature.

[drips-wave]

@BernardOnuh Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits