ADR 033 — Canonical first-class alphaswarm module

• Status: Accepted (2026-08-10) — ratified in chat / field ADR package (first-class module + Nautilus)
• Authors: Platform architecture (consolidation planning)
• Related: ADR 005, ADR 004, principal plan

Context

Source reports urge a “first-class” trading/simulation module. The estate already has many packages (alphaswarm, alphaswarm_core, alphaswarm_controller, alphaswarm_worker, specialists). Promoting the wrong layer would either:

1. Bloat alphaswarm_core (intentionally dependency-light infra contracts), or
2. Create a parallel public API that duplicates WorkRequest / DeploymentSpec / runtimes.

Spot-verified facts: DeploymentSpec already exists; worker owns WorkRequest/ExecutorRouter; controller owns /manage/*; Temporal and asctl are absent.

Decision

Adopt a monorepo-local compatibility facade that promotes the existing alphaswarm Python namespace as the stable public domain/application kernel.

• Application code prefers alphaswarm.* for domain vocabulary, activities, simulations, and composition helpers.
• Infra wire contracts remain in alphaswarm_core.
• Mutation remains in alphaswarm_controller.
• Distributed execution remains in alphaswarm_worker.
• Specialists (agents, bots, rl, models, kb) remain separately deployable owners.
• Facades use translation adapters; no big-bang package merge.

Secondary (not primary): PEP 420 namespace aggregation, or generated contracts via alphaswarm_catalog — complementary for schemas, insufficient as the application kernel.

Consequences

Positive

• Matches existing import gravity (monolith already composes specialists).
• Preserves CI import boundaries on controller/worker.
• Enables Strangler Fig without renaming every package.

Negative / risks

• Facade can become a god-object if logic is copied inward — mitigate with thin re-exports.
• Dual import paths during transition — mitigate with deprecation ADR-038.

Compliance

• Do not introduce a second scheduler/execution/MLOps/deployment control plane.
• Do not invent RuntimeDeploymentSpec; use DeploymentSpec.

Alternatives considered

Option	Why rejected / deferred
Promote alphaswarm_core alone	Too thin / wrong layer for quant domain
Big-bang rename/merge	Breaks consumers; high risk
New greenfield alphaswarm_platform_sdk	Parallel universe; duplicates contracts
PEP 420 aggregation	Secondary packaging tactic only