causal reasoning · Causal reasoning

Summary / 9. Causal reasoning / Document

2026-10-03

Shared copy: the operator's name and machine names are replaced by roles. Nothing else is changed.

Rendering…

# Piper Cognitive Component 9 — Causal Reasoning Engineering Package **Consolidated revision · 3 October 2026 · prepared for the operator Binkley and Piper** **Component:** Understanding why something happens. **Status:** Research synthesis and implementation specification. The supplied files were reviewed and the references below checked against primary sources. Piper's deployed code and database were not inspected. No causal benchmark bundle was supplied, no Piper benchmark was run, and no upgrade was implemented. The small worked example in Section 7 was independently checked by enumeration while preparing this document; that check is not a validation of Piper or a complete scorer. ## 1. Engineering decision and evidence boundaries Start with matched instrument controls and a small formal-world baseline. Diagnose acquisition, extraction, lookup, scoring, routing, and reasoning separately. Then test the cheapest change addressing the largest measured defect. The supplied reviewer assessment reports: | Observation | Supported reading | Still unknown | | --- | --- | --- | | 0/40 withheld edges recovered | That procedure recorded no recoveries | Whether evidence remained available, lookup worked, or scoring was valid | | 2/5 and later 5/5 on different small samples | Those checks used different cohorts | Performance on the original forty; whether sample composition explains the difference | | `causal()` reportedly failed with an intact edge | A concrete failure report to reproduce | Its current implementation, call arguments, database, and scoring path | | Zero causal-tool calls | No calls within reported instrumentation coverage | Whether it was offered/reachable, telemetry was complete, or alternative paths worked | | Worker debugging uses prose | A plausible existing causal-reasoning path | Whether it outperforms graph-assisted reasoning on matched tasks | The component names supplied are `causal-graph v1.1` / `causal_edges`, `counterfactual v1.0`, `memory_graph_score.py`, and `piper/cognition-parameter-map`. Verify real signatures, schemas, locations, model versions, and deployment commits before writing adapters. No single diagnosis follows from these counts. A small graph, inconsistent endpoints, inaccessible tools, inadequate evidence, correct abstention, a defective scorer, and useful reasoning outside the graph can coexist. Different five-case results do not by themselves prove an instrument defect. ### Claims in the drafts that require reproduction The existing package claims a reference bundle with `scm.py`, `check.py`, `scorer.py`, `controls.py`, and `validate.py`; successful test counts; control-matrix outcomes; shortcut percentages; and execution timings. Those code files and run artifacts are absent from the supplied attachments. These are unverified reported results, not delivered implementation or established measurements. It also attributes outgoing-edge deletion in `counterfactual.py` to an earlier review. That review and code are absent. Preserve this as an inspection hypothesis: **which equation or edges does the current intervention operation modify?** Do not label the deployed implementation broken before reproducing the behavior. The updated build sequence has no dependencies on that missing bundle, invented private directory, assumed host, or unapproved fixed token budget. ## 2. Operational definition and scope **Causal reasoning is making justified claims about mechanisms, interventions, and alternate outcomes under explicit causal assumptions, identifying what the evidence can establish, and revising those claims when observations or experiments challenge them.** | Query | Target | Necessary distinction | | --- | --- | --- | | Observation | P(Y given X=x) | Seeing X is evidence; it does not necessarily alter the system | | Intervention | P(Y given do(X=x)) | Replace X's generating mechanism with the specified action | | Counterfactual | P(Y under X=x-prime given factual evidence e) | Modify the mechanism while retaining the factual episode's inferred exogenous circumstances | A fully specified structural causal model is sufficient to compute these quantities when the factual evidence has positive probability and inference is tractable. It is not necessary for every causal answer: some effects or counterfactual quantities are identifiable from distributions plus additional assumptions, and others are only bounded. An arrow extracted from text is an attributed causal claim. A service dependency is a structural relation. Neither automatically establishes an intervention effect, its size, its sign, or whether it explains a particular incident. A directed path can coexist with a zero population-average effect through cancellation or interaction. Distinguish the injected fault, observed symptom, explanatory mechanism, contributing cause, and best repair. They may refer to different nodes. Successful remediation does not automatically validate the diagnosis; redundant causes can defeat a simple but-for definition of root cause. Component 8 supplies grounding, uncertainty, provenance, belief updating, evidence acquisition, and abstention. Reuse those interfaces. Component 9 adds causal query typing, identification, manipulation semantics, same-episode counterfactuals, and experiment/repair policies. A `query_type` field and causal-model references can extend existing records without duplicating the ledger. Observable sub-capabilities are hypothesis formation, confounder/collider/selection recognition, mechanism representation, identification, effect calculation, experimental discrimination, intervention selection, counterfactual consistency, and causal-model revision. ## 3. Research synthesis Primary source identities and the methods summarized here were checked. Proposed Piper adaptations are engineering hypotheses. Published model results are historical and do not predict the current delegate's performance. | Source | Verified contribution | Adaptation and limitation | Scoring | | --- | --- | --- | --- | | **Pearl, 1995** [R1] | Causal diagrams and identification of effects under stated assumptions | Add an identification contract. The diagram is an assumption to justify, not something prose extraction validates | Exact relative to the stated model/class | | **CLadder, 2023** [R2] | Formal queries generated from causal models and rendered in language | Use the symbolic-to-language pipeline; add tool access, ambiguity, and cost. It does not validate Piper's routing | Oracle labels | | **Corr2Cause, 2024** [R3] | Causal claims from correlational/independence information; tests generalization under wording changes | Use claim entailment over compatible graphs. Disclose causal sufficiency, faithfulness, and other assumptions | Enumerated classes or formal entailment | | **Hauser and Bühlmann, 2012** [R4] | Interventional Markov equivalence and GIES | Distinguish structural information gained from interventions from ordinary observation. More intervention information need not uniquely identify every graph | Essential-graph/equivalence criteria | | **NOTEARS, 2018** [R5] | Continuous DAG structure optimization with a smooth acyclicity constraint | Optional discovery baseline in its appropriate model setting. Optimization success alone is not causal identification | Structure metrics after fixed threshold/seed policy | | **Beware of the Simulated DAG!, 2021** [R6] | Simulation shortcuts involving marginal variance and covariance | Audit numeric and textual shortcuts. Standardization alone is not a complete remedy | Shortcut-baseline performance | | **CounterBench, 2025; revised 2026** [R7] | Formal-rule counterfactual tasks with varied structures and names; CoIn reasoning method | External counterfactual check; pin dataset version. Rule-based examples are not automatically quantitative SCMs | Supplied answer keys | | **Abduct, Act, Predict, 2025** [R8] | A2P scaffolding for failure attribution in multi-agent conversations | Test a debugging protocol. The reported implementation uses a single inference pass, not three required model calls. LLM-simulated trajectories are not experimental ground truth | Attribution labels; simulator needed for actual outcome claims | | **Microservice RCA comparison, 2024** [R9] | Compares causal discovery/RCA approaches and finds no universal winner | Include non-LLM baselines and retain real-data/replay checks alongside synthetic worlds | Labeled diagnosis/ranking metrics | | **RCAEval, 2025** [R10] | Telemetry-based RCA dataset and reproducible evaluation framework | Candidate external replay-data source. Telemetry datasets do not by themselves provide executable system snapshots | Fault-label ranking | | **OpenRCA, ICLR 2025** [R11] | Locating software failures' root causes from logs, metrics, and traces | Template for tool-mediated diagnosis. Check label recoverability and distinguish localization from effect/repair validation | Dataset root-cause labels | | **PyMC do-operator example** [R12] | Implementation example of interventional what-if analysis | Useful calculation reference; inspect semantics for the actual model | Compare calculations with a toy oracle | | **PyMC Labs pathmc counterfactual documentation** [R13] | Explicit factual abduction and prediction in a modified model | Clarifies why `observe` followed by `do` is not a universal individual-counterfactual implementation. Its documented supported model class is limited | Model-specific calculation checks | The drafts' unnamed 2026 task-routing paper and additional unverified benchmark/performance claims are not implementation dependencies. Add them only after identifying a primary source, exact method, executable artifacts, and applicable assumptions. Do not claim that this is the first benchmark combining these abilities. ## 4. Audit the production interfaces without changing them Record actual deployment commit, model/configuration, relevant code paths, data versions, and original forty-case artifacts. Inspect code and query behavior rather than accepting self-description as runtime evidence. | Boundary | Questions to answer | | --- | --- | | Acquisition | What source evidence exists for each target relation? Was it available at the original query time? | | Extraction | Does the source assert a cause, condition, correlation, prevention relation, or chronology? What did the extractor emit? | | Storage | Are endpoint IDs, relation type, conditions, scope, provenance, and versions retained? | | Query | Does `causal()` retrieve edges, traverse paths, generate explanations, or discover structure? Which operations are actually supported? | | Counterfactual | Which equation is replaced? How are incoming/outgoing relationships handled? Is factual noise inferred and shared? | | Routing | Was the tool offered/reachable? What causes a call? Could other workers access the same causal information? | | Harness/scorer | What is parsed, what constitutes a hit, and what happens to invalid outputs and exceptions? | Sample edges for a source-fidelity census, using a declared random selection rule. Label relation kind, direction relative to source, sign/conditions, source identity, observed/valid time, scope, and mechanism status. If two raters are used, report agreement and adjudication; a high agreement score does not establish scientific truth. Do not infer graph coverage from a corpus count. Define eligible source relations first, then measure extraction recall. A row faithfully copying an unsupported causal claim is extraction success but remains an unvalidated mechanism. ### Reconstruct the held-out task Determine whether the original run removed rows, raw source text, episodes, summaries, embedding records, or entire mechanisms. Decide what the task was intended to test: - **Re-extraction:** source evidence remains available by design. - **Knowledge acquisition/retrieval:** relevant evidence must be obtained through permitted tools. - **Discovery:** legitimate data remain, but target causal assertions are withheld. - **Memory retention:** previously learned information is queried after storage changes. An allowed summary is not automatically leakage. A forbidden target answer appearing in an accessible summary is leakage. Define the permitted evidence boundary first. If no identifying evidence remains, failure to recover an exact edge may be correct behavior. ## 5. Matched instrument controls Recover the original forty cases if possible. If unavailable, say so and generate a fresh preregistered cohort; it is a replacement diagnostic set, not a reproduction of the missing experiment. Freeze query wording, adapter, parser, scorer, budgets, and expected operation. Change only the graph fixture for each control. If fixes change code, compare the pre-fix and post-fix versions explicitly. | Control | Fixture | Expected result for the declared graph-only operation | | --- | --- | --- | | C0 Original | Original held-out procedure | Empirical result; no assumed answer | | C1 Target present | Exact required edge(s) inserted | Retrieve the supplied edge(s) when direct retrieval is the requested operation | | C2 Minimal oracle | Only the edges needed for this query | Correct retrieval or declared path; distinguish direct edge from indirect path | | C3 Full oracle | Complete relevant relation graph | Same task result, with noise/distractors handled | | C4 Empty/unrelated | No requested edge/path | No supported graph retrieval; defined empty/error result | | C5 Corrupted | Wrong direction, type, endpoint, or condition | Detect the corruption when it changes the requested relation | For deterministic supported operations, every test should match its exact expected output. An unexplained miss is a defect or unresolved contract issue. Passing forty finite controls is not proof of universal tool reliability. Important qualifications: - Inserting one direct edge is not a sufficient positive control for a multi-hop query unless the query contract permits that representation. Match the fixture to the requested operation. - An empty graph does not force an end-to-end LLM answer to be wrong: the agent may have valid text evidence. Zero graph support and zero agent knowledge are different controls. - A reversed edge may leave a separate valid forward path. A corruption must remove or alter the target support if it is meant to create a negative case. - Multiplying signs along arbitrary nonlinear causal paths is not generally sound. For signed linear fixtures, flipping one of two edges avoids accidental sign cancellation, but retain explicit effect semantics. - Aliases require an agreed entity mapping. Distinct nodes must not be merged simply because their words are similar. Capture four stages independently: direct database read, raw tool response, parsed response, and scoring verdict. Add final agent output as a fifth stage in the end-to-end lane. Locate the first observed mismatch instead of inferring it from the final score. Cover direct/path queries, inverse wording, aliases, conditions, preventive claims, missing nodes, invalid inputs, unsupported operations, time/scope changes, and unrelated relation types. Unsupported functionality should be explicit, not silently interpreted as missing knowledge. Run a separate scorer contract test by feeding known-correct, wrong, reversed, incomplete, empty, and malformed responses directly to the scorer. Two scorers agreeing is useful but not sufficient: compare with hand calculations and independently represented semantics as well. ## 6. Benchmark architecture and identifiability Maintain four tracks: | Track | What is supplied | What is tested | | --- | --- | --- | | Representation/query | Declared correct relation/model fixtures | Storage, normalization, lookup, traversal, serialization | | Formal causal reasoning | Public model information sufficient for the requested quantity | Query interpretation, calculation, uncertainty, counterfactual semantics | | Discovery/acquisition | Observational/experimental data and explicit assumptions | Identifiable structure/effects and useful information acquisition | | Incident diagnosis/repair | Simulator or telemetry, permitted actions, costs | Hypotheses, testing, localization, effective repair, side effects | ### Oracle and generator For v0 use acyclic finite SCMs with binary endogenous variables and finite exogenous states. Each variable is a deterministic function of its parents and relevant noise; probabilities live on the joint exogenous distribution. Independent exogenous variables are an assumption, not a universal requirement; model common causes explicitly when needed. Cap the product of exogenous state counts and the execution time. Binary endogenous variables do not guarantee cheap counterfactual enumeration: a node with k binary parents has 2 raised to (2 raised to k) possible Boolean response functions. Use a small, controlled mechanism family rather than unrestricted response tables. Support chains, forks, colliders, mediation, interactions, redundant causes, latent common causes, delayed sensors, and mechanism changes. Model feedback by time-unrolling in v0; do not apply acyclic semantics to an unexplained cyclic graph. Expose structural equations/noise parameters for exact formal queries, or make the needed facts obtainable through permitted tools. For naturalistic unknown-model cases, do not demand equality to a private distribution that the evidence cannot identify. ### Identifiability is query- and assumption-specific Define the admissible model class M(E,A) compatible with delivered evidence E and public assumptions A. A causal quantity is identified when all compatible models agree on it. A compatible-DAG equivalence class is not a universal substitute for this query-level definition. - Under the appropriate causal sufficiency/faithfulness assumptions, observational structural tests can use CPDAG/MEC scoring. - With latent confounding or selection, use a suitable representation such as a PAG or explicit compatible-model class. - Finite samples introduce estimation uncertainty; an estimated zero association is not an exact conditional-independence oracle. - The true sampled DAG is appropriate only when the task's assumptions identify it, or as a separately labeled descriptive recovery metric. - A non-identifiability witness must satisfy **all** public graph, distribution, intervention, and structural assumptions while producing a different requested quantity. Two differing witnesses prove non-identifiability; matching two models does not prove identification. A restricted finite generator can prove identification by enumerating all models in its declared class. If using a general identification algorithm, verify its applicability to the query and graph type. ### Counterfactual oracle For a hard intervention do(X=x), replace X's structural equation by the constant x. In the corresponding causal graph, this removes incoming links to X while retaining outgoing dependencies so consequences propagate. Deleting outgoing links represents a different operation. This is the reference semantics to test, not a finding about Piper's current implementation. For fixed model parameters, compute P(U given factual evidence e), replace the intervened structural equation, and propagate each compatible U through the modified model. Weight results by the factual posterior. Parameter uncertainty, when included, belongs in that posterior as well. Do not condition on the evaluator's private sampled U unless it is public evidence. Do not redraw episode noise as though the factual evidence had never happened. Check positive-probability factual evidence and define behavior for impossible observations. A2P is a reasoning decomposition, not a mandate for three model calls. Numerical correctness comes from the formal model/simulator, not from an LLM's imagined alternate trajectory. ## 7. Worked exact example and data contracts The following toy model has independent noise variables: - Uz follows Bernoulli(0.5), Ux follows Bernoulli(0.25), Uy follows Bernoulli(0.1). - Z = Uz. - X = Z XOR Ux. - Y = X XOR Z XOR Uy. The graph contains Z→X, Z→Y, and X→Y. XOR means exclusive-or. Given this model: | Question | Exact answer | | --- | --- | | P(Y=1 given X=1) | 0.30 | | P(Y=1 given do(X=1)) | 0.50 | | P(Y under X=1 equals 1 given factual X=0,Y=0) | 1.00 | The factual evidence has probability 0.35. Given X=1, Z=1 has posterior probability 0.75, producing 0.25×0.9 + 0.75×0.1 = 0.30. Setting X=1 retains the population distribution of Z, producing 0.50. In the factual X=0,Y=0 episode, Z XOR Uy must equal zero; changing only X to one therefore makes Y one for every compatible noise assignment. Eight-state enumeration reproduced these answers during document preparation. This small arithmetic check does not establish validity of the future generator, independent production code, or Piper's tools. ### Public case example ```json { "case_id": "c9-toy-001", "bench_version": "c9.2.0", "track": "formal_reasoning", "family_tags": ["confounding", "intervention", "counterfactual"], "model": { "endogenous": ["Z", "X", "Y"], "exogenous": ["Uz", "Ux", "Uy"], "independent_exogenous": true, "bernoulli_p1": {"Uz": 0.5, "Ux": 0.25, "Uy": 0.1}, "equations": { "Z": {"op": "identity", "args": ["Uz"]}, "X": {"op": "xor", "args": ["Z", "Ux"]}, "Y": {"op": "xor", "args": ["X", "Z", "Uy"]} } }, "queries": [ {"id": "Q1", "type": "observation", "target": {"Y": 1}, "condition": {"X": 1}}, {"id": "Q2", "type": "intervention", "target": {"Y": 1}, "do": {"X": 1}}, {"id": "Q3", "type": "counterfactual", "target": {"Y": 1}, "do": {"X": 1}, "factual_evidence": {"X": 0, "Y": 0}} ], "allowed_tools": ["calculator"], "budget": {"max_tool_calls": 2}, "answer_contract": "one status and numeric probability per query" } ``` ### Private oracle example ```json { "case_id": "c9-toy-001", "private_seed": 104, "generator_version": "finite-scm-v0", "factual_episode": {"Uz": 0, "Ux": 0, "Uy": 0}, "reference": { "Q1": {"status": "answer", "probability": 0.3}, "Q2": {"status": "answer", "probability": 0.5}, "Q3": {"status": "answer", "probability": 1.0} }, "factual_evidence_probability": 0.35, "counterfactual_conditioning": "all U compatible with factual evidence, weighted by posterior", "numeric_tolerance": 0.000001, "scorer_version": "c9-score-v0" } ``` ### Agent response example ```json { "case_id": "c9-toy-001", "answers": [ {"query_id": "Q1", "status": "answer", "event_probability": 0.3, "answer_confidence": 0.9}, {"query_id": "Q2", "status": "answer", "event_probability": 0.5, "answer_confidence": 0.9}, {"query_id": "Q3", "status": "answer", "event_probability": 1.0, "answer_confidence": 0.9} ], "claims": [], "evidence_used": ["public:model"], "requested_experiment": null } ``` These are example records, not formal JSON Schemas or model outputs observed in a run. Implement strict validators and type-specific contracts. Required response statuses distinguish `answer`, `not_identifiable`, `need_evidence`, `cannot_compute`, `model_conflict`, and an actual information/action request. A timeout or malformed output is a protocol failure, not abstention. Use bounds/identified sets when the query requests them. `event_probability` is the estimated causal event probability. `answer_confidence` is the agent's claimed probability that its answer meets the scoring contract; it is not the same quantity. Both require separate evaluation. Also define tool-event records with delivered observations, query/action IDs, timestamps, source versions, return/error status, hashes, and actual cost. The run manifest records model/provider version, system/harness/scorer commits, seed identity kept private where needed, sampling settings, snapshot hashes, limits, pricing date, and all failures/exclusions. Runner metadata is not supplied by the agent. ## 8. Task families and deterministic scoring | Family | Controlled construction | Endpoint | | --- | --- | --- | | Association versus causation | Common-cause, direct-effect, reverse-direction, and ambiguous matched models | Causal claim entailment and query typing | | Confounding | Measured/unmeasured common causes; declared adjustment assumptions | Identified effect, bounds, or correct non-identifiability | | Collider/selection | Conditional sampling and collider structures | Correct conditioned association and adjustment choices | | Mechanisms/mediation | Direct/indirect paths, interaction, cancellation | Requested total/direct quantity under its specific assumptions | | Multi-hop representation | Direct and indirect relation fixtures | Exact lookup/path contract; do not call every path a nonzero effect | | Interventions | Replace a mechanism and propagate | Event-probability/effect error | | Counterfactuals | Same factual evidence with alternate action | Abduced episode answer; consistency checks | | Incident root cause | Injected faults, alternative explanations, telemetry | Localization, justified hypotheses, and explanation scored separately | | Multiple causes | Interaction and redundant faults | Correct contributing/necessary/sufficient claims under declared definitions | | Negative evidence | Missing logs, unreliable sensors, delivery delay | Appropriate update; absence is not an observed negative without coverage | | Active experiments | Response models, permitted interventions, explicit costs | EIG or decision regret, according to task | | Revision | Staged observations/interventions/mechanism changes | Correct revision and dependency preservation | | Provenance | Claimed, inferred, tested relations and copied sources | Source fidelity, lineage, and independence handling | | Insufficient evidence | Compatible-model witnesses and missing accessible facts | Non-ID versus evidence acquisition versus computation limits | | Tool-mediated episodes | Logs/SQLite/graph/calculator/simulator fixtures | Actual acquisition, final answer, repair effect, and cost | ### Score dimensions separately 1. **Representation/query:** precision/recall, relation direction/type/condition, path validity, scope, and errors. Each fixture has an exact expected contract. 2. **Identification:** a confusion matrix distinguishing identified, non-identified, inconsistent-model, missing-evidence, and unsupported-computation responses. Correct non-identifiability is a substantive answer, not an arbitrary half-credit refusal. 3. **Numerical fidelity:** absolute/squared probability error and effect MAE in meaningful units. Avoid relative error divided by a true effect that can be zero. For distributions, compare to the oracle distribution with KL or another declared proper expected-score difference. 4. **Outcomes:** fault localization and realized repair success, coverage, side effects, and time to useful action. 5. **Justification:** valid structured premises/calculations and consistency with all delivered evidence. Expressed explanations are auditable behavior, not access to private model reasoning. 6. **Uncertainty:** proper outcome scores and calibration of answer confidence, with denominators, uncertainty, and appropriate sampling cohorts. 7. **Revision:** stale retrieval, missed dependent updates, false invalidation, and preservation of alternative independent support. A numerical causal probability of 0.5 is not an incorrect answer merely because the realized event is zero. For Bernoulli reference probability p and prediction q, squared probability error is (q-p) squared; realized Brier is (q-y) squared. Their expected difference from the oracle Brier is the squared probability error. Do not conflate these with calibration of confidence that a computed answer is correct. For a diagnosis, distinguish sampled truth from what the evidence supports. A likely hypothesis can be justified without certainty; several viable causes do not make every tentative answer unjustified. Preserve a posterior or compatible set and the task's decision policy. A lucky correct label does not earn proof of mechanism. A directed path's existence does not prove its average intervention effect is nonzero. Natural direct/indirect effects also require estimand-specific assumptions; do not derive them by generic path multiplication in nonlinear or confounded worlds. ### Acquisition and repair regret Given current evidence e, hypothesis distribution p, loss L, and allowed terminal actions a: $$R(p)=\min_a\sum_h p_hL(a,h).$$ For a one-query experiment Q with outcome z and cost in the same units as L: $$NetVOI(Q)=R(p)-\sum_zP(z\mid e,Q)R(p_{Q=z})-cost(Q).$$ Compare the chosen acquisition/terminal policy with the best permitted option. For information-only tasks use entropy reduction instead. Do not subtract dollars directly from bits. Include no-query and abstention options when appropriate, and accept tied optima. Experiments may alter the system. Define reset behavior, remaining action horizon, intervention constraints, and side-effect cost; an observational query formula is not enough for a state-changing experiment. Start with a resettable one-experiment simulator and explicit oracle policy before longer plans. ### Scorer verification Use hand-derived examples, alternate representations/implementations, exact arithmetic where feasible, empirical simulation checks with known error, and deliberate defect injection. Verify empty/zero-probability evidence, ties, zero effects, invalid distributions, malformed outputs, wrong source versions, and newly delivered evidence. A Monte Carlo comparison has simulation error and is not an exact proof. Two implementations can share a mistaken specification. Resolve every disagreement; do not advertise a fixed acceptable disagreement rate as validation. Keep raw outputs, protocol failures, and scorer errors visible in totals. ## 9. Runtime diagnosis and telemetry | Hypothesis | Discriminating observation | | --- | --- | | Acquisition deficit | Identifying source/data absent under the allowed evidence policy | | Extraction/storage defect | Source relation present, emitted/stored relation absent or changed | | Lookup defect | Correct fixture present, declared supported query returns an incorrect result | | Parser/scorer defect | Raw known-correct result becomes a miss at a later stage | | Tool exposure/routing defect | Tool absent/unreachable, or eligible opportunities consistently bypass it | | Optional tool unnecessary | Bare/text-equivalent arm matches useful outcomes more cheaply within a powered margin | | Incorrect intervention semantics | Current operation disagrees with a public SCM oracle on controlled manipulation tasks | | Counterfactual resampling | Executed computation uses fresh noise rather than factual posterior; a wrong answer alone only suggests this | | Premature debugging commitment | Matched ambiguous incidents show unsupported repair choice before useful evidence acquisition | | Mixed edge semantics | Census shows extracted claims, dependencies, and chronology using one undifferentiated causal type | Log opportunity IDs, episode/stage, actual graph calls/results, alternatives recorded, experiment selected/executed, evidence delivered, predictions, relation writes, revisions, costs, and independently resolved outcomes. Mark failure and unsupported-operation status explicitly. Bench opportunity denominators come from the generator. Live denominators come from an independent sampled audit, including detector-negative turns; a regex/classifier is only an estimate. Measure missed opportunities and precision, not only agreement on flagged turns. Useful rates include query correctness by operation, supported conclusion/repair rate per eligible task, chosen experiment regret on controlled worlds, resolution coverage, source-lineage preservation, and downstream stale-claim retrieval. Tool invocation is descriptive; there is no universal healthy call-rate target. A correctly predicted outcome or successful repair supports a causal hypothesis to a degree determined by alternatives and design. It does not automatically verify the whole causal chain. Separate prediction success, remediation success, and mechanism confirmation. Use a protected append-only logger or separately controlled writer for contemporaneous evidence/predictions; local SQLite triggers alone do not prevent an agent with file/code authority from rewriting history. Preserve immutable source versions or snapshots, not just IDs pointing to mutable evidence. Test isolation requires separate state and access boundaries. Equal pre/post row counts do not prove unchanged state: content can change with the count unchanged. Use snapshot hashes/diffs and retrieval checks where relevant. ## 10. Experimental controls and ablations Hold model version, sampling settings, tools, budgets, initial evidence, initial state, and response contracts fixed. Avoid extra production memory in Piper's arm unless an equivalent evidence source is accessible to the bare control. Label total-system versus mechanism-only comparisons separately. | Arm or comparison | What it isolates | | --- | --- | | Bare model / bare + equivalent instruction | Prompt effect | | Current Piper / matched bare with neutral evidence access | Existing agent integration beyond the matched instruction/information | | Current Piper / graph mechanism disabled but facts accessible | Graph mechanism contribution | | Current Piper / counterfactual module disabled | Existing counterfactual mechanism contribution | | Production graph / identical production facts as text | Representation/interface effect with the same content | | Oracle graph / identical oracle mechanism as text | Representation ceiling comparison with the same oracle content | | Production graph / oracle graph with same query interface | Additional or corrected content, not format | | Current query / repaired query | Lookup/normalization change | | Repaired query / repaired query plus conditional routing | Routing change | | Current worker / debugging protocol with equivalent information | Worker decision-process change | | Best individually useful interventions combined / leave-one-out | Interaction and marginal contribution | Do not compare an oracle graph with production-text facts and call the difference a graph-format effect. If a graph stores equations/noise parameters, its text-equivalent control must contain them too. If facts are served on demand in one arm but preloaded in another, that comparison includes retrieval/context effects; label it honestly or match the access protocol. Maintain state within an episode, reset independent worlds, and discard test memories. Per-arm posteriors and oracle decisions depend on evidence actually delivered; different queries need not yield identical transcripts. Cluster paired uncertainty by independently generated worlds. Multiple questions, stages, skins, and samples of one world do not increase the independent world count. Estimate variance/discordance in a pilot, then plan sample size for the primary effect and noninferiority guards. Forty interface controls diagnose their contracts; they are not a power calculation for cognitive gain. An inconclusive difference remains inconclusive. Equivalence requires an interval within a preregistered margin, not a nonsignificant test. Cheap prompt changes can be valuable shipped improvements even when no architectural benefit is found. ## 11. Interventions ranked by conditional experimental priority The following effect targets are proposed starting defaults, not expected effects from the literature. Register final endpoints and margins after a pilot and before candidate selection. Branch according to diagnosis instead of building every row. | Intervention | Hypothesis and control | Primary test / proposed gate | Main risk and rollback | | --- | --- | --- | --- | | **P1 Query/scorer repair** | An identified interface defect causes misses; control is frozen current query/scorer | Exact supported-operation controls plus a generated regression set; all declared deterministic contracts match; no new false retrievals | Alias over-merging, permissive scoring, incompatible return schema. Reject any unresolved contract violation | | **P2 Query typing/calculation** | Explicit observation/intervention/counterfactual/identification types reduce substitution; compare prompt-only and optional calculator controls | Numerical/identification primary endpoint on about 200 pilot worlds; size confirmatory set from variance. Starting target: +8 points useful correct answers; false-non-ID guard 3 points; cost ≤25% increase | Calculation overuse and inability mislabeled non-ID. Roll back utility/coverage regression | | **P3 Intervention/counterfactual semantics** | A reproduced semantic defect is fixed by mechanism replacement and factual-noise inference | Hand and randomized exact worlds; agreement within numerical precision for supported queries; then task accuracy/runtime guards | Correct surgery on a wrong or incomplete model. Reject false claims of supported computation | | **P4 Worker diagnostic protocol** | Recording live alternatives and a useful test where ambiguity remains reduces repair loss; compare current prompt and equivalent bare protocol | About 200 incident worlds as pilot; confirmatory N from paired variance. Starting target: ≥15% expected-loss reduction; useful-coverage guard 3 points; cost ≤25% increase | Ritual strawman hypotheses, delay on obvious repairs. Skip extra steps when evidence already resolves the task | | **P5 Typed provenance and revision** | Correct types/scope/lineage prevent relation confusion and stale conclusions | About 300 independent source/dependency chains; source fidelity and required-update recall, with false-invalidation/retrieval guards | Migration loss or unsupported certainty upgrades. Validate content, provenance, and versions, not row count alone | | **P6 Conditional routing** | Reliable graph access improves selected graph-answerable cases; compare repaired interface without gate, equivalent prompt, and always-on routing | Useful task/decision outcome, missed eligible tasks, cost; no invocation quota. Starting target: ≥10% relative primary-quality gain where meaningful | Mandatory calls waste time or replace better prose reasoning. Roll back outcome/cost regression | | **P7 Decision-value experiments** | Cost-aware queries improve decisions over existing discriminator and entropy-only policy | About 300 controlled worlds; expected-loss regret. Starting target: ≥20% regret reduction at ≤25% added cost | Wrong simulated response model and state-change assumptions. Reject imagined gains absent simulator outcome benefit | | **P8 Extraction/failure memory** | Better evidence-linked relations or episodes help when coverage is the confirmed bottleneck | Source extraction fidelity and downstream decision quality; independent-source/distractor variants | A larger misleading graph or remembered story overrides current evidence. Reject downstream accuracy/provenance regression | Test one intervention at a time before a combined candidate. For interface fixes, a runtime reproduction plus exact controls can justify repair without requiring a statistically significant cognitive-gain claim. For cognitive interventions, require paired evidence of a practically useful gain. A module may correctly answer qualitative ancestry yet lack the implementation for numerical counterfactuals. Return `cannot_compute` or request necessary evidence according to the situation; do not automatically claim scientific non-identifiability because a code path is missing. Dependency invalidation uses a durable queue with bounded processing, recognition of pending-stale records at read time, and retained alternative supports. Resource limits may defer work, not silently drop descendants. Failure memory retains original hypotheses/probabilities and separately appends later outcomes. ## 12. Acceptance, regressions, and cost Register task cohort, primary metric, minimum useful effect, noninferiority margins, analysis, sampling/stopping rule, and resource limits. Use endpoint-specific acceptance; lineage repair does not need to improve every numerical causal task. Ship when the paired improvement meets its practical target with appropriate uncertainty, guards meet noninferiority margins, cheaper controls are evaluated, transfer results are acceptable, and the measured behavior survives isolated replay or bounded rollout. Choose the simpler control if it provides equivalent utility at lower cost. Starting planning limits can include a 3-point useful-coverage margin, 2-point memory retrieval margin, and ≤25% incremental model cost. Latency needs an actual per-incident/service limit as well as relative comparison. Sparse-error baselines need absolute margins or decision loss rather than unstable percentage reductions. Reject unsupported conflict closure, silent state corruption, invalid intervention output, unresolved scorer defects, material coverage/non-target regression, or unacceptable cost. Hard integrity defects warrant immediate disablement; do not wait for weekly trends after a confirmed corruption. Record input/output/cached tokens, actual priced charges with date, retries/timeouts, tool and simulator calls, wall-clock and tail latency, writes, background work, and compute resources. No reference-bundle timings or oracle speed measurements from the prior draft are retained as facts. Run only the ablations necessary for the current question first; a full many-arm matrix is not a prerequisite to fixing a reproduced lookup bug. Report quality and cost deltas directly, then compare the quality–cost frontier. Ratios such as gain per extra dollar are unstable when added cost is near zero and cannot combine unrelated quality endpoints. ## 13. Contamination, transfer, and generator shortcuts Separate inspectable development, operator-controlled validation with recorded selection exposure, a fresh final cohort for the selected candidate, and rotating production-shaped canaries. Repeated validation gradually exposes information even if each candidate is evaluated once. Keep private seeds, oracle mechanisms for discovery tasks, future tool outputs, and scoring state outside the agent's readable/editable tools. Expose the public model when the task requires it; model disclosure in formal reasoning is not contamination. Audit variable order/names, textual cue words, distributions, variance/covariance patterns, topology/difficulty, and answer balance. A sort-by-variance baseline is appropriate for the relevant numeric model families, not every binary task. Standardization is an audit variant, not proof all shortcuts are removed [R6]. Randomized listing order should be assessed against its sampling uncertainty and task conditions, not a universal ≤0.55 rule. Probe whether cheap surface baselines predict the answer beyond appropriate chance; analyze name/order mutations and held-out topology separately. Non-identifiability witnesses must be query-specific. Selecting worlds with large observational/interventional differences can create a useful challenge set but does not establish counterfactual non-identifiability or represent ordinary workloads. Record filtering and report both unfiltered and selected cohorts. Use domain skins for Linux, software, Binx operations, logistics, physical/sensor systems, and fiction. Preserve equations, observations, and permitted information. A nonsense skin is a useful prior-knowledge diagnostic, not a required invariance theorem for natural language. ## 14. Live shadow evaluation and weekly report Snapshot contemporaneous hypotheses, causal claims, predicted effects, evidence versions, confidence, action options, and actual tool choices. Resolve outcomes through independent telemetry, authoritative records, or explicit operator verification. Mark unresolved and disputed outcomes rather than excluding them silently. Shadow mode can score predictions of events that occur anyway. It cannot establish effects of unexecuted repairs. A captured log replay is not automatically an executable causal simulator; use appropriate system snapshots/fault injection for repair experiments and report that simulator's limits. Add a bounded reversible canary only after isolated validation. Audit successes and unresolved/detector-negative cases. Outcome calibration on selectively resolved cases may be biased; report N, resolution coverage, lag, and category mix. A later Piper assertion or new ledger label is not independent confirmation. | Weekly line | Contents | | --- | --- | | Bench | Model/system/scorer versions, targeted paired delta and interval versus current and cheap controls | | Coverage | Audited opportunity sample, trigger precision/recall, graph-eligible versus general causal tasks | | Query reliability | Supported-operation correctness, false retrievals, parsing/timeout/unsupported counts | | Causal claims | Grounded/overstated rates plus useful coverage; separate identified and estimated conclusions | | Experiments | Proposed/executed, predicted/observed effects, controlled regret, side effects | | Diagnosis/repair | Localization, hypothesis support, actual repair success, unresolved/disputed outcomes | | Revision/provenance | Source fidelity, stale descendants, false invalidation, silent mutation | | Cost and resolution | Per-episode tokens/dollars/latency; outcome N and coverage | The report answers three questions with evidence or an explicit inconclusive result: understanding improved; graph/tool contributed; decisions/debugging improved at acceptable cost. ## 15. Failure taxonomy Keep unexplained error separate from a demonstrated mechanism. A number close to the observational answer is a rung-confusion candidate, not proof of the model's hidden computation. Matching alternative answers can occur by coincidence or true equality. | Group | Labels | | --- | --- | | Causal validity | Correlation/chronology treated as causation; reverse-cause shortcut; confounding neglect; collider/selection bias; mediator/estimand misuse | | Mechanisms | Fabricated link; nonzero effect assumed from a path; sign/interaction error; omitted joint/redundant cause; symptom mistaken for injected fault | | Query semantics | Observation/intervention substitution; intervention/counterfactual substitution; factual noise not retained; wrong conditioning set; impossible factual evidence ignored | | Identification | Unique DAG overclaimed; point effect overclaimed; invalid witness; missing data confused with non-ID; unsupported computation confused with non-ID | | Tools/representation | Query/alias/direction/type/condition failure; parser loss; unsupported operation; missed or wasteful routing | | Decisions | Premature commitment; unexecuted discriminator; irrelevant/cost-blind experiment; successful workaround treated as diagnosis proof | | State/evidence | Stale mechanism; duplicate-source counting; provenance laundering; destructive collateral revision; selective outcome reporting | | Infrastructure | Oracle leakage; invalid response; wrong stage evidence; scorer defect; mismatched controls/budgets; generator shortcut | Assign deterministic labels where fixtures/traces justify them, otherwise mark suspected or unexplained. Aggregate failures by track and family to choose the next experiment. ## 16. Staged implementation and handoff | Stage | Work | Reviewable completion gate | | --- | --- | --- | | 0. Establish facts | Inspect deployed interfaces and reconstruct the forty-case evidence policy | Audit names actual paths, versions, source availability, and unsupported claims | | 1. Isolate instrument | Graph-only and scorer-only controls; preserve raw/parsed/results | Each declared supported operation has known expected behavior; every mismatch localized | | 2. Build minimal oracle | Finite SCM, exact query types, identification witnesses, protected contracts | Hand derivations and independent checks agree; no claim of inherited missing-bundle validation | | 3. Pilot comparisons | Bare, current, prompt-only, production/text-equivalent and matched oracle/text controls | Task differences, costs, uncertainty, and dominant errors identified | | 4. Test one justified fix | Conditional query, semantics, worker, lineage, or routing change | Registered primary gain/repair and guards pass; otherwise reject or remain inconclusive | | 5. Expand only as needed | Incident simulator, active experiments, revision, discovery and transfer | Specific new decisions can be measured; isolated contributions remain interpretable | | 6. Final and live | Fresh cohort, replay, shadow, limited reversible rollout | Release/rollback criteria work and relevant production behavior is evidenced | ### Implementation prompt > Improve Component 9 using this package. Begin with the deployed causal graph, query, counterfactual, router, extraction, and scorer interfaces. Record real paths/commits and the original forty-case evidence policy. Treat missing reference code and reported results as unverified; implement or obtain artifacts explicitly instead of assuming `validate.py` already exists. > > Separate graph-only retrieval from end-to-end reasoning. Reproduce intact-edge failures, test the scorer directly, and preserve every stage's raw output. Match positive/negative fixtures to the declared query operation. Do not demand an empty-graph failure from an agent that has permitted causal facts elsewhere. > > Build a small protected finite-SCM oracle for observation, intervention, counterfactual, and witness-backed identification tasks. Check the toy probabilities in Section 7 and additional degenerate, latent, interaction, and impossible-evidence cases. Implement strict public/private/response/tool/manifest contracts. Score each arm using its actually delivered evidence. > > Pilot matched bare, current-Piper, prompt-only, graph/text-equivalent, and oracle/text-equivalent controls. Do not call extra oracle content a format effect. Preregister the first measured intervention's endpoint, effect target, guard margins, power/sample plan, cost/latency limits, and rollback before confirmatory comparison. > > Implement one reversible fix justified by evidence. Deliver audit, source/scorer tests, reproducible commands, schemas, manifests, baseline comparison, intervention diff, results with uncertainty, costs, and keep/reject/inconclusive recommendation. Preserve history and source lineage. Do not claim causal improvement from more arrows, more calls, persuasive prose, or an unvalidated score. ## References Primary pages and applicable method descriptions checked 3 October 2026. Bibliographic links identify sources; the generator, schemas, thresholds, toy model, and proposed experiments above are this document's engineering specification. - **[R1]** Pearl. *Causal diagrams for empirical research*. Biometrika, 1995. [Author-hosted paper](https://ftp.cs.ucla.edu/pub/stat_ser/R218-B-L.pdf). - **[R2]** Jin et al. *CLadder: Assessing Causal Reasoning in Language Models*. NeurIPS 2023. [Publication](https://papers.nips.cc/paper_files/paper/2023/hash/631bb9434d718ea309af82566347d607-Abstract-Conference.html). - **[R3]** Jin et al. *Can Large Language Models Infer Causation from Correlation?* ICLR 2024. [Paper](https://arxiv.org/abs/2306.05836). - **[R4]** Hauser and Bühlmann. *Characterization and Greedy Learning of Interventional Markov Equivalence Classes of Directed Acyclic Graphs*. JMLR, 2012. [Paper](https://jmlr.org/papers/v13/hauser12a.html). - **[R5]** Zheng et al. *DAGs with NO TEARS: Continuous Optimization for Structure Learning*. NeurIPS 2018. [Publication](https://papers.nips.cc/paper/2018/hash/e347c51419ffb23ca3fd5050202f9c3d-Abstract.html). - **[R6]** Reisach, Seiler, and Weichwald. *Beware of the Simulated DAG! Causal Discovery Benchmarks May Be Easy To Game*. NeurIPS 2021. [Paper](https://arxiv.org/abs/2102.13647). - **[R7]** Chen et al. *CounterBench: Evaluating and Improving Counterfactual Reasoning in Large Language Models*. Preprint 2025, revised 2026. [Paper](https://arxiv.org/abs/2502.11008). - **[R8]** West et al. *Abduct, Act, Predict: Scaffolding Causal Inference for Automated Failure Attribution in Multi-Agent Systems*. 2025. [Paper](https://arxiv.org/abs/2509.10401). - **[R9]** Pham, Ha, and Zhang. *Root Cause Analysis for Microservice System based on Causal Inference: How Far Are We?* ASE 2024. [Paper](https://arxiv.org/abs/2408.13729). - **[R10]** Pham et al. *RCAEval: A Benchmark for Root Cause Analysis of Microservice Systems with Telemetry Data*. 2025 version. [Paper](https://arxiv.org/abs/2412.17015). - **[R11]** Xu et al. *OpenRCA: Can Large Language Models Locate the Root Cause of Software Failures?* ICLR 2025. [Publication](https://iclr.cc/virtual/2025/poster/32093). - **[R12]** PyMC example gallery. *Interventional what-if analysis using the PyMC do-operator*. [Official example](https://www.pymc.io/projects/examples/en/latest/causal_inference/interventional_what_if_do_operator.html). - **[R13]** PyMC Labs pathmc documentation. *Counterfactuals: From Population to Individual*. [Official implementation documentation](https://pathmc.pymc-labs.com/docs/examples/effect-estimation/counterfactual.html).