---
title: "Simulate an in-flight working-tree patch (no stored decision plan)"
method: POST
path: "/v1/repositories/{repository_id}/simulate-patch"
tags: ["Repository Intelligence"]
---

# Simulate an in-flight working-tree patch (no stored decision plan)

`POST /v1/repositories/{repository_id}/simulate-patch`

## Request

- Base URL: `https://api.algenta.ai`
- URL: `https://api.algenta.ai/v1/repositories/{repository_id}/simulate-patch`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Path parameters

- `repository_id` string, uuid, required

## Request body

- RepositorySimulatePatchRequest: Simulate an in-flight working-tree patch directly (no stored decision plan) — used by the verified_agentic agent's simulate_patch tool to verify mid-run.
  - `snapshot_id` string, required
  - `patch_diff` string, required
  - `confidence` number, nullable

## Response `200`

Successful Response

- DecisionEnvelope: Full decision output returned by /v1/simulate, /v1/recommend, and /v1/score.
  - `run_id` string, uuid, required
  - `status` string
  - `engine_version` string, required
  - `recommended_action` string, required
  - `confidence` number, required
  - `rationale` string, required
  - `metrics` MetricsSummary, required
    - `expected_value` number, required
    - `median` number, required
    - `std_deviation` number, required
    - `variance` number, required
    - `probability_of_loss` number, required
    - `var_95` number, nullable
    - `cvar_95` number, nullable
  - `percentiles` PercentileSummary, required
    - `p5` number, required
    - `p10` number, nullable
    - `p25` number, required
    - `p50` number, required
    - `p75` number, required
    - `p90` number, nullable
    - `p95` number, required
    - `p99` number, nullable
  - `scenarios_run` integer, required
  - `execution_ms` integer, required
  - `metadata` RunMetadata, required
    - `mode` string, required
    - `seed` integer, nullable
    - `billing_units` integer, required
    - `engine_version` string, required
  - `simulation_model` string: Which simulation algorithm was used. Possible values: monte_carlo | qmc_sobol | lhs | bootstrap | scenario | sensitivity | mcmc | decision_tree | time_series | compare | importance_sampling
  - `engine_type` string, nullable: Engine that ran the simulation (e.g. 'mojo-native-expr', 'lhs', 'mcmc')
  - `simulation_class` string: High-level simulation contract class. Examples: predictive, scenario_analysis, sensitivity_analysis, decision_tree.
  - `model_revision` string, nullable: Stable engine or model revision used to generate this result.
  - `assumptions_hash` string, nullable: Stable fingerprint of the validated simulation assumptions executed by the engine.
  - `validated_inputs` object, nullable: Normalized summary of the validated request inputs used for execution. Includes mode, runs, variable counts, and model selection.
  - `confidence_interval` object, nullable: Primary outcome confidence interval derived from the simulated distribution.
  - `request_id` string, nullable: Correlation identifier propagated from the API request.
  - `scenario_analysis` object, nullable: Populated for simulation_model='scenario': expected_value, best_case, scenarios list
  - `sensitivity_analysis` object, nullable: Populated for simulation_model='sensitivity': tornado_chart, first_order_sobol, variable_importance
  - `bootstrap_result` object, nullable: Populated for simulation_model='bootstrap': statistic, observed_value, CI, bias, SE
  - `mcmc_result` object, nullable: Populated for simulation_model='mcmc': posterior summaries, R-hat, acceptance_rate
  - `importance_sampling_result` object, nullable: 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` object[], nullable
  - `sensitivity_ranking` object[], nullable
  - `score` number, nullable
  - `score_breakdown` object, nullable
  - `created_at` string, date-time, nullable
  - `decision_tree_result` object, nullable: Populated for simulation_model='decision_tree': n_paths, expected_value, paths[]
  - `time_series_result` object, nullable: 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` object, nullable: 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` object, nullable: 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` string[], nullable: Non-fatal unit validation warnings (e.g. negative currency, out-of-range probability). Simulation still ran — these are advisory only.
  - `charts` object, nullable: 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` object, nullable: Pre-computed histogram bins (50 bins) for the primary output distribution.
  - `decision_plan` DecisionPlan: Structured, LLM-readable summary of the decision output. This is the headline object — it surfaces all decision-critical fields in a compact, consistent shape regardless of simulation model used. Populate ``options`` with all ranked alternatives when using /v1/recommend.
    - `recommended_action` string, required
    - `confidence` number, required
    - `expected_value` number, required
    - `risk` RiskProfile, required: Quantified downside and upside for a single outcome distribution.
      - `p5` number, required: 5th-percentile outcome (downside risk floor)
      - `p95` number, required: 95th-percentile outcome (upside ceiling)
      - `probability_of_loss` number, required: P(outcome < 0)
      - `var_95` number, nullable: Value-at-Risk at 95% confidence
    - `options` DecisionOption[]: All alternatives ranked by expected value. Single-element for simulate, multi for recommend.
      - `name` string, required
      - `rank` integer, required
      - `expected_value` number, required
      - `risk` RiskProfile, required: Quantified downside and upside for a single outcome distribution.
        - `p5` number, required: 5th-percentile outcome (downside risk floor)
        - `p95` number, required: 95th-percentile outcome (upside ceiling)
        - `probability_of_loss` number, required: P(outcome < 0)
        - `var_95` number, nullable: Value-at-Risk at 95% confidence
      - `score` number, nullable: Composite score (0–1)
    - `rationale` string, required
    - `integrity` object, nullable: Cryptographic proof of inputs/outputs: {request_hash, result_hash}.
    - `calibration` string, nullable: 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` RepositoryAnalysis: Repository-intelligence extension block for DecisionPlan.
      - `root_cause` string, required
      - `planner_model_id` string, required
      - `planner_execution_mode` string, required
      - `planner_provider_backend` string, nullable
      - `candidate_fixes` string[]
      - `impacted_services` string[]
      - `impacted_symbols` string[]
      - `likely_failing_tests` string[]
      - `rollback_complexity` string, required
      - `blast_radius` string, required
      - `workspace_evidence_refs` string[]
      - `generated_patch_ref` string, nullable
      - `patch_impact_report_ref` string, nullable
      - `token_reduction_metrics` TokenReductionMetrics, required: Token-budget compression produced by deterministic repository narrowing.
        - `raw_repo_token_estimate` integer, required
        - `evidence_bundle_token_count` integer, required
        - `reduction_ratio` number, required
  - `request_hash` string, nullable: 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` string, nullable: 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.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/codna/apis/algenta-api.md) · [All operations](https://skmtc.dev/codna/apis/algenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/codna/apis/algenta-api/revisions/35d30f84a5df?raw)