guise_oracle/lib.rs
1//! `guise-oracle` - shared surface taxonomy and differential oracle data types
2//!
3//! [](https://santh.dev/standard)
4//!
5//! This crate publishes the data-shaped contract that the differential oracle,
6//! the fingerprint inventory, and downstream stealth consumers (`lurien`, `guise`,
7//! `sear`) agree on: [`Severity`], [`Probe`], [`ProbeOutcome`],
8//! [`Capture`], [`DifferentialReport`], and [`ThreeWayReport`]. It contains zero
9//! browser-driver, TLS, or heavy dependencies so it can be imported cheaply across
10//! any tier of the stealth stack.
11//!
12//! Runtime evaluation, rendering, and scorecard generation live in the `guise`
13//! crate, which re-exports these types from its `probe` module.
14//!
15//! ## Quick Start
16//!
17//! ```rust
18//! use guise_oracle::{Capture, CapturedSurface, Severity};
19//!
20//! // Create offline captures from two browser profiles
21//! let stock = Capture {
22//! label: "stock-firefox-135".into(),
23//! surfaces: vec![CapturedSurface {
24//! name: "navigator.webdriver".into(),
25//! severity: Severity::High,
26//! value: Ok("false".into()),
27//! }],
28//! };
29//!
30//! let target = Capture {
31//! label: "patched-lurien-135".into(),
32//! surfaces: vec![CapturedSurface {
33//! name: "navigator.webdriver".into(),
34//! severity: Severity::High,
35//! value: Ok("false".into()),
36//! }],
37//! };
38//!
39//! // Perform offline differential analysis without browser drivers
40//! let report = stock.diff(&target);
41//! assert!(report.is_identical());
42//! assert_eq!(report.agreed, 1);
43//! ```
44//!
45//! ## When to use / when not to use
46//!
47//! - **Use when:**
48//! - You are building fingerprint probes, report renderers, or differential diffing tooling.
49//! - You need serializable JSON report schemas shared between automation analyzers and JS engines.
50//! - You want offline differential comparison between captured browser surface fixtures.
51//! - **Do not use when:**
52//! - You need live browser orchestration or CDP automation (use `guise` or `lurien` instead).
53//! - You require full browser profile generator state (use `guise-profiles` instead).
54//!
55//! ## Compared to alternatives
56//!
57//! Traditional browser bot-detection frameworks tightly couple surface taxonomy with
58//! browser automation runtimes, requiring headless browsers or heavy Node.js dependencies
59//! just to parse or diff report formats. `guise-oracle` decouples the taxonomy contract
60//! into a lightweight Rust crate that serializes deterministically and diffs offline in sub-millisecond time.
61//!
62//! Unlike unstructured raw JSON diffing tools, `guise-oracle` classifies divergences by
63//! severity (High, Medium, Low) and isolates persona-intended overrides from unexpected engine-level leaks.
64//!
65//! ## How it fits in Santh
66//!
67//! `guise-oracle` lives under `software/browser/` in the Santh monorepo. It serves as the
68//! shared taxonomy contract between the lurien engine, high-level stealth
69//! drivers (`guise`), and verification engines (`sear`).
70
71#![forbid(unsafe_code)]
72#![warn(missing_docs)]
73#![warn(clippy::pedantic)]
74#![cfg_attr(
75 not(test),
76 deny(
77 clippy::unwrap_used,
78 clippy::expect_used,
79 clippy::todo,
80 clippy::unimplemented,
81 clippy::panic
82 )
83)]
84#![allow(
85 clippy::module_name_repetitions,
86 clippy::must_use_candidate,
87 clippy::missing_errors_doc
88)]
89mod types;
90
91pub use types::{
92 severity_rank, Capture, CapturedSurface, Determinism, DifferentialReport, Divergence,
93 DivergenceKind, DriftReport, Probe, ProbeOutcome, ProbeReport, Severity, ThreeWayReport,
94 ThreeWaySurface,
95};