Integrate observed and forecast economic scenarios

[unes07]

Problem

Observed prices, forecasts, deterministic gross margins, and predicted realized margins must remain distinguishable when they are exposed through one economic-planning workflow.

Status: Blocked

Blocked by:

• Benchmark fertilizer-price forecasting with uncertainty turba-models#6
• Benchmark supported crop farm-gate price forecasting turba-models#7
• Add deterministic gross-margin scenario calculation #8
• Develop leakage-safe realized gross-margin prediction turba-models#8
• Add price-aware fertilizer product optimization #4
• Add model cards and artifact-integrity checks turba-models#5

Implementation must not start until all prerequisite contracts and model cards are published.

Proposed behavior

• Keep observed prices as the default.
• Require explicit opt-in for forecast values.
• Return deterministic gross margin separately from predicted realized gross margin.
• Carry source type, horizon, interval, model version, training cutoff, dataset version, and freshness through every scenario.

Acceptance criteria

• Every price identifies whether it is observed, user supplied, quoted, imputed, or forecast.
• Forecast scenarios include horizon and lower/upper intervals.
• Observed and forecast values are never silently combined.
• Scenario ranking occurs only when required data is fresh, supported, and comparable.
• Ranking is suppressed when data is stale, unsupported, or uncertainty exceeds a documented threshold.
• Deterministic and predicted margins use different fields and labels.
• Python, JSON, CSV, CLI, and batch outputs preserve all provenance and uncertainty metadata.
• Tests cover opt-in behavior, stale data, unsupported series, wide intervals, and mixed observed/forecast scenarios.