Document appended request messages

docs/internal/llm.md

@@ -21,8 +21,9 @@ uses internal domain values for rendered prompts, execution targets,
 structured output, responses, and token usage.
 
 The runner supplies a fully resolved target after applying backend, profile,
-and request precedence. The client uses its endpoint, credential metadata,
-generation fields, and extra parameters. `BackendID` remains routing metadata
+and request precedence, plus canonical provider-bound text messages. The
+client uses its endpoint, credential metadata, generation fields, and extra
+parameters. `BackendID` remains routing metadata
 for the generation boundary and is not mapped into the provider payload.
 
 Construction trims and validates a nonempty configured base URL and clones any

docs/internal/runner.md

@@ -84,7 +84,8 @@ profile, or backend:
    schema metadata from it when required;
 2. load and hash input artifacts;
 3. render messages and the prompt-defined session;
-4. apply any direct session ID;
+4. apply any direct session ID, then append already-normalized request messages
+   after the rendered definition messages;
 5. hash the effective rendered prompt; and
 6. construct the prepared value and preparation timing.
 
@@ -113,7 +114,10 @@ the prompt session template, and is applied after ordinary message rendering.
 A blank direct value retains prompt-template behavior. The runner clears the
 template only on a value copy of the definition, so the definition hash always
 describes the original source while the rendered-prompt hash includes the
-effective direct or rendered session.
+effective direct or rendered session and the complete effective message
+sequence. The rendered-prompt hash uses a versioned, length-framed SHA-256
+encoding of that session, every role and content value, and cache-control
+presence and values; its hexadecimal value is opaque.
 
 The registry is read-only after engine construction. Concurrent `Prepare` and
 `Run` calls resolve independent defensive backend values and keep all
@@ -146,9 +150,10 @@ each actual generation call.
 
 After a failed `basic`, JSON, or JSON Schema validation with a positive frozen
 budget, the installed repairer can make a bounded corrective call. Each request
-starts with a fresh copy of the complete original rendered messages, includes
-only the latest nonempty candidate as an assistant message, and appends one
-corrective user message. Empty candidates omit that assistant message. The
+starts with a fresh copy of the complete effective message sequence (the
+configured prefix followed by the request suffix), includes only the latest
+nonempty candidate as an assistant message, and appends one corrective user
+message. Empty candidates omit that assistant message. The
 correction carries validation diagnostics as JSON data bounded to 64 KiB; the
 full diagnostics remain in the validation result.
 

docs/internal/sources.md

@@ -21,6 +21,12 @@ paths, content opening, and root containment. Each lookup remains a
 point-in-time scan: definitions and catalogs are not cached, and file-backed
 message content is opened only for the exact selected candidate.
 
+Message roles are normalized through the shared domain owner by trimming
+Unicode whitespace and lowercasing. Only `developer`, `system`, `user`, and
+`assistant` are published; invalid roles remain selected prompt-definition
+failures rather than becoming request errors. Cache-control metadata uses the
+same shared domain normalization and defensive-copy rule.
+
 Operating-system sources enforce containment against canonical roots and
 targets so symlinks cannot escape. Injected `fs.FS` sources enforce containment
 in their clean relative path namespace. A single-file source uses the selected
@@ -122,8 +128,9 @@ Session and message parsing and execution remain synchronous. The renderer
 checks cancellation before and after each parse and execution boundary,
 between artifact conversion chunks, around each message, and before publishing
 the complete prompt. It cannot interrupt template work already in progress and
-never publishes a partial prompt after observing cancellation. It carries
-message roles, session IDs, and cache control into the rendered prompt. The
+never publishes a partial prompt after observing cancellation. It validates and
+canonicalizes message roles before carrying roles, session IDs, and cache
+control into the rendered prompt. The
 [renderer tests](../../internal/prompt/renderer_test.go) own rendering behavior.
 
 ## Schemas And Output Validation