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