Supply Inventory Drift Above Safety Stock — Root-Cause & Fix

1. Symptom

On the series page for http://mirabelle.ddns.net/series/16_301, the projected stock line climbs monotonically above the displayed safety-stock line and never plateaus within the 52-week horizon.

2. Investigation trail

Step 1 — Netting logic (initial suspect)

The Rust netting_pass (supply/src/netting.rs:18) computes carry = (available - demand).max(0.0) — it keeps everything above demand, including surplus above SS. This pointed at where does the surplus come from?

Step 2 — Allocation cover buffer (red herring)

The Rust allocate_transfers had a hardcoded cover_weeks = lead_time + 3 forward look-ahead, driving the target to SS + 5×demand ≈ 9.25. But the production path does not use Rust allocation (disabled in favour of Python _allocate_transfers).

Step 3 — Python allocation tracker

Instrumenting the Python allocation showed the tracker correctly held the store at SS=5.0. The Python allocation was not the source of the drift.

16_301 transfer orders: 52  qty_sum: 43.24
16_301 init_inv: 2.7  demand_sum: 40.94  sr_sum: 43.24
16_301 projected peak (alloc tracker): 5.0  final: 5.0  SS=5

Step 4 — Pass-2 store MRP (the divergence)

The store's TRANSFER receipts (SRs) are injected as scheduled_receipts into the Pass-2 Rust engine run. Week 0: SR=3.572 vs demand=1.272 (+2.3 SS top-up). Weeks 1+: SR=demand exactly (net zero). Yet the Rust result showed inventory climbing.

Step 5 — f32 rounding hypothesis (false lead)

In f32, 2.7f32 + 3.572f32 = 6.272037 (overshoot by ~3.7e-5). But simulating the exact f32 netting produced carry=5.0 exactly. f32 rounding was not the cause.

Step 6 — Repair returns autofill (the real cause) FOUND

The store has a Repair route:

{"source_type": "Repair", "return_rate": 1.0, "repair_yield": 0.07, "repair_turnaround": 0}

The Rust preprocessing pass (supply/src/preprocess.rs:127, autofill_repair_returns) computes repair returns when the plan's repair_returns array is all-zero:

// repair_returns[w] = demand[w - turnaround] * return_rate * repair_yield
let qty = plan.demand[src] * rr * ry;  // = demand[w] * 1.0 * 0.07 = 7% of demand

This repair supply is on top of the TRANSFER receipts (which already equal demand). So every week the store receives demand + 7%×demand but only consumes demand → the 7% surplus accumulates above SS.

wk=0  sr=3.572  rr=0.089  dem=1.272  → carry=5.089  (surplus=0.089)
wk=1  sr=1.005  rr=0.070  dem=1.005  → carry=5.159  (surplus=0.159)
...
final carry = 7.87  (= 5.0 SS + 2.87 accumulated repair returns)

3. Root cause — double supply from repair autofill

The Python _allocate_transfers sizes TRANSFER receipts to cover demand + the SS gap, without knowing that the Rust netting will also add autofilled repair returns. The two supply sources are additive:

TRANSFER receipts (Python)   = demand + SS_top_up      ← covers full demand
Repair returns (Rust autofill) = demand × 7%            ← surplus on top
───────────────────────────────────────────────────────────
Total supply                   = demand × 1.07 + SS_top_up

For low-demand/intermittent series the ~7% weekly surplus is never consumed, so it accumulates and the projected inventory climbs monotonically above SS.

4. The red herring — allocation cover buffer

The Rust allocate_transfers cover buffer (lead_time + 3 hardcoded at allocation.rs:347) looked like the cause. It was fixed anyway because:

• It is a genuine latent bug — the Python mirror targets exactly SS, so Rust had diverged from its own docstring.
• It was made configurable (allocation_cover_weeks, default 0).
• It only affects the Rust allocation path (currently disabled in production).

5. The fix

1. Python — offset TRANSFER receipts by expected repair returns production fix

files/supply_runner.py — _allocate_transfers:

• Pre-compute expected_repair[(item_id, site_id)] for every leaf store, mirroring the Rust autofill_repair_returns logic (including turnaround=0).
• In the leaf-store need computation, subtract the expected repair returns:

  inv_after_demand = d_inv - d_dem + d_rr_w   # was: d_inv - d_dem
  dest_needs[d_site] = max(0.0, d_ss_w - inv_after_demand)

• Update dest_inv_tracker at all three sites (idle, no-transfer, active) to add repair returns, keeping the tracker in sync with the Rust netting.

2. Rust — configurable allocation cover buffer forward-looking fix

• EngineConfig.allocation_cover_weeks (engine.rs) — new field, default 0.
• allocate_transfers (allocation.rs) — accepts cover_weeks, replaces hardcoded lead_time + 3. With 0, the look-ahead loop is empty → need collapses to max(0, SS - inv_after_demand).
• supply_runner.py — wires allocation_cover_weeks into engine_cfg (default 0) + config defaults + validation.

6. Before / after data

Series 16_301 (pipeline 4, archive 2026-06-15)

7. Files changed

8. Validation

• Rust tests: cargo test --lib allocation:: netting:: — 8 passed, 0 failed.
• Pipeline re-run: pipeline 4 supply run completed; order_count 33285→33009, shortage_count unchanged (9561, no new shortages).
• Series 16_301: inventory 5.0–5.46 (was 5.09→7.87), 0 shortage weeks, transfers 52→45.
• Pre-existing failures: 2 score_alloc tests fail on clean baseline too (unrelated).

9. Risks & guards

• The expected_repair computation mirrors Rust's autofill_repair_returns but is a separate implementation. If the Rust autofill logic changes, this Python mirror must be kept in sync.
• For stores with confirmed repair returns (non-zero array), Rust takes max(confirmed, autofill). The Python mirror uses confirmed values as a lower bound — correct when confirmed ≥ autofill, slightly conservative otherwise.
• The allocation_cover_weeks Rust field is currently inert in production (Rust allocation disabled) but is the rollback lever if Rust allocation is re-enabled.