@@ -95,6 +95,8 @@ and hardware sections of the preparation guide.
 
 For sampling or frontend metadata changes, also read
 [sampling and frontend metadata](docs/model-development.md#sampling-and-frontend-metadata).
+Model onboarding and changes to tokenizers, chat templates, or native prompt
+encoders must satisfy the [renderer contract and validation requirements](docs/model-development.md#prompt-renderers-and-checkpoint-boundaries).
 
 ## Build and run model checkpoints
 
 
@@ -1078,13 +1078,17 @@ retain the first failure, and a failed CUDA drain retains the graph and buffer o
 ### Native frontend dependencies
 
 Helios uses Axum/Tokio for HTTP, Hugging Face `tokenizers` for tokenization,
-and MiniJinja with Python-method compatibility for chat templates. Dependency
-versions and features are specified in [Cargo.toml](../helios/Cargo.toml).
-The [template renderer](../helios/src/frontend/mod.rs) supplies Python-compatible
-JSON formatting, whitespace handling, and template exceptions. Rendering must
-match the recipe's canonical template bytes and token IDs, including tool schemas
-and image content. Recipes normally use the checkpoint template; Gemma 4 uses
-Google's canonical templates across quantization publishers as specified in
+and its compiled Jinja VM or a native encoder for prompt rendering. MiniJinja is
+a development-only differential and benchmark reference. Dependency versions and
+features are specified in [Cargo.toml](../helios/Cargo.toml).
+The [native frontend](../helios/src/frontend/mod.rs) preserves the authoritative
+renderer's prompt bytes, token IDs, tool serialization, and image order. Jinja
+evaluation supplies Python-compatible JSON formatting, whitespace handling, and
+template exceptions. Model integrations must satisfy the
+[renderer contract and validation requirements](model-development.md#prompt-renderers-and-checkpoint-boundaries).
+
+Recipes normally use the checkpoint template. Gemma 4 uses Google's canonical
+templates across quantization publishers as specified in
 [frontend metadata](model-development.md#sampling-and-frontend-metadata).
 
 The [native image processor](../helios/src/frontend/images/mod.rs) is checked
@@ -1348,16 +1352,21 @@ Only consumed history can define a checkpoint.
 
 ### Exact endpoint capture
 
-The shared frontend renders each message prefix without a generation header or
-assistant continuation. It accepts every nonempty rendered token sequence that
-is a strict prefix of the complete prompt, irrespective of message roles. A
-prefix may contain a template-generated preamble or end after any system,
-developer, user, assistant, or tool message. Templates can reject an incomplete
-conversation after emitting a complete prefix; only emitted tokens matching the
-validated full prompt are eligible. Context-dependent rendering that changes
-previous tokens cannot create a checkpoint for that prefix. Equal endpoints are
-deduplicated. Image placeholder expansion shifts endpoints to their positions in
-the prepared token stream; no endpoint may split an atomic image span.
+The shared frontend renders the complete normalized conversation once. Annotated
+Jinja templates record zero-output byte marks, segmented templates record counts
+of completed segments, and native encoders record normalized-message byte ends
+as they append output. Completed preambles and messages of every supported role
+are eligible; the open assistant generation header is excluded.
+
+Shared mapping converts those positions through the full prompt encoding's
+untrimmed token offsets. An exact cut requires every preceding token to end at
+or before it and every following token to start at or after it. BPE tokens
+crossing a mark and overlapping Unicode spans cannot create partial-token cuts.
+Continuation truncation excludes later positions. Token endpoints are sorted,
+deduplicated, and strictly inside the prompt. Image placeholder expansion shifts
+them into the prepared token stream without splitting atomic image spans. Cache
+reuse depends on the actual prepared prefix identity; context-dependent changes
+to earlier tokens cannot reuse a checkpoint for different tokens.
 
 Endpoints are not rounded to token groups or KV pages. The scheduler obtains a
 snapshot destination when it reaches an endpoint, using normal cache eviction.
 
@@ -61,6 +61,148 @@ templates do not select rendering behavior. Helios normalizes JSON-string tool
 arguments into objects before rendering. Tests compare the assets with the pinned
 Google sources and exercise prompt bytes, reasoning, tool rounds, and cache boundaries.
 
+## Prompt renderers and checkpoint boundaries
+
+Every model integration must provide prompt rendering, tokenization, image
+ordering, and reusable-prefix endpoints through the shared native frontend.
+These requirements apply to text Jinja, segmented Jinja, and programmatic Rust
+encoders. A plausible generated answer does not establish frontend correctness.
+Follow the [frontend metadata contract](../helios/model-contract.md#frontend-implementations)
+and [native frontend interfaces](../helios/README.md#native-frontend).
+
+### Canonical prompt semantics
+
+- Identify the exact checkpoint tokenizer and authoritative template or encoder
+  revision. Preserve prompt bytes, token IDs, special-token treatment, whitespace,
+  tool serialization, reasoning history, generation headers, and continuation
+  behavior. A deliberate inference transformation needs an explicit semantic
+  requirement and independent reference tests.
+- Render the normalized conversation supplied by the shared request path.
+  Protocol decoding, instruction lowering, and tool-result normalization belong
+  in shared code. Renderer selection describes prompt syntax; it must not select
+  scheduling, cache policy, or model execution behavior.
+- Return image sources in the same order as their rendered placeholders. If
+  normalization reorders tool results, move each result's images with its text.
+  Preserve the tokenizer's distinction between ordinary text and special tokens,
+  including literal special-token spellings in user and tool content.
+- Explicit request options override packaged defaults. Validate unsupported
+  options and malformed content explicitly. Preserve previously exported
+  packages' renderer selection, absent-field defaults, and packaged semantics.
+
+### Complete-message endpoints
+
+- Render the conversation once and record endpoints while producing its output.
+  Tokenize each required text or ordinary/special-token segment once. Do not
+  recover boundaries by rendering or tokenizing every conversation prefix,
+  searching for message text, or inserting marker text into the prompt.
+- Record the completed preamble and every completed normalized message in output
+  order, including system, assistant, and tool messages where supported. A merged
+  user run has the endpoint of the merged message; reordered results have
+  endpoints in rendered order. Include closing wrappers and separators belonging
+  to a completed message, and exclude the open assistant generation header.
+- Text renderers report UTF-8 byte positions, not character counts or token IDs;
+  segmented Jinja reports segment counts as specified below. Shared boundary
+  mapping uses the full encoding's untrimmed offsets and accepts
+  an exact cut only when every preceding token ends at or before it and every
+  following token starts at or after it. Omit an exact cut crossed by a BPE token
+  or overlapping Unicode spans; do not round it to a nearby token or cache page.
+- The frontend's final token endpoints must be sorted, unique, and strictly
+  inside the prompt. Continuation truncation must exclude later endpoints. Image
+  expansion must shift endpoints with the token stream without splitting an
+  atomic image span. The scheduler owns prompt/terminal checkpoints and complete
+  state capture; renderers supply positions, not cache-management instructions.
+
+### Jinja integration
+
+- Package an annotated recipe template. Removing its mark annotations must
+  reproduce the authoritative template bytes, including any explicitly supported
+  inference transformation. Preserve Jinja whitespace-control behavior and test
+  actual rendered output; source equality alone does not validate placement.
+- Text templates use `{% mark %}` to record a zero-output byte position.
+  Templates producing token segments use `{% mark expression %}`, where the
+  expression is the number of completed segments. For example,
+  `{% mark ns.segments | length %}` refers to segment entries, not bytes in the
+  serialized JSON representation. Preserve each segment's `allow_special` value.
+- Place marks at root output sites after a completed preamble or message.
+  Marks inside macros, captured assignments, or filter blocks are forbidden;
+  mark the root call site after the helper returns. Handle each output branch,
+  including tool-only messages and empty content with nonempty framing.
+- Verify the recipe exports the annotated asset and Helios loads it through the
+  shared compiler. Do not bypass the missing-annotation error or add a broad
+  template fallback. Compatibility substitutions must match the exact template
+  bytes of an existing supported package.
+
+### Programmatic encoder integration
+
+- Use the authoritative encoder where available. Expose normalized-message byte
+  endpoints from its actual append loop, and adapt them through the shared
+  tokenizer/boundary path. Avoid a parallel implementation of the encoder's
+  formatting or normalization solely to discover positions.
+- Carry positions through system insertion, adjacent-message merging, tool-result
+  sorting, and wrapper emission. Keep image sources, message text, and endpoint
+  ownership together through those operations. Both Jinja and native encoders
+  must satisfy the same complete-message and token-boundary invariants.
+- Maintain required upstream changes as focused commits in a pinned dependency
+  fork. Keep related crates' revisions and shared types coherent, preserve the
+  upstream license, and document dependency updates. Compare against the
+  independent upstream renderer when changing prompt behavior; calling the same
+  patched encoder through another adapter is not an independent reference.
+
+### Content-block checkpoint hints
+
+For requests carrying advisory block hints, every supported rendering mode must
+satisfy these requirements:
+
+- Decode protocol-specific fields into neutral message/block positions before
+  rendering. Hints must not alter prompt bytes, token IDs, image order, reasoning
+  state, or explicit request options, and must not reach model-visible output.
+  Requests from protocols that do not supply hints retain their ordinary behavior.
+- Preserve block identity through normalization and rendering. Carry positions
+  through byte-preserving concatenation, captures, macros, segment construction,
+  and trimming where their output positions remain defined. Repeated equal text
+  must not cause a hint to move to a different block. Never guess a position after
+  an unmappable transformation.
+- Cover text blocks, supported image blocks, and whole tool results. A tool-result
+  endpoint includes its closing wrapper; an image endpoint must survive atomic
+  image expansion. Text-only coverage does not establish image or segmented
+  renderer support. Report unsupported cases explicitly rather than silently
+  treating an accepted hint as implemented.
+- Keep advisory cuts distinct from exact message marks. A hint may use the last
+  safe complete-token prefix before its byte endpoint; it must not weaken exact
+  message-boundary validation or change scheduler/cache policy.
+- Preserve an unhinted path without hint-specific string copies or per-value
+  hint allocations. Measure unhinted latency and allocations when changing shared
+  rendering machinery; protocol-specific decoding alone does not isolate its cost.
+
+### Required validation
+
+1. Compare the production renderer with the pinned authoritative reference using
+   the actual template/encoder and checkpoint tokenizer. Check rendered bytes,
+   token IDs, image order, supported options, and expected errors. Exercise
+   system/developer lowering, user and assistant turns, reasoning on/off where
+   supported, tool choices, multiple/reordered results, and continuation.
+2. Test boundary behavior with empty and repeated content, UTF-8, whitespace/BPE
+   joins, merged users, wrappers, generation headers, and image expansion.
+   For block hints, include a stable history plus a changing suffix inside one
+   user message; assert the expected extra cut and identical hinted/unhinted
+   prompts. Exercise captures and macros with the real recipe template, and
+   segmented and image paths where supported. Synthetic tokenizers are useful
+   edge-case tests but do not establish checkpoint-tokenizer parity.
+3. Exercise the native request preparation used by each supported HTTP protocol
+   and load the exported package's frontend assets/settings. Validate older
+   packages when changing their loading or default semantics.
+4. Demonstrate repeated-prompt and changed-suffix cache reuse through the actual
+   service, including ordinary and speculative execution where supported. Check
+   consumed-prefix accounting and continuation correctness. Frontend CPU tests
+   alone do not establish runtime cache reuse or a serving performance gain.
+   Report missing checkpoints, unrun hardware paths, and skipped tests explicitly.
+
+Use [frontend fixtures](../tests/frontend),
+[native boundary tests](../helios/tests/message_boundaries.rs),
+[native encoder/request tests](../helios/tests/deepseek_requests.rs), and
+[HTTP protocol tests](../tests/server/test_protocols.py) as starting points.
+Keep ordinary tests and measurements; do not add development audit artifacts.
+
 ## Weight formats and arithmetic precision
 
 - **Read quantization from checkpoint metadata.** Use `config.json` declarations
 
@@ -38,7 +38,7 @@ blake2 = "0.10"
 libloading = "0.8.9"
 libc = "0.2.189"
 tokenizers = { version = "=0.23.2", default-features = false, features = ["onig"], optional = true }
-serde_json = { version = "1.0", features = ["preserve_order", "float_roundtrip"], optional = true }
+serde_json = { version = "1.0", features = ["preserve_order", "float_roundtrip", "raw_value"], optional = true }
 sha2 = { version = "0.10.9", optional = true }
 ryu = { version = "1.0", optional = true }
 png = { version = "0.18.1", optional = true }
 
@@ -432,6 +432,13 @@ token starts at or after it. Overlapping Unicode spans and BPE tokens crossing a
 create partial-token cuts. Token endpoints are sorted, unique, and strictly
 inside the prompt. Image expansion adjusts them with one ordered pass.
 
+Advisory content-block hints travel separately from prompt text. Text hints keep
+their positions through captured strings and JSON serialization; segmented
+templates map JSON string positions back to decoded segment bytes before token
+mapping. Image hints retain indices into the rendered image-source list and
+resolve to the ends of prepared image spans after expansion. Hints do not change
+prompt bytes, token IDs, image conditioning, or ordinary/special-token selection.
+
 `Frontend::encode`, `decode`, and `incremental_decoder` use Hugging Face's Rust
 tokenizers library pinned to the fixture environment's version. Incremental
 decoding preserves incomplete UTF-8 between chunks and flushes remaining bytes
 
@@ -221,7 +221,7 @@ fn main() {
             let expected = template.render(&context).unwrap();
             let iterations =
                 (50_000_000 / start.elapsed().as_nanos().max(1)).clamp(1, 5000) as usize;
-            let actual = compiled.render(context.as_object().unwrap()).unwrap();
+            let actual = compiled.render(context.as_object().unwrap(), &[]).unwrap();
             assert_eq!(actual.text, expected, "{name}/{case}");
             if check_only {
                 println!(
@@ -242,7 +242,7 @@ fn main() {
             measure(&format!("owned,{name},{case}"), || {
                 black_box(
                     compiled
-                        .render(black_box(context.as_object().unwrap()))
+                        .render(black_box(context.as_object().unwrap()), &[])
                         .unwrap(),
                 );
             });
@@ -252,7 +252,7 @@ fn main() {
                 black_box(output);
             });
             concurrent(&format!("owned,{name},{case}"), iterations, || {
-                black_box(compiled.render(context.as_object().unwrap()).unwrap());
+                black_box(compiled.render(context.as_object().unwrap(), &[]).unwrap());
             });
         }
     }
 
@@ -20,6 +20,7 @@ pub(super) fn preserve_offsets(tokenizer: &mut Tokenizer) {
 
 pub(super) fn token_ends(
     bytes: &[usize],
+    hints: &[usize],
     offsets: &[(usize, usize)],
     text_len: usize,
 ) -> Result<Vec<usize>> {
@@ -38,19 +39,32 @@ pub(super) fn token_ends(
     for i in (0..offsets.len()).rev() {
         suffix_start[i] = suffix_start[i + 1].min(offsets[i].0);
     }
-    let mut result = Vec::with_capacity(bytes.len());
+    let mut cuts = Vec::with_capacity(bytes.len() + hints.len());
+    for &byte in bytes {
+        cuts.push((byte, false));
+    }
+    for &byte in hints {
+        if byte <= text_len {
+            cuts.push((byte, true));
+        }
+    }
+    if !hints.is_empty() {
+        cuts.sort_unstable();
+    }
+    let mut result = Vec::with_capacity(cuts.len());
     let mut tokens = 0;
     let mut prefix_end = 0;
-    for &byte in bytes {
+    for (byte, hint) in cuts {
         let byte = byte.min(text_len);
         while tokens < offsets.len() && prefix_end.max(offsets[tokens].1) <= byte {
             prefix_end = prefix_end.max(offsets[tokens].1);
             tokens += 1;
         }
-        // Overlapping offsets can represent several tokens for one Unicode scalar.
+        // Hints may floor a crossing token; overlapping Unicode spans still cannot split.
+        let boundary = if hint { prefix_end } else { byte };
         if tokens > 0
             && tokens < offsets.len()
-            && suffix_start[tokens] >= byte
+            && suffix_start[tokens] >= boundary
             && result.last() != Some(&tokens)
         {
             result.push(tokens);
@@ -66,18 +80,41 @@ mod tests {
     #[test]
     fn cuts_require_all_tokens_on_their_respective_side() {
         assert_eq!(
-            token_ends(&[0, 1, 2, 3, 4, 6], &[(0, 2), (2, 4), (2, 4), (4, 6)], 6).unwrap(),
+            token_ends(
+                &[0, 1, 2, 3, 4, 6],
+                &[],
+                &[(0, 2), (2, 4), (2, 4), (4, 6)],
+                6
+            )
+            .unwrap(),
             vec![1, 3]
         );
         assert_eq!(
-            token_ends(&[2, 3, 4, 5], &[(0, 2), (4, 5), (2, 4), (5, 6)], 6).unwrap(),
+            token_ends(&[2, 3, 4, 5], &[], &[(0, 2), (4, 5), (2, 4), (5, 6)], 6).unwrap(),
             vec![1, 3]
         );
         assert_eq!(
-            token_ends(&[2, 3, 4, 100], &[(0, 2), (4, 6)], 6).unwrap(),
+            token_ends(&[2, 3, 4, 100], &[], &[(0, 2), (4, 6)], 6).unwrap(),
             vec![1]
         );
-        assert!(token_ends(&[4, 2], &[(0, 2), (2, 6)], 6).is_err());
-        assert!(token_ends(&[2], &[(0, 7)], 6).is_err());
+        assert!(token_ends(&[4, 2], &[], &[(0, 2), (2, 6)], 6).is_err());
+        assert!(token_ends(&[2], &[], &[(0, 7)], 6).is_err());
+    }
+
+    #[test]
+    fn only_hint_cuts_floor_crossing_tokens() {
+        assert_eq!(
+            token_ends(&[3], &[3], &[(0, 2), (2, 5), (5, 6)], 6).unwrap(),
+            [1]
+        );
+        assert!(
+            token_ends(&[3], &[], &[(0, 2), (2, 5), (5, 6)], 6)
+                .unwrap()
+                .is_empty()
+        );
+        assert_eq!(
+            token_ends(&[], &[3, 7], &[(0, 2), (2, 4), (2, 4), (4, 6)], 6).unwrap(),
+            [1]
+        );
     }
 }