Commands, events, and state

Target design contract; wire schema is not yet frozen. The scaffold supports a smaller immediate command lifecycle and in-memory state; durable journaling and scheduled execution are planned. DjState contains decks, mixer, track references, transport position, ownership, capabilities, and observation freshness. Unknown values remain unknown rather than defaulting to plausible measurements.

A command envelope carries schema_version, session_id, command_id, server-authenticated actor_id, target resource, ownership generation, optional expected state revision, requested execution frame, and typed payload. Values have explicit units and ranges: tempo in BPM, gain in dB, faders in [0, 1], and positions in source frames with source sample rate.

Lifecycle

1. Authenticate the actor and validate the envelope.
2. Reject duplicates, stale ownership, unsupported capabilities, invalid values, and disallowed scheduling. Duplicate IDs return the original result without repeating the action.
3. Assign a server sequence and enqueue valid work.
4. At execution, recheck ownership and capabilities. Emit applied events for virtual actions; dispatch physical actions and wait for the relevant evidence.
5. Reduce authoritative events into state and publish the new revision.

Distinguish CommandAccepted, CommandRejected, CommandDispatched, CommandApplied, and CommandFailed or CommandTimedOut. A device observation can corroborate a requested change without proving causality; mark inferred matches explicitly.

Event records include session sequence, event ID, simulation frame, source time if available, receive time, source identity, causation command ID where known, payload, and schema version. Events at the same frame are ordered by sequence. State reducers must be pure.

Durability and telemetry

Store commands, results, ownership changes, external inputs, and state-affecting events in the session journal. High-rate meters and display interpolation are disposable telemetry. Store waveform/audio artifacts separately. Do not assume that an in-memory event bus makes a session event-sourced.

A session starts from a versioned initial snapshot. Checkpoints include the last sequence and state hash. A crash leaves a recoverable valid journal prefix; incomplete tails are detected. If durable recording cannot keep up, mark the session incomplete and disable reproducibility claims while keeping live audio running.

Replay distinguishes state reconstruction from re-running actor decisions.