Internal Sessions and the Event Model

Every event belongs to a union discriminated by type: {type, seq, time, data}. Its only optional fields are surfaceOp, sourceEventSeqs, and ignorable: true. Seed and load reject every additional envelope key.SESSION-EVENT-ENVELOPE

The current build generates its known-event catalog from every SessionEventMap declaration in the repository and contains 44 types. The core package declares 13; package owners add the rest through TypeScript module augmentation.SESSION-CORE-EVENTSSESSION-KNOWN-EVENTS

snapshotJsonValue() walks the graph with an explicit task stack and validates while copying from the same property read. A stateful getter cannot swap values between a separate “check” and “copy” pass, and nesting depth is limited by memory rather than the JavaScript call stack.SESSION-LOSSLESS-JSON

Events and nested Messages are deep-frozen when admitted; derived history shares those frozen objects. Tests require mutations of content and tool results to throw TypeError, and an invalid graph to be rejected without changing log length.SESSION-IMMUTABILITY-TEST

The same frozen candidate crosses precommit validation, commit, and observation. A reentrant append during observer notification is rejected so a nested commit cannot reorder later listeners.SESSION-APPEND-COMMIT

The tests require an internal-dispatch veto to leave the log, publication, and Surface unchanged. After commit, a hostile observer can neither roll back the event nor prevent later observers from seeing it.SESSION-APPEND-BOUNDARY-TEST

The runtime recognizes only user/message, assistant/message, and tool/result as Surface-eligible. They must declare a surfaceOp; a boundary, chunk, request, or plugin audit event carrying Surface metadata fails.SESSION-SURFACE-PROJECTIONSESSION-SURFACE-PROVENANCE

A replacement tool/result may target exactly one current tool result and may change only the nested result block's content. Call ID, error flag, message identity, turn and step, and meta must remain structurally equivalent. Spill or pruning can shorten output without forging another tool execution.

When present, the source list must be dense, duplicate-free, composed of non-negative safe integers, and strictly earlier than the current event. A Surface replacement must include at least every shadowed node, or it cannot establish what the new node replaced.SESSION-SURFACE-PROVENANCE

user/message returns its user message unchanged; a nonempty assistant/message returns the model message; tool/result returns its user-role result. An assistant with empty content carries usage but does not enter the transcript. The other 41 event types all return null.SESSION-SURFACE-PROJECTION

Without replacement, the projector folds only Surface nodes added since the prior call, making the work O(new nodes). When replace generation changes, it clears and rebuilds from the current node list. Each API call returns a fresh array snapshot while the inner Message objects remain shared frozen event data.SESSION-DERIVED-CACHE

After ordinary append, an empty assistant, and replacement, the tests construct a fresh Session from the complete events and require its derived result to deep-equal the live incremental cache. An earlier returned array must not grow when later events append. Dependencies are not installed, so this study reviewed but did not run the tests.SESSION-DERIVED-ORACLE-TEST

Every seed event is detached or adopted, frozen, and checked for envelope shape, request header shape, contiguous seq, and a legal Surface transition. Failure cannot leave half a Surface. Construction records seed length as firstLiveSeq and appends session/end-seed when the tail does not already contain it.SESSION-SEED-ACCEPTANCE

A fresh Session has no marker; an explicitly empty seed receives one; reopening a seed that already ends with the marker does not append another. The seed prefix remains unchanged and derived Messages match the original Session.SESSION-SEED-REPLAY-TEST

SESSION_FORMAT_VERSION is fixed at 0 in this baseline. Breaking changes to the Header, envelope, core semantics, or Surface mechanism should bump it; this baseline has no upgrade chain or migration and rejects a different version. An ordinary new event theoretically need not bump the format because the envelope has ignorable.SESSION-FORMAT-HEADER

After persistence normalization, the loader checks the whole log against the generated known catalog. An unknown required event produces SessionFormatUnsupportedError; an unknown event marked ignorable:true remains in the loaded log so a consumer that understands it can still read it.SESSION-UNKNOWN-EVENT-GATESESSION-UNKNOWN-EVENT-TEST

The companion replays a trace from the existing log. On internal/dispatch, a new candidate creates only a staged transition; state advances only when the real session/event arrives. A later precommit-listener veto therefore cannot move invariant state ahead of the log.SESSION-RELATIONAL-INVARIANTSESSION-INVARIANT-COMMIT

This chapter rechecked the types, production append, Surface, and invariant control flow, the generated vocabulary, and test source. Upstream dependencies are not installed, so every test section describes the contract encoded by tests rather than a local execution result. The next chapter follows raw logs, forks, repair, history, and client replay on top of this event model.