Decide what the deposit cap limits #294

Priority

Medium — should be addressed soon

User story / Problem statement

The deposit cap limits deposited capital: what the vault holds plus net_deployed(), less committed(). That figure counts money in and out, not the vault's value. A deposit request adds what it brings, and a priced redemption takes off what it pays, gain or loss included. A gain or a loss at the custodian does not move it.

So the cap drifts away from what the vault manages:

• Once leavers are paid a gain, the figure can go negative, and the cap admits more than its own amount. On the testnet vault deployed on 2026-10-20, the custodian funded back 1,550 USDC more than it was sent. The vault holds 1,272.07, net_deployed is −1,550 and committed is 0, so deposited capital is −277.93 and the 10,000 cap admits a 10,277.93 deposit.
• After a loss, the figure stays above the vault's value, and the cap refuses deposits sooner. Nothing writes a loss off net_deployed().

As an operator, I want the cap to limit what the vault manages, so that a vault that pays out gains does not grow past its cap, and a vault that took a loss is not held below it.

#278 documents today's behaviour and pins it with a_gain_paid_out_to_leavers_leaves_room_above_the_cap and a_loss_at_the_custodian_still_counts_toward_the_cap.

Expected outcome

A recorded decision on what the cap limits, with the vault, the docs and the tests matching it. If the decision is to keep counting money in and out, the docs from #278 stand and this issue closes with that decision.

Acceptance criteria

• The decision is recorded in this issue
• If the measure changes, request_deposit checks the new measure, and tests cover a gain paid out and a loss
• The kit spec's Supply and Capital Figures section and the design doc say what the cap limits and how far it can drift from the vault's value

Alternatives considered

• Value from the last price: the latest priced epoch's share_price applied to the shares holders own, including those escrowed by an unpriced redemption, plus unpriced deposit requests. The vault already stores each epoch's price, so a deposit request needs no oracle call. It lags the market until the next epoch is priced.
• Value from the oracle: current, but every deposit request calls the oracle and needs a rule for a stale feed or a raised NAV pause.
• A floor at zero on today's figure: one line. It removes the negative case only; the cap still drifts with gains and losses.
• Keep counting money in and out: no code change. Governance moves the cap by hand, which is instant both ways.

Technical notes

• Today's code: treasury::deposited_capital and guards::within_cap. The checked math there stops an overflow, not a negative result.
• The console should not present deposited capital as the vault's value.