Struct EvaluationSession 

pub struct EvaluationSession { /* private fields */ }

Implementations

impl EvaluationSession

pub fn internal_term(&self, term: &Term) -> Term

Resolve a public RDF term to the indexed identity used by evidence constraints. This is a constant-time lookup and leaves other terms alone.

pub fn prepared_evidence(&self) -> &PreparedEvidenceValidator

Borrow the prepared evidence view for existing shape-map projections.

pub fn validate(&self, options: &FindingOptions) -> ValidationOutcome

Examples found in repository

examples/bench_many_sessions.rs (line 54)

fn main() {
    let args: Vec<_> = env::args().skip(1).collect();
    assert!(
        args.len() == 3 || (args.len() == 4 && args[3] == "--infer"),
        "usage: bench_many_sessions SHAPES DATA COUNT [--infer]"
    );
    let count: usize = args[2].parse().expect("COUNT must be an integer");
    assert!(count > 0, "COUNT must be positive");
    let options = SessionOptions {
        inference: args.len() == 4,
        ..SessionOptions::default()
    };
    let findings = FindingOptions::default();

    let started = Instant::now();
    let compiled = CompiledShapes::compile(load(&args[0])).expect("compilable shapes");
    let compile_ms = started.elapsed().as_secs_f64() * 1000.0;
    let data = load(&args[1]).graph;
    let compiled_rss_kib = rss_kib();

    let mut sessions = Vec::with_capacity(count);
    let started = Instant::now();
    let mut first_rss_kib = None;
    for index in 0..count {
        let session = compiled
            .session(SessionData::Separate(data.clone()), options)
            .expect("session");
        black_box(session.validate(&findings));
        sessions.push(session);
        if index == 0 {
            first_rss_kib = rss_kib();
        }
    }
    let sessions_ms = started.elapsed().as_secs_f64() * 1000.0;
    let final_rss_kib = rss_kib();
    black_box(&sessions);
    println!(
        "shapes={},data={},count={count},infer={},compile_ms={compile_ms:.2},sessions_ms={sessions_ms:.2},compiled_rss_kib={compiled_rss_kib:?},first_rss_kib={first_rss_kib:?},final_rss_kib={final_rss_kib:?}",
        args[0], args[1], options.inference,
    );
}

examples/bench_sessions.rs (line 71)

fn main() {
    let args: Vec<_> = env::args().skip(1).collect();
    assert!(
        args.len() == 3 || (args.len() == 4 && args[3] == "--infer"),
        "usage: bench_sessions SHAPES DATA_A DATA_B [--infer]"
    );
    let options = SessionOptions {
        inference: args.len() == 4,
        ..SessionOptions::default()
    };
    let findings = FindingOptions::default();

    let start = Instant::now();
    let shapes = load(&args[0]);
    let load_shapes_ms = start.elapsed().as_secs_f64() * 1000.0;
    let start = Instant::now();
    let compiled = CompiledShapes::compile(shapes).expect("compilable shapes");
    let compile_ms = start.elapsed().as_secs_f64() * 1000.0;
    let compiled_rss_kib = rss_kib();

    let data_a = load(&args[1]).graph;
    let data_b = load(&args[2]).graph;
    let delta = GraphDelta {
        delete: data_a
            .iter()
            .next()
            .map(|triple| triple.into_owned())
            .into_iter()
            .collect(),
        ..GraphDelta::default()
    };

    let start = Instant::now();
    let first = compiled
        .session(SessionData::Separate(data_a), options)
        .expect("first session");
    let first_session_ms = start.elapsed().as_secs_f64() * 1000.0;
    let start = Instant::now();
    black_box(first.validate(&findings));
    let first_validate_ms = start.elapsed().as_secs_f64() * 1000.0;
    let first_rss_kib = rss_kib();

    let start = Instant::now();
    for _ in 0..3 {
        black_box(first.validate(&findings));
    }
    let repeated_validate_ms = start.elapsed().as_secs_f64() * 1000.0 / 3.0;

    let start = Instant::now();
    let second = compiled
        .session(SessionData::Separate(data_b), options)
        .expect("second session");
    let second_session_ms = start.elapsed().as_secs_f64() * 1000.0;
    let start = Instant::now();
    black_box(second.validate(&findings));
    let second_validate_ms = start.elapsed().as_secs_f64() * 1000.0;
    let second_rss_kib = rss_kib();

    let start = Instant::now();
    let edited = first.with_delta(&delta).expect("edited session");
    let edit_session_ms = start.elapsed().as_secs_f64() * 1000.0;
    let start = Instant::now();
    black_box(edited.validate(&findings));
    let edit_validate_ms = start.elapsed().as_secs_f64() * 1000.0;
    let edited_rss_kib = rss_kib();

    println!(
        "shapes={},data_a={},data_b={},infer={},load_shapes_ms={load_shapes_ms:.2},compile_ms={compile_ms:.2},first_session_ms={first_session_ms:.2},first_validate_ms={first_validate_ms:.2},repeated_validate_ms={repeated_validate_ms:.2},second_session_ms={second_session_ms:.2},second_validate_ms={second_validate_ms:.2},edit_session_ms={edit_session_ms:.2},edit_validate_ms={edit_validate_ms:.2},compiled_rss_kib={compiled_rss_kib:?},first_rss_kib={first_rss_kib:?},second_rss_kib={second_rss_kib:?},edited_rss_kib={edited_rss_kib:?}",
        args[0], args[1], args[2], options.inference,
    );
}

pub fn report(&self, options: &FindingOptions) -> ValidationReport

pub fn property_witnesses( &self, key_path: Option<&Path>, options: &FindingOptions, ) -> Vec<PropertyWitness>

pub fn evidence(&self, options: &EvidenceOptions) -> EvidenceRun

pub fn evidence_with_validation( &self, validation: &ValidationOptions, include_progress: bool, ) -> EvidenceRun

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

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

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

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

pub fn with_delta(&self, delta: &GraphDelta) -> Result<Self, SessionError>

Examples found in repository

examples/bench_sessions.rs (line 92)

fn main() {
    let args: Vec<_> = env::args().skip(1).collect();
    assert!(
        args.len() == 3 || (args.len() == 4 && args[3] == "--infer"),
        "usage: bench_sessions SHAPES DATA_A DATA_B [--infer]"
    );
    let options = SessionOptions {
        inference: args.len() == 4,
        ..SessionOptions::default()
    };
    let findings = FindingOptions::default();

    let start = Instant::now();
    let shapes = load(&args[0]);
    let load_shapes_ms = start.elapsed().as_secs_f64() * 1000.0;
    let start = Instant::now();
    let compiled = CompiledShapes::compile(shapes).expect("compilable shapes");
    let compile_ms = start.elapsed().as_secs_f64() * 1000.0;
    let compiled_rss_kib = rss_kib();

    let data_a = load(&args[1]).graph;
    let data_b = load(&args[2]).graph;
    let delta = GraphDelta {
        delete: data_a
            .iter()
            .next()
            .map(|triple| triple.into_owned())
            .into_iter()
            .collect(),
        ..GraphDelta::default()
    };

    let start = Instant::now();
    let first = compiled
        .session(SessionData::Separate(data_a), options)
        .expect("first session");
    let first_session_ms = start.elapsed().as_secs_f64() * 1000.0;
    let start = Instant::now();
    black_box(first.validate(&findings));
    let first_validate_ms = start.elapsed().as_secs_f64() * 1000.0;
    let first_rss_kib = rss_kib();

    let start = Instant::now();
    for _ in 0..3 {
        black_box(first.validate(&findings));
    }
    let repeated_validate_ms = start.elapsed().as_secs_f64() * 1000.0 / 3.0;

    let start = Instant::now();
    let second = compiled
        .session(SessionData::Separate(data_b), options)
        .expect("second session");
    let second_session_ms = start.elapsed().as_secs_f64() * 1000.0;
    let start = Instant::now();
    black_box(second.validate(&findings));
    let second_validate_ms = start.elapsed().as_secs_f64() * 1000.0;
    let second_rss_kib = rss_kib();

    let start = Instant::now();
    let edited = first.with_delta(&delta).expect("edited session");
    let edit_session_ms = start.elapsed().as_secs_f64() * 1000.0;
    let start = Instant::now();
    black_box(edited.validate(&findings));
    let edit_validate_ms = start.elapsed().as_secs_f64() * 1000.0;
    let edited_rss_kib = rss_kib();

    println!(
        "shapes={},data_a={},data_b={},infer={},load_shapes_ms={load_shapes_ms:.2},compile_ms={compile_ms:.2},first_session_ms={first_session_ms:.2},first_validate_ms={first_validate_ms:.2},repeated_validate_ms={repeated_validate_ms:.2},second_session_ms={second_session_ms:.2},second_validate_ms={second_validate_ms:.2},edit_session_ms={edit_session_ms:.2},edit_validate_ms={edit_validate_ms:.2},compiled_rss_kib={compiled_rss_kib:?},first_rss_kib={first_rss_kib:?},second_rss_kib={second_rss_kib:?},edited_rss_kib={edited_rss_kib:?}",
        args[0], args[1], args[2], options.inference,
    );
}

pub fn with_delta_and_inference( &self, delta: &GraphDelta, inference: bool, ) -> Result<Self, SessionError>

Revalidate a delta with a different inference setting. Enabling rules patches asserted data and derives again; disabling them patches the already evaluated graph so previously inferred triples remain present.

pub fn data(&self) -> &Graph

Examples found in repository

examples/probe_evidence_cost.rs (line 70)

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 compiled = CompiledShapes::compile(shapes).expect("cannot compile shapes");

    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 {
        compiled
            .session(
                SessionData::Separate(data.graph.clone()),
                SessionOptions {
                    inference: true,
                    ..SessionOptions::default()
                },
            )
            .expect("inference")
            .data()
            .clone()
    };

    let prepared = PreparedEvidenceValidator::with_graphs(
        &data_graph,
        &compiled.source().graph,
        compiled.authored_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 169)

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 compiled = CompiledShapes::compile(shapes).expect("cannot compile shapes");
    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 {
            compiled
                .session(
                    SessionData::Separate(data.graph.clone()),
                    SessionOptions {
                        inference: true,
                        ..SessionOptions::default()
                    },
                )
                .unwrap_or_else(|error| panic!("{name}: inference failed: {error}"))
                .data()
                .clone()
        };
        let data_triples = data_graph.len();

        let prepared = PreparedEvidenceValidator::with_graphs(
            &data_graph,
            &compiled.source().graph,
            compiled.authored_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_shared(&self) -> Arc<Graph>

Share the evaluated data graph without copying it.

pub fn public_shapes_graph_if_relabelled(&self) -> Option<Graph>

A source graph with only colliding blank nodes relabeled for combining with the public data graph. No copy is made when scopes do not collide.

pub fn public_schema(&self, schema: Arc<Schema>) -> Arc<Schema>

Relabel shape constants only when a split graph has a blank-node collision; otherwise preserve the caller’s shared schema allocation.

pub fn asserted_shared(&self) -> Arc<Graph>

Share the asserted data graph used by with_delta.

pub fn inferred(&self) -> &[Triple]

pub fn inferred_count(&self) -> usize

Count inferred triples without materializing their public RDF terms.

pub fn inferred_for_write_back(&self) -> Vec<Triple>

Inferred triples with input data blank-node labels restored and shapes nodes kept distinct, for adding the delta to a caller-owned data graph.

pub fn diagnostics(&self) -> &[ExecutionDiagnostic]

pub fn gate(&self, delta: &GraphDelta) -> Result<RepairOutcome, SessionError>