# Divergence Index Calculus -- Stage 2 Computation

**Owner:** frame-divergence-gate (E8). **Scope:** compute Stage 2's continuous `D` over the shared-concept surface and choose between measures. Dimensions in `KUHNIAN_DIMENSIONS.md`. Thresholds in `THETA_Q_CALIBRATION_DEFAULTS.md`. Runtime detectors in `RUNTIME_CONVERGENCE_DETECTORS.md`. Zero overlap.

## What Stage 2 measures

A single scalar `D in [0, 1]` over the concepts the two frames share. `D = 0` is perfect overlap. `D = 1` is maximal divergence.

## Shared-concept surface extraction

Before computing `D`, extract the shared-concept surface: concept tokens present in **both** the Evaluator and RAM lexicons AND **relevant to the active question**.

- Intersect lexicons.
- Filter to tokens referenced in the question artifact OR in frame axioms on any Kuhnian dimension.
- Non-empty surface required. If empty, `stage2_verdict = FAIL` with reason `shared_concept_surface_empty` (Stage 2 cannot measure divergence over nothing; escalate to Frame Host).

## Measure 1 -- Jaccard distance over inference-rule sets

Use when: the two frames have enumerable inference-rule sets over the shared-concept surface.

Let `R_E` be the Evaluator inference-rule set restricted to the shared surface, and `R_R` the RAM set restricted similarly. Compute:

```
D_jaccard = 1 - |R_E intersect R_R| / |R_E union R_R|
```

If both sets are empty after restriction, Jaccard is undefined -> fall through to Measure 2.

## Measure 2 -- KL divergence over prior distributions

Use when the frames have well-defined priors on the answer space. Let `P_E`, `P_R` be those priors. Use Jensen-Shannon distance (symmetric, bounded) instead of raw KL:

```
JSD(P_E, P_R) = 0.5 * KL(P_E || M) + 0.5 * KL(P_R || M)  where M = 0.5 * (P_E + P_R)
D_kl = sqrt(JSD(P_E, P_R) / ln(2))   # bounded to [0, 1]
```

Raw KL is unbounded; the `sqrt(JSD / ln(2))` form is bounded and symmetric, matching Stage 2's required shape.

## Measure choice

1. **Jaccard preferred** when inference-rule sets are enumerable over the shared surface.
2. **KL (as JSD)** when prior distributions are well-defined and inference-rule sets are not enumerable.
3. **Both available:** compute both; record both in the Frame Registry. If `|D_jaccard - D_kl| > 0.2`, use the **more conservative (lower) D** (per Ambiguity Register A5). Record the choice.

## Verdict

```
stage2_verdict = PASS  if D >= theta_q
               = FAIL  otherwise
```

`theta_q` is looked up in `THETA_Q_CALIBRATION_DEFAULTS.md` at Step 2 of the operating logic. It is never adjusted mid-decision.

## Recording rules

In the Frame Registry record, write:

- `stage2_measure_used`: `jaccard_inference_rules | kl_prior_distributions | both`.
- `stage2_divergence_index`: the `D` value used for the verdict (the more conservative if both).
- `stage2_threshold_used`: `theta_q`.
- `stage2_threshold_source`: `calibrated_record_ref | default_conservative`.
- `stage2_verdict`: PASS or FAIL.

## Anti-patterns

- Never substitute a runtime detector for Stage 2. Those are for Step 8, after gate PASS.
- Never compute `D` over full lexicons without the shared-concept-surface restriction.
- Never use raw unbounded KL for the verdict. JSD-normalized form only.
