ruvnet--RuView/api-docs/adr/ADR-313-counterfactual-inference.md

ADR-313: Counterfactual inference — generative spatial reasoning

• Status: Accepted — initial implementation (ADR-300 phase 3)
• Date: 2026-08-11
• Deciders: ruv
• Tags: inference, generative, counterfactual, rf-twin, fusion, uncertainty, phase-3

Context

This ADR is a child of ADR-300 (perception substrate program) and owns primitive #13, counterfactual inference. In the ADR-300 DAG it is a phase-3, research-forward primitive that sits on top of the fused world state: it consumes ADR-311 (real sensor fusion) for the current fused estimate and ADR-315 (digital RF twin) for the twin's expected measurement distributions. It is design intent, authored as Proposed, and is expected to be revised as the phase-1 spine and the phase-2 fusion layer land.

RuView today reasons discriminatively: a task head maps measurements to a label or a pose. That answers "what does the classifier say?" but not the questions an operator actually asks — would these RF measurements still make sense if nobody were present? Does one person explain the observation better than two? Those are counterfactual questions, and a classifier cannot answer them because it has no model of what a measurement should look like under a hypothesized world state. A discriminative head asked about an empty room simply emits its best-effort label; it cannot say "the observation is better explained by absence."

The step this ADR proposes is toward a generative spatial model: given a hypothesized scene state (occupancy, count, coarse positions) and the ADR-315 twin's propagation model for the deployment, predict the expected measurement distribution, then score how well each hypothesis explains the observed measurement. The best-explaining hypothesis — including the nobody-present null hypothesis — is the answer, and the margin between hypotheses is a first-class uncertainty signal.

Relevant existing assets to build on rather than duplicate:

• ADR-311 (fusion) already produces the fused world estimate and its covariance; the counterfactual layer scores hypotheses relative to that estimate rather than re-fusing raw measurements.
• ADR-315 (RF twin) is the generative forward model — per-deployment geometry, radio locations, and expected measurement distributions. This ADR is a consumer of the twin's forward simulator, not a second simulator.
• ADR-302 (OOD/observability) already owns the UNKNOWN verdict; the null-hypothesis ("nobody present better explains this than any occupancy hypothesis") and the "no hypothesis explains this" case route through ADR-302, not a parallel gate.
• frame::EvidenceLevel L0–L5 (ADR-282) and the ADR-304 evidence engine account for the resulting confidence.

Options considered

1. Keep only discriminative heads. Rejected: cannot express absence, cannot compare "one person vs. two" as competing explanations, and gives a confident label even when no world state explains the data.
2. A second, independently trained generative network with its own forward model. Rejected for the default path: duplicates the ADR-315 twin's propagation model, invites the two models to disagree, and multiplies the surface that must be validated. Reserved only if the twin's analytic forward model proves insufficient for a phenomenon.
3. A hypothesis-scoring layer that uses the ADR-315 twin as the forward model and the ADR-311 fused state as the hypothesis prior, routing low-margin and null-dominant cases to the ADR-302 UNKNOWN verdict. Chosen.

Decision

Define a counterfactual inference layer that scores a small set of scene hypotheses against observed measurements using the digital RF twin as the generative forward model.

1. Hypothesis set

• Hypotheses are drawn from the ADR-311 fused state and its neighbourhood: the current estimate, the null hypothesis (nobody present), and a bounded set of nearby alternatives (±1 occupant, shifted position). The fused estimate supplies the prior so the search stays small and grounded rather than enumerating an open world.
• The hypothesis space is expressed over the ADR-306 canonical ontology (Space/Zone, occupant count, coarse position), so a counterfactual result is a governed spatial statement, not an opaque score.

2. Forward model and scoring

• For each hypothesis, query the ADR-315 twin for the expected measurement distribution given that scene state and the deployment's propagation model. Score the observed measurement's likelihood under each hypothesis's expected distribution.
• The answer is the maximum-likelihood hypothesis; the margin between the top hypotheses (and between the top hypothesis and the null) is the confidence signal, carried into the ADR-304 evidence engine.

3. Routing to UNKNOWN

• When the null hypothesis dominates, the layer reports absence, not a low-confidence occupancy label.
• When no hypothesis explains the observation well (all likelihoods low, or the winning margin below threshold), the result routes to the ADR-302 UNKNOWN verdict — the observation is outside what the twin can explain, and the honest output is "I cannot account for this," never a forced label.

Evidence discipline

• Twin-predicted distributions are a simulation (evidence level L0 per ADR-282) labelled SYNTHETIC; a counterfactual verdict inherits the evidence level of its weakest input and is never presented as camera-grade ground truth (CLAUDE.md honesty rule).
• Any accuracy statement about counterfactual discrimination (e.g. "distinguishes one occupant from two") requires the mean-pose-style baseline discipline of CLAUDE.md, a leakage-free held-out split, and a reproducer before it may be tagged MEASURED. This ADR asserts no such number.

Consequences

• RuView gains the ability to answer absence and "which explanation is better" questions that discriminative heads structurally cannot — a step toward generative spatial reasoning and a differentiator for security and facility-monitoring applications where absence is the valuable signal.
• Quality is bounded by the fidelity of the ADR-315 twin's forward model and the ADR-311 fused prior; the layer reports margins and defers to ADR-302 UNKNOWN rather than overstating a coarse model.
• Hard dependency on ADR-311 (fused state and covariance) and ADR-315 (forward model); this ADR builds neither a fusion engine nor a propagation simulator of its own.
• Being phase 3, this is design intent sitting on the fused world state; it is expected to be revised as ADR-311 and ADR-315 land, and it is not implemented by the phase-1 swarm.

Validation

• Unit tests: hypothesis likelihood scoring is a deterministic function of observed measurement + hypothesis + twin parameters; the null hypothesis wins on a synthesized empty-room measurement; a two-occupant measurement scores the two-occupant hypothesis above the one-occupant hypothesis on a controlled synthetic case.
• Integration test: measurements the twin cannot explain (out-of-model scattering) drive the layer to the ADR-302 UNKNOWN verdict rather than a forced occupancy label; margins propagate into the ADR-304 evidence engine.
• Held-out discrimination (deferred, real-silicon): one-vs-two and presence-vs-absence discrimination on a leakage-free held-out split with a mean-pose baseline, reported as MEASURED with a reproducer. Until then all counterfactual output is SYNTHETIC/L0. No discrimination accuracy number is asserted by this ADR.