docs: the governing principle — every LLM request is reconstructable from the session log
The reconstructability RFC is the principle's home: model-visible ⟺ logged in both forms, the mechanism (boundary derivation + header fold), the enforcement (write-time round-trip guard, the dev invariant), the corollaries ranked (prefix-cache stability first), the MiniCode lineage with the provenance arrow inverted, and the alternatives it beat — including the stateful transmission client whose three-design archaeology lives in PR #162. Placements per the one-home-per-fact taxonomy: a standing-order line in root AGENTS.md (with displacement trims to stay inside the 1,575-word ceiling), the principle statement in architecture.md § Session Log and its Turn Flow lines (condensed to the ratcheted 1,630 ceiling), the request-envelope section in core-data-structures/core.md with the LlmCallConfig paste, both review-requested FIXMEs (FIXME(call-config-shape) beside the type, FIXME(catalog-verbs) at the catalog's drift-gate note), cookbook rows redirected off agent/request (tool filtering → system-prompt/assemble, plan-mode prompt → sections/ inject()), and the llm/stream JSDoc stating the frozen-request contract. RFC index and all generated catalogs regenerated.
This commit is contained in:
@@ -71,8 +71,8 @@ forever:
|
||||
assemble system prompt and tool schemas
|
||||
agent/pre-step
|
||||
'step/start'
|
||||
derive messages from the session log
|
||||
agent/request -> llm/stream
|
||||
snapshot the derived messages (the reconstruction boundary)
|
||||
agent/request (config only) -> log request/header -> llm/stream (frozen)
|
||||
'assistant/chunk'
|
||||
agent/step-result
|
||||
'assistant/message'
|
||||
@@ -108,6 +108,8 @@ Every session event is turn-enclosed. Reloading a crashed session preserves the
|
||||
|
||||
The session log is the source of truth. `deriveMessages()` projects session events into the `Message[]` sent to the model; raw `assistant/chunk` events stay in the log for replay and UI fidelity. Replay, fork, resume, transcript rendering, telemetry, and persistence all derive from the same event stream.
|
||||
|
||||
**Model-visible ⟺ logged**: the log reconstructs every conversation request byte-for-byte — messages by derivation at the `step/start` boundary, the header (system prompt, tools, model + sampling) by folding `request/header` events — asserted per request by the dev invariant ([reconstructability RFC](rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)).
|
||||
|
||||
Durability is a plugin concern. Persistence backends buffer synchronous `session/event` notifications and the loop awaits a turn-end checkpoint before moving on. The `SessionPersistence` seam stores `SessionEvent` directly, with metadata in `SessionHeader`; JSONL and SQLite share one contract suite.
|
||||
|
||||
### Model Content
|
||||
|
||||
Reference in New Issue
Block a user