Skip to content

us_equity_strategy_onboarding.md

Latest commit

 

History

History
179 lines (127 loc) · 8.28 KB

us_equity_strategy_onboarding.md

File metadata and controls

179 lines (127 loc) · 8.28 KB

US Equity Strategy Onboarding Checklist

Verified snapshot: 2026-04-16

This checklist describes how a new us_equity strategy becomes available on the three US equity broker platforms without adding a manual allowlist entry in each platform repository.

It applies to:

  • InteractiveBrokersPlatform
  • CharlesSchwabPlatform
  • LongBridgePlatform
  • UsEquityStrategies
  • QuantPlatformKit

Target operating model

UsEquityStrategies is the source of truth for live strategy profiles. The three platform repositories derive their runtime allowlists from get_runtime_enabled_profiles().

A new strategy should become selectable on a platform only after these are true:

  1. The strategy is registered in the UsEquityStrategies catalog.
  2. The strategy declares status="runtime_enabled" only when it is ready for live runtime.
  3. The strategy lists the exact platforms it supports in supported_platforms.
  4. The strategy exposes a unified entrypoint returning StrategyDecision.
  5. The strategy has one platform-neutral runtime adapter spec.
  6. Platform runtime adapters are derived from that spec plus platform native target mode.
  7. The platform capability matrix says the platform can supply the declared required_inputs.
  8. The relevant platform status script reports eligible=true and enabled=true.

Do not add a second per-platform rollout allowlist for live US equity profiles.

Strategy repository requirements

In UsEquityStrategies, a new live profile needs:

  • a canonical profile id in catalog.py
  • a StrategyDefinition with domain="us_equity"
  • explicit required_inputs
  • explicit target_mode
  • status="runtime_enabled" only after platform coverage is complete
  • supported_platforms set to the intended platforms
  • a manifest and unified entrypoint
  • focused strategy tests
  • one platform-neutral runtime adapter spec
  • StrategyArtifactContract when artifacts are required
  • StrategyRuntimePolicy when runtime windows or reconciliation output rules are required
  • packaged or artifact-published canonical config when a live default config exists

The current standard input names are:

  • market_history
  • benchmark_history
  • derived_indicators
  • portfolio_snapshot
  • feature_snapshot

Do not introduce a new input name unless the cross-platform contract docs are updated first.

Runtime adapter requirements

Each strategy needs one base StrategyRuntimeAdapter spec in UsEquityStrategies.

The base adapter should declare strategy-owned metadata:

  • required feature snapshot columns when the strategy uses feature_snapshot
  • snapshot date/freshness rules when the artifact has date-sensitive content
  • StrategyArtifactContract, including snapshot, manifest, strategy config, and config source policy
  • StrategyRuntimePolicy, including reconciliation output and runtime execution window requirements
  • runtime config loaders only as strategy config readers, not as platform deployment logic

Platform-specific adapters are generated from:

  • the strategy's required_inputs
  • the strategy's target_mode
  • the platform's native target mode
  • the platform's declared capabilities

When a weight-mode strategy runs on a value-native platform, the generated adapter adds portfolio_snapshot so the platform can translate weights into dollar orders. When the strategy already requires portfolio_snapshot, the generated adapter maps it as the portfolio input automatically.

The adapter generator is the bridge between strategy contract and platform runtime. Strategy code should not branch on broker platform ids.

When adapters change, platform scripts should only consume the derived runtime requirements:

  • requires_snapshot_artifacts
  • requires_snapshot_manifest_path
  • requires_strategy_config_path
  • config_source_policy
  • reconciliation_output_policy
  • runtime_execution_window_trading_days

Platform code should not add if profile == "..." branches for strategy-private behavior.

Platform repository requirements

The three US equity platform repositories should stay thin:

  • resolve the selected STRATEGY_PROFILE
  • ask the shared strategy registry whether the profile is supported
  • assemble StrategyContext
  • load the unified entrypoint
  • map StrategyDecision to broker-specific orders and notifications

The platform registry should derive live profiles from UsEquityStrategies.get_runtime_enabled_profiles().

Platform repositories should not hard-code strategy symbol pools, private strategy constants, or manual live profile allowlists.

Platform repositories may change when a new broker capability is needed, such as a new market-data input builder. They should not change their core execution flow just to accommodate a strategy-private parameter.

Artifact-backed profiles

If a strategy uses feature_snapshot, the platform env sync workflow must enforce the artifact env vars before Cloud Run is updated. The workflow should derive this from scripts/print_strategy_profile_status.py --json, not from a hard-coded profile-name list.

Current env mapping:

Platform Snapshot path env Manifest path env Strategy config env
IBKR IBKR_FEATURE_SNAPSHOT_PATH IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH IBKR_STRATEGY_CONFIG_PATH
Schwab SCHWAB_FEATURE_SNAPSHOT_PATH SCHWAB_FEATURE_SNAPSHOT_MANIFEST_PATH SCHWAB_STRATEGY_CONFIG_PATH
LongBridge LONGBRIDGE_FEATURE_SNAPSHOT_PATH LONGBRIDGE_FEATURE_SNAPSHOT_MANIFEST_PATH LONGBRIDGE_STRATEGY_CONFIG_PATH

Only profiles whose adapter requires a manifest should require the manifest path. Only profiles with config_source_policy="env_only" should require the strategy config path. Profiles with config_source_policy="bundled_or_env" use the packaged canonical config by default and treat env paths as explicit overrides.

Minimum onboarding steps

  1. Register the profile, manifest, default config, and unified entrypoint in UsEquityStrategies.
  2. Declare required_inputs, target_mode, supported_platforms, and status.
  3. Add the base StrategyRuntimeAdapter with StrategyArtifactContract and StrategyRuntimePolicy.
  4. If the profile uses feature_snapshot, declare schema, date columns, freshness, manifest contract version, and managed symbol extraction.
  5. If live config is required, prefer packaging it with the strategy package; use env_only only when it cannot be packaged.
  6. Run strategy contract governance and entrypoint tests, then verify describe_platform_runtime_requirements().
  7. Run each platform status or switch-plan script and confirm eligible/enabled state plus artifact env requirements come from the adapter.
  8. Modify platform core flow only when a new broker data source or execution capability is required.

Test gates

Before marking a new profile runtime_enabled, run:

  • QuantPlatformKit strategy contract tests
  • UsEquityStrategies contract governance and entrypoint tests
  • IBKR runtime config, loader, runtime, and workflow tests
  • LongBridge runtime config, loader, runtime, and workflow tests
  • Schwab runtime config, loader, runtime, and workflow tests
  • each platform's scripts/print_strategy_profile_status.py --json

UsEquityStrategies governance tests should fail if a runtime_enabled strategy does not have the expected generated platform adapter coverage.

Release order

Use this order for a live rollout:

  1. Merge and tag QuantPlatformKit if shared contracts changed.
  2. Merge and tag UsEquityStrategies.
  3. Update platform repository dependency pins to the released tags.
  4. Merge the platform repositories.
  5. Let Cloud Run source deployments build the platform repositories.
  6. Enable or update GitHub-managed env sync values.
  7. Verify Cloud Run env and the first runtime heartbeat.

Current pending tags for this change set:

  • QuantPlatformKit -> v0.7.16
  • UsEquityStrategies -> v0.7.23

Permission-dependent steps

Local code, tests, and docs do not require GitHub or Google Cloud login.

These steps require credentials:

  • pushing commits and tags with gh or git
  • creating pull requests or releases
  • updating GitHub repository variables, secrets, or environments
  • creating or updating Workload Identity Federation bindings
  • creating or updating Secret Manager secrets
  • deploying or inspecting Cloud Run services
  • creating or updating Cloud Scheduler jobs
  • reading or writing GCS strategy artifacts