DMS Simulation — real-time API

Transport is Socket.IO (Engine.IO), not a raw WebSocket.

- HTTP path: `/ws/socket.io`
- Namespace: `/simulation`
- Requires `ENABLE_SOCKET_TIMER=true` on the server for the endpoint to be mounted.

Authentication (on connect)
JWT access token via either:
- `Authorization: Bearer <token>`, or
- query parameter `token=<jwt>`

Disconnect closes any open simulation attempt (server-side).

Servers

local

URL: localhost:{port}/ws/socket.io

Protocol: ws

port default=8000 — Same as APP_PORT (uvicorn/gunicorn).

Channels

`simulation:complete`

Publish (client → server)

Finalise attempt with optional score and metadata

simulationComplete

type: object
properties:
  attempt_id:
    type: integer
  score:
    type: number
  metadata:
    description: Arbitrary JSON-serialisable metadata (stored truncated server-side).

`simulation:completed`

Subscribe (server → client)

Server confirms completion

simulationCompleted

type: object
properties:
  attempt_id:
    type: integer
  ok:
    type: boolean

`simulation:error`

Subscribe (server → client)

Server rejects simulation:start (validation / business rule)

simulationError

type: object
properties:
  error:
    type: string

`simulation:first_cta`

Publish (client → server)

Record first CTA for timing

simulationFirstCta

type: object
properties:
  attempt_id:
    type: integer
    description: Uses session attempt id if omitted.

`simulation:first_cta_recorded`

Subscribe (server → client)

Server confirms first CTA

simulationFirstCtaRecorded

type: object
properties:
  attempt_id:
    type: integer

`simulation:heartbeat`

Publish (client → server)

Keep-alive / presence for session timing

simulationHeartbeat

type: object
properties:
  attempt_id:
    type: integer

`simulation:start`

Publish (client → server)

Client starts a simulation attempt

simulationStart

type: object
required:
- simulation_id
properties:
  simulation_id:
    type: integer
    description: Simulation module id.
  allocation_id:
    type: integer
    description: Optional licence allocation id (B2B).

`simulation:started`

Subscribe (server → client)

Server returns new attempt id after simulation:start

simulationStarted

type: object
properties:
  attempt_id:
    type: integer