Add online predictive KV tiering experiments

README.md

@@ -137,20 +137,30 @@ The Predictive Tiering Lab deliberately changes the duration distribution of slo
 
 Model dynamic multi-agent workflows as a sequence of reusable agent roles rather than only a sequence of tool durations. The default synthetic workflow has structured transitions among `planner`, `retriever`, `reasoner`, `verifier`, and `writer`, then deliberately changes its transition matrix partway through the study.
 
-The simulator maintains a bounded shared HBM cache for each role's reusable static prefix. A first-order transition model is updated **only after the next role is observed** and can trigger host-to-HBM prefetch during the intervening tool gap. Four policies are available:
+The simulator maintains a bounded shared HBM cache for each role's reusable static prefix. A first-order transition model is updated **only after the next role is observed**. The learned matrix can now be rolled forward for several steps without reading the future trace. Single-run policies include learn-only, cumulative/decayed top-1 prefetch, multi-step top-k prefetch, a utility-aware multi-step planner, and explicitly labeled oracle information bounds.
 
-1. learn-only / no prefetch;
-2. cumulative transition counts;
-3. exponentially decayed transition counts;
-4. an explicitly labeled oracle next-role upper bound.
+The utility-aware planner estimates, for each candidate role:
 
-Three experiments separate prediction quality from systems quality:
+```text
+expected discounted reuse benefit
+- host-to-HBM transfer time
+- forecast-weighted recomputation cost of prefixes that would be evicted
+```
+
+This is intentionally a transparent reference objective rather than a learned black-box policy.
 
-- **Prefetch Policy Study:** compare the four policies on one common shifted workflow trace;
+Six controlled experiments separate prediction quality from systems quality:
+
+- **Prefetch Policy Study:** compare no prefetch, cumulative counts, decayed counts, and a clairvoyant next-role information bound on one common shifted workflow trace;
 - **Confidence Threshold Study:** trade prefetch coverage against precision, wrong-step traffic, cache pollution, and TTFT;
-- **Forgetting-Rate Study:** vary how quickly old transitions are forgotten after the workflow changes and compare post-shift accuracy with downstream latency/cache outcomes.
+- **Forgetting-Rate Study:** vary how quickly old transitions are forgotten after the workflow changes;
+- **Prefetch Planning Study:** compare one-step, multi-step top-k, utility-aware multi-step, and a clairvoyant future-set information bound;
+- **Forecast Horizon Study:** sweep how many future workflow steps the online planner rolls forward;
+- **Cache Budget Study:** compare top-1, multi-step, and utility-aware planning under multiple working-set-relative HBM budgets.
+
+Prediction diagnostics now include top-1 accuracy, Brier score, multiclass log loss, expected calibration error (ECE), and pre/post-shift calibration. Serving diagnostics separately track forecast-set recall, immediate next-step precision, eventual prefetch utilization, unused prefetch volume, cache hits, HBM residency, and p95 latency. A predictor can therefore become better calibrated or more accurate without automatically being declared a better serving policy.
 
-A perfect next-role predictor is **not assumed to be a perfect serving policy**: aggressive prefetch can still evict useful prefixes or occupy transfer/cache capacity. The UI therefore reports prediction accuracy and serving outcomes side by side and labels correlations from parameter sweeps as descriptive rather than causal.
+The oracle candidates are **clairvoyant information bounds**, not guaranteed upper bounds on serving performance: perfect local future information can still trigger globally poor cache or transfer decisions. That distinction is intentional.
 
 Single Agent Session runs, Predictive Tiering studies, adaptation sweeps, and Execution Learning studies all support JSON artifact export in addition to CSV/table export where applicable.
 

app.js

@@ -22,6 +22,9 @@ let lastExecutionRun = null;
 let lastExecutionCompare = null;
 let lastExecutionThreshold = null;
 let lastExecutionDecay = null;
+let lastExecutionPlanning = null;
+let lastExecutionHorizon = null;
+let lastExecutionBudget = null;
 let traceRequests = [];
 
 const COLORS = {
@@ -45,7 +48,7 @@ worker.addEventListener("message", (event) => {
   if (data.type === "ready") {
     runtimePill.classList.add("ready");
     runtimeText.textContent = "Python runtime ready";
-    ["runBtn", "arenaBtn", "capacityBtn", "topologyBtn", "designBtn", "pairedStudyBtn", "robustStudyBtn", "agentRunBtn", "agentCompareBtn", "agentTtlBtn", "agentMemoryCompareBtn", "agentBudgetBtn", "agentAffinityBtn", "predictiveCompareBtn", "predictiveAlphaBtn", "execRunBtn", "execCompareBtn", "execThresholdBtn", "execDecayBtn"].forEach((id) => { $(id).disabled = false; });
+    ["runBtn", "arenaBtn", "capacityBtn", "topologyBtn", "designBtn", "pairedStudyBtn", "robustStudyBtn", "agentRunBtn", "agentCompareBtn", "agentTtlBtn", "agentMemoryCompareBtn", "agentBudgetBtn", "agentAffinityBtn", "predictiveCompareBtn", "predictiveAlphaBtn", "execRunBtn", "execCompareBtn", "execThresholdBtn", "execDecayBtn", "execPlanningBtn", "execHorizonBtn", "execBudgetBtn"].forEach((id) => { $(id).disabled = false; });
     syncConditionalControls();
     window.setTimeout(() => document.body.classList.add("runtime-ready"), 650);
     return;
@@ -1122,6 +1125,11 @@ function executionConfigFromUI(overrides = {}) {
     transition_decay: num("execDecay"),
     confidence_threshold: num("execThreshold"),
     host_bandwidth_gbps: num("execBandwidth"),
+    forecast_horizon: num("execHorizon"),
+    prefetch_top_k: num("execTopK"),
+    forecast_discount: num("execDiscount"),
+    forecast_min_score: num("execMinScore"),
+    utility_threshold_ms: num("execUtility"),
     ...overrides,
   };
 }
@@ -1152,10 +1160,14 @@ function renderExecutionRun(result) {
   $("execPrecision").textContent = r.prefetch_attempts ? pct(r.prefetch_precision) : "N/A";
   $("execCoverage").textContent = pct(r.prefetch_coverage);
   $("execWaste").textContent = `${fmt(r.wrong_step_prefetch_gb, 4)} GB`;
+  $("execEce").textContent = pct(p.calibration?.ece || 0);
+  $("execForecastRecall").textContent = pct(r.forecast_recall || 0);
+  $("execUtilization").textContent = r.prefetch_attempts ? pct(r.prefetch_utilization || 0) : "N/A";
+  $("execUnused").textContent = `${fmt(r.unused_prefetch_gb || 0, 4)} GB`;
   $("execRunState").textContent = `${s.workflows_completed}/${s.workflows_generated} workflows`;
   $("execRunState").className = `tag ${s.workflow_completion_rate === 1 ? "good" : "bad"}`;
   const lookahead = result.provenance.lookahead === "oracle-upper-bound" ? "oracle upper bound" : "online/no-lookahead";
-  $("execRunSummary").innerHTML = `<strong>${escapeHtml(result.config.prefetch_policy.replaceAll("_", " "))} policy.</strong> ${p.count} observed transitions; top-1 accuracy ${pct(p.top1_accuracy)} overall and ${pct(p.post_shift_accuracy)} after the workflow shift. Prefix hits saved ${fmt(r.prefill_tokens_saved, 0)} prefill tokens while ${fmt(r.wrong_step_prefetch_gb, 4)} GB of transfer was sent toward the wrong immediate next role. Provenance: ${escapeHtml(lookahead)}.`;
+  $("execRunSummary").innerHTML = `<strong>${escapeHtml(result.config.prefetch_policy.replaceAll("_", " "))} policy.</strong> ${p.count} observed transitions; top-1 accuracy ${pct(p.top1_accuracy)} overall and ${pct(p.post_shift_accuracy)} after the workflow shift. Calibration ECE is ${pct(p.calibration?.ece || 0)}. Forecast-set recall is ${pct(r.forecast_recall || 0)}; ${r.prefetch_attempts || 0} prefetch attempts achieved ${pct(r.prefetch_utilization || 0)} eventual utilization and left ${fmt(r.unused_prefetch_gb || 0, 4)} GB unused before eviction/end. Provenance: ${escapeHtml(lookahead)}.`;
 
   const timeline = result.timeline || [];
   destroyChart("execTimeline");
@@ -1181,6 +1193,17 @@ function renderExecutionRun(result) {
     data: { datasets },
     options: { ...commonChartOptions(), parsing: false, plugins: { legend: lineLegend() }, scales: { x: { type: "linear", beginAtZero: true, title: { display: true, text: "Observed transitions" } }, y: { min: 0, max: 100, title: { display: true, text: "Rolling top-1 accuracy (%)" } } } },
   });
+
+  const calibrationBins = p.calibration?.bins || [];
+  destroyChart("execCalibration");
+  charts.execCalibration = new Chart($("execCalibrationChart"), {
+    type: "line",
+    data: { datasets: [
+      { label: "Observed accuracy", data: calibrationBins.map((b) => ({ x: b.mean_confidence * 100, y: b.accuracy * 100 })), borderColor: COLORS.blue, backgroundColor: COLORS.blue, pointRadius: 5, tension: .08, fill: false },
+      { label: "Perfect calibration", data: [{ x: 0, y: 0 }, { x: 100, y: 100 }], borderColor: COLORS.steel, backgroundColor: COLORS.steel, borderDash: [6, 5], pointRadius: 0, fill: false },
+    ] },
+    options: { ...commonChartOptions(), parsing: false, plugins: { legend: lineLegend() }, scales: { x: { type: "linear", min: 0, max: 100, title: { display: true, text: "Mean predicted confidence (%)" } }, y: { min: 0, max: 100, title: { display: true, text: "Observed top-1 accuracy (%)" } } } },
+  });
 }
 
 $("execRunBtn").addEventListener("click", async () => {
@@ -1289,6 +1312,104 @@ $("execDecayCopy").addEventListener("click", () => { if (lastExecutionDecay) cop
 $("execDecayCsv").addEventListener("click", () => { if (lastExecutionDecay) downloadCsv(`inferscale_execution-decay-sweep_${stamp()}.csv`, execDecayHeaders, execDecayTableRows(lastExecutionDecay)); });
 $("execDecayJson").addEventListener("click", () => { if (lastExecutionDecay) downloadNamedJson("inferscale_execution-decay-sweep", lastExecutionDecay); });
 
+
+const execPlanningHeaders = ["Policy", "p95 TTFT", "Forecast recall", "Prefix hit", "Utilization", "Next-step precision", "Mean HBM", "Unused prefetch", "Saved prefill", "ECE"];
+function execPlanningTableRows(result) {
+  return result.rows.map((r) => [
+    r.label, `${fmt(r.p95_step_ttft_ms)} ms`, pct(r.forecast_recall), pct(r.prefix_hit_rate),
+    r.prefetch_coverage ? pct(r.prefetch_utilization) : "N/A", r.prefetch_coverage ? pct(r.prefetch_precision) : "N/A",
+    `${fmt(r.mean_hbm_gb, 4)} GB`, `${fmt(r.unused_prefetch_gb, 4)} GB`, `${fmt(r.prefill_tokens_saved, 0)} tok`, pct(r.ece),
+  ]);
+}
+function renderExecutionPlanning(result) {
+  lastExecutionPlanning = result;
+  $("execPlanningEmpty").classList.add("hidden"); $("execPlanningContent").classList.remove("hidden");
+  ["execPlanningCopy", "execPlanningCsv", "execPlanningJson"].forEach((id) => { $(id).disabled = false; });
+  $("execPlanningBestTtft").textContent = result.best_ttft_policy || "N/A";
+  $("execPlanningBestEfficiency").textContent = result.best_prefill_per_hbm_policy || "N/A";
+  $("execPlanningHorizon").textContent = `${num("execHorizon")} steps`;
+  $("execPlanningTopK").textContent = `${num("execTopK")} roles`;
+  $("execPlanningRows").innerHTML = execPlanningTableRows(result).map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml(String(cell))}</td>`).join("")}</tr>`).join("");
+  const palette = [COLORS.steel, COLORS.blue, COLORS.green, COLORS.amber];
+  destroyChart("execPlanning");
+  charts.execPlanning = new Chart($("execPlanningChart"), {
+    type: "scatter",
+    data: { datasets: result.rows.map((r, i) => ({ label: r.label, data: [{ x: r.mean_hbm_gb, y: r.p95_step_ttft_ms }], backgroundColor: palette[i], borderColor: palette[i], pointRadius: 7, pointHoverRadius: 9 })) },
+    options: { ...commonChartOptions(), plugins: { legend: pointLegend() }, scales: { x: { beginAtZero: true, title: { display: true, text: "Mean prefix HBM (GB)" } }, y: { beginAtZero: true, title: { display: true, text: "p95 step TTFT (ms)" } } } },
+  });
+}
+$("execPlanningBtn").addEventListener("click", async () => {
+  const button = $("execPlanningBtn"); button.disabled = true; button.textContent = "Comparing planners...";
+  try { renderExecutionPlanning(await callPython("execution_planning_study", { config: executionConfigFromUI() })); }
+  catch (error) { alert(`Execution planning study failed: ${error.message}`); }
+  finally { button.disabled = false; button.textContent = "Compare planning policies"; }
+});
+$("execPlanningCopy").addEventListener("click", () => { if (lastExecutionPlanning) copyText(tableText(execPlanningHeaders, execPlanningTableRows(lastExecutionPlanning)), "Planning table copied"); });
+$("execPlanningCsv").addEventListener("click", () => { if (lastExecutionPlanning) downloadCsv(`inferscale_execution-planning-study_${stamp()}.csv`, execPlanningHeaders, execPlanningTableRows(lastExecutionPlanning)); });
+$("execPlanningJson").addEventListener("click", () => { if (lastExecutionPlanning) downloadNamedJson("inferscale_execution-planning-study", lastExecutionPlanning); });
+
+const execHorizonHeaders = ["Horizon", "p95 TTFT", "Forecast recall", "Prefix hit", "Utilization", "Unused prefetch", "Mean HBM", "Saved prefill"];
+function execHorizonTableRows(result) {
+  return result.rows.map((r) => [r.horizon, `${fmt(r.p95_step_ttft_ms)} ms`, pct(r.forecast_recall), pct(r.prefix_hit_rate), r.prefetch_coverage ? pct(r.prefetch_utilization) : "N/A", `${fmt(r.unused_prefetch_gb, 4)} GB`, `${fmt(r.mean_hbm_gb, 4)} GB`, `${fmt(r.prefill_tokens_saved, 0)} tok`]);
+}
+function renderExecutionHorizon(result) {
+  lastExecutionHorizon = result;
+  $("execHorizonEmpty").classList.add("hidden"); $("execHorizonContent").classList.remove("hidden");
+  ["execHorizonCopy", "execHorizonCsv", "execHorizonJson"].forEach((id) => { $(id).disabled = false; });
+  $("execHorizonBestTtft").textContent = `${result.best_ttft_horizon ?? "N/A"} steps`;
+  $("execHorizonBestUtil").textContent = `${result.best_utilization_horizon ?? "N/A"} steps`;
+  $("execHorizonTopK").textContent = `${num("execTopK")} roles`;
+  $("execHorizonBudget").textContent = `${fmt(num("execCacheBudget"), 2)}x`;
+  $("execHorizonRows").innerHTML = execHorizonTableRows(result).map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml(String(cell))}</td>`).join("")}</tr>`).join("");
+  destroyChart("execHorizon");
+  charts.execHorizon = new Chart($("execHorizonChart"), {
+    type: "line",
+    data: { datasets: [
+      { label: "p95 step TTFT", data: result.rows.map((r) => ({ x: r.horizon, y: r.p95_step_ttft_ms })), borderColor: COLORS.blue, backgroundColor: COLORS.blue, pointRadius: 4, yAxisID: "yLatency", fill: false },
+      { label: "Prefetch utilization", data: result.rows.map((r) => ({ x: r.horizon, y: r.prefetch_utilization * 100 })), borderColor: COLORS.green, backgroundColor: COLORS.green, pointRadius: 4, yAxisID: "yPct", fill: false },
+      { label: "Forecast recall", data: result.rows.map((r) => ({ x: r.horizon, y: r.forecast_recall * 100 })), borderColor: COLORS.amber, backgroundColor: COLORS.amber, pointRadius: 4, borderDash: [6, 4], yAxisID: "yPct", fill: false },
+    ] },
+    options: { ...commonChartOptions(), parsing: false, plugins: { legend: lineLegend() }, scales: { x: { type: "linear", min: 1, max: 5, ticks: { stepSize: 1 }, title: { display: true, text: "Forecast horizon (steps)" } }, yLatency: { position: "left", beginAtZero: true, title: { display: true, text: "p95 TTFT (ms)" } }, yPct: { position: "right", min: 0, max: 100, grid: { drawOnChartArea: false }, title: { display: true, text: "Recall / utilization (%)" } } } },
+  });
+}
+$("execHorizonBtn").addEventListener("click", async () => {
+  const button = $("execHorizonBtn"); button.disabled = true; button.textContent = "Sweeping horizons...";
+  try { renderExecutionHorizon(await callPython("execution_horizon_sweep", { config: executionConfigFromUI() })); }
+  catch (error) { alert(`Forecast horizon sweep failed: ${error.message}`); }
+  finally { button.disabled = false; button.textContent = "Sweep forecast horizon"; }
+});
+$("execHorizonCopy").addEventListener("click", () => { if (lastExecutionHorizon) copyText(tableText(execHorizonHeaders, execHorizonTableRows(lastExecutionHorizon)), "Horizon table copied"); });
+$("execHorizonCsv").addEventListener("click", () => { if (lastExecutionHorizon) downloadCsv(`inferscale_execution-horizon-sweep_${stamp()}.csv`, execHorizonHeaders, execHorizonTableRows(lastExecutionHorizon)); });
+$("execHorizonJson").addEventListener("click", () => { if (lastExecutionHorizon) downloadNamedJson("inferscale_execution-horizon-sweep", lastExecutionHorizon); });
+
+const execBudgetHeaders = ["Budget", "Policy", "p95 TTFT", "Forecast recall", "Prefix hit", "Utilization", "Mean HBM", "Unused prefetch", "Pressure evictions"];
+function execBudgetTableRows(result) {
+  return result.rows.map((r) => [`${fmt(r.budget, 2)}x`, r.policy_label, `${fmt(r.p95_step_ttft_ms)} ms`, pct(r.forecast_recall), pct(r.prefix_hit_rate), r.prefetch_coverage ? pct(r.prefetch_utilization) : "N/A", `${fmt(r.mean_hbm_gb, 4)} GB`, `${fmt(r.unused_prefetch_gb, 4)} GB`, fmt(r.pressure_evictions, 0)]);
+}
+function renderExecutionBudget(result) {
+  lastExecutionBudget = result;
+  $("execBudgetEmpty").classList.add("hidden"); $("execBudgetContent").classList.remove("hidden");
+  ["execBudgetCopy", "execBudgetCsv", "execBudgetJson"].forEach((id) => { $(id).disabled = false; });
+  $("execBudgetRows").innerHTML = execBudgetTableRows(result).map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml(String(cell))}</td>`).join("")}</tr>`).join("");
+  const policyColors = { "Top-1": COLORS.steel, "Multi-step": COLORS.blue, "Utility-aware": COLORS.green };
+  const policies = ["Top-1", "Multi-step", "Utility-aware"];
+  destroyChart("execBudget");
+  charts.execBudget = new Chart($("execBudgetChart"), {
+    type: "line",
+    data: { datasets: policies.map((policy) => ({ label: policy, data: result.rows.filter((r) => r.policy_label === policy).map((r) => ({ x: r.budget, y: r.p95_step_ttft_ms })), borderColor: policyColors[policy], backgroundColor: policyColors[policy], pointRadius: 4, tension: .08, fill: false })) },
+    options: { ...commonChartOptions(), parsing: false, plugins: { legend: lineLegend() }, scales: { x: { type: "linear", min: .25, max: 1.05, title: { display: true, text: "Prefix-cache budget (working-set x)" } }, y: { beginAtZero: true, title: { display: true, text: "p95 step TTFT (ms)" } } } },
+  });
+}
+$("execBudgetBtn").addEventListener("click", async () => {
+  const button = $("execBudgetBtn"); button.disabled = true; button.textContent = "Sweeping cache budget...";
+  try { renderExecutionBudget(await callPython("execution_budget_sweep", { config: executionConfigFromUI() })); }
+  catch (error) { alert(`Cache budget study failed: ${error.message}`); }
+  finally { button.disabled = false; button.textContent = "Sweep cache budget"; }
+});
+$("execBudgetCopy").addEventListener("click", () => { if (lastExecutionBudget) copyText(tableText(execBudgetHeaders, execBudgetTableRows(lastExecutionBudget)), "Cache budget table copied"); });
+$("execBudgetCsv").addEventListener("click", () => { if (lastExecutionBudget) downloadCsv(`inferscale_execution-cache-budget-sweep_${stamp()}.csv`, execBudgetHeaders, execBudgetTableRows(lastExecutionBudget)); });
+$("execBudgetJson").addEventListener("click", () => { if (lastExecutionBudget) downloadNamedJson("inferscale_execution-cache-budget-sweep", lastExecutionBudget); });
+
 function syncAgentControls() {
   const retention = $("agentRetention").value;
   const routing = $("agentRouting").value;

docs/architecture.md

@@ -15,7 +15,8 @@ InferScale-Sim separates **serving-system logic**, **analytical latency estimati
 9. `research.py` implements paired common-seed A/B studies, bootstrap intervals, and analytical-model sensitivity analysis.
 10. `agentic.py` models multi-turn programs, tool gaps, session routing, KV retention/TTL eviction, host tiering, and online tool-gap prediction.
 11. `execution.py` models online agent-role transition learning and bounded static-prefix prefetch under a shifting workflow distribution.
-12. `validation.py` compares predictions against externally supplied measured cases.
+12. `execution.py` also contains online transition calibration, multi-step forecast planning, and cache-budget/horizon study helpers.
+13. `validation.py` compares predictions against externally supplied measured cases.
 13. `api.py` exposes JSON-like actions to local Python and Pyodide.
 
 ## Colocated path

docs/methodology.md

@@ -231,27 +231,49 @@ The EWMA alpha sweep replays the exact same shifted trace for every candidate al
 
 Execution Learning models a different reuse object from Agent Sessions. Agent Sessions tracks one user's growing cross-turn KV state. Execution Learning tracks reusable *static agent prefixes* (for example planner/retriever/reasoner system context) that can be shared across workflows.
 
-A synthetic workflow is generated from a first-order role-transition matrix over five agent roles plus an `END` state. At `shift_fraction` of the arrival horizon a second transition matrix becomes active, changing the execution distribution without changing the hardware/model profile. Every candidate in a study replays the exact same generated workflows.
+A synthetic workflow is generated from a first-order role-transition matrix over five agent roles plus an `END` state. At `shift_fraction` of the arrival horizon a second transition matrix becomes active. Every candidate in a controlled study replays the exact same workflows.
 
-The online transition learner stores a row of counts for each current role. A prediction is made **before** the next role is observable. The next role is added to the learner only when the tool gap ends and that step becomes ready. `transition_decay = 1` is cumulative counting; smaller values exponentially forget older transitions and can adapt faster after the regime shift.
+The learner stores a transition row for each current role. Prediction occurs **before** the next role is observable, and the model is updated only when that next role becomes ready after the tool gap. `transition_decay = 1` is cumulative counting; smaller values exponentially forget older evidence.
 
-The learned top-1 prediction can trigger host-to-HBM prefetch only when its confidence exceeds `confidence_threshold`. Static role-prefix sizes are derived from the analytical KV bytes/token model and fixed role-prefix token counts. The shared prefix cache is intentionally bounded as a fraction of the five-role working set, so wrong prefetches can cause realistic opportunity cost through eviction and transfer occupancy.
+### Multi-step forecast
 
-The simulator reports prediction metrics and serving metrics separately:
+For a current role, InferScale rolls the learned transition matrix forward for `forecast_horizon` steps. Future-step distributions are accumulated with geometric discount `forecast_discount`. This produces an expected discounted future-visit score for each role. No realized future workflow step is read during online policies.
 
-- top-1 transition accuracy before/after the shift;
-- prefetch precision and coverage;
-- wrong-immediate-next-step prefetch volume;
+`multistep` chooses up to `prefetch_top_k` roles from that ranking when their normalized score exceeds `forecast_min_score`. `utility` uses the same learned forecast but requires positive decision value above `utility_threshold_ms`.
+
+The reference utility for role `r` is:
+
+```text
+forecast_score(r) * avoided_static_prefix_prefill_ms(r)
+- host_transfer_ms(r)
+- forecast_weighted_eviction_recompute_ms
+```
+
+The eviction term estimates the opportunity cost of removing currently cached prefixes that the same forecast considers likely to be needed. This is a transparent heuristic objective, not a claim of globally optimal cache control.
+
+### Prediction calibration and action quality
+
+InferScale keeps prediction and action metrics separate. The transition model reports:
+
+- top-1 accuracy before/after the shift;
+- multiclass Brier score;
+- multiclass log loss;
+- top-1 expected calibration error (ECE).
+
+The serving policy reports:
+
+- forecast-set recall over the configured horizon;
+- immediate next-step prefetch precision;
+- eventual prefetch utilization (a prefetched prefix was actually consumed before eviction/end);
+- unused prefetch volume;
 - prefix hit rate and prefill tokens saved;
 - HBM GB-seconds and pressure evictions;
 - p95 step TTFT and workflow E2E.
 
-The oracle next-role candidate is a **clairvoyant upper bound on transition information**, not a guaranteed upper bound on serving performance. Even a perfect local next-step prediction can be globally suboptimal when a small shared cache is polluted or when transfer activity evicts a prefix needed by another queued workflow. This distinction is intentional and is why predictor quality and systems outcomes are shown together.
-
-### Confidence-threshold study
+This distinction matters because multi-step prefetch can be useful even when a prefetched role is not the immediate next step, while a highly accurate top-1 predictor can still make poor resource decisions.
 
-The threshold sweep holds the learned transition model and workload trace fixed while varying how confident the system must be before acting. Low thresholds increase prefetch coverage but can increase wrong-step traffic/cache pollution; high thresholds become conservative and may miss useful overlap opportunities. Correlations reported by the UI are descriptive summaries of that simulated sweep, not causal estimators.
+### Controlled studies
 
-### Forgetting-rate study
+The Confidence Threshold Study varies when one-step learned predictions are acted on. The Forgetting-Rate Study varies transition decay. The Prefetch Planning Study compares top-1, multi-step top-k, utility-aware multi-step, and a clairvoyant realized-future-set information bound. The Forecast Horizon Study varies rollout depth on a common trace. The Cache Budget Study runs top-1, multi-step, and utility-aware planners at multiple shared-prefix working-set budgets.
 
-The decay sweep holds the trace and confidence threshold fixed while changing how much historical transition evidence is retained. It reports the decay with highest post-shift accuracy separately from the decay with lowest p95 TTFT. These need not match because transfer timing, cache occupancy, and other workflows mediate the value of a correct prediction.
+Oracle next-role and oracle future-set candidates are **clairvoyant information bounds**, not guaranteed serving-performance upper bounds. Perfect future information may still produce poor global resource behavior when multiple workflows share a small cache and serialized transfer path.

docs/research.md

@@ -143,7 +143,7 @@ Source: https://arxiv.org/abs/2604.26968
 
 CacheScout argues that future KV reuse in multi-agent systems is governed by execution semantics rather than recency alone. It learns agent execution transitions online without requiring predefined workflow graphs or offline training, then uses the learned model for cache eviction and proactive prefetching.
 
-InferScale inspiration: the **Execution Learning** lab now implements a deliberately smaller first-order transition learner over synthetic agent roles. The model is updated only after a transition is observed; learned next-role predictions can trigger conservative static-prefix prefetch into a bounded HBM cache. InferScale does not reproduce CacheScout's vLLM integration, learned survival policy, or production critical-path design.
+InferScale inspiration: the **Execution Learning** lab implements a deliberately smaller online transition learner over synthetic agent roles. The model is updated only after a transition is observed; learned forecasts can drive one-step or multi-step static-prefix prefetch into a bounded HBM cache. InferScale also measures calibration and downstream action quality separately. It does not reproduce CacheScout's vLLM integration, survival policy, or production critical-path design.
 
 Source: https://arxiv.org/abs/2608.14624
 
@@ -151,7 +151,7 @@ Source: https://arxiv.org/abs/2608.14624
 
 PBKV predicts several future agent invocations in dynamic workflows and uses those predictions conservatively for cache retention and prefetching. Its motivation is particularly relevant when execution paths are input-dependent rather than a fixed workflow graph.
 
-InferScale inspiration: expose prediction confidence as a serving-policy knob rather than automatically acting on every top-1 guess. The Confidence Threshold Study measures how conservative prefetch changes coverage, precision, wasted transfer, cache hits, and TTFT on one common shifted trace. InferScale uses a transparent first-order transition baseline rather than PBKV's richer context-aware predictor.
+InferScale inspiration: PBKV's multi-step view motivates rolling the learned transition matrix forward rather than acting only on top-1 next-role guesses. InferScale adds a transparent top-k forecast and a reference utility rule that subtracts host-transfer and forecast-weighted eviction cost from expected prefill savings. Confidence, forecast-horizon, and cache-budget studies expose how conservative planning changes coverage, utilization, wasted transfer, HBM pressure, and TTFT. InferScale remains much simpler than PBKV's context-aware predictor and production cache manager.
 
 Source: https://arxiv.org/abs/2605.06472
 

index.html

@@ -548,11 +548,17 @@
           <hr />
           <div class="section-kicker">Prediction and prefetch</div>
           <div class="field-grid two">
-            <label>Prefetch policy<select id="execPolicy"><option value="none">No prefetch</option><option value="cumulative">Cumulative transitions</option><option value="decayed" selected>Decayed transitions</option><option value="oracle">Oracle next-role upper bound</option></select></label>
+            <label>Prefetch policy<select id="execPolicy"><option value="none">No prefetch</option><option value="cumulative">Cumulative transitions</option><option value="decayed" selected>Decayed top-1</option><option value="multistep">Multi-step top-k</option><option value="utility">Utility-aware multi-step</option><option value="oracle">Oracle next-role upper bound</option><option value="oracle_horizon">Oracle future-set upper bound</option></select></label>
             <label>Transition decay<input id="execDecay" type="number" min="0.2" max="1" step="0.05" value="0.85" /><span class="unit">fraction</span></label>
-            <label>Confidence threshold<input id="execThreshold" type="number" min="0" max="1" step="0.05" value="0.55" /><span class="unit">fraction</span></label>
+            <label>Confidence threshold<input id="execThreshold" type="number" min="0" max="1" step="0.05" value="0.55" /><span class="unit">top-1</span></label>
             <label>Host bandwidth<input id="execBandwidth" type="number" min="0.1" step="1" value="32" /><span class="unit">GB/s</span></label>
+            <label id="execHorizonLabel">Forecast horizon<input id="execHorizon" type="number" min="1" max="6" step="1" value="3" /><span class="unit">steps</span></label>
+            <label id="execTopKLabel">Prefetch top-k<input id="execTopK" type="number" min="1" max="5" step="1" value="2" /><span class="unit">roles</span></label>
+            <label id="execDiscountLabel">Forecast discount<input id="execDiscount" type="number" min="0.05" max="1" step="0.05" value="0.75" /><span class="unit">fraction</span></label>
+            <label id="execMinScoreLabel">Min forecast score<input id="execMinScore" type="number" min="0" max="1" step="0.05" value="0.10" /><span class="unit">normalized</span></label>
+            <label id="execUtilityLabel">Utility threshold<input id="execUtility" type="number" step="1" value="0" /><span class="unit">ms</span></label>
           </div>
+          <p class="muted tiny-note">Multi-step policies roll the learned transition matrix forward without reading the future trace. Utility-aware planning estimates saved prefill time minus host-transfer and forecast-weighted eviction cost.</p>
           <button id="execRunBtn" class="primary" disabled>Run execution-learning simulation</button>
           <div class="button-row"><button id="execRunCopyJson" class="secondary" disabled>Copy JSON</button><button id="execRunJson" class="secondary" disabled>Download JSON</button></div>
         </aside>
@@ -571,6 +577,10 @@
                 <div class="metric"><span>Prefetch precision</span><strong id="execPrecision">N/A</strong></div>
                 <div class="metric"><span>Prefetch coverage</span><strong id="execCoverage">N/A</strong></div>
                 <div class="metric"><span>Wrong-step prefetch</span><strong id="execWaste">N/A</strong></div>
+                <div class="metric"><span>Calibration ECE</span><strong id="execEce">N/A</strong></div>
+                <div class="metric"><span>Forecast recall</span><strong id="execForecastRecall">N/A</strong></div>
+                <div class="metric"><span>Prefetch utilization</span><strong id="execUtilization">N/A</strong></div>
+                <div class="metric"><span>Unused prefetch</span><strong id="execUnused">N/A</strong></div>
               </div>
               <div class="study-summary" id="execRunSummary"></div>
               <div class="chart-grid">
@@ -583,6 +593,10 @@
                   <div class="chart-body research-chart"><canvas id="execLearningChart"></canvas></div>
                 </div>
               </div>
+              <div class="chart-card full" data-chart-card data-chart-name="execution-transition-calibration">
+                <div class="chart-head"><div class="chart-title">Transition confidence reliability</div><div class="chart-actions"><button class="chart-download" type="button">Download PNG</button><button class="chart-expand" type="button">Expand</button></div></div>
+                <div class="chart-body research-chart"><canvas id="execCalibrationChart"></canvas></div>
+              </div>
             </div>
           </section>
 
@@ -636,6 +650,57 @@
               <div class="table-wrap"><table><thead><tr><th>Decay</th><th>Pre-shift top-1</th><th>Post-shift top-1</th><th>p95 TTFT</th><th>Prefix hit</th><th>Precision</th><th>Coverage</th><th>Wrong prefetch</th></tr></thead><tbody id="execDecayRows"></tbody></table></div>
             </div>
           </section>
+
+          <section class="panel research-panel">
+            <div class="panel-title-row"><div><div class="section-kicker">Multi-step decision quality</div><h2>Prefetch Planning Study</h2><p class="muted">Compare one-step prediction with multi-step forecasting, a utility-aware planner, and a clairvoyant future-set information bound on one common shifted workflow trace.</p></div><button id="execPlanningBtn" class="primary compact" disabled>Compare planning policies</button></div>
+            <div id="execPlanningEmpty" class="empty-state small"><h3>No planning study yet</h3><p>This experiment separates next-role accuracy from forecast-set recall, cache utilization, unused prefetch traffic, and actual serving latency.</p></div>
+            <div id="execPlanningContent" class="hidden">
+              <div class="metric-grid four">
+                <div class="metric emphasis"><span>Lowest p95 TTFT</span><strong id="execPlanningBestTtft">N/A</strong></div>
+                <div class="metric"><span>Best prefill / HBM</span><strong id="execPlanningBestEfficiency">N/A</strong></div>
+                <div class="metric"><span>Forecast horizon</span><strong id="execPlanningHorizon">N/A</strong></div>
+                <div class="metric"><span>Top-k</span><strong id="execPlanningTopK">N/A</strong></div>
+              </div>
+              <div class="chart-card full" data-chart-card data-chart-name="execution-planning-tradeoff">
+                <div class="chart-head"><div class="chart-title">Mean HBM residency vs p95 TTFT</div><div class="chart-actions"><button class="chart-download" type="button">Download PNG</button><button class="chart-expand" type="button">Expand</button></div></div>
+                <div class="chart-body research-chart"><canvas id="execPlanningChart"></canvas></div>
+              </div>
+              <div class="table-toolbar"><span>Common-trace planning results</span><div><button id="execPlanningCopy" class="mini-button" disabled>Copy table</button><button id="execPlanningCsv" class="mini-button" disabled>Download CSV</button><button id="execPlanningJson" class="mini-button" disabled>Download JSON</button></div></div>
+              <div class="table-wrap"><table><thead><tr><th>Policy</th><th>p95 TTFT</th><th>Forecast recall</th><th>Prefix hit</th><th>Utilization</th><th>Next-step precision</th><th>Mean HBM</th><th>Unused prefetch</th><th>Saved prefill</th><th>ECE</th></tr></thead><tbody id="execPlanningRows"></tbody></table></div>
+            </div>
+          </section>
+
+          <section class="panel research-panel">
+            <div class="panel-title-row"><div><div class="section-kicker">How far ahead?</div><h2>Forecast Horizon Study</h2><p class="muted">Sweep a utility-aware planner from one-step prediction to longer rollout horizons. Longer forecasts can reveal reuse but can also waste bandwidth or evict nearer-term prefixes.</p></div><button id="execHorizonBtn" class="primary compact" disabled>Sweep forecast horizon</button></div>
+            <div id="execHorizonEmpty" class="empty-state small"><h3>No horizon sweep yet</h3><p>Each horizon replays the exact same shifted workflow trace and uses the same cache budget and learned transition model.</p></div>
+            <div id="execHorizonContent" class="hidden">
+              <div class="metric-grid four">
+                <div class="metric emphasis"><span>Best TTFT horizon</span><strong id="execHorizonBestTtft">N/A</strong></div>
+                <div class="metric"><span>Best utilization horizon</span><strong id="execHorizonBestUtil">N/A</strong></div>
+                <div class="metric"><span>Configured top-k</span><strong id="execHorizonTopK">N/A</strong></div>
+                <div class="metric"><span>Cache budget</span><strong id="execHorizonBudget">N/A</strong></div>
+              </div>
+              <div class="chart-card full" data-chart-card data-chart-name="execution-forecast-horizon">
+                <div class="chart-head"><div class="chart-title">Forecast horizon vs latency and prefetch utilization</div><div class="chart-actions"><button class="chart-download" type="button">Download PNG</button><button class="chart-expand" type="button">Expand</button></div></div>
+                <div class="chart-body research-chart"><canvas id="execHorizonChart"></canvas></div>
+              </div>
+              <div class="table-toolbar"><span>Horizon sweep</span><div><button id="execHorizonCopy" class="mini-button" disabled>Copy table</button><button id="execHorizonCsv" class="mini-button" disabled>Download CSV</button><button id="execHorizonJson" class="mini-button" disabled>Download JSON</button></div></div>
+              <div class="table-wrap"><table><thead><tr><th>Horizon</th><th>p95 TTFT</th><th>Forecast recall</th><th>Prefix hit</th><th>Utilization</th><th>Unused prefetch</th><th>Mean HBM</th><th>Saved prefill</th></tr></thead><tbody id="execHorizonRows"></tbody></table></div>
+            </div>
+          </section>
+
+          <section class="panel research-panel">
+            <div class="panel-title-row"><div><div class="section-kicker">Scarce-cache regime</div><h2>Cache Budget Study</h2><p class="muted">Compare top-1, multi-step, and utility-aware planning while shrinking or expanding the shared prefix-cache budget. The useful policy can change when speculative prefixes compete for HBM.</p></div><button id="execBudgetBtn" class="primary compact" disabled>Sweep cache budget</button></div>
+            <div id="execBudgetEmpty" class="empty-state small"><h3>No cache-budget sweep yet</h3><p>The study executes 12 controlled simulations: three planning policies across four working-set-relative HBM budgets.</p></div>
+            <div id="execBudgetContent" class="hidden">
+              <div class="chart-card full" data-chart-card data-chart-name="execution-cache-budget-policy">
+                <div class="chart-head"><div class="chart-title">Cache budget vs p95 TTFT by planning policy</div><div class="chart-actions"><button class="chart-download" type="button">Download PNG</button><button class="chart-expand" type="button">Expand</button></div></div>
+                <div class="chart-body research-chart"><canvas id="execBudgetChart"></canvas></div>
+              </div>
+              <div class="table-toolbar"><span>Cache-budget policy sweep</span><div><button id="execBudgetCopy" class="mini-button" disabled>Copy table</button><button id="execBudgetCsv" class="mini-button" disabled>Download CSV</button><button id="execBudgetJson" class="mini-button" disabled>Download JSON</button></div></div>
+              <div class="table-wrap"><table><thead><tr><th>Budget</th><th>Policy</th><th>p95 TTFT</th><th>Forecast recall</th><th>Prefix hit</th><th>Utilization</th><th>Mean HBM</th><th>Unused prefetch</th><th>Pressure evictions</th></tr></thead><tbody id="execBudgetRows"></tbody></table></div>
+            </div>
+          </section>
         </div>
       </div>
     </section>
@@ -647,11 +712,11 @@
         <article class="panel prose"><div class="section-kicker">P/D disaggregation</div><h2>Role-specific resources and transfer cost</h2><p>Prefill and decode have separate accelerator profiles and worker counts. Prompt KV state crosses a modeled interconnect before decode admission. The simulator reports role utilization, transfer latency, and transfer pressure so the benefit of isolation can be weighed against data-movement overhead.</p></article>
         <article class="panel prose"><div class="section-kicker">Stateful agent sessions</div><h2>Tool gaps turn KV into a residency and routing decision</h2><p>Agent Sessions preserves program identity and turn order, materializes tool-induced gaps, and tracks HBM retention, TTL expiry, host-memory offload/restore, recomputation, and pressure eviction. Strict affinity, least-load, and bounded-affinity routing expose the tension between cache locality and hot-replica queueing. The per-replica service model remains intentionally serial so state-management effects are not confounded with dynamic batching.</p></article>
         <article class="panel prose"><div class="section-kicker">Online adaptive tiering</div><h2>Prediction without future-gap leakage</h2><p>Adaptive tiering learns an exponentially weighted estimate from tool calls only after they complete. Global and per-tool predictors can be evaluated on the same non-stationary program trace, while an oracle policy that sees the realized future gap is kept separate as an upper bound. A shift experiment changes slower external-tool durations mid-trace to expose the stability-versus-adaptation trade-off.</p></article>
-        <article class="panel prose"><div class="section-kicker">Execution learning</div><h2>Learn workflow transitions, then prefetch conservatively</h2><p>Execution Learning maintains a first-order transition model over agent roles and only updates it after the next role is observed. Static role prefixes share a bounded HBM cache. Learned next-role predictions can trigger host-to-HBM prefetch during tool gaps, while confidence and forgetting sweeps expose the difference between prediction quality and downstream serving quality.</p></article>
+        <article class="panel prose"><div class="section-kicker">Execution learning</div><h2>Learn transitions, forecast multiple steps, then spend cache carefully</h2><p>Execution Learning updates a first-order role-transition model only after the next role is observed. The learned matrix can be rolled forward for multi-step forecasts without future-trace access. A utility-aware planner weighs expected prefill savings against host-transfer cost and forecast-weighted eviction cost, while calibration, horizon, confidence, forgetting, and cache-budget studies expose where better predictions do or do not improve serving outcomes.</p></article>
         <article class="panel prose"><div class="section-kicker">Design search</div><h2>Pareto, not one magic configuration</h2><p>The Design Explorer reports both a raw-performance frontier and a resource-normalized frontier using goodput per accelerator. That prevents a multi-GPU P/D layout from looking unconditionally better merely because it uses more simulated hardware.</p></article>
         <article class="panel prose"><div class="section-kicker">Trace methodology</div><h2>Generated load or exact replay</h2><p>Poisson, constant, and bursty workloads are open-loop: arrivals are scheduled independently of response completion, so queueing delay is not hidden by client backpressure. Exact CSV/JSON traces can be replayed with their original arrival times and token lengths.</p></article>
         <article class="panel prose"><div class="section-kicker">Research protocol</div><h2>Paired conclusions, not one lucky seed</h2><p>Research Studies use common random numbers: baseline and treatment receive identical seeds, reducing workload variance in the paired difference. A bootstrap interval summarizes the repeated effect, while a separate sensitivity study perturbs analytical latency scales to reveal conclusions that depend too strongly on one reference profile.</p></article>
-        <article class="panel prose wide-method"><div class="section-kicker">Research lineage</div><h2>Research lineage and scope</h2><p>Vidur established the value of simulation for avoiding expensive deployment sweeps. Recent systems have pushed toward heterogeneous and disaggregated serving, communication-aware modeling, stateful workloads, trace replay, and SLA-dependent design-space exploration. InferScale-Sim remains intentionally smaller and inspectable, with paired experiments and sensitivity analysis built into the workflow.</p><div class="paper-grid"><div><strong>Vidur / 2024</strong><span>Predictive profiling, workload-aware serving simulation, configuration search.</span></div><div><strong>TokenSim / 2025</strong><span>Extensible scheduling and memory-management simulation.</span></div><div><strong>Revati / 2026</strong><span>GPU-free time-warp emulation of serving control logic.</span></div><div><strong>LLMServingSim 2.0 / 2026</strong><span>Heterogeneous and disaggregated infrastructure, memory and communication.</span></div><div><strong>Frontier / May 2026</strong><span>P/D disaggregation, runtime optimizations, stateful workloads, Pareto exploration.</span></div><div><strong>HeteroPanacea / Aug 2026</strong><span>Heterogeneous stage specialization motivates resource-aware P/D comparison.</span></div><div><strong>Vanguard / Jun 2026</strong><span>Open-loop replay avoids coordinated omission when studying latency under load.</span></div><div><strong>AgentServeSim / Jun 2026</strong><span>Stateful multi-turn serving motivates session-aware workload modeling.</span></div><div><strong>IdleKV / Jun 2026</strong><span>Tool-call idle windows motivate explicit HBM-to-host KV offload experiments.</span></div><div><strong>SMetric / Jul 2026</strong><span>Cache-local routing can overload hot replicas, motivating bounded affinity.</span></div><div><strong>Continuum / May 2026</strong><span>Per-tool duration history and bounded TTL motivate adaptive retention without clairvoyance.</span></div><div><strong>CacheScout / Jul 2026</strong><span>Online learning of agent execution transitions and between-step prefetch motivates the Execution Learning experiments.</span></div><div><strong>PBKV / May 2026</strong><span>Prediction-based KV management for dynamic agent workflows motivates conservative prefetch under imperfect future-step predictions.</span></div><div><strong>Predictive KV Memory / Aug 2026 rev.</strong><span>Bayesian reuse prediction and multi-tier placement motivate explicit prediction-quality experiments.</span></div><div><strong>SGLang / RadixAttention</strong><span>Automatic shared-prefix KV reuse motivates the controlled cache scenario.</span></div></div></article>
+        <article class="panel prose wide-method"><div class="section-kicker">Research lineage</div><h2>Research lineage and scope</h2><p>Vidur established the value of simulation for avoiding expensive deployment sweeps. Recent systems have pushed toward heterogeneous and disaggregated serving, communication-aware modeling, stateful workloads, trace replay, and SLA-dependent design-space exploration. InferScale-Sim remains intentionally smaller and inspectable, with paired experiments and sensitivity analysis built into the workflow.</p><div class="paper-grid"><div><strong>Vidur / 2024</strong><span>Predictive profiling, workload-aware serving simulation, configuration search.</span></div><div><strong>TokenSim / 2025</strong><span>Extensible scheduling and memory-management simulation.</span></div><div><strong>Revati / 2026</strong><span>GPU-free time-warp emulation of serving control logic.</span></div><div><strong>LLMServingSim 2.0 / 2026</strong><span>Heterogeneous and disaggregated infrastructure, memory and communication.</span></div><div><strong>Frontier / May 2026</strong><span>P/D disaggregation, runtime optimizations, stateful workloads, Pareto exploration.</span></div><div><strong>HeteroPanacea / Aug 2026</strong><span>Heterogeneous stage specialization motivates resource-aware P/D comparison.</span></div><div><strong>Vanguard / Jun 2026</strong><span>Open-loop replay avoids coordinated omission when studying latency under load.</span></div><div><strong>AgentServeSim / Jun 2026</strong><span>Stateful multi-turn serving motivates session-aware workload modeling.</span></div><div><strong>IdleKV / Jun 2026</strong><span>Tool-call idle windows motivate explicit HBM-to-host KV offload experiments.</span></div><div><strong>SMetric / Jul 2026</strong><span>Cache-local routing can overload hot replicas, motivating bounded affinity.</span></div><div><strong>Continuum / May 2026</strong><span>Per-tool duration history and bounded TTL motivate adaptive retention without clairvoyance.</span></div><div><strong>CacheScout / Jul 2026</strong><span>Online learning of agent execution transitions and between-step prefetch motivates the Execution Learning experiments.</span></div><div><strong>PBKV / May 2026</strong><span>Multi-step prediction for dynamic workflows motivates forecast-horizon and utility-aware prefetch experiments.</span></div><div><strong>Predictive KV Memory / Aug 2026 rev.</strong><span>Bayesian reuse prediction and multi-tier placement motivate explicit prediction-quality experiments.</span></div><div><strong>SGLang / RadixAttention</strong><span>Automatic shared-prefix KV reuse motivates the controlled cache scenario.</span></div></div></article>
       </div>
     </section>
   </main>

py/inferscale/__init__.py

@@ -9,7 +9,15 @@ from .agentic import (
     ttl_retention_sweep,
 )
 from .api import execute, metadata
-from .execution import execution_decay_sweep, execution_prefetch_study, execution_threshold_sweep, run_execution_learning
+from .execution import (
+    execution_budget_sweep,
+    execution_decay_sweep,
+    execution_horizon_sweep,
+    execution_planning_study,
+    execution_prefetch_study,
+    execution_threshold_sweep,
+    run_execution_learning,
+)
 from .models import SimulationConfig
 from .optimizer import capacity_search, compare_schedulers, compare_topologies, design_space_search
 from .research import paired_study, robustness_study
@@ -29,7 +37,10 @@ __all__ = [
     "compare_topologies",
     "design_space_search",
     "execute",
+    "execution_budget_sweep",
     "execution_decay_sweep",
+    "execution_horizon_sweep",
+    "execution_planning_study",
     "execution_prefetch_study",
     "execution_threshold_sweep",
     "metadata",
@@ -44,4 +55,4 @@ __all__ = [
 
 # Internal package metadata only; the public project intentionally avoids
 # release/version branding in the interface and documentation.
-__version__ = "0.8.0"
+__version__ = "0.9.0"

py/inferscale/api.py

@@ -11,7 +11,10 @@ from .agentic import (
     ttl_retention_sweep,
 )
 from .execution import (
+    execution_budget_sweep,
     execution_decay_sweep,
+    execution_horizon_sweep,
+    execution_planning_study,
     execution_prefetch_study,
     execution_threshold_sweep,
     run_execution_learning,
@@ -37,6 +40,7 @@ def metadata() -> dict:
         ],
         "execution_learning_modes": [
             "single_run", "prefetch_policy_compare", "confidence_threshold_sweep", "transition_decay_sweep",
+            "multistep_planning", "forecast_horizon_sweep", "cache_budget_policy_sweep",
         ],
     }
 
@@ -107,6 +111,12 @@ def execute(action: str, payload: dict) -> dict:
         return execution_threshold_sweep(payload.get("config", payload), payload.get("thresholds"))
     if action == "execution_decay_sweep":
         return execution_decay_sweep(payload.get("config", payload), payload.get("decay_values"))
+    if action == "execution_planning_study":
+        return execution_planning_study(payload.get("config", payload))
+    if action == "execution_horizon_sweep":
+        return execution_horizon_sweep(payload.get("config", payload), payload.get("horizon_values"))
+    if action == "execution_budget_sweep":
+        return execution_budget_sweep(payload.get("config", payload), payload.get("budget_values"))
     if action == "robustness_study":
         config = payload.get("config", payload)
         return robustness_study(

py/inferscale/execution.py

@@ -48,7 +48,7 @@ ROLE_GAP_MULTIPLIERS = {
     "writer": 0.30,
 }
 
-PREFETCH_POLICIES = {"none", "cumulative", "decayed", "oracle"}
+PREFETCH_POLICIES = {"none", "cumulative", "decayed", "multistep", "utility", "oracle", "oracle_horizon"}
 
 
 @dataclass
@@ -74,6 +74,11 @@ class ExecutionLearningConfig:
     transition_decay: float = 0.85
     confidence_threshold: float = 0.55
     prior_strength: float = 0.35
+    forecast_horizon: int = 3
+    prefetch_top_k: int = 2
+    forecast_discount: float = 0.75
+    forecast_min_score: float = 0.10
+    utility_threshold_ms: float = 0.0
     timeline_points: int = 240
 
     @classmethod
@@ -90,6 +95,11 @@ class ExecutionLearningConfig:
         cfg.transition_decay = min(max(float(cfg.transition_decay), 0.20), 1.0)
         cfg.confidence_threshold = min(max(float(cfg.confidence_threshold), 0.0), 1.0)
         cfg.prior_strength = max(float(cfg.prior_strength), 0.01)
+        cfg.forecast_horizon = max(1, min(int(cfg.forecast_horizon), 6))
+        cfg.prefetch_top_k = max(1, min(int(cfg.prefetch_top_k), len(AGENT_ROLES)))
+        cfg.forecast_discount = min(max(float(cfg.forecast_discount), 0.05), 1.0)
+        cfg.forecast_min_score = min(max(float(cfg.forecast_min_score), 0.0), 1.0)
+        cfg.utility_threshold_ms = float(cfg.utility_threshold_ms)
         cfg.timeline_points = max(40, min(int(cfg.timeline_points), 1000))
         if cfg.prefetch_policy not in PREFETCH_POLICIES:
             raise ValueError(f"Unsupported execution prefetch policy: {cfg.prefetch_policy}")
@@ -123,6 +133,7 @@ class PrefixEntry:
     available_time: float
     source: str
     generation: int
+    used: bool = False
 
 
 class OnlineTransitionPredictor:
@@ -150,6 +161,59 @@ class OnlineTransitionPredictor:
         best = max(self.targets, key=lambda target: (probabilities[target], -self.targets.index(target)))
         return best, probabilities[best], probabilities
 
+    def forecast(
+        self,
+        current_role: str,
+        *,
+        horizon: int = 3,
+        discount: float = 0.75,
+    ) -> dict[str, Any]:
+        """Roll the learned first-order matrix forward without future trace access.
+
+        ``role_scores`` are discounted expected future visits, not calibrated
+        probabilities of at-least-one reuse. They are therefore used as a
+        ranking signal and are normalized separately for UI/decision thresholds.
+        """
+
+        horizon = max(1, min(int(horizon), 8))
+        discount = min(max(float(discount), 0.0), 1.0)
+        distributions: list[dict[str, float]] = []
+        current: dict[str, float] = {target: 0.0 for target in self.targets}
+        current[current_role] = 1.0
+        role_scores = {role: 0.0 for role in AGENT_ROLES}
+
+        for depth in range(1, horizon + 1):
+            nxt = {target: 0.0 for target in self.targets}
+            for source, mass in current.items():
+                if mass <= 0.0:
+                    continue
+                if source == END:
+                    nxt[END] += mass
+                    continue
+                _, _, probs = self.predict(source)
+                for target, probability in probs.items():
+                    nxt[target] += mass * probability
+            distributions.append(nxt)
+            weight = discount ** (depth - 1)
+            for role in AGENT_ROLES:
+                role_scores[role] += weight * nxt.get(role, 0.0)
+            current = nxt
+
+        total_score = sum(role_scores.values())
+        normalized = {
+            role: (score / total_score if total_score > 1e-12 else 0.0)
+            for role, score in role_scores.items()
+        }
+        ranked = sorted(AGENT_ROLES, key=lambda role: (-role_scores[role], role))
+        return {
+            "horizon": horizon,
+            "discount": discount,
+            "distributions": distributions,
+            "role_scores": role_scores,
+            "normalized_scores": normalized,
+            "ranked_roles": ranked,
+        }
+
     def observe(self, current_role: str, next_role: str) -> None:
         row = self.rows[current_role]
         if self.decay < 1.0:
@@ -225,6 +289,50 @@ def generate_workflows(cfg: ExecutionLearningConfig) -> list[WorkflowSpec]:
     return workflows
 
 
+def _prediction_calibration(rows: list[dict[str, Any]], bins: int = 10) -> dict[str, Any]:
+    if not rows:
+        return {"count": 0, "brier": 0.0, "log_loss": 0.0, "ece": 0.0, "bins": []}
+    targets = (*AGENT_ROLES, END)
+    brier_total = 0.0
+    log_total = 0.0
+    buckets: list[list[tuple[float, float]]] = [[] for _ in range(max(2, bins))]
+    for row in rows:
+        probs = row.get("probabilities", {})
+        actual = str(row.get("actual_next_role", END))
+        brier_total += sum((float(probs.get(target, 0.0)) - (1.0 if target == actual else 0.0)) ** 2 for target in targets)
+        actual_p = max(float(probs.get(actual, 0.0)), 1e-12)
+        log_total += -math.log(actual_p)
+        confidence = min(max(float(row.get("confidence", 0.0)), 0.0), 1.0)
+        correct = 1.0 if row.get("prediction_correct") else 0.0
+        index = min(int(confidence * len(buckets)), len(buckets) - 1)
+        buckets[index].append((confidence, correct))
+    ece = 0.0
+    rendered = []
+    for index, bucket in enumerate(buckets):
+        if not bucket:
+            continue
+        avg_conf = mean(value[0] for value in bucket)
+        accuracy = mean(value[1] for value in bucket)
+        weight = len(bucket) / len(rows)
+        ece += weight * abs(avg_conf - accuracy)
+        rendered.append(
+            {
+                "lower": index / len(buckets),
+                "upper": (index + 1) / len(buckets),
+                "count": len(bucket),
+                "mean_confidence": avg_conf,
+                "accuracy": accuracy,
+            }
+        )
+    return {
+        "count": len(rows),
+        "brier": brier_total / len(rows),
+        "log_loss": log_total / len(rows),
+        "ece": ece,
+        "bins": rendered,
+    }
+
+
 class ExecutionLearningSimulator:
     """Reference simulator for online workflow learning and prefix prefetch.
 
@@ -260,7 +368,10 @@ class ExecutionLearningSimulator:
         self.pressure_evictions = 0
         self.prefetch_attempts = 0
         self.prefetch_correct = 0
+        self.prefetch_useful = 0
         self.prefetch_bytes = 0.0
+        self.prefetch_useful_bytes = 0.0
+        self.unused_prefetch_bytes = 0.0
         self.wrong_step_prefetch_bytes = 0.0
         self.transfer_latencies_ms: list[float] = []
         self.prefix_hits = 0
@@ -308,6 +419,40 @@ class ExecutionLearningSimulator:
         if len(self.timeline) > self.cfg.timeline_points * 2:
             self.timeline = self.timeline[::2]
 
+    def _mark_unused_prefetch(self, entry: PrefixEntry) -> None:
+        if entry.source == "prefetch" and not entry.used:
+            self.unused_prefetch_bytes += entry.size_gb * 1e9
+
+    def _candidate_eviction_cost_ms(self, role: str, forecast_scores: dict[str, float]) -> float:
+        """Approximate downstream cost of evicting forecast-relevant cached prefixes."""
+        size_gb = self.role_size_gb[role]
+        existing = self.cache.get(role)
+        current_without = self._used_gb() - (existing.size_gb if existing else 0.0)
+        overflow = max(0.0, current_without + size_gb - self.cache_capacity_gb)
+        if overflow <= 1e-12:
+            return 0.0
+        cost_ms = 0.0
+        reclaimed = 0.0
+        candidates = sorted(
+            [entry for key, entry in self.cache.items() if key != role],
+            key=lambda entry: (entry.last_access, entry.role),
+        )
+        for victim in candidates:
+            if reclaimed >= overflow - 1e-12:
+                break
+            reuse_score = max(float(forecast_scores.get(victim.role, 0.0)), 0.0)
+            recompute_ms = self.latency.prefill_seconds([ROLE_PREFIX_TOKENS[victim.role]]) * 1000.0
+            cost_ms += reuse_score * recompute_ms
+            reclaimed += victim.size_gb
+        return cost_ms
+
+    def _prefetch_utility_ms(self, role: str, forecast_scores: dict[str, float]) -> float:
+        score = max(float(forecast_scores.get(role, 0.0)), 0.0)
+        saved_ms = self.latency.prefill_seconds([ROLE_PREFIX_TOKENS[role]]) * 1000.0
+        transfer_ms = self.cfg.transfer_base_ms + self.role_size_gb[role] / self.cfg.host_bandwidth_gbps * 1000.0
+        eviction_ms = self._candidate_eviction_cost_ms(role, forecast_scores)
+        return score * saved_ms - transfer_ms - eviction_ms
+
     def _evict_for(self, role: str, size_gb: float) -> bool:
         existing = self.cache.get(role)
         current_without_role = self._used_gb() - (existing.size_gb if existing else 0.0)
@@ -319,6 +464,7 @@ class ExecutionLearningSimulator:
                 return False
             victim = min(candidates, key=lambda entry: (entry.last_access, entry.role))
             self._integrate_memory(self.now)
+            self._mark_unused_prefetch(victim)
             self.cache.pop(victim.role, None)
             self.prefix_source.pop(victim.role, None)
             self.pressure_evictions += 1
@@ -331,6 +477,8 @@ class ExecutionLearningSimulator:
             return None
         self._integrate_memory(self.now)
         previous = self.cache.get(role)
+        if previous is not None:
+            self._mark_unused_prefetch(previous)
         generation = (previous.generation + 1) if previous else 1
         self.cache[role] = PrefixEntry(role, size_gb, self.now, available_time, source, generation)
         self.prefix_source[role] = source
@@ -362,35 +510,103 @@ class ExecutionLearningSimulator:
             return END
         return workflow.steps[step_index + 1].role
 
-    def _schedule_prediction(self, workflow_id: int, step_index: int, current_role: str) -> None:
+    def _actual_future_roles(self, workflow_id: int, step_index: int, horizon: int) -> list[str]:
+        workflow = self.workflows[workflow_id]
+        roles = [step.role for step in workflow.steps[step_index + 1 : step_index + 1 + max(1, horizon)]]
+        return roles
+
+    def _planned_prefetch_roles(
+        self,
+        workflow_id: int,
+        step_index: int,
+        current_role: str,
+    ) -> tuple[str, float, dict[str, float], dict[str, Any], list[dict[str, Any]]]:
         actual_next = self._actual_next_role(workflow_id, step_index)
-        predicted_role = END
-        confidence = 1.0
-        probabilities: dict[str, float] = {target: 0.0 for target in (*AGENT_ROLES, END)}
-        attempted = False
-        decision_reason = "disabled"
+        predicted_role, confidence, probabilities = self.predictor.predict(current_role)
+        forecast = self.predictor.forecast(
+            current_role,
+            horizon=self.cfg.forecast_horizon,
+            discount=self.cfg.forecast_discount,
+        )
+        plans: list[dict[str, Any]] = []
+
         if self.cfg.prefetch_policy == "oracle":
             predicted_role = actual_next
             confidence = 1.0
+            probabilities = {target: 0.0 for target in (*AGENT_ROLES, END)}
             probabilities[predicted_role] = 1.0
-        elif self.cfg.prefetch_policy in {"cumulative", "decayed"}:
-            predicted_role, confidence, probabilities = self.predictor.predict(current_role)
-        elif self.cfg.prefetch_policy == "none":
-            # Learn-only control: the transition model still makes a prediction,
-            # but the serving policy never acts on it. This separates the value
-            # of prediction from the value (and cost) of prefetch.
-            predicted_role, confidence, probabilities = self.predictor.predict(current_role)
-
-        prefetch_result: dict[str, Any] = {"attempted": False, "reason": "no_prefetch", "role": predicted_role}
-        if self.cfg.prefetch_policy != "none" and predicted_role != END:
-            if confidence >= self.cfg.confidence_threshold or self.cfg.prefetch_policy == "oracle":
-                prefetch_result = self._prefetch(predicted_role)
-                attempted = bool(prefetch_result.get("attempted"))
-                decision_reason = str(prefetch_result.get("reason", "scheduled"))
-            else:
-                decision_reason = "below_threshold"
-        elif predicted_role == END:
-            decision_reason = "predict_end"
+            if actual_next != END:
+                plans = [{"role": actual_next, "score": 1.0, "utility_ms": None, "oracle": True}]
+            return predicted_role, confidence, probabilities, forecast, plans
+
+        if self.cfg.prefetch_policy == "oracle_horizon":
+            actual_future = self._actual_future_roles(workflow_id, step_index, self.cfg.forecast_horizon)
+            predicted_role = actual_next
+            confidence = 1.0
+            probabilities = {target: 0.0 for target in (*AGENT_ROLES, END)}
+            probabilities[predicted_role] = 1.0
+            seen: set[str] = set()
+            for role in actual_future:
+                if role not in seen:
+                    plans.append({"role": role, "score": 1.0, "utility_ms": None, "oracle": True})
+                    seen.add(role)
+                if len(plans) >= self.cfg.prefetch_top_k:
+                    break
+            return predicted_role, confidence, probabilities, forecast, plans
+
+        if self.cfg.prefetch_policy in {"none", "cumulative", "decayed"}:
+            if self.cfg.prefetch_policy != "none" and predicted_role != END and confidence >= self.cfg.confidence_threshold:
+                plans = [{"role": predicted_role, "score": confidence, "utility_ms": None, "oracle": False}]
+            return predicted_role, confidence, probabilities, forecast, plans
+
+        ranked = forecast["ranked_roles"]
+        normalized = forecast["normalized_scores"]
+        raw_scores = forecast["role_scores"]
+        for role in ranked:
+            if len(plans) >= self.cfg.prefetch_top_k:
+                break
+            normalized_score = float(normalized.get(role, 0.0))
+            if normalized_score < self.cfg.forecast_min_score:
+                continue
+            utility_ms = self._prefetch_utility_ms(role, raw_scores)
+            if self.cfg.prefetch_policy == "utility" and utility_ms < self.cfg.utility_threshold_ms:
+                continue
+            plans.append(
+                {
+                    "role": role,
+                    "score": normalized_score,
+                    "raw_score": float(raw_scores.get(role, 0.0)),
+                    "utility_ms": utility_ms,
+                    "oracle": False,
+                }
+            )
+        return predicted_role, confidence, probabilities, forecast, plans
+
+    def _schedule_prediction(self, workflow_id: int, step_index: int, current_role: str) -> None:
+        actual_next = self._actual_next_role(workflow_id, step_index)
+        predicted_role, confidence, probabilities, forecast, plans = self._planned_prefetch_roles(
+            workflow_id, step_index, current_role
+        )
+        attempted_roles: list[str] = []
+        attempt_sizes: dict[str, float] = {}
+        attempt_reasons: dict[str, str] = {}
+
+        for plan in plans:
+            role = str(plan["role"])
+            result = self._prefetch(role)
+            attempt_reasons[role] = str(result.get("reason", "unknown"))
+            if result.get("attempted"):
+                attempted_roles.append(role)
+                attempt_sizes[role] = float(result.get("size_gb", 0.0))
+
+        if self.cfg.prefetch_policy == "none":
+            decision_reason = "learn_only"
+        elif not plans:
+            decision_reason = "no_candidate"
+        elif attempted_roles:
+            decision_reason = "scheduled"
+        else:
+            decision_reason = ",".join(sorted(set(attempt_reasons.values()))) or "not_scheduled"
 
         self.pending_predictions[(workflow_id, step_index)] = {
             "workflow_id": workflow_id,
@@ -399,14 +615,21 @@ class ExecutionLearningSimulator:
             "predicted_role": predicted_role,
             "confidence": confidence,
             "probabilities": probabilities,
-            "prefetch_attempted": attempted,
+            "forecast_horizon": self.cfg.forecast_horizon,
+            "forecast_discount": self.cfg.forecast_discount,
+            "forecast_role_scores": forecast["role_scores"],
+            "forecast_normalized_scores": forecast["normalized_scores"],
+            "forecast_roles": [str(plan["role"]) for plan in plans],
+            "forecast_plans": plans,
+            "prefetch_attempted": bool(attempted_roles),
+            "prefetch_roles": attempted_roles,
+            "prefetch_reasons": attempt_reasons,
             "prefetch_reason": decision_reason,
-            "prefetch_size_gb": float(prefetch_result.get("size_gb", 0.0)),
+            "prefetch_sizes_gb": attempt_sizes,
+            "prefetch_size_gb": sum(attempt_sizes.values()),
             "shifted_regime": self.workflows[workflow_id].steps[step_index].shifted_regime,
         }
 
-        # END is observable immediately at workflow completion. Non-final
-        # transitions become observable only after the tool gap has elapsed.
         if actual_next == END:
             self._observe_transition(workflow_id, step_index, actual_next)
 
@@ -418,22 +641,38 @@ class ExecutionLearningSimulator:
         if pending is None:
             return
         predicted_role = str(pending["predicted_role"])
-        attempted = bool(pending["prefetch_attempted"])
+        attempted_roles = [str(role) for role in pending.get("prefetch_roles", [])]
         correct = predicted_role == actual_next
-        if attempted and correct and actual_next != END:
+        if actual_next != END and actual_next in attempted_roles:
             self.prefetch_correct += 1
-        if attempted and not correct:
-            self.wrong_step_prefetch_bytes += float(pending.get("prefetch_size_gb", 0.0)) * 1e9
+        immediate_wrong_bytes = 0.0
+        for role in attempted_roles:
+            if role != actual_next:
+                immediate_wrong_bytes += float(pending.get("prefetch_sizes_gb", {}).get(role, 0.0)) * 1e9
+        self.wrong_step_prefetch_bytes += immediate_wrong_bytes
+
+        future_roles = self._actual_future_roles(workflow_id, step_index, int(pending.get("forecast_horizon", 1)))
+        actual_future_set = set(future_roles)
+        forecast_roles = [str(role) for role in pending.get("forecast_roles", [])]
+        forecast_set = set(forecast_roles)
+        forecast_recall = (
+            len(actual_future_set & forecast_set) / len(actual_future_set)
+            if actual_future_set
+            else None
+        )
         self.prediction_rows.append(
             pending
             | {
                 "actual_next_role": actual_next,
+                "actual_future_roles": future_roles,
                 "prediction_correct": correct,
+                "forecast_next_hit": actual_next in forecast_set if actual_next != END else predicted_role == END,
+                "forecast_recall": forecast_recall,
+                "immediate_wrong_prefetch_gb": immediate_wrong_bytes / 1e9,
                 "post_shift": bool(pending["shifted_regime"]),
             }
         )
-        # Oracle is kept as an upper-bound candidate; it is not an online learner.
-        if self.cfg.prefetch_policy != "oracle":
+        if self.cfg.prefetch_policy not in {"oracle", "oracle_horizon"}:
             self.predictor.observe(current_role, actual_next)
 
     def _start_next(self) -> None:
@@ -470,6 +709,10 @@ class ExecutionLearningSimulator:
                 self.prefetch_hits += 1
             self.prefill_tokens_saved += prefix_tokens
             if entry is not None:
+                if entry.source == "prefetch" and not entry.used:
+                    entry.used = True
+                    self.prefetch_useful += 1
+                    self.prefetch_useful_bytes += entry.size_gb * 1e9
                 entry.last_access = self.now + prefix_wait_s
             prefill_tokens = max(step.dynamic_prompt_tokens, 1)
         else:
@@ -590,8 +833,19 @@ class ExecutionLearningSimulator:
         def accuracy(rows: list[dict[str, Any]]) -> float:
             return sum(1 for row in rows if row["prediction_correct"]) / len(rows) if rows else 0.0
 
+        # Account for prefetched entries that remained unused through the end of the run.
+        for entry in list(self.cache.values()):
+            self._mark_unused_prefetch(entry)
         prefetch_precision = self.prefetch_correct / self.prefetch_attempts if self.prefetch_attempts else 0.0
-        prefetch_coverage = self.prefetch_attempts / len(predictions) if predictions else 0.0
+        prefetch_coverage = (
+            sum(1 for row in predictions if row.get("prefetch_attempted")) / len(predictions)
+            if predictions else 0.0
+        )
+        prefetch_utilization = self.prefetch_useful / self.prefetch_attempts if self.prefetch_attempts else 0.0
+        forecast_recall_values = [
+            float(row["forecast_recall"]) for row in predictions if row.get("forecast_recall") is not None
+        ]
+        forecast_recall = mean(forecast_recall_values) if forecast_recall_values else 0.0
         workflow_count = len(self.workflows)
         completed_count = len(self.workflow_completion)
         summary = {
@@ -615,7 +869,12 @@ class ExecutionLearningSimulator:
             "prefetch_correct": self.prefetch_correct,
             "prefetch_precision": prefetch_precision,
             "prefetch_coverage": prefetch_coverage,
+            "prefetch_utilization": prefetch_utilization,
+            "prefetch_attempts_per_prediction": self.prefetch_attempts / len(predictions) if predictions else 0.0,
+            "forecast_recall": forecast_recall,
             "prefetch_gb": self.prefetch_bytes / 1e9,
+            "prefetch_useful_gb": self.prefetch_useful_bytes / 1e9,
+            "unused_prefetch_gb": self.unused_prefetch_bytes / 1e9,
             "wrong_step_prefetch_gb": self.wrong_step_prefetch_bytes / 1e9,
             "p95_prefetch_transfer_ms": percentile(self.transfer_latencies_ms, 0.95),
         }
@@ -624,6 +883,9 @@ class ExecutionLearningSimulator:
             "top1_accuracy": accuracy(predictions),
             "pre_shift_accuracy": accuracy(pre),
             "post_shift_accuracy": accuracy(post),
+            "calibration": _prediction_calibration(predictions),
+            "pre_shift_calibration": _prediction_calibration(pre),
+            "post_shift_calibration": _prediction_calibration(post),
             "rows": predictions[:4000],
             "predictor": self.predictor.snapshot(),
         }
@@ -638,9 +900,9 @@ class ExecutionLearningSimulator:
                 "simulator": "InferScale-Sim",
                 "mode": "online-agent-execution-learning",
                 "latency_profile_type": "analytical-reference",
-                "execution_model": "first-order-transition-prefix-prefetch-reference",
+                "execution_model": "online-transition-multistep-prefix-prefetch-reference",
                 "prefetch_policy": self.cfg.prefetch_policy,
-                "lookahead": "oracle-upper-bound" if self.cfg.prefetch_policy == "oracle" else "no-future-transition-lookahead",
+                "lookahead": "oracle-upper-bound" if self.cfg.prefetch_policy in {"oracle", "oracle_horizon"} else "no-future-transition-lookahead",
                 "warning": "Execution Learning isolates cross-workflow static-prefix prediction/prefetch from session-KV retention and dynamic batching.",
             },
             "summary": summary,
@@ -672,10 +934,17 @@ def _row(label: str, result: dict[str, Any]) -> dict[str, Any]:
         "prefix_hit_rate": result["resource"]["prefix_hit_rate"],
         "prefetch_precision": result["resource"]["prefetch_precision"],
         "prefetch_coverage": result["resource"]["prefetch_coverage"],
+        "prefetch_utilization": result["resource"].get("prefetch_utilization", 0.0),
+        "forecast_recall": result["resource"].get("forecast_recall", 0.0),
         "mean_hbm_gb": result["resource"]["mean_prefix_hbm_gb"],
+        "pressure_evictions": result["resource"].get("pressure_evictions", 0),
         "wrong_step_prefetch_gb": result["resource"]["wrong_step_prefetch_gb"],
+        "unused_prefetch_gb": result["resource"].get("unused_prefetch_gb", 0.0),
         "prefill_tokens_saved": result["resource"]["prefill_tokens_saved"],
         "top1_accuracy": result["prediction"]["top1_accuracy"],
+        "brier": result["prediction"].get("calibration", {}).get("brier", 0.0),
+        "ece": result["prediction"].get("calibration", {}).get("ece", 0.0),
+        "post_shift_ece": result["prediction"].get("post_shift_calibration", {}).get("ece", 0.0),
         "pre_shift_accuracy": result["prediction"]["pre_shift_accuracy"],
         "post_shift_accuracy": result["prediction"]["post_shift_accuracy"],
     }
@@ -790,3 +1059,102 @@ def execution_decay_sweep(
         "association": association,
         "note": "Better next-role prediction need not minimize serving latency because cache occupancy and transfer timing mediate the effect.",
     }
+
+
+def execution_planning_study(config: dict[str, Any]) -> dict[str, Any]:
+    """Compare one-step, multi-step, utility-aware, and clairvoyant planning."""
+    base = ExecutionLearningConfig.from_dict(config)
+    workflows = _common_workflows(base)
+    candidates = [
+        ("Top-1 decayed", "decayed"),
+        ("Multi-step top-k", "multistep"),
+        ("Utility-aware multi-step", "utility"),
+        ("Oracle future-set", "oracle_horizon"),
+    ]
+    rows: list[dict[str, Any]] = []
+    results: dict[str, dict[str, Any]] = {}
+    for label, policy in candidates:
+        cfg = ExecutionLearningConfig.from_dict(base.to_dict())
+        cfg.prefetch_policy = policy
+        result = run_execution_learning(cfg.to_dict(), workflows)
+        results[label] = result
+        rows.append(_row(label, result))
+    best_ttft = min(rows, key=lambda row: row["p95_step_ttft_ms"]) if rows else None
+    best_efficiency = max(
+        rows,
+        key=lambda row: (
+            row["prefill_tokens_saved"] / max(row["mean_hbm_gb"], 1e-9),
+            -row["p95_step_ttft_ms"],
+        ),
+    ) if rows else None
+    return {
+        "protocol": "common-shifted-agent-workflow-trace",
+        "study": "multi-step-prefetch-planning",
+        "rows": rows,
+        "results": results,
+        "best_ttft_policy": best_ttft["label"] if best_ttft else None,
+        "best_prefill_per_hbm_policy": best_efficiency["label"] if best_efficiency else None,
+        "note": "Oracle future-set sees realized future roles only as an information upper bound; online multi-step policies roll the learned transition matrix forward without future trace access.",
+    }
+
+
+def execution_horizon_sweep(
+    config: dict[str, Any], horizon_values: list[int] | None = None
+) -> dict[str, Any]:
+    base = ExecutionLearningConfig.from_dict(config)
+    base.prefetch_policy = "utility"
+    workflows = _common_workflows(base)
+    values = horizon_values or [1, 2, 3, 4, 5]
+    cleaned = sorted({max(1, min(int(value), 6)) for value in values})
+    rows: list[dict[str, Any]] = []
+    for horizon in cleaned:
+        cfg = ExecutionLearningConfig.from_dict(base.to_dict())
+        cfg.forecast_horizon = horizon
+        result = run_execution_learning(cfg.to_dict(), workflows)
+        rows.append(_row(f"horizon {horizon}", result) | {"horizon": horizon})
+    best_ttft = min(rows, key=lambda row: (row["p95_step_ttft_ms"], row["unused_prefetch_gb"])) if rows else None
+    best_utilization = max(rows, key=lambda row: (row["prefetch_utilization"], -row["unused_prefetch_gb"])) if rows else None
+    return {
+        "protocol": "common-shifted-agent-workflow-trace",
+        "study": "forecast-horizon-sweep",
+        "rows": rows,
+        "best_ttft_horizon": best_ttft["horizon"] if best_ttft else None,
+        "best_utilization_horizon": best_utilization["horizon"] if best_utilization else None,
+        "note": "Longer forecasts can expose future reuse but may spend bandwidth and cache capacity on prefixes that are not consumed before eviction.",
+    }
+
+
+def execution_budget_sweep(
+    config: dict[str, Any], budget_values: list[float] | None = None
+) -> dict[str, Any]:
+    base = ExecutionLearningConfig.from_dict(config)
+    workflows = _common_workflows(base)
+    values = budget_values or [0.30, 0.50, 0.75, 1.00]
+    cleaned = sorted({min(max(float(value), 0.10), 1.50) for value in values})
+    policies = [
+        ("Top-1", "decayed"),
+        ("Multi-step", "multistep"),
+        ("Utility-aware", "utility"),
+    ]
+    rows: list[dict[str, Any]] = []
+    for budget in cleaned:
+        for label, policy in policies:
+            cfg = ExecutionLearningConfig.from_dict(base.to_dict())
+            cfg.prefix_cache_budget_fraction = budget
+            cfg.prefetch_policy = policy
+            result = run_execution_learning(cfg.to_dict(), workflows)
+            rows.append(_row(label, result) | {"budget": budget, "policy_label": label})
+    winners = []
+    for budget in cleaned:
+        group = [row for row in rows if abs(float(row["budget"]) - budget) < 1e-12]
+        if group:
+            winner = min(group, key=lambda row: (row["p95_step_ttft_ms"], row["unused_prefetch_gb"]))
+            winners.append({"budget": budget, "policy": winner["policy_label"], "p95_step_ttft_ms": winner["p95_step_ttft_ms"]})
+    return {
+        "protocol": "common-shifted-agent-workflow-trace",
+        "study": "prefix-cache-budget-policy-sweep",
+        "rows": rows,
+        "winners": winners,
+        "note": "All policies see the same workflows at each cache budget; the sweep exposes when broader forecasting helps versus when it increases cache pressure.",
+    }
+

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "inferscale-sim"
-version = "0.8.0"
+version = "0.9.0"
 description = "Interactive LLM serving simulator and SLO capacity planner"
 readme = "README.md"
 requires-python = ">=3.10"

scripts/release_check.py

@@ -22,6 +22,9 @@ agent_affinity_sweep = inferscale.agent_affinity_sweep
 execution_prefetch_study = inferscale.execution_prefetch_study
 execution_threshold_sweep = inferscale.execution_threshold_sweep
 execution_decay_sweep = inferscale.execution_decay_sweep
+execution_planning_study = inferscale.execution_planning_study
+execution_horizon_sweep = inferscale.execution_horizon_sweep
+execution_budget_sweep = inferscale.execution_budget_sweep
 run_execution_learning = inferscale.run_execution_learning
 paired_study = inferscale.paired_study
 robustness_study = inferscale.robustness_study
@@ -43,8 +46,8 @@ else:
 
 if "sdk: static" not in README:
     errors.append("README metadata must use sdk: static")
-if internal_version != "0.8.0":
-    errors.append(f"internal package version is {internal_version}; expected 0.8.0")
+if internal_version != "0.9.0":
+    errors.append(f"internal package version is {internal_version}; expected 0.9.0")
 
 # Public-facing release/version branding is intentionally absent. Model names
 # such as Mistral-7B-v0.3 are allowed; project headings/badges are not.
@@ -83,7 +86,7 @@ if "Download PNG" not in index or ".chart-download" not in app:
     errors.append("chart PNG export controls are missing")
 if "Worst repetition" not in index or "Target" not in index:
     errors.append("capacity evidence columns are missing")
-for expected in ["Trace replay", "Research Studies", "Run paired study", "Stress-test selected hypothesis", "Agent Sessions", "Session Policy Arena", "TTL frontier", "Agent Memory Lab", "Affinity Frontier", "Stress HBM budget", "Predictive Tiering Lab", "Compare predictive policies", "Sweep adaptation rate", "Execution Learning", "Prefetch Policy Study", "Confidence Threshold Study", "Forgetting-Rate Study", "Download JSON"]:
+for expected in ["Trace replay", "Research Studies", "Run paired study", "Stress-test selected hypothesis", "Agent Sessions", "Session Policy Arena", "TTL frontier", "Agent Memory Lab", "Affinity Frontier", "Stress HBM budget", "Predictive Tiering Lab", "Compare predictive policies", "Sweep adaptation rate", "Execution Learning", "Prefetch Policy Study", "Confidence Threshold Study", "Forgetting-Rate Study", "Prefetch Planning Study", "Forecast Horizon Study", "Cache Budget Study", "Download JSON"]:
     if expected not in index:
         errors.append(f"UI is missing research/trace feature: {expected}")
 
@@ -248,6 +251,15 @@ try:
     execution_decay = execution_decay_sweep(execution_cfg, [0.5, 0.85, 1.0])
     if len(execution_decay.get("rows", [])) != 3:
         errors.append("execution transition-decay sweep is incomplete")
+    execution_planning = execution_planning_study(execution_cfg | {"forecast_horizon": 3, "prefetch_top_k": 2})
+    if len(execution_planning.get("rows", [])) != 4:
+        errors.append("execution multi-step planning study is incomplete")
+    execution_horizon = execution_horizon_sweep(execution_cfg, [1, 2, 3])
+    if len(execution_horizon.get("rows", [])) != 3:
+        errors.append("execution forecast-horizon sweep is incomplete")
+    execution_budget = execution_budget_sweep(execution_cfg, [0.3, 0.6])
+    if len(execution_budget.get("rows", [])) != 6:
+        errors.append("execution cache-budget sweep is incomplete")
 except Exception as exc:  # pragma: no cover
     errors.append(f"execution-learning smoke test raised: {exc}")
 
@@ -290,5 +302,8 @@ print(f"Execution transition observations: {execution_run['prediction']['count']
 print(f"Execution policy candidates: {len(execution_compare['rows'])}")
 print(f"Execution threshold points: {len(execution_threshold['rows'])}")
 print(f"Execution decay points: {len(execution_decay['rows'])}")
+print(f"Execution planning candidates: {len(execution_planning['rows'])}")
+print(f"Execution horizon points: {len(execution_horizon['rows'])}")
+print(f"Execution cache-budget rows: {len(execution_budget['rows'])}")
 print(f"Validation observations: {validation['observation_count']}")
 print(f"Profile provenance: {smoke['provenance']['latency_profile_type']}")

src/inferscale/__init__.py

@@ -9,7 +9,15 @@ from .agentic import (
     ttl_retention_sweep,
 )
 from .api import execute, metadata
-from .execution import execution_decay_sweep, execution_prefetch_study, execution_threshold_sweep, run_execution_learning
+from .execution import (
+    execution_budget_sweep,
+    execution_decay_sweep,
+    execution_horizon_sweep,
+    execution_planning_study,
+    execution_prefetch_study,
+    execution_threshold_sweep,
+    run_execution_learning,
+)
 from .models import SimulationConfig
 from .optimizer import capacity_search, compare_schedulers, compare_topologies, design_space_search
 from .research import paired_study, robustness_study
@@ -29,7 +37,10 @@ __all__ = [
     "compare_topologies",
     "design_space_search",
     "execute",
+    "execution_budget_sweep",
     "execution_decay_sweep",
+    "execution_horizon_sweep",
+    "execution_planning_study",
     "execution_prefetch_study",
     "execution_threshold_sweep",
     "metadata",
@@ -44,4 +55,4 @@ __all__ = [
 
 # Internal package metadata only; the public project intentionally avoids
 # release/version branding in the interface and documentation.
-__version__ = "0.8.0"
+__version__ = "0.9.0"

src/inferscale/api.py

@@ -11,7 +11,10 @@ from .agentic import (
     ttl_retention_sweep,
 )
 from .execution import (
+    execution_budget_sweep,
     execution_decay_sweep,
+    execution_horizon_sweep,
+    execution_planning_study,
     execution_prefetch_study,
     execution_threshold_sweep,
     run_execution_learning,
@@ -37,6 +40,7 @@ def metadata() -> dict:
         ],
         "execution_learning_modes": [
             "single_run", "prefetch_policy_compare", "confidence_threshold_sweep", "transition_decay_sweep",
+            "multistep_planning", "forecast_horizon_sweep", "cache_budget_policy_sweep",
         ],
     }
 
@@ -107,6 +111,12 @@ def execute(action: str, payload: dict) -> dict:
         return execution_threshold_sweep(payload.get("config", payload), payload.get("thresholds"))
     if action == "execution_decay_sweep":
         return execution_decay_sweep(payload.get("config", payload), payload.get("decay_values"))
+    if action == "execution_planning_study":
+        return execution_planning_study(payload.get("config", payload))
+    if action == "execution_horizon_sweep":
+        return execution_horizon_sweep(payload.get("config", payload), payload.get("horizon_values"))
+    if action == "execution_budget_sweep":
+        return execution_budget_sweep(payload.get("config", payload), payload.get("budget_values"))
     if action == "robustness_study":
         config = payload.get("config", payload)
         return robustness_study(

src/inferscale/execution.py

@@ -48,7 +48,7 @@ ROLE_GAP_MULTIPLIERS = {
     "writer": 0.30,
 }
 
-PREFETCH_POLICIES = {"none", "cumulative", "decayed", "oracle"}
+PREFETCH_POLICIES = {"none", "cumulative", "decayed", "multistep", "utility", "oracle", "oracle_horizon"}
 
 
 @dataclass
@@ -74,6 +74,11 @@ class ExecutionLearningConfig:
     transition_decay: float = 0.85
     confidence_threshold: float = 0.55
     prior_strength: float = 0.35
+    forecast_horizon: int = 3
+    prefetch_top_k: int = 2
+    forecast_discount: float = 0.75
+    forecast_min_score: float = 0.10
+    utility_threshold_ms: float = 0.0
     timeline_points: int = 240
 
     @classmethod
@@ -90,6 +95,11 @@ class ExecutionLearningConfig:
         cfg.transition_decay = min(max(float(cfg.transition_decay), 0.20), 1.0)
         cfg.confidence_threshold = min(max(float(cfg.confidence_threshold), 0.0), 1.0)
         cfg.prior_strength = max(float(cfg.prior_strength), 0.01)
+        cfg.forecast_horizon = max(1, min(int(cfg.forecast_horizon), 6))
+        cfg.prefetch_top_k = max(1, min(int(cfg.prefetch_top_k), len(AGENT_ROLES)))
+        cfg.forecast_discount = min(max(float(cfg.forecast_discount), 0.05), 1.0)
+        cfg.forecast_min_score = min(max(float(cfg.forecast_min_score), 0.0), 1.0)
+        cfg.utility_threshold_ms = float(cfg.utility_threshold_ms)
         cfg.timeline_points = max(40, min(int(cfg.timeline_points), 1000))
         if cfg.prefetch_policy not in PREFETCH_POLICIES:
             raise ValueError(f"Unsupported execution prefetch policy: {cfg.prefetch_policy}")
@@ -123,6 +133,7 @@ class PrefixEntry:
     available_time: float
     source: str
     generation: int
+    used: bool = False
 
 
 class OnlineTransitionPredictor:
@@ -150,6 +161,59 @@ class OnlineTransitionPredictor:
         best = max(self.targets, key=lambda target: (probabilities[target], -self.targets.index(target)))
         return best, probabilities[best], probabilities
 
+    def forecast(
+        self,
+        current_role: str,
+        *,
+        horizon: int = 3,
+        discount: float = 0.75,
+    ) -> dict[str, Any]:
+        """Roll the learned first-order matrix forward without future trace access.
+
+        ``role_scores`` are discounted expected future visits, not calibrated
+        probabilities of at-least-one reuse. They are therefore used as a
+        ranking signal and are normalized separately for UI/decision thresholds.
+        """
+
+        horizon = max(1, min(int(horizon), 8))
+        discount = min(max(float(discount), 0.0), 1.0)
+        distributions: list[dict[str, float]] = []
+        current: dict[str, float] = {target: 0.0 for target in self.targets}
+        current[current_role] = 1.0
+        role_scores = {role: 0.0 for role in AGENT_ROLES}
+
+        for depth in range(1, horizon + 1):
+            nxt = {target: 0.0 for target in self.targets}
+            for source, mass in current.items():
+                if mass <= 0.0:
+                    continue
+                if source == END:
+                    nxt[END] += mass
+                    continue
+                _, _, probs = self.predict(source)
+                for target, probability in probs.items():
+                    nxt[target] += mass * probability
+            distributions.append(nxt)
+            weight = discount ** (depth - 1)
+            for role in AGENT_ROLES:
+                role_scores[role] += weight * nxt.get(role, 0.0)
+            current = nxt
+
+        total_score = sum(role_scores.values())
+        normalized = {
+            role: (score / total_score if total_score > 1e-12 else 0.0)
+            for role, score in role_scores.items()
+        }
+        ranked = sorted(AGENT_ROLES, key=lambda role: (-role_scores[role], role))
+        return {
+            "horizon": horizon,
+            "discount": discount,
+            "distributions": distributions,
+            "role_scores": role_scores,
+            "normalized_scores": normalized,
+            "ranked_roles": ranked,
+        }
+
     def observe(self, current_role: str, next_role: str) -> None:
         row = self.rows[current_role]
         if self.decay < 1.0:
@@ -225,6 +289,50 @@ def generate_workflows(cfg: ExecutionLearningConfig) -> list[WorkflowSpec]:
     return workflows
 
 
+def _prediction_calibration(rows: list[dict[str, Any]], bins: int = 10) -> dict[str, Any]:
+    if not rows:
+        return {"count": 0, "brier": 0.0, "log_loss": 0.0, "ece": 0.0, "bins": []}
+    targets = (*AGENT_ROLES, END)
+    brier_total = 0.0
+    log_total = 0.0
+    buckets: list[list[tuple[float, float]]] = [[] for _ in range(max(2, bins))]
+    for row in rows:
+        probs = row.get("probabilities", {})
+        actual = str(row.get("actual_next_role", END))
+        brier_total += sum((float(probs.get(target, 0.0)) - (1.0 if target == actual else 0.0)) ** 2 for target in targets)
+        actual_p = max(float(probs.get(actual, 0.0)), 1e-12)
+        log_total += -math.log(actual_p)
+        confidence = min(max(float(row.get("confidence", 0.0)), 0.0), 1.0)
+        correct = 1.0 if row.get("prediction_correct") else 0.0
+        index = min(int(confidence * len(buckets)), len(buckets) - 1)
+        buckets[index].append((confidence, correct))
+    ece = 0.0
+    rendered = []
+    for index, bucket in enumerate(buckets):
+        if not bucket:
+            continue
+        avg_conf = mean(value[0] for value in bucket)
+        accuracy = mean(value[1] for value in bucket)
+        weight = len(bucket) / len(rows)
+        ece += weight * abs(avg_conf - accuracy)
+        rendered.append(
+            {
+                "lower": index / len(buckets),
+                "upper": (index + 1) / len(buckets),
+                "count": len(bucket),
+                "mean_confidence": avg_conf,
+                "accuracy": accuracy,
+            }
+        )
+    return {
+        "count": len(rows),
+        "brier": brier_total / len(rows),
+        "log_loss": log_total / len(rows),
+        "ece": ece,
+        "bins": rendered,
+    }
+
+
 class ExecutionLearningSimulator:
     """Reference simulator for online workflow learning and prefix prefetch.
 
@@ -260,7 +368,10 @@ class ExecutionLearningSimulator:
         self.pressure_evictions = 0
         self.prefetch_attempts = 0
         self.prefetch_correct = 0
+        self.prefetch_useful = 0
         self.prefetch_bytes = 0.0
+        self.prefetch_useful_bytes = 0.0
+        self.unused_prefetch_bytes = 0.0
         self.wrong_step_prefetch_bytes = 0.0
         self.transfer_latencies_ms: list[float] = []
         self.prefix_hits = 0
@@ -308,6 +419,40 @@ class ExecutionLearningSimulator:
         if len(self.timeline) > self.cfg.timeline_points * 2:
             self.timeline = self.timeline[::2]
 
+    def _mark_unused_prefetch(self, entry: PrefixEntry) -> None:
+        if entry.source == "prefetch" and not entry.used:
+            self.unused_prefetch_bytes += entry.size_gb * 1e9
+
+    def _candidate_eviction_cost_ms(self, role: str, forecast_scores: dict[str, float]) -> float:
+        """Approximate downstream cost of evicting forecast-relevant cached prefixes."""
+        size_gb = self.role_size_gb[role]
+        existing = self.cache.get(role)
+        current_without = self._used_gb() - (existing.size_gb if existing else 0.0)
+        overflow = max(0.0, current_without + size_gb - self.cache_capacity_gb)
+        if overflow <= 1e-12:
+            return 0.0
+        cost_ms = 0.0
+        reclaimed = 0.0
+        candidates = sorted(
+            [entry for key, entry in self.cache.items() if key != role],
+            key=lambda entry: (entry.last_access, entry.role),
+        )
+        for victim in candidates:
+            if reclaimed >= overflow - 1e-12:
+                break
+            reuse_score = max(float(forecast_scores.get(victim.role, 0.0)), 0.0)
+            recompute_ms = self.latency.prefill_seconds([ROLE_PREFIX_TOKENS[victim.role]]) * 1000.0
+            cost_ms += reuse_score * recompute_ms
+            reclaimed += victim.size_gb
+        return cost_ms
+
+    def _prefetch_utility_ms(self, role: str, forecast_scores: dict[str, float]) -> float:
+        score = max(float(forecast_scores.get(role, 0.0)), 0.0)
+        saved_ms = self.latency.prefill_seconds([ROLE_PREFIX_TOKENS[role]]) * 1000.0
+        transfer_ms = self.cfg.transfer_base_ms + self.role_size_gb[role] / self.cfg.host_bandwidth_gbps * 1000.0
+        eviction_ms = self._candidate_eviction_cost_ms(role, forecast_scores)
+        return score * saved_ms - transfer_ms - eviction_ms
+
     def _evict_for(self, role: str, size_gb: float) -> bool:
         existing = self.cache.get(role)
         current_without_role = self._used_gb() - (existing.size_gb if existing else 0.0)
@@ -319,6 +464,7 @@ class ExecutionLearningSimulator:
                 return False
             victim = min(candidates, key=lambda entry: (entry.last_access, entry.role))
             self._integrate_memory(self.now)
+            self._mark_unused_prefetch(victim)
             self.cache.pop(victim.role, None)
             self.prefix_source.pop(victim.role, None)
             self.pressure_evictions += 1
@@ -331,6 +477,8 @@ class ExecutionLearningSimulator:
             return None
         self._integrate_memory(self.now)
         previous = self.cache.get(role)
+        if previous is not None:
+            self._mark_unused_prefetch(previous)
         generation = (previous.generation + 1) if previous else 1
         self.cache[role] = PrefixEntry(role, size_gb, self.now, available_time, source, generation)
         self.prefix_source[role] = source
@@ -362,35 +510,103 @@ class ExecutionLearningSimulator:
             return END
         return workflow.steps[step_index + 1].role
 
-    def _schedule_prediction(self, workflow_id: int, step_index: int, current_role: str) -> None:
+    def _actual_future_roles(self, workflow_id: int, step_index: int, horizon: int) -> list[str]:
+        workflow = self.workflows[workflow_id]
+        roles = [step.role for step in workflow.steps[step_index + 1 : step_index + 1 + max(1, horizon)]]
+        return roles
+
+    def _planned_prefetch_roles(
+        self,
+        workflow_id: int,
+        step_index: int,
+        current_role: str,
+    ) -> tuple[str, float, dict[str, float], dict[str, Any], list[dict[str, Any]]]:
         actual_next = self._actual_next_role(workflow_id, step_index)
-        predicted_role = END
-        confidence = 1.0
-        probabilities: dict[str, float] = {target: 0.0 for target in (*AGENT_ROLES, END)}
-        attempted = False
-        decision_reason = "disabled"
+        predicted_role, confidence, probabilities = self.predictor.predict(current_role)
+        forecast = self.predictor.forecast(
+            current_role,
+            horizon=self.cfg.forecast_horizon,
+            discount=self.cfg.forecast_discount,
+        )
+        plans: list[dict[str, Any]] = []
+
         if self.cfg.prefetch_policy == "oracle":
             predicted_role = actual_next
             confidence = 1.0
+            probabilities = {target: 0.0 for target in (*AGENT_ROLES, END)}
             probabilities[predicted_role] = 1.0
-        elif self.cfg.prefetch_policy in {"cumulative", "decayed"}:
-            predicted_role, confidence, probabilities = self.predictor.predict(current_role)
-        elif self.cfg.prefetch_policy == "none":
-            # Learn-only control: the transition model still makes a prediction,
-            # but the serving policy never acts on it. This separates the value
-            # of prediction from the value (and cost) of prefetch.
-            predicted_role, confidence, probabilities = self.predictor.predict(current_role)
-
-        prefetch_result: dict[str, Any] = {"attempted": False, "reason": "no_prefetch", "role": predicted_role}
-        if self.cfg.prefetch_policy != "none" and predicted_role != END:
-            if confidence >= self.cfg.confidence_threshold or self.cfg.prefetch_policy == "oracle":
-                prefetch_result = self._prefetch(predicted_role)
-                attempted = bool(prefetch_result.get("attempted"))
-                decision_reason = str(prefetch_result.get("reason", "scheduled"))
-            else:
-                decision_reason = "below_threshold"
-        elif predicted_role == END:
-            decision_reason = "predict_end"
+            if actual_next != END:
+                plans = [{"role": actual_next, "score": 1.0, "utility_ms": None, "oracle": True}]
+            return predicted_role, confidence, probabilities, forecast, plans
+
+        if self.cfg.prefetch_policy == "oracle_horizon":
+            actual_future = self._actual_future_roles(workflow_id, step_index, self.cfg.forecast_horizon)
+            predicted_role = actual_next
+            confidence = 1.0
+            probabilities = {target: 0.0 for target in (*AGENT_ROLES, END)}
+            probabilities[predicted_role] = 1.0
+            seen: set[str] = set()
+            for role in actual_future:
+                if role not in seen:
+                    plans.append({"role": role, "score": 1.0, "utility_ms": None, "oracle": True})
+                    seen.add(role)
+                if len(plans) >= self.cfg.prefetch_top_k:
+                    break
+            return predicted_role, confidence, probabilities, forecast, plans
+
+        if self.cfg.prefetch_policy in {"none", "cumulative", "decayed"}:
+            if self.cfg.prefetch_policy != "none" and predicted_role != END and confidence >= self.cfg.confidence_threshold:
+                plans = [{"role": predicted_role, "score": confidence, "utility_ms": None, "oracle": False}]
+            return predicted_role, confidence, probabilities, forecast, plans
+
+        ranked = forecast["ranked_roles"]
+        normalized = forecast["normalized_scores"]
+        raw_scores = forecast["role_scores"]
+        for role in ranked:
+            if len(plans) >= self.cfg.prefetch_top_k:
+                break
+            normalized_score = float(normalized.get(role, 0.0))
+            if normalized_score < self.cfg.forecast_min_score:
+                continue
+            utility_ms = self._prefetch_utility_ms(role, raw_scores)
+            if self.cfg.prefetch_policy == "utility" and utility_ms < self.cfg.utility_threshold_ms:
+                continue
+            plans.append(
+                {
+                    "role": role,
+                    "score": normalized_score,
+                    "raw_score": float(raw_scores.get(role, 0.0)),
+                    "utility_ms": utility_ms,
+                    "oracle": False,
+                }
+            )
+        return predicted_role, confidence, probabilities, forecast, plans
+
+    def _schedule_prediction(self, workflow_id: int, step_index: int, current_role: str) -> None:
+        actual_next = self._actual_next_role(workflow_id, step_index)
+        predicted_role, confidence, probabilities, forecast, plans = self._planned_prefetch_roles(
+            workflow_id, step_index, current_role
+        )
+        attempted_roles: list[str] = []
+        attempt_sizes: dict[str, float] = {}
+        attempt_reasons: dict[str, str] = {}
+
+        for plan in plans:
+            role = str(plan["role"])
+            result = self._prefetch(role)
+            attempt_reasons[role] = str(result.get("reason", "unknown"))
+            if result.get("attempted"):
+                attempted_roles.append(role)
+                attempt_sizes[role] = float(result.get("size_gb", 0.0))
+
+        if self.cfg.prefetch_policy == "none":
+            decision_reason = "learn_only"
+        elif not plans:
+            decision_reason = "no_candidate"
+        elif attempted_roles:
+            decision_reason = "scheduled"
+        else:
+            decision_reason = ",".join(sorted(set(attempt_reasons.values()))) or "not_scheduled"
 
         self.pending_predictions[(workflow_id, step_index)] = {
             "workflow_id": workflow_id,
@@ -399,14 +615,21 @@ class ExecutionLearningSimulator:
             "predicted_role": predicted_role,
             "confidence": confidence,
             "probabilities": probabilities,
-            "prefetch_attempted": attempted,
+            "forecast_horizon": self.cfg.forecast_horizon,
+            "forecast_discount": self.cfg.forecast_discount,
+            "forecast_role_scores": forecast["role_scores"],
+            "forecast_normalized_scores": forecast["normalized_scores"],
+            "forecast_roles": [str(plan["role"]) for plan in plans],
+            "forecast_plans": plans,
+            "prefetch_attempted": bool(attempted_roles),
+            "prefetch_roles": attempted_roles,
+            "prefetch_reasons": attempt_reasons,
             "prefetch_reason": decision_reason,
-            "prefetch_size_gb": float(prefetch_result.get("size_gb", 0.0)),
+            "prefetch_sizes_gb": attempt_sizes,
+            "prefetch_size_gb": sum(attempt_sizes.values()),
             "shifted_regime": self.workflows[workflow_id].steps[step_index].shifted_regime,
         }
 
-        # END is observable immediately at workflow completion. Non-final
-        # transitions become observable only after the tool gap has elapsed.
         if actual_next == END:
             self._observe_transition(workflow_id, step_index, actual_next)
 
@@ -418,22 +641,38 @@ class ExecutionLearningSimulator:
         if pending is None:
             return
         predicted_role = str(pending["predicted_role"])
-        attempted = bool(pending["prefetch_attempted"])
+        attempted_roles = [str(role) for role in pending.get("prefetch_roles", [])]
         correct = predicted_role == actual_next
-        if attempted and correct and actual_next != END:
+        if actual_next != END and actual_next in attempted_roles:
             self.prefetch_correct += 1
-        if attempted and not correct:
-            self.wrong_step_prefetch_bytes += float(pending.get("prefetch_size_gb", 0.0)) * 1e9
+        immediate_wrong_bytes = 0.0
+        for role in attempted_roles:
+            if role != actual_next:
+                immediate_wrong_bytes += float(pending.get("prefetch_sizes_gb", {}).get(role, 0.0)) * 1e9
+        self.wrong_step_prefetch_bytes += immediate_wrong_bytes
+
+        future_roles = self._actual_future_roles(workflow_id, step_index, int(pending.get("forecast_horizon", 1)))
+        actual_future_set = set(future_roles)
+        forecast_roles = [str(role) for role in pending.get("forecast_roles", [])]
+        forecast_set = set(forecast_roles)
+        forecast_recall = (
+            len(actual_future_set & forecast_set) / len(actual_future_set)
+            if actual_future_set
+            else None
+        )
         self.prediction_rows.append(
             pending
             | {
                 "actual_next_role": actual_next,
+                "actual_future_roles": future_roles,
                 "prediction_correct": correct,
+                "forecast_next_hit": actual_next in forecast_set if actual_next != END else predicted_role == END,
+                "forecast_recall": forecast_recall,
+                "immediate_wrong_prefetch_gb": immediate_wrong_bytes / 1e9,
                 "post_shift": bool(pending["shifted_regime"]),
             }
         )
-        # Oracle is kept as an upper-bound candidate; it is not an online learner.
-        if self.cfg.prefetch_policy != "oracle":
+        if self.cfg.prefetch_policy not in {"oracle", "oracle_horizon"}:
             self.predictor.observe(current_role, actual_next)
 
     def _start_next(self) -> None:
@@ -470,6 +709,10 @@ class ExecutionLearningSimulator:
                 self.prefetch_hits += 1
             self.prefill_tokens_saved += prefix_tokens
             if entry is not None:
+                if entry.source == "prefetch" and not entry.used:
+                    entry.used = True
+                    self.prefetch_useful += 1
+                    self.prefetch_useful_bytes += entry.size_gb * 1e9
                 entry.last_access = self.now + prefix_wait_s
             prefill_tokens = max(step.dynamic_prompt_tokens, 1)
         else:
@@ -590,8 +833,19 @@ class ExecutionLearningSimulator:
         def accuracy(rows: list[dict[str, Any]]) -> float:
             return sum(1 for row in rows if row["prediction_correct"]) / len(rows) if rows else 0.0
 
+        # Account for prefetched entries that remained unused through the end of the run.
+        for entry in list(self.cache.values()):
+            self._mark_unused_prefetch(entry)
         prefetch_precision = self.prefetch_correct / self.prefetch_attempts if self.prefetch_attempts else 0.0
-        prefetch_coverage = self.prefetch_attempts / len(predictions) if predictions else 0.0
+        prefetch_coverage = (
+            sum(1 for row in predictions if row.get("prefetch_attempted")) / len(predictions)
+            if predictions else 0.0
+        )
+        prefetch_utilization = self.prefetch_useful / self.prefetch_attempts if self.prefetch_attempts else 0.0
+        forecast_recall_values = [
+            float(row["forecast_recall"]) for row in predictions if row.get("forecast_recall") is not None
+        ]
+        forecast_recall = mean(forecast_recall_values) if forecast_recall_values else 0.0
         workflow_count = len(self.workflows)
         completed_count = len(self.workflow_completion)
         summary = {
@@ -615,7 +869,12 @@ class ExecutionLearningSimulator:
             "prefetch_correct": self.prefetch_correct,
             "prefetch_precision": prefetch_precision,
             "prefetch_coverage": prefetch_coverage,
+            "prefetch_utilization": prefetch_utilization,
+            "prefetch_attempts_per_prediction": self.prefetch_attempts / len(predictions) if predictions else 0.0,
+            "forecast_recall": forecast_recall,
             "prefetch_gb": self.prefetch_bytes / 1e9,
+            "prefetch_useful_gb": self.prefetch_useful_bytes / 1e9,
+            "unused_prefetch_gb": self.unused_prefetch_bytes / 1e9,
             "wrong_step_prefetch_gb": self.wrong_step_prefetch_bytes / 1e9,
             "p95_prefetch_transfer_ms": percentile(self.transfer_latencies_ms, 0.95),
         }
@@ -624,6 +883,9 @@ class ExecutionLearningSimulator:
             "top1_accuracy": accuracy(predictions),
             "pre_shift_accuracy": accuracy(pre),
             "post_shift_accuracy": accuracy(post),
+            "calibration": _prediction_calibration(predictions),
+            "pre_shift_calibration": _prediction_calibration(pre),
+            "post_shift_calibration": _prediction_calibration(post),
             "rows": predictions[:4000],
             "predictor": self.predictor.snapshot(),
         }
@@ -638,9 +900,9 @@ class ExecutionLearningSimulator:
                 "simulator": "InferScale-Sim",
                 "mode": "online-agent-execution-learning",
                 "latency_profile_type": "analytical-reference",
-                "execution_model": "first-order-transition-prefix-prefetch-reference",
+                "execution_model": "online-transition-multistep-prefix-prefetch-reference",
                 "prefetch_policy": self.cfg.prefetch_policy,
-                "lookahead": "oracle-upper-bound" if self.cfg.prefetch_policy == "oracle" else "no-future-transition-lookahead",
+                "lookahead": "oracle-upper-bound" if self.cfg.prefetch_policy in {"oracle", "oracle_horizon"} else "no-future-transition-lookahead",
                 "warning": "Execution Learning isolates cross-workflow static-prefix prediction/prefetch from session-KV retention and dynamic batching.",
             },
             "summary": summary,
@@ -672,10 +934,17 @@ def _row(label: str, result: dict[str, Any]) -> dict[str, Any]:
         "prefix_hit_rate": result["resource"]["prefix_hit_rate"],
         "prefetch_precision": result["resource"]["prefetch_precision"],
         "prefetch_coverage": result["resource"]["prefetch_coverage"],
+        "prefetch_utilization": result["resource"].get("prefetch_utilization", 0.0),
+        "forecast_recall": result["resource"].get("forecast_recall", 0.0),
         "mean_hbm_gb": result["resource"]["mean_prefix_hbm_gb"],
+        "pressure_evictions": result["resource"].get("pressure_evictions", 0),
         "wrong_step_prefetch_gb": result["resource"]["wrong_step_prefetch_gb"],
+        "unused_prefetch_gb": result["resource"].get("unused_prefetch_gb", 0.0),
         "prefill_tokens_saved": result["resource"]["prefill_tokens_saved"],
         "top1_accuracy": result["prediction"]["top1_accuracy"],
+        "brier": result["prediction"].get("calibration", {}).get("brier", 0.0),
+        "ece": result["prediction"].get("calibration", {}).get("ece", 0.0),
+        "post_shift_ece": result["prediction"].get("post_shift_calibration", {}).get("ece", 0.0),
         "pre_shift_accuracy": result["prediction"]["pre_shift_accuracy"],
         "post_shift_accuracy": result["prediction"]["post_shift_accuracy"],
     }
@@ -790,3 +1059,102 @@ def execution_decay_sweep(
         "association": association,
         "note": "Better next-role prediction need not minimize serving latency because cache occupancy and transfer timing mediate the effect.",
     }
+
+
+def execution_planning_study(config: dict[str, Any]) -> dict[str, Any]:
+    """Compare one-step, multi-step, utility-aware, and clairvoyant planning."""
+    base = ExecutionLearningConfig.from_dict(config)
+    workflows = _common_workflows(base)
+    candidates = [
+        ("Top-1 decayed", "decayed"),
+        ("Multi-step top-k", "multistep"),
+        ("Utility-aware multi-step", "utility"),
+        ("Oracle future-set", "oracle_horizon"),
+    ]
+    rows: list[dict[str, Any]] = []
+    results: dict[str, dict[str, Any]] = {}
+    for label, policy in candidates:
+        cfg = ExecutionLearningConfig.from_dict(base.to_dict())
+        cfg.prefetch_policy = policy
+        result = run_execution_learning(cfg.to_dict(), workflows)
+        results[label] = result
+        rows.append(_row(label, result))
+    best_ttft = min(rows, key=lambda row: row["p95_step_ttft_ms"]) if rows else None
+    best_efficiency = max(
+        rows,
+        key=lambda row: (
+            row["prefill_tokens_saved"] / max(row["mean_hbm_gb"], 1e-9),
+            -row["p95_step_ttft_ms"],
+        ),
+    ) if rows else None
+    return {
+        "protocol": "common-shifted-agent-workflow-trace",
+        "study": "multi-step-prefetch-planning",
+        "rows": rows,
+        "results": results,
+        "best_ttft_policy": best_ttft["label"] if best_ttft else None,
+        "best_prefill_per_hbm_policy": best_efficiency["label"] if best_efficiency else None,
+        "note": "Oracle future-set sees realized future roles only as an information upper bound; online multi-step policies roll the learned transition matrix forward without future trace access.",
+    }
+
+
+def execution_horizon_sweep(
+    config: dict[str, Any], horizon_values: list[int] | None = None
+) -> dict[str, Any]:
+    base = ExecutionLearningConfig.from_dict(config)
+    base.prefetch_policy = "utility"
+    workflows = _common_workflows(base)
+    values = horizon_values or [1, 2, 3, 4, 5]
+    cleaned = sorted({max(1, min(int(value), 6)) for value in values})
+    rows: list[dict[str, Any]] = []
+    for horizon in cleaned:
+        cfg = ExecutionLearningConfig.from_dict(base.to_dict())
+        cfg.forecast_horizon = horizon
+        result = run_execution_learning(cfg.to_dict(), workflows)
+        rows.append(_row(f"horizon {horizon}", result) | {"horizon": horizon})
+    best_ttft = min(rows, key=lambda row: (row["p95_step_ttft_ms"], row["unused_prefetch_gb"])) if rows else None
+    best_utilization = max(rows, key=lambda row: (row["prefetch_utilization"], -row["unused_prefetch_gb"])) if rows else None
+    return {
+        "protocol": "common-shifted-agent-workflow-trace",
+        "study": "forecast-horizon-sweep",
+        "rows": rows,
+        "best_ttft_horizon": best_ttft["horizon"] if best_ttft else None,
+        "best_utilization_horizon": best_utilization["horizon"] if best_utilization else None,
+        "note": "Longer forecasts can expose future reuse but may spend bandwidth and cache capacity on prefixes that are not consumed before eviction.",
+    }
+
+
+def execution_budget_sweep(
+    config: dict[str, Any], budget_values: list[float] | None = None
+) -> dict[str, Any]:
+    base = ExecutionLearningConfig.from_dict(config)
+    workflows = _common_workflows(base)
+    values = budget_values or [0.30, 0.50, 0.75, 1.00]
+    cleaned = sorted({min(max(float(value), 0.10), 1.50) for value in values})
+    policies = [
+        ("Top-1", "decayed"),
+        ("Multi-step", "multistep"),
+        ("Utility-aware", "utility"),
+    ]
+    rows: list[dict[str, Any]] = []
+    for budget in cleaned:
+        for label, policy in policies:
+            cfg = ExecutionLearningConfig.from_dict(base.to_dict())
+            cfg.prefix_cache_budget_fraction = budget
+            cfg.prefetch_policy = policy
+            result = run_execution_learning(cfg.to_dict(), workflows)
+            rows.append(_row(label, result) | {"budget": budget, "policy_label": label})
+    winners = []
+    for budget in cleaned:
+        group = [row for row in rows if abs(float(row["budget"]) - budget) < 1e-12]
+        if group:
+            winner = min(group, key=lambda row: (row["p95_step_ttft_ms"], row["unused_prefetch_gb"]))
+            winners.append({"budget": budget, "policy": winner["policy_label"], "p95_step_ttft_ms": winner["p95_step_ttft_ms"]})
+    return {
+        "protocol": "common-shifted-agent-workflow-trace",
+        "study": "prefix-cache-budget-policy-sweep",
+        "rows": rows,
+        "winners": winners,
+        "note": "All policies see the same workflows at each cache budget; the sweep exposes when broader forecasting helps versus when it increases cache pressure.",
+    }
+

tests/test_execution.py

@@ -84,3 +84,59 @@ def test_workflow_generation_has_structured_roles_and_shift() -> None:
     assert "planner" in roles
     assert len(roles) >= 3
     assert any(step.shifted_regime for workflow in workflows for step in workflow.steps)
+
+
+def test_multistep_forecast_is_normalized_and_no_lookahead() -> None:
+    predictor = OnlineTransitionPredictor(decay=0.85, prior_strength=0.2)
+    for _ in range(5):
+        predictor.observe("planner", "retriever")
+    forecast = predictor.forecast("planner", horizon=3, discount=0.75)
+    assert forecast["horizon"] == 3
+    assert len(forecast["distributions"]) == 3
+    assert abs(sum(forecast["normalized_scores"].values()) - 1.0) < 1e-9
+    assert forecast["ranked_roles"][0] == "retriever"
+
+
+def test_multistep_and_utility_runs_report_forecast_and_calibration_metrics() -> None:
+    for policy in ("multistep", "utility"):
+        result = run_execution_learning(
+            _cfg()
+            | {
+                "prefetch_policy": policy,
+                "forecast_horizon": 3,
+                "prefetch_top_k": 2,
+                "forecast_min_score": 0.05,
+            }
+        )
+        assert result["provenance"]["lookahead"] == "no-future-transition-lookahead"
+        assert 0 <= result["resource"]["forecast_recall"] <= 1
+        assert 0 <= result["resource"]["prefetch_utilization"] <= 1
+        assert result["prediction"]["calibration"]["brier"] >= 0
+        assert 0 <= result["prediction"]["calibration"]["ece"] <= 1
+
+
+def test_planning_and_horizon_studies_return_controlled_candidates() -> None:
+    from inferscale.execution import execution_horizon_sweep, execution_planning_study
+
+    planning = execution_planning_study(_cfg())
+    assert len(planning["rows"]) == 4
+    assert planning["best_ttft_policy"] in {row["label"] for row in planning["rows"]}
+    assert {row["label"] for row in planning["rows"]} == {
+        "Top-1 decayed",
+        "Multi-step top-k",
+        "Utility-aware multi-step",
+        "Oracle future-set",
+    }
+
+    horizons = execution_horizon_sweep(_cfg(), [1, 2, 3])
+    assert [row["horizon"] for row in horizons["rows"]] == [1, 2, 3]
+    assert horizons["best_ttft_horizon"] in {1, 2, 3}
+
+
+def test_cache_budget_sweep_compares_three_policies_per_budget() -> None:
+    from inferscale.execution import execution_budget_sweep
+
+    result = execution_budget_sweep(_cfg(), [0.3, 0.6])
+    assert len(result["rows"]) == 6
+    assert len(result["winners"]) == 2
+    assert {row["policy_label"] for row in result["rows"]} == {"Top-1", "Multi-step", "Utility-aware"}