aether-quant 0.0.1__py3-none-any.whl

risk/manual_override.py

@@ -0,0 +1,118 @@
+"""Manual trade-lock override for Aether Quant V2.
+
+`main.py`'s sticky total-drawdown lock (see `_refresh_risk_state()`) never
+auto-clears on its own once tripped - by design, a capital-preservation
+circuit breaker requiring a deliberate decision to resume trading. This
+module is that deliberate decision, expressed as a single config value:
+`phase_v2.risk.manual_trade_lock_override` (`true` = force-lock, `false` =
+force-clear, absent/`null` = leave today's automatic behavior untouched).
+
+Two callers, both read-modify-write the same key:
+- `aq_cli.py`'s `trade-lock` command - a human flips the switch directly.
+- `retraining/orchestrator.py::promote()` - a successful promotion clears it
+  automatically, tying "trading resumes" to "a genuinely new model shipped".
+
+This is the first place in the codebase where a Python process writes to
+`config.json` (every other reader treats it as human-edited, read-only
+input) - a deliberate, narrow exception, not a new general pattern. It is a
+*standing* switch, not one-shot: it stays in effect until explicitly changed
+again, so `main.py` itself never writes back to `config.json` - it only
+reads this one key once per session rollover (see `_refresh_risk_state()`).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from execution.config_cache import read_cached
+
+_PHASE_V2_KEY = "phase_v2"
+_RISK_KEY = "risk"
+_OVERRIDE_KEY = "manual_trade_lock_override"
+
+
+def read_manual_trade_lock_override(config_path: Path) -> bool | None:
+    """Returns True/False if a manual override is set, None if absent/unset
+    or the config file doesn't exist yet - never raises. Mtime-gated cache
+    (see execution/config_cache.py) - picks up an edit as soon as the file's
+    mtime changes, not on a fixed schedule."""
+    return read_cached(config_path, _read_manual_trade_lock_override_uncached)
+
+
+def _read_manual_trade_lock_override_uncached(config_path: Path) -> bool | None:
+    if not config_path.exists():
+        return None
+    with config_path.open("r", encoding="utf-8") as f:
+        config = json.load(f)
+    value = config.get(_PHASE_V2_KEY, {}).get(_RISK_KEY, {}).get(_OVERRIDE_KEY)
+    return value if isinstance(value, bool) else None
+
+
+def write_manual_trade_lock_override(value: bool | None, config_path: Path) -> None:
+    """Read-modify-write config.json, setting only
+    phase_v2.risk.manual_trade_lock_override - every other key is preserved
+    untouched. value=None removes the override key entirely (returns to
+    fully automatic behavior)."""
+    with config_path.open("r", encoding="utf-8") as f:
+        config = json.load(f)
+
+    phase_v2 = config.setdefault(_PHASE_V2_KEY, {})
+    risk = phase_v2.setdefault(_RISK_KEY, {})
+    if value is None:
+        risk.pop(_OVERRIDE_KEY, None)
+    else:
+        risk[_OVERRIDE_KEY] = value
+
+    with config_path.open("w", encoding="utf-8") as f:
+        json.dump(config, f, indent=4)
+        f.write("\n")
+
+
+# V5.1 Phase 6 (production safety) - the kill switch's own arm/disarm
+# override, deliberately the EXACT same read/write/cache shape as the
+# manual trade-lock override above (same GUARDRAIL the plan states for
+# `aq kill-switch`: reuse this convention so the two can never disagree -
+# an operator can force-disarm the kill switch's own evaluation without
+# touching phase_v2.risk.kill_switch.enabled in config.json at all, the
+# same way manual_trade_lock_override sits ON TOP of the automatic
+# drawdown-lock logic rather than replacing it).
+_KILL_SWITCH_OVERRIDE_KEY = "kill_switch_manual_override"
+
+
+def read_kill_switch_manual_override(config_path: Path) -> bool | None:
+    """True = force-armed, False = force-disarmed, None = defer entirely to
+    config.json's own phase_v2.risk.kill_switch.enabled. Never raises -
+    same missing-file/missing-key degrade-to-None contract as
+    read_manual_trade_lock_override()."""
+    return read_cached(config_path, _read_kill_switch_manual_override_uncached)
+
+
+def _read_kill_switch_manual_override_uncached(config_path: Path) -> bool | None:
+    if not config_path.exists():
+        return None
+    with config_path.open("r", encoding="utf-8") as f:
+        config = json.load(f)
+    value = config.get(_PHASE_V2_KEY, {}).get(_RISK_KEY, {}).get(_KILL_SWITCH_OVERRIDE_KEY)
+    return value if isinstance(value, bool) else None
+
+
+def write_kill_switch_manual_override(value: bool | None, config_path: Path) -> None:
+    """Read-modify-write config.json, setting only
+    phase_v2.risk.kill_switch_manual_override - every other key (including
+    phase_v2.risk.manual_trade_lock_override) is preserved untouched.
+    value=None removes the override key entirely (returns to fully
+    config-driven kill_switch.enabled behavior)."""
+    with config_path.open("r", encoding="utf-8") as f:
+        config = json.load(f)
+
+    phase_v2 = config.setdefault(_PHASE_V2_KEY, {})
+    risk = phase_v2.setdefault(_RISK_KEY, {})
+    if value is None:
+        risk.pop(_KILL_SWITCH_OVERRIDE_KEY, None)
+    else:
+        risk[_KILL_SWITCH_OVERRIDE_KEY] = value
+
+    with config_path.open("w", encoding="utf-8") as f:
+        json.dump(config, f, indent=4)
+        f.write("\n")

risk/position_sizing.py

@@ -0,0 +1,303 @@
+"""Dynamic position sizing for Aether Quant V2."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass
+
+from .rl_sizing import rl_sizing_multiplier as _rl_sizing_multiplier
+
+TRADING_DAYS_PER_YEAR = 252
+
+
+@dataclass(frozen=True)
+class PositionSizingDecision:
+    base_target_weight: float
+    target_weight: float
+    rolling_volatility: float
+    annualized_volatility: float
+    volatility_regime: str
+    volatility_multiplier: float
+    confidence_multiplier: float
+    topology_multiplier: float
+    leverage_factor: float
+    max_leverage: float
+    sizing_reason: str
+    topology_sizing_reason: str
+    volatility_source: str = "rolling"
+    rank_multiplier: float = 1.0
+    rank_sizing_reason: str = "rank_sizing_disabled_or_absent"
+    rl_multiplier: float = 1.0
+    rl_sizing_reason: str = "rl_sizing_disabled_or_absent"
+    # V5.1 Phase 1 (development/Problems.md, item 3) - see
+    # cost_sizing_multiplier() below.
+    cost_multiplier: float = 1.0
+    cost_sizing_reason: str = "cost_sizing_disabled_or_absent"
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def classify_volatility_regime(
+    rolling_volatility: float,
+    low_volatility_threshold: float,
+    high_volatility_threshold: float,
+) -> str:
+    volatility = abs(float(rolling_volatility))
+    if volatility >= high_volatility_threshold:
+        return "high_volatility"
+    if volatility <= low_volatility_threshold:
+        return "low_volatility"
+    return "normal_volatility"
+
+
+def _clamp01(value: float) -> float:
+    return max(0.0, min(float(value), 1.0))
+
+
+def topology_sizing_multiplier(
+    topology_source: str | None,
+    topology_confidence: float | None,
+    topology_disagreement: float | None,
+    min_topology_multiplier: float = 0.5,
+    max_topology_multiplier: float = 1.0,
+) -> tuple[float, str]:
+    """Bounded, continuous, shrink-only adjustment - never above
+    max_topology_multiplier (1.0 by default), i.e. never amplifies size
+    beyond what the deterministic-only sizing already computed. Only
+    engages when topology_source == "learned" - topology/learned_topology.py
+    already gates that label on confidence clearing
+    min_confidence_for_learned upstream, so "fallback"/missing/None here is
+    always a strict no-op, matching the same "a missing/degraded learned
+    model never changes trading behavior" convention already established
+    for the topology overlay itself (see analyzer/README.md and
+    development/architecture.md's V2-17.5 safety rule: probabilistic
+    scoring may only ever produce a bounded, continuous adjustment, never
+    a randomized or amplified decision)."""
+    if topology_source != "learned" or topology_confidence is None:
+        return 1.0, "topology_absent_or_fallback_no_adjustment"
+
+    confidence = _clamp01(topology_confidence)
+    disagreement = _clamp01(topology_disagreement) if topology_disagreement is not None else 0.0
+    raw = confidence * (1.0 - disagreement)
+    multiplier = min_topology_multiplier + (max_topology_multiplier - min_topology_multiplier) * raw
+    return multiplier, "topology_confidence_scaled_sizing"
+
+
+def rank_sizing_multiplier(
+    rank_prediction: float | None,
+    rank_sizing_enabled: bool,
+    min_rank_multiplier: float = 0.75,
+    max_rank_multiplier: float = 1.25,
+) -> tuple[float, str]:
+    """Bounded, continuous, direction-preserving size adjustment driven by
+    the sequence/multitask model's rank_20d head (predicted cross-
+    sectional percentile rank of 20-day forward return, [0, 1] - see
+    train.py::compute_rank_ic()/development/Changelog.md's "frontier-model
+    edge investigation" entry: the one signal in the whole system with a
+    statistically significant backtest rank-IC, 0.073 mean IC / t-stat 4.40
+    on the sequence model's full backtest series).
+
+    A predicted rank near 1.0 (top of the universe) scales size UP toward
+    max_rank_multiplier; a rank near 0.0 (predicted bottom) scales it DOWN
+    toward min_rank_multiplier; a rank of exactly 0.5 (predicted median) is
+    a no-op (multiplier 1.0). Never flips direction/sign - this only ever
+    scales the SAME direction the existing 1d-direction gating decision
+    already picked, matching topology_sizing_multiplier()'s "probabilistic
+    scoring may only ever produce a bounded, continuous adjustment, never
+    a randomized or amplified decision" convention.
+
+    Config-gated, additive, default OFF
+    (phase_v2.dynamic_risk.rank_sizing_enabled) - this signal's own
+    non-overlapping-date backtest subsample was not yet independently
+    significant (t-stat 1.20 on 28 independent 20-day windows, vs. 4.40 on
+    the full autocorrelated series), so it ships available, tested, and
+    wired end-to-end, but not defaulted on until validated further."""
+    if not rank_sizing_enabled or rank_prediction is None:
+        return 1.0, "rank_sizing_disabled_or_absent"
+
+    rank = _clamp01(rank_prediction)
+    multiplier = min_rank_multiplier + (max_rank_multiplier - min_rank_multiplier) * rank
+    return multiplier, "rank_prediction_scaled_sizing"
+
+
+def cost_sizing_multiplier(
+    expected_edge_bps: float,
+    expected_cost_bps: float,
+    cost_sizing_enabled: bool,
+    min_cost_multiplier: float = 0.25,
+) -> tuple[float, str]:
+    """Bounded, continuous, shrink-only size adjustment (V5.1 Phase 1,
+    development/Problems.md, item 3) - follows topology_sizing_multiplier()'s
+    exact contract: never above 1.0 (never amplifies size beyond what the
+    deterministic sizing already computed), and a disabled/absent input is
+    always a strict no-op.
+
+    multiplier = clamp((edge - cost) / max(edge, eps), min_cost_multiplier, 1.0) -
+    a trade whose edge comfortably clears its cost sizes at full conviction
+    (multiplier 1.0); one whose edge is barely above cost (or below it -
+    analyzer/market_analyzer.py's Priority 6.5 tier is the actual entry
+    veto for that case, this is a size-scaling BACKSTOP for whatever
+    reaches sizing regardless, e.g. an already-open position being
+    resized) shrinks toward min_cost_multiplier rather than sizing at full
+    weight on a marginal edge.
+
+    Config-gated, additive, default OFF (phase_v2.costs.cost_sizing_enabled) -
+    same off-by-default precedent as rank_sizing_enabled/rl_sizing_enabled,
+    since this depends on the same not-yet-calibrated edge_bps_per_rank_unit
+    execution/cost_model.py::build_net_edge_decision() documents."""
+    if not cost_sizing_enabled or expected_edge_bps == 0.0:
+        return 1.0, "cost_sizing_disabled_or_absent"
+
+    raw_ratio = (expected_edge_bps - expected_cost_bps) / max(abs(expected_edge_bps), 1e-9)
+    multiplier = max(min_cost_multiplier, min(raw_ratio, 1.0))
+    return multiplier, "net_edge_scaled_sizing"
+
+
+def _resolve_effective_volatility(
+    rolling_volatility: float,
+    predicted_volatility: float | None,
+    use_predicted_volatility: bool,
+) -> tuple[float, str]:
+    """Picks which volatility number actually drives sizing this bar.
+    predicted_volatility (the multitask model's forward-looking volatility
+    head, see train_multitask.py) only ever swaps in when both the config
+    flag is on AND a real prediction is available - any other case falls
+    back to the existing backward-looking rolling_volatility_20d average,
+    byte-identical to pre-flag behavior. Config-gated, additive, default
+    off - see phase_v2.dynamic_risk.use_predicted_volatility."""
+    if use_predicted_volatility and predicted_volatility is not None:
+        return abs(float(predicted_volatility)), "predicted"
+    return abs(float(rolling_volatility)), "rolling"
+
+
+def build_dynamic_position_sizing(
+    base_target_weight: float,
+    confidence: float,
+    rolling_volatility: float,
+    max_position_weight: float,
+    target_daily_volatility: float = 0.015,
+    min_position_weight: float = 0.0,
+    low_volatility_threshold: float = 0.01,
+    high_volatility_threshold: float = 0.03,
+    min_volatility_multiplier: float = 0.35,
+    max_volatility_multiplier: float = 1.25,
+    max_leverage: float = 1.0,
+    topology_source: str | None = None,
+    topology_confidence: float | None = None,
+    topology_disagreement: float | None = None,
+    min_topology_multiplier: float = 0.5,
+    max_topology_multiplier: float = 1.0,
+    predicted_volatility: float | None = None,
+    use_predicted_volatility: bool = False,
+    predicted_rank_20d: float | None = None,
+    rank_sizing_enabled: bool = False,
+    min_rank_multiplier: float = 0.75,
+    max_rank_multiplier: float = 1.25,
+    rl_model: dict | None = None,
+    rl_state: dict | None = None,
+    rl_sizing_enabled: bool = False,
+    min_rl_multiplier: float = 0.6,
+    max_rl_multiplier: float = 1.0,
+) -> PositionSizingDecision:
+    base_target_weight = float(base_target_weight)
+    confidence = max(0.0, min(float(confidence), 1.0))
+    max_position_weight = max(float(max_position_weight), 0.0)
+    abs_base_target = abs(base_target_weight)
+    volatility, volatility_source = _resolve_effective_volatility(
+        rolling_volatility, predicted_volatility, use_predicted_volatility
+    )
+    annualized_volatility = volatility * math.sqrt(TRADING_DAYS_PER_YEAR)
+    volatility_regime = classify_volatility_regime(
+        volatility,
+        low_volatility_threshold,
+        high_volatility_threshold,
+    )
+    topology_multiplier, topology_sizing_reason = topology_sizing_multiplier(
+        topology_source,
+        topology_confidence,
+        topology_disagreement,
+        min_topology_multiplier,
+        max_topology_multiplier,
+    )
+    rank_multiplier, rank_sizing_reason = rank_sizing_multiplier(
+        predicted_rank_20d,
+        rank_sizing_enabled,
+        min_rank_multiplier,
+        max_rank_multiplier,
+    )
+    rl_multiplier, rl_sizing_reason = _rl_sizing_multiplier(
+        rl_model,
+        rl_state,
+        rl_sizing_enabled,
+        min_rl_multiplier,
+        max_rl_multiplier,
+    )
+
+    if abs_base_target == 0.0 or confidence == 0.0 or max_position_weight == 0.0:
+        return PositionSizingDecision(
+            base_target_weight=base_target_weight,
+            target_weight=0.0,
+            rolling_volatility=volatility,
+            annualized_volatility=annualized_volatility,
+            volatility_regime=volatility_regime,
+            volatility_multiplier=0.0,
+            confidence_multiplier=0.0,
+            topology_multiplier=topology_multiplier,
+            leverage_factor=0.0,
+            max_leverage=float(max_leverage),
+            sizing_reason="no_active_signal",
+            topology_sizing_reason=topology_sizing_reason,
+            volatility_source=volatility_source,
+            rank_multiplier=rank_multiplier,
+            rank_sizing_reason=rank_sizing_reason,
+            rl_multiplier=rl_multiplier,
+            rl_sizing_reason=rl_sizing_reason,
+        )
+
+    safe_volatility = max(volatility, 1e-6)
+    volatility_multiplier = target_daily_volatility / safe_volatility
+    volatility_multiplier = max(min_volatility_multiplier, min(volatility_multiplier, max_volatility_multiplier))
+    confidence_multiplier = 0.5 + 0.5 * confidence
+
+    sized_weight = (
+        abs_base_target * volatility_multiplier * confidence_multiplier
+        * topology_multiplier * rank_multiplier * rl_multiplier
+    )
+    sized_weight = min(sized_weight, max_position_weight)
+    if sized_weight > 0.0 and min_position_weight > 0.0:
+        # V5.4.5: the floor is re-clamped by the cap - a misconfigured
+        # min > max previously pushed the sized weight ABOVE the leverage
+        # cap. Cap wins (conservative); direction preserved below either way.
+        sized_weight = min(max(sized_weight, min_position_weight), max_position_weight)
+
+    direction = 1.0 if base_target_weight >= 0.0 else -1.0
+    target_weight = direction * sized_weight
+    leverage_factor = min(float(max_leverage), sized_weight / max(abs_base_target, 1e-9))
+
+    if volatility_regime == "high_volatility":
+        reason = "reduced_for_high_volatility"
+    elif volatility_regime == "low_volatility" and volatility_multiplier > 1.0:
+        reason = "expanded_for_low_volatility"
+    else:
+        reason = "normal_volatility_sizing"
+
+    return PositionSizingDecision(
+        base_target_weight=base_target_weight,
+        target_weight=target_weight,
+        rolling_volatility=volatility,
+        annualized_volatility=annualized_volatility,
+        volatility_regime=volatility_regime,
+        volatility_multiplier=volatility_multiplier,
+        confidence_multiplier=confidence_multiplier,
+        topology_multiplier=topology_multiplier,
+        leverage_factor=leverage_factor,
+        max_leverage=float(max_leverage),
+        sizing_reason=reason,
+        topology_sizing_reason=topology_sizing_reason,
+        volatility_source=volatility_source,
+        rank_multiplier=rank_multiplier,
+        rank_sizing_reason=rank_sizing_reason,
+        rl_multiplier=rl_multiplier,
+        rl_sizing_reason=rl_sizing_reason,
+    )

risk/rl_sizing.py

@@ -0,0 +1,189 @@
+"""Offline-trained contextual-bandit sizing overlay (development/Problems.md
+#71, Phase 4.12, Component E) - a SHRINK-ONLY multiplier layered on top of
+risk/position_sizing.py::build_dynamic_position_sizing()'s output, never
+replacing it. Pure Python, no numpy/torch at runtime, matching
+topology/learned_topology.py's exact "pure inference, model trained offline,
+degrades to a strict no-op when the model is missing/malformed/disabled"
+split.
+
+Honest framing, not oversold (see train_rl_sizing.py's own module docstring
+for the full data-source story): this is a full-information contextual
+bandit fit offline over ml/datasets/*.csv (the SAME rows train.py already
+builds), NOT online/off-policy reinforcement learning against live
+exploration data - main.py has never logged a stochastic sizing action, and
+risk/position_sizing.py's own established rule (topology_sizing_multiplier()'s
+docstring) forbids ever randomizing a live sizing decision. The offline
+reward for every candidate action is computable in closed form from the
+already-known forward return, so no exploration is needed to fit this - see
+train_rl_sizing.py.
+
+What this CAN plausibly do: learn to shrink size in STATE-CONDITIONAL
+low-edge regimes (e.g. high implied volatility + backwardation + tightening
+financial conditions - exactly the alt-data features Problems.md #71's
+Component D added), reducing turnover/fees in the states this project's own
+Backtest 1 measured were the most costly. What it CANNOT do: manufacture
+alpha where none exists - if the underlying signal doesn't clear costs
+anywhere, the reward-maximizing policy over a shrink-only action set
+degenerates to "always pick the smallest multiplier," which is a `max_*_multiplier`
+config change, not a model, and is the intended "give up gracefully" behavior,
+not a bug.
+
+Default OFF (phase_v2.dynamic_risk.rl_sizing_enabled) - see
+risk/position_sizing.py's rl_multiplier param and main.py's wiring."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+# Fixed, order-significant state key list - the trained artifact carries
+# its OWN copy of this same list (model["state_keys"]) and
+# rl_sizing_multiplier() below refuses to score anything (falls back to
+# 1.0) if the two disagree, rather than silently reordering/misaligning
+# a state vector against weights trained for a different order. Every key
+# here is already computed once per bar as part of the existing base
+# feature/topology payload - no new computation, no new data source.
+RL_SIZING_STATE_KEYS = [
+    "confidence",
+    "rolling_volatility_20d",
+    "regime_signal_risk_score",
+    "topology_correlation_strength",
+    "liquidity_spread_proxy",
+    "bond_credit_spread_level",
+    "alt_implied_volatility_level",
+    "alt_implied_vol_term_structure",
+    "alt_financial_conditions_change",
+    # V5.4.1 - regime trend one-hots: lets the linear policy learn
+    # regime-conditional sizing (e.g. be more conservative in bearish)
+    # rather than a single global multiplier that averages across regimes.
+    "regime_trend_bullish",
+    "regime_trend_bearish",
+    "regime_trend_sideways",
+]
+
+DEFAULT_MIN_RL_MULTIPLIER = 0.6
+DEFAULT_MAX_RL_MULTIPLIER = 1.0
+
+
+def build_rl_sizing_state(base_features: dict, confidence: float) -> dict | None:
+    """Pulls RL_SIZING_STATE_KEYS out of the SAME base_features dict
+    main.py's _build_model_input_impl() already assembled this bar (plus
+    the model's own separately-computed confidence score, not itself a
+    base_feature) - no new computation, no new data source. Returns None
+    if any key is absent (e.g. Component D's alt-data features not yet in
+    input_set/retrained), which rl_sizing_multiplier() treats identically
+    to "no model" - a strict 1.0 no-op, never a crash or a partially-built
+    state vector."""
+    state = {}
+    for key in RL_SIZING_STATE_KEYS:
+        if key == "confidence":
+            continue
+        if key not in base_features:
+            return None
+        state[key] = float(base_features[key])
+    state["confidence"] = float(confidence)
+    return state
+
+
+def _softmax_argmax_index(scores: list[float]) -> int:
+    """Deterministic argmax - NOT a sampled draw from the softmax
+    distribution. topology_sizing_multiplier()'s docstring establishes the
+    project-wide rule this module also follows: "probabilistic scoring may
+    only ever produce a bounded, continuous adjustment, never a randomized
+    or amplified decision." A stochastic policy is legitimate during
+    OFFLINE training (see train_rl_sizing.py - exploration there costs
+    nothing, it's arithmetic over historical rows) and forbidden at live
+    inference. Ties broken toward the LAST action with the max score - by
+    convention the action list is built low-to-high multiplier
+    (see rl_sizing_multiplier()), so a tie prefers the larger (less
+    aggressive shrink) multiplier, matching a zero-initialized/untrained
+    model's intended "prefer no-op" default."""
+    best_index = 0
+    best_score = scores[0]
+    for index, score in enumerate(scores):
+        if score >= best_score:
+            best_score = score
+            best_index = index
+    return best_index
+
+
+def rl_sizing_multiplier(
+    model: dict | None,
+    state: dict | None,
+    rl_sizing_enabled: bool,
+    min_rl_multiplier: float = DEFAULT_MIN_RL_MULTIPLIER,
+    max_rl_multiplier: float = DEFAULT_MAX_RL_MULTIPLIER,
+) -> tuple[float, str]:
+    """Bounded, deterministic (argmax, never sampled), shrink-only size
+    adjustment - exact contract clone of
+    risk/position_sizing.py::rank_sizing_multiplier()/topology_sizing_multiplier():
+    returns (1.0, "<reason>") whenever the flag is off, the model is
+    missing/malformed, the state is incomplete, or the model's own
+    state_keys disagree with RL_SIZING_STATE_KEYS - every failure mode is a
+    strict no-op, never a crash and never an amplified size.
+
+    THREE safety properties, all enforced HERE rather than trusted from the
+    artifact (an untrusted/stale/hand-edited model file must never be able
+    to violate them):
+    1. Argmax, never sampled - see _softmax_argmax_index()'s docstring.
+    2. Clamped to [min_rl_multiplier, max_rl_multiplier] AFTER the argmax,
+       so a corrupted/adversarial action table can never emit a
+       multiplier outside the configured band, regardless of what the
+       model file claims its own actions are.
+    3. max_rl_multiplier defaults to 1.0 - SHRINK-ONLY, matching
+       topology_sizing_multiplier()'s "never amplifies size beyond what
+       deterministic-only sizing already computed" rule. Amplification
+       (max_rl_multiplier > 1.0) is technically possible via config but
+       is NOT the shipped/recommended posture for v1 - see
+       development/Problems.md #71's abandon criteria."""
+    if not rl_sizing_enabled or model is None or state is None:
+        return 1.0, "rl_sizing_disabled_or_absent"
+
+    try:
+        state_keys = model.get("state_keys")
+        actions = model.get("actions")
+        weights = model.get("weights")
+        bias = model.get("bias")
+        mean = model.get("mean")
+        scale = model.get("scale")
+        if state_keys != RL_SIZING_STATE_KEYS:
+            return 1.0, "rl_sizing_state_key_mismatch"
+        if not actions or not weights or not bias or not mean or not scale:
+            return 1.0, "rl_sizing_malformed_model"
+        if len(weights) != len(actions) or len(bias) != len(actions):
+            return 1.0, "rl_sizing_malformed_model"
+
+        standardized = []
+        for key, mean_value, scale_value in zip(state_keys, mean, scale):
+            raw = float(state[key])
+            denominator = float(scale_value) if float(scale_value) != 0.0 else 1.0
+            standardized.append((raw - float(mean_value)) / denominator)
+
+        scores = []
+        for action_weights, action_bias in zip(weights, bias):
+            if len(action_weights) != len(standardized):
+                return 1.0, "rl_sizing_malformed_model"
+            score = float(action_bias) + sum(w * x for w, x in zip(action_weights, standardized))
+            scores.append(score)
+
+        best_index = _softmax_argmax_index(scores)
+        raw_multiplier = float(actions[best_index])
+    except (KeyError, TypeError, ValueError, ZeroDivisionError):
+        return 1.0, "rl_sizing_malformed_model"
+
+    clamped = max(float(min_rl_multiplier), min(raw_multiplier, float(max_rl_multiplier)))
+    return clamped, "rl_sizing_policy_scaled_sizing"
+
+
+def load_rl_sizing_model(path: Path) -> dict | None:
+    """Missing file -> None (fresh checkout / never trained - the
+    documented default state). Malformed JSON -> None (never raises).
+    Mirrors main.py's own "missing/malformed model -> None, never a hard
+    failure" convention already established for every other optional
+    learned artifact (topology, gating, experts)."""
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None