Gate 12 specification — Paper Trading Workspace and confirmed reconciliation

[tonywxx]

Scope

This specification defines the first current-head implementation slice of Gate 12 (#156): a Paper Trading Workspace for one User and one OKX Demo account. It does not implement the Gate Parent.

Current-head facts

• The Host already persists and exposes account snapshots, reservations, buying power, positions, Orders, Fills, reconciliation state, and provider evidence through the Paper Account view and reconciliation commands.
• No React route invokes the Paper Account commands today; the prior acceptance guide requires command invocation rather than a product workspace.
• Existing direct order commands are not a V1 Paper Trading Workspace authority: they are not tied to a Running Bot lifecycle.

Decisions

• Canonical name: Paper Trading Workspace. Route: /paper-trading. It is a dedicated Operations-module entry and does not replace /operations, which remains the Operations Dashboard.
• On entry, immediately render locally available Paper account evidence and visible freshness. Do not automatically contact OKX. Empty, loading, degraded, disconnected, Reconciliation Required, uncertain, and restart states must be explicit and must not block navigation.
• Reconcile is the sole active control. It needs clear confirmation and control-scoped loading, then refreshes the retained local evidence.
• Direct order submission, cancellation, and synchronization are not reachable from this Workspace. Pause, block, retry, Bot lifecycle, immutable deployment Bundles, Sidecars, and first Running Attempt remain later Gate 12 work.
• Account, reservation, buying-power, position, Order, Fill, provider, reconciliation, and retained Risk Decision evidence must be inspectable. Where no Risk Decision exists, the Workspace must say so rather than infer one.
• All strings are localized. This Gate runs en-US Desktop acceptance now; zh-CN is explicitly deferred to the V1-completion complete-workflow rerun.

Acceptance criteria

• An authenticated User can reach /paper-trading from the Operations navigation and inspect retained, user-scoped OKX Demo evidence without exposing credentials.
• Freshness and every declared account/evidence state are visible. Absence of a configured connection or retained account is an actionable empty state, not a crash.
• A confirmed Reconcile invokes the Host only after User action, shows loading only in that control, surfaces a typed failure without discarding the prior view, and refreshes on success.
• The route contains no direct order-entry, cancel, sync, Pause, Block, Retry, or Bot-lifecycle control. It does not change the Operations Dashboard.
• Focused frontend and Host checks plus an en-US Desktop product run demonstrate the route, confirmation, fail-closed recovery state, and OKX Demo-only boundary.

Out of scope

Live Trading; Alpaca or other provider expansion; direct manual order authority; Bot deployment or control; Worker Sidecars; cross-account aggregation; Operations Dashboard changes; and zh-CN Gate acceptance before the V1-completion rerun.

Ticketing

Existing child #139 is the single implementation target. Its historical wording is replaced with this current-head contract and it becomes ready-for-agent.

[tonywxx]

Closure audit at current main HEAD 727ee6a: the current-head Paper Trading Workspace and confirmed reconciliation specification has been delivered by implementation child #139, which is CLOSED with its implementation and verification evidence. Gate Parent #156 is accepted and CLOSED. This issue remains the specification record; no implementation work remains here. Gate 13 is tracked separately by #193 and #194 under #157.