@pgnio/helios-mcp 0.0.0-stage → 0.2.0

package/docs/ai-agent-indicators/bayesian_overbought.txt

@@ -0,0 +1,134 @@
+================================================================================
+INDICATOR: BAYESIAN_OVERBOUGHT — BAYESIAN P(OVERBOUGHT)
+================================================================================
+id:                 bayesian_overbought
+data_field:         indicators.bayesian_overbought
+type:               NUMERIC
+range:              0.0 to 1.0
+precision:          3 decimal places
+update_rate:        per_tick
+latency_profile:    COINCIDENT
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+bayesian_overbought is the Bayesian posterior probability that the current
+weighted RSI reading is at the upper extreme of its recent history.
+
+Method: Beta-Binomial with empirical percentile counting
+  - Prior: Beta(1, 1) — uniform, no initial knowledge
+  - Window: 60 most recent weighted_rsi observations
+  - countLower = number of history values ≤ current value
+  - P(overbought) = (1 + countLower) / (2 + historyLength)
+    (Laplace smoothing prevents 0 or 1 as exact outputs)
+
+Edge case: IF fewer than 10 observations are in the history buffer:
+  Returns value / 100 (raw weighted_rsi converted to 0-1 scale).
+  This is an approximation with no statistical basis.
+
+The output contextualizes the current RSI reading against recent history:
+an absolute RSI of 72 may be perfectly normal for a trending asset
+(bayesian = 0.5) or extremely rare (bayesian = 0.95).
+
+At exactly 0.5: current RSI is at the median of recent history.
+Above 0.5: current RSI is higher than median recent history.
+Below 0.5: current RSI is lower than median recent history.
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value > 0.9
+    Extremely overbought in historical context. The current weighted_rsi is
+    at the 90th percentile or higher of the last 60 readings. This level of
+    RSI has been rare for this asset recently. Associated with short-TF
+    momentum exhaustion risk.
+
+  value > 0.8 AND value <= 0.9
+    Overbought. RSI is at the 80th percentile of recent readings. Momentum
+    is historically stretched. Not a reversal signal, but upside continuation
+    becomes progressively harder to sustain statistically.
+
+  value >= 0.4 AND value <= 0.6
+    Historically normal range. Current RSI is near the median of recent
+    observations. No extreme condition present.
+
+  value < 0.2 AND value >= 0.1
+    Oversold. RSI is at the 20th percentile of recent readings. Downside
+    momentum is historically stretched.
+
+  value < 0.1
+    Extremely oversold in historical context. Mirror of > 0.9.
+
+# Note: values will NOT be exactly 0.0 or 1.0 due to Laplace smoothing.
+
+--------------------------------------------------------------------------------
+BOOTSTRAP PERIOD WARNING
+--------------------------------------------------------------------------------
+  IF fewer than 10 observations have been seen since the indicator started
+    → Bayesian estimate replaced with value/100.
+       Do not use. Wait for >= 10 observations for meaningful output.
+    → You can infer this state from startup or data reset conditions.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.weighted_rsi | REQUIRED_COMPANION
+    bayesian_overbought is computed FROM weighted_rsi.
+    Evaluate weighted_rsi first, then frame it with bayesian_overbought.
+    They are a pair — neither is sufficient alone.
+
+  indicators.rsi_divergence | CONTEXT
+    IF bayesian_overbought > 0.85 AND rsi_divergence = BEARISH_DIVERGENCE
+      → Overbought by historical standards AND price is making higher highs
+         while RSI peaks are lower. Dual overbought condition.
+    IF bayesian_overbought < 0.15 AND rsi_divergence = BULLISH_DIVERGENCE
+      → Oversold by historical standards AND price making lower lows while
+         RSI troughs are improving. Dual oversold condition.
+
+  indicators.vwap_zscore | COMPANION
+    vwap_zscore measures price deviation from institutional cost basis.
+    bayesian_overbought measures RSI percentile (momentum deviation).
+    IF bayesian_overbought > 0.88 AND vwap_zscore > 2.0
+      → Momentum AND price are both historically stretched upward simultaneously.
+    IF bayesian_overbought < 0.12 AND vwap_zscore < -2.0
+      → Momentum AND price are both historically stretched downward simultaneously.
+
+  indicators.regime | CONTEXT
+    During EXHAUST_UP regime, expect bayesian_overbought to be elevated.
+    During CASCADE/PARABOLIC, bayesian_overbought may STAY elevated for many
+    ticks. Do not treat sustained elevated bayesian_ob as a reversal trigger
+    in trending regimes.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  If < 10 observations (bootstrap period): discard.
+  2  Read weighted_rsi range bucket.
+  3  Frame weighted_rsi using bayesian_overbought percentile.
+  4  Compound with vwap_zscore and regime for full overbought assessment.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF fewer than 10 observations in history
+    → Not statistically valid. Discard.
+
+  IF market has undergone a major structural change very recently
+    (e.g., a crash/spike that reset price level significantly)
+    → The 60-observation window may contain pre-event RSI values that
+       make the current percentile unreliable. Allow 60 ticks for window
+       to refresh.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF bayesian_overbought > 0.9 is used alone as a short trigger
+    → INCOMPLETE. High bayesian OB means RSI is historically stretched.
+       But in trending markets, this can remain elevated. Require
+       confirmation from rsi_divergence or hmi_velocity deceleration
+       before inferring a momentum reversal risk.
+
+  IF bayesian_overbought = 0.5 is interpreted as "neutral market"
+    → INCORRECT SCOPE. bayesian_overbought only describes the RSI reading
+       relative to recent RSI history. A value of 0.5 simply means RSI is
+       at its recent median — the broader market could be strongly trending.

package/docs/ai-agent-indicators/directional_efficiency.txt

@@ -0,0 +1,134 @@
+================================================================================
+INDICATOR: DIRECTIONAL_EFFICIENCY
+================================================================================
+id:                 directional_efficiency
+data_field:         indicators.directional_efficiency
+type:               NUMERIC
+range:              -1.0 to 1.0
+precision:          3 decimal places
+update_rate:        per_tick
+latency_profile:    COINCIDENT
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+Directional efficiency is a Kaufman-style efficiency ratio measuring how
+cleanly price is moving in a single direction across all timeframes — as
+opposed to zigzagging back and forth.
+
+Formula:
+  For each TF, normalize by expected magnitude using TF_NORM divisors:
+    1m:1  3m:1.5  5m:2  15m:3.5  30m:5  1h:7  2h:10  4h:13  6h:15  8h:17  12h:19  24h:20
+
+  netChange   = Σ(change[tf] / TF_NORM[tf])   (sum preserves sign)
+  totalMovement = Σ(|change[tf]| / TF_NORM[tf]) (sum of absolute values)
+
+  value = clamp(netChange / totalMovement, -1.0, 1.0)
+
+Interpretation:
+  If all TFs move in the same direction: netChange = totalMovement → value = +1 or -1
+  If TFs perfectly cancel out: netChange = 0 → value = 0
+  Most readings fall between -0.7 and +0.7 in practice.
+
+Per-cluster sub-breakdowns are also computed (micro, short, medium, macro) using
+the same formula on each cluster's TF subset. These are available for agents
+needing cluster-level efficiency.
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value >= 0.7
+    Highly efficient upward movement. Timeframes are not cancelling each other
+    out — the net directional movement is at least 70% of total movement.
+    Low noise, clean trend. Price is moving in one direction with minimal
+    countertrend interference.
+
+  value >= 0.4 AND value < 0.7
+    Moderately efficient upward movement. Meaningful net directional movement
+    but with some countertrend noise from opposing TFs. A trend is present
+    and tradeable but with more chop than pure efficiency readings.
+
+  value > -0.4 AND value < 0.4
+    Choppy / inefficient. The countertrend movement across TFs is nearly as
+    large as the directional movement. Net direction is weak or absent. Price
+    is not moving cleanly in either direction. Directional trades have reduced
+    edge in this state.
+
+  value > -0.7 AND value <= -0.4
+    Moderately efficient downward movement. Mirror of 0.4 to 0.7 upside range.
+
+  value <= -0.7
+    Highly efficient downward movement. Mirror of >= 0.7 upside range. Clean
+    sustained downtrend with minimal upside interference.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.tf_alignment | COMPANION
+    tf_alignment measures breadth of alignment with macro.
+    directional_efficiency measures cleanliness of net directional movement.
+    These are independent — an asset can have high alignment with low efficiency
+    (many TFs go same direction but weakly, with noise) or high efficiency with
+    moderate alignment (few TFs but very clean).
+
+    IF tf_alignment >= 70 AND directional_efficiency >= 0.6
+      → Both breadth and cleanliness confirm direction. Strong trending signal.
+
+    IF tf_alignment >= 70 AND directional_efficiency < 0.3
+      → Broad alignment but noisy movement. Trend is directionless despite
+         TF consensus. Could be a chop period within a trending structure.
+
+  indicators.hmi | CONTEXT
+    directional_efficiency provides the quality dimension missing from hmi.
+    hmi can be high even with some countertrend noise; efficiency flags that.
+
+    IF hmi >= 50 AND directional_efficiency <= 0.3
+      → hmi is reading momentum but prices are still moving inefficiently.
+         Wait for efficiency to improve before treating hmi as high quality.
+
+  indicators.regime | CONTEXT
+    CASCADE and TREND regimes imply high directional_efficiency.
+    SPIKE regimes often show high efficiency in one cluster (micro) but
+    low efficiency overall — the per-cluster efficiency breakdowns are
+    useful to distinguish spike vs cascade.
+
+  indicators.hurst_exponent | COMPANION
+    hurst_exponent measures persistence (trending vs mean-reverting tendency).
+    directional_efficiency measures current net directional movement.
+    IF hurst >= 0.6 AND directional_efficiency >= 0.5
+      → Both statistical persistence and current price efficiency confirm
+         trending conditions.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Regime: in CHOP/CONSOL, efficiency near zero is expected.
+  2  Read value and range bucket.
+  3  Cross-reference with tf_alignment for breadth vs quality divergence.
+  4  Check per-cluster efficiency if spike vs cascade distinction is needed.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF activity_ratio < 0.5
+    → Low-volume TF changes produce unreliable efficiency ratios.
+      Discard.
+
+  IF all TF changes are near zero (totalMovement < 0.01 after normalization)
+    → Division by near-zero is guarded internally but the result (near 0)
+       carries no information. Treat as INDETERMINATE.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF directional_efficiency is used as a reversal indicator
+    → INCORRECT USE. Low efficiency means price is moving without clear
+       direction — it does NOT predict a reversal. It predicts continued
+       choppiness. Reversal signals come from regime and hmi_velocity.
+
+  IF efficiency is used without checking whether it applies to the full stack
+    or a single cluster
+    → CLARIFY: The top-level value is across all 12 TFs. Per-cluster
+       (micro, short, medium, macro) efficiency is a separate sub-field.
+       A SPIKE_UP will show high micro efficiency but low overall efficiency.
+       Make sure you are reading the correct field.

package/docs/ai-agent-indicators/hfi.txt

@@ -0,0 +1,172 @@
+================================================================================
+INDICATOR: HFI — HELIOS FLOW INDEX
+================================================================================
+id:                 hfi
+data_field:         indicators.hfi
+type:               NUMERIC
+range:              -100.0 to +100.0
+precision:          2 decimal places
+update_rate:        per_tick
+latency_profile:    COINCIDENT (EWMA smoothed, alpha=0.3)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+HFI (Helios Flow Index) is a composite derivatives market sentiment indicator
+synthesizing three components: funding rate behavior, open interest dynamics,
+and cumulative volume delta (CVD). Each component's weight is dynamically
+adjusted via Bayesian inverse-variance weighting.
+
+COMPONENTS:
+
+  1. FUNDING COMPONENT
+    recent    = average funding rate over last 10 candles
+    baseline  = average funding rate over candles 10-20 back
+    std       = rolling standard deviation of funding rate changes
+    fundingScore = clamp((recent - baseline) / std, -3, 3) × 33.33
+    Interpretation: is the funding rate rising or falling vs recent baseline?
+    Rising funding = longs paying more premium = long-heavy positioning.
+
+  2. OI COMPONENT
+    recent    = average OI over last 5 candles
+    baseline  = average OI over candles 25-35 back
+    oiChanges = sequential OI changes within baseline window
+    oiScore = clamp(((recent - baseline) / baseline) / std(oiChanges), -3, 3) × 33.33
+    Interpretation: is OI growing or shrinking vs baseline?
+    Rising OI with price up = new long positions (conviction).
+    Rising OI with price down = new short positions (conviction).
+    (OI direction must be combined with price direction for full context.)
+
+  3. CVD COMPONENT
+    volDelta[i] = volBuy[i] - volSell[i] for each of last 20 candles
+    cvdSlope = regression slope of volDelta sequence
+    meanAbsCVD = mean absolute value of volDelta
+    cvdScore = clamp(cvdSlope / meanAbsCVD, -3, 3) × 33.33
+    Interpretation: is buying pressure vs selling pressure trending up or down?
+    Rising CVD slope = buyers are increasingly dominating vs sellers.
+
+BAYESIAN WEIGHT MODULATION:
+  Default weights: funding=0.40, OI=0.30, CVD=0.30
+  
+  Each component's weight is adjusted by:
+    componentAccuracy ∈ [0, 1] (how stable/consistent recent component signal is)
+    adjustedWeight = defaultWeight × (0.5 + componentAccuracy)
+    Result maps [0,1] accuracy → [0.5, 1.5] multiplier on the default weight.
+    All weights re-normalized to sum=1.0.
+
+  GRANGER CAUSALITY BOOST for OI:
+    5 lagged correlations between OI changes and CVD changes computed.
+    IF maxLagCorrelation > 0.2:
+      OI weight boosted by × (1 + correlation × 0.5)
+      Reasoning: when OI changes are causally leading CVD, OI signal has higher
+      predictive value for order flow direction.
+
+  PRECISION_BLEND = 0.4:
+    Final weights = 0.4 × bayesianWeights + 0.6 × defaultWeights
+    (Prevents extreme weight concentration; defaults anchored at 40% influence.)
+
+FINAL COMPOSITE:
+  rawHFI = Σ(componentScore × finalWeight)   for funding, OI, CVD
+  smoothedHFI = 0.3 × rawHFI + 0.7 × prevSmoothedHFI   (EWMA alpha=0.3)
+  value = clamp(smoothedHFI, -100, 100)
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value >= 40
+    Strong positive derivatives flow. Funding is rising, OI is growing, CVD
+    is trending upward — positioning and order flow are aligned in a bullish
+    direction. The derivatives market is expressing confidence in upside.
+    Associated with genuine accumulation phases or momentum breakout conditions.
+
+  value >= 15 AND value < 40
+    Moderate positive derivatives flow. Some combination of positive funding,
+    OI, and CVD conditions. Constructive but not extreme. Watch component
+    weights (hfi_weights) to understand which component is dominant.
+
+  value >= -15 AND value < 15
+    Neutral derivatives flow. No dominant directional signal from the
+    combined funding/OI/CVD stack. Non-committal positioning.
+
+  value >= -40 AND value < -15
+    Moderate negative derivatives flow. Mixed-to-bearish positioning signals
+    from the derivatives stack.
+
+  value < -40
+    Strong negative derivatives flow. Funding is falling/negative, OI is
+    declining or dominated by shorts, CVD trending downward. The derivatives
+    market is expressing confidence in downside.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.hfi_weights | REQUIRED_COMPANION
+    Read hfi_weights alongside hfi. The composite value can be
+    misleading if one component is dominant and the others are suppressed.
+    IF hfi = 60 AND weights = {funding:0.85, oi:0.10, cvd:0.05}
+      → The HFI value is almost entirely driven by funding. OI and CVD
+         are not confirming. Lower confidence than if all weights balanced.
+
+  indicators.hmi | CROSS_VALIDATE
+    HMI operates on price timeframe alignment.
+    HFI operates on derivatives positioning signals.
+    These are independent domains.
+
+    IF hmi >= 50 AND hfi >= 30
+      → Price stack and derivatives positioning agree upside. Both confirm.
+    IF hmi >= 50 AND hfi < -20
+      → Price trending up but derivatives showing bearish positioning.
+         Potential divergence: price may run ahead of positioning, or
+         derivatives market is fading the price move (distribution phase).
+    IF hmi < -30 AND hfi > 20
+      → Price trending down but positive funding/OI. Could indicate
+         shorts are being squeezed even in a downtrend.
+
+  indicators.regime | CONTEXT
+    During REVERSAL regime: if HFI is also turning positive, both confirm
+    a potential upside structural shift.
+    During EXHAUST_UP: if HFI turns negative, the exhaustion signal is
+    being confirmed by derivatives market positioning.
+
+  indicators.activity_ratio | GATE
+    IF activity_ratio < 0.5: funding, OI, and CVD signals are based on low
+    volume. Components computed from sparse data are less reliable.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read hfi value (range and direction).
+  2  Read hfi_weights to understand which components are dominant.
+  3  Cross-validate with hmi direction.
+  4  Note divergences between hmi and hfi — price/derivatives separation is a
+     meaningful transitional signal.
+  5  Activity_ratio gate: low volume degrades CVD component reliability.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF funding rate data is unavailable (Hyperliquid API outage, new listing)
+    → Funding component weight collapses. The other 2 components remain.
+       Check hfi_weights.funding for near-zero to detect this.
+
+  IF activity_ratio < 0.5
+    → CVD computed from low-volume candles is unreliable. CVD component weight
+       should be treated with skepticism.
+
+  IF asset is newly listed (< 24h)
+    → OI baseline (using candles 25-35 back) is not established.
+       OI component is in warm-up. Check hfi_weights.oi for near-zero.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF hfi direction is used as a proxy for immediate price direction
+    → INCORRECT SCOPE. HFI measures sentiment in the DERIVATIVES market
+       (funding, OI, CVD). Derivatives can lead price, lag price, or diverge
+       from it. HFI is a positioning indicator, not a price direction indicator.
+       Cross-validate with price-based indicators (hmi, regime).
+
+  IF hfi_weights are not checked when extreme hfi values are observed
+    → INCOMPLETE. An hfi of 70 driven entirely by one component is
+       structurally weaker than one with balanced component weights.
+       Weight inspection is mandatory for high-value HFI readings.

package/docs/ai-agent-indicators/hfi_weights.txt

@@ -0,0 +1,124 @@
+================================================================================
+INDICATOR: HFI_WEIGHTS — HFI COMPONENT WEIGHTS
+================================================================================
+id:                 hfi_weights
+data_field:         indicators.hfi_weights
+type:               OBJECT (three numeric fields)
+fields:             { funding: number, oi: number, cvd: number }
+range:              Each field [0.0, 1.0]; all three sum = 1.0
+precision:          3 decimal places per field
+update_rate:        per_tick
+latency_profile:    COINCIDENT (dynamically updated with HFI computation)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+hfi_weights exposes the real-time Bayesian component weights used in the HFI
+computation. These weights reflect how much of the current hfi value is driven
+by each of the three data sources.
+
+Default starting weights before Bayesian adjustment:
+  funding:  0.40
+  oi:       0.30
+  cvd:      0.30
+
+The Bayesian update process (described in hfi.txt) can shift these significantly.
+The PRECISION_BLEND parameter ensures defaults retain 60% influence (preventing
+extreme concentration), so practical ranges:
+  funding range:  approximately 0.20 to 0.60
+  oi range:       approximately 0.10 to 0.50
+  cvd range:      approximately 0.10 to 0.50
+
+Granger causality (OI → CVD lead correlation) can boost OI weight specifically
+when OI changes are empirically leading CVD changes.
+
+--------------------------------------------------------------------------------
+WEIGHT INTERPRETATION
+--------------------------------------------------------------------------------
+  funding > 0.55
+    HFI is predominantly driven by funding rate dynamics.
+    OI and CVD are contributing minimally. The composite reflects whether
+    long/short carry is increasing or decreasing — but is not confirming
+    from an OI or CVD perspective.
+
+  oi > 0.50
+    HFI is heavily driven by OI changes. Often co-occurs with high
+    Granger causality correlation (OI is successfully leading CVD).
+    This configuration is associated with aggressive position-building
+    phases where OI expansion is the most reliable signal.
+
+  cvd > 0.50
+    HFI is heavily driven by CVD (cumulative buy-minus-sell volume).
+    Funding and OI are contributing less. Pure order flow signal is dominant.
+
+  Weights balanced (all three within 0.25-0.40)
+    All three components are contributing approximately equally.
+    This is the healthiest HFI configuration — all derivatives signals
+    agree on direction. No single component should be dismissed.
+
+  Any weight < 0.10
+    That component is effectively disabled by Bayesian precision collapse.
+    Its recent data has been too noisy/divergent from the others.
+    Treat the HFI composite as two-component for the current period.
+
+--------------------------------------------------------------------------------
+USE WITH HFI — COMPOUND ASSESSMENT
+--------------------------------------------------------------------------------
+  IF hfi >= 40 AND all weights balanced (all between 0.25 and 0.45)
+    → Maximum confidence HFI reading. Funding, OI, and CVD all agree.
+    → Strongest combined derivatives bullish signal.
+
+  IF hfi >= 40 AND funding > 0.60 AND (oi < 0.15 OR cvd < 0.15)
+    → HFI driven by funding alone. No OI or CVD confirmation.
+    → Funding can rise in short-driven markets too (shorts pay funding if
+       perpetual price < spot). Lower confidence in HFI direction.
+
+  IF hfi is near zero BUT one component weight is dominant
+    → The dominant component is likely showing a clear signal that is being
+       cancelled by opposite signals from the other components.
+    → Read the dominant component separately if its specific data is available.
+
+  IF any weight is near zero
+    → That data source has degraded reliability right now. Proceed as if
+       HFI is a two-component indicator for this tick.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.hfi | REQUIRED_COMPANION
+    hfi_weights only has meaning alongside the hfi value.
+    Evaluate together — weights without the composite value are context-
+    free; composite without weights may be misleading.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read hfi composite value.
+  2  Read hfi_weights fields: funding, oi, cvd.
+  3  Identify dominant component (highest weight).
+  4  Check if any weight < 0.10 (that component is degraded).
+  5  Apply balanced/concentrated interpretation.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF sum(funding + oi + cvd) != 1.0 (approximately)
+    → Data integrity issue. Components should always sum to 1.
+
+  IF all three weights are exactly equal to defaults (funding=0.4, oi=0.3, cvd=0.3)
+    → Bayesian updates have not yet converged (warm-up period). Treat as
+       unmodulated defaults. HFI composite is valid but weights carry no
+       extra information yet.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF hfi_weights are ignored and hfi value is used directly
+    → INCOMPLETE EVALUATION. A high hfi driven by a single degraded component
+       is qualitatively different from a high hfi with balanced weights.
+       Inspect weights before drawing conclusions from extreme hfi readings.
+
+  IF individual weights are used to assess raw data source reliability
+    → PRECISION_BLEND=0.4 means 60% of each final weight always reflects
+       the default allocation. No weight perfectly reflects raw Bayesian precision.
+       Weights indicate direction of influence, not absolute data reliability.