feat(library): six book-control rules for the risk category - #13
Merged
Conversation
The risk category shipped one rule, max_drawdown_breaker — which is also the
rule now sitting above the fold in the README, because it is the one that shows
host governance without implying a trade. The category that best demonstrates
the product had the least in it.
Adds six controls, each with a distinct failure it is the only rule to catch:
daily_loss_limit DAY_LOSS_PCT >= 2
position_concentration_cap MAX_POSITION_PCT >= 25
correlation_cluster_guard CLUSTER_EXPOSURE_PCT >= 40
stale_data_halt FEED_AGE_SEC >= 30
leverage_ceiling GROSS_LEVERAGE >= 3
consecutive_loss_circuit CONSECUTIVE_LOSSES >= 4
All six emit only pause/observe and escalate to a named agent — none proposes a
direction, so the category carries no performance or advice implication.
Every series is nonnegative and rises as the situation worsens, so each control
is a >= against a ceiling. Same direction on every rule makes a stack of them
readable at a glance, and the new "Book-control signals" table in the library
README documents the feed contract for all six.
The comment headers carry the distinctions that make the rules worth having
separately, rather than restating the threshold:
- daily_loss_limit vs max_drawdown_breaker: peak-to-trough over the book's
life can sit quiet through a catastrophic day if the book was up first.
- position_concentration_cap vs leverage_ceiling: distribution vs total size.
A 1x book entirely in one name passes the leverage limit.
- correlation_cluster_guard vs position_concentration_cap: one instrument vs
many instruments that are the same bet.
- stale_data_halt vs event_liquidity_halt: can the book be traded, vs are the
numbers real at all.
- consecutive_loss_circuit vs daily_loss_limit: sequence vs magnitude. Four
small losses can cost almost nothing and still be the clearest evidence the
regime changed.
IR fixtures are generated from compile_to_dict rather than hand-written, so the
pairs match byte-for-byte by construction.
Five execution tests cover the behaviour worth pinning: the >= boundary fires
(a limit that only trips past its number lets a book sit on the limit), stale
data emits PAUSE before OBSERVE in log order, concentration and leverage each
stay silent on the other's failure, and a losing streak that resets never trips
the circuit.
401 passed, 2 skipped. Library 26 -> 32 strategies.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The
risk/category shipped one rule —max_drawdown_breaker, which is also the rule now sitting above the fold in the README, because it's the one that demonstrates host governance without implying a trade.So the category that best sells the product had the least in it. This fills it.
What's added
daily_loss_limitDAY_LOSS_PCT>= 2position_concentration_capMAX_POSITION_PCT>= 25correlation_cluster_guardCLUSTER_EXPOSURE_PCT>= 40stale_data_haltFEED_AGE_SEC>= 30leverage_ceilingGROSS_LEVERAGE>= 3consecutive_loss_circuitCONSECUTIVE_LOSSES>= 4All six emit only
pause/observeand escalate to a named agent. None proposes a direction, so the category carries no performance or advice implication — and it stays inside baseline IR (AND-only thresholds over host-supplied series).One design decision worth calling out
Every series is nonnegative and rises as the situation worsens, so each control is a
>=against a ceiling. The same direction on every rule is what makes a stack of them readable at a glance — you never have to work out which way a given control points. The new Book-control signals table in the library README documents the feed contract for all six.The headers carry the distinctions, not the thresholds
The threshold is visible in the source. What isn't visible is why each rule exists separately, so that's what the comment headers argue:
daily_loss_limitvsmax_drawdown_breaker— peak-to-trough over the book's life can sit perfectly quiet through a catastrophic single day, if the book was up beforehand.position_concentration_capvsleverage_ceiling— distribution vs total size. A 1x-gross book entirely in one name passes the leverage limit cleanly.correlation_cluster_guardvsposition_concentration_cap— one instrument, vs many instruments that are secretly the same bet.stale_data_haltvsevent_liquidity_halt— can the book be traded, vs are the numbers describing it real at all. A liquid market with a dead feed passes that rule and fails this one.consecutive_loss_circuitvsdaily_loss_limit— sequence vs magnitude. Four small losses can cost almost nothing and still be the clearest evidence available that the regime changed.Verification
IR fixtures are generated from
compile_to_dict, not hand-written, so the.nano/_ir.jsonpairs match byte-for-byte by construction rather than by care.Five execution tests pin the behaviour that would otherwise rot silently:
>=boundary fires — a limit that only trips past its number lets a book sit exactly on the limit indefinitelystale_data_haltemitsPAUSEbeforeOBSERVE, because the ordered run log is the product401 passed, 2 skipped(was 378). Library 26 → 32 strategies.Not included
No new category, no grammar change, no performance claims. The corpus disclaimer — "a conformance corpus, not a performance claim, live signal service, or trading recommendation" — stands unchanged and now covers seven risk rules instead of one.