Skip to content

feat(library): six book-control rules for the risk category - #13

Merged
AetherAI3 merged 1 commit into
mainfrom
feat/nano-risk-corpus
Aug 14, 2026
Merged

feat(library): six book-control rules for the risk category#13
AetherAI3 merged 1 commit into
mainfrom
feat/nano-risk-corpus

Conversation

@AetherAI3

Copy link
Copy Markdown
Owner

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

Rule Signal Ceiling
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 — 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_limit vs max_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_cap vs leverage_ceiling — distribution vs total size. A 1x-gross book entirely in one name passes the leverage limit cleanly.
  • correlation_cluster_guard vs position_concentration_cap — one instrument, vs many instruments that are secretly the same bet.
  • stale_data_halt vs event_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_circuit vs daily_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.json pairs match byte-for-byte by construction rather than by care.

Five execution tests pin the behaviour that would otherwise rot silently:

  • the >= boundary fires — a limit that only trips past its number lets a book sit exactly on the limit indefinitely
  • stale_data_halt emits PAUSE before OBSERVE, because the ordered run log is the product
  • concentration and leverage each stay silent on the other's failure, proving they aren't redundant
  • a losing streak that resets never trips the circuit — a rule counting losses rather than runs would fire there

401 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.

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.
@AetherAI3
AetherAI3 merged commit 23827e2 into main Aug 14, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant