1use 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
19pub const EXTRACTION_CONTRACT_SCHEMA_VERSION: u32 = 1;
21
22pub const MAX_EXTRACTION_NODES: u32 = 8_192;
24pub const MAX_EXTRACTION_TEXT_BYTES: u32 = 128 * 1024;
26pub const MAX_EXTRACTION_DEPTH: u16 = 64;
28pub const MAX_EXTRACTION_DURATION_MS: u64 = 15_000;
30pub const MAX_EXTRACTION_OUTPUT_BYTES: u32 = 256 * 1024;
32
33#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
35#[serde(rename_all = "camelCase", deny_unknown_fields)]
36pub enum ExtractionScope {
37 Document,
39 Region { region_id: String },
41 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#[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#[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 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#[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 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 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 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 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#[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#[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#[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#[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 #[serde(default, skip_serializing_if = "Option::is_none")]
277 pub surface_set: Option<SurfaceSet>,
278}
279
280#[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 #[serde(skip_serializing_if = "Option::is_none")]
293 pub parent_role: Option<String>,
294 #[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 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 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#[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
423pub 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}
690pub 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 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(®ion_root.role)
1453 && (region_root.name.is_empty() || name.eq_ignore_ascii_case(®ion_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
1637fn 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#[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(), ®ion_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}