feat(broker): add Alpaca paper order submit sandbox (#311)

Add a backend-only, multi-gated, PAPER-ONLY order submission sandbox. Blocked by
default; it submits a single paper order to Alpaca Paper ONLY when every explicit
gate is satisfied. Not live trading, not frontend UX, not autotrade.

Gates (all required): ALPACA_ENV=paper, ALPACA_PAPER_ORDER_SUBMIT_ENABLED=true,
ALPACA_PAPER_ORDER_SUBMIT_SANDBOX_ACK=I_UNDERSTAND_THIS_SUBMITS_A_PAPER_ORDER,
paper credentials present, request confirm_paper_order=true and
source="manual_sandbox", draft risk validation, and conservative size caps
(qty<=100, notional<=5000; market/limit only). Any failure -> no Alpaca call,
safe blocked response (HTTP 200), safety flags preserved.

- app/schemas/alpaca_paper_order_submit_sandbox.py — request/response
  (extra="forbid"); response locks paper_only=true, live_trading=false,
  live_orders_blocked=true, dry_run=true, read_only_posture_preserved=true,
  execution_enabled=false, requires_human_review=true; only redacted ids.
- app/services/alpaca_paper_order_submit_sandbox_service.py — gated service with
  an isolated paper-only client wrapper. Lazy SDK import only after gates;
  TradingClient(paper=True) only; single non-retried submit; raw order id
  redacted. Legacy live adapter (brokers/alpaca_adapter.py) NOT imported.
  Injected fake client supported for tests.
- app/api/routes/alpaca_paper.py — POST /api/alpaca-paper/order-submit-sandbox.
- tests/app/test_alpaca_paper_order_submit_sandbox.py — 36 tests (default
  blocked; every gate; validation reuse + caps; gated fake-client submit called
  once; redaction/no leak; dry-run-preview; raising client; no network; route
  POST-only/405; OpenAPI; allowlists do not exempt live paths).
- tests/app/test_safety_invariants.py & test_paper_sandbox_guardrails.py —
  narrow, path-specific allowlist registration with justification (additive).
- docs/tasks/alpaca_paper_order_submit_sandbox_001.md (incl. manual-smoke policy).

No live endpoint, no live credentials, no frontend trading controls, no secrets.
No manual real-paper smoke performed (requires separate explicit approval).
Global safety posture unchanged: autotrade=false, dry_run=true, read_only
preserved, live_orders_blocked=true, max risk <= 1%.

Co-authored-by: Melly <Melly-999@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: Melly-999

app/api/routes/alpaca_paper.py

@@ -29,6 +29,10 @@
     AlpacaPaperOrderDraftResponse,
 )
 from app.schemas.alpaca_paper_order_preview import AlpacaPaperOrderPreviewResponse
+from app.schemas.alpaca_paper_order_submit_sandbox import (
+    AlpacaPaperOrderSubmitSandboxRequest,
+    AlpacaPaperOrderSubmitSandboxResponse,
+)
 from app.schemas.alpaca_paper_readonly import AlpacaPaperPositionsPreview
 from app.services.alpaca_paper_demo import AlpacaPaperDemoService
 from app.services.alpaca_paper_order_draft_service import (
@@ -37,13 +41,19 @@
 from app.services.alpaca_paper_order_preview_service import (
     generate_alpaca_paper_order_preview,
 )
+from app.services.alpaca_paper_order_submit_sandbox_service import (
+    AlpacaPaperOrderSubmitSandboxService,
+)
 from app.services.alpaca_paper_readonly_adapter import AlpacaPaperReadOnlyAdapter
 
 router = APIRouter(tags=["alpaca-paper"])
 service = AlpacaPaperDemoService()
 # Default adapter: no injected client -> degraded_demo unless read-only is
 # explicitly enabled for a paper environment with credentials present.
 readonly_adapter = AlpacaPaperReadOnlyAdapter()
+# Default submit sandbox: no injected client -> blocked unless every explicit
+# paper-only gate is satisfied (env flags + ACK + credentials + confirmation).
+submit_sandbox_service = AlpacaPaperOrderSubmitSandboxService()
 
 
 @router.get("/alpaca-paper/status", response_model=AlpacaPaperStatus)
@@ -172,6 +182,45 @@ def post_alpaca_paper_order_draft(
     return build_alpaca_paper_order_draft(request)
 
 
+_SUBMIT_SANDBOX_DESCRIPTION = (
+    "ALPACA-PAPER-ORDER-SUBMIT-SANDBOX-001 — backend-only, multi-gated, "
+    "PAPER-ONLY order submission sandbox for local/manual testing. "
+    "\n\n"
+    "**Blocked by default.** A real Alpaca **Paper** submission is attempted ONLY "
+    "when every explicit gate is satisfied: ALPACA_ENV=paper, "
+    "ALPACA_PAPER_ORDER_SUBMIT_ENABLED=true, the acknowledgement env gate, "
+    "Alpaca paper credentials present, request confirm_paper_order=true, and "
+    "source='manual_sandbox' — plus the standard draft risk validation and "
+    "conservative sandbox size caps. If any gate fails, no Alpaca call is made "
+    "and a safe blocked response (HTTP 200) is returned. "
+    "\n\n"
+    "**This is NOT live trading.** No live endpoint, no autotrade, no frontend "
+    "control, no cancellation/replacement, no bracket/OCO. live_orders_blocked "
+    "and dry_run remain true; only a paper order may be submitted, and only a "
+    "redacted order id is returned (never a raw broker order id, account id, or "
+    "credential)."
+)
+
+
+@router.post(
+    "/alpaca-paper/order-submit-sandbox",
+    response_model=AlpacaPaperOrderSubmitSandboxResponse,
+    summary="Alpaca paper order submit SANDBOX — gated, paper-only, not live",
+    description=_SUBMIT_SANDBOX_DESCRIPTION,
+    operation_id="post_alpaca_paper_order_submit_sandbox",
+)
+def post_alpaca_paper_order_submit_sandbox(
+    request: AlpacaPaperOrderSubmitSandboxRequest,
+) -> AlpacaPaperOrderSubmitSandboxResponse:
+    """Attempt a gated, paper-only order submission for manual sandbox testing.
+
+    Blocked by default; submits to Alpaca Paper only when every gate is
+    satisfied. Never live trading, never frontend-triggered. Returns a safe
+    blocked response (HTTP 200) on any gate/validation failure.
+    """
+    return submit_sandbox_service.submit(request)
+
+
 @router.get(
     "/alpaca-paper/order-preview",
     response_model=AlpacaPaperOrderPreviewResponse,

app/schemas/alpaca_paper_order_submit_sandbox.py

@@ -0,0 +1,96 @@
+"""Alpaca Paper order SUBMIT SANDBOX schemas.
+
+ALPACA-PAPER-ORDER-SUBMIT-SANDBOX-001 — request/response models for the
+**backend-only, multi-gated, paper-only** order submission sandbox.
+
+This surface can submit a single small order to Alpaca **Paper** only when every
+explicit gate is satisfied. It is **not** live trading, **not** frontend UX, and
+**not** autotrading. It is blocked by default.
+
+Safety semantics encoded in the response:
+- ``paper_only=true``, ``live_trading=false``, ``live_orders_blocked=true``,
+  ``dry_run=true``, ``read_only_posture_preserved=true``,
+  ``execution_enabled=false`` (no *live* execution), ``requires_human_review=true``.
+- A submitted **paper** order does not change the global dry-run / live-orders
+  posture: paper submission is a separate, manually-gated sandbox path.
+- No ``account_id`` / raw ``broker_order_id`` / ``api_key`` / ``secret`` /
+  ``token`` is ever represented. Only a redacted order id is returned.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AlpacaPaperOrderSubmitSandboxRequest(BaseModel):
+    """Input for a gated paper order submission attempt.
+
+    ``side`` / ``order_type`` / ``time_in_force`` / ``source`` are plain strings
+    so invalid values are reported as a blocked response (HTTP 200) rather than a
+    parse error. Provide exactly one of ``quantity`` / ``notional``.
+    ``entry_price`` / ``stop_loss`` / ``take_profit`` are required (risk geometry
+    is validated even though only the entry order is submitted — no bracket/OCO).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    symbol: str = Field(min_length=1, max_length=32)
+    side: str = Field(description="BUY or SELL")
+    order_type: str = Field(default="market", description="market or limit")
+    time_in_force: str = Field(default="day", description="day/gtc/ioc/fok/opg/cls")
+    quantity: Optional[float] = Field(default=None)
+    notional: Optional[float] = Field(default=None)
+    limit_price: Optional[float] = Field(
+        default=None, description="Required only for order_type=limit"
+    )
+    entry_price: Optional[float] = Field(default=None, description="Reference price")
+    stop_loss: Optional[float] = Field(default=None)
+    take_profit: Optional[float] = Field(default=None)
+    max_risk_pct: float = Field(description="Per-trade risk; capped at 1.0")
+    confirm_paper_order: bool = Field(
+        default=False, description="Must be true to attempt a paper submission"
+    )
+    source: str = Field(
+        default="", description='Must be "manual_sandbox" to attempt submission'
+    )
+    client_order_id_prefix: Optional[str] = Field(
+        default=None, max_length=32, description="Optional safe prefix for our id"
+    )
+    dry_run_preview_only: bool = Field(
+        default=False,
+        description="If true, exercise all gates but never submit (no Alpaca call)",
+    )
+
+
+class AlpacaPaperOrderSubmitSandboxResponse(BaseModel):
+    """Result of a gated paper order submission attempt."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    accepted: bool
+    submitted_to_alpaca_paper: bool = False
+    blocked_reason: Optional[str] = None
+
+    # Safety posture — locked.
+    paper_only: Literal[True] = True
+    live_trading: Literal[False] = False
+    live_orders_blocked: Literal[True] = True
+    dry_run: Literal[True] = True
+    read_only_posture_preserved: Literal[True] = True
+    execution_enabled: Literal[False] = False
+    requires_human_review: Literal[True] = True
+
+    # Whether submission was actually enabled (all gates satisfied).
+    order_submission_enabled: bool = False
+
+    # Redacted identifiers only — never a raw broker order id / account id.
+    redacted_order_id: Optional[str] = None
+    client_order_id: Optional[str] = None
+    order_status: Optional[str] = None
+
+    message: str = (
+        "Paper sandbox only — blocked by default; submits to Alpaca Paper only "
+        "when every explicit gate is satisfied. Not live trading."
+    )