Polytraders Dev Guide
internal
v3 spine Phase 1 · Shared contracts 9 demo-wired · 0 shadow-ready · 0 production-live · 100 pending · 109 total 15/33 infra tasks the plan status board

Live modes

Five modes, in order of increasing effect. Every bot must support at least off, shadow, and enforced. Most also support advisory and quarantine.

ModeWhat it doesEffect on ordersWhen to use
offBot is disabled. decide() is not called.Nothing.Set during incident handling or before promotion.
shadowBot runs and emits ReportEnvelopes, but its output is discarded.Read-only.Pre-promotion validation; cross-checking new logic against incumbent.
advisoryBot's output is shown to operators and downstream bots, but never blocks or submits.Warn/recommend.Risk bots in their first week of life; new strategies before stub→limited_live.
enforcedBot's output is honoured according to its authority — Risk can block, Strategy can emit OrderIntents, Execution can submit.Up to its declared authority.The default for any bot at limited_live or wide_live.
quarantineBot isolates the affected market(s), wallet(s), or strategy(ies). It does not block the rest of the system.Reject orders that touch the quarantined scope; let everything else through.When a problem is localised but the rest of the platform is healthy.

Promotion ladder

A bot's mode and its readiness state are coupled. The default ladder is:

  1. stub · mode off by default.
  2. stub · promoted to shadow in staging with synthetic input fixtures.
  3. limited_live · advisory in prod_advisory; output reviewed by Risk on a daily standup.
  4. limited_live · enforced on a per-market allow-list.
  5. wide_live · enforced across the full universe.

Demotion goes through the same ladder in reverse and never skips a step.

Per-bot mode support

Every bot declares which modes it supports in its spec page. The build cross-checks this against the bot's class and authority — for example, a Guardrail must support enforced and quarantine; a Signal Service is forbidden from supporting enforced because it has no enforcement surface.