Takes a message history and a character budget and returns a shortened history together with a full account of what it cost. Four stages run in fixed order: pin protects messages that must survive (roles listed in keep_roles, the last keep_last_n messages, and anything you marked pin), dedupe removes later near-duplicates of an earlier message of the same role using word-overlap similarity, trim shortens unprotected survivors to max_message_chars at the last sentence boundary, and drop removes…

Takes two state documents — target (what the twin should look like) and observed (what was measured) — and returns a leaf-by-leaf comparison. Every leaf path carries one of five states: in_tolerance, out_of_tolerance, missing_in_observed, unexpected_in_observed or type_mismatch.