{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/algenta-ai/json-schema/algenta-ai-decision-envelope-schema.json",
  "title": "DecisionEnvelope",
  "description": "Full decision output returned by /v1/simulate, /v1/recommend, and /v1/score.",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/api.algenta.ai-openapi.json#/components/schemas/DecisionEnvelope",
  "properties": {
    "run_id": {
      "type": "string",
      "format": "uuid",
      "title": "Run Id"
    },
    "status": {
      "type": "string",
      "title": "Status",
      "default": "completed"
    },
    "engine_version": {
      "type": "string",
      "title": "Engine Version"
    },
    "recommended_action": {
      "type": "string",
      "title": "Recommended Action"
    },
    "confidence": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Confidence"
    },
    "rationale": {
      "type": "string",
      "title": "Rationale"
    },
    "metrics": {
      "$ref": "#/$defs/MetricsSummary"
    },
    "percentiles": {
      "$ref": "#/$defs/PercentileSummary"
    },
    "scenarios_run": {
      "type": "integer",
      "title": "Scenarios Run"
    },
    "execution_ms": {
      "type": "integer",
      "title": "Execution Ms"
    },
    "metadata": {
      "$ref": "#/$defs/RunMetadata"
    },
    "simulation_model": {
      "type": "string",
      "title": "Simulation Model",
      "description": "Which simulation algorithm was used. Possible values: monte_carlo | qmc_sobol | lhs | bootstrap | scenario | sensitivity | mcmc | decision_tree | time_series | compare | importance_sampling",
      "default": "monte_carlo"
    },
    "engine_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Engine Type",
      "description": "Engine that ran the simulation (e.g. 'mojo-native-expr', 'lhs', 'mcmc')"
    },
    "simulation_class": {
      "type": "string",
      "title": "Simulation Class",
      "description": "High-level simulation contract class. Examples: predictive, scenario_analysis, sensitivity_analysis, decision_tree.",
      "default": "predictive"
    },
    "model_revision": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model Revision",
      "description": "Stable engine or model revision used to generate this result."
    },
    "assumptions_hash": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Assumptions Hash",
      "description": "Stable fingerprint of the validated simulation assumptions executed by the engine."
    },
    "validated_inputs": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Validated Inputs",
      "description": "Normalized summary of the validated request inputs used for execution. Includes mode, runs, variable counts, and model selection."
    },
    "confidence_interval": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Confidence Interval",
      "description": "Primary outcome confidence interval derived from the simulated distribution."
    },
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Request Id",
      "description": "Correlation identifier propagated from the API request."
    },
    "scenario_analysis": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Scenario Analysis",
      "description": "Populated for simulation_model='scenario': expected_value, best_case, scenarios list"
    },
    "sensitivity_analysis": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sensitivity Analysis",
      "description": "Populated for simulation_model='sensitivity': tornado_chart, first_order_sobol, variable_importance"
    },
    "bootstrap_result": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Bootstrap Result",
      "description": "Populated for simulation_model='bootstrap': statistic, observed_value, CI, bias, SE"
    },
    "mcmc_result": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Mcmc Result",
      "description": "Populated for simulation_model='mcmc': posterior summaries, R-hat, acceptance_rate"
    },
    "importance_sampling_result": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Importance Sampling Result",
      "description": "Populated for simulation_model='importance_sampling'. Contains: tail_direction, target_threshold, tail_probability, tail_probability_se, cvar_tail, weighted_mean, weighted_std, theta (tilt parameter), tilt_variable, effective_sample_size, nominal_sample_size, variance_reduction_factor, naive_tail_count."
    },
    "scenario_ranking": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Scenario Ranking"
    },
    "sensitivity_ranking": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sensitivity Ranking"
    },
    "score": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Score"
    },
    "score_breakdown": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Score Breakdown"
    },
    "created_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Created At"
    },
    "decision_tree_result": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Decision Tree Result",
      "description": "Populated for simulation_model='decision_tree': n_paths, expected_value, paths[]"
    },
    "time_series_result": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Time Series Result",
      "description": "Populated for simulation_model='time_series'. Contains: model, granularity, dt_years, initial_value, n_steps, fan_chart (per-horizon p5/p25/p50/p75/p95), terminal distribution, max_drawdown_pct, and optional sample_paths for visualization."
    },
    "formatted_result": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Formatted Result",
      "description": "Human-readable formatted output values with units. Populated when output_unit_specs or unit_spec is provided. Contains: mean_formatted, p5_formatted, p95_formatted, unit, unit_type, etc."
    },
    "unit_context": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Unit Context",
      "description": "Unit metadata for all variables and outputs. Contains per-variable unit type, code, precision, and display scale. Use this to reconstruct formatted values client-side."
    },
    "unit_warnings": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Unit Warnings",
      "description": "Non-fatal unit validation warnings (e.g. negative currency, out-of-range probability). Simulation still ran — these are advisory only."
    },
    "charts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Charts",
      "description": "Pre-computed Vega-Lite compatible chart specs for instant rendering. Populated when include_charts=true in the request or automatically for sensitivity/time_series engine types. Keys: 'histogram', 'cdf', 'tornado', 'fan_chart', 'scatter'. Each value is a complete Vega-Lite spec that can be passed to vega-embed."
    },
    "histogram_data": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Histogram Data",
      "description": "Pre-computed histogram bins (50 bins) for the primary output distribution."
    },
    "decision_plan": {
      "anyOf": [
        {
          "$ref": "#/$defs/DecisionPlan"
        },
        {
          "type": "null"
        }
      ],
      "description": "Structured decision summary. Always populated by /v1/simulate and /v1/recommend. Contains: recommended_action, confidence, expected_value, risk (p5/p95/PoL), all ranked options, rationale, and integrity hashes."
    },
    "request_hash": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Request Hash",
      "description": "SHA-256 fingerprint of the INPUT payload (variables, distributions, objective function, seed). Cryptographic proof of what data was used to make this decision. Computed at submission time before simulation runs. Format: hex string, 64 chars."
    },
    "result_hash": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Result Hash",
      "description": "SHA-256 fingerprint of this decision OUTPUT (64-char hex). Covers: run_id, request_hash (input binding), recommended_action, confidence, rationale, metrics, percentiles, scenarios_run, engine_version, simulation_model. Binds the decision to both its inputs AND outputs. Use to verify the decision has not been tampered with. Also returned as X-Decision-Hash response header."
    }
  },
  "type": "object",
  "required": [
    "run_id",
    "engine_version",
    "recommended_action",
    "confidence",
    "rationale",
    "metrics",
    "percentiles",
    "scenarios_run",
    "execution_ms",
    "metadata"
  ],
  "$defs": {
    "DecisionOption": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name"
        },
        "rank": {
          "type": "integer",
          "minimum": 1.0,
          "title": "Rank"
        },
        "expected_value": {
          "type": "number",
          "title": "Expected Value"
        },
        "risk": {
          "$ref": "#/$defs/RiskProfile"
        },
        "score": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Score",
          "description": "Composite score (0–1)"
        }
      },
      "type": "object",
      "required": [
        "name",
        "rank",
        "expected_value",
        "risk"
      ],
      "title": "DecisionOption",
      "description": "One named alternative in a multi-option decision comparison."
    },
    "DecisionPlan": {
      "properties": {
        "recommended_action": {
          "type": "string",
          "title": "Recommended Action"
        },
        "confidence": {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0,
          "title": "Confidence"
        },
        "expected_value": {
          "type": "number",
          "title": "Expected Value"
        },
        "risk": {
          "$ref": "#/$defs/RiskProfile"
        },
        "options": {
          "items": {
            "$ref": "#/$defs/DecisionOption"
          },
          "type": "array",
          "title": "Options",
          "description": "All alternatives ranked by expected value. Single-element for simulate, multi for recommend."
        },
        "rationale": {
          "type": "string",
          "title": "Rationale"
        },
        "integrity": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Integrity",
          "description": "Cryptographic proof of inputs/outputs: {request_hash, result_hash}."
        },
        "calibration": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Calibration",
          "description": "Human-readable calibration summary, e.g. '12 outcomes | bias=-8.3% (over-optimistic) | hit_rate=75%'. Null until MIN_SAMPLES (5) outcomes are recorded for this org."
        },
        "repository_analysis": {
          "anyOf": [
            {
              "$ref": "#/$defs/RepositoryAnalysis"
            },
            {
              "type": "null"
            }
          ],
          "description": "Repository-intelligence context including root cause, candidate fixes, workspace evidence refs, patch impact, and token reduction metrics."
        }
      },
      "type": "object",
      "required": [
        "recommended_action",
        "confidence",
        "expected_value",
        "risk",
        "rationale"
      ],
      "title": "DecisionPlan",
      "description": "Structured, LLM-readable summary of the decision output.\n\nThis is the headline object — it surfaces all decision-critical fields\nin a compact, consistent shape regardless of simulation model used.\nPopulate ``options`` with all ranked alternatives when using /v1/recommend."
    },
    "MetricsSummary": {
      "properties": {
        "expected_value": {
          "type": "number",
          "title": "Expected Value"
        },
        "median": {
          "type": "number",
          "title": "Median"
        },
        "std_deviation": {
          "type": "number",
          "title": "Std Deviation"
        },
        "variance": {
          "type": "number",
          "title": "Variance"
        },
        "probability_of_loss": {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0,
          "title": "Probability Of Loss"
        },
        "var_95": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Var 95"
        },
        "cvar_95": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Cvar 95"
        }
      },
      "type": "object",
      "required": [
        "expected_value",
        "median",
        "std_deviation",
        "variance",
        "probability_of_loss"
      ],
      "title": "MetricsSummary"
    },
    "PercentileSummary": {
      "properties": {
        "p5": {
          "type": "number",
          "title": "P5"
        },
        "p10": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "P10"
        },
        "p25": {
          "type": "number",
          "title": "P25"
        },
        "p50": {
          "type": "number",
          "title": "P50"
        },
        "p75": {
          "type": "number",
          "title": "P75"
        },
        "p90": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "P90"
        },
        "p95": {
          "type": "number",
          "title": "P95"
        },
        "p99": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "P99"
        }
      },
      "type": "object",
      "required": [
        "p5",
        "p25",
        "p50",
        "p75",
        "p95"
      ],
      "title": "PercentileSummary"
    },
    "RepositoryAnalysis": {
      "properties": {
        "root_cause": {
          "type": "string",
          "title": "Root Cause"
        },
        "planner_model_id": {
          "type": "string",
          "title": "Planner Model Id"
        },
        "planner_execution_mode": {
          "type": "string",
          "title": "Planner Execution Mode"
        },
        "planner_provider_backend": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Planner Provider Backend"
        },
        "candidate_fixes": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Candidate Fixes"
        },
        "impacted_services": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Impacted Services"
        },
        "impacted_symbols": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Impacted Symbols"
        },
        "likely_failing_tests": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Likely Failing Tests"
        },
        "rollback_complexity": {
          "type": "string",
          "title": "Rollback Complexity"
        },
        "blast_radius": {
          "type": "string",
          "title": "Blast Radius"
        },
        "workspace_evidence_refs": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Workspace Evidence Refs"
        },
        "generated_patch_ref": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Generated Patch Ref"
        },
        "patch_impact_report_ref": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Patch Impact Report Ref"
        },
        "token_reduction_metrics": {
          "$ref": "#/$defs/TokenReductionMetrics"
        }
      },
      "type": "object",
      "required": [
        "root_cause",
        "planner_model_id",
        "planner_execution_mode",
        "rollback_complexity",
        "blast_radius",
        "token_reduction_metrics"
      ],
      "title": "RepositoryAnalysis",
      "description": "Repository-intelligence extension block for DecisionPlan."
    },
    "RiskProfile": {
      "properties": {
        "p5": {
          "type": "number",
          "title": "P5",
          "description": "5th-percentile outcome (downside risk floor)"
        },
        "p95": {
          "type": "number",
          "title": "P95",
          "description": "95th-percentile outcome (upside ceiling)"
        },
        "probability_of_loss": {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0,
          "title": "Probability Of Loss",
          "description": "P(outcome < 0)"
        },
        "var_95": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Var 95",
          "description": "Value-at-Risk at 95% confidence"
        }
      },
      "type": "object",
      "required": [
        "p5",
        "p95",
        "probability_of_loss"
      ],
      "title": "RiskProfile",
      "description": "Quantified downside and upside for a single outcome distribution."
    },
    "RunMetadata": {
      "properties": {
        "mode": {
          "type": "string",
          "title": "Mode"
        },
        "seed": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Seed"
        },
        "billing_units": {
          "type": "integer",
          "title": "Billing Units"
        },
        "engine_version": {
          "type": "string",
          "title": "Engine Version"
        }
      },
      "type": "object",
      "required": [
        "mode",
        "billing_units",
        "engine_version"
      ],
      "title": "RunMetadata"
    },
    "TokenReductionMetrics": {
      "properties": {
        "raw_repo_token_estimate": {
          "type": "integer",
          "minimum": 0.0,
          "title": "Raw Repo Token Estimate"
        },
        "evidence_bundle_token_count": {
          "type": "integer",
          "minimum": 0.0,
          "title": "Evidence Bundle Token Count"
        },
        "reduction_ratio": {
          "type": "number",
          "minimum": 1.0,
          "title": "Reduction Ratio"
        }
      },
      "type": "object",
      "required": [
        "raw_repo_token_estimate",
        "evidence_bundle_token_count",
        "reduction_ratio"
      ],
      "title": "TokenReductionMetrics",
      "description": "Token-budget compression produced by deterministic repository narrowing."
    }
  }
}