Struct PreparedEvidenceValidator 

pub struct PreparedEvidenceValidator { /* private fields */ }

A prepared, immutable evidence-validation snapshot.

Parsing and inference happen before construction. Normalization, stratification, dataset indexing, and SPARQL-executor construction happen once here; each validate call creates one reusable ShapeEvaluator over those retained resources.

Implementations

impl PreparedEvidenceValidator

pub fn new(data: &Graph, schema: &Schema) -> Result<Self, NonStratifiable>

Prepare embedded data/shapes validation over one graph.

pub fn with_context( data: &Graph, context: &Graph, schema: &Schema, ) -> Result<Self, NonStratifiable>

Prepare separate focus and evaluation graphs.

pub fn with_graphs( data: &Graph, shapes: &Graph, schema: &Schema, mode: ValidationGraphMode, ) -> Result<Self, NonStratifiable>

Prepare split data/shapes validation in the requested graph mode.

Examples found in repository

examples/probe_evidence_cost.rs (lines 67-72)

fn main() {
    let mut shapes_path = PathBuf::new();
    let mut data_path = PathBuf::new();
    let mut no_infer = false;
    let mut top = 15usize;
    let mut dump_json: Option<PathBuf> = None;
    let mut argv = std::env::args().skip(1);
    while let Some(flag) = argv.next() {
        let mut value = || {
            argv.next()
                .unwrap_or_else(|| panic!("{flag} needs a value"))
        };
        match flag.as_str() {
            "--shapes" => shapes_path = PathBuf::from(value()),
            "--data" => data_path = PathBuf::from(value()),
            "--no-infer" => no_infer = true,
            "--top" => top = value().parse().expect("--top must be an integer"),
            "--dump-json" => dump_json = Some(PathBuf::from(value())),
            other => panic!("unknown flag {other}"),
        }
    }
    assert!(!shapes_path.as_os_str().is_empty(), "--shapes is required");
    assert!(!data_path.as_os_str().is_empty(), "--data is required");

    let shapes_bytes = fs::read(&shapes_path).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    let inference_schema = shifty_opt::normalize(&raw_schema);

    let data_bytes = fs::read(&data_path).expect("cannot read --data");
    let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse --data");
    let data_graph = if no_infer {
        data.graph.clone()
    } else {
        shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
            .expect("inference")
            .graph
    };

    let prepared = PreparedEvidenceValidator::with_graphs(
        &data_graph,
        &shapes.graph,
        &raw_schema,
        ValidationGraphMode::Union,
    )
    .expect("stratifiable");
    let options = ValidationOptions::default();
    let scan_options = ConformanceOptions::default();

    println!("model: {}", data_path.display());
    println!("normalized arena nodes: {}", prepared.schema().arena.len());
    println!(
        "normalized statements:  {}",
        prepared.schema().statements.len()
    );
    println!();

    // ---- arm A: conformance only ------------------------------------------
    profile::enable();
    let _ = profile::take_evidence_visits();
    let start = Instant::now();
    let conformance = prepared.validate_conformance(&scan_options);
    let conformance_ms = start.elapsed().as_secs_f64() * 1e3;
    let conformance_visits = profile::take_evidence_visits();
    let conformance_probes = profile::take_path_probes();
    let conformance_cache = profile::take().expect("profiling enabled");
    let conformance_cache = conformance_cache.shape_cache().clone();

    // ---- arm B: dual evidence ----------------------------------------------
    profile::enable();
    let start = Instant::now();
    let run = prepared.validate(&options);
    let evidence_ms = start.elapsed().as_secs_f64() * 1e3;
    let evidence_visits = profile::take_evidence_visits();
    let evidence_probes = profile::take_path_probes();
    let collector = profile::take().expect("profiling enabled");
    let evidence_cache = collector.shape_cache().clone();

    // ---- arm C: on-demand ---------------------------------------------------
    // What a caller pays who wants explanations only for what failed: one
    // conformance pass that also records the failing pairs, then evidence
    // materialized for those pairs alone.
    profile::enable();
    let start = Instant::now();
    let (_, failures) = prepared.find_failures(&scan_options);
    let find_ms = start.elapsed().as_secs_f64() * 1e3;
    let start = Instant::now();
    let explained: usize = failures
        .iter()
        .map(|pair| prepared.explain(pair).len())
        .sum();
    let explain_ms = start.elapsed().as_secs_f64() * 1e3;
    let _ = profile::take();
    let _ = profile::take_evidence_visits();
    let _ = profile::take_path_probes();

    let pairs = conformance.selected_pairs.max(1) as f64;
    let retained = run.walk().len();

    // ---- compact encoding --------------------------------------------------
    let full_json = run.to_json().expect("evidence run serializes");
    // Split so the encoding's own cost is separable from the intermediate
    // `Value` tree it currently has to be handed: compaction is worth doing
    // inline only if the total stays under the validation it describes.
    let to_value_start = Instant::now();
    let run_value = serde_json::to_value(&run).expect("run serializes");
    let to_value_ms = to_value_start.elapsed().as_secs_f64() * 1e3;
    let intern_start = Instant::now();
    let interned = shifty_engine::compact_value(run_value, true);
    let intern_ms = intern_start.elapsed().as_secs_f64() * 1e3;
    let emit_start = Instant::now();
    let compact_json = serde_json::to_string(&interned).expect("compact encoding serializes");
    let emit_ms = emit_start.elapsed().as_secs_f64() * 1e3;
    let compact_ms = to_value_ms + intern_ms + emit_ms;
    drop(interned);
    let compact_no_catalog =
        shifty_engine::to_compact_json(&run, false).expect("compact encoding succeeds");
    println!();
    println!(
        "serialized full:           {:>10.2} MB  ({:.0} bytes/pair)",
        full_json.len() as f64 / 1e6,
        full_json.len() as f64 / pairs
    );
    println!(
        "compact (with catalog):    {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller, {compact_ms:.0} ms \
         = {to_value_ms:.0} to_value + {intern_ms:.0} intern + {emit_ms:.0} emit)",
        compact_json.len() as f64 / 1e6,
        compact_json.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_json.len()) as f64 / full_json.len() as f64
    );
    println!(
        "compact (catalog elided):  {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller)",
        compact_no_catalog.len() as f64 / 1e6,
        compact_no_catalog.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_no_catalog.len()) as f64 / full_json.len() as f64
    );

    if let Some(path) = &dump_json {
        fs::write(path, run.to_json().expect("evidence run serializes"))
            .expect("cannot write --dump-json");
        eprintln!("wrote {}", path.display());
    }

    println!("                        conformance        evidence");
    println!("  wall ms               {conformance_ms:>11.1}  {evidence_ms:>14.1}");
    println!(
        "  memo lookups          {:>11}  {:>14}",
        conformance_cache.hits + conformance_cache.misses,
        evidence_cache.hits + evidence_cache.misses
    );
    println!(
        "  memo hits             {:>11}  {:>14}",
        conformance_cache.hits, evidence_cache.hits
    );
    println!(
        "  memo misses           {:>11}  {:>14}",
        conformance_cache.misses, evidence_cache.misses
    );
    println!(
        "  memo entries (peak)   {:>11}  {:>14}",
        conformance_cache.peak_entries, evidence_cache.peak_entries
    );
    println!(
        "  back-edges            {:>11}  {:>14}",
        conformance_cache.recursion_back_edges, evidence_cache.recursion_back_edges
    );
    println!(
        "  uncacheable results   {:>11}  {:>14}",
        conformance_cache.non_cacheable_results, evidence_cache.non_cacheable_results
    );
    println!("  evidence visits       {conformance_visits:>11}  {evidence_visits:>14}");
    println!("  path_support probes   {conformance_probes:>11}  {evidence_probes:>14}");
    println!();
    println!(
        "path probes per visit:     {:.1}",
        evidence_probes as f64 / evidence_visits.max(1) as f64
    );

    println!("selected pairs:            {}", conformance.selected_pairs);
    println!("retained evidence nodes:   {retained}");
    println!(
        "visited / retained:        {:.1}x",
        evidence_visits as f64 / retained.max(1) as f64
    );
    println!(
        "visits per pair:           {:.0}",
        evidence_visits as f64 / pairs
    );
    println!(
        "distinct (shape,node) that a cache could collapse to at most: {}",
        evidence_cache.peak_entries
    );
    println!(
        "visits / distinct pairs:   {:.1}x",
        evidence_visits as f64 / evidence_cache.peak_entries.max(1) as f64
    );
    println!();
    println!(
        "per-visit cost:            {:.2} us",
        evidence_ms * 1e3 / evidence_visits.max(1) as f64
    );
    println!(
        "per-memo-lookup cost:      {:.2} us",
        conformance_ms * 1e3 / (conformance_cache.hits + conformance_cache.misses).max(1) as f64
    );

    // ---- attribution: which statements own the time ------------------------
    let (selection, materialization): (Vec<_>, Vec<_>) = collector
        .shape_records()
        .iter()
        .partition(|record| record.label.starts_with("select:"));
    let selection_us: u64 = selection.iter().map(|record| record.total_us).sum();
    let materialization_us: u64 = materialization.iter().map(|record| record.total_us).sum();

    println!();
    println!(
        "target selection total:    {:.1} ms over {} statement(s)",
        selection_us as f64 / 1e3,
        selection.len()
    );
    println!(
        "materialization total:     {:.1} ms over {} statement(s)",
        materialization_us as f64 / 1e3,
        materialization.len()
    );
    println!();
    println!(
        "on-demand: {} failing pair(s) of {} selected -> {} explanation(s)",
        failures.len(),
        conformance.selected_pairs,
        explained
    );
    println!(
        "  find_failures {find_ms:.1} ms + explain {explain_ms:.1} ms = {:.1} ms  \
         ({:.2}x the full evidence run, {:.2}x conformance alone)",
        find_ms + explain_ms,
        (find_ms + explain_ms) / evidence_ms.max(f64::MIN_POSITIVE),
        (find_ms + explain_ms) / conformance_ms.max(f64::MIN_POSITIVE)
    );

    let mut ranked = materialization;
    ranked.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by evidence-materialization time:");
    println!(
        "  {:>8}  {:>7}  {:>6}  {:>10}  {:>12}  {:>10}  shape",
        "ms", "share", "foci", "us/focus", "visits", "visits/foci"
    );
    for record in ranked.iter().take(top) {
        println!(
            "  {:>8.1}  {:>6.1}%  {:>6}  {:>10.1}  {:>12}  {:>10.0}  {}",
            record.total_us as f64 / 1e3,
            100.0 * record.total_us as f64 / materialization_us.max(1) as f64,
            record.invocations,
            record.total_us as f64 / record.invocations.max(1) as f64,
            record.visits,
            record.visits as f64 / record.invocations.max(1) as f64,
            record.label,
        );
    }

    let mut ranked_selection = selection;
    ranked_selection.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by target-selection time:");
    for record in ranked_selection.iter().take(5) {
        println!(
            "  {:>8.1} ms  {}",
            record.total_us as f64 / 1e3,
            record.label
        );
    }
}

examples/bench_evidence.rs (lines 168-173)

fn main() {
    let args = parse_args();

    eprintln!("loading shapes {}…", args.shapes.display());
    let shapes_bytes = fs::read(&args.shapes).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    // Inference runs against the normalized schema, exactly as the CLI does.
    let inference_schema = shifty_opt::normalize(&raw_schema);
    drop(shapes_bytes);

    if args.header {
        println!("{COLUMNS}");
    }

    for model in models_in(&args.models) {
        let name = model
            .file_name()
            .and_then(|name| name.to_str())
            .unwrap_or("?")
            .to_string();
        eprint!("{name}… ");

        // ---- untimed setup: everything common to all workflows --------------
        let data_bytes = fs::read(&model).expect("cannot read model");
        let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse model");
        drop(data_bytes);
        let data_graph = if args.no_infer {
            data.graph.clone()
        } else {
            shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
                .unwrap_or_else(|error| panic!("{name}: inference failed: {error}"))
                .graph
        };
        let data_triples = data_graph.len();

        let prepared = PreparedEvidenceValidator::with_graphs(
            &data_graph,
            &shapes.graph,
            &raw_schema,
            ValidationGraphMode::Union,
        )
        .unwrap_or_else(|error| panic!("{name}: schema is non-stratifiable: {error}"));
        let options = ValidationOptions::default();
        let scan_options = ConformanceOptions::default();

        // ---- timed: validation only -----------------------------------------
        // One warm-up round, discarded: it faults in the caches all arms share.
        // Its duration is only consulted when `--budget-ms` is in play.
        let probe = Instant::now();
        let _ = prepared.validate_conformance(&scan_options);
        let _ = prepared.validate_canonical(&options);
        let (_, warm_failures) = prepared.find_failures(&scan_options);
        for pair in &warm_failures {
            std::hint::black_box(prepared.explain_canonical(pair));
        }
        let probe_ms = probe.elapsed().as_secs_f64() * 1e3;
        // Every model gets the same iteration count. `--budget-ms` only caps the
        // count for a corpus slow enough that a fixed count is impractical; it
        // is off by default, and the emitted `iters` column records what was used.
        let iters = if args.budget_ms > 0.0 {
            ((args.budget_ms / probe_ms.max(f64::MIN_POSITIVE)) as usize)
                .clamp(args.min_iters.min(args.iters), args.iters)
        } else {
            args.iters
        };

        let mut conformance_samples = Vec::with_capacity(iters);
        let mut evidence_samples = Vec::with_capacity(iters);
        let mut discovery_samples = Vec::with_capacity(iters);
        let mut explanation_samples = Vec::with_capacity(iters);
        let mut on_demand_samples = Vec::with_capacity(iters);
        let mut last_run = None;
        let mut last_conformance = None;
        let mut last_on_demand_conformance = None;
        let mut last_failures = Vec::new();
        let mut last_explanations = Vec::new();

        // Rotate A/B/C so no arm systematically inherits the cache, allocator,
        // scheduler, or thermal state left by another arm.
        for iteration in 0..iters {
            for arm in ARM_ORDERS[iteration % ARM_ORDERS.len()] {
                match arm {
                    Arm::Conformance => {
                        let start = Instant::now();
                        let conformance_run = prepared.validate_conformance(&scan_options);
                        conformance_samples.push(start.elapsed());
                        std::hint::black_box(conformance_run.selected_pairs);
                        last_conformance = Some(conformance_run);
                    }
                    Arm::FullEvidence => {
                        let start = Instant::now();
                        let run = prepared.validate_canonical(&options);
                        evidence_samples.push(start.elapsed());
                        std::hint::black_box(run.statements.len());
                        last_run = Some(run);
                    }
                    Arm::OnDemand => {
                        let start = Instant::now();
                        let (on_demand_conformance, failures) =
                            prepared.find_failures(&scan_options);
                        let discovery = start.elapsed();

                        let start = Instant::now();
                        let explanations: Vec<_> = failures
                            .iter()
                            .flat_map(|pair| prepared.explain_canonical(pair))
                            .collect();
                        let explanation = start.elapsed();

                        discovery_samples.push(discovery);
                        explanation_samples.push(explanation);
                        on_demand_samples.push(discovery + explanation);
                        std::hint::black_box(explanations.len());
                        last_on_demand_conformance = Some(on_demand_conformance);
                        last_failures = failures;
                        last_explanations = explanations;
                    }
                }
            }
        }

        // ---- untimed: shape of the evidence produced -------------------------
        // Reuse the final timed results rather than paying for another run.
        let conformance = last_conformance.expect("at least one iteration runs");
        let on_demand_conformance =
            last_on_demand_conformance.expect("at least one iteration runs");
        let run = last_run.expect("at least one iteration runs");
        let authored_pairs: usize = run
            .statements
            .iter()
            .map(|statement| statement.selected_foci.len())
            .sum();
        let authored_fail_pairs: usize = run
            .statements
            .iter()
            .flat_map(|statement| &statement.selected_foci)
            .filter(|focus| focus.status() == shifty_engine::EvaluationStatus::Fail)
            .count();

        // The three interfaces must describe the same normalized selection and
        // polarity partition. Compare exact failed identities, not just the
        // report-wide conformance bit.
        assert_eq!(
            conformance, on_demand_conformance,
            "{name}: on-demand counts"
        );
        assert_eq!(
            conformance.conforms, run.conforms,
            "{name}: conformance bit"
        );
        let full_selected: HashSet<_> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement.selected_foci.iter().filter_map(|focus| {
                    statement
                        .normalized_statement_id
                        .map(|id| (id, focus.focus.clone()))
                })
            })
            .collect();
        let full_failures: HashSet<_> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement
                    .selected_foci
                    .iter()
                    .filter(|focus| focus.status() == shifty_engine::EvaluationStatus::Fail)
                    .filter_map(|focus| {
                        statement
                            .normalized_statement_id
                            .map(|id| (id, focus.focus.clone()))
                    })
            })
            .collect();
        let discovered_failures: HashSet<_> = last_failures
            .iter()
            .map(|pair| (pair.normalized_statement(), pair.focus().clone()))
            .collect();
        assert_eq!(
            full_selected.len(),
            conformance.selected_pairs,
            "{name}: selected pairs"
        );
        assert_eq!(
            full_failures.len(),
            conformance.failed,
            "{name}: failed pairs"
        );
        assert_eq!(
            full_selected.len() - full_failures.len(),
            conformance.passed,
            "{name}: passed pairs"
        );
        assert_eq!(
            full_failures, discovered_failures,
            "{name}: failed identities"
        );

        let full_by_authored: HashMap<_, _> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement.selected_foci.iter().map(|focus| {
                    (
                        (statement.source_statement_id, focus.focus.clone()),
                        &focus.evidence,
                    )
                })
            })
            .collect();
        let mut explained_foci = 0;
        for statement in &last_explanations {
            for focus in &statement.selected_foci {
                explained_foci += 1;
                assert_eq!(
                    focus.status(),
                    shifty_engine::EvaluationStatus::Fail,
                    "{name}: on-demand explanation polarity"
                );
                let key = (statement.source_statement_id, focus.focus.clone());
                assert_eq!(
                    &focus.evidence,
                    *full_by_authored
                        .get(&key)
                        .unwrap_or_else(|| panic!("{name}: unexplained full-run pair {key:?}")),
                    "{name}: full and on-demand evidence differ for {key:?}"
                );
            }
        }
        assert_eq!(
            explained_foci, authored_fail_pairs,
            "{name}: authored explanations"
        );

        let evidence_nodes = run.walk().len();
        let evidence_bytes: usize = run
            .statements
            .iter()
            .flat_map(|statement| &statement.selected_foci)
            .map(|focus| focus.evidence.to_json().expect("evidence serializes").len())
            .sum();
        let full_json = run.to_json().expect("evidence run serializes");
        let full_run_bytes_with_catalog = full_json.len();
        let mut full_value_no_catalog =
            serde_json::to_value(&run).expect("evidence run converts to JSON");
        full_value_no_catalog
            .as_object_mut()
            .expect("evidence run is a JSON object")
            .remove("constraints");
        let full_run_bytes_no_catalog = serde_json::to_string(&full_value_no_catalog)
            .expect("catalog-free evidence run serializes")
            .len();

        // Compare complete runs with the same catalog policy on each side, and
        // verify both encodings reconstruct the exact typed result.
        let encoded_with_catalog =
            shifty_engine::compact(&run, true).expect("compact encoding succeeds");
        let compact_run_bytes_with_catalog = serde_json::to_string(&encoded_with_catalog)
            .expect("compact encoding serializes")
            .len();
        assert_eq!(
            shifty_engine::expand(&encoded_with_catalog).expect("compact run expands"),
            run,
            "{name}: compact run with catalog is not lossless"
        );
        let encoded_no_catalog =
            shifty_engine::compact(&run, false).expect("compact encoding succeeds");
        let compact_run_bytes_no_catalog = serde_json::to_string(&encoded_no_catalog)
            .expect("catalog-free compact encoding serializes")
            .len();
        let catalog = serde_json::to_value(&run.constraints).expect("catalog serializes");
        assert_eq!(
            shifty_engine::expand_with_catalog(&encoded_no_catalog, catalog)
                .expect("catalog-free compact run expands"),
            run,
            "{name}: compact run without catalog is not lossless"
        );
        // Sharing is reported over the evidence alone. The node and term tables
        // of `encoded` also hold catalog entries, which would understate the
        // redundancy by adding distinct entries with no evidence occurrences.
        let sharing = shifty_engine::sharing(&run).expect("sharing measures");
        let results = shifty_engine::result_sharing(&run);

        // The two passes reach the same judgment nodes by routes that share no
        // code: `sharing` interns serialized JSON, `result_sharing` walks the
        // typed evidence. Agreement on both counts is what makes either number
        // reportable; a mismatch means the node families are misclassified or a
        // traversal is missing a variant.
        assert_eq!(
            sharing.result_occurrences + sharing.support_occurrences,
            sharing.node_occurrences,
            "{name}: node families do not partition occurrences"
        );
        assert_eq!(
            sharing.distinct_results + sharing.distinct_support,
            sharing.distinct_nodes,
            "{name}: node families do not partition the table"
        );
        assert_eq!(
            sharing.result_occurrences, evidence_nodes,
            "{name}: interned judgments disagree with the typed walk"
        );
        assert_eq!(
            results.occurrences, evidence_nodes,
            "{name}: typed sharing pass disagrees with the typed walk"
        );
        assert_eq!(
            results.distinct_payloads, sharing.distinct_results,
            "{name}: distinct judgments disagree between the two passes"
        );
        // Structural equality implies key equality, never the reverse.
        assert!(
            results.distinct_keys <= results.distinct_payloads,
            "{name}: more keys than payloads"
        );
        // Requests are the normalized selection the conformance pass counts;
        // authored records are the source-preserving view over them.
        assert_eq!(
            results.normalized_requests, conformance.selected_pairs,
            "{name}: requests disagree with the conformance selection"
        );
        assert_eq!(
            results.authored_records, authored_pairs,
            "{name}: authored records disagree with the run"
        );

        // Serialization is measured separately so its allocation traffic does
        // not perturb the next validation arm.
        let mut serialize_samples = Vec::with_capacity(iters);
        for _ in 0..iters {
            let start = Instant::now();
            let json = run.to_json().expect("evidence run serializes");
            serialize_samples.push(start.elapsed());
            std::hint::black_box(json.len());
        }

        // Each ratio compares the corresponding raw samples from one rotated
        // A/B/C round. The CSV retains those samples for independent checking.
        let full_ratios: Vec<f64> = conformance_samples
            .iter()
            .zip(evidence_samples.iter())
            .map(|(conformance, evidence)| {
                evidence.as_secs_f64() / conformance.as_secs_f64().max(f64::MIN_POSITIVE)
            })
            .collect();
        let on_demand_ratios: Vec<f64> = conformance_samples
            .iter()
            .zip(on_demand_samples.iter())
            .map(|(conformance, on_demand)| {
                on_demand.as_secs_f64() / conformance.as_secs_f64().max(f64::MIN_POSITIVE)
            })
            .collect();

        let conformance_ms = summarize_durations(&conformance_samples);
        let evidence_ms = summarize_durations(&evidence_samples);
        let discovery_ms = summarize_durations(&discovery_samples);
        let explanation_ms = summarize_durations(&explanation_samples);
        let on_demand_ms = summarize_durations(&on_demand_samples);
        let serialize_ms = summarize_durations(&serialize_samples);
        let full_ratio = summarize_values(&full_ratios);
        let on_demand_ratio = summarize_values(&on_demand_ratios);
        let evaluated_pairs = conformance.selected_pairs.max(1) as f64;
        let authored_pairs_denominator = authored_pairs.max(1) as f64;

        println!(
            "{suite},{name},{data_triples},{iters},\
{c_med:.4},{c_mad:.4},{e_med:.4},{e_mad:.4},{full_ratio:.4},{full_ratio_mad:.4},\
{find_med:.4},{find_mad:.4},{explain_med:.4},{explain_mad:.4},\
{ondemand_med:.4},{ondemand_mad:.4},{ondemand_ratio:.4},{ondemand_ratio_mad:.4},\
{serialize_med:.4},{serialize_mad:.4},\
{conforms_c},{conforms_e},{conforms_o},\
{pairs_eval},{pass_pairs},{fail_pairs},{fail_fraction:.6},\
{authored_pairs},{authored_pass},{authored_fail},\
{statements},\
{evidence_nodes},{nodes_per_authored_pair:.3},\
{evidence_bytes},{bytes_per_authored_pair:.1},\
{full_with_catalog},{full_no_catalog},{compact_with_catalog},{compact_no_catalog},\
{node_occurrences},{distinct_nodes},{node_redundancy:.3},\
{result_occurrences},{distinct_results},{result_redundancy:.3},\
{support_occurrences},{distinct_support},{support_redundancy:.3},{support_share:.4},\
{term_occurrences},{distinct_terms},{term_redundancy:.3},\
{normalized_requests},{duplicate_records},{divergent_duplicates},\
{canonical_occurrences},{shared_payloads},{shared_payload_fraction:.4},\
{shared_canonical_occurrences},{shared_occurrence_fraction:.4},\
{request_reaches},{requests_per_payload:.3},{max_payload_requests},\
{distinct_keys},{key_redundancy:.3},{multi_occurrence_keys},\
{divergent_keys},{divergence_fraction:.4},{divergent_occurrences},\
{distinct_payloads_per_key},{keys_over_payload_cap},{both_polarity_addresses},\
{conformance_raw},{evidence_raw},{discovery_raw},{explanation_raw},{ondemand_raw}",
            suite = args.suite,
            node_occurrences = sharing.node_occurrences,
            distinct_nodes = sharing.distinct_nodes,
            node_redundancy = sharing.node_redundancy(),
            result_occurrences = sharing.result_occurrences,
            distinct_results = sharing.distinct_results,
            result_redundancy = sharing.result_redundancy(),
            support_occurrences = sharing.support_occurrences,
            distinct_support = sharing.distinct_support,
            support_redundancy = sharing.support_redundancy(),
            support_share = sharing.support_share(),
            term_occurrences = sharing.term_occurrences,
            distinct_terms = sharing.distinct_terms,
            term_redundancy = sharing.term_redundancy(),
            normalized_requests = results.normalized_requests,
            duplicate_records = results.duplicate_records,
            divergent_duplicates = results.divergent_duplicates,
            canonical_occurrences = results.canonical_occurrences,
            shared_payloads = results.shared_payloads,
            shared_payload_fraction = results.shared_payload_fraction(),
            shared_canonical_occurrences = results.shared_canonical_occurrences,
            shared_occurrence_fraction = results.shared_occurrence_fraction(),
            request_reaches = results.request_reaches,
            requests_per_payload = results.requests_per_payload(),
            max_payload_requests = results.max_payload_requests,
            distinct_keys = results.distinct_keys,
            key_redundancy = results.key_redundancy(),
            multi_occurrence_keys = results.multi_occurrence_keys,
            divergent_keys = results.divergent_keys,
            divergence_fraction = results.divergence_fraction(),
            divergent_occurrences = results.divergent_occurrences,
            distinct_payloads_per_key = results.distinct_payloads_per_key,
            keys_over_payload_cap = results.keys_over_payload_cap,
            both_polarity_addresses = results.both_polarity_addresses,
            c_med = conformance_ms.median,
            c_mad = conformance_ms.mad,
            e_med = evidence_ms.median,
            e_mad = evidence_ms.mad,
            full_ratio = full_ratio.median,
            full_ratio_mad = full_ratio.mad,
            find_med = discovery_ms.median,
            find_mad = discovery_ms.mad,
            explain_med = explanation_ms.median,
            explain_mad = explanation_ms.mad,
            ondemand_med = on_demand_ms.median,
            ondemand_mad = on_demand_ms.mad,
            ondemand_ratio = on_demand_ratio.median,
            ondemand_ratio_mad = on_demand_ratio.mad,
            serialize_med = serialize_ms.median,
            serialize_mad = serialize_ms.mad,
            conforms_c = conformance.conforms,
            conforms_e = run.conforms,
            conforms_o = on_demand_conformance.conforms,
            pairs_eval = conformance.selected_pairs,
            pass_pairs = conformance.passed,
            fail_pairs = conformance.failed,
            fail_fraction = conformance.failed as f64 / evaluated_pairs,
            authored_pass = authored_pairs - authored_fail_pairs,
            authored_fail = authored_fail_pairs,
            statements = run.statements.len(),
            nodes_per_authored_pair = evidence_nodes as f64 / authored_pairs_denominator,
            bytes_per_authored_pair = evidence_bytes as f64 / authored_pairs_denominator,
            full_with_catalog = full_run_bytes_with_catalog,
            full_no_catalog = full_run_bytes_no_catalog,
            compact_with_catalog = compact_run_bytes_with_catalog,
            compact_no_catalog = compact_run_bytes_no_catalog,
            conformance_raw = samples_string(&conformance_samples),
            evidence_raw = samples_string(&evidence_samples),
            discovery_raw = samples_string(&discovery_samples),
            explanation_raw = samples_string(&explanation_samples),
            ondemand_raw = samples_string(&on_demand_samples),
        );

        eprintln!(
            "median: {:.1}ms conformance, {:.1}ms full ({:.2}x), {:.1}ms on-demand ({:.2}x); {} failures / {} pairs; {iters} rounds",
            conformance_ms.median,
            evidence_ms.median,
            full_ratio.median,
            on_demand_ms.median,
            on_demand_ratio.median,
            conformance.failed,
            conformance.selected_pairs,
        );
    }
}

pub fn data(&self) -> &Graph

The evaluation data graph this snapshot was prepared over: the dataset after inference (when requested), exactly as target selection and the evaluator see it. Borrowed so a caller resolving extra paths (e.g. the shape-map value_paths feature) evaluates over the same graph the run used without cloning it.

pub fn raw_constraint_holds( &self, focus: &Term, constraint: ShapeId, ) -> Option<bool>

Decide one retained authored/raw constraint directly.

Most callers should use normalized constraints and Self::explain_constraint. This is for source-provenance consumers that need a child made unreachable when an enclosing constraint was normalized away (for example, an unbounded qualified property slot).

pub fn validate_conformance( &self, options: &ConformanceOptions, ) -> ConformanceRun

Validate the prepared snapshot for conformance only.

Preparation, target selection, and the evaluator are exactly those of validate; each selected (statement, focus) pair is instead decided by one short-circuiting satisfaction test. No evidence is materialized and no authored-statement progress is computed, so the difference against validate on the same snapshot is the cost of evidence tracing alone.

Every failing pair makes conforms false: severity filtering requires the failure evidence this entry point deliberately does not construct.

Examples found in repository

examples/probe_evidence_cost.rs (line 89)

fn main() {
    let mut shapes_path = PathBuf::new();
    let mut data_path = PathBuf::new();
    let mut no_infer = false;
    let mut top = 15usize;
    let mut dump_json: Option<PathBuf> = None;
    let mut argv = std::env::args().skip(1);
    while let Some(flag) = argv.next() {
        let mut value = || {
            argv.next()
                .unwrap_or_else(|| panic!("{flag} needs a value"))
        };
        match flag.as_str() {
            "--shapes" => shapes_path = PathBuf::from(value()),
            "--data" => data_path = PathBuf::from(value()),
            "--no-infer" => no_infer = true,
            "--top" => top = value().parse().expect("--top must be an integer"),
            "--dump-json" => dump_json = Some(PathBuf::from(value())),
            other => panic!("unknown flag {other}"),
        }
    }
    assert!(!shapes_path.as_os_str().is_empty(), "--shapes is required");
    assert!(!data_path.as_os_str().is_empty(), "--data is required");

    let shapes_bytes = fs::read(&shapes_path).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    let inference_schema = shifty_opt::normalize(&raw_schema);

    let data_bytes = fs::read(&data_path).expect("cannot read --data");
    let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse --data");
    let data_graph = if no_infer {
        data.graph.clone()
    } else {
        shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
            .expect("inference")
            .graph
    };

    let prepared = PreparedEvidenceValidator::with_graphs(
        &data_graph,
        &shapes.graph,
        &raw_schema,
        ValidationGraphMode::Union,
    )
    .expect("stratifiable");
    let options = ValidationOptions::default();
    let scan_options = ConformanceOptions::default();

    println!("model: {}", data_path.display());
    println!("normalized arena nodes: {}", prepared.schema().arena.len());
    println!(
        "normalized statements:  {}",
        prepared.schema().statements.len()
    );
    println!();

    // ---- arm A: conformance only ------------------------------------------
    profile::enable();
    let _ = profile::take_evidence_visits();
    let start = Instant::now();
    let conformance = prepared.validate_conformance(&scan_options);
    let conformance_ms = start.elapsed().as_secs_f64() * 1e3;
    let conformance_visits = profile::take_evidence_visits();
    let conformance_probes = profile::take_path_probes();
    let conformance_cache = profile::take().expect("profiling enabled");
    let conformance_cache = conformance_cache.shape_cache().clone();

    // ---- arm B: dual evidence ----------------------------------------------
    profile::enable();
    let start = Instant::now();
    let run = prepared.validate(&options);
    let evidence_ms = start.elapsed().as_secs_f64() * 1e3;
    let evidence_visits = profile::take_evidence_visits();
    let evidence_probes = profile::take_path_probes();
    let collector = profile::take().expect("profiling enabled");
    let evidence_cache = collector.shape_cache().clone();

    // ---- arm C: on-demand ---------------------------------------------------
    // What a caller pays who wants explanations only for what failed: one
    // conformance pass that also records the failing pairs, then evidence
    // materialized for those pairs alone.
    profile::enable();
    let start = Instant::now();
    let (_, failures) = prepared.find_failures(&scan_options);
    let find_ms = start.elapsed().as_secs_f64() * 1e3;
    let start = Instant::now();
    let explained: usize = failures
        .iter()
        .map(|pair| prepared.explain(pair).len())
        .sum();
    let explain_ms = start.elapsed().as_secs_f64() * 1e3;
    let _ = profile::take();
    let _ = profile::take_evidence_visits();
    let _ = profile::take_path_probes();

    let pairs = conformance.selected_pairs.max(1) as f64;
    let retained = run.walk().len();

    // ---- compact encoding --------------------------------------------------
    let full_json = run.to_json().expect("evidence run serializes");
    // Split so the encoding's own cost is separable from the intermediate
    // `Value` tree it currently has to be handed: compaction is worth doing
    // inline only if the total stays under the validation it describes.
    let to_value_start = Instant::now();
    let run_value = serde_json::to_value(&run).expect("run serializes");
    let to_value_ms = to_value_start.elapsed().as_secs_f64() * 1e3;
    let intern_start = Instant::now();
    let interned = shifty_engine::compact_value(run_value, true);
    let intern_ms = intern_start.elapsed().as_secs_f64() * 1e3;
    let emit_start = Instant::now();
    let compact_json = serde_json::to_string(&interned).expect("compact encoding serializes");
    let emit_ms = emit_start.elapsed().as_secs_f64() * 1e3;
    let compact_ms = to_value_ms + intern_ms + emit_ms;
    drop(interned);
    let compact_no_catalog =
        shifty_engine::to_compact_json(&run, false).expect("compact encoding succeeds");
    println!();
    println!(
        "serialized full:           {:>10.2} MB  ({:.0} bytes/pair)",
        full_json.len() as f64 / 1e6,
        full_json.len() as f64 / pairs
    );
    println!(
        "compact (with catalog):    {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller, {compact_ms:.0} ms \
         = {to_value_ms:.0} to_value + {intern_ms:.0} intern + {emit_ms:.0} emit)",
        compact_json.len() as f64 / 1e6,
        compact_json.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_json.len()) as f64 / full_json.len() as f64
    );
    println!(
        "compact (catalog elided):  {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller)",
        compact_no_catalog.len() as f64 / 1e6,
        compact_no_catalog.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_no_catalog.len()) as f64 / full_json.len() as f64
    );

    if let Some(path) = &dump_json {
        fs::write(path, run.to_json().expect("evidence run serializes"))
            .expect("cannot write --dump-json");
        eprintln!("wrote {}", path.display());
    }

    println!("                        conformance        evidence");
    println!("  wall ms               {conformance_ms:>11.1}  {evidence_ms:>14.1}");
    println!(
        "  memo lookups          {:>11}  {:>14}",
        conformance_cache.hits + conformance_cache.misses,
        evidence_cache.hits + evidence_cache.misses
    );
    println!(
        "  memo hits             {:>11}  {:>14}",
        conformance_cache.hits, evidence_cache.hits
    );
    println!(
        "  memo misses           {:>11}  {:>14}",
        conformance_cache.misses, evidence_cache.misses
    );
    println!(
        "  memo entries (peak)   {:>11}  {:>14}",
        conformance_cache.peak_entries, evidence_cache.peak_entries
    );
    println!(
        "  back-edges            {:>11}  {:>14}",
        conformance_cache.recursion_back_edges, evidence_cache.recursion_back_edges
    );
    println!(
        "  uncacheable results   {:>11}  {:>14}",
        conformance_cache.non_cacheable_results, evidence_cache.non_cacheable_results
    );
    println!("  evidence visits       {conformance_visits:>11}  {evidence_visits:>14}");
    println!("  path_support probes   {conformance_probes:>11}  {evidence_probes:>14}");
    println!();
    println!(
        "path probes per visit:     {:.1}",
        evidence_probes as f64 / evidence_visits.max(1) as f64
    );

    println!("selected pairs:            {}", conformance.selected_pairs);
    println!("retained evidence nodes:   {retained}");
    println!(
        "visited / retained:        {:.1}x",
        evidence_visits as f64 / retained.max(1) as f64
    );
    println!(
        "visits per pair:           {:.0}",
        evidence_visits as f64 / pairs
    );
    println!(
        "distinct (shape,node) that a cache could collapse to at most: {}",
        evidence_cache.peak_entries
    );
    println!(
        "visits / distinct pairs:   {:.1}x",
        evidence_visits as f64 / evidence_cache.peak_entries.max(1) as f64
    );
    println!();
    println!(
        "per-visit cost:            {:.2} us",
        evidence_ms * 1e3 / evidence_visits.max(1) as f64
    );
    println!(
        "per-memo-lookup cost:      {:.2} us",
        conformance_ms * 1e3 / (conformance_cache.hits + conformance_cache.misses).max(1) as f64
    );

    // ---- attribution: which statements own the time ------------------------
    let (selection, materialization): (Vec<_>, Vec<_>) = collector
        .shape_records()
        .iter()
        .partition(|record| record.label.starts_with("select:"));
    let selection_us: u64 = selection.iter().map(|record| record.total_us).sum();
    let materialization_us: u64 = materialization.iter().map(|record| record.total_us).sum();

    println!();
    println!(
        "target selection total:    {:.1} ms over {} statement(s)",
        selection_us as f64 / 1e3,
        selection.len()
    );
    println!(
        "materialization total:     {:.1} ms over {} statement(s)",
        materialization_us as f64 / 1e3,
        materialization.len()
    );
    println!();
    println!(
        "on-demand: {} failing pair(s) of {} selected -> {} explanation(s)",
        failures.len(),
        conformance.selected_pairs,
        explained
    );
    println!(
        "  find_failures {find_ms:.1} ms + explain {explain_ms:.1} ms = {:.1} ms  \
         ({:.2}x the full evidence run, {:.2}x conformance alone)",
        find_ms + explain_ms,
        (find_ms + explain_ms) / evidence_ms.max(f64::MIN_POSITIVE),
        (find_ms + explain_ms) / conformance_ms.max(f64::MIN_POSITIVE)
    );

    let mut ranked = materialization;
    ranked.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by evidence-materialization time:");
    println!(
        "  {:>8}  {:>7}  {:>6}  {:>10}  {:>12}  {:>10}  shape",
        "ms", "share", "foci", "us/focus", "visits", "visits/foci"
    );
    for record in ranked.iter().take(top) {
        println!(
            "  {:>8.1}  {:>6.1}%  {:>6}  {:>10.1}  {:>12}  {:>10.0}  {}",
            record.total_us as f64 / 1e3,
            100.0 * record.total_us as f64 / materialization_us.max(1) as f64,
            record.invocations,
            record.total_us as f64 / record.invocations.max(1) as f64,
            record.visits,
            record.visits as f64 / record.invocations.max(1) as f64,
            record.label,
        );
    }

    let mut ranked_selection = selection;
    ranked_selection.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by target-selection time:");
    for record in ranked_selection.iter().take(5) {
        println!(
            "  {:>8.1} ms  {}",
            record.total_us as f64 / 1e3,
            record.label
        );
    }
}

examples/bench_evidence.rs (line 182)

fn main() {
    let args = parse_args();

    eprintln!("loading shapes {}…", args.shapes.display());
    let shapes_bytes = fs::read(&args.shapes).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    // Inference runs against the normalized schema, exactly as the CLI does.
    let inference_schema = shifty_opt::normalize(&raw_schema);
    drop(shapes_bytes);

    if args.header {
        println!("{COLUMNS}");
    }

    for model in models_in(&args.models) {
        let name = model
            .file_name()
            .and_then(|name| name.to_str())
            .unwrap_or("?")
            .to_string();
        eprint!("{name}… ");

        // ---- untimed setup: everything common to all workflows --------------
        let data_bytes = fs::read(&model).expect("cannot read model");
        let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse model");
        drop(data_bytes);
        let data_graph = if args.no_infer {
            data.graph.clone()
        } else {
            shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
                .unwrap_or_else(|error| panic!("{name}: inference failed: {error}"))
                .graph
        };
        let data_triples = data_graph.len();

        let prepared = PreparedEvidenceValidator::with_graphs(
            &data_graph,
            &shapes.graph,
            &raw_schema,
            ValidationGraphMode::Union,
        )
        .unwrap_or_else(|error| panic!("{name}: schema is non-stratifiable: {error}"));
        let options = ValidationOptions::default();
        let scan_options = ConformanceOptions::default();

        // ---- timed: validation only -----------------------------------------
        // One warm-up round, discarded: it faults in the caches all arms share.
        // Its duration is only consulted when `--budget-ms` is in play.
        let probe = Instant::now();
        let _ = prepared.validate_conformance(&scan_options);
        let _ = prepared.validate_canonical(&options);
        let (_, warm_failures) = prepared.find_failures(&scan_options);
        for pair in &warm_failures {
            std::hint::black_box(prepared.explain_canonical(pair));
        }
        let probe_ms = probe.elapsed().as_secs_f64() * 1e3;
        // Every model gets the same iteration count. `--budget-ms` only caps the
        // count for a corpus slow enough that a fixed count is impractical; it
        // is off by default, and the emitted `iters` column records what was used.
        let iters = if args.budget_ms > 0.0 {
            ((args.budget_ms / probe_ms.max(f64::MIN_POSITIVE)) as usize)
                .clamp(args.min_iters.min(args.iters), args.iters)
        } else {
            args.iters
        };

        let mut conformance_samples = Vec::with_capacity(iters);
        let mut evidence_samples = Vec::with_capacity(iters);
        let mut discovery_samples = Vec::with_capacity(iters);
        let mut explanation_samples = Vec::with_capacity(iters);
        let mut on_demand_samples = Vec::with_capacity(iters);
        let mut last_run = None;
        let mut last_conformance = None;
        let mut last_on_demand_conformance = None;
        let mut last_failures = Vec::new();
        let mut last_explanations = Vec::new();

        // Rotate A/B/C so no arm systematically inherits the cache, allocator,
        // scheduler, or thermal state left by another arm.
        for iteration in 0..iters {
            for arm in ARM_ORDERS[iteration % ARM_ORDERS.len()] {
                match arm {
                    Arm::Conformance => {
                        let start = Instant::now();
                        let conformance_run = prepared.validate_conformance(&scan_options);
                        conformance_samples.push(start.elapsed());
                        std::hint::black_box(conformance_run.selected_pairs);
                        last_conformance = Some(conformance_run);
                    }
                    Arm::FullEvidence => {
                        let start = Instant::now();
                        let run = prepared.validate_canonical(&options);
                        evidence_samples.push(start.elapsed());
                        std::hint::black_box(run.statements.len());
                        last_run = Some(run);
                    }
                    Arm::OnDemand => {
                        let start = Instant::now();
                        let (on_demand_conformance, failures) =
                            prepared.find_failures(&scan_options);
                        let discovery = start.elapsed();

                        let start = Instant::now();
                        let explanations: Vec<_> = failures
                            .iter()
                            .flat_map(|pair| prepared.explain_canonical(pair))
                            .collect();
                        let explanation = start.elapsed();

                        discovery_samples.push(discovery);
                        explanation_samples.push(explanation);
                        on_demand_samples.push(discovery + explanation);
                        std::hint::black_box(explanations.len());
                        last_on_demand_conformance = Some(on_demand_conformance);
                        last_failures = failures;
                        last_explanations = explanations;
                    }
                }
            }
        }

        // ---- untimed: shape of the evidence produced -------------------------
        // Reuse the final timed results rather than paying for another run.
        let conformance = last_conformance.expect("at least one iteration runs");
        let on_demand_conformance =
            last_on_demand_conformance.expect("at least one iteration runs");
        let run = last_run.expect("at least one iteration runs");
        let authored_pairs: usize = run
            .statements
            .iter()
            .map(|statement| statement.selected_foci.len())
            .sum();
        let authored_fail_pairs: usize = run
            .statements
            .iter()
            .flat_map(|statement| &statement.selected_foci)
            .filter(|focus| focus.status() == shifty_engine::EvaluationStatus::Fail)
            .count();

        // The three interfaces must describe the same normalized selection and
        // polarity partition. Compare exact failed identities, not just the
        // report-wide conformance bit.
        assert_eq!(
            conformance, on_demand_conformance,
            "{name}: on-demand counts"
        );
        assert_eq!(
            conformance.conforms, run.conforms,
            "{name}: conformance bit"
        );
        let full_selected: HashSet<_> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement.selected_foci.iter().filter_map(|focus| {
                    statement
                        .normalized_statement_id
                        .map(|id| (id, focus.focus.clone()))
                })
            })
            .collect();
        let full_failures: HashSet<_> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement
                    .selected_foci
                    .iter()
                    .filter(|focus| focus.status() == shifty_engine::EvaluationStatus::Fail)
                    .filter_map(|focus| {
                        statement
                            .normalized_statement_id
                            .map(|id| (id, focus.focus.clone()))
                    })
            })
            .collect();
        let discovered_failures: HashSet<_> = last_failures
            .iter()
            .map(|pair| (pair.normalized_statement(), pair.focus().clone()))
            .collect();
        assert_eq!(
            full_selected.len(),
            conformance.selected_pairs,
            "{name}: selected pairs"
        );
        assert_eq!(
            full_failures.len(),
            conformance.failed,
            "{name}: failed pairs"
        );
        assert_eq!(
            full_selected.len() - full_failures.len(),
            conformance.passed,
            "{name}: passed pairs"
        );
        assert_eq!(
            full_failures, discovered_failures,
            "{name}: failed identities"
        );

        let full_by_authored: HashMap<_, _> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement.selected_foci.iter().map(|focus| {
                    (
                        (statement.source_statement_id, focus.focus.clone()),
                        &focus.evidence,
                    )
                })
            })
            .collect();
        let mut explained_foci = 0;
        for statement in &last_explanations {
            for focus in &statement.selected_foci {
                explained_foci += 1;
                assert_eq!(
                    focus.status(),
                    shifty_engine::EvaluationStatus::Fail,
                    "{name}: on-demand explanation polarity"
                );
                let key = (statement.source_statement_id, focus.focus.clone());
                assert_eq!(
                    &focus.evidence,
                    *full_by_authored
                        .get(&key)
                        .unwrap_or_else(|| panic!("{name}: unexplained full-run pair {key:?}")),
                    "{name}: full and on-demand evidence differ for {key:?}"
                );
            }
        }
        assert_eq!(
            explained_foci, authored_fail_pairs,
            "{name}: authored explanations"
        );

        let evidence_nodes = run.walk().len();
        let evidence_bytes: usize = run
            .statements
            .iter()
            .flat_map(|statement| &statement.selected_foci)
            .map(|focus| focus.evidence.to_json().expect("evidence serializes").len())
            .sum();
        let full_json = run.to_json().expect("evidence run serializes");
        let full_run_bytes_with_catalog = full_json.len();
        let mut full_value_no_catalog =
            serde_json::to_value(&run).expect("evidence run converts to JSON");
        full_value_no_catalog
            .as_object_mut()
            .expect("evidence run is a JSON object")
            .remove("constraints");
        let full_run_bytes_no_catalog = serde_json::to_string(&full_value_no_catalog)
            .expect("catalog-free evidence run serializes")
            .len();

        // Compare complete runs with the same catalog policy on each side, and
        // verify both encodings reconstruct the exact typed result.
        let encoded_with_catalog =
            shifty_engine::compact(&run, true).expect("compact encoding succeeds");
        let compact_run_bytes_with_catalog = serde_json::to_string(&encoded_with_catalog)
            .expect("compact encoding serializes")
            .len();
        assert_eq!(
            shifty_engine::expand(&encoded_with_catalog).expect("compact run expands"),
            run,
            "{name}: compact run with catalog is not lossless"
        );
        let encoded_no_catalog =
            shifty_engine::compact(&run, false).expect("compact encoding succeeds");
        let compact_run_bytes_no_catalog = serde_json::to_string(&encoded_no_catalog)
            .expect("catalog-free compact encoding serializes")
            .len();
        let catalog = serde_json::to_value(&run.constraints).expect("catalog serializes");
        assert_eq!(
            shifty_engine::expand_with_catalog(&encoded_no_catalog, catalog)
                .expect("catalog-free compact run expands"),
            run,
            "{name}: compact run without catalog is not lossless"
        );
        // Sharing is reported over the evidence alone. The node and term tables
        // of `encoded` also hold catalog entries, which would understate the
        // redundancy by adding distinct entries with no evidence occurrences.
        let sharing = shifty_engine::sharing(&run).expect("sharing measures");
        let results = shifty_engine::result_sharing(&run);

        // The two passes reach the same judgment nodes by routes that share no
        // code: `sharing` interns serialized JSON, `result_sharing` walks the
        // typed evidence. Agreement on both counts is what makes either number
        // reportable; a mismatch means the node families are misclassified or a
        // traversal is missing a variant.
        assert_eq!(
            sharing.result_occurrences + sharing.support_occurrences,
            sharing.node_occurrences,
            "{name}: node families do not partition occurrences"
        );
        assert_eq!(
            sharing.distinct_results + sharing.distinct_support,
            sharing.distinct_nodes,
            "{name}: node families do not partition the table"
        );
        assert_eq!(
            sharing.result_occurrences, evidence_nodes,
            "{name}: interned judgments disagree with the typed walk"
        );
        assert_eq!(
            results.occurrences, evidence_nodes,
            "{name}: typed sharing pass disagrees with the typed walk"
        );
        assert_eq!(
            results.distinct_payloads, sharing.distinct_results,
            "{name}: distinct judgments disagree between the two passes"
        );
        // Structural equality implies key equality, never the reverse.
        assert!(
            results.distinct_keys <= results.distinct_payloads,
            "{name}: more keys than payloads"
        );
        // Requests are the normalized selection the conformance pass counts;
        // authored records are the source-preserving view over them.
        assert_eq!(
            results.normalized_requests, conformance.selected_pairs,
            "{name}: requests disagree with the conformance selection"
        );
        assert_eq!(
            results.authored_records, authored_pairs,
            "{name}: authored records disagree with the run"
        );

        // Serialization is measured separately so its allocation traffic does
        // not perturb the next validation arm.
        let mut serialize_samples = Vec::with_capacity(iters);
        for _ in 0..iters {
            let start = Instant::now();
            let json = run.to_json().expect("evidence run serializes");
            serialize_samples.push(start.elapsed());
            std::hint::black_box(json.len());
        }

        // Each ratio compares the corresponding raw samples from one rotated
        // A/B/C round. The CSV retains those samples for independent checking.
        let full_ratios: Vec<f64> = conformance_samples
            .iter()
            .zip(evidence_samples.iter())
            .map(|(conformance, evidence)| {
                evidence.as_secs_f64() / conformance.as_secs_f64().max(f64::MIN_POSITIVE)
            })
            .collect();
        let on_demand_ratios: Vec<f64> = conformance_samples
            .iter()
            .zip(on_demand_samples.iter())
            .map(|(conformance, on_demand)| {
                on_demand.as_secs_f64() / conformance.as_secs_f64().max(f64::MIN_POSITIVE)
            })
            .collect();

        let conformance_ms = summarize_durations(&conformance_samples);
        let evidence_ms = summarize_durations(&evidence_samples);
        let discovery_ms = summarize_durations(&discovery_samples);
        let explanation_ms = summarize_durations(&explanation_samples);
        let on_demand_ms = summarize_durations(&on_demand_samples);
        let serialize_ms = summarize_durations(&serialize_samples);
        let full_ratio = summarize_values(&full_ratios);
        let on_demand_ratio = summarize_values(&on_demand_ratios);
        let evaluated_pairs = conformance.selected_pairs.max(1) as f64;
        let authored_pairs_denominator = authored_pairs.max(1) as f64;

        println!(
            "{suite},{name},{data_triples},{iters},\
{c_med:.4},{c_mad:.4},{e_med:.4},{e_mad:.4},{full_ratio:.4},{full_ratio_mad:.4},\
{find_med:.4},{find_mad:.4},{explain_med:.4},{explain_mad:.4},\
{ondemand_med:.4},{ondemand_mad:.4},{ondemand_ratio:.4},{ondemand_ratio_mad:.4},\
{serialize_med:.4},{serialize_mad:.4},\
{conforms_c},{conforms_e},{conforms_o},\
{pairs_eval},{pass_pairs},{fail_pairs},{fail_fraction:.6},\
{authored_pairs},{authored_pass},{authored_fail},\
{statements},\
{evidence_nodes},{nodes_per_authored_pair:.3},\
{evidence_bytes},{bytes_per_authored_pair:.1},\
{full_with_catalog},{full_no_catalog},{compact_with_catalog},{compact_no_catalog},\
{node_occurrences},{distinct_nodes},{node_redundancy:.3},\
{result_occurrences},{distinct_results},{result_redundancy:.3},\
{support_occurrences},{distinct_support},{support_redundancy:.3},{support_share:.4},\
{term_occurrences},{distinct_terms},{term_redundancy:.3},\
{normalized_requests},{duplicate_records},{divergent_duplicates},\
{canonical_occurrences},{shared_payloads},{shared_payload_fraction:.4},\
{shared_canonical_occurrences},{shared_occurrence_fraction:.4},\
{request_reaches},{requests_per_payload:.3},{max_payload_requests},\
{distinct_keys},{key_redundancy:.3},{multi_occurrence_keys},\
{divergent_keys},{divergence_fraction:.4},{divergent_occurrences},\
{distinct_payloads_per_key},{keys_over_payload_cap},{both_polarity_addresses},\
{conformance_raw},{evidence_raw},{discovery_raw},{explanation_raw},{ondemand_raw}",
            suite = args.suite,
            node_occurrences = sharing.node_occurrences,
            distinct_nodes = sharing.distinct_nodes,
            node_redundancy = sharing.node_redundancy(),
            result_occurrences = sharing.result_occurrences,
            distinct_results = sharing.distinct_results,
            result_redundancy = sharing.result_redundancy(),
            support_occurrences = sharing.support_occurrences,
            distinct_support = sharing.distinct_support,
            support_redundancy = sharing.support_redundancy(),
            support_share = sharing.support_share(),
            term_occurrences = sharing.term_occurrences,
            distinct_terms = sharing.distinct_terms,
            term_redundancy = sharing.term_redundancy(),
            normalized_requests = results.normalized_requests,
            duplicate_records = results.duplicate_records,
            divergent_duplicates = results.divergent_duplicates,
            canonical_occurrences = results.canonical_occurrences,
            shared_payloads = results.shared_payloads,
            shared_payload_fraction = results.shared_payload_fraction(),
            shared_canonical_occurrences = results.shared_canonical_occurrences,
            shared_occurrence_fraction = results.shared_occurrence_fraction(),
            request_reaches = results.request_reaches,
            requests_per_payload = results.requests_per_payload(),
            max_payload_requests = results.max_payload_requests,
            distinct_keys = results.distinct_keys,
            key_redundancy = results.key_redundancy(),
            multi_occurrence_keys = results.multi_occurrence_keys,
            divergent_keys = results.divergent_keys,
            divergence_fraction = results.divergence_fraction(),
            divergent_occurrences = results.divergent_occurrences,
            distinct_payloads_per_key = results.distinct_payloads_per_key,
            keys_over_payload_cap = results.keys_over_payload_cap,
            both_polarity_addresses = results.both_polarity_addresses,
            c_med = conformance_ms.median,
            c_mad = conformance_ms.mad,
            e_med = evidence_ms.median,
            e_mad = evidence_ms.mad,
            full_ratio = full_ratio.median,
            full_ratio_mad = full_ratio.mad,
            find_med = discovery_ms.median,
            find_mad = discovery_ms.mad,
            explain_med = explanation_ms.median,
            explain_mad = explanation_ms.mad,
            ondemand_med = on_demand_ms.median,
            ondemand_mad = on_demand_ms.mad,
            ondemand_ratio = on_demand_ratio.median,
            ondemand_ratio_mad = on_demand_ratio.mad,
            serialize_med = serialize_ms.median,
            serialize_mad = serialize_ms.mad,
            conforms_c = conformance.conforms,
            conforms_e = run.conforms,
            conforms_o = on_demand_conformance.conforms,
            pairs_eval = conformance.selected_pairs,
            pass_pairs = conformance.passed,
            fail_pairs = conformance.failed,
            fail_fraction = conformance.failed as f64 / evaluated_pairs,
            authored_pass = authored_pairs - authored_fail_pairs,
            authored_fail = authored_fail_pairs,
            statements = run.statements.len(),
            nodes_per_authored_pair = evidence_nodes as f64 / authored_pairs_denominator,
            bytes_per_authored_pair = evidence_bytes as f64 / authored_pairs_denominator,
            full_with_catalog = full_run_bytes_with_catalog,
            full_no_catalog = full_run_bytes_no_catalog,
            compact_with_catalog = compact_run_bytes_with_catalog,
            compact_no_catalog = compact_run_bytes_no_catalog,
            conformance_raw = samples_string(&conformance_samples),
            evidence_raw = samples_string(&evidence_samples),
            discovery_raw = samples_string(&discovery_samples),
            explanation_raw = samples_string(&explanation_samples),
            ondemand_raw = samples_string(&on_demand_samples),
        );

        eprintln!(
            "median: {:.1}ms conformance, {:.1}ms full ({:.2}x), {:.1}ms on-demand ({:.2}x); {} failures / {} pairs; {iters} rounds",
            conformance_ms.median,
            evidence_ms.median,
            full_ratio.median,
            on_demand_ms.median,
            on_demand_ratio.median,
            conformance.failed,
            conformance.selected_pairs,
        );
    }
}

pub fn find_failures( &self, options: &ConformanceOptions, ) -> (ConformanceRun, Vec<SelectedPair>)

Conformance totals together with the pairs that failed.

The same single pass as validate_conformance, paying only a Term clone per failing pair, and giving the handles explain needs. On corpora where failures are a small fraction of selected pairs — 8,047 of 286,705 across the Brick suite — this plus per-pair explanation is far cheaper than materializing evidence for everything and discarding the passes.

Examples found in repository

examples/probe_evidence_cost.rs (line 112)

fn main() {
    let mut shapes_path = PathBuf::new();
    let mut data_path = PathBuf::new();
    let mut no_infer = false;
    let mut top = 15usize;
    let mut dump_json: Option<PathBuf> = None;
    let mut argv = std::env::args().skip(1);
    while let Some(flag) = argv.next() {
        let mut value = || {
            argv.next()
                .unwrap_or_else(|| panic!("{flag} needs a value"))
        };
        match flag.as_str() {
            "--shapes" => shapes_path = PathBuf::from(value()),
            "--data" => data_path = PathBuf::from(value()),
            "--no-infer" => no_infer = true,
            "--top" => top = value().parse().expect("--top must be an integer"),
            "--dump-json" => dump_json = Some(PathBuf::from(value())),
            other => panic!("unknown flag {other}"),
        }
    }
    assert!(!shapes_path.as_os_str().is_empty(), "--shapes is required");
    assert!(!data_path.as_os_str().is_empty(), "--data is required");

    let shapes_bytes = fs::read(&shapes_path).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    let inference_schema = shifty_opt::normalize(&raw_schema);

    let data_bytes = fs::read(&data_path).expect("cannot read --data");
    let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse --data");
    let data_graph = if no_infer {
        data.graph.clone()
    } else {
        shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
            .expect("inference")
            .graph
    };

    let prepared = PreparedEvidenceValidator::with_graphs(
        &data_graph,
        &shapes.graph,
        &raw_schema,
        ValidationGraphMode::Union,
    )
    .expect("stratifiable");
    let options = ValidationOptions::default();
    let scan_options = ConformanceOptions::default();

    println!("model: {}", data_path.display());
    println!("normalized arena nodes: {}", prepared.schema().arena.len());
    println!(
        "normalized statements:  {}",
        prepared.schema().statements.len()
    );
    println!();

    // ---- arm A: conformance only ------------------------------------------
    profile::enable();
    let _ = profile::take_evidence_visits();
    let start = Instant::now();
    let conformance = prepared.validate_conformance(&scan_options);
    let conformance_ms = start.elapsed().as_secs_f64() * 1e3;
    let conformance_visits = profile::take_evidence_visits();
    let conformance_probes = profile::take_path_probes();
    let conformance_cache = profile::take().expect("profiling enabled");
    let conformance_cache = conformance_cache.shape_cache().clone();

    // ---- arm B: dual evidence ----------------------------------------------
    profile::enable();
    let start = Instant::now();
    let run = prepared.validate(&options);
    let evidence_ms = start.elapsed().as_secs_f64() * 1e3;
    let evidence_visits = profile::take_evidence_visits();
    let evidence_probes = profile::take_path_probes();
    let collector = profile::take().expect("profiling enabled");
    let evidence_cache = collector.shape_cache().clone();

    // ---- arm C: on-demand ---------------------------------------------------
    // What a caller pays who wants explanations only for what failed: one
    // conformance pass that also records the failing pairs, then evidence
    // materialized for those pairs alone.
    profile::enable();
    let start = Instant::now();
    let (_, failures) = prepared.find_failures(&scan_options);
    let find_ms = start.elapsed().as_secs_f64() * 1e3;
    let start = Instant::now();
    let explained: usize = failures
        .iter()
        .map(|pair| prepared.explain(pair).len())
        .sum();
    let explain_ms = start.elapsed().as_secs_f64() * 1e3;
    let _ = profile::take();
    let _ = profile::take_evidence_visits();
    let _ = profile::take_path_probes();

    let pairs = conformance.selected_pairs.max(1) as f64;
    let retained = run.walk().len();

    // ---- compact encoding --------------------------------------------------
    let full_json = run.to_json().expect("evidence run serializes");
    // Split so the encoding's own cost is separable from the intermediate
    // `Value` tree it currently has to be handed: compaction is worth doing
    // inline only if the total stays under the validation it describes.
    let to_value_start = Instant::now();
    let run_value = serde_json::to_value(&run).expect("run serializes");
    let to_value_ms = to_value_start.elapsed().as_secs_f64() * 1e3;
    let intern_start = Instant::now();
    let interned = shifty_engine::compact_value(run_value, true);
    let intern_ms = intern_start.elapsed().as_secs_f64() * 1e3;
    let emit_start = Instant::now();
    let compact_json = serde_json::to_string(&interned).expect("compact encoding serializes");
    let emit_ms = emit_start.elapsed().as_secs_f64() * 1e3;
    let compact_ms = to_value_ms + intern_ms + emit_ms;
    drop(interned);
    let compact_no_catalog =
        shifty_engine::to_compact_json(&run, false).expect("compact encoding succeeds");
    println!();
    println!(
        "serialized full:           {:>10.2} MB  ({:.0} bytes/pair)",
        full_json.len() as f64 / 1e6,
        full_json.len() as f64 / pairs
    );
    println!(
        "compact (with catalog):    {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller, {compact_ms:.0} ms \
         = {to_value_ms:.0} to_value + {intern_ms:.0} intern + {emit_ms:.0} emit)",
        compact_json.len() as f64 / 1e6,
        compact_json.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_json.len()) as f64 / full_json.len() as f64
    );
    println!(
        "compact (catalog elided):  {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller)",
        compact_no_catalog.len() as f64 / 1e6,
        compact_no_catalog.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_no_catalog.len()) as f64 / full_json.len() as f64
    );

    if let Some(path) = &dump_json {
        fs::write(path, run.to_json().expect("evidence run serializes"))
            .expect("cannot write --dump-json");
        eprintln!("wrote {}", path.display());
    }

    println!("                        conformance        evidence");
    println!("  wall ms               {conformance_ms:>11.1}  {evidence_ms:>14.1}");
    println!(
        "  memo lookups          {:>11}  {:>14}",
        conformance_cache.hits + conformance_cache.misses,
        evidence_cache.hits + evidence_cache.misses
    );
    println!(
        "  memo hits             {:>11}  {:>14}",
        conformance_cache.hits, evidence_cache.hits
    );
    println!(
        "  memo misses           {:>11}  {:>14}",
        conformance_cache.misses, evidence_cache.misses
    );
    println!(
        "  memo entries (peak)   {:>11}  {:>14}",
        conformance_cache.peak_entries, evidence_cache.peak_entries
    );
    println!(
        "  back-edges            {:>11}  {:>14}",
        conformance_cache.recursion_back_edges, evidence_cache.recursion_back_edges
    );
    println!(
        "  uncacheable results   {:>11}  {:>14}",
        conformance_cache.non_cacheable_results, evidence_cache.non_cacheable_results
    );
    println!("  evidence visits       {conformance_visits:>11}  {evidence_visits:>14}");
    println!("  path_support probes   {conformance_probes:>11}  {evidence_probes:>14}");
    println!();
    println!(
        "path probes per visit:     {:.1}",
        evidence_probes as f64 / evidence_visits.max(1) as f64
    );

    println!("selected pairs:            {}", conformance.selected_pairs);
    println!("retained evidence nodes:   {retained}");
    println!(
        "visited / retained:        {:.1}x",
        evidence_visits as f64 / retained.max(1) as f64
    );
    println!(
        "visits per pair:           {:.0}",
        evidence_visits as f64 / pairs
    );
    println!(
        "distinct (shape,node) that a cache could collapse to at most: {}",
        evidence_cache.peak_entries
    );
    println!(
        "visits / distinct pairs:   {:.1}x",
        evidence_visits as f64 / evidence_cache.peak_entries.max(1) as f64
    );
    println!();
    println!(
        "per-visit cost:            {:.2} us",
        evidence_ms * 1e3 / evidence_visits.max(1) as f64
    );
    println!(
        "per-memo-lookup cost:      {:.2} us",
        conformance_ms * 1e3 / (conformance_cache.hits + conformance_cache.misses).max(1) as f64
    );

    // ---- attribution: which statements own the time ------------------------
    let (selection, materialization): (Vec<_>, Vec<_>) = collector
        .shape_records()
        .iter()
        .partition(|record| record.label.starts_with("select:"));
    let selection_us: u64 = selection.iter().map(|record| record.total_us).sum();
    let materialization_us: u64 = materialization.iter().map(|record| record.total_us).sum();

    println!();
    println!(
        "target selection total:    {:.1} ms over {} statement(s)",
        selection_us as f64 / 1e3,
        selection.len()
    );
    println!(
        "materialization total:     {:.1} ms over {} statement(s)",
        materialization_us as f64 / 1e3,
        materialization.len()
    );
    println!();
    println!(
        "on-demand: {} failing pair(s) of {} selected -> {} explanation(s)",
        failures.len(),
        conformance.selected_pairs,
        explained
    );
    println!(
        "  find_failures {find_ms:.1} ms + explain {explain_ms:.1} ms = {:.1} ms  \
         ({:.2}x the full evidence run, {:.2}x conformance alone)",
        find_ms + explain_ms,
        (find_ms + explain_ms) / evidence_ms.max(f64::MIN_POSITIVE),
        (find_ms + explain_ms) / conformance_ms.max(f64::MIN_POSITIVE)
    );

    let mut ranked = materialization;
    ranked.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by evidence-materialization time:");
    println!(
        "  {:>8}  {:>7}  {:>6}  {:>10}  {:>12}  {:>10}  shape",
        "ms", "share", "foci", "us/focus", "visits", "visits/foci"
    );
    for record in ranked.iter().take(top) {
        println!(
            "  {:>8.1}  {:>6.1}%  {:>6}  {:>10.1}  {:>12}  {:>10.0}  {}",
            record.total_us as f64 / 1e3,
            100.0 * record.total_us as f64 / materialization_us.max(1) as f64,
            record.invocations,
            record.total_us as f64 / record.invocations.max(1) as f64,
            record.visits,
            record.visits as f64 / record.invocations.max(1) as f64,
            record.label,
        );
    }

    let mut ranked_selection = selection;
    ranked_selection.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by target-selection time:");
    for record in ranked_selection.iter().take(5) {
        println!(
            "  {:>8.1} ms  {}",
            record.total_us as f64 / 1e3,
            record.label
        );
    }
}

examples/bench_evidence.rs (line 184)

fn main() {
    let args = parse_args();

    eprintln!("loading shapes {}…", args.shapes.display());
    let shapes_bytes = fs::read(&args.shapes).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    // Inference runs against the normalized schema, exactly as the CLI does.
    let inference_schema = shifty_opt::normalize(&raw_schema);
    drop(shapes_bytes);

    if args.header {
        println!("{COLUMNS}");
    }

    for model in models_in(&args.models) {
        let name = model
            .file_name()
            .and_then(|name| name.to_str())
            .unwrap_or("?")
            .to_string();
        eprint!("{name}… ");

        // ---- untimed setup: everything common to all workflows --------------
        let data_bytes = fs::read(&model).expect("cannot read model");
        let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse model");
        drop(data_bytes);
        let data_graph = if args.no_infer {
            data.graph.clone()
        } else {
            shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
                .unwrap_or_else(|error| panic!("{name}: inference failed: {error}"))
                .graph
        };
        let data_triples = data_graph.len();

        let prepared = PreparedEvidenceValidator::with_graphs(
            &data_graph,
            &shapes.graph,
            &raw_schema,
            ValidationGraphMode::Union,
        )
        .unwrap_or_else(|error| panic!("{name}: schema is non-stratifiable: {error}"));
        let options = ValidationOptions::default();
        let scan_options = ConformanceOptions::default();

        // ---- timed: validation only -----------------------------------------
        // One warm-up round, discarded: it faults in the caches all arms share.
        // Its duration is only consulted when `--budget-ms` is in play.
        let probe = Instant::now();
        let _ = prepared.validate_conformance(&scan_options);
        let _ = prepared.validate_canonical(&options);
        let (_, warm_failures) = prepared.find_failures(&scan_options);
        for pair in &warm_failures {
            std::hint::black_box(prepared.explain_canonical(pair));
        }
        let probe_ms = probe.elapsed().as_secs_f64() * 1e3;
        // Every model gets the same iteration count. `--budget-ms` only caps the
        // count for a corpus slow enough that a fixed count is impractical; it
        // is off by default, and the emitted `iters` column records what was used.
        let iters = if args.budget_ms > 0.0 {
            ((args.budget_ms / probe_ms.max(f64::MIN_POSITIVE)) as usize)
                .clamp(args.min_iters.min(args.iters), args.iters)
        } else {
            args.iters
        };

        let mut conformance_samples = Vec::with_capacity(iters);
        let mut evidence_samples = Vec::with_capacity(iters);
        let mut discovery_samples = Vec::with_capacity(iters);
        let mut explanation_samples = Vec::with_capacity(iters);
        let mut on_demand_samples = Vec::with_capacity(iters);
        let mut last_run = None;
        let mut last_conformance = None;
        let mut last_on_demand_conformance = None;
        let mut last_failures = Vec::new();
        let mut last_explanations = Vec::new();

        // Rotate A/B/C so no arm systematically inherits the cache, allocator,
        // scheduler, or thermal state left by another arm.
        for iteration in 0..iters {
            for arm in ARM_ORDERS[iteration % ARM_ORDERS.len()] {
                match arm {
                    Arm::Conformance => {
                        let start = Instant::now();
                        let conformance_run = prepared.validate_conformance(&scan_options);
                        conformance_samples.push(start.elapsed());
                        std::hint::black_box(conformance_run.selected_pairs);
                        last_conformance = Some(conformance_run);
                    }
                    Arm::FullEvidence => {
                        let start = Instant::now();
                        let run = prepared.validate_canonical(&options);
                        evidence_samples.push(start.elapsed());
                        std::hint::black_box(run.statements.len());
                        last_run = Some(run);
                    }
                    Arm::OnDemand => {
                        let start = Instant::now();
                        let (on_demand_conformance, failures) =
                            prepared.find_failures(&scan_options);
                        let discovery = start.elapsed();

                        let start = Instant::now();
                        let explanations: Vec<_> = failures
                            .iter()
                            .flat_map(|pair| prepared.explain_canonical(pair))
                            .collect();
                        let explanation = start.elapsed();

                        discovery_samples.push(discovery);
                        explanation_samples.push(explanation);
                        on_demand_samples.push(discovery + explanation);
                        std::hint::black_box(explanations.len());
                        last_on_demand_conformance = Some(on_demand_conformance);
                        last_failures = failures;
                        last_explanations = explanations;
                    }
                }
            }
        }

        // ---- untimed: shape of the evidence produced -------------------------
        // Reuse the final timed results rather than paying for another run.
        let conformance = last_conformance.expect("at least one iteration runs");
        let on_demand_conformance =
            last_on_demand_conformance.expect("at least one iteration runs");
        let run = last_run.expect("at least one iteration runs");
        let authored_pairs: usize = run
            .statements
            .iter()
            .map(|statement| statement.selected_foci.len())
            .sum();
        let authored_fail_pairs: usize = run
            .statements
            .iter()
            .flat_map(|statement| &statement.selected_foci)
            .filter(|focus| focus.status() == shifty_engine::EvaluationStatus::Fail)
            .count();

        // The three interfaces must describe the same normalized selection and
        // polarity partition. Compare exact failed identities, not just the
        // report-wide conformance bit.
        assert_eq!(
            conformance, on_demand_conformance,
            "{name}: on-demand counts"
        );
        assert_eq!(
            conformance.conforms, run.conforms,
            "{name}: conformance bit"
        );
        let full_selected: HashSet<_> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement.selected_foci.iter().filter_map(|focus| {
                    statement
                        .normalized_statement_id
                        .map(|id| (id, focus.focus.clone()))
                })
            })
            .collect();
        let full_failures: HashSet<_> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement
                    .selected_foci
                    .iter()
                    .filter(|focus| focus.status() == shifty_engine::EvaluationStatus::Fail)
                    .filter_map(|focus| {
                        statement
                            .normalized_statement_id
                            .map(|id| (id, focus.focus.clone()))
                    })
            })
            .collect();
        let discovered_failures: HashSet<_> = last_failures
            .iter()
            .map(|pair| (pair.normalized_statement(), pair.focus().clone()))
            .collect();
        assert_eq!(
            full_selected.len(),
            conformance.selected_pairs,
            "{name}: selected pairs"
        );
        assert_eq!(
            full_failures.len(),
            conformance.failed,
            "{name}: failed pairs"
        );
        assert_eq!(
            full_selected.len() - full_failures.len(),
            conformance.passed,
            "{name}: passed pairs"
        );
        assert_eq!(
            full_failures, discovered_failures,
            "{name}: failed identities"
        );

        let full_by_authored: HashMap<_, _> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement.selected_foci.iter().map(|focus| {
                    (
                        (statement.source_statement_id, focus.focus.clone()),
                        &focus.evidence,
                    )
                })
            })
            .collect();
        let mut explained_foci = 0;
        for statement in &last_explanations {
            for focus in &statement.selected_foci {
                explained_foci += 1;
                assert_eq!(
                    focus.status(),
                    shifty_engine::EvaluationStatus::Fail,
                    "{name}: on-demand explanation polarity"
                );
                let key = (statement.source_statement_id, focus.focus.clone());
                assert_eq!(
                    &focus.evidence,
                    *full_by_authored
                        .get(&key)
                        .unwrap_or_else(|| panic!("{name}: unexplained full-run pair {key:?}")),
                    "{name}: full and on-demand evidence differ for {key:?}"
                );
            }
        }
        assert_eq!(
            explained_foci, authored_fail_pairs,
            "{name}: authored explanations"
        );

        let evidence_nodes = run.walk().len();
        let evidence_bytes: usize = run
            .statements
            .iter()
            .flat_map(|statement| &statement.selected_foci)
            .map(|focus| focus.evidence.to_json().expect("evidence serializes").len())
            .sum();
        let full_json = run.to_json().expect("evidence run serializes");
        let full_run_bytes_with_catalog = full_json.len();
        let mut full_value_no_catalog =
            serde_json::to_value(&run).expect("evidence run converts to JSON");
        full_value_no_catalog
            .as_object_mut()
            .expect("evidence run is a JSON object")
            .remove("constraints");
        let full_run_bytes_no_catalog = serde_json::to_string(&full_value_no_catalog)
            .expect("catalog-free evidence run serializes")
            .len();

        // Compare complete runs with the same catalog policy on each side, and
        // verify both encodings reconstruct the exact typed result.
        let encoded_with_catalog =
            shifty_engine::compact(&run, true).expect("compact encoding succeeds");
        let compact_run_bytes_with_catalog = serde_json::to_string(&encoded_with_catalog)
            .expect("compact encoding serializes")
            .len();
        assert_eq!(
            shifty_engine::expand(&encoded_with_catalog).expect("compact run expands"),
            run,
            "{name}: compact run with catalog is not lossless"
        );
        let encoded_no_catalog =
            shifty_engine::compact(&run, false).expect("compact encoding succeeds");
        let compact_run_bytes_no_catalog = serde_json::to_string(&encoded_no_catalog)
            .expect("catalog-free compact encoding serializes")
            .len();
        let catalog = serde_json::to_value(&run.constraints).expect("catalog serializes");
        assert_eq!(
            shifty_engine::expand_with_catalog(&encoded_no_catalog, catalog)
                .expect("catalog-free compact run expands"),
            run,
            "{name}: compact run without catalog is not lossless"
        );
        // Sharing is reported over the evidence alone. The node and term tables
        // of `encoded` also hold catalog entries, which would understate the
        // redundancy by adding distinct entries with no evidence occurrences.
        let sharing = shifty_engine::sharing(&run).expect("sharing measures");
        let results = shifty_engine::result_sharing(&run);

        // The two passes reach the same judgment nodes by routes that share no
        // code: `sharing` interns serialized JSON, `result_sharing` walks the
        // typed evidence. Agreement on both counts is what makes either number
        // reportable; a mismatch means the node families are misclassified or a
        // traversal is missing a variant.
        assert_eq!(
            sharing.result_occurrences + sharing.support_occurrences,
            sharing.node_occurrences,
            "{name}: node families do not partition occurrences"
        );
        assert_eq!(
            sharing.distinct_results + sharing.distinct_support,
            sharing.distinct_nodes,
            "{name}: node families do not partition the table"
        );
        assert_eq!(
            sharing.result_occurrences, evidence_nodes,
            "{name}: interned judgments disagree with the typed walk"
        );
        assert_eq!(
            results.occurrences, evidence_nodes,
            "{name}: typed sharing pass disagrees with the typed walk"
        );
        assert_eq!(
            results.distinct_payloads, sharing.distinct_results,
            "{name}: distinct judgments disagree between the two passes"
        );
        // Structural equality implies key equality, never the reverse.
        assert!(
            results.distinct_keys <= results.distinct_payloads,
            "{name}: more keys than payloads"
        );
        // Requests are the normalized selection the conformance pass counts;
        // authored records are the source-preserving view over them.
        assert_eq!(
            results.normalized_requests, conformance.selected_pairs,
            "{name}: requests disagree with the conformance selection"
        );
        assert_eq!(
            results.authored_records, authored_pairs,
            "{name}: authored records disagree with the run"
        );

        // Serialization is measured separately so its allocation traffic does
        // not perturb the next validation arm.
        let mut serialize_samples = Vec::with_capacity(iters);
        for _ in 0..iters {
            let start = Instant::now();
            let json = run.to_json().expect("evidence run serializes");
            serialize_samples.push(start.elapsed());
            std::hint::black_box(json.len());
        }

        // Each ratio compares the corresponding raw samples from one rotated
        // A/B/C round. The CSV retains those samples for independent checking.
        let full_ratios: Vec<f64> = conformance_samples
            .iter()
            .zip(evidence_samples.iter())
            .map(|(conformance, evidence)| {
                evidence.as_secs_f64() / conformance.as_secs_f64().max(f64::MIN_POSITIVE)
            })
            .collect();
        let on_demand_ratios: Vec<f64> = conformance_samples
            .iter()
            .zip(on_demand_samples.iter())
            .map(|(conformance, on_demand)| {
                on_demand.as_secs_f64() / conformance.as_secs_f64().max(f64::MIN_POSITIVE)
            })
            .collect();

        let conformance_ms = summarize_durations(&conformance_samples);
        let evidence_ms = summarize_durations(&evidence_samples);
        let discovery_ms = summarize_durations(&discovery_samples);
        let explanation_ms = summarize_durations(&explanation_samples);
        let on_demand_ms = summarize_durations(&on_demand_samples);
        let serialize_ms = summarize_durations(&serialize_samples);
        let full_ratio = summarize_values(&full_ratios);
        let on_demand_ratio = summarize_values(&on_demand_ratios);
        let evaluated_pairs = conformance.selected_pairs.max(1) as f64;
        let authored_pairs_denominator = authored_pairs.max(1) as f64;

        println!(
            "{suite},{name},{data_triples},{iters},\
{c_med:.4},{c_mad:.4},{e_med:.4},{e_mad:.4},{full_ratio:.4},{full_ratio_mad:.4},\
{find_med:.4},{find_mad:.4},{explain_med:.4},{explain_mad:.4},\
{ondemand_med:.4},{ondemand_mad:.4},{ondemand_ratio:.4},{ondemand_ratio_mad:.4},\
{serialize_med:.4},{serialize_mad:.4},\
{conforms_c},{conforms_e},{conforms_o},\
{pairs_eval},{pass_pairs},{fail_pairs},{fail_fraction:.6},\
{authored_pairs},{authored_pass},{authored_fail},\
{statements},\
{evidence_nodes},{nodes_per_authored_pair:.3},\
{evidence_bytes},{bytes_per_authored_pair:.1},\
{full_with_catalog},{full_no_catalog},{compact_with_catalog},{compact_no_catalog},\
{node_occurrences},{distinct_nodes},{node_redundancy:.3},\
{result_occurrences},{distinct_results},{result_redundancy:.3},\
{support_occurrences},{distinct_support},{support_redundancy:.3},{support_share:.4},\
{term_occurrences},{distinct_terms},{term_redundancy:.3},\
{normalized_requests},{duplicate_records},{divergent_duplicates},\
{canonical_occurrences},{shared_payloads},{shared_payload_fraction:.4},\
{shared_canonical_occurrences},{shared_occurrence_fraction:.4},\
{request_reaches},{requests_per_payload:.3},{max_payload_requests},\
{distinct_keys},{key_redundancy:.3},{multi_occurrence_keys},\
{divergent_keys},{divergence_fraction:.4},{divergent_occurrences},\
{distinct_payloads_per_key},{keys_over_payload_cap},{both_polarity_addresses},\
{conformance_raw},{evidence_raw},{discovery_raw},{explanation_raw},{ondemand_raw}",
            suite = args.suite,
            node_occurrences = sharing.node_occurrences,
            distinct_nodes = sharing.distinct_nodes,
            node_redundancy = sharing.node_redundancy(),
            result_occurrences = sharing.result_occurrences,
            distinct_results = sharing.distinct_results,
            result_redundancy = sharing.result_redundancy(),
            support_occurrences = sharing.support_occurrences,
            distinct_support = sharing.distinct_support,
            support_redundancy = sharing.support_redundancy(),
            support_share = sharing.support_share(),
            term_occurrences = sharing.term_occurrences,
            distinct_terms = sharing.distinct_terms,
            term_redundancy = sharing.term_redundancy(),
            normalized_requests = results.normalized_requests,
            duplicate_records = results.duplicate_records,
            divergent_duplicates = results.divergent_duplicates,
            canonical_occurrences = results.canonical_occurrences,
            shared_payloads = results.shared_payloads,
            shared_payload_fraction = results.shared_payload_fraction(),
            shared_canonical_occurrences = results.shared_canonical_occurrences,
            shared_occurrence_fraction = results.shared_occurrence_fraction(),
            request_reaches = results.request_reaches,
            requests_per_payload = results.requests_per_payload(),
            max_payload_requests = results.max_payload_requests,
            distinct_keys = results.distinct_keys,
            key_redundancy = results.key_redundancy(),
            multi_occurrence_keys = results.multi_occurrence_keys,
            divergent_keys = results.divergent_keys,
            divergence_fraction = results.divergence_fraction(),
            divergent_occurrences = results.divergent_occurrences,
            distinct_payloads_per_key = results.distinct_payloads_per_key,
            keys_over_payload_cap = results.keys_over_payload_cap,
            both_polarity_addresses = results.both_polarity_addresses,
            c_med = conformance_ms.median,
            c_mad = conformance_ms.mad,
            e_med = evidence_ms.median,
            e_mad = evidence_ms.mad,
            full_ratio = full_ratio.median,
            full_ratio_mad = full_ratio.mad,
            find_med = discovery_ms.median,
            find_mad = discovery_ms.mad,
            explain_med = explanation_ms.median,
            explain_mad = explanation_ms.mad,
            ondemand_med = on_demand_ms.median,
            ondemand_mad = on_demand_ms.mad,
            ondemand_ratio = on_demand_ratio.median,
            ondemand_ratio_mad = on_demand_ratio.mad,
            serialize_med = serialize_ms.median,
            serialize_mad = serialize_ms.mad,
            conforms_c = conformance.conforms,
            conforms_e = run.conforms,
            conforms_o = on_demand_conformance.conforms,
            pairs_eval = conformance.selected_pairs,
            pass_pairs = conformance.passed,
            fail_pairs = conformance.failed,
            fail_fraction = conformance.failed as f64 / evaluated_pairs,
            authored_pass = authored_pairs - authored_fail_pairs,
            authored_fail = authored_fail_pairs,
            statements = run.statements.len(),
            nodes_per_authored_pair = evidence_nodes as f64 / authored_pairs_denominator,
            bytes_per_authored_pair = evidence_bytes as f64 / authored_pairs_denominator,
            full_with_catalog = full_run_bytes_with_catalog,
            full_no_catalog = full_run_bytes_no_catalog,
            compact_with_catalog = compact_run_bytes_with_catalog,
            compact_no_catalog = compact_run_bytes_no_catalog,
            conformance_raw = samples_string(&conformance_samples),
            evidence_raw = samples_string(&evidence_samples),
            discovery_raw = samples_string(&discovery_samples),
            explanation_raw = samples_string(&explanation_samples),
            ondemand_raw = samples_string(&on_demand_samples),
        );

        eprintln!(
            "median: {:.1}ms conformance, {:.1}ms full ({:.2}x), {:.1}ms on-demand ({:.2}x); {} failures / {} pairs; {iters} rounds",
            conformance_ms.median,
            evidence_ms.median,
            full_ratio.median,
            on_demand_ms.median,
            on_demand_ratio.median,
            conformance.failed,
            conformance.selected_pairs,
        );
    }
}

pub fn explain(&self, pair: &SelectedPair) -> Vec<StatementEvaluation>

Materialize evidence for one pair, in the shape validate would have produced for it.

Returns one StatementEvaluation per authored statement that normalizes to the pair’s normalized statement and was selected when the handle was created, each carrying the single focus, so a caller can treat the result exactly like a slice of a full run. Empty if the statement index is out of range.

Target selection is not re-run: pair is taken as already selected, which is the point — re-deriving the selection would cost what the whole pass costs. Pairs should come from find_failures or from an earlier run over the same snapshot. A focus this statement never selected still yields well-defined evidence; it just describes a pair the run did not contain.

The constraint catalog is not included, since it is fixed per snapshot rather than per pair; take it once from constraints.

Examples found in repository

examples/probe_evidence_cost.rs (line 117)

fn main() {
    let mut shapes_path = PathBuf::new();
    let mut data_path = PathBuf::new();
    let mut no_infer = false;
    let mut top = 15usize;
    let mut dump_json: Option<PathBuf> = None;
    let mut argv = std::env::args().skip(1);
    while let Some(flag) = argv.next() {
        let mut value = || {
            argv.next()
                .unwrap_or_else(|| panic!("{flag} needs a value"))
        };
        match flag.as_str() {
            "--shapes" => shapes_path = PathBuf::from(value()),
            "--data" => data_path = PathBuf::from(value()),
            "--no-infer" => no_infer = true,
            "--top" => top = value().parse().expect("--top must be an integer"),
            "--dump-json" => dump_json = Some(PathBuf::from(value())),
            other => panic!("unknown flag {other}"),
        }
    }
    assert!(!shapes_path.as_os_str().is_empty(), "--shapes is required");
    assert!(!data_path.as_os_str().is_empty(), "--data is required");

    let shapes_bytes = fs::read(&shapes_path).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    let inference_schema = shifty_opt::normalize(&raw_schema);

    let data_bytes = fs::read(&data_path).expect("cannot read --data");
    let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse --data");
    let data_graph = if no_infer {
        data.graph.clone()
    } else {
        shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
            .expect("inference")
            .graph
    };

    let prepared = PreparedEvidenceValidator::with_graphs(
        &data_graph,
        &shapes.graph,
        &raw_schema,
        ValidationGraphMode::Union,
    )
    .expect("stratifiable");
    let options = ValidationOptions::default();
    let scan_options = ConformanceOptions::default();

    println!("model: {}", data_path.display());
    println!("normalized arena nodes: {}", prepared.schema().arena.len());
    println!(
        "normalized statements:  {}",
        prepared.schema().statements.len()
    );
    println!();

    // ---- arm A: conformance only ------------------------------------------
    profile::enable();
    let _ = profile::take_evidence_visits();
    let start = Instant::now();
    let conformance = prepared.validate_conformance(&scan_options);
    let conformance_ms = start.elapsed().as_secs_f64() * 1e3;
    let conformance_visits = profile::take_evidence_visits();
    let conformance_probes = profile::take_path_probes();
    let conformance_cache = profile::take().expect("profiling enabled");
    let conformance_cache = conformance_cache.shape_cache().clone();

    // ---- arm B: dual evidence ----------------------------------------------
    profile::enable();
    let start = Instant::now();
    let run = prepared.validate(&options);
    let evidence_ms = start.elapsed().as_secs_f64() * 1e3;
    let evidence_visits = profile::take_evidence_visits();
    let evidence_probes = profile::take_path_probes();
    let collector = profile::take().expect("profiling enabled");
    let evidence_cache = collector.shape_cache().clone();

    // ---- arm C: on-demand ---------------------------------------------------
    // What a caller pays who wants explanations only for what failed: one
    // conformance pass that also records the failing pairs, then evidence
    // materialized for those pairs alone.
    profile::enable();
    let start = Instant::now();
    let (_, failures) = prepared.find_failures(&scan_options);
    let find_ms = start.elapsed().as_secs_f64() * 1e3;
    let start = Instant::now();
    let explained: usize = failures
        .iter()
        .map(|pair| prepared.explain(pair).len())
        .sum();
    let explain_ms = start.elapsed().as_secs_f64() * 1e3;
    let _ = profile::take();
    let _ = profile::take_evidence_visits();
    let _ = profile::take_path_probes();

    let pairs = conformance.selected_pairs.max(1) as f64;
    let retained = run.walk().len();

    // ---- compact encoding --------------------------------------------------
    let full_json = run.to_json().expect("evidence run serializes");
    // Split so the encoding's own cost is separable from the intermediate
    // `Value` tree it currently has to be handed: compaction is worth doing
    // inline only if the total stays under the validation it describes.
    let to_value_start = Instant::now();
    let run_value = serde_json::to_value(&run).expect("run serializes");
    let to_value_ms = to_value_start.elapsed().as_secs_f64() * 1e3;
    let intern_start = Instant::now();
    let interned = shifty_engine::compact_value(run_value, true);
    let intern_ms = intern_start.elapsed().as_secs_f64() * 1e3;
    let emit_start = Instant::now();
    let compact_json = serde_json::to_string(&interned).expect("compact encoding serializes");
    let emit_ms = emit_start.elapsed().as_secs_f64() * 1e3;
    let compact_ms = to_value_ms + intern_ms + emit_ms;
    drop(interned);
    let compact_no_catalog =
        shifty_engine::to_compact_json(&run, false).expect("compact encoding succeeds");
    println!();
    println!(
        "serialized full:           {:>10.2} MB  ({:.0} bytes/pair)",
        full_json.len() as f64 / 1e6,
        full_json.len() as f64 / pairs
    );
    println!(
        "compact (with catalog):    {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller, {compact_ms:.0} ms \
         = {to_value_ms:.0} to_value + {intern_ms:.0} intern + {emit_ms:.0} emit)",
        compact_json.len() as f64 / 1e6,
        compact_json.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_json.len()) as f64 / full_json.len() as f64
    );
    println!(
        "compact (catalog elided):  {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller)",
        compact_no_catalog.len() as f64 / 1e6,
        compact_no_catalog.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_no_catalog.len()) as f64 / full_json.len() as f64
    );

    if let Some(path) = &dump_json {
        fs::write(path, run.to_json().expect("evidence run serializes"))
            .expect("cannot write --dump-json");
        eprintln!("wrote {}", path.display());
    }

    println!("                        conformance        evidence");
    println!("  wall ms               {conformance_ms:>11.1}  {evidence_ms:>14.1}");
    println!(
        "  memo lookups          {:>11}  {:>14}",
        conformance_cache.hits + conformance_cache.misses,
        evidence_cache.hits + evidence_cache.misses
    );
    println!(
        "  memo hits             {:>11}  {:>14}",
        conformance_cache.hits, evidence_cache.hits
    );
    println!(
        "  memo misses           {:>11}  {:>14}",
        conformance_cache.misses, evidence_cache.misses
    );
    println!(
        "  memo entries (peak)   {:>11}  {:>14}",
        conformance_cache.peak_entries, evidence_cache.peak_entries
    );
    println!(
        "  back-edges            {:>11}  {:>14}",
        conformance_cache.recursion_back_edges, evidence_cache.recursion_back_edges
    );
    println!(
        "  uncacheable results   {:>11}  {:>14}",
        conformance_cache.non_cacheable_results, evidence_cache.non_cacheable_results
    );
    println!("  evidence visits       {conformance_visits:>11}  {evidence_visits:>14}");
    println!("  path_support probes   {conformance_probes:>11}  {evidence_probes:>14}");
    println!();
    println!(
        "path probes per visit:     {:.1}",
        evidence_probes as f64 / evidence_visits.max(1) as f64
    );

    println!("selected pairs:            {}", conformance.selected_pairs);
    println!("retained evidence nodes:   {retained}");
    println!(
        "visited / retained:        {:.1}x",
        evidence_visits as f64 / retained.max(1) as f64
    );
    println!(
        "visits per pair:           {:.0}",
        evidence_visits as f64 / pairs
    );
    println!(
        "distinct (shape,node) that a cache could collapse to at most: {}",
        evidence_cache.peak_entries
    );
    println!(
        "visits / distinct pairs:   {:.1}x",
        evidence_visits as f64 / evidence_cache.peak_entries.max(1) as f64
    );
    println!();
    println!(
        "per-visit cost:            {:.2} us",
        evidence_ms * 1e3 / evidence_visits.max(1) as f64
    );
    println!(
        "per-memo-lookup cost:      {:.2} us",
        conformance_ms * 1e3 / (conformance_cache.hits + conformance_cache.misses).max(1) as f64
    );

    // ---- attribution: which statements own the time ------------------------
    let (selection, materialization): (Vec<_>, Vec<_>) = collector
        .shape_records()
        .iter()
        .partition(|record| record.label.starts_with("select:"));
    let selection_us: u64 = selection.iter().map(|record| record.total_us).sum();
    let materialization_us: u64 = materialization.iter().map(|record| record.total_us).sum();

    println!();
    println!(
        "target selection total:    {:.1} ms over {} statement(s)",
        selection_us as f64 / 1e3,
        selection.len()
    );
    println!(
        "materialization total:     {:.1} ms over {} statement(s)",
        materialization_us as f64 / 1e3,
        materialization.len()
    );
    println!();
    println!(
        "on-demand: {} failing pair(s) of {} selected -> {} explanation(s)",
        failures.len(),
        conformance.selected_pairs,
        explained
    );
    println!(
        "  find_failures {find_ms:.1} ms + explain {explain_ms:.1} ms = {:.1} ms  \
         ({:.2}x the full evidence run, {:.2}x conformance alone)",
        find_ms + explain_ms,
        (find_ms + explain_ms) / evidence_ms.max(f64::MIN_POSITIVE),
        (find_ms + explain_ms) / conformance_ms.max(f64::MIN_POSITIVE)
    );

    let mut ranked = materialization;
    ranked.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by evidence-materialization time:");
    println!(
        "  {:>8}  {:>7}  {:>6}  {:>10}  {:>12}  {:>10}  shape",
        "ms", "share", "foci", "us/focus", "visits", "visits/foci"
    );
    for record in ranked.iter().take(top) {
        println!(
            "  {:>8.1}  {:>6.1}%  {:>6}  {:>10.1}  {:>12}  {:>10.0}  {}",
            record.total_us as f64 / 1e3,
            100.0 * record.total_us as f64 / materialization_us.max(1) as f64,
            record.invocations,
            record.total_us as f64 / record.invocations.max(1) as f64,
            record.visits,
            record.visits as f64 / record.invocations.max(1) as f64,
            record.label,
        );
    }

    let mut ranked_selection = selection;
    ranked_selection.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by target-selection time:");
    for record in ranked_selection.iter().take(5) {
        println!(
            "  {:>8.1} ms  {}",
            record.total_us as f64 / 1e3,
            record.label
        );
    }
}

pub fn explain_canonical(&self, pair: &SelectedPair) -> Vec<StatementEvaluation>

Materialize only the canonical evidence for one pair.

This omits the optional authored-statement progress view while retaining the satisfaction trace or failure witness and the authored identities. It is the per-pair counterpart of validate_canonical.

Examples found in repository

examples/bench_evidence.rs (line 186)

fn main() {
    let args = parse_args();

    eprintln!("loading shapes {}…", args.shapes.display());
    let shapes_bytes = fs::read(&args.shapes).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    // Inference runs against the normalized schema, exactly as the CLI does.
    let inference_schema = shifty_opt::normalize(&raw_schema);
    drop(shapes_bytes);

    if args.header {
        println!("{COLUMNS}");
    }

    for model in models_in(&args.models) {
        let name = model
            .file_name()
            .and_then(|name| name.to_str())
            .unwrap_or("?")
            .to_string();
        eprint!("{name}… ");

        // ---- untimed setup: everything common to all workflows --------------
        let data_bytes = fs::read(&model).expect("cannot read model");
        let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse model");
        drop(data_bytes);
        let data_graph = if args.no_infer {
            data.graph.clone()
        } else {
            shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
                .unwrap_or_else(|error| panic!("{name}: inference failed: {error}"))
                .graph
        };
        let data_triples = data_graph.len();

        let prepared = PreparedEvidenceValidator::with_graphs(
            &data_graph,
            &shapes.graph,
            &raw_schema,
            ValidationGraphMode::Union,
        )
        .unwrap_or_else(|error| panic!("{name}: schema is non-stratifiable: {error}"));
        let options = ValidationOptions::default();
        let scan_options = ConformanceOptions::default();

        // ---- timed: validation only -----------------------------------------
        // One warm-up round, discarded: it faults in the caches all arms share.
        // Its duration is only consulted when `--budget-ms` is in play.
        let probe = Instant::now();
        let _ = prepared.validate_conformance(&scan_options);
        let _ = prepared.validate_canonical(&options);
        let (_, warm_failures) = prepared.find_failures(&scan_options);
        for pair in &warm_failures {
            std::hint::black_box(prepared.explain_canonical(pair));
        }
        let probe_ms = probe.elapsed().as_secs_f64() * 1e3;
        // Every model gets the same iteration count. `--budget-ms` only caps the
        // count for a corpus slow enough that a fixed count is impractical; it
        // is off by default, and the emitted `iters` column records what was used.
        let iters = if args.budget_ms > 0.0 {
            ((args.budget_ms / probe_ms.max(f64::MIN_POSITIVE)) as usize)
                .clamp(args.min_iters.min(args.iters), args.iters)
        } else {
            args.iters
        };

        let mut conformance_samples = Vec::with_capacity(iters);
        let mut evidence_samples = Vec::with_capacity(iters);
        let mut discovery_samples = Vec::with_capacity(iters);
        let mut explanation_samples = Vec::with_capacity(iters);
        let mut on_demand_samples = Vec::with_capacity(iters);
        let mut last_run = None;
        let mut last_conformance = None;
        let mut last_on_demand_conformance = None;
        let mut last_failures = Vec::new();
        let mut last_explanations = Vec::new();

        // Rotate A/B/C so no arm systematically inherits the cache, allocator,
        // scheduler, or thermal state left by another arm.
        for iteration in 0..iters {
            for arm in ARM_ORDERS[iteration % ARM_ORDERS.len()] {
                match arm {
                    Arm::Conformance => {
                        let start = Instant::now();
                        let conformance_run = prepared.validate_conformance(&scan_options);
                        conformance_samples.push(start.elapsed());
                        std::hint::black_box(conformance_run.selected_pairs);
                        last_conformance = Some(conformance_run);
                    }
                    Arm::FullEvidence => {
                        let start = Instant::now();
                        let run = prepared.validate_canonical(&options);
                        evidence_samples.push(start.elapsed());
                        std::hint::black_box(run.statements.len());
                        last_run = Some(run);
                    }
                    Arm::OnDemand => {
                        let start = Instant::now();
                        let (on_demand_conformance, failures) =
                            prepared.find_failures(&scan_options);
                        let discovery = start.elapsed();

                        let start = Instant::now();
                        let explanations: Vec<_> = failures
                            .iter()
                            .flat_map(|pair| prepared.explain_canonical(pair))
                            .collect();
                        let explanation = start.elapsed();

                        discovery_samples.push(discovery);
                        explanation_samples.push(explanation);
                        on_demand_samples.push(discovery + explanation);
                        std::hint::black_box(explanations.len());
                        last_on_demand_conformance = Some(on_demand_conformance);
                        last_failures = failures;
                        last_explanations = explanations;
                    }
                }
            }
        }

        // ---- untimed: shape of the evidence produced -------------------------
        // Reuse the final timed results rather than paying for another run.
        let conformance = last_conformance.expect("at least one iteration runs");
        let on_demand_conformance =
            last_on_demand_conformance.expect("at least one iteration runs");
        let run = last_run.expect("at least one iteration runs");
        let authored_pairs: usize = run
            .statements
            .iter()
            .map(|statement| statement.selected_foci.len())
            .sum();
        let authored_fail_pairs: usize = run
            .statements
            .iter()
            .flat_map(|statement| &statement.selected_foci)
            .filter(|focus| focus.status() == shifty_engine::EvaluationStatus::Fail)
            .count();

        // The three interfaces must describe the same normalized selection and
        // polarity partition. Compare exact failed identities, not just the
        // report-wide conformance bit.
        assert_eq!(
            conformance, on_demand_conformance,
            "{name}: on-demand counts"
        );
        assert_eq!(
            conformance.conforms, run.conforms,
            "{name}: conformance bit"
        );
        let full_selected: HashSet<_> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement.selected_foci.iter().filter_map(|focus| {
                    statement
                        .normalized_statement_id
                        .map(|id| (id, focus.focus.clone()))
                })
            })
            .collect();
        let full_failures: HashSet<_> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement
                    .selected_foci
                    .iter()
                    .filter(|focus| focus.status() == shifty_engine::EvaluationStatus::Fail)
                    .filter_map(|focus| {
                        statement
                            .normalized_statement_id
                            .map(|id| (id, focus.focus.clone()))
                    })
            })
            .collect();
        let discovered_failures: HashSet<_> = last_failures
            .iter()
            .map(|pair| (pair.normalized_statement(), pair.focus().clone()))
            .collect();
        assert_eq!(
            full_selected.len(),
            conformance.selected_pairs,
            "{name}: selected pairs"
        );
        assert_eq!(
            full_failures.len(),
            conformance.failed,
            "{name}: failed pairs"
        );
        assert_eq!(
            full_selected.len() - full_failures.len(),
            conformance.passed,
            "{name}: passed pairs"
        );
        assert_eq!(
            full_failures, discovered_failures,
            "{name}: failed identities"
        );

        let full_by_authored: HashMap<_, _> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement.selected_foci.iter().map(|focus| {
                    (
                        (statement.source_statement_id, focus.focus.clone()),
                        &focus.evidence,
                    )
                })
            })
            .collect();
        let mut explained_foci = 0;
        for statement in &last_explanations {
            for focus in &statement.selected_foci {
                explained_foci += 1;
                assert_eq!(
                    focus.status(),
                    shifty_engine::EvaluationStatus::Fail,
                    "{name}: on-demand explanation polarity"
                );
                let key = (statement.source_statement_id, focus.focus.clone());
                assert_eq!(
                    &focus.evidence,
                    *full_by_authored
                        .get(&key)
                        .unwrap_or_else(|| panic!("{name}: unexplained full-run pair {key:?}")),
                    "{name}: full and on-demand evidence differ for {key:?}"
                );
            }
        }
        assert_eq!(
            explained_foci, authored_fail_pairs,
            "{name}: authored explanations"
        );

        let evidence_nodes = run.walk().len();
        let evidence_bytes: usize = run
            .statements
            .iter()
            .flat_map(|statement| &statement.selected_foci)
            .map(|focus| focus.evidence.to_json().expect("evidence serializes").len())
            .sum();
        let full_json = run.to_json().expect("evidence run serializes");
        let full_run_bytes_with_catalog = full_json.len();
        let mut full_value_no_catalog =
            serde_json::to_value(&run).expect("evidence run converts to JSON");
        full_value_no_catalog
            .as_object_mut()
            .expect("evidence run is a JSON object")
            .remove("constraints");
        let full_run_bytes_no_catalog = serde_json::to_string(&full_value_no_catalog)
            .expect("catalog-free evidence run serializes")
            .len();

        // Compare complete runs with the same catalog policy on each side, and
        // verify both encodings reconstruct the exact typed result.
        let encoded_with_catalog =
            shifty_engine::compact(&run, true).expect("compact encoding succeeds");
        let compact_run_bytes_with_catalog = serde_json::to_string(&encoded_with_catalog)
            .expect("compact encoding serializes")
            .len();
        assert_eq!(
            shifty_engine::expand(&encoded_with_catalog).expect("compact run expands"),
            run,
            "{name}: compact run with catalog is not lossless"
        );
        let encoded_no_catalog =
            shifty_engine::compact(&run, false).expect("compact encoding succeeds");
        let compact_run_bytes_no_catalog = serde_json::to_string(&encoded_no_catalog)
            .expect("catalog-free compact encoding serializes")
            .len();
        let catalog = serde_json::to_value(&run.constraints).expect("catalog serializes");
        assert_eq!(
            shifty_engine::expand_with_catalog(&encoded_no_catalog, catalog)
                .expect("catalog-free compact run expands"),
            run,
            "{name}: compact run without catalog is not lossless"
        );
        // Sharing is reported over the evidence alone. The node and term tables
        // of `encoded` also hold catalog entries, which would understate the
        // redundancy by adding distinct entries with no evidence occurrences.
        let sharing = shifty_engine::sharing(&run).expect("sharing measures");
        let results = shifty_engine::result_sharing(&run);

        // The two passes reach the same judgment nodes by routes that share no
        // code: `sharing` interns serialized JSON, `result_sharing` walks the
        // typed evidence. Agreement on both counts is what makes either number
        // reportable; a mismatch means the node families are misclassified or a
        // traversal is missing a variant.
        assert_eq!(
            sharing.result_occurrences + sharing.support_occurrences,
            sharing.node_occurrences,
            "{name}: node families do not partition occurrences"
        );
        assert_eq!(
            sharing.distinct_results + sharing.distinct_support,
            sharing.distinct_nodes,
            "{name}: node families do not partition the table"
        );
        assert_eq!(
            sharing.result_occurrences, evidence_nodes,
            "{name}: interned judgments disagree with the typed walk"
        );
        assert_eq!(
            results.occurrences, evidence_nodes,
            "{name}: typed sharing pass disagrees with the typed walk"
        );
        assert_eq!(
            results.distinct_payloads, sharing.distinct_results,
            "{name}: distinct judgments disagree between the two passes"
        );
        // Structural equality implies key equality, never the reverse.
        assert!(
            results.distinct_keys <= results.distinct_payloads,
            "{name}: more keys than payloads"
        );
        // Requests are the normalized selection the conformance pass counts;
        // authored records are the source-preserving view over them.
        assert_eq!(
            results.normalized_requests, conformance.selected_pairs,
            "{name}: requests disagree with the conformance selection"
        );
        assert_eq!(
            results.authored_records, authored_pairs,
            "{name}: authored records disagree with the run"
        );

        // Serialization is measured separately so its allocation traffic does
        // not perturb the next validation arm.
        let mut serialize_samples = Vec::with_capacity(iters);
        for _ in 0..iters {
            let start = Instant::now();
            let json = run.to_json().expect("evidence run serializes");
            serialize_samples.push(start.elapsed());
            std::hint::black_box(json.len());
        }

        // Each ratio compares the corresponding raw samples from one rotated
        // A/B/C round. The CSV retains those samples for independent checking.
        let full_ratios: Vec<f64> = conformance_samples
            .iter()
            .zip(evidence_samples.iter())
            .map(|(conformance, evidence)| {
                evidence.as_secs_f64() / conformance.as_secs_f64().max(f64::MIN_POSITIVE)
            })
            .collect();
        let on_demand_ratios: Vec<f64> = conformance_samples
            .iter()
            .zip(on_demand_samples.iter())
            .map(|(conformance, on_demand)| {
                on_demand.as_secs_f64() / conformance.as_secs_f64().max(f64::MIN_POSITIVE)
            })
            .collect();

        let conformance_ms = summarize_durations(&conformance_samples);
        let evidence_ms = summarize_durations(&evidence_samples);
        let discovery_ms = summarize_durations(&discovery_samples);
        let explanation_ms = summarize_durations(&explanation_samples);
        let on_demand_ms = summarize_durations(&on_demand_samples);
        let serialize_ms = summarize_durations(&serialize_samples);
        let full_ratio = summarize_values(&full_ratios);
        let on_demand_ratio = summarize_values(&on_demand_ratios);
        let evaluated_pairs = conformance.selected_pairs.max(1) as f64;
        let authored_pairs_denominator = authored_pairs.max(1) as f64;

        println!(
            "{suite},{name},{data_triples},{iters},\
{c_med:.4},{c_mad:.4},{e_med:.4},{e_mad:.4},{full_ratio:.4},{full_ratio_mad:.4},\
{find_med:.4},{find_mad:.4},{explain_med:.4},{explain_mad:.4},\
{ondemand_med:.4},{ondemand_mad:.4},{ondemand_ratio:.4},{ondemand_ratio_mad:.4},\
{serialize_med:.4},{serialize_mad:.4},\
{conforms_c},{conforms_e},{conforms_o},\
{pairs_eval},{pass_pairs},{fail_pairs},{fail_fraction:.6},\
{authored_pairs},{authored_pass},{authored_fail},\
{statements},\
{evidence_nodes},{nodes_per_authored_pair:.3},\
{evidence_bytes},{bytes_per_authored_pair:.1},\
{full_with_catalog},{full_no_catalog},{compact_with_catalog},{compact_no_catalog},\
{node_occurrences},{distinct_nodes},{node_redundancy:.3},\
{result_occurrences},{distinct_results},{result_redundancy:.3},\
{support_occurrences},{distinct_support},{support_redundancy:.3},{support_share:.4},\
{term_occurrences},{distinct_terms},{term_redundancy:.3},\
{normalized_requests},{duplicate_records},{divergent_duplicates},\
{canonical_occurrences},{shared_payloads},{shared_payload_fraction:.4},\
{shared_canonical_occurrences},{shared_occurrence_fraction:.4},\
{request_reaches},{requests_per_payload:.3},{max_payload_requests},\
{distinct_keys},{key_redundancy:.3},{multi_occurrence_keys},\
{divergent_keys},{divergence_fraction:.4},{divergent_occurrences},\
{distinct_payloads_per_key},{keys_over_payload_cap},{both_polarity_addresses},\
{conformance_raw},{evidence_raw},{discovery_raw},{explanation_raw},{ondemand_raw}",
            suite = args.suite,
            node_occurrences = sharing.node_occurrences,
            distinct_nodes = sharing.distinct_nodes,
            node_redundancy = sharing.node_redundancy(),
            result_occurrences = sharing.result_occurrences,
            distinct_results = sharing.distinct_results,
            result_redundancy = sharing.result_redundancy(),
            support_occurrences = sharing.support_occurrences,
            distinct_support = sharing.distinct_support,
            support_redundancy = sharing.support_redundancy(),
            support_share = sharing.support_share(),
            term_occurrences = sharing.term_occurrences,
            distinct_terms = sharing.distinct_terms,
            term_redundancy = sharing.term_redundancy(),
            normalized_requests = results.normalized_requests,
            duplicate_records = results.duplicate_records,
            divergent_duplicates = results.divergent_duplicates,
            canonical_occurrences = results.canonical_occurrences,
            shared_payloads = results.shared_payloads,
            shared_payload_fraction = results.shared_payload_fraction(),
            shared_canonical_occurrences = results.shared_canonical_occurrences,
            shared_occurrence_fraction = results.shared_occurrence_fraction(),
            request_reaches = results.request_reaches,
            requests_per_payload = results.requests_per_payload(),
            max_payload_requests = results.max_payload_requests,
            distinct_keys = results.distinct_keys,
            key_redundancy = results.key_redundancy(),
            multi_occurrence_keys = results.multi_occurrence_keys,
            divergent_keys = results.divergent_keys,
            divergence_fraction = results.divergence_fraction(),
            divergent_occurrences = results.divergent_occurrences,
            distinct_payloads_per_key = results.distinct_payloads_per_key,
            keys_over_payload_cap = results.keys_over_payload_cap,
            both_polarity_addresses = results.both_polarity_addresses,
            c_med = conformance_ms.median,
            c_mad = conformance_ms.mad,
            e_med = evidence_ms.median,
            e_mad = evidence_ms.mad,
            full_ratio = full_ratio.median,
            full_ratio_mad = full_ratio.mad,
            find_med = discovery_ms.median,
            find_mad = discovery_ms.mad,
            explain_med = explanation_ms.median,
            explain_mad = explanation_ms.mad,
            ondemand_med = on_demand_ms.median,
            ondemand_mad = on_demand_ms.mad,
            ondemand_ratio = on_demand_ratio.median,
            ondemand_ratio_mad = on_demand_ratio.mad,
            serialize_med = serialize_ms.median,
            serialize_mad = serialize_ms.mad,
            conforms_c = conformance.conforms,
            conforms_e = run.conforms,
            conforms_o = on_demand_conformance.conforms,
            pairs_eval = conformance.selected_pairs,
            pass_pairs = conformance.passed,
            fail_pairs = conformance.failed,
            fail_fraction = conformance.failed as f64 / evaluated_pairs,
            authored_pass = authored_pairs - authored_fail_pairs,
            authored_fail = authored_fail_pairs,
            statements = run.statements.len(),
            nodes_per_authored_pair = evidence_nodes as f64 / authored_pairs_denominator,
            bytes_per_authored_pair = evidence_bytes as f64 / authored_pairs_denominator,
            full_with_catalog = full_run_bytes_with_catalog,
            full_no_catalog = full_run_bytes_no_catalog,
            compact_with_catalog = compact_run_bytes_with_catalog,
            compact_no_catalog = compact_run_bytes_no_catalog,
            conformance_raw = samples_string(&conformance_samples),
            evidence_raw = samples_string(&evidence_samples),
            discovery_raw = samples_string(&discovery_samples),
            explanation_raw = samples_string(&explanation_samples),
            ondemand_raw = samples_string(&on_demand_samples),
        );

        eprintln!(
            "median: {:.1}ms conformance, {:.1}ms full ({:.2}x), {:.1}ms on-demand ({:.2}x); {} failures / {} pairs; {iters} rounds",
            conformance_ms.median,
            evidence_ms.median,
            full_ratio.median,
            on_demand_ms.median,
            on_demand_ratio.median,
            conformance.failed,
            conformance.selected_pairs,
        );
    }
}

pub fn source_statements(&self, normalized: usize) -> &[usize]

The authored statements that normalize to normalized, in source order.

Common-subexpression elimination makes this one-to-many: several authored statements can share one normalized statement, which is why explain returns one evaluation per authored statement rather than one per pair. Empty if normalized is out of range.

pub fn explain_constraint( &self, focus: &Term, constraint: ShapeId, ) -> Option<Evidence>

Materialize evidence for one focus against one normalized constraint — any arena id, not just a statement’s top-level shape.

This is the sub-statement counterpart of explain: a failing conjunction’s Witness carries only its failing children, so a caller reconstructing per-property coverage uses the run’s EvaluationProgress to learn which children passed and this method to materialize the satisfaction evidence the witness elided. Like explain, no target selection is involved: the pair is taken as given, and a focus no statement selects still yields well-defined evidence. Returns None when constraint is not an arena id of the normalized schema (see schema).

pub fn constraints(&self) -> ConstraintCatalog

The constraint catalogs an EvidenceRun carries.

Fixed for the snapshot, so a caller explaining pairs one at a time takes this once rather than paying for it per pair — on a small 223P model the catalog is 57% of a whole run’s serialized bytes.

pub fn validate(&self, options: &ValidationOptions) -> EvidenceRun

Validate the prepared snapshot and return its complete coverage horizon.

Examples found in repository

examples/probe_evidence_cost.rs (line 99)

fn main() {
    let mut shapes_path = PathBuf::new();
    let mut data_path = PathBuf::new();
    let mut no_infer = false;
    let mut top = 15usize;
    let mut dump_json: Option<PathBuf> = None;
    let mut argv = std::env::args().skip(1);
    while let Some(flag) = argv.next() {
        let mut value = || {
            argv.next()
                .unwrap_or_else(|| panic!("{flag} needs a value"))
        };
        match flag.as_str() {
            "--shapes" => shapes_path = PathBuf::from(value()),
            "--data" => data_path = PathBuf::from(value()),
            "--no-infer" => no_infer = true,
            "--top" => top = value().parse().expect("--top must be an integer"),
            "--dump-json" => dump_json = Some(PathBuf::from(value())),
            other => panic!("unknown flag {other}"),
        }
    }
    assert!(!shapes_path.as_os_str().is_empty(), "--shapes is required");
    assert!(!data_path.as_os_str().is_empty(), "--data is required");

    let shapes_bytes = fs::read(&shapes_path).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    let inference_schema = shifty_opt::normalize(&raw_schema);

    let data_bytes = fs::read(&data_path).expect("cannot read --data");
    let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse --data");
    let data_graph = if no_infer {
        data.graph.clone()
    } else {
        shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
            .expect("inference")
            .graph
    };

    let prepared = PreparedEvidenceValidator::with_graphs(
        &data_graph,
        &shapes.graph,
        &raw_schema,
        ValidationGraphMode::Union,
    )
    .expect("stratifiable");
    let options = ValidationOptions::default();
    let scan_options = ConformanceOptions::default();

    println!("model: {}", data_path.display());
    println!("normalized arena nodes: {}", prepared.schema().arena.len());
    println!(
        "normalized statements:  {}",
        prepared.schema().statements.len()
    );
    println!();

    // ---- arm A: conformance only ------------------------------------------
    profile::enable();
    let _ = profile::take_evidence_visits();
    let start = Instant::now();
    let conformance = prepared.validate_conformance(&scan_options);
    let conformance_ms = start.elapsed().as_secs_f64() * 1e3;
    let conformance_visits = profile::take_evidence_visits();
    let conformance_probes = profile::take_path_probes();
    let conformance_cache = profile::take().expect("profiling enabled");
    let conformance_cache = conformance_cache.shape_cache().clone();

    // ---- arm B: dual evidence ----------------------------------------------
    profile::enable();
    let start = Instant::now();
    let run = prepared.validate(&options);
    let evidence_ms = start.elapsed().as_secs_f64() * 1e3;
    let evidence_visits = profile::take_evidence_visits();
    let evidence_probes = profile::take_path_probes();
    let collector = profile::take().expect("profiling enabled");
    let evidence_cache = collector.shape_cache().clone();

    // ---- arm C: on-demand ---------------------------------------------------
    // What a caller pays who wants explanations only for what failed: one
    // conformance pass that also records the failing pairs, then evidence
    // materialized for those pairs alone.
    profile::enable();
    let start = Instant::now();
    let (_, failures) = prepared.find_failures(&scan_options);
    let find_ms = start.elapsed().as_secs_f64() * 1e3;
    let start = Instant::now();
    let explained: usize = failures
        .iter()
        .map(|pair| prepared.explain(pair).len())
        .sum();
    let explain_ms = start.elapsed().as_secs_f64() * 1e3;
    let _ = profile::take();
    let _ = profile::take_evidence_visits();
    let _ = profile::take_path_probes();

    let pairs = conformance.selected_pairs.max(1) as f64;
    let retained = run.walk().len();

    // ---- compact encoding --------------------------------------------------
    let full_json = run.to_json().expect("evidence run serializes");
    // Split so the encoding's own cost is separable from the intermediate
    // `Value` tree it currently has to be handed: compaction is worth doing
    // inline only if the total stays under the validation it describes.
    let to_value_start = Instant::now();
    let run_value = serde_json::to_value(&run).expect("run serializes");
    let to_value_ms = to_value_start.elapsed().as_secs_f64() * 1e3;
    let intern_start = Instant::now();
    let interned = shifty_engine::compact_value(run_value, true);
    let intern_ms = intern_start.elapsed().as_secs_f64() * 1e3;
    let emit_start = Instant::now();
    let compact_json = serde_json::to_string(&interned).expect("compact encoding serializes");
    let emit_ms = emit_start.elapsed().as_secs_f64() * 1e3;
    let compact_ms = to_value_ms + intern_ms + emit_ms;
    drop(interned);
    let compact_no_catalog =
        shifty_engine::to_compact_json(&run, false).expect("compact encoding succeeds");
    println!();
    println!(
        "serialized full:           {:>10.2} MB  ({:.0} bytes/pair)",
        full_json.len() as f64 / 1e6,
        full_json.len() as f64 / pairs
    );
    println!(
        "compact (with catalog):    {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller, {compact_ms:.0} ms \
         = {to_value_ms:.0} to_value + {intern_ms:.0} intern + {emit_ms:.0} emit)",
        compact_json.len() as f64 / 1e6,
        compact_json.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_json.len()) as f64 / full_json.len() as f64
    );
    println!(
        "compact (catalog elided):  {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller)",
        compact_no_catalog.len() as f64 / 1e6,
        compact_no_catalog.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_no_catalog.len()) as f64 / full_json.len() as f64
    );

    if let Some(path) = &dump_json {
        fs::write(path, run.to_json().expect("evidence run serializes"))
            .expect("cannot write --dump-json");
        eprintln!("wrote {}", path.display());
    }

    println!("                        conformance        evidence");
    println!("  wall ms               {conformance_ms:>11.1}  {evidence_ms:>14.1}");
    println!(
        "  memo lookups          {:>11}  {:>14}",
        conformance_cache.hits + conformance_cache.misses,
        evidence_cache.hits + evidence_cache.misses
    );
    println!(
        "  memo hits             {:>11}  {:>14}",
        conformance_cache.hits, evidence_cache.hits
    );
    println!(
        "  memo misses           {:>11}  {:>14}",
        conformance_cache.misses, evidence_cache.misses
    );
    println!(
        "  memo entries (peak)   {:>11}  {:>14}",
        conformance_cache.peak_entries, evidence_cache.peak_entries
    );
    println!(
        "  back-edges            {:>11}  {:>14}",
        conformance_cache.recursion_back_edges, evidence_cache.recursion_back_edges
    );
    println!(
        "  uncacheable results   {:>11}  {:>14}",
        conformance_cache.non_cacheable_results, evidence_cache.non_cacheable_results
    );
    println!("  evidence visits       {conformance_visits:>11}  {evidence_visits:>14}");
    println!("  path_support probes   {conformance_probes:>11}  {evidence_probes:>14}");
    println!();
    println!(
        "path probes per visit:     {:.1}",
        evidence_probes as f64 / evidence_visits.max(1) as f64
    );

    println!("selected pairs:            {}", conformance.selected_pairs);
    println!("retained evidence nodes:   {retained}");
    println!(
        "visited / retained:        {:.1}x",
        evidence_visits as f64 / retained.max(1) as f64
    );
    println!(
        "visits per pair:           {:.0}",
        evidence_visits as f64 / pairs
    );
    println!(
        "distinct (shape,node) that a cache could collapse to at most: {}",
        evidence_cache.peak_entries
    );
    println!(
        "visits / distinct pairs:   {:.1}x",
        evidence_visits as f64 / evidence_cache.peak_entries.max(1) as f64
    );
    println!();
    println!(
        "per-visit cost:            {:.2} us",
        evidence_ms * 1e3 / evidence_visits.max(1) as f64
    );
    println!(
        "per-memo-lookup cost:      {:.2} us",
        conformance_ms * 1e3 / (conformance_cache.hits + conformance_cache.misses).max(1) as f64
    );

    // ---- attribution: which statements own the time ------------------------
    let (selection, materialization): (Vec<_>, Vec<_>) = collector
        .shape_records()
        .iter()
        .partition(|record| record.label.starts_with("select:"));
    let selection_us: u64 = selection.iter().map(|record| record.total_us).sum();
    let materialization_us: u64 = materialization.iter().map(|record| record.total_us).sum();

    println!();
    println!(
        "target selection total:    {:.1} ms over {} statement(s)",
        selection_us as f64 / 1e3,
        selection.len()
    );
    println!(
        "materialization total:     {:.1} ms over {} statement(s)",
        materialization_us as f64 / 1e3,
        materialization.len()
    );
    println!();
    println!(
        "on-demand: {} failing pair(s) of {} selected -> {} explanation(s)",
        failures.len(),
        conformance.selected_pairs,
        explained
    );
    println!(
        "  find_failures {find_ms:.1} ms + explain {explain_ms:.1} ms = {:.1} ms  \
         ({:.2}x the full evidence run, {:.2}x conformance alone)",
        find_ms + explain_ms,
        (find_ms + explain_ms) / evidence_ms.max(f64::MIN_POSITIVE),
        (find_ms + explain_ms) / conformance_ms.max(f64::MIN_POSITIVE)
    );

    let mut ranked = materialization;
    ranked.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by evidence-materialization time:");
    println!(
        "  {:>8}  {:>7}  {:>6}  {:>10}  {:>12}  {:>10}  shape",
        "ms", "share", "foci", "us/focus", "visits", "visits/foci"
    );
    for record in ranked.iter().take(top) {
        println!(
            "  {:>8.1}  {:>6.1}%  {:>6}  {:>10.1}  {:>12}  {:>10.0}  {}",
            record.total_us as f64 / 1e3,
            100.0 * record.total_us as f64 / materialization_us.max(1) as f64,
            record.invocations,
            record.total_us as f64 / record.invocations.max(1) as f64,
            record.visits,
            record.visits as f64 / record.invocations.max(1) as f64,
            record.label,
        );
    }

    let mut ranked_selection = selection;
    ranked_selection.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by target-selection time:");
    for record in ranked_selection.iter().take(5) {
        println!(
            "  {:>8.1} ms  {}",
            record.total_us as f64 / 1e3,
            record.label
        );
    }
}

pub fn validate_canonical(&self, options: &ValidationOptions) -> EvidenceRun

Validate the prepared snapshot and return canonical evidence only.

The optional authored-statement progress view is omitted. This is the evidence interface benchmarked against conformance-only validation.

Examples found in repository

examples/bench_evidence.rs (line 183)

fn main() {
    let args = parse_args();

    eprintln!("loading shapes {}…", args.shapes.display());
    let shapes_bytes = fs::read(&args.shapes).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    // Inference runs against the normalized schema, exactly as the CLI does.
    let inference_schema = shifty_opt::normalize(&raw_schema);
    drop(shapes_bytes);

    if args.header {
        println!("{COLUMNS}");
    }

    for model in models_in(&args.models) {
        let name = model
            .file_name()
            .and_then(|name| name.to_str())
            .unwrap_or("?")
            .to_string();
        eprint!("{name}… ");

        // ---- untimed setup: everything common to all workflows --------------
        let data_bytes = fs::read(&model).expect("cannot read model");
        let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse model");
        drop(data_bytes);
        let data_graph = if args.no_infer {
            data.graph.clone()
        } else {
            shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
                .unwrap_or_else(|error| panic!("{name}: inference failed: {error}"))
                .graph
        };
        let data_triples = data_graph.len();

        let prepared = PreparedEvidenceValidator::with_graphs(
            &data_graph,
            &shapes.graph,
            &raw_schema,
            ValidationGraphMode::Union,
        )
        .unwrap_or_else(|error| panic!("{name}: schema is non-stratifiable: {error}"));
        let options = ValidationOptions::default();
        let scan_options = ConformanceOptions::default();

        // ---- timed: validation only -----------------------------------------
        // One warm-up round, discarded: it faults in the caches all arms share.
        // Its duration is only consulted when `--budget-ms` is in play.
        let probe = Instant::now();
        let _ = prepared.validate_conformance(&scan_options);
        let _ = prepared.validate_canonical(&options);
        let (_, warm_failures) = prepared.find_failures(&scan_options);
        for pair in &warm_failures {
            std::hint::black_box(prepared.explain_canonical(pair));
        }
        let probe_ms = probe.elapsed().as_secs_f64() * 1e3;
        // Every model gets the same iteration count. `--budget-ms` only caps the
        // count for a corpus slow enough that a fixed count is impractical; it
        // is off by default, and the emitted `iters` column records what was used.
        let iters = if args.budget_ms > 0.0 {
            ((args.budget_ms / probe_ms.max(f64::MIN_POSITIVE)) as usize)
                .clamp(args.min_iters.min(args.iters), args.iters)
        } else {
            args.iters
        };

        let mut conformance_samples = Vec::with_capacity(iters);
        let mut evidence_samples = Vec::with_capacity(iters);
        let mut discovery_samples = Vec::with_capacity(iters);
        let mut explanation_samples = Vec::with_capacity(iters);
        let mut on_demand_samples = Vec::with_capacity(iters);
        let mut last_run = None;
        let mut last_conformance = None;
        let mut last_on_demand_conformance = None;
        let mut last_failures = Vec::new();
        let mut last_explanations = Vec::new();

        // Rotate A/B/C so no arm systematically inherits the cache, allocator,
        // scheduler, or thermal state left by another arm.
        for iteration in 0..iters {
            for arm in ARM_ORDERS[iteration % ARM_ORDERS.len()] {
                match arm {
                    Arm::Conformance => {
                        let start = Instant::now();
                        let conformance_run = prepared.validate_conformance(&scan_options);
                        conformance_samples.push(start.elapsed());
                        std::hint::black_box(conformance_run.selected_pairs);
                        last_conformance = Some(conformance_run);
                    }
                    Arm::FullEvidence => {
                        let start = Instant::now();
                        let run = prepared.validate_canonical(&options);
                        evidence_samples.push(start.elapsed());
                        std::hint::black_box(run.statements.len());
                        last_run = Some(run);
                    }
                    Arm::OnDemand => {
                        let start = Instant::now();
                        let (on_demand_conformance, failures) =
                            prepared.find_failures(&scan_options);
                        let discovery = start.elapsed();

                        let start = Instant::now();
                        let explanations: Vec<_> = failures
                            .iter()
                            .flat_map(|pair| prepared.explain_canonical(pair))
                            .collect();
                        let explanation = start.elapsed();

                        discovery_samples.push(discovery);
                        explanation_samples.push(explanation);
                        on_demand_samples.push(discovery + explanation);
                        std::hint::black_box(explanations.len());
                        last_on_demand_conformance = Some(on_demand_conformance);
                        last_failures = failures;
                        last_explanations = explanations;
                    }
                }
            }
        }

        // ---- untimed: shape of the evidence produced -------------------------
        // Reuse the final timed results rather than paying for another run.
        let conformance = last_conformance.expect("at least one iteration runs");
        let on_demand_conformance =
            last_on_demand_conformance.expect("at least one iteration runs");
        let run = last_run.expect("at least one iteration runs");
        let authored_pairs: usize = run
            .statements
            .iter()
            .map(|statement| statement.selected_foci.len())
            .sum();
        let authored_fail_pairs: usize = run
            .statements
            .iter()
            .flat_map(|statement| &statement.selected_foci)
            .filter(|focus| focus.status() == shifty_engine::EvaluationStatus::Fail)
            .count();

        // The three interfaces must describe the same normalized selection and
        // polarity partition. Compare exact failed identities, not just the
        // report-wide conformance bit.
        assert_eq!(
            conformance, on_demand_conformance,
            "{name}: on-demand counts"
        );
        assert_eq!(
            conformance.conforms, run.conforms,
            "{name}: conformance bit"
        );
        let full_selected: HashSet<_> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement.selected_foci.iter().filter_map(|focus| {
                    statement
                        .normalized_statement_id
                        .map(|id| (id, focus.focus.clone()))
                })
            })
            .collect();
        let full_failures: HashSet<_> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement
                    .selected_foci
                    .iter()
                    .filter(|focus| focus.status() == shifty_engine::EvaluationStatus::Fail)
                    .filter_map(|focus| {
                        statement
                            .normalized_statement_id
                            .map(|id| (id, focus.focus.clone()))
                    })
            })
            .collect();
        let discovered_failures: HashSet<_> = last_failures
            .iter()
            .map(|pair| (pair.normalized_statement(), pair.focus().clone()))
            .collect();
        assert_eq!(
            full_selected.len(),
            conformance.selected_pairs,
            "{name}: selected pairs"
        );
        assert_eq!(
            full_failures.len(),
            conformance.failed,
            "{name}: failed pairs"
        );
        assert_eq!(
            full_selected.len() - full_failures.len(),
            conformance.passed,
            "{name}: passed pairs"
        );
        assert_eq!(
            full_failures, discovered_failures,
            "{name}: failed identities"
        );

        let full_by_authored: HashMap<_, _> = run
            .statements
            .iter()
            .flat_map(|statement| {
                statement.selected_foci.iter().map(|focus| {
                    (
                        (statement.source_statement_id, focus.focus.clone()),
                        &focus.evidence,
                    )
                })
            })
            .collect();
        let mut explained_foci = 0;
        for statement in &last_explanations {
            for focus in &statement.selected_foci {
                explained_foci += 1;
                assert_eq!(
                    focus.status(),
                    shifty_engine::EvaluationStatus::Fail,
                    "{name}: on-demand explanation polarity"
                );
                let key = (statement.source_statement_id, focus.focus.clone());
                assert_eq!(
                    &focus.evidence,
                    *full_by_authored
                        .get(&key)
                        .unwrap_or_else(|| panic!("{name}: unexplained full-run pair {key:?}")),
                    "{name}: full and on-demand evidence differ for {key:?}"
                );
            }
        }
        assert_eq!(
            explained_foci, authored_fail_pairs,
            "{name}: authored explanations"
        );

        let evidence_nodes = run.walk().len();
        let evidence_bytes: usize = run
            .statements
            .iter()
            .flat_map(|statement| &statement.selected_foci)
            .map(|focus| focus.evidence.to_json().expect("evidence serializes").len())
            .sum();
        let full_json = run.to_json().expect("evidence run serializes");
        let full_run_bytes_with_catalog = full_json.len();
        let mut full_value_no_catalog =
            serde_json::to_value(&run).expect("evidence run converts to JSON");
        full_value_no_catalog
            .as_object_mut()
            .expect("evidence run is a JSON object")
            .remove("constraints");
        let full_run_bytes_no_catalog = serde_json::to_string(&full_value_no_catalog)
            .expect("catalog-free evidence run serializes")
            .len();

        // Compare complete runs with the same catalog policy on each side, and
        // verify both encodings reconstruct the exact typed result.
        let encoded_with_catalog =
            shifty_engine::compact(&run, true).expect("compact encoding succeeds");
        let compact_run_bytes_with_catalog = serde_json::to_string(&encoded_with_catalog)
            .expect("compact encoding serializes")
            .len();
        assert_eq!(
            shifty_engine::expand(&encoded_with_catalog).expect("compact run expands"),
            run,
            "{name}: compact run with catalog is not lossless"
        );
        let encoded_no_catalog =
            shifty_engine::compact(&run, false).expect("compact encoding succeeds");
        let compact_run_bytes_no_catalog = serde_json::to_string(&encoded_no_catalog)
            .expect("catalog-free compact encoding serializes")
            .len();
        let catalog = serde_json::to_value(&run.constraints).expect("catalog serializes");
        assert_eq!(
            shifty_engine::expand_with_catalog(&encoded_no_catalog, catalog)
                .expect("catalog-free compact run expands"),
            run,
            "{name}: compact run without catalog is not lossless"
        );
        // Sharing is reported over the evidence alone. The node and term tables
        // of `encoded` also hold catalog entries, which would understate the
        // redundancy by adding distinct entries with no evidence occurrences.
        let sharing = shifty_engine::sharing(&run).expect("sharing measures");
        let results = shifty_engine::result_sharing(&run);

        // The two passes reach the same judgment nodes by routes that share no
        // code: `sharing` interns serialized JSON, `result_sharing` walks the
        // typed evidence. Agreement on both counts is what makes either number
        // reportable; a mismatch means the node families are misclassified or a
        // traversal is missing a variant.
        assert_eq!(
            sharing.result_occurrences + sharing.support_occurrences,
            sharing.node_occurrences,
            "{name}: node families do not partition occurrences"
        );
        assert_eq!(
            sharing.distinct_results + sharing.distinct_support,
            sharing.distinct_nodes,
            "{name}: node families do not partition the table"
        );
        assert_eq!(
            sharing.result_occurrences, evidence_nodes,
            "{name}: interned judgments disagree with the typed walk"
        );
        assert_eq!(
            results.occurrences, evidence_nodes,
            "{name}: typed sharing pass disagrees with the typed walk"
        );
        assert_eq!(
            results.distinct_payloads, sharing.distinct_results,
            "{name}: distinct judgments disagree between the two passes"
        );
        // Structural equality implies key equality, never the reverse.
        assert!(
            results.distinct_keys <= results.distinct_payloads,
            "{name}: more keys than payloads"
        );
        // Requests are the normalized selection the conformance pass counts;
        // authored records are the source-preserving view over them.
        assert_eq!(
            results.normalized_requests, conformance.selected_pairs,
            "{name}: requests disagree with the conformance selection"
        );
        assert_eq!(
            results.authored_records, authored_pairs,
            "{name}: authored records disagree with the run"
        );

        // Serialization is measured separately so its allocation traffic does
        // not perturb the next validation arm.
        let mut serialize_samples = Vec::with_capacity(iters);
        for _ in 0..iters {
            let start = Instant::now();
            let json = run.to_json().expect("evidence run serializes");
            serialize_samples.push(start.elapsed());
            std::hint::black_box(json.len());
        }

        // Each ratio compares the corresponding raw samples from one rotated
        // A/B/C round. The CSV retains those samples for independent checking.
        let full_ratios: Vec<f64> = conformance_samples
            .iter()
            .zip(evidence_samples.iter())
            .map(|(conformance, evidence)| {
                evidence.as_secs_f64() / conformance.as_secs_f64().max(f64::MIN_POSITIVE)
            })
            .collect();
        let on_demand_ratios: Vec<f64> = conformance_samples
            .iter()
            .zip(on_demand_samples.iter())
            .map(|(conformance, on_demand)| {
                on_demand.as_secs_f64() / conformance.as_secs_f64().max(f64::MIN_POSITIVE)
            })
            .collect();

        let conformance_ms = summarize_durations(&conformance_samples);
        let evidence_ms = summarize_durations(&evidence_samples);
        let discovery_ms = summarize_durations(&discovery_samples);
        let explanation_ms = summarize_durations(&explanation_samples);
        let on_demand_ms = summarize_durations(&on_demand_samples);
        let serialize_ms = summarize_durations(&serialize_samples);
        let full_ratio = summarize_values(&full_ratios);
        let on_demand_ratio = summarize_values(&on_demand_ratios);
        let evaluated_pairs = conformance.selected_pairs.max(1) as f64;
        let authored_pairs_denominator = authored_pairs.max(1) as f64;

        println!(
            "{suite},{name},{data_triples},{iters},\
{c_med:.4},{c_mad:.4},{e_med:.4},{e_mad:.4},{full_ratio:.4},{full_ratio_mad:.4},\
{find_med:.4},{find_mad:.4},{explain_med:.4},{explain_mad:.4},\
{ondemand_med:.4},{ondemand_mad:.4},{ondemand_ratio:.4},{ondemand_ratio_mad:.4},\
{serialize_med:.4},{serialize_mad:.4},\
{conforms_c},{conforms_e},{conforms_o},\
{pairs_eval},{pass_pairs},{fail_pairs},{fail_fraction:.6},\
{authored_pairs},{authored_pass},{authored_fail},\
{statements},\
{evidence_nodes},{nodes_per_authored_pair:.3},\
{evidence_bytes},{bytes_per_authored_pair:.1},\
{full_with_catalog},{full_no_catalog},{compact_with_catalog},{compact_no_catalog},\
{node_occurrences},{distinct_nodes},{node_redundancy:.3},\
{result_occurrences},{distinct_results},{result_redundancy:.3},\
{support_occurrences},{distinct_support},{support_redundancy:.3},{support_share:.4},\
{term_occurrences},{distinct_terms},{term_redundancy:.3},\
{normalized_requests},{duplicate_records},{divergent_duplicates},\
{canonical_occurrences},{shared_payloads},{shared_payload_fraction:.4},\
{shared_canonical_occurrences},{shared_occurrence_fraction:.4},\
{request_reaches},{requests_per_payload:.3},{max_payload_requests},\
{distinct_keys},{key_redundancy:.3},{multi_occurrence_keys},\
{divergent_keys},{divergence_fraction:.4},{divergent_occurrences},\
{distinct_payloads_per_key},{keys_over_payload_cap},{both_polarity_addresses},\
{conformance_raw},{evidence_raw},{discovery_raw},{explanation_raw},{ondemand_raw}",
            suite = args.suite,
            node_occurrences = sharing.node_occurrences,
            distinct_nodes = sharing.distinct_nodes,
            node_redundancy = sharing.node_redundancy(),
            result_occurrences = sharing.result_occurrences,
            distinct_results = sharing.distinct_results,
            result_redundancy = sharing.result_redundancy(),
            support_occurrences = sharing.support_occurrences,
            distinct_support = sharing.distinct_support,
            support_redundancy = sharing.support_redundancy(),
            support_share = sharing.support_share(),
            term_occurrences = sharing.term_occurrences,
            distinct_terms = sharing.distinct_terms,
            term_redundancy = sharing.term_redundancy(),
            normalized_requests = results.normalized_requests,
            duplicate_records = results.duplicate_records,
            divergent_duplicates = results.divergent_duplicates,
            canonical_occurrences = results.canonical_occurrences,
            shared_payloads = results.shared_payloads,
            shared_payload_fraction = results.shared_payload_fraction(),
            shared_canonical_occurrences = results.shared_canonical_occurrences,
            shared_occurrence_fraction = results.shared_occurrence_fraction(),
            request_reaches = results.request_reaches,
            requests_per_payload = results.requests_per_payload(),
            max_payload_requests = results.max_payload_requests,
            distinct_keys = results.distinct_keys,
            key_redundancy = results.key_redundancy(),
            multi_occurrence_keys = results.multi_occurrence_keys,
            divergent_keys = results.divergent_keys,
            divergence_fraction = results.divergence_fraction(),
            divergent_occurrences = results.divergent_occurrences,
            distinct_payloads_per_key = results.distinct_payloads_per_key,
            keys_over_payload_cap = results.keys_over_payload_cap,
            both_polarity_addresses = results.both_polarity_addresses,
            c_med = conformance_ms.median,
            c_mad = conformance_ms.mad,
            e_med = evidence_ms.median,
            e_mad = evidence_ms.mad,
            full_ratio = full_ratio.median,
            full_ratio_mad = full_ratio.mad,
            find_med = discovery_ms.median,
            find_mad = discovery_ms.mad,
            explain_med = explanation_ms.median,
            explain_mad = explanation_ms.mad,
            ondemand_med = on_demand_ms.median,
            ondemand_mad = on_demand_ms.mad,
            ondemand_ratio = on_demand_ratio.median,
            ondemand_ratio_mad = on_demand_ratio.mad,
            serialize_med = serialize_ms.median,
            serialize_mad = serialize_ms.mad,
            conforms_c = conformance.conforms,
            conforms_e = run.conforms,
            conforms_o = on_demand_conformance.conforms,
            pairs_eval = conformance.selected_pairs,
            pass_pairs = conformance.passed,
            fail_pairs = conformance.failed,
            fail_fraction = conformance.failed as f64 / evaluated_pairs,
            authored_pass = authored_pairs - authored_fail_pairs,
            authored_fail = authored_fail_pairs,
            statements = run.statements.len(),
            nodes_per_authored_pair = evidence_nodes as f64 / authored_pairs_denominator,
            bytes_per_authored_pair = evidence_bytes as f64 / authored_pairs_denominator,
            full_with_catalog = full_run_bytes_with_catalog,
            full_no_catalog = full_run_bytes_no_catalog,
            compact_with_catalog = compact_run_bytes_with_catalog,
            compact_no_catalog = compact_run_bytes_no_catalog,
            conformance_raw = samples_string(&conformance_samples),
            evidence_raw = samples_string(&evidence_samples),
            discovery_raw = samples_string(&discovery_samples),
            explanation_raw = samples_string(&explanation_samples),
            ondemand_raw = samples_string(&on_demand_samples),
        );

        eprintln!(
            "median: {:.1}ms conformance, {:.1}ms full ({:.2}x), {:.1}ms on-demand ({:.2}x); {} failures / {} pairs; {iters} rounds",
            conformance_ms.median,
            evidence_ms.median,
            full_ratio.median,
            on_demand_ms.median,
            on_demand_ratio.median,
            conformance.failed,
            conformance.selected_pairs,
        );
    }
}

pub fn schema(&self) -> &Schema

The normalized schema whose ids appear in returned evidence.

Examples found in repository

examples/probe_evidence_cost.rs (line 78)

fn main() {
    let mut shapes_path = PathBuf::new();
    let mut data_path = PathBuf::new();
    let mut no_infer = false;
    let mut top = 15usize;
    let mut dump_json: Option<PathBuf> = None;
    let mut argv = std::env::args().skip(1);
    while let Some(flag) = argv.next() {
        let mut value = || {
            argv.next()
                .unwrap_or_else(|| panic!("{flag} needs a value"))
        };
        match flag.as_str() {
            "--shapes" => shapes_path = PathBuf::from(value()),
            "--data" => data_path = PathBuf::from(value()),
            "--no-infer" => no_infer = true,
            "--top" => top = value().parse().expect("--top must be an integer"),
            "--dump-json" => dump_json = Some(PathBuf::from(value())),
            other => panic!("unknown flag {other}"),
        }
    }
    assert!(!shapes_path.as_os_str().is_empty(), "--shapes is required");
    assert!(!data_path.as_os_str().is_empty(), "--data is required");

    let shapes_bytes = fs::read(&shapes_path).expect("cannot read --shapes");
    let shapes = shifty_parse::load_turtle(&shapes_bytes, None).expect("cannot parse --shapes");
    let parsed = shifty_parse::parse_loaded(&shapes);
    let raw_schema = parsed.schema.clone();
    let inference_schema = shifty_opt::normalize(&raw_schema);

    let data_bytes = fs::read(&data_path).expect("cannot read --data");
    let data = shifty_parse::load_turtle(&data_bytes, None).expect("cannot parse --data");
    let data_graph = if no_infer {
        data.graph.clone()
    } else {
        shifty_engine::infer_graphs(&data.graph, &shapes.graph, &inference_schema)
            .expect("inference")
            .graph
    };

    let prepared = PreparedEvidenceValidator::with_graphs(
        &data_graph,
        &shapes.graph,
        &raw_schema,
        ValidationGraphMode::Union,
    )
    .expect("stratifiable");
    let options = ValidationOptions::default();
    let scan_options = ConformanceOptions::default();

    println!("model: {}", data_path.display());
    println!("normalized arena nodes: {}", prepared.schema().arena.len());
    println!(
        "normalized statements:  {}",
        prepared.schema().statements.len()
    );
    println!();

    // ---- arm A: conformance only ------------------------------------------
    profile::enable();
    let _ = profile::take_evidence_visits();
    let start = Instant::now();
    let conformance = prepared.validate_conformance(&scan_options);
    let conformance_ms = start.elapsed().as_secs_f64() * 1e3;
    let conformance_visits = profile::take_evidence_visits();
    let conformance_probes = profile::take_path_probes();
    let conformance_cache = profile::take().expect("profiling enabled");
    let conformance_cache = conformance_cache.shape_cache().clone();

    // ---- arm B: dual evidence ----------------------------------------------
    profile::enable();
    let start = Instant::now();
    let run = prepared.validate(&options);
    let evidence_ms = start.elapsed().as_secs_f64() * 1e3;
    let evidence_visits = profile::take_evidence_visits();
    let evidence_probes = profile::take_path_probes();
    let collector = profile::take().expect("profiling enabled");
    let evidence_cache = collector.shape_cache().clone();

    // ---- arm C: on-demand ---------------------------------------------------
    // What a caller pays who wants explanations only for what failed: one
    // conformance pass that also records the failing pairs, then evidence
    // materialized for those pairs alone.
    profile::enable();
    let start = Instant::now();
    let (_, failures) = prepared.find_failures(&scan_options);
    let find_ms = start.elapsed().as_secs_f64() * 1e3;
    let start = Instant::now();
    let explained: usize = failures
        .iter()
        .map(|pair| prepared.explain(pair).len())
        .sum();
    let explain_ms = start.elapsed().as_secs_f64() * 1e3;
    let _ = profile::take();
    let _ = profile::take_evidence_visits();
    let _ = profile::take_path_probes();

    let pairs = conformance.selected_pairs.max(1) as f64;
    let retained = run.walk().len();

    // ---- compact encoding --------------------------------------------------
    let full_json = run.to_json().expect("evidence run serializes");
    // Split so the encoding's own cost is separable from the intermediate
    // `Value` tree it currently has to be handed: compaction is worth doing
    // inline only if the total stays under the validation it describes.
    let to_value_start = Instant::now();
    let run_value = serde_json::to_value(&run).expect("run serializes");
    let to_value_ms = to_value_start.elapsed().as_secs_f64() * 1e3;
    let intern_start = Instant::now();
    let interned = shifty_engine::compact_value(run_value, true);
    let intern_ms = intern_start.elapsed().as_secs_f64() * 1e3;
    let emit_start = Instant::now();
    let compact_json = serde_json::to_string(&interned).expect("compact encoding serializes");
    let emit_ms = emit_start.elapsed().as_secs_f64() * 1e3;
    let compact_ms = to_value_ms + intern_ms + emit_ms;
    drop(interned);
    let compact_no_catalog =
        shifty_engine::to_compact_json(&run, false).expect("compact encoding succeeds");
    println!();
    println!(
        "serialized full:           {:>10.2} MB  ({:.0} bytes/pair)",
        full_json.len() as f64 / 1e6,
        full_json.len() as f64 / pairs
    );
    println!(
        "compact (with catalog):    {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller, {compact_ms:.0} ms \
         = {to_value_ms:.0} to_value + {intern_ms:.0} intern + {emit_ms:.0} emit)",
        compact_json.len() as f64 / 1e6,
        compact_json.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_json.len()) as f64 / full_json.len() as f64
    );
    println!(
        "compact (catalog elided):  {:>10.2} MB  ({:.0} bytes/pair, {:.1}% smaller)",
        compact_no_catalog.len() as f64 / 1e6,
        compact_no_catalog.len() as f64 / pairs,
        100.0 * (full_json.len() - compact_no_catalog.len()) as f64 / full_json.len() as f64
    );

    if let Some(path) = &dump_json {
        fs::write(path, run.to_json().expect("evidence run serializes"))
            .expect("cannot write --dump-json");
        eprintln!("wrote {}", path.display());
    }

    println!("                        conformance        evidence");
    println!("  wall ms               {conformance_ms:>11.1}  {evidence_ms:>14.1}");
    println!(
        "  memo lookups          {:>11}  {:>14}",
        conformance_cache.hits + conformance_cache.misses,
        evidence_cache.hits + evidence_cache.misses
    );
    println!(
        "  memo hits             {:>11}  {:>14}",
        conformance_cache.hits, evidence_cache.hits
    );
    println!(
        "  memo misses           {:>11}  {:>14}",
        conformance_cache.misses, evidence_cache.misses
    );
    println!(
        "  memo entries (peak)   {:>11}  {:>14}",
        conformance_cache.peak_entries, evidence_cache.peak_entries
    );
    println!(
        "  back-edges            {:>11}  {:>14}",
        conformance_cache.recursion_back_edges, evidence_cache.recursion_back_edges
    );
    println!(
        "  uncacheable results   {:>11}  {:>14}",
        conformance_cache.non_cacheable_results, evidence_cache.non_cacheable_results
    );
    println!("  evidence visits       {conformance_visits:>11}  {evidence_visits:>14}");
    println!("  path_support probes   {conformance_probes:>11}  {evidence_probes:>14}");
    println!();
    println!(
        "path probes per visit:     {:.1}",
        evidence_probes as f64 / evidence_visits.max(1) as f64
    );

    println!("selected pairs:            {}", conformance.selected_pairs);
    println!("retained evidence nodes:   {retained}");
    println!(
        "visited / retained:        {:.1}x",
        evidence_visits as f64 / retained.max(1) as f64
    );
    println!(
        "visits per pair:           {:.0}",
        evidence_visits as f64 / pairs
    );
    println!(
        "distinct (shape,node) that a cache could collapse to at most: {}",
        evidence_cache.peak_entries
    );
    println!(
        "visits / distinct pairs:   {:.1}x",
        evidence_visits as f64 / evidence_cache.peak_entries.max(1) as f64
    );
    println!();
    println!(
        "per-visit cost:            {:.2} us",
        evidence_ms * 1e3 / evidence_visits.max(1) as f64
    );
    println!(
        "per-memo-lookup cost:      {:.2} us",
        conformance_ms * 1e3 / (conformance_cache.hits + conformance_cache.misses).max(1) as f64
    );

    // ---- attribution: which statements own the time ------------------------
    let (selection, materialization): (Vec<_>, Vec<_>) = collector
        .shape_records()
        .iter()
        .partition(|record| record.label.starts_with("select:"));
    let selection_us: u64 = selection.iter().map(|record| record.total_us).sum();
    let materialization_us: u64 = materialization.iter().map(|record| record.total_us).sum();

    println!();
    println!(
        "target selection total:    {:.1} ms over {} statement(s)",
        selection_us as f64 / 1e3,
        selection.len()
    );
    println!(
        "materialization total:     {:.1} ms over {} statement(s)",
        materialization_us as f64 / 1e3,
        materialization.len()
    );
    println!();
    println!(
        "on-demand: {} failing pair(s) of {} selected -> {} explanation(s)",
        failures.len(),
        conformance.selected_pairs,
        explained
    );
    println!(
        "  find_failures {find_ms:.1} ms + explain {explain_ms:.1} ms = {:.1} ms  \
         ({:.2}x the full evidence run, {:.2}x conformance alone)",
        find_ms + explain_ms,
        (find_ms + explain_ms) / evidence_ms.max(f64::MIN_POSITIVE),
        (find_ms + explain_ms) / conformance_ms.max(f64::MIN_POSITIVE)
    );

    let mut ranked = materialization;
    ranked.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by evidence-materialization time:");
    println!(
        "  {:>8}  {:>7}  {:>6}  {:>10}  {:>12}  {:>10}  shape",
        "ms", "share", "foci", "us/focus", "visits", "visits/foci"
    );
    for record in ranked.iter().take(top) {
        println!(
            "  {:>8.1}  {:>6.1}%  {:>6}  {:>10.1}  {:>12}  {:>10.0}  {}",
            record.total_us as f64 / 1e3,
            100.0 * record.total_us as f64 / materialization_us.max(1) as f64,
            record.invocations,
            record.total_us as f64 / record.invocations.max(1) as f64,
            record.visits,
            record.visits as f64 / record.invocations.max(1) as f64,
            record.label,
        );
    }

    let mut ranked_selection = selection;
    ranked_selection.sort_by_key(|record| std::cmp::Reverse(record.total_us));
    println!();
    println!("top statements by target-selection time:");
    for record in ranked_selection.iter().take(5) {
        println!(
            "  {:>8.1} ms  {}",
            record.total_us as f64 / 1e3,
            record.label
        );
    }
}