Stock Value vs Max Budget KPI — Investigation & Fix

1. Symptom

On the Dashboard → IO tab, the "Stock Value" KPI showed 4.4M while the IO parameter's max_budget was 15,000. The user expected these two numbers to be directly comparable — they were both served from the same IO parameter set, so the 300× gap looked like a bug.

2. Investigation

Step 1 — Trace the KPI source

The Dashboard IO tab's "Stock Value" KPI is computed at read time as:

stock_value = Σ (committed_buffer × unit_cost)

summed over every (item_id, site_id) row in PIPE_meio_results for the active pipeline. The value is an absolute total of safety-stock investment.

Step 2 — Trace the Budget Cap chip

The Budget Cap chip (Dashboard.jsx:4238) renders only when kpis?.maxBudget != null. That field is populated from the /api/meio/fr-heatmap endpoint, whose group-results pre-fetch in main.py:~27710 selected:

SELECT group_name, segment_id, achieved_fill_rate, fill_rate_target
FROM PIPE_meio_group_results
WHERE pipeline_id = %s AND scenario_id = %s

— only four columns, never achieved_budget or max_budget. So maxBudget was always null, the chip was always hidden, and the only 15,000 the user ever saw was the configured parameter-set field value, not a live KPI.

Step 3 — Are the two metrics even comparable?

Even if both were served, they are not the same metric:

achieved_budget equals the absolute total only on a fresh run (initial buffers = 0). After any re-run with non-zero initial buffers, the optimizer's stored value is a delta, not an absolute. So comparing Stock Value directly to achieved_budget would be wrong in steady state.

Step 4 — Label clarity

The label "Stock Value" was vague — it did not convey that the figure is safety-stock investment, i.e. the same quantity the max_budget cap is meant to bound.

3. Root cause

Three distinct issues combined to produce the symptom:

1. Missing columns in the heatmap pre-fetch. /api/meio/fr-heatmap selected only group_name, segment_id, achieved_fill_rate, fill_rate_target — not achieved_budget or max_budget. The Budget Cap chip's maxBudget gate (kpis?.maxBudget != null) was therefore always false, so the chip never rendered.
2. Metric mismatch. Even when both values are served, Stock Value (absolute total) and the optimizer's achieved_budget (net delta) are not directly comparable except on a fresh run. max_budget is a cap, not a live KPI.
3. Vague label. "Stock Value" did not convey the safety-stock-investment semantics that make it comparable to max_budget.

4. The fix

A. Stock Value vs Max Budget KPI production fix

Files: files/api/main.py, files/frontend/src/components/Dashboard.jsx

• Added achieved_budget, max_budget to the heatmap group_results SELECT so the Budget Cap chip can render:

SELECT group_name, segment_id, achieved_fill_rate, fill_rate_target,
       achieved_budget, max_budget
FROM PIPE_meio_group_results
WHERE pipeline_id = %s AND scenario_id = %s

• Added a (item_id, site_id) → segment_id map fetch from PIPE_segment_membership, guarded by if _pre_group_results: and scoped to archive_date = (SELECT max(archive_date) ...) to avoid a full-history scan. This lets per-group absolute inventory value be computed.
• Computed per-group achieved_budget_abs = Σ committed_buffer × unit_cost from the heatmap's fetched rows, using the same unit-cost fallback chain the heatmap rows loop uses:

 achieved_budget_abs += ss_v_db if ss_v_db > 0 else (buf * ucost)

This makes the chip numerator directly comparable to the Safety Stock Value KPI (both are absolute totals over the same (item_id, site_id) set).

• Frontend chip numerator now uses achieved_budget_abs ?? achieved_budget — falls back gracefully to the optimizer's stored delta when the absolute computation is unavailable.
• Renamed label Stock Value → Safety Stock Value.
• Preserved the optimizer's stored achieved_budget for the diagnostic/completion view (not deleted, just no longer the chip numerator).

B. Mirabelle scenario-id consolidation single source of truth

Problem: The PIPE_* table → scenario-type mapping was duplicated across three places that had already diverged:

• _TABLE_SCENARIO_TYPE in service.py
• the LLM prompt rules in sql_generator.py (missing PIPE_allocation_explanations, PIPE_backtest_fingerprints, PIPE_series_hashes)
• AGENTS.md

Files: files/mirabelle/config.py, files/mirabelle/service.py, files/mirabelle/sql_generator.py

• Moved TABLE_SCENARIO_TYPE and SCENARIO_COL maps to config.py as the single source of truth.
• service.py: _TABLE_SCENARIO_TYPE / _SCENARIO_COL are now thin aliases of config.TABLE_SCENARIO_TYPE / config.SCENARIO_COL.
• sql_generator.py: _build_system_prompt() now generates the "SCENARIO_ID PER TABLE" per-type table list from config.TABLE_SCENARIO_TYPE / config.SCENARIO_COL instead of a hardcoded copy. The three previously divergent tables now appear in the prompt.

# config.py — single source of truth
TABLE_SCENARIO_TYPE = {
    "PIPE_meio_results": "meio_scenario_id",
    "PIPE_supply_orders": "supply_scenario_id",
    "PIPE_causal_forecast": "causal_scenario_id",
    # ... every PIPE_* table
}
SCENARIO_COL = "scenario_id"

5. Files changed

6. Validation

• Import chain: files/mirabelle/ imports load cleanly — config.TABLE_SCENARIO_TYPE resolved from both service.py and sql_generator.py.
• Generated prompt: the LLM system prompt now contains all expected PIPE_* tables and their correct scenario columns, including the three previously missing (PIPE_allocation_explanations, PIPE_backtest_fingerprints, PIPE_series_hashes).
• Dashboard chip: Budget Cap chip renders with max_budget once the heatmap endpoint returns the new columns; numerator uses achieved_budget_abs so it is directly comparable to the Safety Stock Value KPI.
• Label: "Safety Stock Value" now conveys the safety-stock-investment semantics.

7. Known follow-ups

1. Partition mismatch in segment_membership map — files/api/main.py:27947: the segment_membership map is pinned to max(archive_date), but the PIPE_meio_results rows feeding achieved_budget_abs have no archive_date filter. A partition mismatch can drop SKUs in edge cases (e.g. MEIO re-run without re-segmentation), so the absolute sum under-counts. The archive_date filter should be applied consistently to both sides of the join.
2. Untracked config modules — files/main.py:294 / files/alerts/engine.py:17: utils/server_config.py and alerts/config.py are untracked in git. Deploying from a clean checkout raises ModuleNotFoundError (server_config) or silently defeats env config (alerts). They must be git added before commit.
3. allocation_cover_weeks silent default flip — files/supply/src/engine.rs:124: allocation_cover_weeks defaults to 0, silently flipping every existing pipeline from the old lead_time + 3 cover buffer to exactly-safety-stock sizing. This is a service-level behavior change with no opt-in — existing pipelines that relied on the forward cover will see smaller transfer orders with no warning. Either preserve the legacy default or expose an explicit migration flag.

8. Out of scope

• MEIO committed_buffer recalculation (unchanged — remains the SS source of truth).
• The optimizer's target.rs commit_groups net-investment accounting (preserved as-is).
• max_budget parameter-set editor UI (no schema change).
• Frontend chart rendering on the IO tab.