HTTP and WebSocket

Mixed implementation/reference page. The daemon retains the metadata state/commands/WebSocket API and now adds the offline /library, /sessions, /sessions/{id}/control, /sessions/{id}/replay, and artifact routes. See current status and the software wire contract for exact implemented DTOs. The richer lifecycle and hardware routes below remain proposed. All HTTP routes use /api/v1; WebSocket transport remains the metadata playground.

Method / path	Purpose
GET /api/v1/state	Snapshot, state revision, sequence cursor, capabilities
GET /api/v1/devices	Device identities, modes, freshness, capabilities
GET /api/v1/tracks	Registered track metadata
GET /api/v1/sessions	Session manifests and completion status
GET /api/v1/config	Effective non-secret configuration
POST /api/v1/commands	Submit the same command envelope used over WS
POST /api/v1/simulator/start	Instantiate a scenario
POST /api/v1/simulator/stop	Stop simulation explicitly
POST /api/v1/sessions	Begin recording with a manifest
POST /api/v1/sessions/{id}/stop	Finalize recording

Recording lifecycle and simulation lifecycle are distinct: stopping a recording does not stop playback.

Illustrative first-slice exchange

{
  "schema_version": 1,
  "session_id": "demo",
  "command_id": "cmd-001",
  "ownership_generation": 1,
  "payload": { "type": "Play", "deck_id": 1 }
}

The server derives actor identity from the authenticated connection. It first returns a receipt tied to command_id; an applied event later supplies the sequence, output frame, and resulting state revision. Rejected commands carry stable reason codes such as unsupported, not_owner, stale_revision, or invalid_value.

Use JSON initially. A stream starts with a versioned snapshot and cursor; subscription setup must avoid a race between snapshot capture and subsequent events. Bound outbound queues, coalesce meters, and force resynchronization rather than silently dropping authoritative events. Reject incompatible schema versions explicitly.

Bind to loopback by default. For LAN operation, define authentication, allowed browser origins, viewer/controller roles, and transport protection. Require authentication on control-plane HTTP routes as well as WebSocket upgrades. Avoid logging credentials or raw track filesystem paths.