Skip to main content

glass_browser/
protocol.rs

1//! Transport-neutral Glass request and response envelopes.
2//!
3//! MCP keeps its JSON-RPC framing, but daemon clients and embedded callers use
4//! these envelopes for the operation payload. The envelope is intentionally
5//! small: transport-specific framing, streaming, and authentication remain
6//! outside this contract.
7use serde::{Deserialize, Serialize};
8use serde_json::Value;
9use std::collections::BTreeMap;
10
11/// Version of the canonical Glass operation envelope.
12pub const GLASS_PROTOCOL_VERSION: u32 = 1;
13const MAX_ID_BYTES: usize = 128;
14const MAX_OPERATION_BYTES: usize = 96;
15const MAX_ERROR_CODE_BYTES: usize = 64;
16const MAX_MESSAGE_BYTES: usize = 512;
17const MAX_ERROR_DETAILS_BYTES: usize = 16 * 1024;
18const MAX_DEADLINE_MS: u64 = 15 * 60 * 1_000;
19
20/// Canonical operation for browser-free Web IR validation.
21pub const WEB_IR_VALIDATE_OPERATION: &str = "webIr.validate";
22/// Canonical operation for browser-free Web IR inspection.
23pub const WEB_IR_INSPECT_OPERATION: &str = "webIr.inspect";
24/// Canonical operation for browser-free Web IR revision diffs.
25pub const WEB_IR_DIFF_OPERATION: &str = "webIr.diff";
26/// Canonical operation for browser-free Web IR continuity checks.
27pub const WEB_IR_CONTINUITY_OPERATION: &str = "webIr.continuity";
28/// Canonical operation for browser-free Task Protocol compilation.
29pub const TASK_COMPILE_OPERATION: &str = "task.compile";
30/// Canonical operation for browser-free Task Protocol validation.
31pub const TASK_VALIDATE_OPERATION: &str = "task.validate";
32/// Canonical operation for browser-backed Task Protocol execution.
33pub const TASK_EXECUTE_OPERATION: &str = "task.execute";
34
35/// Browser-free or live experience operations use these stable names in all
36/// supported transports.
37pub const EXPERIENCE_INSPECT_OPERATION: &str = "experience.inspect";
38pub const EXPERIENCE_EXTRACT_OPERATION: &str = "experience.extract";
39pub const EXPERIENCE_RESOLVE_OPERATION: &str = "experience.resolve";
40pub const EXPERIENCE_ACT_OPERATION: &str = "experience.act";
41pub const EXPERIENCE_VERIFY_OPERATION: &str = "experience.verify";
42pub const EXPERIENCE_CAPTURE_OPERATION: &str = "experience.capture";
43pub const EXPERIENCE_REPLAY_OPERATION: &str = "experience.replay";
44pub const EXPERIENCE_DIFF_OPERATION: &str = "experience.diff";
45pub const EXPERIENCE_ATTACH_OPERATION: &str = "experience.attach";
46
47/// Typed payload carried by a `task.compile` request.
48#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
49#[serde(rename_all = "camelCase", deny_unknown_fields)]
50pub struct TaskCompilePayload {
51    pub task: crate::task_protocol::GlassTask,
52    pub ir: crate::web_ir::GlassWebIrV1,
53}
54
55impl TaskCompilePayload {
56    /// Validate the authored task and source IR before compiler dispatch.
57    pub fn validate(&self) -> Result<(), ProtocolError> {
58        self.task
59            .validate()
60            .map_err(|error| ProtocolError::TaskCompilation(error.into()))?;
61        self.ir.validate().map_err(ProtocolError::WebIrValidation)
62    }
63}
64
65/// Typed payload carried by a browser-backed `task.execute` request.
66#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
67#[serde(rename_all = "camelCase", deny_unknown_fields)]
68pub struct TaskExecutionPayload {
69    pub task: crate::task_protocol::GlassTask,
70    pub expected_revision: u64,
71    #[serde(default)]
72    pub confirmed: bool,
73}
74
75impl TaskExecutionPayload {
76    /// Validate the authored task before browser session startup.
77    pub fn validate(&self) -> Result<(), ProtocolError> {
78        self.task.validate().map_err(ProtocolError::TaskValidation)
79    }
80}
81
82/// Typed payload carried by a `task.validate` request.
83#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
84#[serde(rename_all = "camelCase", deny_unknown_fields)]
85pub struct TaskValidationPayload {
86    pub task: crate::task_protocol::GlassTask,
87}
88
89impl TaskValidationPayload {
90    /// Validate the authored task before validation dispatch.
91    pub fn validate(&self) -> Result<(), ProtocolError> {
92        self.task.validate().map_err(ProtocolError::TaskValidation)
93    }
94}
95
96/// Typed payload carried by a `webIr.validate` or `webIr.inspect` request.
97#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
98#[serde(rename_all = "camelCase", deny_unknown_fields)]
99pub struct WebIrPayload {
100    pub ir: crate::web_ir::GlassWebIrV1,
101}
102
103impl WebIrPayload {
104    /// Validate the stable IR graph before browser-free dispatch.
105    pub fn validate(&self) -> Result<(), ProtocolError> {
106        self.ir.validate().map_err(ProtocolError::WebIrValidation)
107    }
108}
109
110/// Typed payload carried by a `webIr.diff` request.
111#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
112#[serde(rename_all = "camelCase", deny_unknown_fields)]
113pub struct WebIrDiffPayload {
114    pub before: crate::web_ir::GlassWebIrV1,
115    pub after: crate::web_ir::GlassWebIrV1,
116}
117
118impl WebIrDiffPayload {
119    /// Validate both Web IR revisions before diff dispatch.
120    pub fn validate(&self) -> Result<(), ProtocolError> {
121        self.before
122            .validate()
123            .map_err(ProtocolError::WebIrValidation)?;
124        self.after
125            .validate()
126            .map_err(ProtocolError::WebIrValidation)?;
127        self.before
128            .validate_revision_transition(&self.after)
129            .map_err(ProtocolError::WebIrValidation)?;
130        Ok(())
131    }
132}
133
134/// Typed payload carried by a `webIr.continuity` request.
135#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
136#[serde(rename_all = "camelCase", deny_unknown_fields)]
137pub struct WebIrContinuityPayload {
138    pub before: crate::web_ir::GlassWebIrV1,
139    pub after: crate::web_ir::GlassWebIrV1,
140    pub entity_id: String,
141}
142
143impl WebIrContinuityPayload {
144    /// Validate both Web IR revisions and the bounded source entity ID.
145    pub fn validate(&self) -> Result<(), ProtocolError> {
146        self.before
147            .validate()
148            .map_err(ProtocolError::WebIrValidation)?;
149        self.after
150            .validate()
151            .map_err(ProtocolError::WebIrValidation)?;
152        self.before
153            .validate_revision_transition(&self.after)
154            .map_err(ProtocolError::WebIrValidation)?;
155        validate_identifier(&self.entity_id, "entityId")
156    }
157}
158
159/// Typed successful result for a `task.compile` operation.
160#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
161#[serde(rename_all = "camelCase", deny_unknown_fields)]
162pub struct TaskCompileResult {
163    pub plan: crate::task_compiler::TaskExecutionPlan,
164}
165
166/// Typed successful result for browser-free Task Protocol validation.
167#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
168#[serde(rename_all = "camelCase", deny_unknown_fields)]
169pub struct TaskValidationResult {
170    pub valid: bool,
171    pub schema_version: u32,
172    pub task: crate::task_protocol::TaskKind,
173}
174
175/// Bounded successful result for browser-free Web IR validation.
176#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
177#[serde(rename_all = "camelCase", deny_unknown_fields)]
178pub struct WebIrValidationResult {
179    pub valid: bool,
180    pub schema_version: u32,
181    pub revision: u64,
182}
183
184impl WebIrValidationResult {
185    /// Build the validation result after an IR has passed graph validation.
186    pub fn from_ir(ir: &crate::web_ir::GlassWebIrV1) -> Self {
187        Self {
188            valid: true,
189            schema_version: ir.schema_version,
190            revision: ir.revision,
191        }
192    }
193}
194
195/// Bounded summary result for browser-free Web IR inspection.
196#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
197#[serde(rename_all = "camelCase", deny_unknown_fields)]
198pub struct WebIrInspectionResult {
199    pub schema_version: u32,
200    pub revision: u64,
201    pub entity_count: usize,
202    pub relationship_count: usize,
203    pub coverage: crate::extraction::EvidenceCoverage,
204    pub truncated: bool,
205    pub opaque_regions: u32,
206    pub diagnostic_count: usize,
207    pub relationship_hint_diagnostic_count: usize,
208    #[serde(default)]
209    pub entity_kind_counts: BTreeMap<String, usize>,
210    #[serde(default)]
211    pub actionable_entities: Vec<WebIrCompactEntity>,
212}
213
214#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
215#[serde(rename_all = "camelCase", deny_unknown_fields)]
216pub struct WebIrCompactEntity {
217    pub id: String,
218    pub kind: crate::web_ir::WebIrEntityKind,
219    #[serde(default, skip_serializing_if = "Option::is_none")]
220    pub role: Option<String>,
221    #[serde(default, skip_serializing_if = "Option::is_none")]
222    pub name: Option<String>,
223    pub sensitivity: crate::web_ir::WebIrSensitivity,
224    pub supported_actions: Vec<crate::web_ir::WebIrAction>,
225}
226
227impl WebIrInspectionResult {
228    /// Build a bounded summary after an IR has passed graph validation.
229    pub fn from_ir(ir: &crate::web_ir::GlassWebIrV1) -> Self {
230        let mut entity_kind_counts = BTreeMap::new();
231        for entity in &ir.entities {
232            let kind = serde_json::to_value(entity.kind)
233                .ok()
234                .and_then(|value| value.as_str().map(str::to_owned))
235                .unwrap_or_else(|| "unknown".into());
236            *entity_kind_counts.entry(kind).or_default() += 1;
237        }
238        let actionable_entities = ir
239            .entities
240            .iter()
241            .filter_map(|entity| {
242                let details = ir.entity_details.get(&entity.id)?;
243                (!details.supported_actions.is_empty()).then(|| WebIrCompactEntity {
244                    id: entity.id.clone(),
245                    kind: entity.kind,
246                    role: entity.role.clone(),
247                    name: entity.name.clone(),
248                    sensitivity: details.sensitivity,
249                    supported_actions: details.supported_actions.clone(),
250                })
251            })
252            .take(16)
253            .collect();
254        Self {
255            schema_version: ir.schema_version,
256            revision: ir.revision,
257            entity_count: ir.entities.len(),
258            relationship_count: ir.relationships.len(),
259            coverage: ir.coverage.clone(),
260            truncated: ir.limits.truncated,
261            opaque_regions: ir.coverage.opaque_regions,
262            diagnostic_count: ir.diagnostics.len(),
263            relationship_hint_diagnostic_count: ir.relationship_hint_diagnostics.len(),
264            entity_kind_counts,
265            actionable_entities,
266        }
267    }
268}
269
270/// Bounded summary result for a browser-free Web IR revision diff.
271#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
272#[serde(rename_all = "camelCase", deny_unknown_fields)]
273pub struct WebIrDiffResult {
274    pub schema_version: u32,
275    pub from_revision: u64,
276    pub to_revision: u64,
277    pub entity_added_count: usize,
278    pub entity_removed_count: usize,
279    pub entity_changed_count: usize,
280    pub relationship_added_count: usize,
281    pub relationship_removed_count: usize,
282    pub coverage_changed: bool,
283    pub limits_changed: bool,
284    pub diagnostics_changed: bool,
285    pub relationship_hint_diagnostics_changed: bool,
286}
287
288impl WebIrDiffResult {
289    /// Build a bounded summary without exposing entity or page content.
290    pub fn from_diff(diff: &crate::web_ir::GlassWebIrDiff) -> Self {
291        Self {
292            schema_version: diff.schema_version,
293            from_revision: diff.from_revision,
294            to_revision: diff.to_revision,
295            entity_added_count: diff
296                .entity_changes
297                .iter()
298                .filter(|change| change.kind == crate::web_ir::WebIrChangeKind::Added)
299                .count(),
300            entity_removed_count: diff
301                .entity_changes
302                .iter()
303                .filter(|change| change.kind == crate::web_ir::WebIrChangeKind::Removed)
304                .count(),
305            entity_changed_count: diff
306                .entity_changes
307                .iter()
308                .filter(|change| change.kind == crate::web_ir::WebIrChangeKind::Changed)
309                .count(),
310            relationship_added_count: diff
311                .relationship_changes
312                .iter()
313                .filter(|change| change.kind == crate::web_ir::WebIrChangeKind::Added)
314                .count(),
315            relationship_removed_count: diff
316                .relationship_changes
317                .iter()
318                .filter(|change| change.kind == crate::web_ir::WebIrChangeKind::Removed)
319                .count(),
320            coverage_changed: diff.coverage_changed,
321            limits_changed: diff.limits_changed,
322            diagnostics_changed: diff.diagnostics_changed,
323            relationship_hint_diagnostics_changed: diff.relationship_hint_diagnostics_changed,
324        }
325    }
326}
327
328/// Browser-free Web IR continuity classification for one entity.
329#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
330#[serde(rename_all = "camelCase", deny_unknown_fields)]
331pub struct WebIrContinuityResult {
332    pub requested_id: String,
333    pub status: crate::web_ir::WebIrEntityContinuityStatus,
334    #[serde(skip_serializing_if = "Option::is_none")]
335    pub current_id: Option<String>,
336    pub reason: String,
337}
338
339impl From<crate::web_ir::WebIrEntityContinuity> for WebIrContinuityResult {
340    fn from(continuity: crate::web_ir::WebIrEntityContinuity) -> Self {
341        Self {
342            requested_id: continuity.requested_id,
343            status: continuity.status,
344            current_id: continuity.current_id,
345            reason: continuity.reason,
346        }
347    }
348}
349
350impl TaskCompileResult {
351    /// Validate the embedded deterministic execution plan.
352    pub fn validate(&self) -> Result<(), ProtocolError> {
353        self.plan.validate().map_err(ProtocolError::TaskCompilation)
354    }
355}
356
357/// A request-independent mutation lease reference.
358#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
359#[serde(rename_all = "camelCase", deny_unknown_fields)]
360pub struct MutationLeaseRef {
361    pub session_id: String,
362    pub token: String,
363}
364
365/// Canonical operation request shared by supported transports.
366#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
367#[serde(rename_all = "camelCase", deny_unknown_fields)]
368pub struct GlassRequest {
369    pub protocol_version: u32,
370    pub request_id: String,
371    #[serde(skip_serializing_if = "Option::is_none")]
372    pub correlation_id: Option<String>,
373    #[serde(skip_serializing_if = "Option::is_none")]
374    pub session_id: Option<String>,
375    #[serde(skip_serializing_if = "Option::is_none")]
376    pub mutation_lease: Option<MutationLeaseRef>,
377    pub operation: String,
378    pub payload: Value,
379    #[serde(skip_serializing_if = "Option::is_none")]
380    pub deadline_ms: Option<u64>,
381}
382
383impl GlassRequest {
384    /// Validate protocol version, identifiers, operation bounds, and deadline.
385    pub fn validate(&self) -> Result<(), ProtocolError> {
386        if self.protocol_version != GLASS_PROTOCOL_VERSION {
387            return Err(ProtocolError::UnsupportedVersion(self.protocol_version));
388        }
389        validate_identifier(&self.request_id, "requestId")?;
390        if let Some(correlation_id) = &self.correlation_id {
391            validate_identifier(correlation_id, "correlationId")?;
392        }
393        if let Some(session_id) = &self.session_id {
394            validate_identifier(session_id, "sessionId")?;
395        }
396        if let Some(lease) = &self.mutation_lease {
397            validate_identifier(&lease.session_id, "mutationLease.sessionId")?;
398            validate_identifier(&lease.token, "mutationLease.token")?;
399        }
400        if let (Some(session_id), Some(lease)) = (&self.session_id, &self.mutation_lease)
401            && session_id != &lease.session_id
402        {
403            return Err(ProtocolError::InvalidField(
404                "sessionId must match mutationLease.sessionId".into(),
405            ));
406        }
407        if self.operation.is_empty() || self.operation.len() > MAX_OPERATION_BYTES {
408            return Err(ProtocolError::InvalidField(
409                "operation must be a bounded non-empty string".into(),
410            ));
411        }
412        if self.operation.chars().any(char::is_whitespace) {
413            return Err(ProtocolError::InvalidField(
414                "operation must not contain whitespace".into(),
415            ));
416        }
417        if let Some(deadline_ms) = self.deadline_ms
418            && !(1..=MAX_DEADLINE_MS).contains(&deadline_ms)
419        {
420            return Err(ProtocolError::InvalidField(format!(
421                "deadlineMs must be 1..={MAX_DEADLINE_MS}"
422            )));
423        }
424        Ok(())
425    }
426
427    /// Decode and validate a typed `task.compile` payload.
428    pub fn decode_task_compile(&self) -> Result<TaskCompilePayload, ProtocolError> {
429        self.validate()?;
430        if self.operation != TASK_COMPILE_OPERATION {
431            return Err(ProtocolError::InvalidField(format!(
432                "expected operation {TASK_COMPILE_OPERATION}"
433            )));
434        }
435        let payload: TaskCompilePayload =
436            serde_json::from_value(self.payload.clone()).map_err(|error| {
437                ProtocolError::InvalidField(format!("task.compile payload: {error}"))
438            })?;
439        payload.validate()?;
440        Ok(payload)
441    }
442
443    /// Decode and validate a typed browser-backed `task.execute` payload.
444    pub fn decode_task_execute(&self) -> Result<TaskExecutionPayload, ProtocolError> {
445        self.validate()?;
446        if self.operation != TASK_EXECUTE_OPERATION {
447            return Err(ProtocolError::InvalidField(format!(
448                "expected operation {TASK_EXECUTE_OPERATION}"
449            )));
450        }
451        let mut value = self.payload.clone();
452        if let Value::Object(fields) = &mut value {
453            fields.remove("responseMode");
454        }
455        let payload: TaskExecutionPayload = serde_json::from_value(value).map_err(|error| {
456            ProtocolError::InvalidField(format!("task.execute payload: {error}"))
457        })?;
458        payload.validate()?;
459        Ok(payload)
460    }
461
462    /// Decode and validate a typed `task.validate` payload.
463    pub fn decode_task_validate(&self) -> Result<TaskValidationPayload, ProtocolError> {
464        self.validate()?;
465        if self.operation != TASK_VALIDATE_OPERATION {
466            return Err(ProtocolError::InvalidField(format!(
467                "expected operation {TASK_VALIDATE_OPERATION}"
468            )));
469        }
470        let payload: TaskValidationPayload =
471            serde_json::from_value(self.payload.clone()).map_err(|error| {
472                ProtocolError::InvalidField(format!("task.validate payload: {error}"))
473            })?;
474        payload.validate()?;
475        Ok(payload)
476    }
477
478    /// Decode and validate a typed `webIr.validate` payload.
479    pub fn decode_web_ir_validate(&self) -> Result<WebIrPayload, ProtocolError> {
480        self.decode_web_ir(WEB_IR_VALIDATE_OPERATION)
481    }
482
483    /// Decode and validate a typed `webIr.inspect` payload.
484    pub fn decode_web_ir_inspect(&self) -> Result<WebIrPayload, ProtocolError> {
485        self.decode_web_ir(WEB_IR_INSPECT_OPERATION)
486    }
487
488    fn decode_web_ir(&self, operation: &str) -> Result<WebIrPayload, ProtocolError> {
489        self.validate()?;
490        if self.operation != operation {
491            return Err(ProtocolError::InvalidField(format!(
492                "expected operation {operation}"
493            )));
494        }
495        let payload: WebIrPayload =
496            serde_json::from_value(self.payload.clone()).map_err(|error| {
497                ProtocolError::InvalidField(format!("{operation} payload: {error}"))
498            })?;
499        payload.validate()?;
500        Ok(payload)
501    }
502
503    /// Decode and validate a typed `webIr.diff` payload.
504    pub fn decode_web_ir_diff(&self) -> Result<WebIrDiffPayload, ProtocolError> {
505        self.validate()?;
506        if self.operation != WEB_IR_DIFF_OPERATION {
507            return Err(ProtocolError::InvalidField(format!(
508                "expected operation {WEB_IR_DIFF_OPERATION}"
509            )));
510        }
511        let payload: WebIrDiffPayload = serde_json::from_value(self.payload.clone())
512            .map_err(|error| ProtocolError::InvalidField(format!("webIr.diff payload: {error}")))?;
513        payload.validate()?;
514        Ok(payload)
515    }
516
517    /// Decode and validate a typed `webIr.continuity` payload.
518    pub fn decode_web_ir_continuity(&self) -> Result<WebIrContinuityPayload, ProtocolError> {
519        self.validate()?;
520        if self.operation != WEB_IR_CONTINUITY_OPERATION {
521            return Err(ProtocolError::InvalidField(format!(
522                "expected operation {WEB_IR_CONTINUITY_OPERATION}"
523            )));
524        }
525        let payload: WebIrContinuityPayload = serde_json::from_value(self.payload.clone())
526            .map_err(|error| {
527                ProtocolError::InvalidField(format!("webIr.continuity payload: {error}"))
528            })?;
529        payload.validate()?;
530        Ok(payload)
531    }
532
533    /// Decode the shared experience result payload carried by any transport.
534    pub fn decode_experience_result(
535        &self,
536    ) -> Result<crate::results::ExperienceResult, ProtocolError> {
537        self.validate()?;
538        let result: crate::results::ExperienceResult = serde_json::from_value(self.payload.clone())
539            .map_err(|error| {
540                ProtocolError::InvalidField(format!("experience result payload: {error}"))
541            })?;
542        result
543            .validate()
544            .map_err(|error| ProtocolError::InvalidField(error.to_string()))?;
545        Ok(result)
546    }
547}
548
549/// Decode and compile a `task.compile` request without browser access.
550pub fn compile_task_request(
551    request: &GlassRequest,
552) -> Result<crate::task_compiler::TaskExecutionPlan, ProtocolError> {
553    let payload = request.decode_task_compile()?;
554    crate::task_compiler::compile_task(&payload.task, &payload.ir)
555        .map_err(ProtocolError::TaskCompilation)
556}
557
558/// Decode and compile a `task.compile` request into a typed response payload.
559pub fn compile_task_result(request: &GlassRequest) -> Result<TaskCompileResult, ProtocolError> {
560    Ok(TaskCompileResult {
561        plan: compile_task_request(request)?,
562    })
563}
564
565/// Validate a `task.validate` request into a typed response payload.
566pub fn validate_task_result(request: &GlassRequest) -> Result<TaskValidationResult, ProtocolError> {
567    let payload = request.decode_task_validate()?;
568    Ok(TaskValidationResult {
569        valid: true,
570        schema_version: payload.task.schema_version,
571        task: payload.task.task,
572    })
573}
574
575/// Validate a Glass Web IR from a canonical request.
576pub fn web_ir_validate_result(
577    request: &GlassRequest,
578) -> Result<WebIrValidationResult, ProtocolError> {
579    let payload = request.decode_web_ir_validate()?;
580    Ok(WebIrValidationResult::from_ir(&payload.ir))
581}
582
583/// Inspect a Glass Web IR from a canonical request.
584pub fn web_ir_inspect_result(
585    request: &GlassRequest,
586) -> Result<WebIrInspectionResult, ProtocolError> {
587    let payload = request.decode_web_ir_inspect()?;
588    Ok(WebIrInspectionResult::from_ir(&payload.ir))
589}
590
591/// Compute a bounded Web IR diff from a canonical request.
592pub fn web_ir_diff_result(request: &GlassRequest) -> Result<WebIrDiffResult, ProtocolError> {
593    let payload = request.decode_web_ir_diff()?;
594    let diff = payload
595        .before
596        .diff(&payload.after)
597        .map_err(ProtocolError::WebIrValidation)?;
598    Ok(WebIrDiffResult::from_diff(&diff))
599}
600
601/// Classify one Web IR entity from a canonical request.
602pub fn web_ir_continuity_result(
603    request: &GlassRequest,
604) -> Result<WebIrContinuityResult, ProtocolError> {
605    let payload = request.decode_web_ir_continuity()?;
606    let continuity = payload
607        .before
608        .classify_entity_continuity(&payload.after, &payload.entity_id)
609        .map_err(ProtocolError::WebIrValidation)?;
610    Ok(WebIrContinuityResult::from(continuity))
611}
612
613/// Canonical operation response shared by supported transports.
614#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
615#[serde(rename_all = "camelCase")]
616pub struct GlassResponse {
617    pub protocol_version: u32,
618    pub request_id: String,
619    #[serde(skip_serializing_if = "Option::is_none")]
620    pub correlation_id: Option<String>,
621    pub ok: bool,
622    #[serde(skip_serializing_if = "Option::is_none")]
623    pub result: Option<Value>,
624    #[serde(skip_serializing_if = "Option::is_none")]
625    pub error: Option<GlassError>,
626}
627
628impl GlassResponse {
629    /// Validate envelope identity and the mutually exclusive result/error form.
630    pub fn validate(&self) -> Result<(), ProtocolError> {
631        if self.protocol_version != GLASS_PROTOCOL_VERSION {
632            return Err(ProtocolError::UnsupportedVersion(self.protocol_version));
633        }
634        validate_identifier(&self.request_id, "requestId")?;
635        if let Some(correlation_id) = &self.correlation_id {
636            validate_identifier(correlation_id, "correlationId")?;
637        }
638        if let Some(error) = &self.error {
639            error.validate()?;
640        }
641        match (self.ok, self.result.is_some(), self.error.is_some()) {
642            (true, true, false) | (false, false, true) => Ok(()),
643            _ => Err(ProtocolError::InvalidField(
644                "ok responses require result and error responses require error".into(),
645            )),
646        }
647    }
648
649    /// Decode and validate a successful typed `task.compile` result.
650    pub fn decode_task_compile_result(&self) -> Result<TaskCompileResult, ProtocolError> {
651        self.validate()?;
652        if !self.ok {
653            return Err(ProtocolError::InvalidField(
654                "task.compile result requires a successful response".into(),
655            ));
656        }
657        let value = self
658            .result
659            .clone()
660            .ok_or_else(|| ProtocolError::InvalidField("task.compile result is missing".into()))?;
661        let result: TaskCompileResult = serde_json::from_value(value).map_err(|error| {
662            ProtocolError::InvalidField(format!("task.compile result: {error}"))
663        })?;
664        result.validate()?;
665        Ok(result)
666    }
667
668    /// Decode and validate a successful typed `task.validate` result.
669    pub fn decode_task_validation_result(&self) -> Result<TaskValidationResult, ProtocolError> {
670        self.validate()?;
671        if !self.ok {
672            return Err(ProtocolError::InvalidField(
673                "task.validate result requires a successful response".into(),
674            ));
675        }
676        let value = self
677            .result
678            .clone()
679            .ok_or_else(|| ProtocolError::InvalidField("task.validate result is missing".into()))?;
680        serde_json::from_value(value)
681            .map_err(|error| ProtocolError::InvalidField(format!("task.validate result: {error}")))
682    }
683
684    /// Decode and validate a successful bounded `webIr.validate` result.
685    pub fn decode_web_ir_validation_result(&self) -> Result<WebIrValidationResult, ProtocolError> {
686        self.decode_web_ir_result("webIr.validate")
687    }
688
689    /// Decode and validate a successful bounded `webIr.inspect` result.
690    pub fn decode_web_ir_inspection_result(&self) -> Result<WebIrInspectionResult, ProtocolError> {
691        self.decode_web_ir_result("webIr.inspect")
692    }
693
694    fn decode_web_ir_result<T>(&self, operation: &str) -> Result<T, ProtocolError>
695    where
696        T: for<'de> Deserialize<'de>,
697    {
698        self.validate()?;
699        if !self.ok {
700            return Err(ProtocolError::InvalidField(format!(
701                "{operation} result requires a successful response"
702            )));
703        }
704        let value = self
705            .result
706            .clone()
707            .ok_or_else(|| ProtocolError::InvalidField(format!("{operation} result is missing")))?;
708        serde_json::from_value(value)
709            .map_err(|error| ProtocolError::InvalidField(format!("{operation} result: {error}")))
710    }
711
712    /// Decode and validate a successful bounded `webIr.diff` result.
713    pub fn decode_web_ir_diff_result(&self) -> Result<WebIrDiffResult, ProtocolError> {
714        self.validate()?;
715        if !self.ok {
716            return Err(ProtocolError::InvalidField(
717                "webIr.diff result requires a successful response".into(),
718            ));
719        }
720        let value = self
721            .result
722            .clone()
723            .ok_or_else(|| ProtocolError::InvalidField("webIr.diff result is missing".into()))?;
724        serde_json::from_value(value)
725            .map_err(|error| ProtocolError::InvalidField(format!("webIr.diff result: {error}")))
726    }
727
728    /// Decode and validate a successful Web IR continuity result.
729    pub fn decode_web_ir_continuity_result(&self) -> Result<WebIrContinuityResult, ProtocolError> {
730        self.validate()?;
731        if !self.ok {
732            return Err(ProtocolError::InvalidField(
733                "webIr.continuity result requires a successful response".into(),
734            ));
735        }
736        let value = self.result.clone().ok_or_else(|| {
737            ProtocolError::InvalidField("webIr.continuity result is missing".into())
738        })?;
739        serde_json::from_value(value).map_err(|error| {
740            ProtocolError::InvalidField(format!("webIr.continuity result: {error}"))
741        })
742    }
743}
744
745/// Phase in which a public operation stopped.
746#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
747#[serde(rename_all = "camelCase")]
748pub enum ErrorPhase {
749    #[default]
750    Preflight,
751    Dispatch,
752    PostDispatch,
753    Verification,
754    Reconciliation,
755}
756
757/// Stable retry classification for agent recovery.
758#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
759#[serde(rename_all = "camelCase")]
760pub enum RetryClassification {
761    SafeImmediate,
762    #[default]
763    SafeAfterReobserve,
764    SafeAfterReconcile,
765    UnsafeUntilReconciled,
766    RequiresUserDecision,
767    NotRetryable,
768    Unknown,
769}
770
771/// Bounded recovery guidance attached to every canonical failure.
772#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
773#[serde(rename_all = "camelCase")]
774pub struct RetryGuidance {
775    pub classification: RetryClassification,
776    pub recommended_operation: String,
777}
778
779impl Default for RetryGuidance {
780    fn default() -> Self {
781        Self {
782            classification: RetryClassification::SafeAfterReobserve,
783            recommended_operation: "inspect_page".into(),
784        }
785    }
786}
787
788/// Structured failure that can be carried across transports without parsing text.
789#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
790#[serde(rename_all = "camelCase")]
791pub struct GlassError {
792    pub code: String,
793    #[serde(default)]
794    pub phase: ErrorPhase,
795    pub message: String,
796    #[serde(default)]
797    pub mutation_possible: bool,
798    #[serde(default)]
799    pub retry: RetryGuidance,
800    /// Kept as a tolerated compatibility field for pre-0.2.2 clients.
801    #[serde(default, skip_serializing_if = "Option::is_none")]
802    pub retryable: Option<bool>,
803    #[serde(skip_serializing_if = "Option::is_none")]
804    pub details: Option<Value>,
805}
806
807impl GlassError {
808    /// Validate bounded, non-empty diagnostic fields.
809    pub fn validate(&self) -> Result<(), ProtocolError> {
810        if self.code.is_empty() || self.code.len() > MAX_ERROR_CODE_BYTES {
811            return Err(ProtocolError::InvalidField(
812                "error code must be a bounded non-empty string".into(),
813            ));
814        }
815        if self.message.is_empty() || self.message.len() > MAX_MESSAGE_BYTES {
816            return Err(ProtocolError::InvalidField(
817                "error message must be a bounded non-empty string".into(),
818            ));
819        }
820        validate_identifier(
821            &self.retry.recommended_operation,
822            "retry.recommendedOperation",
823        )?;
824        if let Some(details) = &self.details {
825            let detail_bytes = serde_json::to_vec(details).map_err(|error| {
826                ProtocolError::InvalidField(format!("error details are not serializable: {error}"))
827            })?;
828            if detail_bytes.len() > MAX_ERROR_DETAILS_BYTES {
829                return Err(ProtocolError::InvalidField(format!(
830                    "error details must be at most {MAX_ERROR_DETAILS_BYTES} bytes"
831                )));
832            }
833        }
834        Ok(())
835    }
836}
837
838/// Validation failure for the canonical protocol envelope.
839#[derive(Debug, Clone, PartialEq, Eq)]
840pub enum ProtocolError {
841    UnsupportedVersion(u32),
842    InvalidField(String),
843    TaskValidation(crate::task_protocol::TaskProtocolError),
844    TaskCompilation(crate::task_compiler::TaskCompilationError),
845    WebIrValidation(crate::web_ir::WebIrValidationError),
846}
847
848impl std::fmt::Display for ProtocolError {
849    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
850        match self {
851            Self::UnsupportedVersion(version) => {
852                write!(formatter, "unsupported Glass protocol version {version}")
853            }
854            Self::InvalidField(detail) => formatter.write_str(detail),
855            Self::TaskValidation(error) => error.fmt(formatter),
856            Self::TaskCompilation(error) => error.fmt(formatter),
857            Self::WebIrValidation(error) => error.fmt(formatter),
858        }
859    }
860}
861
862impl std::error::Error for ProtocolError {}
863
864fn validate_identifier(value: &str, field: &str) -> Result<(), ProtocolError> {
865    if value.is_empty() || value.len() > MAX_ID_BYTES || value.chars().any(char::is_whitespace) {
866        return Err(ProtocolError::InvalidField(format!(
867            "{field} must be a bounded non-whitespace identifier"
868        )));
869    }
870    Ok(())
871}
872
873#[cfg(test)]
874mod tests {
875    use super::*;
876
877    fn request() -> GlassRequest {
878        GlassRequest {
879            protocol_version: GLASS_PROTOCOL_VERSION,
880            request_id: "request-1".into(),
881            correlation_id: Some("run-1".into()),
882            session_id: Some("session-1".into()),
883            mutation_lease: Some(MutationLeaseRef {
884                session_id: "session-1".into(),
885                token: "lease-1".into(),
886            }),
887            operation: "browser.observe".into(),
888            payload: serde_json::json!({"level": "interactive"}),
889            deadline_ms: Some(5_000),
890        }
891    }
892
893    fn web_ir_fixture(revision: u64, name: &str) -> crate::web_ir::GlassWebIrV1 {
894        serde_json::from_value(serde_json::json!({
895            "schemaVersion": 1,
896            "revision": revision,
897            "document": {"revision": revision},
898            "entities": [
899                {
900                    "id": "page",
901                    "kind": "page",
902                    "quality": "confirmed",
903                    "evidenceSources": []
904                },
905                {
906                    "id": "field-1",
907                    "kind": "field",
908                    "role": "textbox",
909                    "name": name,
910                    "quality": "strong",
911                    "evidenceSources": ["dom"]
912                }
913            ],
914            "relationships": [
915                {"from": "page", "to": "field-1", "kind": "contains"}
916            ],
917            "coverage": {
918                "structural": "strong",
919                "semantic": "strong",
920                "interactiveEntitiesObserved": 1,
921                "opaqueRegions": 0,
922                "reasons": []
923            },
924            "limits": {
925                "truncated": false,
926                "omittedFacts": 0,
927                "textBytes": 0,
928                "missingSources": []
929            }
930        }))
931        .unwrap()
932    }
933
934    #[test]
935    fn request_round_trips_and_validates() {
936        let request = request();
937        request.validate().unwrap();
938        let value = serde_json::to_value(&request).unwrap();
939        assert_eq!(value["protocolVersion"], 1);
940        assert_eq!(value["mutationLease"]["sessionId"], "session-1");
941        let decoded: GlassRequest = serde_json::from_value(value).unwrap();
942        assert_eq!(decoded, request);
943    }
944
945    #[test]
946    fn response_requires_exactly_one_outcome() {
947        let response = GlassResponse {
948            protocol_version: GLASS_PROTOCOL_VERSION,
949            request_id: "request-1".into(),
950            correlation_id: None,
951            ok: false,
952            result: None,
953            error: Some(GlassError {
954                code: "target.stale".into(),
955                phase: ErrorPhase::Preflight,
956                message: "a mutation lease is required".into(),
957                mutation_possible: false,
958                retry: RetryGuidance {
959                    classification: RetryClassification::SafeAfterReobserve,
960                    recommended_operation: "inspect_page".into(),
961                },
962                retryable: Some(true),
963                details: None,
964            }),
965        };
966        response.validate().unwrap();
967        let mut invalid = response.clone();
968        invalid.ok = true;
969        assert!(invalid.validate().is_err());
970    }
971
972    #[test]
973    fn response_validation_rejects_unbounded_error_diagnostics() {
974        let response = GlassResponse {
975            protocol_version: GLASS_PROTOCOL_VERSION,
976            request_id: "request-1".into(),
977            correlation_id: None,
978            ok: false,
979            result: None,
980            error: Some(GlassError {
981                code: "invalid".into(),
982                phase: ErrorPhase::Preflight,
983                message: "request rejected".into(),
984                mutation_possible: false,
985                retry: RetryGuidance::default(),
986                retryable: None,
987                details: Some(serde_json::json!({
988                    "diagnostic": "x".repeat(MAX_ERROR_DETAILS_BYTES)
989                })),
990            }),
991        };
992        let error = response.validate().unwrap_err();
993        assert!(error.to_string().contains("error details must be at most"));
994    }
995
996    #[test]
997    fn web_ir_revision_operations_round_trip_with_bounded_results() {
998        let before = web_ir_fixture(7, "Email");
999        let after = web_ir_fixture(8, "Email address");
1000        let diff_request = GlassRequest {
1001            protocol_version: GLASS_PROTOCOL_VERSION,
1002            request_id: "diff-1".into(),
1003            correlation_id: None,
1004            session_id: None,
1005            mutation_lease: None,
1006            operation: WEB_IR_DIFF_OPERATION.into(),
1007            payload: serde_json::to_value(WebIrDiffPayload {
1008                before: before.clone(),
1009                after: after.clone(),
1010            })
1011            .unwrap(),
1012            deadline_ms: None,
1013        };
1014        let diff = web_ir_diff_result(&diff_request).unwrap();
1015        assert_eq!(diff.from_revision, 7);
1016        assert_eq!(diff.to_revision, 8);
1017        assert_eq!(diff.entity_changed_count, 1);
1018        assert_eq!(diff_request.decode_web_ir_diff().unwrap().before, before);
1019
1020        let continuity_request = GlassRequest {
1021            protocol_version: GLASS_PROTOCOL_VERSION,
1022            request_id: "continuity-1".into(),
1023            correlation_id: None,
1024            session_id: None,
1025            mutation_lease: None,
1026            operation: WEB_IR_CONTINUITY_OPERATION.into(),
1027            payload: serde_json::to_value(WebIrContinuityPayload {
1028                before,
1029                after,
1030                entity_id: "field-1".into(),
1031            })
1032            .unwrap(),
1033            deadline_ms: None,
1034        };
1035        let continuity = web_ir_continuity_result(&continuity_request).unwrap();
1036        assert_eq!(
1037            continuity.status,
1038            crate::web_ir::WebIrEntityContinuityStatus::Changed
1039        );
1040        let response = GlassResponse {
1041            protocol_version: GLASS_PROTOCOL_VERSION,
1042            request_id: continuity_request.request_id.clone(),
1043            correlation_id: None,
1044            ok: true,
1045            result: Some(serde_json::to_value(&continuity).unwrap()),
1046            error: None,
1047        };
1048        assert_eq!(
1049            response.decode_web_ir_continuity_result().unwrap(),
1050            continuity
1051        );
1052    }
1053
1054    #[test]
1055    fn web_ir_inspect_and_validate_operations_round_trip() {
1056        let draft = web_ir_fixture(7, "Email");
1057        let validate_request = GlassRequest {
1058            protocol_version: GLASS_PROTOCOL_VERSION,
1059            request_id: "validate-1".into(),
1060            correlation_id: None,
1061            session_id: None,
1062            mutation_lease: None,
1063            operation: WEB_IR_VALIDATE_OPERATION.into(),
1064            payload: serde_json::json!({"ir": draft.clone()}),
1065            deadline_ms: None,
1066        };
1067        let validation = web_ir_validate_result(&validate_request).unwrap();
1068        assert!(validation.valid);
1069        assert_eq!(validate_request.decode_web_ir_validate().unwrap().ir, draft);
1070        let validation_response = GlassResponse {
1071            protocol_version: GLASS_PROTOCOL_VERSION,
1072            request_id: "validate-1".into(),
1073            correlation_id: None,
1074            ok: true,
1075            result: Some(serde_json::to_value(&validation).unwrap()),
1076            error: None,
1077        };
1078        assert_eq!(
1079            validation_response
1080                .decode_web_ir_validation_result()
1081                .unwrap(),
1082            validation
1083        );
1084
1085        let inspect_request = GlassRequest {
1086            operation: WEB_IR_INSPECT_OPERATION.into(),
1087            request_id: "inspect-1".into(),
1088            payload: serde_json::json!({"ir": draft}),
1089            ..validate_request
1090        };
1091        let inspection = web_ir_inspect_result(&inspect_request).unwrap();
1092        let inspection_response = GlassResponse {
1093            protocol_version: GLASS_PROTOCOL_VERSION,
1094            request_id: "inspect-1".into(),
1095            correlation_id: None,
1096            ok: true,
1097            result: Some(serde_json::to_value(&inspection).unwrap()),
1098            error: None,
1099        };
1100        assert_eq!(
1101            inspection_response
1102                .decode_web_ir_inspection_result()
1103                .unwrap(),
1104            inspection
1105        );
1106    }
1107
1108    #[test]
1109    fn bounds_and_unknown_fields_fail_closed() {
1110        let mut request = request();
1111        request.operation = "bad operation".into();
1112        assert!(request.validate().is_err());
1113        let unknown = serde_json::json!({
1114            "protocolVersion": 1,
1115            "requestId": "request-1",
1116            "operation": "browser.observe",
1117            "payload": {},
1118            "future": true
1119        });
1120        assert!(serde_json::from_value::<GlassRequest>(unknown).is_err());
1121    }
1122
1123    #[test]
1124    fn task_validate_boundary_decodes_without_compiling() {
1125        let task = serde_json::json!({
1126            "schemaVersion": 1,
1127            "task": "region.extract",
1128            "scope": {"regionName": "Checkout"},
1129            "limits": {"maxActions": 4, "timeoutMs": 2000, "maxItems": 16},
1130            "risk": "readOnly"
1131        });
1132        let request = GlassRequest {
1133            protocol_version: GLASS_PROTOCOL_VERSION,
1134            request_id: "validate-task-1".into(),
1135            correlation_id: None,
1136            session_id: None,
1137            mutation_lease: None,
1138            operation: TASK_VALIDATE_OPERATION.into(),
1139            payload: serde_json::json!({"task": task}),
1140            deadline_ms: None,
1141        };
1142        let result = validate_task_result(&request).unwrap();
1143        assert_eq!(
1144            result,
1145            TaskValidationResult {
1146                valid: true,
1147                schema_version: 1,
1148                task: crate::task_protocol::TaskKind::RegionExtract,
1149            }
1150        );
1151        let response = GlassResponse {
1152            protocol_version: GLASS_PROTOCOL_VERSION,
1153            request_id: request.request_id.clone(),
1154            correlation_id: None,
1155            ok: true,
1156            result: Some(serde_json::to_value(&result).unwrap()),
1157            error: None,
1158        };
1159        assert_eq!(response.decode_task_validation_result().unwrap(), result);
1160        assert_eq!(
1161            request.decode_task_validate().unwrap().task.task,
1162            crate::task_protocol::TaskKind::RegionExtract
1163        );
1164    }
1165
1166    #[test]
1167    fn task_execute_boundary_decodes_revision_and_confirmation() {
1168        let request = GlassRequest {
1169            protocol_version: GLASS_PROTOCOL_VERSION,
1170            request_id: "execute-task-1".into(),
1171            correlation_id: None,
1172            session_id: Some("session-1".into()),
1173            mutation_lease: Some(MutationLeaseRef {
1174                session_id: "session-1".into(),
1175                token: "lease-1".into(),
1176            }),
1177            operation: TASK_EXECUTE_OPERATION.into(),
1178            payload: serde_json::json!({
1179                "task": {
1180                    "schemaVersion": 1,
1181                    "task": "form.submit",
1182                    "scope": {"regionName": "Checkout"},
1183                    "inputs": {"submit": "Submit"},
1184                    "limits": {"maxActions": 4, "timeoutMs": 2000, "maxItems": 16},
1185                    "risk": "remoteIrreversible",
1186                    "postconditions": [{"kind": "navigationOccurred"}],
1187                },
1188                "expectedRevision": 9,
1189                "confirmed": true
1190            }),
1191            deadline_ms: None,
1192        };
1193        let payload = request.decode_task_execute().unwrap();
1194        assert_eq!(
1195            payload.task.task,
1196            crate::task_protocol::TaskKind::FormSubmit
1197        );
1198        assert_eq!(payload.expected_revision, 9);
1199        assert!(payload.confirmed);
1200    }
1201
1202    #[test]
1203    fn task_compile_boundary_decodes_and_compiles_without_browser_state() {
1204        let task = serde_json::json!({
1205            "schemaVersion": 1,
1206            "task": "region.extract",
1207            "scope": {"regionName": "Checkout", "entityKind": "region"},
1208            "limits": {"maxActions": 8, "timeoutMs": 5000, "maxItems": 32},
1209            "risk": "readOnly"
1210        });
1211        let request = GlassRequest {
1212            protocol_version: GLASS_PROTOCOL_VERSION,
1213            request_id: "compile-1".into(),
1214            correlation_id: None,
1215            session_id: None,
1216            mutation_lease: None,
1217            operation: TASK_COMPILE_OPERATION.into(),
1218            payload: serde_json::json!({
1219                "task": task,
1220                "ir": crate::task_compiler::test_compiler_ir()
1221            }),
1222            deadline_ms: None,
1223        };
1224        let plan = compile_task_request(&request).unwrap();
1225        assert_eq!(plan.task, crate::task_protocol::TaskKind::RegionExtract);
1226        assert_eq!(plan.scope.region_name.as_deref(), Some("Checkout"));
1227        assert_eq!(plan.limits.max_actions, 8);
1228        assert_eq!(
1229            plan.revision,
1230            crate::task_protocol::TaskRevisionPolicy::Exact
1231        );
1232
1233        let mut wrong_operation = request.clone();
1234        wrong_operation.operation = "browser.observe".into();
1235        assert!(wrong_operation.decode_task_compile().is_err());
1236
1237        let mut unknown = request.clone();
1238        unknown.payload["futureField"] = true.into();
1239        assert!(unknown.decode_task_compile().is_err());
1240
1241        let mut invalid = request;
1242        invalid.payload["task"]["task"] = "form.fill".into();
1243        assert!(compile_task_request(&invalid).is_err());
1244    }
1245
1246    #[test]
1247    fn task_compile_result_round_trips_through_success_response() {
1248        let request = GlassRequest {
1249            protocol_version: GLASS_PROTOCOL_VERSION,
1250            request_id: "compile-2".into(),
1251            correlation_id: None,
1252            session_id: None,
1253            mutation_lease: None,
1254            operation: TASK_COMPILE_OPERATION.into(),
1255            payload: serde_json::json!({
1256                "task": {
1257                    "schemaVersion": 1,
1258                    "task": "field.read",
1259                    "scope": {"regionName": "Checkout", "entityKind": "field", "entityName": "Email"},
1260                    "inputs": {"field": "Email"},
1261                    "limits": {"maxActions": 4, "timeoutMs": 2000, "maxItems": 1},
1262                    "risk": "readOnly"
1263                },
1264                "ir": crate::task_compiler::test_compiler_ir()
1265            }),
1266            deadline_ms: None,
1267        };
1268        let result = compile_task_result(&request).unwrap();
1269        let response = GlassResponse {
1270            protocol_version: GLASS_PROTOCOL_VERSION,
1271            request_id: request.request_id.clone(),
1272            correlation_id: None,
1273            ok: true,
1274            result: Some(serde_json::to_value(&result).unwrap()),
1275            error: None,
1276        };
1277        assert_eq!(response.decode_task_compile_result().unwrap(), result);
1278
1279        let mut unknown = response.clone();
1280        unknown.result.as_mut().unwrap()["futureField"] = true.into();
1281        assert!(unknown.decode_task_compile_result().is_err());
1282
1283        let mut failure = response;
1284        failure.ok = false;
1285        failure.result = None;
1286        failure.error = Some(GlassError {
1287            code: "task.invalid".into(),
1288            phase: ErrorPhase::Preflight,
1289            message: "invalid task".into(),
1290            mutation_possible: false,
1291            retry: RetryGuidance::default(),
1292            retryable: None,
1293            details: None,
1294        });
1295        assert!(failure.decode_task_compile_result().is_err());
1296    }
1297
1298    #[test]
1299    fn additive_response_fields_are_tolerated() {
1300        let response: GlassResponse = serde_json::from_value(serde_json::json!({
1301            "protocolVersion": 1,
1302            "requestId": "request-1",
1303            "ok": false,
1304            "error": {
1305                "code": "target.stale",
1306                "message": "stale",
1307                "retryable": true,
1308                "future": "ignored"
1309            },
1310            "future": true
1311        }))
1312        .unwrap();
1313        assert_eq!(
1314            response.error.unwrap().retry.classification,
1315            RetryClassification::SafeAfterReobserve
1316        );
1317    }
1318}