Retain user instructions in guardian thread context (#42762)

## Why

Guardian review needs the original user instructions alongside verified answers, even after compaction, resume, or rollback. A summarized or legacy checkpoint cannot establish a complete instruction history.

## What changed

- Capture text user messages in retained context when `guardian_thread_context` is enabled, preserving their message identity through compaction and replay.
- Keep retained instructions and verified answers in arrival order, with independent size and completeness tracking for each family.
- Roll back retained evidence at the exact user-message boundary, including steers that share a turn ID, and apply the same semantics during rollout migration.
- Treat checkpoints without retained user messages as incomplete while preserving their verified answers.

## Testing

- Cover capture, compaction, resume, rollback, child forks, legacy checkpoints, storage bounds, and rollout migration.

GitOrigin-RevId: 72706731b54e5ac8645db61b446d2401afb42235
This commit is contained in:
felixxia-oai authored and copyberry committed 2026-09-04 13:24:42 +00:00
1 parent cc4b8bdeb8
commit 80d7ca34bc
18 files changed
+1058 -103

No files matched your search

+190 -29
View File
@@ -7,9 +7,9 @@ use schemars::JsonSchema;
use serde::Deserialize;
use serde::Serialize;
const MAX_ANSWERS: usize = 8;
const MAX_ANSWER_BYTES: usize = 16_384;
const MAX_ANSWERS_BYTES: usize = 65_536;
const MAX_FAMILY_RECORDS: usize = 8;
const MAX_RECORD_BYTES: usize = 16_384;
const MAX_FAMILY_BYTES: usize = 65_536;
/// Original assistant question and host-verified user reply, never an inferred permission.
#[derive(Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
@@ -27,6 +27,39 @@ pub struct VerifiedAnswer {
pub questions: Vec<VerifiedQuestionAnswer>,
}
/// Original user instruction, retained outside model summarization for delegated review.
/// Non-text input is not reconstructed as text; missing evidence remains explicit.
#[derive(Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct RetainedUserMessage {
pub turn_id: String,
pub message_id: Option<String>,
pub text: String,
pub complete: bool,
}
impl std::fmt::Debug for RetainedUserMessage {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("RetainedUserMessage")
.field("complete", &self.complete)
.finish_non_exhaustive()
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
struct Ordered<T> {
#[serde(default)]
order: u64,
#[serde(flatten)]
value: T,
}
/// Borrowed host evidence in original arrival order, across retained families.
pub enum RetainedContextEntry<'a> {
UserMessage(&'a RetainedUserMessage),
VerifiedAnswer(&'a VerifiedAnswer),
}
impl std::fmt::Debug for VerifiedAnswer {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
@@ -47,9 +80,44 @@ pub enum RetainedContextEvent {
/// Facts live until their source instruction is rolled back; compaction does not expire them.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct RetainedContext {
verified_answers: VecDeque<VerifiedAnswer>,
verified_answers: VecDeque<Ordered<VerifiedAnswer>>,
/// Lost evidence cannot be treated as a complete authorization history.
incomplete: bool,
#[serde(rename = "incomplete")]
verified_answers_incomplete: bool,
#[serde(default)]
user_messages: VecDeque<Ordered<RetainedUserMessage>>,
/// Old checkpoints did not preserve user restrictions for delegated review.
#[serde(default = "legacy_user_messages_incomplete")]
user_messages_incomplete: bool,
#[serde(default)]
next_order: u64,
}
fn legacy_user_messages_incomplete() -> bool {
true
}
fn bound_family<T: Serialize>(items: &mut VecDeque<Ordered<T>>, incomplete: &mut bool) {
while items.len() > MAX_FAMILY_RECORDS
|| serde_json::to_vec(items).map_or(true, |bytes| bytes.len() > MAX_FAMILY_BYTES)
{
items.pop_front();
*incomplete = true;
}
}
impl RetainedUserMessage {
fn bound(&mut self) {
if serde_json::to_vec(self).map_or(true, |bytes| bytes.len() > MAX_RECORD_BYTES) {
self.text.clear();
self.complete = false;
self.turn_id
.truncate(self.turn_id.floor_char_boundary(1_024));
if let Some(id) = &mut self.message_id {
id.truncate(id.floor_char_boundary(1_024));
}
}
}
}
impl RetainedContextEvent {
@@ -57,7 +125,7 @@ impl RetainedContextEvent {
pub fn bound(&mut self) {
match self {
Self::VerifiedAnswer(answer) => {
if serde_json::to_vec(answer).map_or(true, |bytes| bytes.len() > MAX_ANSWER_BYTES) {
if serde_json::to_vec(answer).map_or(true, |bytes| bytes.len() > MAX_RECORD_BYTES) {
answer.questions.clear();
// IDs are correlation metadata, not model-visible authorization text.
answer
@@ -74,15 +142,67 @@ impl RetainedContextEvent {
impl RetainedContext {
pub fn verified_answers(&self) -> impl DoubleEndedIterator<Item = &VerifiedAnswer> {
self.verified_answers.iter()
self.verified_answers.iter().map(|entry| &entry.value)
}
pub fn is_complete(&self) -> bool {
!self.incomplete
pub fn verified_answers_complete(&self) -> bool {
!self.verified_answers_incomplete
&& self
.verified_answers
.iter()
.all(|answer| !answer.questions.is_empty())
.all(|answer| !answer.value.questions.is_empty())
}
pub fn user_messages_complete(&self) -> bool {
!self.user_messages_incomplete
&& self
.user_messages
.iter()
.all(|message| message.value.complete)
}
/// A skipped instruction leaves a gap that later checkpoints must preserve.
pub fn mark_user_messages_incomplete(&mut self) {
self.user_messages_incomplete = true;
}
pub fn ordered_entries(&self) -> impl DoubleEndedIterator<Item = RetainedContextEntry<'_>> {
let mut entries = self
.verified_answers
.iter()
.map(|entry| {
(
entry.order,
RetainedContextEntry::VerifiedAnswer(&entry.value),
)
})
.chain(
self.user_messages
.iter()
.map(|entry| (entry.order, RetainedContextEntry::UserMessage(&entry.value))),
)
.collect::<Vec<_>>();
entries.sort_by_key(|(order, _)| *order);
entries.into_iter().map(|(_, entry)| entry)
}
/// Records the already-persisted user item; checkpoint/suffix replay uses this same path.
pub fn record_user_message(&mut self, mut message: RetainedUserMessage) {
message.bound();
if let Some(index) = self.user_messages.iter().position(|entry| {
message.message_id.is_some() && entry.value.message_id == message.message_id
}) {
if self.user_messages[index].value == message {
return;
}
self.user_messages.remove(index);
}
self.user_messages.push_back(Ordered {
order: self.next_order,
value: message,
});
self.next_order = self.next_order.saturating_add(1);
bound_family(&mut self.user_messages, &mut self.user_messages_incomplete);
}
/// Same-event delivery is idempotent; changed contents replace that source's record.
@@ -92,40 +212,81 @@ impl RetainedContext {
match event {
RetainedContextEvent::VerifiedAnswer(answer) => {
if let Some(index) = self.verified_answers.iter().position(|existing| {
existing.turn_id == answer.turn_id && existing.call_id == answer.call_id
existing.value.turn_id == answer.turn_id
&& existing.value.call_id == answer.call_id
}) {
if self.verified_answers[index] == answer {
if self.verified_answers[index].value == answer {
return false;
}
self.verified_answers.remove(index);
}
self.verified_answers.push_back(answer);
while self.verified_answers.len() > MAX_ANSWERS
|| serde_json::to_vec(&self.verified_answers)
.map_or(true, |bytes| bytes.len() > MAX_ANSWERS_BYTES)
{
self.verified_answers.pop_front();
self.incomplete = true;
}
self.verified_answers.push_back(Ordered {
order: self.next_order,
value: answer,
});
self.next_order = self.next_order.saturating_add(1);
bound_family(
&mut self.verified_answers,
&mut self.verified_answers_incomplete,
);
}
}
true
}
/// Restoring a saved thread must not bypass the live storage limits.
pub fn restore(&mut self, checkpoint: &Self) {
*self = Self {
incomplete: checkpoint.incomplete,
/// A missing checkpoint cannot establish complete historical user instructions.
pub fn restore(&mut self, checkpoint: Option<&Self>) {
*self = checkpoint.cloned().unwrap_or_else(|| Self {
user_messages_incomplete: true,
..Self::default()
};
for answer in &checkpoint.verified_answers {
self.record(&RetainedContextEvent::VerifiedAnswer(answer.clone()));
});
for entry in &mut self.verified_answers {
let mut event = RetainedContextEvent::VerifiedAnswer(entry.value.clone());
event.bound();
let RetainedContextEvent::VerifiedAnswer(answer) = event;
entry.value = answer;
self.next_order = self.next_order.max(entry.order.saturating_add(1));
}
for entry in &mut self.user_messages {
entry.value.bound();
self.next_order = self.next_order.max(entry.order.saturating_add(1));
}
bound_family(
&mut self.verified_answers,
&mut self.verified_answers_incomplete,
);
bound_family(&mut self.user_messages, &mut self.user_messages_incomplete);
}
/// Retains facts whose sources survive a lifecycle change. Compaction alone is not removal.
pub fn retain_answers(&mut self, keep: impl FnMut(&VerifiedAnswer) -> bool) {
self.verified_answers.retain(keep);
/// Keeps legacy answers whose source calls survive when no retained instruction boundary exists.
pub fn retain_answers(&mut self, mut keep: impl FnMut(&VerifiedAnswer) -> bool) {
self.verified_answers.retain(|answer| keep(&answer.value));
}
/// Rolls back at the original user-message boundary, including facts delivered after it.
/// Steering can share a turn ID. Legacy sources without message identity fall back to
/// source-turn removal and cannot establish complete retained user instructions.
pub fn rollback(&mut self, turn_ids: &[&str], first_removed_message_id: Option<&str>) {
if let Some(order) = first_removed_message_id.and_then(|id| {
self.user_messages
.iter()
.find(|message| message.value.message_id.as_deref() == Some(id))
.map(|message| message.order)
}) {
self.verified_answers.retain(|entry| entry.order < order);
self.user_messages.retain(|entry| entry.order < order);
return;
}
self.user_messages_incomplete |= first_removed_message_id.is_some()
|| self
.user_messages
.iter()
.any(|message| turn_ids.contains(&message.value.turn_id.as_str()));
self.verified_answers
.retain(|answer| !turn_ids.contains(&answer.value.turn_id.as_str()));
self.user_messages
.retain(|message| !turn_ids.contains(&message.value.turn_id.as_str()));
}
}