A declared causal graph, fitted mechanisms, checks on held-out data, then an incident and candidate repairs. This synthetic system has a known answer, so we can check the whole workflow. All fitting and evaluation code runs natively in Clojure and ClojureScript.
(ns foerster.causal-workflow
(:require [org.replikativ.foerster.causal.model :as cm]
[org.replikativ.foerster.causal.counterfactual :as cf]
[org.replikativ.foerster.causal.attribution :as attribution]
[org.replikativ.foerster.dist :as dist]
[org.replikativ.foerster.random :as random]
[org.replikativ.spindel.core :as sp]))Workload drives queue delay and latency; queue delay also drives latency. Load and queue are centered operating measurements; latency is in ms. The true equations are load = U₁, queue = load + U₂, and latency = 100 + 20 queue + 30 load + 5 U₃, with independent standard Gaussian noises. The graph and absence of hidden confounding are explicit assumptions. A regression alone does not supply those assumptions.
(def graph
{:directed [[:load :queue] [:load :latency] [:queue :latency]]})(defn operating-data [n seed]
(random/with-stream* seed ::operating-data
#(mapv (fn [_]
(let [load (dist/draw (dist/normal 0 1))
queue (+ load (dist/draw (dist/normal 0 1)))
latency (+ 100 (* 20 queue) (* 30 load) (dist/draw (dist/normal 0 5)))]
{:load load :queue queue :latency latency})) (range n))))(def training (operating-data 500 10))(def validation (operating-data 250 20))(def fitted (cm/fit graph training))(into {} (map (fn [[v m]] [v (select-keys m [:intercept :coefficients :sigma])]) (:mechanisms fitted))){:load
{:intercept -0.0030338873671694583,
:coefficients {},
:sigma 1.0272631478955905},
:queue
{:intercept 0.006308998710131372,
:coefficients {:load 0.9635549454599673},
:sigma 1.059056247522682},
:latency
{:intercept 99.49351491669728,
:coefficients {:load 30.178057286617673, :queue 19.81261356918568},
:sigma 4.698079094859116}}
Per-node conditional scores, 90% predictive coverage and residual checks. Dependence tests look for noise related to parents or to other noise. Their p-values use permutations and Holm multiple-testing correction. This finite collection of checks can detect errors; passing does not prove the graph, independence assumptions, or counterfactual coupling.
(def evaluation (cm/evaluate fitted validation {:seed 30 :permutations 399}))(select-keys evaluation [:mechanisms :rejected-checks]){:mechanisms
{:load
{:mean-log-score -1.380747335142234,
:noise-mean 0.043399083170813764,
:noise-variance 0.8679378678169429,
:rmse 0.9580688934002523,
:coverage-90 0.9},
:queue
{:mean-log-score -1.4815438770636205,
:noise-mean -0.02348801667998963,
:noise-variance 1.009902642756759,
:rmse 1.0645777158133862,
:coverage-90 0.896},
:latency
{:mean-log-score -2.990810206337357,
:noise-mean 0.031122684003175298,
:noise-variance 1.048467280900561,
:rmse 4.812805191083185,
:coverage-90 0.884}},
:rejected-checks []}
Set queue delay one unit higher while leaving workload unchanged. The true effect on latency is 20 ms. An unadjusted regression gives about 35 ms: it mixes the queue effect with workload's direct effect.
(defn queue-effect [m]
(let [u (zipmap (:order m) (repeat 0.0))]
(- (:latency (cm/replay m u {:queue 1.0}))
(:latency (cm/replay m u {:queue 0.0})))))(def effect-uncertainty
(cm/bootstrap fitted training queue-effect {:seed 40 :replicates 150})){:truth 20
:adjusted (select-keys effect-uncertainty [:estimate :interval :level])
:unadjusted (queue-effect (cm/fit {:directed [[:queue :latency]]} training))}{:truth 20,
:adjusted
{:estimate 19.81261356918567,
:interval [19.461177264202256 20.109153473548677],
:level 0.95},
:unadjusted 34.4152824794635}
Bootstrap resamples IID rows and refits every mechanism. Its interval measures fitting uncertainty within the chosen graph and mechanism family. It does not account for a wrong graph, unobserved confounding, dependent time-series observations, or an alternative noise coupling.
For this incident we measured every node: load = 1, queue = 3, latency = 200 ms. With fitted parameters fixed, abduction reconstructs one standardized residual per mechanism. Replaying these residuals with queue set to zero predicts roughly 140 ms, while preserving the incident's workload and unexplained latency. There is no new outcome noise draw.
(def incident {:load 1.0 :queue 3.0 :latency 200.0})(def abduction (cm/abduct fitted incident))(defn resolve! [operation]
(let [p (promise)]
(operation #(deliver p [:ok %]) #(deliver p [:error %]))
(let [[status value] (deref p 60000 [:timeout nil])]
(if (= :ok status) value
(throw (ex-info "Causal workflow operation failed" {:status status} value))))))(def context (sp/create-execution-context))(def executable (sp/with-context context (cm/model fitted)))(def worlds
(resolve! (cf/query executable
{:abductions [abduction]
:worlds [[:queue-normal {:queue {:do 0.0}}]
[:load-normal {:load {:do 0.0}}]]})))(:worlds (first worlds)){:factual {:load 1.0, :queue 3.0, :latency 200.0},
:queue-normal
{:load 0.9999999999999999, :queue 0.0, :latency 140.56215929244297},
:load-normal
{:load 0.0, :queue 2.0364450545400326, :latency 150.7314009263062}}
(def repairs
(resolve! (attribution/repairs executable [abduction]
{:leave-as-is {}
:queue-normal {:queue {:do 0.0}}
:load-normal {:load {:do 0.0}}}
#(< (:latency %) 145.0))))repairs[{:candidate :queue-normal, :success-probability 1.0}
{:candidate :leave-as-is, :success-probability 0.0}
{:candidate :load-normal, :success-probability 0.0}]
Here success probabilities are 0 or 1 because every value is observed and the fitted continuous mechanisms are invertible. Missing observations or a posterior over parameters require multiple weighted abductions. The bootstrap above is a different source of uncertainty.
Compared to a finite bank of normal operating observations, which exogenous disturbances explain the increase? Shapley allocation shares interactions rather than declaring a single winning 'root cause'. The baseline population and latency score are part of the question.
(def baseline-rows (subvec training 0 16))(def baseline-noise (mapv #(-> (cm/abduct fitted %) :noise) baseline-rows))(def attribution-report
(resolve! (attribution/attribute-noise executable abduction baseline-noise
{:nodes (:order fitted) :score :latency})))(select-keys attribution-report [:baseline :total :contributions :baseline-count]){:baseline 86.27171182716155,
:total 200.0,
:contributions
{:load 53.578126674455355,
:queue 46.213647503656766,
:latency 13.93651399472632},
:baseline-count 16}
The synchronous structural evaluator can also supply the same coalition game to Shapley. This lets the ordinary row bootstrap refit and recompute a contribution. Keep the incident and reference observations fixed; reconstruct their noise under each refitted model.
(defn queue-contribution [m]
(let [incident-noise (:noise (cm/abduct m incident))
baselines (mapv #(:noise (cm/abduct m %)) baseline-rows)
value (fn [coalition]
(/ (reduce + (map (fn [baseline]
(:latency (cm/replay m (merge baseline (select-keys incident-noise coalition)))))
baselines))
(count baselines)))]
(get-in (attribution/shapley (:order m) value) [:contributions :queue])))(def attribution-uncertainty
(cm/bootstrap fitted training queue-contribution {:seed 50 :replicates 100}))(select-keys attribution-uncertainty [:estimate :interval :level]){:estimate 46.213647503656766,
:interval [43.806368288848766 48.20395102104284],
:level 0.95}
These intervals condition on the particular reference bank, graph, mechanism family and coupling. Noise attribution is not a probability that a node is a cause, and the largest allocation need not name the easiest intervention. Repairs act on endogenous values; the allocations above concern exogenous disturbances.
Replace the queue mechanism by queue = 3 load² + small noise, then fit a linear mechanism anyway. Linear correlation of residual with load can be almost zero, while residual dependence on load² is strong. Held-out checks include squared features specifically to expose this failure.
(defn nonlinear-data [seed]
(random/with-stream* seed ::nonlinear-data
#(mapv (fn [_]
(let [load (dist/draw (dist/normal 0 1))]
{:load load :queue (+ (* 3 load load) (dist/draw (dist/normal 0 0.2)))})) (range 180))))(def misspecified (cm/fit {:directed [[:load :queue]]} (nonlinear-data 60)))(def failure-report (cm/evaluate misspecified (nonlinear-data 70) {:seed 80 :permutations 399}))(:rejected-checks failure-report)[{:kind :noise-parent,
:nodes [:queue :load],
:statistic 0.9982499557768827,
:p-value 0.0025,
:adjusted-p-value 0.005,
:rejected? true}
{:kind :noise-noise,
:nodes [:load :queue],
:statistic 0.9982499557768828,
:p-value 0.0025,
:adjusted-p-value 0.005,
:rejected? true}]
A reversed linear Gaussian graph may pass the same observational checks while giving a different intervention answer. Neither fit quality nor bootstrap precision resolves that ambiguity. Graphical identification (causal/identify) and explicit domain knowledge remain separate steps.
See the causal guide for custom fitting hooks, model contracts, and the boundaries of this workflow.