@nomadamas/k-skill 0.9.2 → 0.10.0

package/skills/market-event-impact/scripts/asset_selector.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""Select event-sensitive assets from available sourced series."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+PROFILES = {
+    "monetary_policy": (("short_rates", "long_rates", "curve", "fx", "broad_equity", "volatility"), ("rates", "fx", "equity", "volatility")),
+    "inflation": (("short_rates", "long_rates", "inflation_breakeven", "fx", "growth_equity", "broad_equity", "volatility"), ("rates", "fx", "equity", "volatility")),
+    "employment": (("short_rates", "long_rates", "curve", "fx", "growth_equity", "broad_equity", "volatility"), ("rates", "fx", "equity", "volatility")),
+    "growth": (("long_rates", "cyclical_equity", "broad_equity", "fx", "commodity"), ("rates", "equity", "fx", "commodity")),
+    "financial_stress": (("short_rates", "bank_equity", "credit", "volatility", "safe_haven", "broad_equity", "fx"), ("rates", "credit", "equity", "volatility", "fx")),
+    "sovereign_credit": (("government_bond", "sovereign_cds", "fx", "gold", "broad_equity", "volatility"), ("rates", "credit", "fx", "commodity", "equity", "volatility")),
+    "geopolitics": (("oil", "gold", "safe_haven", "fx", "volatility", "broad_equity"), ("commodity", "fx", "rates", "volatility", "equity")),
+    "commodity_supply": (("oil", "commodity", "inflation_breakeven", "commodity_equity", "fx", "broad_equity", "volatility"), ("commodity", "rates", "equity", "fx", "volatility")),
+    "corporate_earnings": (("event_security", "sector_equity", "broad_equity", "volatility"), ("equity", "volatility")),
+    "fiscal_policy": (("government_bond", "curve", "fx", "broad_equity"), ("rates", "fx", "equity")),
+    "trade_policy": (("short_rates", "long_rates", "curve", "affected_equity", "broad_equity", "fx", "oil", "commodity", "volatility"), ("rates", "equity", "fx", "commodity", "volatility")),
+    "regulation": (("affected_equity", "sector_equity", "broad_equity", "volatility"), ("equity", "volatility")),
+    "market_shock": (("event_security", "broad_equity", "volatility", "credit", "safe_haven"), ("equity", "volatility", "credit", "rates")),
+    "other": (("event_security", "broad_equity", "fx", "short_rates", "long_rates", "government_bond", "volatility"), ("price", "equity", "fx", "rates", "volatility")),
+}
+
+EVENT_TYPE_LABELS = {
+    "monetary_policy": "통화정책", "inflation": "물가", "employment": "고용", "growth": "성장",
+    "financial_stress": "금융스트레스", "sovereign_credit": "국가신용", "geopolitics": "지정학",
+    "commodity_supply": "원자재 공급", "corporate_earnings": "기업실적", "fiscal_policy": "재정정책",
+    "trade_policy": "무역정책", "regulation": "규제", "market_shock": "시장충격", "other": "사건별",
+}
+ROLE_LABELS = {
+    "short_rates": "단기금리", "long_rates": "장기금리", "curve": "금리곡선", "government_bond": "국채",
+    "bank_equity": "은행주", "credit": "신용", "volatility": "변동성", "safe_haven": "안전자산",
+    "oil": "원유", "gold": "금", "fx": "외환", "broad_equity": "시장지수", "sector_equity": "업종주",
+    "event_security": "사건 직접 노출 종목", "affected_equity": "영향 주식", "commodity": "원자재",
+    "growth_equity": "성장주", "cyclical_equity": "경기민감주", "commodity_equity": "원자재 관련주",
+    "inflation_breakeven": "기대인플레이션", "sovereign_cds": "국가 CDS",
+}
+
+
+def select_assets(series: list[dict[str, Any]], event: dict[str, Any], requested: tuple[str, ...] | None = None, limit: int = 8) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[str]]:
+    if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 20:
+        raise ValueError("asset selection limit must be an integer from 1 to 20")
+    by_symbol = {item["symbol"].casefold(): item for item in series}
+    if requested:
+        selected, missing = [], []
+        for symbol in requested:
+            item = by_symbol.get(symbol.casefold())
+            if item is None:
+                missing.append(symbol)
+            elif item not in selected:
+                selected.append(item)
+        reasons = [{"symbol": item["symbol"], "reason": "사용자 지정", "matched_roles": []} for item in selected]
+        return selected, reasons, missing
+
+    event_type = str(event.get("event_type") or "other")
+    preferred_roles, preferred_classes = PROFILES.get(event_type, PROFILES["other"])
+    event_region = str(event.get("region") or "GLOBAL").upper()
+    scored: list[tuple[int, int, str, dict[str, Any], list[str]]] = []
+    for item in series:
+        roles = [str(role).casefold() for role in item.get("roles", [])]
+        matched = [role for role in preferred_roles if role in roles]
+        class_rank = preferred_classes.index(item["asset_class"]) if item["asset_class"] in preferred_classes else len(preferred_classes)
+        role_score = sum(len(preferred_roles) - preferred_roles.index(role) for role in matched)
+        region_score = 3 if item.get("region") == event_region else (1 if item.get("region") == "GLOBAL" else 0)
+        explicit_priority = int(item.get("selection_priority", 0))
+        availability_penalty = 100000 if item.get("selection_usable") is False else 0
+        total = role_score * 100 + region_score * 10 + explicit_priority - availability_penalty
+        # A generic role equal to its asset class conveys no narrower exposure.
+        # Specific nonmatching roles (e.g. bank_equity for a CPI event) remain excluded.
+        if roles and not matched and not all(role in {item["asset_class"], "price"} for role in roles):
+            continue
+        if not matched and item["asset_class"] not in preferred_classes:
+            continue
+        scored.append((total, -class_rank, item["symbol"], item, matched))
+    scored.sort(key=lambda row: (-row[0], -row[1], row[2]))
+    # Cover distinct asset classes before filling finer roles. Otherwise a
+    # profile with many rate/equity roles can exhaust a small limit before FX
+    # or volatility is considered. Unusable series never displace usable ones.
+    selected_rows: list[tuple[int, int, str, dict[str, Any], list[str]]] = []
+    used_symbols: set[str] = set()
+    for pool in ([row for row in scored if row[3].get("selection_usable") is not False],
+                 [row for row in scored if row[3].get("selection_usable") is False]):
+        for asset_class in preferred_classes:
+            candidate = next((row for row in pool if row[3]["asset_class"] == asset_class and row[2] not in used_symbols), None)
+            if candidate is not None:
+                selected_rows.append(candidate)
+                used_symbols.add(candidate[2])
+            if len(selected_rows) >= limit:
+                break
+        if len(selected_rows) >= limit:
+            break
+        for role in preferred_roles:
+            candidate = next((row for row in pool if role in row[4] and row[2] not in used_symbols), None)
+            if candidate is not None:
+                selected_rows.append(candidate)
+                used_symbols.add(candidate[2])
+            if len(selected_rows) >= limit:
+                break
+        if len(selected_rows) >= limit:
+            break
+        for row in pool:
+            if row[2] not in used_symbols:
+                selected_rows.append(row)
+                used_symbols.add(row[2])
+            if len(selected_rows) >= limit:
+                break
+        if len(selected_rows) >= limit:
+            break
+    selected_rows.sort(key=lambda row: (preferred_classes.index(row[3]["asset_class"])
+                                        if row[3]["asset_class"] in preferred_classes else len(preferred_classes),
+                                        -row[0], row[2]))
+    selected = [row[3] for row in selected_rows]
+    reasons = [{
+        "symbol": row[3]["symbol"],
+        "reason": f"{EVENT_TYPE_LABELS.get(event_type, event_type)} 전달경로",
+        "matched_roles": [ROLE_LABELS.get(role, role) for role in (row[4] or [row[3]["asset_class"]])],
+    } for row in selected_rows]
+    return selected, reasons, []

package/skills/market-event-impact/scripts/calendars.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Trading-calendar alignment helpers based on actual observations."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta, timezone, tzinfo
+from typing import Any, Iterable
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+MARKET_CLOSES = {
+    "KR": ("Asia/Seoul", time(15, 30)),
+    "JP": ("Asia/Tokyo", time(15, 0)),
+    "CN": ("Asia/Shanghai", time(15, 0)),
+    "EU": ("Europe/Frankfurt", time(17, 30)),
+    "UK": ("Europe/London", time(16, 30)),
+    "US": ("America/New_York", time(16, 0)),
+}
+SESSION_ORDER = {"JP": 0, "KR": 0, "CN": 0, "EU": 1, "UK": 1, "US": 2}
+FALLBACK_ZONES = {"Asia/Seoul", "Asia/Tokyo", "Asia/Shanghai", "Europe/Frankfurt", "Europe/London", "America/New_York"}
+TIMEZONE_CLOSES = {zone: close for zone, close in MARKET_CLOSES.values()}
+
+
+def _nth_weekday(year: int, month: int, weekday: int, occurrence: int) -> date:
+    current = date(year, month, 1)
+    shift = (weekday - current.weekday()) % 7
+    return date(year, month, 1 + shift + 7 * (occurrence - 1))
+
+
+def _last_weekday(year: int, month: int, weekday: int) -> date:
+    next_month = date(year + (month == 12), 1 if month == 12 else month + 1, 1)
+    current = next_month - timedelta(days=1)
+    return current - timedelta(days=(current.weekday() - weekday) % 7)
+
+
+def zone_for_date(name: str, day: date) -> tzinfo:
+    try:
+        return ZoneInfo(name)
+    except ZoneInfoNotFoundError:
+        if name in {"Asia/Seoul", "Asia/Tokyo"}:
+            return timezone(timedelta(hours=9), name)
+        if name == "Asia/Shanghai":
+            return timezone(timedelta(hours=8), name)
+        if name == "America/New_York":
+            dst = _nth_weekday(day.year, 3, 6, 2) <= day < _nth_weekday(day.year, 11, 6, 1)
+            return timezone(timedelta(hours=-4 if dst else -5), name)
+        if name == "Europe/Frankfurt":
+            dst = _last_weekday(day.year, 3, 6) <= day < _last_weekday(day.year, 10, 6)
+            return timezone(timedelta(hours=2 if dst else 1), name)
+        if name == "Europe/London":
+            dst = _last_weekday(day.year, 3, 6) <= day < _last_weekday(day.year, 10, 6)
+            return timezone(timedelta(hours=1 if dst else 0), name)
+        raise
+
+
+def valid_timezone(name: str, day: date) -> bool:
+    try:
+        zone_for_date(name, day)
+        return True
+    except ZoneInfoNotFoundError:
+        return False
+
+
+def iso_date(value: str) -> str:
+    return date.fromisoformat(value).isoformat()
+
+
+def sorted_unique_dates(values: Iterable[str]) -> list[str]:
+    return sorted({iso_date(value) for value in values})
+
+
+def align_date(event_date: str, observation_dates: Iterable[str], mode: str = "next") -> tuple[str | None, int | None]:
+    target = iso_date(event_date)
+    dates = sorted_unique_dates(observation_dates)
+    if mode not in {"same", "next", "next_strict", "previous"}:
+        raise ValueError("alignment must be same, next, next_strict, or previous")
+    if mode == "same":
+        return (target, dates.index(target)) if target in dates else (None, None)
+    if mode == "next":
+        for index, observed in enumerate(dates):
+            if observed >= target:
+                return observed, index
+        return None, None
+    if mode == "next_strict":
+        for index, observed in enumerate(dates):
+            if observed > target:
+                return observed, index
+        return None, None
+    for reverse_index, observed in enumerate(reversed(dates)):
+        if observed <= target:
+            index = len(dates) - reverse_index - 1
+            return observed, index
+    return None, None
+
+
+def window_indices(anchor: int, size: int, offsets: Iterable[int]) -> dict[int, int | None]:
+    return {offset: anchor + offset if 0 <= anchor + offset < size else None for offset in offsets}
+
+
+def market_alignment_for_event(event: dict[str, Any], target_region: str | None) -> str:
+    """Choose same-date eligibility from event time versus target market close."""
+    event_region = str(event.get("region") or "").upper()
+    target = str(target_region or "").upper()
+    if target in {"", "GLOBAL"}:
+        return "next"
+    event_time = event.get("event_time_local")
+    event_timezone = event.get("event_timezone")
+    if event_time and event_timezone:
+        try:
+            parsed_time = time.fromisoformat(str(event_time))
+            if parsed_time.tzinfo is not None:
+                raise ValueError("event_time_local must not contain a timezone offset")
+            event_day = date.fromisoformat(str(event["event_date"]))
+            event_instant = datetime.combine(event_day, parsed_time, zone_for_date(str(event_timezone), event_day)).astimezone(timezone.utc)
+            target_zone, target_close = MARKET_CLOSES[target]
+            target_local_date = event_instant.astimezone(zone_for_date(target_zone, event_day)).date()
+            target_close_zone = zone_for_date(target_zone, target_local_date)
+            close_instant = datetime.combine(target_local_date, target_close, target_close_zone).astimezone(timezone.utc)
+            return "next" if event_instant <= close_instant else "next_strict"
+        except (KeyError, ValueError, ZoneInfoNotFoundError):
+            pass
+    if target == event_region:
+        return "next"
+    if event_region not in MARKET_CLOSES or target not in MARKET_CLOSES:
+        return "next_strict"
+    return "next" if SESSION_ORDER[event_region] < SESSION_ORDER[target] else "next_strict"
+
+
+def market_alignment_for_series(event: dict[str, Any], series: dict[str, Any]) -> tuple[str, str, str]:
+    """Return alignment mode, basis, and target-local date for a series."""
+    event_time = event.get("event_time_local")
+    event_timezone = event.get("event_timezone")
+    observation_time = series.get("observation_time")
+    observation_timezone = series.get("observation_timezone")
+    if event_time and event_timezone:
+        try:
+            event_day = date.fromisoformat(str(event["event_date"]))
+            parsed_event_time = time.fromisoformat(str(event_time))
+            event_instant = datetime.combine(
+                event_day, parsed_event_time, zone_for_date(str(event_timezone), event_day)
+            ).astimezone(timezone.utc)
+            if observation_time and observation_timezone:
+                observation_zone = zone_for_date(str(observation_timezone), event_instant.date())
+                local_event = event_instant.astimezone(observation_zone)
+                local_date = local_event.date()
+                observation_instant = datetime.combine(
+                    local_date, time.fromisoformat(str(observation_time)), observation_zone
+                ).astimezone(timezone.utc)
+                mode = "next" if event_instant < observation_instant else "next_strict"
+                return mode, "source_observation_time", local_date.isoformat()
+
+            market_timezone = series.get("market_timezone")
+            if market_timezone:
+                market_zone = zone_for_date(str(market_timezone), event_instant.date())
+                local_event = event_instant.astimezone(market_zone)
+                local_date = local_event.date()
+                close = TIMEZONE_CLOSES.get(str(market_timezone))
+                if close:
+                    close_instant = datetime.combine(local_date, close, market_zone).astimezone(timezone.utc)
+                    mode = "next" if event_instant <= close_instant else "next_strict"
+                    return mode, "market_close_proxy", local_date.isoformat()
+        except (KeyError, ValueError, ZoneInfoNotFoundError):
+            pass
+
+        target_region = str(series.get("region") or "").upper()
+        if target_region in MARKET_CLOSES:
+            try:
+                market_timezone, close = MARKET_CLOSES[target_region]
+                market_zone = zone_for_date(market_timezone, event_instant.date())
+                local_event = event_instant.astimezone(market_zone)
+                local_date = local_event.date()
+                close_instant = datetime.combine(local_date, close, market_zone).astimezone(timezone.utc)
+                mode = "next" if event_instant <= close_instant else "next_strict"
+                return mode, "region_market_close_proxy", local_date.isoformat()
+            except (ValueError, ZoneInfoNotFoundError):
+                pass
+
+    alignment = market_alignment_for_event(event, series.get("region"))
+    return alignment, "region_calendar_proxy", str(event["event_date"])

package/skills/market-event-impact/scripts/event_resolver.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Resolve free-form market events into a verified, generic event contract."""
+
+from __future__ import annotations
+
+import re
+import hashlib
+from datetime import date, time as dt_time
+from typing import Any
+from urllib.parse import urlparse
+
+from calendars import valid_timezone
+
+
+EVENT_TYPES = {
+    "monetary_policy",
+    "inflation",
+    "employment",
+    "growth",
+    "financial_stress",
+    "sovereign_credit",
+    "geopolitics",
+    "commodity_supply",
+    "corporate_earnings",
+    "fiscal_policy",
+    "trade_policy",
+    "regulation",
+    "market_shock",
+    "other",
+}
+EVENT_STRUCTURES = {"point_event", "scheduled_event", "developing_event"}
+
+GENERIC_QUERY_TERMS = {"decision", "meeting", "event", "release", "announcement", "analysis", "update", "발표", "회의", "사건", "분석", "시장"}
+KNOWN_ACRONYMS = {"svb", "fomc", "ecb", "boj", "bok", "cpi", "ppi", "hicp", "nfp", "gdp", "pmi", "opec", "s&p", "vix", "kre"}
+
+TYPE_KEYWORDS = (
+    ("financial_stress", ("svb", "bank run", "bank failure", "banking crisis", "은행위기", "은행 파산", "예금유출", "금융불안")),
+    ("sovereign_credit", ("downgrade", "default", "credit rating", "신용등급", "국가부도", "디폴트")),
+    ("geopolitics", ("war", "invasion", "missile", "conflict", "전쟁", "침공", "군사충돌", "지정학")),
+    ("commodity_supply", ("opec", "production cut", "supply disruption", "감산", "공급차질")),
+    ("trade_policy", ("tariff", "trade war", "관세", "무역분쟁")),
+    ("corporate_earnings", ("earnings", "guidance", "실적", "가이던스")),
+    ("monetary_policy", ("fomc", "ecb", "boj", "bok", "금통위", "기준금리", "금리 결정")),
+    ("inflation", ("cpi", "ppi", "hicp", "inflation", "물가")),
+    ("employment", ("nfp", "payroll", "unemployment", "고용", "실업률")),
+    ("growth", ("gdp", "pmi", "growth", "성장률")),
+    ("fiscal_policy", ("budget", "stimulus", "fiscal", "예산", "재정", "부양책")),
+    ("regulation", ("regulation", "antitrust", "ban", "규제", "금지")),
+    ("market_shock", ("flash crash", "selloff", "short squeeze", "폭락", "급등", "쇼트스퀴즈")),
+)
+
+REGION_ALIASES = {
+    "KOREA": "KR", "SOUTH KOREA": "KR", "한국": "KR",
+    "UNITED STATES": "US", "USA": "US", "미국": "US",
+    "EURO AREA": "EU", "EUROZONE": "EU", "유로존": "EU",
+    "JAPAN": "JP", "일본": "JP", "CHINA": "CN", "중국": "CN",
+    "UNITED KINGDOM": "UK", "영국": "UK", "GLOBAL": "GLOBAL", "글로벌": "GLOBAL",
+}
+
+
+class EventResolutionError(ValueError):
+    pass
+
+
+def normalize_token(value: Any) -> str:
+    return " ".join(re.sub(r"[^\w]+", " ", str(value or "").casefold(), flags=re.UNICODE).split())
+
+
+def stable_event_id(name: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", normalize_token(name)).strip("-")
+    if slug:
+        return slug[:80].rstrip("-")
+    digest = hashlib.sha256(normalize_token(name).encode("utf-8")).hexdigest()[:16]
+    return f"event-{digest}"
+
+
+def infer_event_type(query: str) -> tuple[str, list[str]]:
+    normalized = normalize_token(query)
+    matches = [event_type for event_type, words in TYPE_KEYWORDS if any(normalize_token(word) in normalized for word in words)]
+    unique = list(dict.fromkeys(matches))
+    return (unique[0] if unique else "other", unique)
+
+
+def _source(value: Any) -> dict[str, str]:
+    if not isinstance(value, dict):
+        raise EventResolutionError("event needs source.name and source.url")
+    name = str(value.get("name") or "").strip()
+    url = str(value.get("url") or "").strip()
+    parsed = urlparse(url)
+    if not name or parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise EventResolutionError("event needs a valid source.name and http(s) source.url")
+    return {"name": name, "url": url}
+
+
+def normalize_region(value: Any) -> str:
+    raw = str(value or "").strip().upper()
+    resolved = REGION_ALIASES.get(raw, raw)
+    if not resolved or not re.fullmatch(r"[A-Z]{2,6}", resolved):
+        raise EventResolutionError("event region must be a 2-6 letter market code such as US, KR, EU, JP, or GLOBAL")
+    return resolved
+
+
+def normalize_event(item: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(item, dict):
+        raise EventResolutionError("event must be an object")
+    name = str(item.get("event_name") or item.get("event_family") or "").strip()
+    if not name:
+        raise EventResolutionError("event_name is required")
+    event_id = str(item.get("event_id") or "").strip().casefold() or stable_event_id(name)
+    if not re.fullmatch(r"[a-z0-9][a-z0-9._-]{0,95}", event_id):
+        raise EventResolutionError("event_id must use 1-96 lowercase letters, numbers, dots, underscores, or hyphens")
+    try:
+        event_date = date.fromisoformat(str(item.get("event_date"))).isoformat()
+    except ValueError as exc:
+        raise EventResolutionError("event_date must be YYYY-MM-DD") from exc
+    explicit_type = str(item.get("event_type") or "").strip().casefold()
+    inferred_type, matches = infer_event_type(" ".join([name, str(item.get("event_family") or ""), " ".join(map(str, item.get("aliases") or []))]))
+    event_type = explicit_type or inferred_type
+    if event_type not in EVENT_TYPES:
+        raise EventResolutionError(f"unsupported event_type: {event_type}")
+    if not explicit_type and len(matches) > 1:
+        raise EventResolutionError("event_type is ambiguous; provide an explicit event_type")
+    aliases = item.get("aliases") or []
+    if not isinstance(aliases, list) or not all(isinstance(alias, str) and alias.strip() for alias in aliases):
+        raise EventResolutionError("event aliases must be non-empty strings")
+    event_time = item.get("event_time_local")
+    event_timezone = item.get("event_timezone")
+    if bool(event_time) != bool(event_timezone):
+        raise EventResolutionError("event_time_local and event_timezone must be provided together")
+    if event_time:
+        try:
+            parsed_time = dt_time.fromisoformat(str(event_time))
+            if parsed_time.tzinfo is not None or not valid_timezone(str(event_timezone), date.fromisoformat(event_date)):
+                raise ValueError
+        except ValueError as exc:
+            raise EventResolutionError("event time must be local HH:MM with a valid IANA timezone") from exc
+    family = str(item.get("event_family") or "").strip().upper().replace(" ", "_") or None
+    raw_sequence = item.get("event_sequence") or []
+    if not isinstance(raw_sequence, list) or any(not isinstance(step, dict) for step in raw_sequence):
+        raise EventResolutionError("event_sequence must be an object array")
+    if len(raw_sequence) > 20:
+        raise EventResolutionError("event_sequence supports at most 20 timeline steps")
+    sequence = []
+    sequence_keys = set()
+    previous_date = None
+    for index, step in enumerate(raw_sequence):
+        try:
+            step_date = date.fromisoformat(str(step.get("date"))).isoformat()
+        except ValueError as exc:
+            raise EventResolutionError(f"event_sequence[{index}].date must be YYYY-MM-DD") from exc
+        step_time = step.get("time_local")
+        step_timezone = step.get("timezone")
+        if bool(step_time) != bool(step_timezone):
+            raise EventResolutionError(f"event_sequence[{index}].time_local and timezone must be provided together")
+        if step_time:
+            try:
+                parsed_step_time = dt_time.fromisoformat(str(step_time))
+                if parsed_step_time.tzinfo is not None or not valid_timezone(str(step_timezone), date.fromisoformat(step_date)):
+                    raise ValueError
+                step_time = parsed_step_time.isoformat(timespec="minutes" if parsed_step_time.second == 0 else "seconds")
+            except ValueError as exc:
+                raise EventResolutionError(f"event_sequence[{index}] needs a local time and valid IANA timezone") from exc
+        step_name = str(step.get("event") or "").strip()
+        if not step_name:
+            raise EventResolutionError(f"event_sequence[{index}].event is required")
+        stage = str(step.get("stage") or "milestone").strip().casefold()
+        if not re.fullmatch(r"[a-z][a-z0-9_-]{0,31}", stage):
+            raise EventResolutionError(f"event_sequence[{index}].stage must be a short identifier")
+        source = _source(step.get("source"))
+        if previous_date and step_date < previous_date:
+            raise EventResolutionError("event_sequence must be in chronological date order")
+        previous_date = step_date
+        key = (step_date, str(step_time or ""), step_name.casefold())
+        if key in sequence_keys:
+            raise EventResolutionError("event_sequence contains duplicate milestones")
+        sequence_keys.add(key)
+        sequence.append({
+            "date": step_date,
+            "time_local": step_time,
+            "timezone": str(step_timezone) if step_timezone else None,
+            "stage": stage,
+            "event": step_name,
+            "source": source,
+        })
+    raw_structure = str(item.get("event_structure") or "").strip().casefold()
+    if raw_structure:
+        if raw_structure not in EVENT_STRUCTURES:
+            raise EventResolutionError(f"event_structure must be one of {sorted(EVENT_STRUCTURES)}")
+        event_structure = raw_structure
+        structure_inferred = False
+    elif len(sequence) > 1:
+        event_structure = "developing_event"
+        structure_inferred = True
+    elif item.get("adapter") or family:
+        event_structure = "scheduled_event"
+        structure_inferred = True
+    else:
+        event_structure = "point_event"
+        structure_inferred = True
+    if event_structure == "developing_event":
+        if len(sequence) < 2:
+            raise EventResolutionError("developing_event needs at least two verified event_sequence milestones")
+        if not any(step["date"] == event_date for step in sequence):
+            raise EventResolutionError("developing_event sequence must include the primary event_date")
+    return {
+        **item,
+        "event_id": event_id,
+        "event_name": name,
+        "event_family": family,
+        "event_type": event_type,
+        "event_date": event_date,
+        "event_structure": event_structure,
+        "event_structure_inferred": structure_inferred,
+        "event_timestamp_quality": "exact_timestamp" if event_time else "date_only",
+        "event_sequence": sequence,
+        "region": normalize_region(item.get("region")),
+        "aliases": list(dict.fromkeys(alias.strip() for alias in aliases)),
+        "source": _source(item.get("source")),
+    }
+
+
+def resolve_from_events(query: str, events: list[dict[str, Any]]) -> dict[str, Any]:
+    needle = normalize_token(query)
+    if not needle:
+        raise EventResolutionError("event query must be a non-empty string")
+    scored: list[tuple[int, dict[str, Any]]] = []
+    for raw in events:
+        item = normalize_event(raw)
+        candidates = [item["event_name"], item["event_id"], item.get("event_family") or "", *item["aliases"]]
+        normalized = [normalize_token(value) for value in candidates if value]
+        exact = any(needle == value for value in normalized)
+        contains = any(needle in value or value in needle for value in normalized)
+        needle_tokens = set(needle.split())
+        meaningful_tokens = needle_tokens - GENERIC_QUERY_TERMS
+        token_overlap = max((len(meaningful_tokens & (set(value.split()) - GENERIC_QUERY_TERMS)) for value in normalized), default=0)
+        acronym_match = bool(meaningful_tokens & KNOWN_ACRONYMS & set(" ".join(normalized).split()))
+        safe_contains = contains and not (len(needle_tokens) == 1 and needle in GENERIC_QUERY_TERMS)
+        score = 100 if exact else (50 if safe_contains else (10 if token_overlap >= 2 or acronym_match else 0))
+        if score:
+            scored.append((score, item))
+    if not scored:
+        inferred, matches = infer_event_type(query)
+        return {
+            "result": "verification_required",
+            "query": query,
+            "inferred_event_type": inferred,
+            "ambiguous_types": matches if len(matches) > 1 else [],
+            "message": "사건 날짜와 직접 출처를 확인한 뒤 events 파일에 추가해야 합니다.",
+        }
+    top_score = max(score for score, _ in scored)
+    top = [item for score, item in scored if score == top_score]
+    identities = {(item["event_id"], item["event_date"]) for item in top}
+    if len(identities) != 1:
+        return {
+            "result": "ambiguous",
+            "query": query,
+            "candidates": top,
+            "message": "동일하게 일치하는 사건이 여러 개입니다. 날짜나 지역을 추가해 주세요.",
+        }
+    return {"result": "ok", "query": query, "event": top[0], "resolution": "verified_event_file"}