dsh-session-persistence-mysql

The default JSONL file backend of DeepSeek Harness is perfectly adequate for single-node setups, but its limitations surface quickly in multi-instance deployments, high-concurrency workloads, or any scenario that demands cross-process session-state sharing. Writes lack transactional guarantees, a hard crash can leave half-written records, and there is no way to offload read traffic to a replica. dsh-session-persistence-mysql exists to close exactly that gap: it persists the event-sourced SessionEvent log into MySQL with a behaviour contract identical to the JSONL backend, so it can be dropped in as a plugin and replace the default implementation seamlessly.

The plugin’s design revolves around three pillars — write safety, read separation, and crash survivability. Every appendBatch lands in a single InnoDB transaction; the log is strictly append-only with contiguous sequence numbers, and the composite primary key makes same-ID double-writes impossible by construction. A dedicated read pool, configured independently via SESSION_READ_* environment variables, serves all read hooks while the write pool handles appends; when no replica is set it transparently falls back to a single shared connection. If a process dies mid-turn, the shared coordinator writes synthetic closers to durably close the interrupted exchange, and committed records are never rewritten. Lazy materialization guarantees the session header and its first event batch commit atomically, bounded deadlock retries keep throughput stable under contention, and idempotent schema creation on startup eliminates manual DDL steps.

It is aimed at teams shipping DeepSeek Harness into production or distributed topologies: multiple dsh instances that must share one session store, operators who prefer database-native backup and replication over file-level snapshots, or read-heavy deployments that benefit from a dedicated replica. In all of these cases the plugin offers a smooth, contract-preserving migration path from the JSONL file backend to a relational database, and it slots naturally alongside dsh-storage-mysql, dsh-credentials-mysql, and dsh-workspace-bootstrap to form a fully distributed deployment.