ADR 034 — Activity and Simulation boundaries
- Status: Accepted (2026-08-10) — ratified in chat / field ADR package (first-class module + Nautilus)
- Related: ADR 033, ADR 035, principal plan
Context
Source docs propose a universal Simulation type and metaclass binding. Repo evidence shows:
- No
SimulationSpec/SimulationMeta/ PyO3 SHM product path (BLOCKED). - De facto simulation:
GraphSpec(mode="simulation")+ backtest engines +LabRuntime. - Distinct dispatch/deploy types already exist:
WorkRequest,WorkflowSpec,DeploymentSpec.
Collapsing these nouns causes wrong ownership (e.g. treating infra deploy as a simulation, or agent DAGs as µs engines).
Decision
Adopt the following non-collapsible vocabulary:
| Noun | Definition | Canonical home today |
|---|---|---|
| Activity | Short-lived auditable unit (tool invoke, approval step, pricing calc) | DataMCP / approvals; optional alphaswarm.activity facade later |
| Simulation | Deterministic/quasi-deterministic replay; no live venue side effects | GraphSpec(mode="simulation"), backtest engines, RL non-paper episodes |
| Workflow | Multi-step checkpointed graph | WorkflowSpec + WorkflowRuntime |
| WorkRequest | Resource-bounded routed dispatch unit | alphaswarm_worker.WorkRequest |
| DeploymentSpec | Infra deploy request | alphaswarm_core.models.deployment.DeploymentSpec |
Reject SimulationMeta and “write-once identical semantics” across vectorized ↔ live ↔ agent DAG. Share pure kernels + canonical events; engines own time/I/O/fill semantics.
Do not add Temporal Activities. Orchestration remains Dagster/Prefect via alphaswarm_orchestration.
Consequences
- New APIs must declare which noun they implement.
- A future named
SimulationSpecis allowed only if it is a thin typed alias/facade over GraphSpec/backtest configs — not a parallel runtime family — and only after Phase 5 review. - Agent-directed DAGs stay in the agent/workflow plane, never as an execution-engine peer to live money-plane paths.