Skip to main content

guise_oracle/
lib.rs

1//! `guise-oracle` - shared surface taxonomy and differential oracle data types
2//!
3//! [![santh status](https://img.shields.io/badge/santh-beta-blue)](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};