# `DeltaCalc.MarginBridge`
[🔗](https://github.com/ZenHive/delta_calc/blob/v0.3.0/lib/delta_calc/margin_bridge.ex#L1)

Pure margin-bridge formulas for perp-funded option financing.

Computes margin usage ratios, runway, payback timelines, negative-funding stress,
and funding kill-switch conditions using Decimal arithmetic throughout.

## API Functions
| Function | Arity | Description | Param Kinds |
| --- | --- | --- | --- |
| `check_kill_switch` | 3 | Evaluate daily-normalized negative funding plus high margin usage. | `per_period_funding_rate: value`, `margin_ratio: value`, `opts: value` |
| `stress_test_prolonged_negative` | 4 | Stress-test prolonged negative funding: rate × position × days. | `negative_rate: value`, `position_size: value`, `duration_days: value`, `opts: value` |
| `payback_timeline` | 3 | Single-scenario payback: days to payoff and optional projected payoff date from daily funding. | `remaining_debt: value`, `daily_funding: value`, `opts: value` |
| `margin_runway_days` | 2 | Estimate days until margin is exhausted at the current daily burn rate. | `available_margin: value`, `daily_burn: value` |
| `margin_ratio` | 3 | Compute margin usage as (initial_margin + option_premium) / capital. | `initial_margin: value`, `option_premium: value`, `capital: value` |

# `kill_switch_result`

```elixir
@type kill_switch_result() :: %{
  per_period_funding_rate: Decimal.t(),
  periods_per_day: Decimal.t(),
  daily_funding_rate: Decimal.t(),
  margin_ratio: Decimal.t(),
  daily_funding_threshold: Decimal.t(),
  margin_threshold: Decimal.t(),
  kill_switch_triggered: boolean()
}
```

Kill-switch evaluation for margin bridge safety.

# `payback_timeline`

```elixir
@type payback_timeline() :: %{
  remaining_debt: Decimal.t(),
  daily_funding: Decimal.t(),
  days_to_payoff: Decimal.t() | nil,
  projected_payoff_date: Date.t() | nil
}
```

Payback projection from remaining debt and daily funding income.

# `stress_test_result`

```elixir
@type stress_test_result() :: %{
  negative_rate: Decimal.t(),
  position_size: Decimal.t(),
  duration_days: pos_integer(),
  daily_cost: Decimal.t(),
  total_cost: Decimal.t(),
  kill_switch_day: pos_integer() | nil
}
```

Negative-funding stress scenario over a duration.

# `check_kill_switch`

```elixir
@spec check_kill_switch(
  DeltaCalc.Decimal.input(),
  DeltaCalc.Decimal.input(),
  keyword()
) ::
  kill_switch_result()
```

Return kill-switch status after normalizing per-period funding to a daily fraction.

The comparison is `per_period_funding_rate * periods_per_day < daily_funding_threshold`.
The default cadence of 3, daily threshold of `-0.0006`, and margin threshold of
`0.25` are conventions; each is overridable through `opts`.

# `margin_ratio`

```elixir
@spec margin_ratio(
  DeltaCalc.Decimal.input(),
  DeltaCalc.Decimal.input(),
  DeltaCalc.Decimal.input()
) ::
  Decimal.t()
```

Return `(initial_margin + option_premium) / capital`, or zero when capital is non-positive.

# `margin_runway_days`

```elixir
@spec margin_runway_days(DeltaCalc.Decimal.input(), DeltaCalc.Decimal.input()) ::
  Decimal.t() | nil
```

Return `available_margin / daily_burn`, or nil when burn is non-positive.

# `payback_timeline`

```elixir
@spec payback_timeline(
  DeltaCalc.Decimal.input(),
  DeltaCalc.Decimal.input(),
  keyword()
) ::
  payback_timeline()
```

Compute single-scenario payback days from `remaining_debt` and `daily_funding`.

Pass `from_date:` in opts to include `projected_payoff_date`.
`days_to_payoff` preserves Decimal precision; date projection alone rounds up
because a `Date` is an intrinsic whole-day boundary.
For best/expected/worst cases under funding volatility, use
`DeltaCalc.FundingProjection.project_payback_timeline/1`.

# `stress_test_prolonged_negative`

```elixir
@spec stress_test_prolonged_negative(
  DeltaCalc.Decimal.input(),
  DeltaCalc.Decimal.input(),
  pos_integer(),
  keyword()
) :: stress_test_result()
```

Compute daily and total funding cost under prolonged negative rates.

`negative_rate` is a decimal fraction per funding period (e.g. `-0.00025` for
`-0.025%`), matching `Funding`/`Hedging` — not a percent number. Scale to daily
cost with `periods_per_day`. Its default of 3 is an overridable cadence convention.
`kill_switch_day`, when requested, rounds up because it identifies the first
whole calendar day on which the threshold is crossed.

---

*Consult [api-reference.md](api-reference.md) for complete listing*