Definitions doc shipped inside kalshi_microstructure_pack.zip (member kalshi_microstructure_pack/DEFINITIONS.md, 4,950 bytes, v1.0.0 of 2025-12-29), published unchanged except that the author handle reads "[author handle removed]" in its two places; per-file column names are in the ZIP's data_card.json.

# Event Definitions & Methodology

**Version:** 1.0.0
**Last Updated:** 2025-12-29
**Author:** [author handle removed]

---

## Universe Definitions

| Subset | Definition | Use Case |
|--------|------------|----------|
| **ALL** | All detected events across all game states | Raw data exploration |
| **LIVE** | Events where `game_state == "live"` | Execution risk analysis |
| **TRADEABLE** | Events passing tradability filters | Alpha research |

---

## 1. Quote Freeze

**Definition:** Period where bid AND ask prices remain unchanged for consecutive observations.

### Parameters
| Parameter | Value | Rationale |
|-----------|-------|-----------|
| `min_duration_seconds` | 5 | Filter noise, capture meaningful staleness |
| `max_duration_seconds` | 300 | Cap at 5 min (longer = collection gap, not freeze) |
| `min_observations` | 2 | Require confirmation of unchanged quote |
| `max_gap_between_obs_seconds` | 30 | Distinguish freeze from collection gaps |

### Deduplication
- Consecutive freezes at same price level are counted as **one event**
- New freeze starts when price changes then returns to unchanged state

### Record Counts (this release)
- **ALL states:** 178,101 events
- **LIVE only:** 7,889 events

### Key Metrics
- `freeze_rate_per_live_hour`: Freeze segments per market-hour of live time
  - *Denominator: sum of (live duration per market), not game-hours*
  - *Each market contributes time only when `game_state == "live"`*
- `p95_freeze_seconds_by_sport`: Tail risk varies by sport
- `freeze_during_score_events_pct`: % of freezes overlapping score change window
  - *Score window: ±30 seconds around a detected `score_change` event*
  - *A freeze is counted "during score" if ANY portion overlaps the window*

---

## 2. Tradability Cliff

**Definition:** Moment when a market transitions between tradable and untradable states.

### Tradability Criteria
A market is **tradable** when ALL of:
- `spread_cents <= 3`
- `min(bid_size, ask_size) >= 100`
- `bid > 0`
- `ask < 1.0` (not halted)

### Flip Types
| Type | Meaning |
|------|---------|
| `flip_off` | Was tradable → became untradable |
| `flip_on` | Was untradable → became tradable |

### Record Counts (this release)
- **Total flips:** 2,901
- **Live flip_off:** 563
- **Live flip_on:** 552

### Key Metrics
- `cliff_frequency_per_game`: Avg cliffs per unique game
- `median_recovery_by_game_state`: How fast tradability returns
- `worst_10_markets_by_cliff_count`: Most problematic tickers

---

## 3. Reversion After Overshoot

**Definition:** Price overshoot following a score change, followed by mean reversion.

### Detection Parameters
| Parameter | Value | Rationale |
|-----------|-------|-----------|
| `overshoot_threshold_cents` | 5 | Minimum meaningful price move |
| `reversion_threshold_pct` | 50 | Must revert at least half of overshoot |
| `pre_window_seconds` | 30 | Baseline measurement window |
| `post_window_seconds` | 120 | Observation window for reversion |

### Tradeable Event Criteria
An event is **tradeable** when:
- `tradable_overshoot_pct >= 30` (30%+ of overshoot window was tradable)
- `tradable_reversion_pct >= 30` (30%+ of reversion window was tradable)

### Record Counts (this release)
- **Total reversions:** 237
- **Tradeable reversions:** 8 (3.4%)

### Key Metrics
- `tradeable_share_by_overshoot_threshold`: How tradeability varies with move size
- `avg_tradeable_window_seconds`: Time available to execute
- `theoretical_profit_cents`: Upper bound before execution costs

---

## 4. Proprietary Indices

### LVS (Liquidity Void Severity)
**Range:** 0-100 (higher = worse)

**Formula:**
```
LVS = collapse_factor + severity_factor + recovery_factor

collapse_factor = min(collapse_count / 10, 1.0) × 30
severity_factor = avg_depth_drop_pct × 0.4
recovery_factor = min(avg_recovery_s / 120, 1.0) × 30
```

### QFR (Quote Freeze Risk)
**Range:** 0-100 (higher = worse)

**Formula:**
```
QFR = frequency + median + tail + extreme

frequency = min(freeze_count / 1000, 1.0) × 25
median = min(median_duration / 60, 1.0) × 25
tail = min(p95_duration / 180, 1.0) × 30
extreme = min(max_duration / 300, 1.0) × 20
```

### TUS (Tradability Uptime Score)
**Range:** 0-100 (higher = better)

**Formula:**
```
TUS = uptime_pct × (0.5 + 0.5 × avg_quality)

uptime_pct = tradeable_snaps / total_live_snaps × 100
avg_quality = (spread_quality + depth_quality) / 2
```

---

## Data Quality Notes

1. **Timestamps:** Unix epoch (seconds), timezone-naive
2. **Prices:** Decimal dollars (0.50 = 50¢)
3. **Sizes:** Integer contracts
4. **Deduplication:** Events at identical timestamps are preserved (may represent different tickers)
5. **Missing values:** `None` or `NaN` for unavailable fields

---

## Changelog

### v1.0.0 (2025-12-29)
- Initial release
- Quote Freeze, Tradability Cliff, Reversion Overshoot libraries
- LVS, QFR, TUS proprietary indices
- Execution-aware backtest proof

---

*Questions? Contact [author handle removed]*