evotraders/docs/legacy-inventory.md

# Legacy Inventory

This file records the major legacy or compatibility-oriented surfaces that still
exist in the repository.

It is not a deletion plan by itself. Its purpose is to separate:

- current source-of-truth runtime paths
- intentional compatibility surfaces
- historical directories and scripts that should not guide new development

## Source Of Truth

These are the current defaults to build against:

- `runs/<run_id>/`
  - runtime state, bootstrap configuration, agent runtime assets, logs
- split services
  - `backend.apps.agent_service` on `:8000`
  - `backend.apps.runtime_service` on `:8003`
  - `backend.apps.trading_service` on `:8001`
  - `backend.apps.news_service` on `:8002`
- gateway process
  - `backend.gateway_server` in the default managed-runtime path
  - `backend.services.gateway` on `:8765`

## Compatibility Surface Classification

All compatibility surfaces are categorized into three buckets:

### 1. Stable and Intentional (Keep)

These have clear operational reasons to exist and are documented as intentional
compatibility surfaces with explicit ownership.

| Surface | Location | Owner | Reason |
|---------|----------|-------|--------|
| Dashboard export layer | `runs/<run_id>/team_dashboard/*.json` | frontend-team | Downstream dashboard consumers read these exports |
| Design-time workspace registry | `workspaces/`, `backend.api.workspaces` | control-plane-team | Control-plane editing and registry-style management |
| Gateway WebSocket transport | `backend.services.gateway` on `:8765` | runtime-team | Live event streaming contract for frontend |

**Status**: These are NOT migration leftovers. Do not remove without explicit
replacement plan signed off by owning team.

### 2. Temporary and Shrinking (Mark for Removal)

These should not grow further. Keep only until concrete replacement is fully
in use.

| Surface | Location | Replacement | ETA |
|---------|----------|-------------|-----|
| Legacy agent fallback paths | compatibility constructors in `backend.core.pipeline_runner` | `EvoAgent` | After fallback-free runtime cutover |
| Mixed workspace_id semantics | removed from runtime agent routes | ✅ `/api/runs/{run_id}/agents/...` is the only runtime agent route | Completed |
| Root-level runtime directories | `live/`, `backtest/`, `production/` | `runs/<run_id>/` | ✅ Removed, backed up to runs/_legacy/ |

**Status**: Do not add new code using these surfaces. Migrate existing usage
when touching related code.

### 3. Deferred Until Topology Final (Revisit Later)

These are real migration boundaries, but removing them prematurely would create
churn without simplifying the current runtime. Revisit only after production
topology and service-routing policy are frozen.

| Surface | Current State | Decision Needed |
|---------|---------------|-----------------|
| OpenClaw integration | Gateway WebSocket (port 18789) | Stable — REST facade removed |
| Env-dependent service fallbacks | `TRADING_SERVICE_URL`, `NEWS_SERVICE_URL` fallbacks to local modules | Remove fallbacks and require explicit URLs? |
| Split-service deployment docs | Deployment docs are still partial compared with the dev topology | Rewrite deploy docs around split services? |

**Status**: Document current behavior. Do not actively remove until topology
decisions are finalized.

## Detailed Surface Documentation

### Dashboard Export Layer

**Files**: `runs/<run_id>/team_dashboard/*.json`

**Purpose**:
- Compatibility/export layer for dashboard consumers
- Non-authoritative snapshot of runtime state
- Can be disabled via `ENABLE_DASHBOARD_COMPAT_EXPORTS=false`

**Why not remove**:
- Downstream consumers still read these files
- Provides decoupling between runtime and dashboard

**Ownership**: frontend-team
**Status**: Stable and intentional

### Design-Time Workspace Registry

**Files**:
- `workspaces/` directory
- `backend/api/workspaces.py`
- `backend/agents/workspace_manager.py`

**Purpose**:
- Control-plane editing and registry-style management
- Design-time CRUD for agent workspaces
- Separate from runtime state in `runs/<run_id>/`

**Key distinction**:
- `workspaces/` = design-time registry (what agents *could* be)
- `runs/<run_id>/` = runtime state (what agents *are* right now)

**Ownership**: control-plane-team
**Status**: Stable and intentional

## Historical Or High-Risk-To-Misread Surfaces

These remain in the tree, but they should not define the architecture for new work.

### Root-level runtime directories

- `live/`
- `backtest/`
- `production/`

**Read**:

- treat these as historical or compatibility-oriented data/layout artifacts
- do not use them as the default runtime contract for new features

### Historical mixed `workspace_id` semantics on agent routes

This compatibility shape has been removed from runtime agent routes.

**Current rule**:

- design-time CRUD routes use `/api/workspaces/{workspace_id}/agents/...`
- runtime agent assets use `/api/runs/{run_id}/agents/...`

### Partial EvoAgent rollout

- `EVO_AGENT_IDS`
- staged smoke coverage in `scripts/smoke_evo_runtime.py`

**Read**:

- EvoAgent is the default selection path for supported roles in the current
  pipeline
- legacy implementations remain as compatibility fallbacks in selected startup
  and runner paths

## Recommended Usage

When in doubt:

1. trust `docs/current-architecture.md`
2. trust `runs/<run_id>/` over root-level runtime directories
3. treat `workspaces/` as control-plane registry, not runtime truth
4. treat deploy artifacts as partial references, not the full system contract
5. check this file's **Compatibility Surface Classification** before assuming something is legacy
6. prefer `runtime_service`-managed startup for all new work

## Change Log

| Date | Change |
|------|--------|
| 2026-03-31 | Added Compatibility Surface Classification (3 buckets) |
| 2026-03-31 | Clarified OpenClaw integration documentation |
| 2026-03-31 | Added ownership and status to all surfaces |