Initial commit of integrated agent system

docs/compat-removal-plan.md

@@ -0,0 +1,116 @@
+# Compatibility And Migration Status
+
+This document tracks the remaining migration-related boundaries after the
+repository switched to split-first development.
+
+## Current Status
+
+The repo no longer depends on a combined FastAPI compatibility wrapper for
+normal local development. The default path is now:
+
+`agent_service + trading_service + news_service + runtime_service + gateway`
+
+That means compatibility is no longer a separate startup mode. What remains is
+mostly protocol-level and routing-level compatibility while the codebase
+continues to move responsibilities into clearer service surfaces.
+
+## What Was Removed
+
+### `backend.app`
+
+- Removed after startup paths switched away from the legacy app wrapper.
+
+### `backend.apps.combined_service`
+
+- Removed after split-service startup became the only supported local dev mode.
+
+### `shared.client.AgentServiceClient`
+
+- Removed after split-aware clients became the default import surface.
+- Replaced by:
+  - `ControlPlaneClient`
+  - `RuntimeServiceClient`
+  - `TradingServiceClient`
+  - `NewsServiceClient`
+
+## What Still Exists For Compatibility
+
+These are not legacy wrappers in the old sense, but they still preserve
+backward-compatible behavior while migration settles.
+
+### Gateway-mediated flows
+
+- The WebSocket gateway still carries a mix of:
+  - live runtime feed transport
+  - orchestration
+  - selected read flows that have not been moved to direct browser service calls
+- This is intentional for now because the frontend still depends on the gateway
+  for event streaming and some compatibility reads.
+
+### In-process fallbacks
+
+- Some read paths still support local-module fallback when split-service URLs
+  are not configured.
+- Relevant variables include:
+  - `TRADING_SERVICE_URL`
+  - `NEWS_SERVICE_URL`
+- This keeps the app resilient during migration, but it also means behavior can
+  differ depending on env configuration.
+
+### Dual OpenClaw integration surfaces
+
+- OpenClaw currently appears through two different shapes:
+  - WebSocket gateway integration on `:18789`
+  - optional REST surface at `backend.apps.openclaw_service` on `:8004`
+- These are both valid, but they are not the same surface and should not be
+  documented as interchangeable.
+
+## Remaining Migration Risks
+
+### Split service deployment is not yet the checked-in production default
+
+- The repo documents split-service local development clearly.
+- The checked-in production example still centers on `backend.main` and nginx
+  WebSocket proxying.
+- This is a topology mismatch to keep in mind when changing deploy docs or prod
+  automation.
+
+### Environment-dependent routing
+
+- The frontend and gateway can switch behavior based on configured service URLs.
+- This is helpful operationally, but it makes debugging more configuration-
+  sensitive than a fully fixed service topology.
+
+### Runtime/control-plane separation is logical, not fully operationally isolated
+
+- `runtime_service` owns lifecycle APIs.
+- `agent_service` owns control-plane APIs.
+- The gateway still hosts the live runtime orchestration path, so the split is
+  clean at the API level but not yet a completely independent service mesh.
+
+## Exit Criteria For Declaring Migration Complete
+
+Migration can be considered effectively complete when all of the following are
+true:
+
+1. Production deployment docs and scripts explicitly run the same split-service
+   topology used in development, or intentionally document a different stable
+   production topology.
+2. Critical read paths no longer require ambiguous fallback behavior to local
+   module implementations.
+3. OpenClaw integration is documented as a stable contract with clear guidance
+   on when to use the WebSocket gateway versus the REST surface.
+4. The frontend-service routing model is stable enough that direct-service and
+   gateway-mediated paths are deliberate design choices rather than migration
+   leftovers.
+
+## Practical Read Of The Current State
+
+The migration away from combined-service startup is done.
+
+What remains is not “legacy startup debt”, but:
+
+- topology clarification
+- deployment consistency
+- reduction of env-dependent fallback behavior
+- sharper documentation around gateway and OpenClaw boundaries