# RFC 0002: Message, Stream, and Event Model - **Status:** accepted for preview - **Stability:** pre-1.0 with versioned persistence/transport encodings ## Message and model values Messages have a stable validated ID, role, and bounded ordered content parts. Parts represent provider-neutral text, tool calls, and tool results. Constructors deep-copy byte slices and accessors return copies; mutable JSON supplied by a caller can never mutate an in-flight request. A model request carries a host-issued operation ID, model name, immutable message history, and immutable tool definitions. Streams are strict tagged unions: text delta, finalized tool call, completion with usage/metadata, or typed failure. Empty, contradictory, oversized, duplicate, or post-terminal items fail. Provider-specific safe facts use count/byte-bounded namespaced JSON. Namespaces must be explicitly allowlisted by engine composition before metadata enters events. Credentials, headers, prompt/tool content, arbitrary provider payloads, and secrets are prohibited even when they fit the byte bound. Provider start and receive failures carry a bounded typed problem. The host tracks whether any valid stream item has been observed and computes retry position; adapters cannot incorrectly label a partial stream as pristine. ## Event lifecycle An event contains one immutable run ID, strictly increasing sequence, engine- clock timestamp, stable kind, and bounded canonical JSON payload. Every committed Run/Turn/Model/Tool/Interaction Started event receives exactly one matching Completed, Failed, or Cancelled terminal. Cancellation preserves history and no replay or import operation renumbers committed events. Tool infrastructure failures carry a tool-specific payload with the active call ID, canonical tool name, bounded error text, and—when supplied by a valid typed execution failure—its definitive/uncertain outcome and retry disposition. This correlation is retained even when execution terminates the turn and run. ## Authoritative replay Each run owns one count-and-encoded-byte-bounded authoritative in-memory log. Retention eviction is oldest-first and terminal events receive reserved capacity. A subscriber atomically captures retained entries after a cursor and joins the live tail while the log lock is held, preventing a replay/live gap. Each subscription has independent count/byte queue bounds. A slow consumer is terminated rather than blocking execution. Typed errors contain the requested, earliest/latest, recovery cursor, last delivered sequence, and configured bounds needed by daemon/client recovery. ## Observer ordering The local log commits first. Required observers are called in deterministic construction order and may backpressure within the operation context. A nil return acknowledges durable acceptance according to that observer's documented contract. An error may follow a partial external side effect, but the local sequence remains committed and is never reused. Best-effort observers receive an event only after every required observer acknowledges it. They use bounded queues, count drops, cannot block execution, and close without send/close races. ## Encoding and compatibility Event kind and typed payload contracts are additive within a protocol major version. Unknown optional data is retained or ignored according to the protocol RFC; unknown lifecycle kinds cannot be guessed. Persistence snapshots record their schema version and last committed sequence rather than serializing Go private fields. ## Rejected alternatives - One shared event channel loses reconnect/replay and lets one client starve all others. - Unbounded histories and subscriber queues convert a slow UI into process OOM. - Publishing best-effort observers before durable observers lets telemetry claim an event that durability rejected. - Reusing a sequence after an observer error creates ambiguous external history. - Raw provider event passthrough leaks churn and potentially secrets. ## Acceptance Table, race, and fuzz tests cover message immutability, malformed stream unions, partial failures, all lifecycle terminals, required-observer partial failure, retention boundaries, cursor recovery, slow consumers, cancellation, shutdown, and byte-identical event reconstruction.