SessionEvent: the single source of truth
Message history is not a stored array; it is derived from an append-only, extensible, lossless JSON log
append-only facts → surface projection → derived messagesWhy persist raw assistant chunks instead of only the final message?
A session log is a flight data recorder. Passenger announcements are one projection; investigation, replay, metering, and dashboards rebuild from finer-grained facts.
Mechanism
SessionEventMap expands through declaration merging. Core turn/step/message/tool events coexist with domain events for goals, approval, compaction, schedules, and more.
deriveMessages() projects model history from current surface position order. Replacement nodes may have larger seq values while appearing earlier, so numeric seq is not surface order.
Append event
Validate lossless JSON, then allocate contiguous seq.
What extensions must preserve
- Model-visible means logged
- seq is contiguous but not surface position
- Commit points isolate observer failure
The tempting wrong turns
- ×Storing a second messages array as truth
- ×Skipping log-only events during replay and drifting domain state
- ×Encoding transient UI state as model-visible messages
Do not trust the conclusion—verify it
These anchors are pinned to official deepseek-harness@47f9438; account for later breaking changes when reading current upstream.
Pause for ten seconds before revealing
Why does compaction append a replacement user/message instead of mutating old events?
With a fact log, turns and steps become clear durable boundaries. Next we follow work from inbox claim.