Struct TruncationPolicy 

pub struct TruncationPolicy {
    pub max_bytes: usize,
    pub head_ratio: HeadRatio,
    pub alignment: TruncationAlignment,
    pub marker_template: Option<String>,
    pub spill_sink: Option<Arc<dyn OutputSpillSink>>,
}

Configuration policy for middle-out string truncation.

Fields

max_bytes: usize

Maximum allowed bytes in the truncated output.

head_ratio: HeadRatio

Ratio of available content budget assigned to the head portion. Default is 50/50 balance between head and tail.

alignment: TruncationAlignment

Alignment boundary strategy.

marker_template: Option<String>

Optional custom marker template.

spill_sink: Option<Arc<dyn OutputSpillSink>>

Optional spill sink for retaining full un-truncated observations.

Implementations

impl TruncationPolicy

pub const fn new(max_bytes: usize) -> Self

Create a new truncation policy with a specified max_bytes ceiling, balanced 50/50 head-tail ratio, and character boundary alignment.

pub fn with_head_ratio(self, ratio: impl Into<HeadRatio>) -> Self

Set the head budget ratio.

pub const fn with_alignment(self, alignment: TruncationAlignment) -> Self

Set the boundary alignment strategy.

pub fn with_marker(self, marker: impl Into<String>) -> Self

Set a custom marker template.

Placeholders {omitted_bytes}, {original_bytes}, {offset_start}, {offset_end}, and {ref} will be substituted. Legacy aliases {count}, {bytes}, and <N> are also supported.

pub fn with_spill_sink(self, sink: Arc<dyn OutputSpillSink>) -> Self

Set a spill sink for retaining un-truncated observations.

pub fn format_marker(&self, omitted_bytes: usize) -> String

Format the marker string for the given omitted bytes without sink reference.

Preserved for backwards compatibility with existing callers.

pub fn format_marker_detailed( &self, omitted_bytes: usize, original_bytes: usize, offset_start: usize, offset_end: usize, spill: &SpillDisposition, ) -> String

Format marker with full metadata substitutions including offsets and spill disposition.

When spill is SpillDisposition::Failed, the rendered marker always carries an in-band warning that the omitted bytes are unrecoverable — including for custom templates that do not mention the failure themselves — so retention loss can never pass unnoticed by the model reading the output.

pub fn truncate<'a>(&self, input: &'a str) -> Cow<'a, str>

Truncate input using this policy, returning a borrowed Cow when no truncation is needed, or an owned string when middle-out truncation occurs.

If a configured OutputSpillSink fails, this method does not fail: the error is logged and rendered into the truncation marker, so the loss of the omitted bytes is visible to both the operator and the model. Callers that need to handle spill failure programmatically should use TruncationPolicy::truncate_detailed, which returns the SpillError.

pub fn truncate_lossy_with_context<'a>( &self, input: &'a str, ctx: &SpillContext<'_>, ) -> TruncationOutcome<'a>

Infallible truncation that degrades visibly — rather than failing — when a configured OutputSpillSink returns an error.

pub fn truncate_detailed<'a>( &self, input: &'a str, ) -> Result<TruncationOutcome<'a>, SpillError>

Truncate input using an anonymous spill context, returning a detailed TruncationOutcome.

Errors

Returns SpillError if an OutputSpillSink is configured and fails.

pub fn truncate_detailed_with_context<'a>( &self, input: &'a str, ctx: &SpillContext<'_>, ) -> Result<TruncationOutcome<'a>, SpillError>

Truncate input with caller-provided SpillContext, returning a detailed TruncationOutcome.

Errors

Returns SpillError if an OutputSpillSink is configured and fails.

Trait Implementations

impl Clone for TruncationPolicy

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TruncationPolicy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for TruncationPolicy

impl PartialEq for TruncationPolicy

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.