feat(broker): add Alpaca paper read-only adapter

[Melly-999]

⚠️ Runtime/backend code PR — first backend code step toward Alpaca Paper integration. Strictly GET-only / read-only: no order placement, no execution, no live broker, no committed credentials.

Scope

Backend read-only adapter + GET route + tests + task doc. No frontend, scripts, workflows, package, Docker/Tauri, cloud config, or env files.

• Baseline SHA: 99ff2f11971f5de214d7547f2ea89e465cae573e
• Commit SHA: bf9a01cbf889367dc462073f74d3d47bb5b8e1aa

Files changed

• app/api/routes/alpaca_paper.py (1 new GET route)
• app/schemas/alpaca_paper_readonly.py (new)
• app/services/alpaca_paper_readonly_adapter.py (new)
• tests/app/test_alpaca_paper_readonly_adapter.py (new)
• docs/tasks/alpaca_paper_readonly_adapter_001.md (new)

Implementation summary

• AlpacaPaperReadOnlyAdapter — optional injected client + env_reader. Resolves a client only when explicitly enabled (ALPACA_PAPER_READONLY_ENABLED=true + ALPACA_ENV=paper + credentials present) or when a client is injected; otherwise a safe degraded fallback. The default client factory lazy-imports the Alpaca SDK with paper=True (paper endpoint only) and degrades on any error. Only the read-only get_all_positions is referenced.
• GET /api/alpaca-paper/positions-preview — sanitized positions preview (no mutating routes added).
• Degraded fallback — no creds / not enabled / unsafe ALPACA_ENV / client error → mode=degraded_demo, connected=false, source=fallback, empty positions; never raises.
• Injected fake client support — treated as a trusted read-only client for tests (no env, no network).
• Sanitization/redaction — positions reduced to symbol/qty/market_value/unrealized_pl/side; schema extra="forbid" drops broker-internal fields; credentials never stored, logged, or returned.

Read-only boundary

GET-only · no POST/PUT/PATCH/DELETE · no order placement/cancellation/replacement · no live broker endpoint (paper=True only) · no credential UI · no secrets · no frontend trading controls.

Forbidden output fields confirmed absent: account_id, broker_account_id, broker_order_id, execution_id, api_key, secret, token.

Tests / validation summary

• New adapter tests: 13 passed (degraded default; injected-client sanitization; no forbidden-field leakage even when raw objects carry account_id/asset_id; raising client degrades; malformed positions skip/degrade; unsafe ALPACA_ENV=live and disabled config resolve no client; route GET 200 + safety flags; route no forbidden keys; POST/PUT/PATCH/DELETE → 405; OpenAPI GET-only). No real creds, no network.
• Full run (new + demo + order-preview + openapi-forbidden-paths + safety suites): 183 passed.
• python scripts/validate_safety_config.py → OVERALL: PASS.
• black --check, flake8, mypy (new files) → all clean. git diff --check → clean.

Static scan summary

No secrets / token-shaped strings / DB URLs / API keys / broker credentials / account IDs / emails / phones / Neon identifiers. No safety-flip values. No place_order/submit_order/execute_order/cancel_order/replace_order/MarketOrderRequest/OrderSide in new code — matches exist only in the task doc's prohibition/denylist text. Legacy brokers/alpaca_adapter.py left untouched.

Out of scope

• Paper order submission
• Paper order cancellation
• Order replacement
• Live broker connection
• Live credentials
• Frontend trading controls (Buy/Sell/Order/Execute)

Safety confirmation

• backend read-only only ✅
• no frontend changes ✅
• no scripts / workflows / package / env changes ✅
• no broker credentials / no real secrets ✅
• no order/execution routes ✅
• no Buy/Sell/Order/Execute UI ✅
• no live trading ✅
• no profit/ROI/win-rate claims ✅
• no financial-advice claims ✅
• safety posture unchanged (autotrade=false, dry_run=true, read_only=true, live_orders_blocked=true, max risk <= 1%) ✅

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @Melly-999, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery