Refine runtime target compatibility and validation

Author: Pigbibi

docs/deployment_model.md

@@ -4,7 +4,7 @@
 
 - `QuantPlatformKit` remains the shared platform package and is **not deployed as a runtime service**.
 - The current runtime repositories (`InteractiveBrokersPlatform`, `CharlesSchwabPlatform`, `LongBridgePlatform`, `BinancePlatform`) are the **transitional deployment units**.
-- The **target state** is one deployment repository per broker platform, with strategy behavior selected by configuration such as `STRATEGY_PROFILE`.
+- The **target state** is one deployment repository per broker platform, with strategy behavior selected through `RuntimeTarget` / `RUNTIME_TARGET_JSON` and compatibility selectors such as `STRATEGY_PROFILE`.
 - Strategy or platform repositories should always depend on a fixed `QuantPlatformKit` Git tag instead of `main`.
 
 For the live runtime inventory across repositories, projects, services, schedulers, runtime identities, and current secret names, see [`platform_runtime_inventory.md`](./platform_runtime_inventory.md).
@@ -13,6 +13,8 @@ For a cleaner split between shared package code, platform runtime repositories,
 
 For the platform / strategy-domain / configurable-profile matrix, see [`platform_strategy_matrix.md`](./platform_strategy_matrix.md).
 
+For the runtime-target-first control-plane design, see [`runtime_target_architecture.md`](./runtime_target_architecture.md).
+
 ## Current state vs target state
 
 ### Current transitional state
@@ -149,10 +151,12 @@ Within one broker platform repository, selecting a strategy by configuration is
 
 Recommended selector:
 
-- `STRATEGY_PROFILE`
+- `RUNTIME_TARGET_JSON` for structured runtime identity
+- `STRATEGY_PROFILE` for compatibility with existing strategy routing
 
 Good examples:
 
+- `RUNTIME_TARGET_JSON={"platform_id":"longbridge",...}`
 - `STRATEGY_PROFILE=rotation`
 - `STRATEGY_PROFILE=income`
 - `STRATEGY_PROFILE=hybrid`
@@ -171,6 +175,7 @@ IBKR should support multiple accounts or account groups under one platform repos
 
 Recommended configuration boundary:
 
+- `RUNTIME_TARGET_JSON`
 - `STRATEGY_PROFILE`
 - `ACCOUNT_GROUP` or `IB_ACCOUNT_SET`
 - `IB_CLIENT_ID` or a deterministic `IB_CLIENT_ID_BASE`
@@ -196,6 +201,7 @@ LongBridge should keep:
 
 The split should always be defined by runtime configuration:
 
+- `RUNTIME_TARGET_JSON`
 - `ACCOUNT_REGION=HK|SG`
 - `ACCOUNT_PREFIX`
 - `SERVICE_NAME`
@@ -213,7 +219,8 @@ Charles Schwab can stay simpler:
 
 - one platform repository
 - one or more services only when strategy profiles truly differ
-- `STRATEGY_PROFILE` is already part of the current runtime shape
+- `RUNTIME_TARGET_JSON` is part of the current runtime shape
+- `STRATEGY_PROFILE` remains the compatibility selector
 
 ### Binance
 
@@ -230,7 +237,7 @@ If you rename a repository or move it under a different owner, Cloud Build and C
 Recommended migration order:
 
 1. align every runtime repository to the same `QuantPlatformKit` tag
-2. finish the platform runtime configuration shape (`STRATEGY_PROFILE`, `ACCOUNT_GROUP`, `ACCOUNT_REGION`, `SERVICE_NAME`)
+2. finish the platform runtime configuration shape (`RUNTIME_TARGET_JSON`, `STRATEGY_PROFILE`, `ACCOUNT_GROUP`, `ACCOUNT_REGION`, `SERVICE_NAME`)
 3. create or update the new trigger against the target repository
 4. confirm the branch is still `main`
 5. confirm the target service and region
@@ -262,6 +269,6 @@ Rename affects:
 
 - platform code lives in `QuantPlatformKit`
 - one broker platform should map to one deployable runtime repository
-- strategy selection can happen inside one broker platform via config like `STRATEGY_PROFILE`
+- strategy selection can happen inside one broker platform via config like `RUNTIME_TARGET_JSON` and `STRATEGY_PROFILE`
 - LongBridge HK/SG and IBKR multi-account should be modeled as service or trigger splits, not broker-mixing logic
 - versions are managed with fixed tags

docs/platform_repo_boundaries.md

@@ -14,6 +14,8 @@ The codebase is in a transitional state, so this document is meant to answer a s
 
 For the platform / strategy-domain / configurable-profile matrix, see [`platform_strategy_matrix.md`](./platform_strategy_matrix.md).
 
+For the runtime-target-first architecture and the Bridge / Adapter split, see [`runtime_target_architecture.md`](./runtime_target_architecture.md).
+
 ## 1. `QuantPlatformKit`
 
 `QuantPlatformKit` is the shared dependency.
@@ -28,6 +30,7 @@ It should own:
   - strategy domain
   - strategy profile definition
   - platform compatibility rules
+  - `RuntimeTarget` / `RuntimeAssembly` bridge objects
 
 It should **not** own:
 
@@ -75,7 +78,9 @@ When a runtime already has a controlled cutover window, prefer removing the old
 flat callable entrypoint entirely instead of carrying both shapes in parallel.
 Keeping `runtime/config` and legacy one-off call signatures alive at the same
 time usually leaks compatibility branches back into execution and notification
-code.
+code. The shared `RuntimeTarget` / `RuntimeAssembly` bridge exists so
+entrypoints can stay thin while runtime identity still flows through logs,
+reports, and deployment metadata.
 
 When a dependency already matches a shared interface, entrypoints should adapt
 it to the shared port first, for example:

docs/platform_runtime_inventory.md

@@ -16,20 +16,21 @@ For the platform / strategy-domain / configurable-profile matrix, see [`platform
 - GitHub Variables remain the control plane for:
   - service names
   - regions
-  - strategy selectors such as `STRATEGY_PROFILE`
+  - structured runtime selectors such as `RUNTIME_TARGET_JSON`
+  - compatibility strategy selectors such as `STRATEGY_PROFILE`
   - secret selector variables such as `*_SECRET_NAME`
 - Secret Manager is the runtime source of truth for sensitive values that Cloud Run services actually consume.
 - The US equity Cloud Run env-sync workflows use GitHub OIDC + Workload Identity Federation. `GCP_SA_KEY` is not required for those workflows.
 - GitHub Secrets can remain as temporary runtime fallbacks where migration is not fully finished.
 
 ## Runtime inventory
 
-| Platform | Repo | Strategy domain | Strategy selector | Runtime model | Project / backend | Runtime unit |
-|---|---|---:|---|---|---|---|
-| IBKR | `QuantStrategyLab/InteractiveBrokersPlatform` | `us_equity` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` | Cloud Run | configurable |
-| Schwab | `QuantStrategyLab/CharlesSchwabPlatform` | `us_equity` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` | Cloud Run | `charlesschwabquant` | `charles-schwab-quant-service` |
-| LongBridge | `QuantStrategyLab/LongBridgePlatform` | `us_equity` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` | Cloud Run | configurable |
-| Binance | `QuantStrategyLab/BinancePlatform` | `crypto` | `STRATEGY_PROFILE=crypto_leader_rotation` | Oracle Cloud + self-hosted runner | `binancequant` only for Firestore / GCP credentials | GitHub Actions `workflow_dispatch` + self-hosted runner |
+| Platform | Repo | Strategy domain | Runtime identity | Strategy selector | Runtime model | Project / backend | Runtime unit |
+|---|---|---:|---|---|---|---|---|
+| IBKR | `QuantStrategyLab/InteractiveBrokersPlatform` | `us_equity` | `RUNTIME_TARGET_JSON` + `ACCOUNT_GROUP` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` | Cloud Run | configurable |
+| Schwab | `QuantStrategyLab/CharlesSchwabPlatform` | `us_equity` | `RUNTIME_TARGET_JSON` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` | Cloud Run | `charlesschwabquant` | `charles-schwab-quant-service` |
+| LongBridge | `QuantStrategyLab/LongBridgePlatform` | `us_equity` | `RUNTIME_TARGET_JSON` + `ACCOUNT_REGION` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` | Cloud Run | configurable |
+| Binance | `QuantStrategyLab/BinancePlatform` | `crypto` | `RUNTIME_TARGET_JSON` (workflow-local) | `STRATEGY_PROFILE=crypto_leader_rotation` | Oracle Cloud + self-hosted runner | `binancequant` only for Firestore / GCP credentials | GitHub Actions `workflow_dispatch` + self-hosted runner |
 
 ## Platform details
 

docs/platform_strategy_matrix.md

@@ -18,19 +18,19 @@ For strategy behavior, research status, and archived backtest evidence, see
 - There are currently two strategy domains:
   - `us_equity`
   - `crypto`
-- Runtime repositories already expose `STRATEGY_PROFILE`, but this is **not** a full multi-strategy marketplace yet.
+- Runtime repositories now expose `RUNTIME_TARGET_JSON` plus `STRATEGY_PROFILE`; this is **not** a full multi-strategy marketplace yet.
 - Today, each US equity platform can switch among the `runtime_enabled` `us_equity` profiles published by `UsEquityStrategies`, subject to each platform's rollout configuration.
 - Platform runtime adapters are generated from strategy input/target-mode declarations plus platform capabilities, so new in-contract profiles should not need per-platform allowlist edits.
 - The shared contract is in `QuantPlatformKit`; real `us_equity` strategy implementations now live in `UsEquityStrategies`, while platform repositories own runtime adapters and broker execution.
 
 ## Platform matrix
 
-| Platform | Repo | Strategy domain | Configurable profile scope | Runtime model | Real switching today? |
-|---|---|---|---|---|---|
-| IBKR | `QuantStrategyLab/InteractiveBrokersPlatform` | `us_equity` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` | Cloud Run | Yes - controlled by platform rollout config |
-| Charles Schwab | `QuantStrategyLab/CharlesSchwabPlatform` | `us_equity` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` | Cloud Run | Yes - controlled by platform rollout config |
-| LongBridge | `QuantStrategyLab/LongBridgePlatform` | `us_equity` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` per regional service | Cloud Run | Yes - controlled by platform rollout config |
-| Binance | `QuantStrategyLab/BinancePlatform` | `crypto` | `crypto_leader_rotation` | Oracle Cloud + self-hosted runner | No - only this profile is supported today |
+| Platform | Repo | Strategy domain | Runtime identity | Configurable profile scope | Runtime model | Real switching today? |
+|---|---|---|---|---|---|---|
+| IBKR | `QuantStrategyLab/InteractiveBrokersPlatform` | `us_equity` | `RUNTIME_TARGET_JSON` + `ACCOUNT_GROUP` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` | Cloud Run | Yes - controlled by platform rollout config |
+| Charles Schwab | `QuantStrategyLab/CharlesSchwabPlatform` | `us_equity` | `RUNTIME_TARGET_JSON` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` | Cloud Run | Yes - controlled by platform rollout config |
+| LongBridge | `QuantStrategyLab/LongBridgePlatform` | `us_equity` | `RUNTIME_TARGET_JSON` + `ACCOUNT_REGION` | `STRATEGY_PROFILE=<runtime_enabled us_equity profile>` per regional service | Cloud Run | Yes - controlled by platform rollout config |
+| Binance | `QuantStrategyLab/BinancePlatform` | `crypto` | `RUNTIME_TARGET_JSON` (workflow-local) | `crypto_leader_rotation` | Oracle Cloud + self-hosted runner | No - only this profile is supported today |
 
 ## What this means right now
 

docs/runtime_target_architecture.md

@@ -0,0 +1,198 @@
+# Runtime Target Architecture
+
+## Goal
+
+Make runtime selection explicit and stable across platforms by separating:
+
+- strategy selection
+- platform selection
+- account selection
+- deployment mode
+
+`STRATEGY_PROFILE` still exists as a compatibility selector, but the running service is now described primarily by `RuntimeTarget` and `RuntimeAssembly`.
+
+## Core idea
+
+The shared control-plane object is `RuntimeTarget`.
+
+It answers:
+
+- which platform is this?
+- which strategy implementation is selected?
+- is this paper or live?
+- which deployment selector is active?
+- which account selector is active?
+- which service is this bound to?
+
+The runtime target should flow through:
+
+- GitHub env sync
+- Cloud Run env
+- runtime logs
+- reports
+- deployment previews
+
+`RuntimeAssembly` is the internal bridge object that carries the deployment identity plus the runtime target into logging, reporting, and platform wiring.
+
+## Design patterns used
+
+### Strategy
+
+`strategy_profile` selects the strategy behavior:
+
+- signal generation
+- universe
+- cadence
+- sizing rules
+
+It must not own broker selection or deployment identity.
+
+### Bridge
+
+Platform and strategy evolve independently.
+
+- strategy axis: `global_etf_rotation`, `tqqq_growth_income`, ...
+- platform axis: LongBridge, IBKR, Schwab, PaperSignal
+
+`RuntimeTarget` is the bridge payload that keeps those axes separate.
+
+### Adapter
+
+Each platform still adapts unified ports to broker-specific APIs:
+
+- `ExecutionPort`
+- `PortfolioPort`
+- `MarketDataPort`
+- notification/report adapters
+
+Platform differences stay at the edge.
+
+### Abstract Factory
+
+A runtime factory assembles a runnable service from `RuntimeTarget` and `RuntimeAssembly`:
+
+- runtime config
+- broker adapter
+- reporting adapter
+- notification adapter
+- capability validation
+
+### Template Method
+
+GitHub sync and runtime startup follow the same high-level flow:
+
+1. resolve inputs
+2. resolve capability
+3. build runtime target
+4. sync env
+5. start service
+6. emit report
+
+### Facade
+
+External callers should prefer a small surface:
+
+- `runtime_target`
+- `strategy_profile` for compatibility
+
+Do not leak broker-specific wiring into external deployment steps.
+
+## Target module split
+
+### Shared package
+
+`QuantPlatformKit`
+
+Owns:
+
+- `RuntimeTarget`
+- runtime config helpers
+- shared ports and adapters
+- runtime report helpers
+- strategy contracts
+
+### Platform runtime repository
+
+Example repositories:
+
+- `LongBridgePlatform`
+- `InteractiveBrokersPlatform`
+- `CharlesSchwabPlatform`
+
+Own:
+
+- runtime entrypoints
+- platform adapters
+- deployment sync scripts
+- account selection and secret wiring
+- platform-specific reporting text
+
+### Strategy repository
+
+Future shared strategy repositories should own:
+
+- reusable strategy math
+- platform-independent signal logic
+- domain parameters
+
+They should not own:
+
+- Cloud Run entrypoints
+- broker auth
+- scheduler wiring
+- deployment secrets
+
+## RuntimeTarget invariants
+
+- `strategy_profile` is still required for compatibility and strategy routing.
+- `platform_id` is required.
+- `dry_run_only` determines `execution_mode`.
+- `account_selector` is optional and platform-dependent.
+- `account_scope` is optional and may mirror region or account-group semantics.
+- `service_name` is a deployment identity, not a strategy concept.
+
+## Platform-specific account rules
+
+### LongBridge
+
+- split by region
+- `account_scope` can mirror `HK` / `SG`
+- `deployment_selector` should reflect the active region
+- one service per region is the target shape
+
+### IBKR
+
+- split by account group
+- `account_selector` may contain one or more IB account identifiers
+- `ACCOUNT_GROUP` stays as the external runtime selector
+
+### Schwab
+
+- typically one service identity
+- `account_selector` may stay empty
+- `STRATEGY_PROFILE` remains the compatibility selector, not the main control plane
+
+### PaperSignal
+
+- paper/live is controlled by `dry_run_only`
+- strategy identity still flows through the same `RuntimeTarget`
+
+## Migration sequence
+
+1. keep `STRATEGY_PROFILE` working
+2. emit `RuntimeTarget` in runtime settings and reports
+3. emit `RUNTIME_TARGET_JSON` in GitHub env sync
+4. move docs and previews to runtime-target-first wording
+5. keep `strategy_profile` only as internal compatibility input
+6. keep `RuntimeAssembly` as the internal bridge for entrypoints and reports
+7. extract more shared orchestration once the target model is stable
+
+## Practical rule
+
+If a piece of code answers:
+
+- "which broker runtime is this?"
+- "which account or region is active?"
+- "is this paper or live?"
+
+then it belongs in the runtime target / runtime config layer, not in strategy code.