Skip to main content

glass_browser/
extraction.rs

1//! Stable bounded evidence-extraction contract and browser-observation adapter.
2//!
3//! Authored requests are strict and resource-bounded. Observed evidence is
4//! source-labelled, explicit about omissions, and safe to reconcile into
5//! Glass Web IR without dispatching browser actions.
6use crate::browser::dom::{CompactAxNode, CompactInteractiveElement, DomNode};
7use crate::browser::session::{PageContext, find_region_node};
8use crate::surfaces::{
9    BridgeGrantRegistry, BridgeTrustLevel, CoverageLevel, DiagnosticSeverity, InteractionCoverage,
10    ProvenanceSourceClass, SURFACE_SCHEMA_VERSION, SemanticBridge, Surface, SurfaceCapability,
11    SurfaceCoverage, SurfaceDiagnostic, SurfaceEvidence, SurfaceEvidenceSource, SurfaceId,
12    SurfaceKind, SurfaceProvenance, SurfaceRevision, SurfaceSet, UnderstandingLevel,
13};
14use serde::{Deserialize, Serialize};
15use std::collections::BTreeSet;
16use std::fmt::{Display, Formatter};
17use std::time::{Duration, Instant};
18
19/// Version of the extraction request contract.
20pub const EXTRACTION_CONTRACT_SCHEMA_VERSION: u32 = 1;
21
22/// Maximum number of browser nodes one extraction may inspect.
23pub const MAX_EXTRACTION_NODES: u32 = 8_192;
24/// Maximum text bytes retained by one extraction.
25pub const MAX_EXTRACTION_TEXT_BYTES: u32 = 128 * 1024;
26/// Maximum DOM/accessibility depth one extraction may traverse.
27pub const MAX_EXTRACTION_DEPTH: u16 = 64;
28/// Maximum wall-clock duration permitted for one extraction.
29pub const MAX_EXTRACTION_DURATION_MS: u64 = 15_000;
30/// Maximum serialized evidence bytes returned by one extraction.
31pub const MAX_EXTRACTION_OUTPUT_BYTES: u32 = 256 * 1024;
32
33/// The page scope from which evidence may be gathered.
34#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
35#[serde(rename_all = "camelCase", deny_unknown_fields)]
36pub enum ExtractionScope {
37    /// Extract from the active document.
38    Document,
39    /// Extract from one previously identified semantic region.
40    Region { region_id: String },
41    /// Extract from one bounded browsing-context scope.
42    Frame { frame_id: String },
43}
44
45impl ExtractionScope {
46    fn validate(&self) -> Result<(), ExtractionContractError> {
47        match self {
48            Self::Document => Ok(()),
49            Self::Region { region_id } => validate_identifier("scope.regionId", region_id),
50            Self::Frame { frame_id } => validate_identifier("scope.frameId", frame_id),
51        }
52    }
53}
54
55/// Browser evidence categories an extraction may request.
56#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
57#[serde(rename_all = "camelCase", deny_unknown_fields)]
58pub enum EvidenceSource {
59    Dom,
60    Accessibility,
61    Layout,
62    Forms,
63    Navigation,
64    Tables,
65    Collections,
66    Dialogs,
67    Frames,
68    ShadowDom,
69    Svg,
70    CanvasDetection,
71    MediaMetadata,
72    EmbeddedDocument,
73    Pdf,
74    BrowserNative,
75    Bridge,
76    BoundedProbe,
77}
78
79/// Hard resource limits for one extraction request.
80#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
81#[serde(rename_all = "camelCase", deny_unknown_fields)]
82pub struct ExtractionBudgets {
83    pub max_nodes: u32,
84    pub max_text_bytes: u32,
85    pub max_depth: u16,
86    pub max_duration_ms: u64,
87    pub max_output_bytes: u32,
88}
89
90impl Default for ExtractionBudgets {
91    fn default() -> Self {
92        Self {
93            max_nodes: 2_048,
94            max_text_bytes: 32 * 1024,
95            max_depth: 32,
96            max_duration_ms: 5_000,
97            max_output_bytes: 64 * 1024,
98        }
99    }
100}
101
102impl ExtractionBudgets {
103    /// Validate all limits against the extraction contract maxima.
104    pub fn validate(&self) -> Result<(), ExtractionContractError> {
105        validate_positive_bounded("budgets.maxNodes", self.max_nodes, MAX_EXTRACTION_NODES)?;
106        validate_positive_bounded(
107            "budgets.maxTextBytes",
108            self.max_text_bytes,
109            MAX_EXTRACTION_TEXT_BYTES,
110        )?;
111        validate_positive_bounded("budgets.maxDepth", self.max_depth, MAX_EXTRACTION_DEPTH)?;
112        validate_positive_bounded(
113            "budgets.maxDurationMs",
114            self.max_duration_ms,
115            MAX_EXTRACTION_DURATION_MS,
116        )?;
117        validate_positive_bounded(
118            "budgets.maxOutputBytes",
119            self.max_output_bytes,
120            MAX_EXTRACTION_OUTPUT_BYTES,
121        )?;
122        Ok(())
123    }
124}
125
126/// A strict, non-mutating evidence extraction request.
127#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
128#[serde(rename_all = "camelCase", deny_unknown_fields)]
129pub struct ExtractionRequest {
130    pub schema_version: u32,
131    pub scope: ExtractionScope,
132    pub sources: Vec<EvidenceSource>,
133    pub budgets: ExtractionBudgets,
134}
135
136impl ExtractionRequest {
137    /// Build the bounded document request used by live semantic consumers.
138    ///
139    /// The source set mirrors live Task Protocol compilation so a caller can
140    /// inspect the same evidence classes without hand-maintaining a second
141    /// request contract. The request remains non-mutating and bounded by the
142    /// default extraction budgets.
143    pub fn default_document() -> Self {
144        Self {
145            schema_version: EXTRACTION_CONTRACT_SCHEMA_VERSION,
146            scope: ExtractionScope::Document,
147            sources: vec![
148                EvidenceSource::Accessibility,
149                EvidenceSource::Dom,
150                EvidenceSource::Forms,
151                EvidenceSource::Layout,
152                EvidenceSource::Navigation,
153                EvidenceSource::Tables,
154                EvidenceSource::Collections,
155                EvidenceSource::Dialogs,
156                EvidenceSource::Frames,
157                EvidenceSource::ShadowDom,
158                EvidenceSource::Svg,
159                EvidenceSource::CanvasDetection,
160                EvidenceSource::MediaMetadata,
161                EvidenceSource::EmbeddedDocument,
162                EvidenceSource::Pdf,
163                EvidenceSource::BrowserNative,
164                EvidenceSource::Bridge,
165                EvidenceSource::BoundedProbe,
166            ],
167            budgets: ExtractionBudgets::default(),
168        }
169    }
170
171    /// Validate the authored request before any browser work starts.
172    pub fn validate(&self) -> Result<(), ExtractionContractError> {
173        if self.schema_version != EXTRACTION_CONTRACT_SCHEMA_VERSION {
174            return Err(ExtractionContractError::new(
175                "schemaVersion",
176                "unsupported extraction contract schema version",
177            ));
178        }
179        self.scope.validate()?;
180        if self.sources.is_empty() {
181            return Err(ExtractionContractError::new(
182                "sources",
183                "at least one evidence source is required",
184            ));
185        }
186        let mut unique_sources = BTreeSet::new();
187        for source in &self.sources {
188            if !unique_sources.insert(*source) {
189                return Err(ExtractionContractError::new(
190                    "sources",
191                    "evidence sources must not be duplicated",
192                ));
193            }
194        }
195        self.budgets.validate()
196    }
197
198    /// Parse and validate a strict authored request.
199    pub fn from_json(input: &str) -> Result<Self, ExtractionContractError> {
200        let request: Self = serde_json::from_str(input).map_err(|error| {
201            ExtractionContractError::new("$", format!("invalid extraction request: {error}"))
202        })?;
203        request.validate()?;
204        Ok(request)
205    }
206
207    /// Serialize a validated request with stable field ordering.
208    pub fn to_canonical_json(&self) -> Result<String, ExtractionContractError> {
209        self.validate()?;
210        serde_json::to_string(self).map_err(|error| {
211            ExtractionContractError::new(
212                "$",
213                format!("failed to serialize extraction request: {error}"),
214            )
215        })
216    }
217}
218
219/// Explainable quality class attached to an evidence fact.
220#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
221#[serde(rename_all = "lowercase")]
222pub enum EvidenceQuality {
223    Confirmed,
224    Strong,
225    Partial,
226    Inferred,
227    Conflicted,
228    Opaque,
229}
230
231/// Explicit semantic relationship hint carried by bounded evidence.
232#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
233#[serde(rename_all = "camelCase")]
234pub enum EvidenceRelationshipHint {
235    Contains,
236    Labels,
237    Owns,
238    Controls,
239    NavigatesTo,
240    Opens,
241    Confirms,
242    Cancels,
243    Continues,
244    Submits,
245    HeaderFor,
246    CellOf,
247    Selects,
248    RepeatsAs,
249    ScopedTo,
250}
251
252/// Coverage summary for one bounded extraction.
253#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
254#[serde(rename_all = "camelCase")]
255pub struct EvidenceCoverage {
256    pub structural: EvidenceQuality,
257    pub semantic: EvidenceQuality,
258    pub interactive_entities_observed: u32,
259    pub opaque_regions: u32,
260    #[serde(default, skip_serializing_if = "Vec::is_empty")]
261    pub reasons: Vec<String>,
262}
263
264/// Bounded evidence produced from an existing page observation.
265#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
266#[serde(rename_all = "camelCase")]
267pub struct ExtractionEvidence {
268    pub schema_version: u32,
269    pub revision: u64,
270    pub scope: ExtractionScope,
271    pub sources: Vec<EvidenceSource>,
272    pub facts: Vec<EvidenceFact>,
273    pub limits: ExtractionEvidenceLimits,
274    pub coverage: EvidenceCoverage,
275    /// Validated transport-neutral surface evidence for this observation.
276    #[serde(default, skip_serializing_if = "Option::is_none")]
277    pub surface_set: Option<SurfaceSet>,
278}
279
280/// One redacted, source-labelled fact from browser evidence.
281#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
282#[serde(rename_all = "camelCase")]
283pub struct EvidenceFact {
284    pub source: EvidenceSource,
285    pub kind: String,
286    pub quality: EvidenceQuality,
287    #[serde(skip_serializing_if = "Option::is_none")]
288    pub role: Option<String>,
289    #[serde(skip_serializing_if = "Option::is_none")]
290    pub name: Option<String>,
291    /// Bounded observed accessibility region role for relationship reconciliation.
292    #[serde(skip_serializing_if = "Option::is_none")]
293    pub parent_role: Option<String>,
294    /// Explicit semantic relationship, when a source can prove one.
295    #[serde(skip_serializing_if = "Option::is_none")]
296    pub relationship_hint: Option<EvidenceRelationshipHint>,
297    #[serde(skip_serializing_if = "Option::is_none")]
298    pub input_type: Option<String>,
299    #[serde(skip_serializing_if = "Option::is_none")]
300    pub autocomplete: Option<String>,
301    #[serde(skip_serializing_if = "Option::is_none")]
302    pub required: Option<bool>,
303    #[serde(skip_serializing_if = "Option::is_none")]
304    pub read_only: Option<bool>,
305    #[serde(skip_serializing_if = "Option::is_none")]
306    pub empty: Option<bool>,
307    #[serde(skip_serializing_if = "Option::is_none")]
308    pub checked: Option<bool>,
309    #[serde(skip_serializing_if = "Option::is_none")]
310    pub disabled: Option<bool>,
311    #[serde(skip_serializing_if = "Option::is_none")]
312    pub geometry_present: Option<bool>,
313}
314
315impl ExtractionEvidence {
316    /// Validate every explicit relationship hint against its source contract.
317    pub fn validate_relationship_hints(&self) -> Result<(), ExtractionContractError> {
318        for (index, fact) in self.facts.iter().enumerate() {
319            let path = format!("facts[{index}].relationshipHint");
320            fact.validate_relationship_hint(&path)?;
321        }
322        Ok(())
323    }
324}
325
326impl EvidenceFact {
327    /// Validate one explicit relationship hint and its required parent role.
328    pub fn validate_relationship_hint(&self, path: &str) -> Result<(), ExtractionContractError> {
329        let Some(hint) = self.relationship_hint else {
330            return Ok(());
331        };
332        if self.parent_role.as_deref().is_none_or(str::is_empty) {
333            return Err(ExtractionContractError::new(
334                path,
335                "relationship hints require a bounded parent role",
336            ));
337        }
338        if !relationship_hint_allowed(self.source, hint) {
339            return Err(ExtractionContractError::new(
340                path,
341                format!(
342                    "relationship hint {hint:?} is not supported by source {:?}",
343                    self.source
344                ),
345            ));
346        }
347        Ok(())
348    }
349}
350
351fn relationship_hint_allowed(source: EvidenceSource, hint: EvidenceRelationshipHint) -> bool {
352    match source {
353        EvidenceSource::Accessibility => matches!(
354            hint,
355            EvidenceRelationshipHint::Contains
356                | EvidenceRelationshipHint::Labels
357                | EvidenceRelationshipHint::Owns
358                | EvidenceRelationshipHint::Controls
359                | EvidenceRelationshipHint::Opens
360                | EvidenceRelationshipHint::Confirms
361                | EvidenceRelationshipHint::Cancels
362                | EvidenceRelationshipHint::Continues
363                | EvidenceRelationshipHint::Selects
364                | EvidenceRelationshipHint::ScopedTo
365        ),
366        EvidenceSource::Dom => matches!(
367            hint,
368            EvidenceRelationshipHint::Contains
369                | EvidenceRelationshipHint::Labels
370                | EvidenceRelationshipHint::Owns
371                | EvidenceRelationshipHint::Controls
372                | EvidenceRelationshipHint::NavigatesTo
373                | EvidenceRelationshipHint::Opens
374                | EvidenceRelationshipHint::Confirms
375                | EvidenceRelationshipHint::Cancels
376                | EvidenceRelationshipHint::Continues
377                | EvidenceRelationshipHint::Submits
378                | EvidenceRelationshipHint::HeaderFor
379                | EvidenceRelationshipHint::CellOf
380                | EvidenceRelationshipHint::Selects
381                | EvidenceRelationshipHint::RepeatsAs
382                | EvidenceRelationshipHint::ScopedTo
383        ),
384        EvidenceSource::Forms => matches!(
385            hint,
386            EvidenceRelationshipHint::Contains
387                | EvidenceRelationshipHint::Labels
388                | EvidenceRelationshipHint::Owns
389                | EvidenceRelationshipHint::Controls
390                | EvidenceRelationshipHint::Submits
391        ),
392        EvidenceSource::Layout => matches!(
393            hint,
394            EvidenceRelationshipHint::Contains | EvidenceRelationshipHint::ScopedTo
395        ),
396        EvidenceSource::Navigation
397        | EvidenceSource::Tables
398        | EvidenceSource::Collections
399        | EvidenceSource::Dialogs
400        | EvidenceSource::Frames
401        | EvidenceSource::ShadowDom
402        | EvidenceSource::Svg
403        | EvidenceSource::CanvasDetection
404        | EvidenceSource::MediaMetadata
405        | EvidenceSource::EmbeddedDocument
406        | EvidenceSource::Pdf
407        | EvidenceSource::BrowserNative
408        | EvidenceSource::Bridge
409        | EvidenceSource::BoundedProbe => false,
410    }
411}
412
413/// Explicit omissions and truncation from one evidence extraction.
414#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
415#[serde(rename_all = "camelCase")]
416pub struct ExtractionEvidenceLimits {
417    pub truncated: bool,
418    pub omitted_facts: u32,
419    pub text_bytes: u32,
420    pub missing_sources: Vec<EvidenceSource>,
421}
422
423/// Extract bounded, redacted facts from an existing page observation.
424///
425/// This adapter is side-effect free. It consumes only the already-collected
426/// `PageContext`; browser acquisition remains owned by the session layer.
427pub fn extract_page_context(
428    context: &PageContext,
429    request: &ExtractionRequest,
430) -> Result<ExtractionEvidence, ExtractionContractError> {
431    validate_observation_boundaries(context)?;
432    request.validate()?;
433    let region_root = match &request.scope {
434        ExtractionScope::Document => None,
435        ExtractionScope::Region { region_id } if region_id == "region_main" => None,
436        ExtractionScope::Region { region_id } => {
437            Some(find_region_node(context, region_id).ok_or_else(|| {
438                ExtractionContractError::new(
439                    "scope.regionId",
440                    format!(
441                        "region {region_id:?} is not present at revision {}",
442                        context.accessibility.revision
443                    ),
444                )
445            })?)
446        }
447        ExtractionScope::Frame { frame_id } if frame_id == &context.page.frame_id => None,
448        ExtractionScope::Frame { frame_id } => {
449            return Err(ExtractionContractError::new(
450                "scope.frameId",
451                format!("frame {frame_id:?} is not the active observed frame"),
452            ));
453        }
454    };
455
456    let mut collector = EvidenceCollector::new(request.budgets);
457    let mut missing_sources = BTreeSet::new();
458    let inconsistent_observation = observation_has_mutation_race(context);
459    let incomplete_accessibility = context.incomplete.iter().any(|reason| {
460        matches!(
461            reason,
462            crate::browser::session::ObservationIncompleteReason::AccessibilityNode
463                | crate::browser::session::ObservationIncompleteReason::AccessibilityLabel
464                | crate::browser::session::ObservationIncompleteReason::Control
465        )
466    });
467
468    for source in &request.sources {
469        match source {
470            EvidenceSource::Accessibility => {
471                if incomplete_accessibility {
472                    missing_sources.insert(*source);
473                } else if let Some(root) = region_root {
474                    collect_accessibility(root, &mut collector, 0, None);
475                } else {
476                    for root in &context.accessibility.roots {
477                        if collector.node_budget_exhausted() {
478                            collector.mark_omitted();
479                            break;
480                        }
481                        collect_accessibility(root, &mut collector, 0, None);
482                    }
483                }
484                if !incomplete_accessibility {
485                    for control in &context.accessibility.interactive {
486                        if control_in_region(control, region_root) {
487                            collect_accessibility_control(control, &mut collector);
488                        }
489                    }
490                }
491            }
492            EvidenceSource::Dom | EvidenceSource::Layout if region_root.is_some() => {
493                missing_sources.insert(*source);
494            }
495            EvidenceSource::Dom => {
496                if let Some(root) = context.dom.as_ref() {
497                    collect_dom(root, &mut collector, 0);
498                } else {
499                    missing_sources.insert(*source);
500                }
501            }
502            EvidenceSource::Forms => {
503                if incomplete_accessibility {
504                    missing_sources.insert(*source);
505                } else {
506                    for control in &context.accessibility.interactive {
507                        if collector.node_budget_exhausted() {
508                            collector.mark_omitted();
509                            break;
510                        }
511                        if !control_in_region(control, region_root)
512                            || (control.input_type.is_none()
513                                && !is_form_control_role(&control.role))
514                        {
515                            continue;
516                        }
517                        if !collector.allow_node(0) {
518                            break;
519                        }
520                        let parent_role = nearest_safe_parent_role(&control.ancestor_path);
521                        collector.push(EvidenceFact {
522                            source: *source,
523                            kind: "control".into(),
524                            quality: EvidenceQuality::Strong,
525                            role: Some(control.role.clone()),
526                            name: Some(control.name.clone()),
527                            input_type: control.input_type.clone(),
528                            autocomplete: control.autocomplete.clone(),
529                            required: Some(control.required),
530                            read_only: Some(control.read_only),
531                            empty: Some(control.empty),
532                            checked: control.checked,
533                            disabled: control.disabled,
534                            geometry_present: None,
535                            relationship_hint: custom_form_control_hint(
536                                &control.role,
537                                parent_role.as_deref(),
538                            ),
539                            parent_role,
540                        });
541                    }
542                }
543            }
544            EvidenceSource::Layout => {
545                if let Some(root) = context.dom.as_ref() {
546                    collect_layout(root, &mut collector, *source, 0);
547                } else {
548                    missing_sources.insert(*source);
549                }
550            }
551            EvidenceSource::Navigation
552            | EvidenceSource::Tables
553            | EvidenceSource::Collections
554            | EvidenceSource::Dialogs => {
555                if incomplete_accessibility {
556                    missing_sources.insert(*source);
557                } else if let Some(root) = region_root {
558                    collect_semantic_source(root, *source, &mut collector, 0, None);
559                } else {
560                    for root in &context.accessibility.roots {
561                        if collector.node_budget_exhausted() {
562                            collector.mark_omitted();
563                            break;
564                        }
565                        collect_semantic_source(root, *source, &mut collector, 0, None);
566                    }
567                }
568            }
569            EvidenceSource::Frames => {
570                let count = if matches!(request.scope, ExtractionScope::Frame { .. }) {
571                    1
572                } else {
573                    context.boundaries.child_frames
574                };
575                if count > 0 {
576                    push_boundary_fact(
577                        &mut collector,
578                        *source,
579                        "frame",
580                        format!("{count} observed frame scope(s)"),
581                    );
582                }
583            }
584            EvidenceSource::ShadowDom => {
585                if context.boundaries.shadow_roots > 0 {
586                    push_boundary_fact(
587                        &mut collector,
588                        *source,
589                        "shadowroot",
590                        format!(
591                            "{} observed shadow root(s)",
592                            context.boundaries.shadow_roots
593                        ),
594                    );
595                }
596            }
597            EvidenceSource::Svg => {
598                if let Some(root) = context.dom.as_ref()
599                    && has_svg_node(root)
600                {
601                    collect_svg_semantics(root, &mut collector, 0, false);
602                } else if context.boundaries.svg_elements > 0 {
603                    push_boundary_fact(
604                        &mut collector,
605                        *source,
606                        "surface",
607                        format!(
608                            "{} observed SVG surface(s)",
609                            context.boundaries.svg_elements
610                        ),
611                    );
612                } else {
613                    missing_sources.insert(*source);
614                }
615            }
616            EvidenceSource::CanvasDetection
617            | EvidenceSource::MediaMetadata
618            | EvidenceSource::EmbeddedDocument
619            | EvidenceSource::Pdf
620            | EvidenceSource::BrowserNative
621            | EvidenceSource::Bridge => {
622                let count = match source {
623                    EvidenceSource::CanvasDetection => context.boundaries.canvases,
624                    EvidenceSource::MediaMetadata => context.boundaries.media_elements,
625                    EvidenceSource::EmbeddedDocument => context.boundaries.embedded_documents,
626                    EvidenceSource::Pdf => context.boundaries.pdf_documents,
627                    EvidenceSource::BrowserNative => context.boundaries.native_surfaces,
628                    EvidenceSource::Bridge => 0,
629                    _ => 0,
630                };
631                if count > 0 {
632                    push_boundary_fact(
633                        &mut collector,
634                        *source,
635                        "surface",
636                        format!("{count} observed surface(s)"),
637                    );
638                } else {
639                    missing_sources.insert(*source);
640                }
641            }
642            EvidenceSource::BoundedProbe => {
643                if let Some(viewport) = context.boundaries.viewport {
644                    push_boundary_fact(
645                        &mut collector,
646                        *source,
647                        "viewport",
648                        format!(
649                            "{}x{} viewport in {}x{} document",
650                            viewport.width,
651                            viewport.height,
652                            viewport.document_width,
653                            viewport.document_height
654                        ),
655                    );
656                } else {
657                    missing_sources.insert(*source);
658                }
659            }
660        }
661    }
662    collector.truncated |= context.accessibility.truncated || context.boundaries.truncated;
663    let missing_source_values: Vec<_> = missing_sources.iter().copied().collect();
664    let coverage = evidence_coverage(
665        context,
666        &request.sources,
667        &missing_sources,
668        collector.truncated,
669        collector.timed_out,
670        inconsistent_observation,
671    );
672    let mut evidence = ExtractionEvidence {
673        schema_version: EXTRACTION_CONTRACT_SCHEMA_VERSION,
674        revision: context.accessibility.revision,
675        scope: request.scope.clone(),
676        sources: request.sources.clone(),
677        facts: collector.facts,
678        limits: ExtractionEvidenceLimits {
679            truncated: collector.truncated,
680            omitted_facts: collector.omitted_facts,
681            text_bytes: collector.text_bytes,
682            missing_sources: missing_source_values,
683        },
684        coverage,
685        surface_set: build_surface_set(context, &request.sources, &missing_sources)?,
686    };
687    trim_to_output_budget(&mut evidence, request.budgets.max_output_bytes)?;
688    Ok(evidence)
689}
690/// Convert a validated page semantic bridge into bounded extraction evidence.
691///
692/// The bridge is never trusted by itself: origin, revision, capability
693/// allowlists, and the independent host grant are checked before facts are
694/// materialized.
695pub fn extract_semantic_bridge(
696    bridge: &SemanticBridge,
697    grants: &BridgeGrantRegistry,
698    expected_origin: &str,
699    expected_revision: SurfaceRevision,
700) -> Result<ExtractionEvidence, ExtractionContractError> {
701    bridge
702        .validate(grants, expected_origin, expected_revision)
703        .map_err(|error| ExtractionContractError::new("bridge", error.to_string()))?;
704    let timestamp = format!(
705        "1970-01-01T00:{:02}:{:02}Z",
706        (bridge.revision.0 / 60) % 60,
707        bridge.revision.0 % 60
708    );
709    let provenance = SurfaceProvenance {
710        schema_version: SURFACE_SCHEMA_VERSION,
711        source_class: ProvenanceSourceClass::Bridge,
712        source_id: format!("bridge:{}", bridge.surface_id.as_str()),
713        backend: None,
714        backend_version: None,
715        adapter_version: None,
716        bridge_version: Some(bridge.bridge_version.clone()),
717        bridge_origin: Some(bridge.origin.clone()),
718        bridge_trust: Some(BridgeTrustLevel::CapabilityGranted),
719        grant_token: Some(bridge.grant_token.clone()),
720        bridge_capabilities: bridge.capabilities.clone(),
721        source_revision: bridge.revision,
722        observed_at: timestamp.clone(),
723        validated_at: timestamp,
724    };
725    let task_compilable = [
726        SurfaceCapability::ReadStructure,
727        SurfaceCapability::ReadState,
728        SurfaceCapability::SemanticAction,
729        SurfaceCapability::RevisionObservation,
730        SurfaceCapability::Verification,
731    ]
732    .iter()
733    .all(|capability| bridge.capabilities.contains(capability));
734    let surface_understanding = if task_compilable {
735        UnderstandingLevel::TaskCompilable
736    } else {
737        UnderstandingLevel::Semantic
738    };
739    let interaction = if task_compilable {
740        InteractionCoverage::TaskCompilable
741    } else {
742        InteractionCoverage::Semantic
743    };
744    let surface = Surface {
745        schema_version: SURFACE_SCHEMA_VERSION,
746        surface_id: bridge.surface_id.clone(),
747        parent_surface_id: None,
748        nesting_depth: 0,
749        kind: bridge.surface_kind.clone(),
750        capabilities: bridge.capabilities.clone(),
751        understanding: surface_understanding,
752        coverage: SurfaceCoverage {
753            structural: CoverageLevel::Strong,
754            semantic: CoverageLevel::Strong,
755            interaction,
756        },
757        evidence: vec![SurfaceEvidence {
758            source: SurfaceEvidenceSource::Bridge,
759            quality: CoverageLevel::Strong,
760            provenance,
761            detail: Some("validated semantic bridge evidence".into()),
762        }],
763        revision: bridge.revision,
764        diagnostics: Vec::new(),
765    };
766    let surface_set = SurfaceSet {
767        schema_version: SURFACE_SCHEMA_VERSION,
768        surfaces: vec![surface],
769    };
770    surface_set
771        .validate_with_grants(grants)
772        .map_err(|error| ExtractionContractError::new("bridge.surfaceSet", error.to_string()))?;
773    let mut facts = Vec::with_capacity(bridge.entities.len());
774    for entity in &bridge.entities {
775        let role = entity.role.clone().or_else(|| Some(entity.kind.clone()));
776        facts.push(EvidenceFact {
777            source: EvidenceSource::Bridge,
778            kind: entity.kind.clone(),
779            quality: match entity.quality {
780                CoverageLevel::Complete | CoverageLevel::Strong => EvidenceQuality::Confirmed,
781                CoverageLevel::Partial => EvidenceQuality::Partial,
782                CoverageLevel::Opaque => EvidenceQuality::Opaque,
783            },
784            role,
785            name: entity.name.clone(),
786            parent_role: None,
787            relationship_hint: None,
788            input_type: None,
789            autocomplete: None,
790            required: None,
791            read_only: None,
792            empty: None,
793            checked: None,
794            disabled: None,
795            geometry_present: Some(true),
796        });
797    }
798    let evidence = ExtractionEvidence {
799        schema_version: EXTRACTION_CONTRACT_SCHEMA_VERSION,
800        revision: bridge.revision.0,
801        scope: ExtractionScope::Document,
802        sources: vec![EvidenceSource::Bridge],
803        facts,
804        limits: ExtractionEvidenceLimits {
805            truncated: false,
806            omitted_facts: 0,
807            text_bytes: 0,
808            missing_sources: Vec::new(),
809        },
810        coverage: EvidenceCoverage {
811            structural: EvidenceQuality::Confirmed,
812            semantic: EvidenceQuality::Confirmed,
813            interactive_entities_observed: bridge.entities.len() as u32,
814            opaque_regions: 0,
815            reasons: Vec::new(),
816        },
817        surface_set: Some(surface_set),
818    };
819    evidence.validate_relationship_hints()?;
820    Ok(evidence)
821}
822
823fn build_surface_set(
824    context: &PageContext,
825    requested: &[EvidenceSource],
826    missing: &BTreeSet<EvidenceSource>,
827) -> Result<Option<SurfaceSet>, ExtractionContractError> {
828    let revision = SurfaceRevision::new(context.accessibility.revision.max(1))
829        .map_err(|error| ExtractionContractError::new("surfaceSet.revision", error.to_string()))?;
830    let quality = if context.boundaries.truncated || context.accessibility.truncated {
831        CoverageLevel::Partial
832    } else {
833        CoverageLevel::Strong
834    };
835    let timestamp = format!(
836        "1970-01-01T00:{:02}:{:02}Z",
837        (revision.0 / 60) % 60,
838        revision.0 % 60
839    );
840    let provenance = || SurfaceProvenance {
841        schema_version: SURFACE_SCHEMA_VERSION,
842        source_class: ProvenanceSourceClass::LiveWebIr,
843        source_id: format!("page:{}", revision.0),
844        backend: None,
845        backend_version: None,
846        adapter_version: Some("browser-observation-1".into()),
847        bridge_version: None,
848        bridge_origin: None,
849        bridge_trust: None,
850        grant_token: None,
851        bridge_capabilities: Vec::new(),
852        source_revision: revision,
853        observed_at: timestamp.clone(),
854        validated_at: timestamp.clone(),
855    };
856    let evidence = |source: SurfaceEvidenceSource, detail: String, level| SurfaceEvidence {
857        source,
858        quality: level,
859        provenance: provenance(),
860        detail: Some(detail),
861    };
862    let available =
863        |source: EvidenceSource| requested.contains(&source) && !missing.contains(&source);
864    let mut surfaces = Vec::new();
865    let mut surface_bound_omitted = false;
866    let add = |surfaces: &mut Vec<Surface>,
867               id: String,
868               parent: Option<SurfaceId>,
869               kind: SurfaceKind,
870               evidence_values: Vec<SurfaceEvidence>,
871               understanding: UnderstandingLevel,
872               coverage: SurfaceCoverage,
873               capabilities: Vec<SurfaceCapability>| {
874        let surface_id = SurfaceId::new(id).map_err(|error| {
875            ExtractionContractError::new("surfaceSet.surfaces", error.to_string())
876        })?;
877        let nesting_depth = u16::from(parent.is_some());
878        let diagnostics = match &kind {
879            SurfaceKind::EmbeddedDocument | SurfaceKind::Pdf | SurfaceKind::BrowserNative => {
880                vec![SurfaceDiagnostic {
881                    severity: DiagnosticSeverity::Warning,
882                    code: "semanticUnavailable".into(),
883                    message: "surface boundary detected, but semantic content was not observed; semantic compilation is unavailable".into(),
884                }]
885            }
886            _ => Vec::new(),
887        };
888        surfaces.push(Surface {
889            schema_version: SURFACE_SCHEMA_VERSION,
890            surface_id,
891            parent_surface_id: parent,
892            nesting_depth,
893            kind,
894            capabilities,
895            understanding,
896            coverage,
897            evidence: evidence_values,
898            revision,
899            diagnostics,
900        });
901        Ok::<(), ExtractionContractError>(())
902    };
903
904    let mut document_evidence = Vec::new();
905    if available(EvidenceSource::Dom) {
906        document_evidence.push(evidence(
907            SurfaceEvidenceSource::Dom,
908            "observed document structure".into(),
909            quality,
910        ));
911    }
912    if available(EvidenceSource::Accessibility) {
913        document_evidence.push(evidence(
914            SurfaceEvidenceSource::Accessibility,
915            "observed accessibility semantics".into(),
916            quality,
917        ));
918    }
919    let has_document = !document_evidence.is_empty();
920    let root_id = SurfaceId::new("document")
921        .map_err(|error| ExtractionContractError::new("surfaceSet.surfaces", error.to_string()))?;
922    if has_document {
923        add(
924            &mut surfaces,
925            "document".into(),
926            None,
927            SurfaceKind::Document,
928            document_evidence,
929            UnderstandingLevel::Structural,
930            SurfaceCoverage {
931                structural: quality,
932                semantic: if available(EvidenceSource::Accessibility) {
933                    quality
934                } else {
935                    CoverageLevel::Partial
936                },
937                interaction: InteractionCoverage::Unavailable,
938            },
939            vec![
940                SurfaceCapability::ReadStructure,
941                SurfaceCapability::ReadText,
942                SurfaceCapability::ReadRelations,
943                SurfaceCapability::ReadState,
944                SurfaceCapability::Extraction,
945                SurfaceCapability::RevisionObservation,
946            ],
947        )?;
948    }
949    let parent_surface_id = has_document.then(|| root_id.clone());
950    let mut add_children = |kind: SurfaceKind,
951                            source: SurfaceEvidenceSource,
952                            request_source: EvidenceSource,
953                            count: usize,
954                            prefix: &str|
955     -> Result<(), ExtractionContractError> {
956        if !available(request_source) {
957            return Ok(());
958        }
959        for index in 0..count.min(256) {
960            if surfaces.len() >= 256 {
961                surface_bound_omitted = true;
962                break;
963            }
964            let structured_svg =
965                matches!(&kind, SurfaceKind::Svg) && context.dom.as_ref().is_some_and(has_svg_node);
966            let (understanding, semantic, capabilities) = if structured_svg {
967                (
968                    UnderstandingLevel::Semantic,
969                    CoverageLevel::Strong,
970                    vec![
971                        SurfaceCapability::ReadStructure,
972                        SurfaceCapability::ReadText,
973                        SurfaceCapability::ReadRelations,
974                        SurfaceCapability::Extraction,
975                    ],
976                )
977            } else {
978                (
979                    UnderstandingLevel::Structural,
980                    CoverageLevel::Partial,
981                    vec![SurfaceCapability::ReadStructure],
982                )
983            };
984            add(
985                &mut surfaces,
986                format!("{prefix}_{index}"),
987                parent_surface_id.clone(),
988                kind.clone(),
989                vec![evidence(
990                    source,
991                    format!("observed {prefix} boundary"),
992                    quality,
993                )],
994                understanding,
995                SurfaceCoverage {
996                    structural: quality,
997                    semantic,
998                    interaction: InteractionCoverage::Unavailable,
999                },
1000                capabilities,
1001            )?;
1002        }
1003        Ok(())
1004    };
1005    add_children(
1006        SurfaceKind::FrameDocument,
1007        SurfaceEvidenceSource::Frame,
1008        EvidenceSource::Frames,
1009        context.boundaries.child_frames,
1010        "frame",
1011    )?;
1012    add_children(
1013        SurfaceKind::ShadowDocument,
1014        SurfaceEvidenceSource::ShadowDom,
1015        EvidenceSource::ShadowDom,
1016        context.boundaries.shadow_roots,
1017        "shadow",
1018    )?;
1019    add_children(
1020        SurfaceKind::Svg,
1021        SurfaceEvidenceSource::Svg,
1022        EvidenceSource::Svg,
1023        context.boundaries.svg_elements,
1024        "svg",
1025    )?;
1026    add_children(
1027        SurfaceKind::Media,
1028        SurfaceEvidenceSource::MediaMetadata,
1029        EvidenceSource::MediaMetadata,
1030        context.boundaries.media_elements,
1031        "media",
1032    )?;
1033    add_children(
1034        SurfaceKind::EmbeddedDocument,
1035        SurfaceEvidenceSource::EmbeddedDocument,
1036        EvidenceSource::EmbeddedDocument,
1037        context.boundaries.embedded_documents,
1038        "embedded",
1039    )?;
1040    add_children(
1041        SurfaceKind::Pdf,
1042        SurfaceEvidenceSource::Pdf,
1043        EvidenceSource::Pdf,
1044        context.boundaries.pdf_documents,
1045        "pdf",
1046    )?;
1047    add_children(
1048        SurfaceKind::BrowserNative,
1049        SurfaceEvidenceSource::BrowserNative,
1050        EvidenceSource::BrowserNative,
1051        context.boundaries.native_surfaces,
1052        "native",
1053    )?;
1054
1055    let canvas_2d = if context.boundaries.canvas_2d == 0
1056        && context.boundaries.webgl_canvases == 0
1057        && context.boundaries.webgpu_canvases == 0
1058    {
1059        context.boundaries.canvases
1060    } else {
1061        context.boundaries.canvas_2d
1062    };
1063    for (kind, count, prefix) in [
1064        (SurfaceKind::Canvas2d, canvas_2d, "canvas2d"),
1065        (
1066            SurfaceKind::Webgl,
1067            context.boundaries.webgl_canvases,
1068            "webgl",
1069        ),
1070        (
1071            SurfaceKind::Webgpu,
1072            context.boundaries.webgpu_canvases,
1073            "webgpu",
1074        ),
1075    ] {
1076        if !available(EvidenceSource::CanvasDetection) {
1077            continue;
1078        }
1079        for index in 0..count.min(256) {
1080            if surfaces.len() >= 256 {
1081                surface_bound_omitted = true;
1082                break;
1083            }
1084            add(
1085                &mut surfaces,
1086                format!("{prefix}_{index}"),
1087                parent_surface_id.clone(),
1088                kind.clone(),
1089                vec![evidence(
1090                    SurfaceEvidenceSource::CanvasDetection,
1091                    format!("observed {prefix} graphics boundary"),
1092                    CoverageLevel::Strong,
1093                )],
1094                UnderstandingLevel::CoordinateOnly,
1095                SurfaceCoverage {
1096                    structural: CoverageLevel::Partial,
1097                    semantic: CoverageLevel::Partial,
1098                    interaction: InteractionCoverage::CoordinateOnly,
1099                },
1100                vec![
1101                    SurfaceCapability::CoordinateAction,
1102                    SurfaceCapability::Capture,
1103                ],
1104            )?;
1105        }
1106    }
1107    if context.boundaries.truncated && surfaces.len() < 256 && available(EvidenceSource::Layout) {
1108        add(
1109            &mut surfaces,
1110            "opaque_boundary".into(),
1111            parent_surface_id,
1112            SurfaceKind::Opaque,
1113            vec![evidence(
1114                SurfaceEvidenceSource::Layout,
1115                "bounded observation omitted surface details".into(),
1116                CoverageLevel::Opaque,
1117            )],
1118            UnderstandingLevel::Opaque,
1119            SurfaceCoverage::OPAQUE,
1120            Vec::new(),
1121        )?;
1122    }
1123    if surface_bound_omitted && let Some(surface) = surfaces.first_mut() {
1124        surface.diagnostics.push(SurfaceDiagnostic {
1125            severity: DiagnosticSeverity::Warning,
1126            code: "surfaceBound".into(),
1127            message: "additional observed surfaces omitted at the contract bound".into(),
1128        });
1129    }
1130    if surfaces.is_empty() {
1131        return Ok(None);
1132    }
1133    let set = SurfaceSet {
1134        schema_version: SURFACE_SCHEMA_VERSION,
1135        surfaces,
1136    };
1137    set.validate()
1138        .map_err(|error| ExtractionContractError::new("surfaceSet", error.to_string()))?;
1139    Ok(Some(set))
1140}
1141
1142fn validate_observation_boundaries(context: &PageContext) -> Result<(), ExtractionContractError> {
1143    let boundaries = &context.boundaries;
1144    if boundaries.scan_limit > 0 && boundaries.scanned_elements > boundaries.scan_limit {
1145        return Err(ExtractionContractError::new(
1146            "boundaries.scannedElements",
1147            "observed element count exceeds the browser boundary scan limit",
1148        ));
1149    }
1150    if boundaries.scanned_elements > 0 {
1151        let counters = [
1152            ("shadowRoots", boundaries.shadow_roots),
1153            ("childFrames", boundaries.child_frames),
1154            ("canvases", boundaries.canvases),
1155            ("svgElements", boundaries.svg_elements),
1156            ("mediaElements", boundaries.media_elements),
1157            ("embeddedDocuments", boundaries.embedded_documents),
1158            ("pdfDocuments", boundaries.pdf_documents),
1159        ];
1160        if let Some((name, _count)) = counters
1161            .into_iter()
1162            .find(|(_, count)| *count > boundaries.scanned_elements)
1163        {
1164            return Err(ExtractionContractError::new(
1165                format!("boundaries.{name}"),
1166                "surface count exceeds the observed element count",
1167            ));
1168        }
1169    }
1170    if boundaries.pdf_documents > boundaries.embedded_documents {
1171        return Err(ExtractionContractError::new(
1172            "boundaries.pdfDocuments",
1173            "PDF surface count cannot exceed embedded document count",
1174        ));
1175    }
1176    let classified_canvases = boundaries
1177        .canvas_2d
1178        .saturating_add(boundaries.webgl_canvases)
1179        .saturating_add(boundaries.webgpu_canvases);
1180    if classified_canvases > boundaries.canvases {
1181        return Err(ExtractionContractError::new(
1182            "boundaries.canvasClassification",
1183            "graphics subtype counts cannot exceed the observed canvas count",
1184        ));
1185    }
1186    Ok(())
1187}
1188
1189struct EvidenceCollector {
1190    budgets: ExtractionBudgets,
1191    deadline: Instant,
1192    facts: Vec<EvidenceFact>,
1193    inspected_nodes: u32,
1194    omitted_facts: u32,
1195    text_bytes: u32,
1196    truncated: bool,
1197    timed_out: bool,
1198}
1199
1200impl EvidenceCollector {
1201    fn new(budgets: ExtractionBudgets) -> Self {
1202        Self {
1203            deadline: Instant::now() + Duration::from_millis(budgets.max_duration_ms),
1204            budgets,
1205            facts: Vec::new(),
1206            inspected_nodes: 0,
1207            omitted_facts: 0,
1208            text_bytes: 0,
1209            truncated: false,
1210            timed_out: false,
1211        }
1212    }
1213
1214    fn deadline_reached(&self) -> bool {
1215        Instant::now() >= self.deadline
1216    }
1217
1218    fn mark_timeout(&mut self) {
1219        self.timed_out = true;
1220        self.mark_omitted();
1221    }
1222
1223    fn allow_node(&mut self, depth: u16) -> bool {
1224        if self.deadline_reached() {
1225            self.mark_timeout();
1226            return false;
1227        }
1228        if depth >= self.budgets.max_depth || self.node_budget_exhausted() {
1229            self.mark_omitted();
1230            return false;
1231        }
1232        self.inspected_nodes = self.inspected_nodes.saturating_add(1);
1233        true
1234    }
1235
1236    fn node_budget_exhausted(&self) -> bool {
1237        self.inspected_nodes >= self.budgets.max_nodes
1238    }
1239
1240    fn mark_omitted(&mut self) {
1241        self.omitted_facts = self.omitted_facts.saturating_add(1);
1242        self.truncated = true;
1243    }
1244
1245    fn push(&mut self, mut fact: EvidenceFact) {
1246        if self.deadline_reached() {
1247            self.mark_timeout();
1248            return;
1249        }
1250        fact.role = self.bound_text(fact.role.take());
1251        fact.name = self.bound_text(fact.name.take());
1252        fact.parent_role = self.bound_text(fact.parent_role.take());
1253        fact.input_type = self.bound_text(fact.input_type.take());
1254        self.facts.push(fact);
1255    }
1256
1257    fn bound_text(&mut self, value: Option<String>) -> Option<String> {
1258        let value = value?;
1259        let remaining = self.budgets.max_text_bytes.saturating_sub(self.text_bytes) as usize;
1260        if remaining == 0 {
1261            self.truncated = true;
1262            return None;
1263        }
1264        let bounded = truncate_utf8(&value, remaining);
1265        if bounded.is_empty() {
1266            self.truncated |= !value.is_empty();
1267            return None;
1268        }
1269
1270        self.text_bytes = self.text_bytes.saturating_add(bounded.len() as u32);
1271        if bounded.len() < value.len() {
1272            self.truncated = true;
1273        }
1274        Some(bounded)
1275    }
1276}
1277fn observation_has_mutation_race(context: &PageContext) -> bool {
1278    !context.consistency.consistent
1279        || context.consistency.start_revision != context.consistency.end_revision
1280        || context.consistency.start_mutation_revision != context.consistency.end_mutation_revision
1281}
1282
1283fn evidence_coverage(
1284    context: &PageContext,
1285    sources: &[EvidenceSource],
1286    missing_sources: &BTreeSet<EvidenceSource>,
1287    truncated: bool,
1288    timed_out: bool,
1289    inconsistent_observation: bool,
1290) -> EvidenceCoverage {
1291    let requested = |source| sources.contains(&source);
1292    let available = |source| requested(source) && !missing_sources.contains(&source);
1293    let mut structural = if available(EvidenceSource::Dom) && !truncated {
1294        EvidenceQuality::Strong
1295    } else if available(EvidenceSource::Dom) || available(EvidenceSource::Accessibility) {
1296        EvidenceQuality::Partial
1297    } else {
1298        EvidenceQuality::Opaque
1299    };
1300    let mut semantic = if available(EvidenceSource::Accessibility) && !truncated {
1301        EvidenceQuality::Strong
1302    } else if requested(EvidenceSource::Accessibility) {
1303        EvidenceQuality::Partial
1304    } else {
1305        EvidenceQuality::Opaque
1306    };
1307    if inconsistent_observation {
1308        if structural != EvidenceQuality::Opaque {
1309            structural = EvidenceQuality::Partial;
1310        }
1311        if semantic != EvidenceQuality::Opaque {
1312            semantic = EvidenceQuality::Partial;
1313        }
1314    }
1315    // Frames, shadow roots, and graphics are explicit boundaries with
1316    // structural or coordinate coverage; only an omitted boundary is opaque.
1317    let opaque_regions = u32::from(context.boundaries.truncated);
1318    let mut reasons = missing_sources
1319        .iter()
1320        .map(|source| format!("missingSource:{source:?}"))
1321        .collect::<Vec<_>>();
1322    if truncated {
1323        reasons.push("budgetTruncated".into());
1324    }
1325    if timed_out {
1326        reasons.push("timeBudgetExceeded".into());
1327    }
1328    if inconsistent_observation {
1329        reasons.push("mutationRace".into());
1330    }
1331    if context.boundaries.child_frames > 0 {
1332        reasons.push("frameBoundary".into());
1333    }
1334    if context.boundaries.shadow_roots > 0 {
1335        reasons.push("shadowBoundary".into());
1336    }
1337    if context.boundaries.canvases > 0 {
1338        reasons.push("canvasBoundary".into());
1339    }
1340    reasons.truncate(16);
1341    EvidenceCoverage {
1342        structural,
1343        semantic,
1344
1345        interactive_entities_observed: context.accessibility.interactive.len() as u32,
1346        opaque_regions,
1347        reasons,
1348    }
1349}
1350fn safe_parent_role(value: &str) -> Option<String> {
1351    let role = value.trim();
1352    if role.is_empty() || role.len() > 64 {
1353        return None;
1354    }
1355    let known_role = matches!(
1356        role.to_ascii_lowercase().as_str(),
1357        "alert"
1358            | "article"
1359            | "banner"
1360            | "button"
1361            | "cell"
1362            | "checkbox"
1363            | "columnheader"
1364            | "combobox"
1365            | "complementary"
1366            | "dialog"
1367            | "document"
1368            | "form"
1369            | "grid"
1370            | "heading"
1371            | "img"
1372            | "link"
1373            | "list"
1374            | "listbox"
1375            | "main"
1376            | "menu"
1377            | "menuitem"
1378            | "navigation"
1379            | "option"
1380            | "radio"
1381            | "region"
1382            | "row"
1383            | "rowheader"
1384            | "search"
1385            | "slider"
1386            | "spinbutton"
1387            | "status"
1388            | "switch"
1389            | "tab"
1390            | "table"
1391            | "textbox"
1392            | "toolbar"
1393            | "tree"
1394    );
1395    known_role.then(|| role.to_owned())
1396}
1397
1398fn nearest_safe_parent_role(ancestor_path: &[String]) -> Option<String> {
1399    ancestor_path.iter().rev().find_map(|value| {
1400        let role = value
1401            .split_once(':')
1402            .map_or(value.as_str(), |(role, _)| role);
1403        safe_parent_role(role)
1404    })
1405}
1406
1407fn is_form_control_role(role: &str) -> bool {
1408    matches!(
1409        role,
1410        "checkbox"
1411            | "combobox"
1412            | "listbox"
1413            | "radio"
1414            | "slider"
1415            | "spinbutton"
1416            | "switch"
1417            | "textbox"
1418    )
1419}
1420
1421fn custom_form_control_hint(
1422    control_role: &str,
1423    parent_role: Option<&str>,
1424) -> Option<EvidenceRelationshipHint> {
1425    if parent_role.is_some_and(|role| role.eq_ignore_ascii_case("form"))
1426        && matches!(
1427            control_role,
1428            "checkbox" | "combobox" | "listbox" | "radio" | "slider" | "spinbutton" | "switch"
1429        )
1430    {
1431        Some(EvidenceRelationshipHint::Controls)
1432    } else {
1433        None
1434    }
1435}
1436fn is_region_role(role: &str) -> bool {
1437    matches!(
1438        role,
1439        "article" | "complementary" | "main" | "navigation" | "region" | "search" | "toolbar"
1440    )
1441}
1442
1443fn control_in_region(
1444    control: &CompactInteractiveElement,
1445    region_root: Option<&CompactAxNode>,
1446) -> bool {
1447    let Some(region_root) = region_root else {
1448        return true;
1449    };
1450    control.ancestor_path.iter().any(|ancestor| {
1451        let (role, name) = ancestor.split_once(':').unwrap_or((ancestor, ""));
1452        role.eq_ignore_ascii_case(&region_root.role)
1453            && (region_root.name.is_empty() || name.eq_ignore_ascii_case(&region_root.name))
1454    })
1455}
1456
1457fn semantic_source_matches(source: EvidenceSource, role: &str) -> bool {
1458    match source {
1459        EvidenceSource::Navigation => {
1460            matches!(role, "navigation" | "link" | "tab" | "menu" | "menuitem")
1461        }
1462        EvidenceSource::Tables => matches!(
1463            role,
1464            "table" | "grid" | "row" | "cell" | "gridcell" | "columnheader" | "rowheader"
1465        ),
1466        EvidenceSource::Collections => {
1467            matches!(role, "list" | "listitem" | "feed" | "article")
1468        }
1469        EvidenceSource::Dialogs => {
1470            matches!(role, "dialog" | "alertdialog" | "alert" | "status")
1471        }
1472        _ => false,
1473    }
1474}
1475
1476fn collect_semantic_source(
1477    node: &CompactAxNode,
1478    source: EvidenceSource,
1479    collector: &mut EvidenceCollector,
1480    depth: u16,
1481    parent_role: Option<&str>,
1482) {
1483    if !collector.allow_node(depth) {
1484        return;
1485    }
1486    if semantic_source_matches(source, &node.role) {
1487        collector.push(EvidenceFact {
1488            source,
1489            kind: "semantic".into(),
1490            quality: EvidenceQuality::Confirmed,
1491            role: Some(node.role.clone()),
1492            name: Some(node.name.clone()),
1493            input_type: None,
1494            autocomplete: None,
1495            required: None,
1496            read_only: None,
1497            empty: None,
1498            checked: None,
1499            disabled: None,
1500            geometry_present: None,
1501            parent_role: parent_role.map(str::to_owned),
1502            relationship_hint: None,
1503        });
1504    }
1505    let next_parent_role = safe_parent_role(&node.role).or_else(|| parent_role.map(str::to_owned));
1506    for child in &node.children {
1507        if collector.node_budget_exhausted() {
1508            collector.mark_omitted();
1509            break;
1510        }
1511        collect_semantic_source(
1512            child,
1513            source,
1514            collector,
1515            depth.saturating_add(1),
1516            next_parent_role.as_deref(),
1517        );
1518    }
1519}
1520
1521fn push_boundary_fact(
1522    collector: &mut EvidenceCollector,
1523    source: EvidenceSource,
1524    role: &str,
1525    name: String,
1526) {
1527    if !collector.allow_node(0) {
1528        return;
1529    }
1530    collector.push(EvidenceFact {
1531        source,
1532        kind: "boundary".into(),
1533        quality: EvidenceQuality::Strong,
1534        role: Some(role.into()),
1535        name: Some(name),
1536        input_type: None,
1537        autocomplete: None,
1538        required: None,
1539        read_only: None,
1540        empty: None,
1541        checked: None,
1542        disabled: None,
1543        geometry_present: None,
1544        parent_role: None,
1545        relationship_hint: None,
1546    });
1547}
1548
1549fn collect_accessibility(
1550    node: &CompactAxNode,
1551    collector: &mut EvidenceCollector,
1552    depth: u16,
1553    parent_role: Option<&str>,
1554) {
1555    if !collector.allow_node(depth) {
1556        return;
1557    }
1558    if !node.interactive {
1559        collector.push(EvidenceFact {
1560            source: EvidenceSource::Accessibility,
1561            kind: "node".into(),
1562            quality: EvidenceQuality::Confirmed,
1563            role: Some(node.role.clone()),
1564            name: Some(node.name.clone()),
1565            input_type: None,
1566            autocomplete: None,
1567            required: None,
1568            read_only: None,
1569            empty: None,
1570            checked: None,
1571            disabled: None,
1572            geometry_present: None,
1573            parent_role: parent_role.map(str::to_owned),
1574            relationship_hint: None,
1575        });
1576    }
1577    let next_parent_role = if is_region_role(&node.role) {
1578        Some(node.role.as_str())
1579    } else {
1580        parent_role
1581    };
1582    for child in &node.children {
1583        if collector.node_budget_exhausted() {
1584            collector.mark_omitted();
1585            break;
1586        }
1587        collect_accessibility(child, collector, depth.saturating_add(1), next_parent_role);
1588    }
1589}
1590
1591fn collect_accessibility_control(
1592    control: &CompactInteractiveElement,
1593    collector: &mut EvidenceCollector,
1594) {
1595    if matches!(
1596        control.role.to_ascii_lowercase().as_str(),
1597        "rootwebarea" | "webarea" | "document"
1598    ) {
1599        return;
1600    }
1601    let parent_role = nearest_safe_parent_role(&control.ancestor_path);
1602    collector.push(EvidenceFact {
1603        source: EvidenceSource::Accessibility,
1604        kind: "control".into(),
1605        quality: EvidenceQuality::Confirmed,
1606        role: Some(control.role.clone()),
1607        name: Some(control.name.clone()),
1608        input_type: control.input_type.clone(),
1609        autocomplete: control.autocomplete.clone(),
1610        required: Some(control.required),
1611        read_only: Some(control.read_only),
1612        empty: Some(control.empty),
1613        checked: control.checked,
1614        disabled: control.disabled,
1615        geometry_present: None,
1616        parent_role,
1617        relationship_hint: None,
1618    });
1619}
1620
1621fn has_svg_node(node: &DomNode) -> bool {
1622    if node.node_name.eq_ignore_ascii_case("svg") {
1623        return true;
1624    }
1625    node.children.iter().any(has_svg_node)
1626}
1627
1628fn svg_attribute(node: &DomNode, name: &str) -> Option<String> {
1629    node.attributes
1630        .as_chunks::<2>()
1631        .0
1632        .iter()
1633        .find(|pair| pair[0].eq_ignore_ascii_case(name))
1634        .map(|pair| pair[1].clone())
1635}
1636
1637/// Extract a conservative semantic projection from structured SVG markup.
1638/// Geometry and paint are intentionally omitted; only bounded roles/names are
1639/// promoted to Web IR facts.
1640fn collect_svg_semantics(
1641    node: &DomNode,
1642    collector: &mut EvidenceCollector,
1643    depth: u16,
1644    inside_svg: bool,
1645) {
1646    if !collector.allow_node(depth) {
1647        return;
1648    }
1649    let tag = node.node_name.to_ascii_lowercase();
1650    let in_svg = inside_svg || tag == "svg";
1651    if in_svg {
1652        let (role, name) = match tag.as_str() {
1653            "svg" => (
1654                "region",
1655                svg_attribute(node, "aria-label")
1656                    .or_else(|| svg_attribute(node, "title"))
1657                    .or_else(|| svg_attribute(node, "id")),
1658            ),
1659            "a" => (
1660                "link",
1661                svg_attribute(node, "aria-label").or_else(|| svg_attribute(node, "href")),
1662            ),
1663            "text" | "title" | "desc" => (
1664                "text",
1665                (!node.node_value.is_empty()).then(|| node.node_value.clone()),
1666            ),
1667            _ => ("", None),
1668        };
1669        if !role.is_empty() {
1670            collector.push(EvidenceFact {
1671                source: EvidenceSource::Svg,
1672                kind: tag.clone(),
1673                quality: EvidenceQuality::Confirmed,
1674                role: Some(role.into()),
1675                name,
1676                parent_role: None,
1677                relationship_hint: None,
1678                input_type: None,
1679                autocomplete: None,
1680                required: None,
1681                read_only: None,
1682                empty: None,
1683                checked: None,
1684                disabled: None,
1685                geometry_present: Some(node.bounding_box.is_some()),
1686            });
1687        }
1688    }
1689    for child in &node.children {
1690        if collector.node_budget_exhausted() {
1691            collector.mark_omitted();
1692            break;
1693        }
1694        collect_svg_semantics(child, collector, depth.saturating_add(1), in_svg);
1695    }
1696}
1697
1698fn collect_dom(node: &DomNode, collector: &mut EvidenceCollector, depth: u16) {
1699    if !collector.allow_node(depth) {
1700        return;
1701    }
1702    collector.push(EvidenceFact {
1703        source: EvidenceSource::Dom,
1704        kind: "element".into(),
1705        quality: EvidenceQuality::Confirmed,
1706        role: None,
1707        name: Some(node.node_name.clone()),
1708        input_type: None,
1709        autocomplete: None,
1710        required: None,
1711        read_only: None,
1712        empty: None,
1713        checked: None,
1714        disabled: None,
1715        geometry_present: None,
1716        parent_role: None,
1717        relationship_hint: None,
1718    });
1719    for child in &node.children {
1720        if collector.node_budget_exhausted() {
1721            collector.mark_omitted();
1722            break;
1723        }
1724        collect_dom(child, collector, depth.saturating_add(1));
1725    }
1726}
1727
1728fn collect_layout(
1729    node: &DomNode,
1730    collector: &mut EvidenceCollector,
1731    source: EvidenceSource,
1732    depth: u16,
1733) {
1734    if !collector.allow_node(depth) {
1735        return;
1736    }
1737    collector.push(EvidenceFact {
1738        source,
1739        kind: "geometry".into(),
1740        quality: EvidenceQuality::Strong,
1741        role: None,
1742        name: Some(node.node_name.clone()),
1743        input_type: None,
1744        autocomplete: None,
1745        required: None,
1746        read_only: None,
1747        empty: None,
1748        checked: None,
1749        disabled: None,
1750        geometry_present: Some(node.bounding_box.is_some()),
1751        parent_role: None,
1752        relationship_hint: None,
1753    });
1754    for child in &node.children {
1755        if collector.node_budget_exhausted() {
1756            collector.mark_omitted();
1757            break;
1758        }
1759        collect_layout(child, collector, source, depth.saturating_add(1));
1760    }
1761}
1762
1763fn trim_to_output_budget(
1764    evidence: &mut ExtractionEvidence,
1765    max_output_bytes: u32,
1766) -> Result<(), ExtractionContractError> {
1767    let mut removed_fact = false;
1768    let mut removed_surface_set = false;
1769    while serde_json::to_vec(evidence)
1770        .map_err(|error| ExtractionContractError::new("$", error.to_string()))?
1771        .len()
1772        > max_output_bytes as usize
1773    {
1774        if evidence.facts.pop().is_none() {
1775            if evidence.surface_set.take().is_some() {
1776                removed_surface_set = true;
1777                evidence.limits.truncated = true;
1778                evidence
1779                    .coverage
1780                    .reasons
1781                    .push("surfaceSetBudgetTruncated".into());
1782                evidence.coverage.reasons.truncate(16);
1783                continue;
1784            }
1785            return Err(ExtractionContractError::new(
1786                "budgets.maxOutputBytes",
1787                "output budget is too small for extraction metadata",
1788            ));
1789        }
1790        if !removed_fact {
1791            evidence.coverage.structural = downgrade_coverage(evidence.coverage.structural);
1792            evidence.coverage.semantic = downgrade_coverage(evidence.coverage.semantic);
1793            if !evidence
1794                .coverage
1795                .reasons
1796                .iter()
1797                .any(|reason| reason == "budgetTruncated")
1798            {
1799                evidence.coverage.reasons.push("budgetTruncated".into());
1800                evidence.coverage.reasons.truncate(16);
1801            }
1802        }
1803        removed_fact = true;
1804        evidence.limits.omitted_facts = evidence.limits.omitted_facts.saturating_add(1);
1805        evidence.limits.truncated = true;
1806        evidence.limits.text_bytes = evidence.facts.iter().map(fact_text_bytes).sum::<u32>();
1807    }
1808    evidence.limits.text_bytes = evidence.facts.iter().map(fact_text_bytes).sum::<u32>();
1809    if removed_fact || removed_surface_set {
1810        evidence.coverage.structural = downgrade_coverage(evidence.coverage.structural);
1811        evidence.coverage.semantic = downgrade_coverage(evidence.coverage.semantic);
1812    }
1813    Ok(())
1814}
1815
1816fn downgrade_coverage(quality: EvidenceQuality) -> EvidenceQuality {
1817    if quality == EvidenceQuality::Opaque {
1818        EvidenceQuality::Opaque
1819    } else {
1820        EvidenceQuality::Partial
1821    }
1822}
1823
1824fn fact_text_bytes(fact: &EvidenceFact) -> u32 {
1825    [
1826        fact.role.as_deref(),
1827        fact.name.as_deref(),
1828        fact.parent_role.as_deref(),
1829        fact.input_type.as_deref(),
1830    ]
1831    .into_iter()
1832    .flatten()
1833    .map(|value| value.len() as u32)
1834    .sum()
1835}
1836
1837fn truncate_utf8(value: &str, max_bytes: usize) -> String {
1838    if value.len() <= max_bytes {
1839        return value.to_owned();
1840    }
1841    let mut end = max_bytes;
1842    while !value.is_char_boundary(end) {
1843        end -= 1;
1844    }
1845    value[..end].to_owned()
1846}
1847
1848/// A machine-readable extraction contract error.
1849#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
1850#[serde(rename_all = "camelCase")]
1851pub struct ExtractionContractError {
1852    pub path: String,
1853    pub reason: String,
1854}
1855
1856impl ExtractionContractError {
1857    fn new(path: impl Into<String>, reason: impl Into<String>) -> Self {
1858        Self {
1859            path: path.into(),
1860            reason: reason.into(),
1861        }
1862    }
1863}
1864
1865impl Display for ExtractionContractError {
1866    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
1867        write!(formatter, "{}: {}", self.path, self.reason)
1868    }
1869}
1870
1871impl std::error::Error for ExtractionContractError {}
1872
1873fn validate_identifier(path: &str, value: &str) -> Result<(), ExtractionContractError> {
1874    if value.is_empty() || value.len() > 256 || value.chars().any(char::is_control) {
1875        return Err(ExtractionContractError::new(
1876            path,
1877            "identifier must contain 1-256 non-control characters",
1878        ));
1879    }
1880    Ok(())
1881}
1882
1883fn validate_positive_bounded<T>(
1884    path: &str,
1885    value: T,
1886    maximum: T,
1887) -> Result<(), ExtractionContractError>
1888where
1889    T: Copy + PartialOrd + From<u8>,
1890{
1891    if value < T::from(1) || value > maximum {
1892        return Err(ExtractionContractError::new(
1893            path,
1894            "value must be positive and within the extraction contract bound",
1895        ));
1896    }
1897    Ok(())
1898}
1899
1900#[cfg(test)]
1901mod tests {
1902    use super::*;
1903    use crate::surfaces::SEMANTIC_BRIDGE_SCHEMA_VERSION;
1904    use serde_json::json;
1905
1906    fn request() -> ExtractionRequest {
1907        ExtractionRequest {
1908            schema_version: EXTRACTION_CONTRACT_SCHEMA_VERSION,
1909            scope: ExtractionScope::Document,
1910            sources: vec![EvidenceSource::Accessibility, EvidenceSource::Forms],
1911            budgets: ExtractionBudgets::default(),
1912        }
1913    }
1914
1915    #[test]
1916    fn request_accepts_bounded_non_mutating_sources() {
1917        let request = request();
1918        assert!(request.validate().is_ok());
1919        assert_eq!(
1920            request.to_canonical_json().unwrap(),
1921            request.to_canonical_json().unwrap()
1922        );
1923    }
1924
1925    #[test]
1926    fn default_document_request_matches_live_evidence_contract() {
1927        let request = ExtractionRequest::default_document();
1928        assert!(request.validate().is_ok());
1929        assert_eq!(request.scope, ExtractionScope::Document);
1930        assert!(request.sources.contains(&EvidenceSource::Accessibility));
1931        assert!(request.sources.contains(&EvidenceSource::BoundedProbe));
1932    }
1933
1934    #[test]
1935    fn request_rejects_duplicate_sources() {
1936        let mut request = request();
1937        request.sources.push(EvidenceSource::Forms);
1938        let error = request.validate().unwrap_err();
1939        assert_eq!(error.path, "sources");
1940    }
1941
1942    #[test]
1943    fn request_rejects_budget_overflow_and_zero() {
1944        let mut request = request();
1945        request.budgets.max_nodes = 0;
1946        assert_eq!(request.validate().unwrap_err().path, "budgets.maxNodes");
1947        request.budgets.max_nodes = MAX_EXTRACTION_NODES + 1;
1948        assert_eq!(request.validate().unwrap_err().path, "budgets.maxNodes");
1949    }
1950
1951    #[test]
1952    fn request_rejects_unknown_authored_fields() {
1953        let value = json!({
1954            "schemaVersion": 1,
1955            "scope": "document",
1956            "sources": ["accessibility"],
1957            "budgets": ExtractionBudgets::default(),
1958            "futureField": true
1959        });
1960        assert!(ExtractionRequest::from_json(&value.to_string()).is_err());
1961    }
1962
1963    #[test]
1964    fn scoped_requests_require_bounded_identifiers() {
1965        let mut request = request();
1966        request.scope = ExtractionScope::Region {
1967            region_id: "".into(),
1968        };
1969        assert_eq!(request.validate().unwrap_err().path, "scope.regionId");
1970    }
1971    fn page_context() -> PageContext {
1972        use crate::browser::dom::{CompactAxNode, CompactInteractiveElement, DomNode};
1973        use crate::browser::session::{
1974            CompactAccessibilitySnapshot, ObservationBoundarySummary, ObservationConsistency,
1975            PageInfo,
1976        };
1977
1978        let page = PageInfo {
1979            url: "https://example.test/form".into(),
1980            title: "Example form".into(),
1981            ready_state: "interactive".into(),
1982            target_id: "target-1".into(),
1983            frame_id: "frame-1".into(),
1984        };
1985        let accessibility = CompactAccessibilitySnapshot {
1986            page: page.clone(),
1987            revision: 7,
1988            roots: vec![CompactAxNode {
1989                role: "form".into(),
1990                name: "Example form".into(),
1991                children: vec![CompactAxNode {
1992                    role: "textbox".into(),
1993                    name: "Full name".into(),
1994                    children: Vec::new(),
1995                    interactive: true,
1996                }],
1997                interactive: false,
1998            }],
1999            interactive: vec![CompactInteractiveElement {
2000                reference: "axr-1-1".into(),
2001                role: "textbox".into(),
2002                name: "Full name".into(),
2003                backend_dom_node_id: 11,
2004                ancestor_path: Vec::new(),
2005                shadow_host_path: None,
2006                input_type: Some("text".into()),
2007                autocomplete: Some("name".into()),
2008                value: Some("secret-value".into()),
2009                checked: None,
2010                disabled: None,
2011                selected_option: None,
2012                empty: true,
2013                read_only: false,
2014                required: true,
2015            }],
2016            truncated: false,
2017            omitted_count: 0,
2018            ranking_applied: false,
2019            completeness: None,
2020        };
2021        PageContext {
2022            page,
2023            text: "secret-value".into(),
2024            dom: Some(DomNode {
2025                node_id: 1,
2026                node_name: "HTML".into(),
2027                node_value: String::new(),
2028                children: vec![DomNode {
2029                    node_id: 2,
2030                    node_name: "INPUT".into(),
2031                    node_value: String::new(),
2032                    children: Vec::new(),
2033                    attributes: vec!["type".into(), "text".into()],
2034                    bounding_box: Some([0.0, 0.0, 120.0, 24.0]),
2035                }],
2036                attributes: Vec::new(),
2037                bounding_box: Some([0.0, 0.0, 800.0, 600.0]),
2038            }),
2039            accessibility,
2040            consistency: ObservationConsistency {
2041                consistent: true,
2042                attempts: 1,
2043                start_revision: 7,
2044                end_revision: 7,
2045                start_mutation_revision: 0,
2046                end_mutation_revision: 0,
2047            },
2048            boundaries: ObservationBoundarySummary::default(),
2049            incomplete: Vec::new(),
2050            screenshot: None,
2051        }
2052    }
2053
2054    #[test]
2055    fn extraction_collects_supported_sources_without_confusing_absence_and_missing_evidence() {
2056        let mut request = request();
2057        request.sources = vec![
2058            EvidenceSource::Accessibility,
2059            EvidenceSource::Dom,
2060            EvidenceSource::Forms,
2061            EvidenceSource::Layout,
2062            EvidenceSource::Navigation,
2063        ];
2064        let evidence = extract_page_context(&page_context(), &request).unwrap();
2065        assert_eq!(evidence.revision, 7);
2066        assert!(!evidence.facts.is_empty());
2067        assert_eq!(evidence.coverage.structural, EvidenceQuality::Strong);
2068        assert_eq!(evidence.coverage.semantic, EvidenceQuality::Strong);
2069        assert_eq!(
2070            evidence.facts.first().map(|fact| fact.quality),
2071            Some(EvidenceQuality::Confirmed)
2072        );
2073        assert!(evidence.limits.missing_sources.is_empty());
2074        assert!(evidence.facts.iter().any(|fact| {
2075            fact.source == EvidenceSource::Accessibility
2076                && fact.role.as_deref() == Some("textbox")
2077                && fact.name.as_deref() == Some("Full name")
2078                && fact.input_type.as_deref() == Some("text")
2079        }));
2080        assert!(
2081            !serde_json::to_string(&evidence)
2082                .unwrap()
2083                .contains("secret-value")
2084        );
2085    }
2086
2087    #[test]
2088    fn extraction_reconciles_compatible_multi_surface_observation() {
2089        let mut context = page_context();
2090        context.boundaries = crate::browser::session::ObservationBoundarySummary {
2091            canvases: 3,
2092            canvas_2d: 1,
2093            webgl_canvases: 1,
2094            webgpu_canvases: 1,
2095            child_frames: 1,
2096            shadow_roots: 1,
2097            svg_elements: 1,
2098            media_elements: 1,
2099            embedded_documents: 1,
2100            pdf_documents: 1,
2101            native_surfaces: 1,
2102            truncated: true,
2103            ..Default::default()
2104        };
2105        let mut request = request();
2106        request.sources = vec![
2107            EvidenceSource::Accessibility,
2108            EvidenceSource::Dom,
2109            EvidenceSource::Layout,
2110            EvidenceSource::Frames,
2111            EvidenceSource::ShadowDom,
2112            EvidenceSource::Svg,
2113            EvidenceSource::CanvasDetection,
2114            EvidenceSource::MediaMetadata,
2115            EvidenceSource::EmbeddedDocument,
2116            EvidenceSource::Pdf,
2117            EvidenceSource::BrowserNative,
2118        ];
2119        let evidence = extract_page_context(&context, &request).unwrap();
2120        let surfaces = evidence.surface_set.as_ref().expect("surface evidence");
2121        surfaces.validate().unwrap();
2122        assert!(
2123            surfaces
2124                .surfaces
2125                .iter()
2126                .any(|surface| surface.kind == SurfaceKind::Webgl)
2127        );
2128        assert!(
2129            surfaces
2130                .surfaces
2131                .iter()
2132                .any(|surface| surface.kind == SurfaceKind::Webgpu)
2133        );
2134        assert!(
2135            surfaces
2136                .surfaces
2137                .iter()
2138                .any(|surface| surface.kind == SurfaceKind::BrowserNative)
2139        );
2140        let embedded = surfaces
2141            .surfaces
2142            .iter()
2143            .find(|surface| surface.kind == SurfaceKind::EmbeddedDocument)
2144            .expect("embedded boundary");
2145        assert_eq!(embedded.understanding, UnderstandingLevel::Structural);
2146        assert!(embedded.diagnostics.iter().any(|diagnostic| {
2147            diagnostic.code == "semanticUnavailable"
2148                && diagnostic.severity == DiagnosticSeverity::Warning
2149        }));
2150        let opaque = surfaces
2151            .surfaces
2152            .iter()
2153            .find(|surface| surface.kind == SurfaceKind::Opaque)
2154            .expect("bounded omission should remain opaque");
2155        assert_eq!(opaque.understanding, UnderstandingLevel::Opaque);
2156        assert!(opaque.capabilities.is_empty());
2157        let ir = crate::web_ir::reconcile_evidence(&evidence).unwrap();
2158        for (surface_id, expected_kind) in [
2159            ("canvas2d_0", SurfaceKind::Canvas2d),
2160            ("embedded_0", SurfaceKind::EmbeddedDocument),
2161            ("pdf_0", SurfaceKind::Pdf),
2162        ] {
2163            let entity_id = ir
2164                .entity_details
2165                .iter()
2166                .find(|(_, details)| details.surface_id.as_deref() == Some(surface_id))
2167                .map(|(id, _)| id)
2168                .expect("surface entity details");
2169            assert_eq!(
2170                ir.entity_details[entity_id].surface_kind.as_ref(),
2171                Some(&expected_kind)
2172            );
2173            assert!(ir.relationships.iter().any(|relationship| {
2174                relationship.from == "page" && relationship.to == *entity_id
2175            }));
2176            assert!(ir.entity_details[entity_id].supported_actions.is_empty());
2177        }
2178        assert!(ir.diagnostics.iter().any(|diagnostic| {
2179            diagnostic.contains("embedded_0") && diagnostic.contains("semanticUnavailable")
2180        }));
2181        assert!(ir.surface_set.is_some());
2182        let mut malformed = evidence.clone();
2183        malformed.surface_set.as_mut().unwrap().schema_version = 99;
2184        assert!(crate::web_ir::reconcile_evidence(&malformed).is_err());
2185        let mut unauthorized = opaque.clone();
2186        unauthorized
2187            .capabilities
2188            .push(SurfaceCapability::SemanticAction);
2189        assert!(unauthorized.validate().is_err());
2190        let mut reversed = ir.clone();
2191        if let Some(surface_set) = &mut reversed.surface_set {
2192            surface_set.surfaces.reverse();
2193            for surface in &mut surface_set.surfaces {
2194                surface.evidence.reverse();
2195            }
2196        }
2197        assert_eq!(
2198            ir.to_canonical_json().unwrap(),
2199            reversed.to_canonical_json().unwrap()
2200        );
2201        let mut next_context = context.clone();
2202        next_context.accessibility.revision = 8;
2203        let next = extract_page_context(&next_context, &request).unwrap();
2204        let next_ir = crate::web_ir::reconcile_evidence(&next).unwrap();
2205        assert!(ir.diff(&next_ir).unwrap().surface_set_changed);
2206        assert!(ir.to_canonical_json().unwrap().contains("surfaceSet"));
2207    }
2208
2209    #[test]
2210    fn extraction_rejects_inconsistent_surface_boundary_counts() {
2211        let mut context = page_context();
2212        context.boundaries.canvases = 1;
2213        context.boundaries.webgl_canvases = 2;
2214        let error = extract_page_context(&context, &request()).unwrap_err();
2215        assert_eq!(error.path, "boundaries.canvasClassification");
2216
2217        context.boundaries.webgl_canvases = 0;
2218        context.boundaries.pdf_documents = 1;
2219        let error = extract_page_context(&context, &request()).unwrap_err();
2220        assert_eq!(error.path, "boundaries.pdfDocuments");
2221    }
2222
2223    #[test]
2224    fn extraction_classifies_specialized_surface_without_document_root() {
2225        let mut context = page_context();
2226        context.dom = None;
2227        context.accessibility.roots.clear();
2228        context.boundaries.canvases = 1;
2229        context.boundaries.canvas_2d = 0;
2230        let mut request = request();
2231        request.sources = vec![EvidenceSource::CanvasDetection];
2232        let evidence = extract_page_context(&context, &request).unwrap();
2233        let surfaces = evidence.surface_set.expect("canvas surface");
2234        assert_eq!(surfaces.surfaces.len(), 1);
2235        assert_eq!(surfaces.surfaces[0].kind, SurfaceKind::Canvas2d);
2236        assert!(surfaces.surfaces[0].parent_surface_id.is_none());
2237        surfaces.validate().unwrap();
2238    }
2239    #[test]
2240    fn extraction_emits_controls_hint_for_custom_form_roles() {
2241        let mut plain_request = request();
2242        plain_request.sources = vec![EvidenceSource::Forms];
2243        let plain_evidence = extract_page_context(&page_context(), &plain_request).unwrap();
2244        assert!(
2245            plain_evidence
2246                .facts
2247                .iter()
2248                .all(|fact| fact.relationship_hint.is_none())
2249        );
2250
2251        let mut context = page_context();
2252        context.accessibility.interactive[0].role = "combobox".into();
2253        context.accessibility.interactive[0].ancestor_path = vec![
2254            "form:Example form".into(),
2255            "label:Nested field label".into(),
2256        ];
2257        let mut request = request();
2258        request.sources = vec![EvidenceSource::Forms];
2259        let evidence = extract_page_context(&context, &request).unwrap();
2260        let fact = evidence
2261            .facts
2262            .iter()
2263            .find(|fact| fact.source == EvidenceSource::Forms)
2264            .expect("custom form control should produce a form fact");
2265        assert_eq!(fact.parent_role.as_deref(), Some("form"));
2266        assert_eq!(
2267            fact.relationship_hint,
2268            Some(EvidenceRelationshipHint::Controls)
2269        );
2270    }
2271
2272    #[test]
2273    fn extraction_emits_controls_hints_for_extended_custom_form_roles() {
2274        for role in ["listbox", "slider", "spinbutton", "switch"] {
2275            let mut context = page_context();
2276            context.accessibility.interactive[0].role = role.into();
2277            context.accessibility.interactive[0].ancestor_path = vec!["form:Example form".into()];
2278            let mut request = request();
2279            request.sources = vec![EvidenceSource::Forms];
2280            let evidence = extract_page_context(&context, &request).unwrap();
2281            let fact = evidence
2282                .facts
2283                .iter()
2284                .find(|fact| fact.source == EvidenceSource::Forms)
2285                .expect("extended custom form control should produce a form fact");
2286            assert_eq!(
2287                fact.relationship_hint,
2288                Some(EvidenceRelationshipHint::Controls)
2289            );
2290        }
2291    }
2292
2293    #[test]
2294    fn extracted_custom_control_hint_reconciles_to_controls_edge() {
2295        let mut context = page_context();
2296        context.accessibility.interactive[0].role = "combobox".into();
2297        context.accessibility.interactive[0].ancestor_path = vec!["form:Example form".into()];
2298        let evidence = extract_page_context(&context, &request()).unwrap();
2299        let draft = crate::web_ir::reconcile_evidence(&evidence).unwrap();
2300        assert_eq!(draft.relationship_hint_diagnostics.len(), 1);
2301        assert_eq!(
2302            draft.relationship_hint_diagnostics[0].status,
2303            crate::web_ir::RelationshipHintDiagnosticStatus::Emitted
2304        );
2305        assert!(draft.relationships.iter().any(
2306            |relationship| relationship.kind == crate::web_ir::WebIrRelationshipKind::Controls
2307        ));
2308    }
2309
2310    #[test]
2311    fn extraction_enforces_node_and_depth_budgets() {
2312        let mut request = request();
2313        request.sources = vec![EvidenceSource::Dom];
2314        request.budgets.max_nodes = 1;
2315        request.budgets.max_depth = 1;
2316        let evidence = extract_page_context(&page_context(), &request).unwrap();
2317        assert_eq!(evidence.facts.len(), 1);
2318        assert!(evidence.limits.truncated);
2319        assert!(evidence.limits.omitted_facts > 0);
2320    }
2321
2322    #[test]
2323    fn extraction_supports_observed_region_and_active_frame_scopes() {
2324        let mut region_request = request();
2325        region_request.scope = ExtractionScope::Region {
2326            region_id: "region_form_1".into(),
2327        };
2328        let region = extract_page_context(&page_context(), &region_request).unwrap();
2329        assert!(!region.facts.is_empty());
2330        assert_eq!(region.scope, region_request.scope);
2331
2332        let mut frame_request = request();
2333        frame_request.scope = ExtractionScope::Frame {
2334            frame_id: "frame-1".into(),
2335        };
2336        assert!(extract_page_context(&page_context(), &frame_request).is_ok());
2337        frame_request.scope = ExtractionScope::Frame {
2338            frame_id: "other-frame".into(),
2339        };
2340        assert_eq!(
2341            extract_page_context(&page_context(), &frame_request)
2342                .unwrap_err()
2343                .path,
2344            "scope.frameId"
2345        );
2346    }
2347
2348    #[test]
2349    fn extraction_covers_semantic_boundary_and_probe_sources() {
2350        use crate::browser::session::ViewportState;
2351
2352        let mut context = page_context();
2353        context.accessibility.roots[0].children.extend([
2354            CompactAxNode {
2355                role: "navigation".into(),
2356                name: "Primary".into(),
2357                children: vec![CompactAxNode {
2358                    role: "link".into(),
2359                    name: "Home".into(),
2360                    children: Vec::new(),
2361                    interactive: true,
2362                }],
2363                interactive: false,
2364            },
2365            CompactAxNode {
2366                role: "table".into(),
2367                name: "Orders".into(),
2368                children: vec![CompactAxNode {
2369                    role: "row".into(),
2370                    name: "Order 1".into(),
2371                    children: Vec::new(),
2372                    interactive: false,
2373                }],
2374                interactive: false,
2375            },
2376            CompactAxNode {
2377                role: "list".into(),
2378                name: "Results".into(),
2379                children: vec![CompactAxNode {
2380                    role: "listitem".into(),
2381                    name: "Result 1".into(),
2382                    children: Vec::new(),
2383                    interactive: false,
2384                }],
2385                interactive: false,
2386            },
2387            CompactAxNode {
2388                role: "dialog".into(),
2389                name: "Confirm".into(),
2390                children: Vec::new(),
2391                interactive: false,
2392            },
2393        ]);
2394        context.boundaries.child_frames = 1;
2395        context.boundaries.shadow_roots = 1;
2396        context.boundaries.viewport = Some(ViewportState {
2397            width: 800.0,
2398            height: 600.0,
2399            document_width: 1200.0,
2400            document_height: 1800.0,
2401            ..ViewportState::default()
2402        });
2403        let mut request = request();
2404        request.sources = vec![
2405            EvidenceSource::Navigation,
2406            EvidenceSource::Tables,
2407            EvidenceSource::Collections,
2408            EvidenceSource::Dialogs,
2409            EvidenceSource::Frames,
2410            EvidenceSource::ShadowDom,
2411            EvidenceSource::BoundedProbe,
2412        ];
2413        let evidence = extract_page_context(&context, &request).unwrap();
2414        assert!(evidence.limits.missing_sources.is_empty());
2415        for source in request.sources {
2416            assert!(
2417                evidence.facts.iter().any(|fact| fact.source == source),
2418                "missing facts for {source:?}"
2419            );
2420        }
2421    }
2422    #[test]
2423    fn observed_absence_of_frames_and_shadow_roots_is_not_missing_evidence() {
2424        let context = page_context();
2425        let mut request = request();
2426        request.sources = vec![EvidenceSource::Frames, EvidenceSource::ShadowDom];
2427
2428        let evidence = extract_page_context(&context, &request).unwrap();
2429
2430        assert!(evidence.facts.is_empty());
2431        assert!(evidence.limits.missing_sources.is_empty());
2432    }
2433    #[test]
2434    fn extraction_reports_explicit_opaque_boundaries_without_counting_structural_boundaries() {
2435        let mut context = page_context();
2436        context.boundaries.child_frames = 1;
2437        let evidence = extract_page_context(&context, &request()).unwrap();
2438        assert_eq!(evidence.coverage.opaque_regions, 0);
2439        assert!(
2440            evidence
2441                .coverage
2442                .reasons
2443                .iter()
2444                .any(|reason| reason == "frameBoundary")
2445        );
2446        assert_ne!(evidence.coverage.semantic, EvidenceQuality::Opaque);
2447
2448        context.boundaries.truncated = true;
2449        let mut opaque_request = request();
2450        opaque_request.sources.push(EvidenceSource::Layout);
2451        let opaque = extract_page_context(&context, &opaque_request).unwrap();
2452        assert_eq!(opaque.coverage.opaque_regions, 1);
2453        assert!(opaque.surface_set.as_ref().is_some_and(|surface_set| {
2454            surface_set
2455                .surfaces
2456                .iter()
2457                .any(|surface| surface.kind == SurfaceKind::Opaque)
2458        }));
2459    }
2460    #[test]
2461    fn extraction_output_budget_truncation_updates_coverage_and_text_bytes() {
2462        let context = page_context();
2463        let mut request = request();
2464        request.sources = vec![EvidenceSource::Accessibility, EvidenceSource::Dom];
2465        let complete = extract_page_context(&context, &request).unwrap();
2466        let complete_size = serde_json::to_vec(&complete).unwrap().len();
2467        request.budgets.max_output_bytes = (complete_size - 1) as u32;
2468
2469        let bounded = extract_page_context(&context, &request).unwrap();
2470        assert!(bounded.limits.truncated);
2471        assert!(bounded.limits.omitted_facts > 0);
2472        assert_eq!(
2473            bounded.limits.text_bytes,
2474            bounded.facts.iter().map(fact_text_bytes).sum::<u32>()
2475        );
2476        assert_eq!(bounded.coverage.structural, EvidenceQuality::Partial);
2477        assert!(
2478            bounded
2479                .coverage
2480                .reasons
2481                .iter()
2482                .any(|reason| reason == "budgetTruncated")
2483        );
2484    }
2485    #[test]
2486    fn extraction_marks_surface_set_omission_when_output_budget_requires_it() {
2487        let context = page_context();
2488        let mut request = request();
2489        request.sources = vec![
2490            EvidenceSource::Accessibility,
2491            EvidenceSource::Dom,
2492            EvidenceSource::Frames,
2493        ];
2494        let complete = extract_page_context(&context, &request).unwrap();
2495        assert!(complete.surface_set.is_some());
2496        let mut facts_removed = complete.clone();
2497        facts_removed.facts.clear();
2498        let minimum_with_surfaces = serde_json::to_vec(&facts_removed).unwrap().len();
2499        request.budgets.max_output_bytes = (minimum_with_surfaces - 1) as u32;
2500
2501        let bounded = extract_page_context(&context, &request).unwrap();
2502        assert!(bounded.surface_set.is_none());
2503        assert!(bounded.limits.truncated);
2504        assert!(
2505            bounded
2506                .coverage
2507                .reasons
2508                .iter()
2509                .any(|reason| reason == "surfaceSetBudgetTruncated")
2510        );
2511    }
2512
2513    #[test]
2514    fn extraction_distinguishes_absent_forms_from_missing_accessibility() {
2515        let mut request = request();
2516        request.sources = vec![EvidenceSource::Forms];
2517
2518        let mut absent_context = page_context();
2519        absent_context.accessibility.interactive.clear();
2520        let absent = extract_page_context(&absent_context, &request).unwrap();
2521        assert!(absent.facts.is_empty());
2522        assert!(absent.limits.missing_sources.is_empty());
2523
2524        let mut missing_context = absent_context;
2525        missing_context
2526            .incomplete
2527            .push(crate::browser::session::ObservationIncompleteReason::AccessibilityNode);
2528        let missing = extract_page_context(&missing_context, &request).unwrap();
2529        assert!(missing.facts.is_empty());
2530        assert_eq!(missing.limits.missing_sources, vec![EvidenceSource::Forms]);
2531        assert!(
2532            missing
2533                .coverage
2534                .reasons
2535                .iter()
2536                .any(|reason| reason == "missingSource:Forms")
2537        );
2538    }
2539
2540    #[test]
2541    fn extraction_treats_truncated_controls_as_missing_forms() {
2542        let mut context = page_context();
2543        context
2544            .incomplete
2545            .push(crate::browser::session::ObservationIncompleteReason::Control);
2546        let mut request = request();
2547        request.sources = vec![EvidenceSource::Forms];
2548
2549        let evidence = extract_page_context(&context, &request).unwrap();
2550        assert!(evidence.facts.is_empty());
2551        assert_eq!(evidence.limits.missing_sources, vec![EvidenceSource::Forms]);
2552    }
2553
2554    #[test]
2555    fn extraction_enforces_duration_budget_at_collection_checkpoint() {
2556        let mut collector = EvidenceCollector::new(ExtractionBudgets::default());
2557        collector.deadline = Instant::now() - Duration::from_millis(1);
2558
2559        assert!(!collector.allow_node(0));
2560        assert!(collector.timed_out);
2561        assert!(collector.truncated);
2562        assert_eq!(collector.omitted_facts, 1);
2563    }
2564
2565    #[test]
2566    fn extraction_marks_mutation_races_as_partial_coverage() {
2567        let mut context = page_context();
2568        context.consistency.consistent = false;
2569        let evidence = extract_page_context(&context, &request()).unwrap();
2570        assert_eq!(evidence.coverage.structural, EvidenceQuality::Partial);
2571        assert_eq!(evidence.coverage.semantic, EvidenceQuality::Partial);
2572        assert!(
2573            evidence
2574                .coverage
2575                .reasons
2576                .iter()
2577                .any(|reason| reason == "mutationRace")
2578        );
2579    }
2580
2581    #[test]
2582    fn extraction_is_non_mutating_and_preserves_fact_source_provenance() {
2583        let context = page_context();
2584        let before = serde_json::to_vec(&context).unwrap();
2585        let mut request = request();
2586        request.sources = vec![
2587            EvidenceSource::Accessibility,
2588            EvidenceSource::Dom,
2589            EvidenceSource::Forms,
2590            EvidenceSource::Layout,
2591        ];
2592        let evidence = extract_page_context(&context, &request).unwrap();
2593        assert_eq!(serde_json::to_vec(&context).unwrap(), before);
2594        assert!(
2595            evidence
2596                .facts
2597                .iter()
2598                .all(|fact| request.sources.contains(&fact.source))
2599        );
2600        assert!(
2601            evidence
2602                .facts
2603                .iter()
2604                .any(|fact| fact.source == EvidenceSource::Dom)
2605        );
2606        assert!(
2607            evidence
2608                .facts
2609                .iter()
2610                .any(|fact| fact.source == EvidenceSource::Forms)
2611        );
2612        assert!(
2613            evidence
2614                .facts
2615                .iter()
2616                .any(|fact| fact.source == EvidenceSource::Layout)
2617        );
2618    }
2619    #[test]
2620    fn utf8_truncation_never_exceeds_the_byte_budget() {
2621        assert_eq!(truncate_utf8("é", 1), "");
2622        assert_eq!(truncate_utf8("aé", 2), "a");
2623        assert_eq!(truncate_utf8("aé", 3), "aé");
2624        assert!(truncate_utf8("🙂🙂", 7).len() <= 7);
2625    }
2626    #[test]
2627    fn semantic_bridge_extracts_svg_fact_and_rejects_stale_revision() {
2628        let mut grants = BridgeGrantRegistry::default();
2629        grants
2630            .insert(crate::surfaces::BridgeCapabilityGrant {
2631                token: "svg-grant".into(),
2632                origin: "https://example.test".into(),
2633                capabilities: vec![SurfaceCapability::ReadStructure],
2634            })
2635            .unwrap();
2636        let bridge = SemanticBridge {
2637            schema_version: SEMANTIC_BRIDGE_SCHEMA_VERSION,
2638            bridge_version: "1".into(),
2639            origin: "https://example.test".into(),
2640            grant_token: "svg-grant".into(),
2641            revision: SurfaceRevision(11),
2642            surface_id: SurfaceId::new("svg-bridge").unwrap(),
2643            surface_kind: SurfaceKind::Svg,
2644            capabilities: vec![SurfaceCapability::ReadStructure],
2645            entities: vec![crate::surfaces::SemanticBridgeEntity {
2646                id: "title".into(),
2647                kind: "text".into(),
2648                role: Some("text".into()),
2649                name: Some("Chart".into()),
2650                quality: CoverageLevel::Strong,
2651                allowed_actions: vec![crate::surfaces::BridgeAction::Read],
2652                parent_id: None,
2653            }],
2654        };
2655        let evidence = extract_semantic_bridge(
2656            &bridge,
2657            &grants,
2658            "https://example.test",
2659            SurfaceRevision(11),
2660        )
2661        .unwrap();
2662        let ir = crate::web_ir::reconcile_evidence_with_grants(&evidence, &grants).unwrap();
2663        assert!(
2664            ir.entities
2665                .iter()
2666                .any(|entity| entity.kind == crate::web_ir::WebIrEntityKind::Text)
2667        );
2668        assert_eq!(ir.revision, 11);
2669        assert!(
2670            extract_semantic_bridge(
2671                &bridge,
2672                &grants,
2673                "https://example.test",
2674                SurfaceRevision(12),
2675            )
2676            .is_err()
2677        );
2678    }
2679}