# Data dictionary

All CSVs are comma-separated, include a header row, and are stored in `results/data/`.

## Common concepts

- `objective`: `head_over_kwh + 4000 * v_violation_total + 0.25 * curtailed_kwh`.
- `violation_hours`: hours with feeder-head cap or voltage-floor violation.
- `plan_faithfulness`: mean Jaccard overlap between declared and issued target sets.
- `plan_groundedness`: share of directives within 105% of true flexible load.
- `plan_minimality`: oracle curtailed kWh divided by realised kWh on successful hours.
- `plan_coherence`: one minus normalised schedule churn across revisions.
- `directive_realization`: realised divided by requested curtailment.
- `latency_s`: accumulated stipulated executor-invocation latency, not measured API latency.
- `deadline_misses`: number of executor invocations whose nominal cost exceeds the event deadline.

## E1.csv

One file combines declaration rows and episode-summary rows.

- `declaration`: `natural` or `hybrid`.
- `seed`: episode seed.
- `mode`: declared mode; blank on summary rows.
- `objective`, `violation_hours`, `curtailed_kwh`: populated on summary rows.

## E2.csv

One row per `(policy, seed)`.

- `policy`: four `forced-*` policies plus `natural` and `hybrid`.
- `mode`: forced mode or `ROUTED`.
- `seed`: paired scenario seed.
- `objective`, `violation_hours`, `curtailed_kwh`, `latency_s`: physical and timing outcomes.
- `plan_faithfulness`, `plan_groundedness`, `plan_coherence`, `plan_minimality`:
  trace and physical plan metrics.
- `directive_realization`, `mean_compliance`, `curtail_gini`: strategic-response metrics.
- `primary_failure`: deterministic primary failure label.
- `regret`: objective minus the best forced objective for the same seed.

## E3.csv

One row per `(state_noise, mode, seed)`.

- `state_noise`: multiplicative forecast-noise standard deviation.
- `forecast_mae_frac`: realised fractional forecast MAE.
- Remaining columns report groundedness, objective, violations, and primary failure.

## E4.csv

One row per `(deadline_s, critic, seed)`.

- `critic`: whether the deterministic deadline gate is active.
- `deadline_misses`: event-level misses after any gate decision.
- `deadline_downgrades`: number of type-valid gate substitutions.
- `executed_mode`: deterministic classifier output for the executor that ran.

## E5.csv

One row per `(honesty, seed)`.

- `honesty`: probability that declared and executed target modes agree at a decision.
- `mode_match`: declared-versus-executed architecture agreement.
- `plan_faithfulness`: targeting-set overlap.
- `targeting_leverage`: mean voltage leverage of issued targets divided by honest targets.
- `v_violation_total`: cumulative voltage shortfall in per-unit voltage.

## E6.csv

One row per issued directive; `(mode, seed, t, node)` is unique.

- `t`, `node`: dispatch hour and prosumer node.
- `requested_kw`, `realized_kw`: requested and realised curtailment.
- `complied`: binary strategic action.
- `archetype`: prosumer behavioural archetype.
- `depth`, `lateral`: electrical position.
- `p_base`: game-theoretic compliance probability before LLM influence.
- `llm_shift`: bounded narrative-induced probability shift.
- `mode`, `seed`: forced planning mode and scenario seed.

## E7_forced_bank.csv

One row per `(scenario_id, mode)`; every scenario has all four modes.

### Scenario factors

- `scenario_id`: unique factor combination.
- `stress_group`: held-out cross-fitting group.
- `cap_tightness`: 1100 divided by scenario head-cap kW.
- `line_resistance`: scenario per-segment resistance.
- `state_noise`: forecast noise.
- `deadline_s`: per-decision operational deadline.
- `resistance_mean`: mean prosumer resistance.
- `horizon`: 24 hours.
- `seed`: 7, 13, or 42.

### Execution and outcome fields

- `mode`, `label`, `declaration`, `declared_mode_first`, `declared_modes`, `executed_mode`,
  `mode_match`: strategy provenance.
- `head_over_kwh`, `v_violation_total`, `v_min`, `curtailed_kwh`, `oracle_kwh`,
  `violation_hours`, `objective`: physical outcomes.
- `revisions`, `candidates`, `tool_failures`, `planning_llm_calls`, `latency_s`:
  execution trace summaries.
- `deadline_misses`, `deadline_downgrades`, `budget_exhausted_steps`: event-level timing.
- `mean_compliance`, `curtail_gini`, `targeting_leverage`, `directive_realization`:
  strategic response.
- `forecast_mae_frac`, `primary_failure`, `plan_*`: observability and plan metrics.

### Cost-sensitive routing fields

- `feasible`: true exactly when `deadline_misses == 0`.
- `feasibility_rule`: `no_event_level_deadline_miss`.
- `selection_cost`: objective plus 10,000 if infeasible.
- `oracle_cost`: minimum selection cost in the same scenario.
- `oracle_regret`: mode selection cost minus scenario oracle cost.

## E7_crossfit_router.csv

One row per held-out scenario.

- `stress_group`: group excluded from training.
- `chosen_mode`: minimum predicted-cost mode.
- `predicted_cost`: selected mode's cross-fitted prediction.
- `actual_cost`, `objective`, `feasible`: realised paired-bank values.
- `regret`: actual selection cost minus scenario oracle cost.

## E7_crossfit_router_enriched.csv

Adds fixed-strategy comparators to the routed table.

- `global_fixed_cost`, `global_fixed_mode`: best mode in the full bank.
- `fold_fixed_cost`, `fold_fixed_mode`: best mode using only each fold's training groups.
- `value_vs_global_fixed`, `value_vs_fold_fixed`: fixed cost minus router cost; positive
  values favour the router.

## E7_calibration.csv

Five quantile bins of selected predicted cost with bin size, realised cost, regret, and
feasibility.

## E7_bootstrap.csv

5,000 scenario-level paired bootstrap draws containing mean and median regret, router
feasibility, and value against global/fold fixed comparators.

## E7_summary.csv

Machine-readable headline values reported in the README and technical summaries.

## E7_mode_selection.csv

Within each held-out stress group, the share of router selections assigned to every mode.

# Secondary E7 diagnostic tables

Derived files in `results/diagnostics/E7/` reuse the committed forced bank and add no calls.

- `D_router_one_stage.csv`: independent prespecified-router reconstruction.
- `D_router_two_stage.csv`: constraint-aware choices; `predicted` is physical-objective prediction.
- `D_router_quality_only.csv`: 72-scenario all-feasible ablation.
- `D_bootstrap.csv`: 5,000 paired draws for one-stage, constraint-aware, and quality-only regret/value.
- `D_specification_grid.csv`: 36 stage x alpha x holdout x feature-set sensitivity rows.
- `D_penalty_target_predictions.csv`, `D_penalty_target_picks.csv`: one-stage target diagnostics.
- `D_summary.csv`, `D_summary.json`: machine-readable headline and stability values.
- `e7_diagnostics.pdf/.svg/.png`: supplementary three-panel figure.

See `docs/E7_DIAGNOSTICS.md` for field-level interpretation and assumptions.


## Multimodel extension tables

| File | Rows | Description |
|---|---:|---|
| `results/multimodel/data/M0_probe.csv` | 7 | Capability/configuration probes; one or more rows per model until a parseable declaration configuration is found. |
| `M1_declarations.csv` | 300 | One typed declaration per model, planner-visible state, and repetition; includes mode, policy fields, parsing, tokens, and latency. |
| `M1_summary.csv` | 5 | Per-model mode diversity, concentration, entropy, and bootstrap interval. |
| `M2_state_dependence.csv` | 5 | Conservative 20-state and secondary three-band Cramer's V tests plus logistic stress trend. |
| `M2_mode_by_stress_band.csv` | variable | Mode counts and shares by model and stress band. |
| `M3_shift.csv` | 200 | Bounded four-mode shift vectors and L1-budget use. |
| `M3_shift_summary.csv` | 5 | Per-model shift-budget summary. |
| `M4_persuasion.csv` | 240 | Bounded prosumer willingness shifts by model, archetype, theme, neighbour level, and repetition. |
| `M4_archetype_summary.csv` | 20 | Mean shift by model and archetype. |
| `M4_reciprocity_summary.csv` | 5 | High-minus-low neighbour-compliance response summary. |
| `M5_cost.csv` | 5 | Original pooled-interface latency/cost export; preserved but not used for reported latency claims. |
| `M5_latency_by_interface.csv` | 15 | Correct latency summaries separated into declaration, bounded-shift, and persuasion interfaces. |
| `M5_declaration_latency.csv` | 5 | Canonical declaration-only p50, p95, maximum, and tail ratio. |
| `M_multimodel_key_results.csv` | 5 | Compact public key-results table for declaration, state dependence, and latency. |
| `M_multimodel_summary.json` | 1 | Machine-readable design, classification, summaries, and caveats. |