.nornir/worlddelta-guide.md

worlddelta (Engine B) — guide

Class: guide · audience: someone driving the world-delta engine in code. The what is in worlddelta-design.md; the why in worlddelta-reasoning.md. Needs --features scip.

f0 — diff two worlds

use modgunn::scip::{self, WorldSnapshot, Symbol, CallEdge, Capability, VulnSink};

// build the "before" and "after" snapshots (normally captured from the warehouse)
let mut from = WorldSnapshot::new("t0");
let mut to   = WorldSnapshot::new("t1");
// … populate .symbols / .calls / .dep_nodes / .dep_edges / .vuln_sinks …

let delta = scip::diff(&from, &to);          // runs the default tripwire battery
for f in &delta.findings {
    println!("{:?} {} — {}", f.severity, f.id, f.summary);
}
let decision = delta.decision();             // Pass / Warn / Block

To fold the delta into the same verdict shape Engine A emits, call scip::verdict_from(...). To plug extra analyses in at the heavy site, use scip::diff_with(&from, &to, &tripwires).

f1 — building a snapshot

let sym = Symbol::new("crate::net::connect", "some-crate")
    .entrypoint()                            // a BFS source
    .with_capability(Capability::Network);
from.symbols.push(sym);
from.calls.push(CallEdge::new("a", "b"));
from.vuln_sinks.push(VulnSink { symbol: "b".into(), advisory: "CVE-…".into(),
                                severity: modgunn::core::Severity::High });

f3 — standing analyses on one snapshot

let reachable = scip::reachability_gated_vulns(&to);   // A8 — only CVEs actually callable
let caps      = scip::capability_surface(&to);         // A9 — net/fs/proc/… reachable set
let ranked    = scip::blast_radius(&to);               // A13 — PageRank (node, score)

Feed reachability_gated_vulns back into Engine A to suppress unreachable CVEs (the automated counterpart to VEX): the sinks it does not return are the ones to add to Policy::vex_not_affected.

f3 — persist to the warehouse (feature `scip` + `warehouse`)

let wh = modgunn::warehouse::Warehouse::open(root)?;
wh.ensure_modgunn_tables()?;
wh.capture_world_snapshot(&to)?;             // world_snapshots + dep_edges + scip_symbols
let delta = scip::diff(&from, &to);
wh.record_behavior_delta_findings(&delta)?;  // behavior_deltas rows

Gotchas

Engine B is heavy and off by default — build it only where you have the RAM (cargo build --features scip).
FingerprintDriftTripwire fires only on the silent case: identical package version + public API but a changed transitive closure. A version bump or API change is not a drift finding — that is by design (those are visible already).
Entrypoints matter: a snapshot with no is_entrypoint symbols has an empty reachable set, so reachability-gated vulns and capability surface come back empty.