# Capacity-Aware Capital Allocator — Design

**Date:** 2026-07-15
**Status:** Design. A focused UPGRADE of the existing B2a allocation engine — not a new system.
**Author:** jgrusewski (+ Claude)
**Builds on:** `docs/superpowers/specs/2026-07-15-crypto-honest-reference-pipeline-design.md` (merged 20437d7).

## 1. Problem

We are running a small, growing multi-edge fund across two venues (Bybit crypto sleeves + an IBKR equity
book). The honest-reference pipeline (merged) proved the edges are real at low capital but revealed hard
**capacity ceilings** — e.g. `xsfunding` is strong at $35k (Sh 3.5) but **breaks by ~$350k–$1M** (Sh → −2.5).
The existing allocation engine (`allocation_engine.compute_allocation`, sub-project B2a) is **capacity-blind**:
it sizes edges equal-weight (capped at a flat `max_strategy_weight`) + an ex-ante vol-target, with no knowledge
that an edge stops working above a dollar figure. A growing fund would keep pouring capital into a
capacity-limited edge past its break.

## 2. Goal

Make the allocation **capacity-aware and risk-parity weighted**, so the fund allocates its pot correctly across
edges within each edge's honest capacity — and, as the pot grows past an edge's ceiling, shifts automatically to
the capacity-robust edges. Minimal, SSOT-respecting upgrade of the existing engine; **no new allocation
system**. Scope stays PAPER (the `capital_ceiling` human gate + forward-gate promotion already enforce this).

## 3. What already exists (verified 2026-07-15) — reuse, do not rebuild

`allocation_ingest.record_allocation(dsn, equity)` already:
- allocates over **deploy-tier + forward-promoted** strategies (`evaluate_promotions` promotes on gate PASS) —
  **this IS the forward-gating**; a not-yet-passed edge gets $0;
- is **cross-venue** — `returns = {sid: {date: ret}}` keyed by strategy id spans crypto + IBKR uniformly;
- **de-funds decaying edges** (B3 `compute_funding`), applies the **rare drawdown killswitch**, and an **ex-ante
  vol-target** leverage `K` (`AllocationPolicy`: target_vol 0.12, kelly_fraction 0.5, max_leverage 1.5,
  cvar_alpha 0.10, `max_strategy_weight` 0.5, `capital_ceiling` $35k) sized from **full-history** vol (never
  trailing — the anti-reactive invariant);
- writes `StrategyAllocationRow(target_weight, target_dollars)` which the rebalancers (`execute-multistrat`,
  `execute-bybit`) consume to size.

So the allocator's plumbing, gating, cross-venue combination, decay, killswitch, and $ conversion are DONE.

## 3.5 Current gate reality (investigated 2026-07-15) — why the sizing basis must change

Live state of the paper edges:
- **Deploy-tier = only `bybit_4edge` (book) + `positioning`** (both crypto, both currently `WAIT`, building
  8/21 and 8/14 days). `multistrat` (IBKR) is tier=research, `WAIT` 6/20 — it joins the allocation only when
  promoted. `unlock` is `PASS` but tier=research with no `promote_on_pass`, so it is not in the deploy set
  (it lives inside the `bybit_4edge` book).
- **`strategy_allocation` is currently EMPTY (0 rows).** Root cause: `compute_allocation` requires
  `min_history_days = 60` FORWARD observations for a stable ex-ante vol, but the 2026-07-14 re-warm reset the
  forward tracks to ~8 days. 8 < 60 → not eligible → empty allocation. Under the current design the allocation
  would not populate until ~60 forward days (~mid-September) — far later than the forward gates themselves
  (14–21 days, late July / early August).

**Consequence:** sizing off the 8-day forward record is both impossible (too short) and, after any future
re-inception, self-defeating. But the honest-reference has 1,290–1,992 days of stable, capacity-adjusted
history. So the sizing basis must move to the backtest (§4c).

## 4. The three changes

### 4a. Weighting: equal-weight → inverse-vol (risk-parity), capped
In `compute_allocation`, replace the equal-weight `base` with **inverse-full-history-vol** weights, still capped
at `max_strategy_weight` (the concentration prudence cap) and still NO-renormalise when the cap binds. Rationale
(decided with the user): risk-parity gives better risk-adjusted return and is adaptive/not-tuned (reuses the
existing `full_history_vol`), but a **firm concentration cap (~0.4–0.5)** is kept because this is a young fund
whose edges are not yet forward-proven — do not bet the fund on one edge (the honest-reference's unconstrained
risk-parity put 0.89 in `xsfunding`; that is a backtest weight, not a fund weight). Diversify across edges,
concentrate only as the forward tracks confirm which edge is real.

### 4b. Capacity: a per-strategy dollar ceiling from the honest-reference
Add a per-strategy `capacity_ceiling[sid]` and cap each edge's dollars at `min(target_dollars,
capacity_ceiling[sid])` in `target_capital` (or as a post-step). The ceiling per edge = the AUM at which the
honest-reference Sharpe crosses a viability threshold (e.g. the largest AUM on the capacity curve with honest
Sharpe ≥ `capacity_min_sharpe`, default 1.0). This makes growth automatic: below the ceiling the cap is
non-binding; as equity grows into it, the capped edge holds cash / the allocation shifts to capacity-robust
edges. Un-capped (no honest curve) → no ceiling (unbounded), logged.

### 4c. Sizing basis: the honest-reference backtest, not the 8-day forward record
`compute_allocation`'s ex-ante vol (and the new inverse-vol weighting) must be computed from the
**honest-reference backtest return series** (capacity-adjusted, at the target AUM — 1,290–1,992 days, stable),
NOT from `nav_history` (the forward record, ~8 days post-re-warm → fails `min_history_days`). The **forward
gate stays the LIVE-DEPLOY switch**: `record_allocation` still allocates real (paper) dollars only to deploy +
forward-promoted edges. So the honest target allocation is computable and visible NOW (backtest-sized +
capacity-capped), while capital is only deployed to an edge once its forward gate passes — exactly "honest
weights now, live per gate". Implementation: `record_allocation` builds `returns` from the honest-reference
series (via a provider) rather than `nav_history`; the `min_history_days` eligibility is then trivially met by
the long backtest. Keep `nav_history`-based sizing available behind the provider so a mature forward track
(≥ `min_history_days` real days) can later blend/replace the backtest (a documented follow-on, not v1).

## 5. Granularity & cross-asset capacity (the load-bearing design decision)

The allocation runs over deploy **strategies** (`bybit_4edge` book, `positioning`, `multistrat`), but the
honest-reference capacity is per **sleeve** (`xsfunding`/`positioning`/`unlock`) and is **crypto-specific**
(Bybit `turnover` ADV). Resolution for v1:
- **Crypto book (`bybit_4edge`):** extend the honest-reference to emit a **book-level** capacity ceiling (run
  the honest-cost pipeline over the book's constituent sleeves, take the book's honest capacity curve). Its
  ceiling is the min of the constituents' effective ceilings, roughly (the book breaks when its biggest
  capacity-limited sleeve does).
- **`positioning`** (deploy sleeve, tracked directly): use its own sleeve capacity curve (ceiling >> $10M in the
  tested range — effectively unbounded at fund scale).
- **`multistrat` (IBKR equity):** the crypto ADV model does NOT apply (equities, different data). US-ETF ADV is
  deep, so v1 assigns a **high default ceiling** (a documented constant, e.g. $10M) and flags that a proper
  equity-ADV capacity model is a follow-on. Do NOT fabricate a crypto-style number for it.

This mapping (deploy-strategy → capacity ceiling) is the crux; it must be explicit and auditable, not implicit.

## 6. Forward-gating (user decision: "honest weights now, live switch per gate")

Two separate surfaces, already aligned:
- **Honest target for ALL edges (now, paper):** the honest-reference report shows the full honest picture across
  every edge (already built).
- **Deployed allocation (live/paper $):** `record_allocation` only allocates to deploy + forward-**promoted**
  edges. As each edge's forward gate PASSes (`evaluate_promotions`), it enters the allocation and earns capital.
  Real money follows proven forward performance; nothing here changes that.

## 7. Scope

**In:** the two `compute_allocation`/`target_capital` changes; the honest-reference emitting per-deploy-strategy
capacity ceilings; wiring the ceilings into `record_allocation`; policy knobs (`capacity_min_sharpe`, the
equity default ceiling); tests. **Out (follow-on):** a real equity-ADV capacity model for IBKR; raising the
`capital_ceiling` above $35k / going live (a deliberate human gate, per-edge on gate PASS + creds); any new
execution path.

## 8. Critical review — where this could go wrong

- **Sharpe-4 is not yet forward-proven.** The honest backtest is strong but the forward tracks just re-warmed.
  The concentration cap (§4a) and forward-gating (§6) are the two guards; do not remove them to chase the
  backtest weight.
- **Capacity ceiling is threshold-sensitive.** "Sharpe ≥ 1.0" is a choice; the curve is steep for `xsfunding`
  (3.5 → 0.28 → −2.5 across $35k/$350k/$1M), so the ceiling lands ~$350k either way, but report the ceiling
  next to the curve so the choice is visible, not buried.
- **Book-vs-sleeve capacity is an approximation.** The `bybit_4edge` book capacity ≠ a clean sum of sleeve
  capacities; state the derivation and its limits.
- **Equity capacity is a stub in v1** (high default). Be honest that the IBKR ceiling is not yet modeled.
- **Sizing from the BACKTEST, not the live record (§4c).** Necessary today (8-day forward is too short), but it
  means the ex-ante vol/weights reflect the honest backtest, not live performance — the two can diverge. The
  forward gate (live-deploy switch) + the funding-decay layer are the guards that catch a live divergence; the
  sizing basis should switch to live vol once a forward track is long enough (documented follow-on). Do not
  read the backtest-sized weights as "what the live book is doing".
- **Still a backtest-derived ceiling on a live allocation.** The capacity cap protects against over-scaling a
  known-limited edge; it cannot protect against an edge decaying — that is the funding-decay layer's job (which
  already exists). Don't conflate the two.

## 9. Decisions locked (from brainstorming)

- Weighting: **inverse-vol (risk-parity) capped at `max_strategy_weight`**. Sizing basis: **the honest-reference
  backtest series (§4c), NOT the 8-day forward record**; forward gate = live-deploy switch only. Forward-gating:
  **honest weights shown now for all edges; deployed $ only to forward-promoted edges** (existing). Capacity:
  **per-deploy-strategy ceiling from the honest-reference (crypto), high default for equity (v1)**. Scope:
  **paper**, an upgrade of the B2a engine, no new system.
