Metadata-Version: 2.4
Name: balabs-risk-kernel
Version: 0.1.1
Summary: Risk model v2 liquidation kernel — pure compute, no DB access
Author-email: Twigmaester <81682766+Twigmaester@users.noreply.github.com>
Requires-Python: <3.15,>=3.13
Requires-Dist: numpy<3,>=2.1
Description-Content-Type: text/markdown

# risk-kernel

The risk model v2 liquidation-simulation kernel as a standalone package —
pure compute (numpy + stdlib), zero DB access, no write path. Powers the
on-demand LTV↔CRR estimator endpoint in `core-api` (office #490).

The kernel operates on in-memory `PricePaths` / `SellOrderbook` /
`BorrowerPosition` structures (`risk_kernel.liquidator.types`); loading those
inputs from a database is the consumer's job, never this package's.

## Consumers

- **core-api** — installs this package from PyPI (`risk-kernel`) and runs the
  kernel in-process for the estimator endpoint.
- **core** — NOT hooked up yet, deliberately out of scope for now. core keeps
  its own in-tree copy at `src/risk_model_v2/liquidator/` and remains the
  production source of truth for kernel logic.

## Source of truth & sync protocol

Until core itself consumes this package, this repo is a **mirror** of core's
kernel, pinned to:

- source: **blockanalitica/core** `src/risk_model_v2/liquidator/`
- commit: **`c0bb2732e51cbb2338e0db5f49799088529e003c`** (main, 2026-07-03)

Kernel changes land in **core first** (production model), then get pulled
here:

```sh
git -C ../core diff <pinned-commit>..main -- src/risk_model_v2/liquidator/
```

Apply the changes to `src/risk_kernel/`, bump the pin above and the package
version, then bump the pin in consumers. The divergences below are expected
diff noise; everything else must match, e.g.:

```sh
diff -r ../core/src/risk_model_v2/liquidator/ src/risk_kernel/liquidator/
```

There is no test guardrail — the pin is the only drift baseline.

## Deliberate divergences from core (the ONLY ones allowed)

1. **Persistence stripped** from `liquidator/pipeline/processors/liquidator.py`:
   the `_persist_market_crr` / `_persist_scenario_paths` /
   `_rewrite_market_crr_tiers` / `_prune_market_crr_snapshot24` methods, their
   call sites in `sync()`, the `risk_model_v2.models` import block, and the
   imports only they used (`asdict`, `timedelta`,
   `MARKET_CRR_SNAPSHOT24_RETENTION_DAYS`, `CapturedScenarioPaths`,
   `select_bands`). `sync()` computes and returns `CRRSummary` objects,
   nothing else. `pipeline/scenario_paths.py` is unused after the strip but
   kept verbatim so the drift diff stays trivial.
2. **Package renamed**: core's `risk_model_v2.liquidator` → `risk_kernel.liquidator`
   (mechanical import rewrite; tree structure is otherwise 1:1 so the diff
   above works).
3. **`constants.py` is a 3-constant subset** of core's
   `src/risk_model_v2/constants.py` (`FORECAST_STEP`, `N_MC`, `SEED`) — the
   only values the kernel imports from outside the liquidator subtree.

Anything else diverging from core = drift = bug.
