balabs-risk-kernel 0.2.1

Risk model liquidation kernels (v2 + v3) — pure compute, no DB access

risk-kernel

The risk model liquidation kernels 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 / #537).

Two model namespaces, mirrored from core:

• risk_kernel.v2 — the v2 liquidation-simulation kernel. Operates on in-memory PricePaths / SellOrderbook / BorrowerPosition structures (risk_kernel.v2.liquidator.types).
• risk_kernel.v3 — the v3 market-clearing kernel: clearing kernel, impact law, CRR stats, liquidation-wall curve math, FHS residuals/simulator. Entry points risk_kernel.v3.kernel.run_clearing_kernel / run_multi_asset_kernel on KernelInputs / MultiAssetKernelInputs.

Loading inputs from a database is the consumer's job, never this package's.

Consumers

• core-api — installs this package from PyPI (balabs-risk-kernel) and runs the kernels in-process for the estimator endpoint.
• core — NOT hooked up yet, deliberately out of scope for now. core keeps its own in-tree copies at src/risk_model_v2/ and src/risk_model_v3/ 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 kernels. Per-model pins (the subtrees sync at different cadences):

• v2 source: blockanalitica/core src/risk_model_v2/liquidator/ commit: c0bb2732e51cbb2338e0db5f49799088529e003c (main, 2026-07-03)
• v3 source: blockanalitica/core src/risk_model_v3/ commit: 0d0695dda00bafe99ad3294958203a7da98f76fd (PR #78, 2026-07-13)

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

git -C ../core diff <v2-pinned-commit>..main -- src/risk_model_v2/liquidator/
git -C ../core diff <v3-pinned-commit>..main -- src/risk_model_v3/

Apply the changes to src/risk_kernel/v2/ / src/risk_kernel/v3/, bump the model's 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.:

diff -r ../core/src/risk_model_v2/liquidator/ src/risk_kernel/v2/liquidator/
diff -r ../core/src/risk_model_v3/ src/risk_kernel/v3/

There is no test guardrail — the pins are the only drift baseline.

Deliberate divergences from core (the ONLY ones allowed)

v2

1. Persistence stripped from v2/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.v2.liquidator (mechanical import rewrite; tree structure is otherwise 1:1 so the diff above works).
3. v2/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 kernels import from outside the mirrored subtrees.

v3

1. Impure modules excluded — only the pure compute modules are mirrored: kernel, impact, stats, types, constants, liquidation_wall/{builder,flow,types}, fhs/{residuals,simulator}. Excluded: models, persistence, pipeline/, tasks, calibration, liquidation_wall/{fetcher,sources}, fhs/forecaster. Mirrored modules import only numpy/stdlib/each other (v3 → v2.constants allowed, mirroring core's fhs/simulator.py).
2. Package renamed: core's risk_model_v3 → risk_kernel.v3, risk_model_v2 → risk_kernel.v2 (mechanical import rewrite, applies to docstrings too).

Anything else diverging from core = drift = bug.