Skip to main content

ADR 038 — Legacy compatibility and deprecation

  • Status: Accepted (2026-08-10) — ratified in chat / field ADR package (first-class module + Nautilus)
  • Related: ADR 033, principal plan

Context​

Track B identified high-severity dual representations:

  • Symbol (legacy core/types.py) vs InstrumentId (core/domain/)
  • BarData vs Bar / BarSpecification
  • OrderRequest / OrderData vs DomainOrder

Event-driven backtest still imports legacy types. A facade (ADR-033) will temporarily create dual import paths. Big-bang deletion would break engines, Celery tasks, and UI contracts.

Decision​

  1. Strangler Fig only — new code prefers alphaswarm.core.domain.* and facade modules; legacy shims remain until call sites migrate.
  2. Deprecation window: minimum two minor releases of DeprecationWarning on legacy public imports after facade GA, tracked by an import inventory CI report.
  3. Hotspot order: (1) Symbol/InstrumentId, (2) BarData/Bar, (3) OrderRequest/DomainOrder, then Signal/PortfolioTarget.
  4. No behavior change in Phase 1 facade skeleton — re-exports only.
  5. Migrations remain immutable; additive schema for new domain tables (Fill, Listing, etc.).
  6. Forbidden shortcuts: editing shipped Alembic versions; mutating hash-locked *_spec_versions; deleting legacy types while engine imports remain.

Consequences​

  • Compatibility package/docs must list shim → target maps.
  • Engines get parity tests before each type cutover.
  • alphaswarm_index + AGENTS maps update on each phase exit (curator or debt notes).

Rollback​

Re-enable shim re-exports; lower warning level; keep dual accept in translators (ExecutionProfile, domain adapters).